Skip to content

Commit c7a9658

Browse files
james-ball-qualcommjames-ball-qualcomm
authored
Merge pull request #309 from riscv-software-src/partials
Add partial templates
2 parents 8721e67 + 0942e39 commit c7a9658

File tree

7 files changed

+226
-218
lines changed

7 files changed

+226
-218
lines changed

‎backends/common_templates/adoc/README.adoc‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
This directory contains partial templates (e.g., a CSR description) to be used by document generators.

‎backends/common_templates/adoc/csr.adoc.erb‎

Lines changed: 123 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,123 @@
1+
<%= anchor_for_csr(csr.name) %>
2+
= <%= csr.name %>
3+
4+
*<%= csr.long_name %>*
5+
6+
<%= csr.description %>
7+
8+
== Attributes
9+
[%autowidth]
10+
|===
11+
h| CSR Address | <%= "0x#{csr.address.to_s(16)}" %>
12+
<%- if csr.priv_mode == 'VS' -%>
13+
h| Virtual CSR Address | <%= "0x#{csr.virtual_address.to_s(16)}" %>
14+
<%- end -%>
15+
<%- if csr.dynamic_length?(arch_def) -%>
16+
h| Length | <%= csr.length_pretty(arch_def) %>
17+
<%- else -%>
18+
h| Length | <%= csr.length_pretty(arch_def) %>-bit
19+
<%- end -%>
20+
h| Privilege Mode | <%= csr.priv_mode %>
21+
|===
22+
23+
== Format
24+
<%- unless csr.dynamic_length?(arch_def) || csr.fields.any? { |f| f.dynamic_location?(arch_def) } -%>
25+
<%# CSR has a known static length, so there is only one format to display -%>
26+
.<%= csr.name %> format
27+
[wavedrom, ,svg,subs='attributes',width="100%"]
28+
....
29+
<%= JSON.dump csr.wavedrom_desc(arch_def, 64) %>
30+
....
31+
<%- else -%>
32+
<%# CSR has a dynamic length, or a field has a dynamic location,
33+
so there is more than one format to display -%>
34+
This CSR format changes dynamically.
35+
36+
.<%= csr.name %> Format when <%= csr.length_cond32 %>
37+
[wavedrom, ,svg,subs='attributes',width="100%"]
38+
....
39+
<%= JSON.dump csr.wavedrom_desc(arch_def, 32) %>
40+
....
41+
42+
.<%= csr.name %> Format when <%= csr.length_cond64 %>
43+
[wavedrom, ,svg,subs='attributes',width="100%"]
44+
....
45+
<%= JSON.dump csr.wavedrom_desc(arch_def, 64) %>
46+
....
47+
<%- end -%>
48+
49+
== Field Summary
50+
51+
[%autowidth,float="center",align="center",cols="^,<,<,<",options="header",role="stretch"]
52+
|===
53+
|Name | Location | Type | Reset Value
54+
55+
<%- csr.fields.each do |field| -%>
56+
| xref:<%=csr.name%>-<%=field.name%>-def[`<%= field.name %>`]
57+
| <%= field.location_pretty(arch_def) %>
58+
| <%= field.type_pretty(arch_def.symtab) %>
59+
| <%= field.reset_value_pretty(arch_def) %>
60+
61+
<%- end -%>
62+
|===
63+
64+
65+
== Fields
66+
67+
<%- if csr.fields.empty? -%>
68+
This CSR has no fields. However, it must still exist (not cause an `Illegal Instruction` trap) and always return zero on a read.
69+
<%- else -%>
70+
71+
<%- csr.fields.each do |field| -%>
72+
[[<%=csr.name%>-<%=field.name%>-def]]
73+
===== `<%= field.name %>`
74+
75+
[example]
76+
****
77+
Location::
78+
<%= field.location_pretty(arch_def) %>
79+
80+
Description::
81+
<%= field.description %>
82+
83+
Type::
84+
<%= field.type_pretty(arch_def.symtab) %>
85+
86+
Reset value::
87+
<%= field.reset_value_pretty(arch_def) %>
88+
89+
****
90+
91+
<%- end -%>
92+
<%- end -%>
93+
94+
<%- if csr.fields.map(&:has_custom_sw_write?).any? -%>
95+
== Software write
96+
97+
This CSR may store a value that is different from what software attempts to write.
98+
99+
When a software write occurs (_e.g._, through `csrrw`), the following determines the
100+
written value:
101+
102+
[idl]
103+
----
104+
<%- csr.fields.each do |field| -%>
105+
<%- if field.has_custom_sw_write? -%>
106+
<%= field.name %> = <%= field["sw_write(csr_value)"] %>
107+
<%- else -%>
108+
<%= field.name %> = csr_value.<%= field.name %>
109+
<%- end -%>
110+
<%- end -%>
111+
----
112+
<%- end -%>
113+
114+
<%- if csr.has_custom_sw_read? -%>
115+
== Software read
116+
117+
This CSR may return a value that is different from what is stored in hardware.
118+
119+
[source,idl,subs="specialchars,macros"]
120+
----
121+
<%= csr.sw_read_ast(arch_def.symtab).gen_adoc %>
122+
----
123+
<%- end -%>

‎backends/common_templates/adoc/inst.adoc.erb‎

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
<%= anchor_for_inst(inst.name) %>
2+
= <%= inst.name %>
3+
4+
Synopsis::
5+
<%= inst.long_name %>
6+
7+
Mnemonic::
8+
----
9+
<%= inst.name %> <%= inst.assembly.gsub('x', 'r') %>
10+
----
11+
12+
Encoding::
13+
<%- if inst.multi_encoding? -%>
14+
[NOTE]
15+
This instruction has different encodings in RV32 and RV64
16+
17+
RV32::
18+
[wavedrom, ,svg,subs='attributes',width="100%"]
19+
....
20+
<%= JSON.dump inst.wavedrom_desc(32) %>
21+
....
22+
23+
RV64::
24+
[wavedrom, ,svg,subs='attributes',width="100%"]
25+
....
26+
<%= JSON.dump inst.wavedrom_desc(64) %>
27+
....
28+
<%- else -%>
29+
[wavedrom, ,svg,subs='attributes',width="100%"]
30+
....
31+
<%= JSON.dump inst.wavedrom_desc(inst.base.nil? ? 64 : inst.base) %>
32+
....
33+
<%- end -%>
34+
35+
Description::
36+
<%= inst.description %>
37+
38+
39+
Decode Variables::
40+
41+
<%- if inst.multi_encoding? ? (inst.decode_variables(32).empty? && inst.decode_variables(64).empty?) : inst.decode_variables(inst.base.nil? ? 64 : inst.base).empty? -%>
42+
43+
<%= inst.name %> has no decode variables.
44+
45+
<%- else -%>
46+
<%- if inst.multi_encoding? -%>
47+
RV32::
48+
+
49+
[source,idl]
50+
----
51+
<%- inst.decode_variables(32).each do |d| -%>
52+
<%= d.sext? ? 'signed ' : '' %>Bits<<%= d.size %>> <%= d.name %> = <%= d.extract %>;
53+
<%- end -%>
54+
----
55+
56+
RV64::
57+
+
58+
[source,idl]
59+
----
60+
<%- inst.decode_variables(64).each do |d| -%>
61+
<%= d.sext? ? 'signed ' : '' %>Bits<<%= d.size %>> <%= d.name %> = <%= d.extract %>;
62+
<%- end -%>
63+
----
64+
<%- else -%>
65+
[source,idl,subs="specialchars,macros"]
66+
----
67+
<%- inst.decode_variables(inst.base.nil? ? 64 : inst.base).each do |d| -%>
68+
<%= d.sext? ? 'signed ' : '' %>Bits<<%= d.size %>> <%= d.name %> = <%= d.extract %>;
69+
<%- end -%>
70+
----
71+
<%- end # if multi_encoding? -%>
72+
<%- end # if no decode variables-%>
73+
74+
Operation::
75+
<%- unless inst.data["operation()"].nil? -%>
76+
[source,idl,subs="specialchars,macros"]
77+
----
78+
<%= inst.operation_ast(arch_def.symtab).gen_adoc %>
79+
----
80+
<%- end -%>
81+
82+
Included in::
83+
84+
<%= inst.defined_by.to_asciidoc %>

0 commit comments

Comments
 (0)