Merge pull request #309 from riscv-software-src/partials

Add partial templates

backends/common_templates/adoc/README.adoc

@@ -0,0 +1 @@
+This directory contains partial templates (e.g., a CSR description) to be used by document generators.

backends/common_templates/adoc/csr.adoc.erb

@@ -0,0 +1,123 @@
+<%= anchor_for_csr(csr.name) %>
+= <%= csr.name %>
+
+*<%= csr.long_name %>*
+
+<%= csr.description %>
+
+== Attributes
+[%autowidth]
+|===
+h| CSR Address    | <%= "0x#{csr.address.to_s(16)}" %>
+<%- if csr.priv_mode == 'VS' -%>
+h| Virtual CSR Address    | <%= "0x#{csr.virtual_address.to_s(16)}" %>
+<%- end -%>
+<%- if csr.dynamic_length?(arch_def) -%>
+h| Length         | <%= csr.length_pretty(arch_def) %>
+<%- else -%>
+h| Length         | <%= csr.length_pretty(arch_def) %>-bit
+<%- end -%>
+h| Privilege Mode | <%= csr.priv_mode %>
+|===
+
+== Format
+<%- unless csr.dynamic_length?(arch_def) || csr.fields.any? { |f| f.dynamic_location?(arch_def) } -%>
+<%# CSR has a known static length, so there is only one format to display -%>
+.<%= csr.name %> format
+[wavedrom, ,svg,subs='attributes',width="100%"]
+....
+<%= JSON.dump csr.wavedrom_desc(arch_def, 64) %>
+....
+<%- else -%>
+<%# CSR has a dynamic length, or a field has a dynamic location,
+    so there is more than one format to display -%>
+This CSR format changes dynamically.
+
+.<%= csr.name %> Format when <%= csr.length_cond32 %>
+[wavedrom, ,svg,subs='attributes',width="100%"]
+....
+<%= JSON.dump csr.wavedrom_desc(arch_def, 32) %>
+....
+
+.<%= csr.name %> Format when <%= csr.length_cond64 %>
+[wavedrom, ,svg,subs='attributes',width="100%"]
+....
+<%= JSON.dump csr.wavedrom_desc(arch_def, 64) %>
+....
+<%- end -%>
+
+== Field Summary
+
+[%autowidth,float="center",align="center",cols="^,<,<,<",options="header",role="stretch"]
+|===
+|Name | Location | Type | Reset Value
+
+<%- csr.fields.each do |field| -%>
+| xref:<%=csr.name%>-<%=field.name%>-def[`<%= field.name %>`]
+| <%= field.location_pretty(arch_def) %>
+| <%= field.type_pretty(arch_def.symtab) %>
+| <%= field.reset_value_pretty(arch_def) %>
+
+<%- end -%>
+|===
+
+
+== Fields
+
+<%- if csr.fields.empty? -%>
+This CSR has no fields. However, it must still exist (not cause an `Illegal Instruction` trap) and always return zero on a read.
+<%- else -%>
+
+<%- csr.fields.each do |field| -%>
+[[<%=csr.name%>-<%=field.name%>-def]]
+===== `<%= field.name %>`
+
+[example]
+****
+Location::
+<%= field.location_pretty(arch_def) %>
+
+Description::
+<%= field.description %>
+
+Type::
+<%= field.type_pretty(arch_def.symtab) %>
+
+Reset value::
+<%= field.reset_value_pretty(arch_def) %>
+
+****
+
+<%- end -%>
+<%- end -%>
+
+<%- if csr.fields.map(&:has_custom_sw_write?).any? -%>
+== Software write
+
+This CSR may store a value that is different from what software attempts to write.
+
+When a software write occurs (_e.g._, through `csrrw`), the following determines the
+written value:
+
+[idl]
+----
+<%- csr.fields.each do |field| -%>
+<%- if field.has_custom_sw_write? -%>
+<%= field.name %> = <%= field["sw_write(csr_value)"] %>
+<%- else -%>
+<%= field.name %> = csr_value.<%= field.name %>
+<%- end -%>
+<%- end -%>
+----
+<%- end -%>
+
+<%- if csr.has_custom_sw_read? -%>
+== Software read
+
+This CSR may return a value that is different from what is stored in hardware.
+
+[source,idl,subs="specialchars,macros"]
+----
+<%= csr.sw_read_ast(arch_def.symtab).gen_adoc %>
+----
+<%- end -%>

backends/common_templates/adoc/inst.adoc.erb

@@ -0,0 +1,84 @@
+<%= anchor_for_inst(inst.name) %>
+= <%= inst.name %>
+
+Synopsis::
+<%= inst.long_name %>
+
+Mnemonic::
+----
+<%= inst.name %> <%= inst.assembly.gsub('x', 'r') %>
+----
+
+Encoding::
+<%- if inst.multi_encoding? -%>
+[NOTE]
+This instruction has different encodings in RV32 and RV64
+
+RV32::
+[wavedrom, ,svg,subs='attributes',width="100%"]
+....
+<%= JSON.dump inst.wavedrom_desc(32) %>
+....
+
+RV64::
+[wavedrom, ,svg,subs='attributes',width="100%"]
+....
+<%= JSON.dump inst.wavedrom_desc(64) %>
+....
+<%- else -%>
+[wavedrom, ,svg,subs='attributes',width="100%"]
+....
+<%= JSON.dump inst.wavedrom_desc(inst.base.nil? ? 64 : inst.base) %>
+....
+<%- end -%>
+
+Description::
+<%= inst.description %>
+
+
+Decode Variables::
+
+<%- if inst.multi_encoding? ? (inst.decode_variables(32).empty? && inst.decode_variables(64).empty?) : inst.decode_variables(inst.base.nil? ? 64 : inst.base).empty? -%>
+
+<%= inst.name %> has no decode variables.
+
+<%- else -%>
+<%- if inst.multi_encoding? -%>
+RV32::
++
+[source,idl]
+----
+<%- inst.decode_variables(32).each do |d| -%>
+<%= d.sext? ? 'signed ' : '' %>Bits<<%= d.size %>> <%= d.name %> = <%= d.extract %>;
+<%- end -%>
+----
+
+RV64::
++
+[source,idl]
+----
+<%- inst.decode_variables(64).each do |d| -%>
+<%= d.sext? ? 'signed ' : '' %>Bits<<%= d.size %>> <%= d.name %> = <%= d.extract %>;
+<%- end -%>
+----
+<%- else -%>
+[source,idl,subs="specialchars,macros"]
+----
+<%- inst.decode_variables(inst.base.nil? ? 64 : inst.base).each do |d| -%>
+<%= d.sext? ? 'signed ' : '' %>Bits<<%= d.size %>> <%= d.name %> = <%= d.extract %>;
+<%- end -%>
+----
+<%- end # if multi_encoding? -%>
+<%- end # if no decode variables-%>
+
+Operation::
+<%- unless inst.data["operation()"].nil? -%>
+[source,idl,subs="specialchars,macros"]
+----
+<%= inst.operation_ast(arch_def.symtab).gen_adoc %>
+----
+<%- end -%>
+
+Included in::
+
+<%= inst.defined_by.to_asciidoc %>