Skip to content

Commit 0bbd605

Browse files
dhower-qcdhower-qc
authored
Merge pull request #101 from riscv-software-src/manual_appendices
Add extension list to manual generator
2 parents 774286c + eb62e0c commit 0bbd605

File tree

3 files changed

+104
-64
lines changed

3 files changed

+104
-64
lines changed

‎backends/manual/tasks.rake‎

Lines changed: 29 additions & 64 deletions
Original file line numberDiff line numberDiff line change
@@ -30,64 +30,6 @@ directory MANUAL_GEN_DIR / "adoc"
3030
directory MANUAL_GEN_DIR / "antora"
3131
directory MANUAL_GEN_DIR / "html"
3232

33-
# ["inst", "csr", "ext"].each do |type|
34-
# directory MANUAL_GEN_DIR / "antora" / "modules" / "#{type}s" / "pages"
35-
36-
# Dir.glob($root / "arch" / type / "**" / "*.yaml") do |fn|
37-
# file MANUAL_GEN_DIR / "adoc" / "#{File.basename(fn, '.yaml')}.adoc" => [
38-
# "gen:arch",
39-
# (MANUAL_GEN_DIR / "adoc").to_s,
40-
# ($root / "backends" / "manual" / "templates" / "#{type}.adoc.erb").to_s,
41-
# __FILE__
42-
# ] do |t|
43-
# name = File.basename(t.name, ".adoc")
44-
45-
# arch_def_32 = arch_def_for("_32")
46-
# arch_def_64 = arch_def_for("_64")
47-
# erb = case type
48-
# when "inst"
49-
# inst_32 = arch_def_32.instruction(name)
50-
# raise "Could not find inst '#{name}' in RV32" if inst_32.nil?
51-
52-
# inst_64 = arch_def_64.instruction(name)
53-
# raise "Could not find inst '#{name}' in RV64" if inst_64.nil?
54-
55-
# inst = inst_32 || inst_64
56-
57-
# ERB.new(File.read($root / "backends" / "manual" / "templates" / "inst.adoc.erb"), trim_mode: "-")
58-
# when "csr"
59-
# csr_32 = arch_def_32.csr(name)
60-
# raise "Could not find csr '#{name}' in RV32" if csr_32.nil?
61-
62-
# csr_64 = arch_def_64.csr(name)
63-
# raise "Could not find csr '#{name}' in RV32" if csr_64.nil?
64-
65-
# csr = csr_32 || csr_64
66-
67-
# ERB.new(File.read($root / "backends" / "manual" / "templates" / "csr.adoc.erb"), trim_mode: "-")
68-
# when "ext"
69-
# ext = arch_def_64.extension(name)
70-
# raise "Could not find ext '#{name}'" if ext.nil?
71-
72-
# arch_def = arch_def_64
73-
74-
# ERB.new(File.read($root / "backends" / "manual" / "templates" / "ext.adoc.erb"), trim_mode: "-")
75-
# else
76-
# raise "Unhandled type '#{type}'"
77-
# end
78-
79-
# File.write(t.name, erb.result(binding))
80-
# end
81-
82-
# file MANUAL_GEN_DIR / "antora" / "modules" / "#{type}s" / "pages" => [
83-
# (MANUAL_GEN_DIR / "adoc" / "#{File.basename(fn, '.yaml')}.adoc").to_s,
84-
# (MANUAL_GEN_DIR / "antora" / "modules" / "#{type}s" / "pages").to_s
85-
# ] do |t|
86-
# FileUtils.cp t.prerequisites.first, t.name
87-
# end
88-
# end
89-
# end
90-
9133
file MANUAL_GEN_DIR / "antora" / "antora.yml" => (MANUAL_GEN_DIR / "antora").to_s do |t|
9234
File.write t.name, <<~ANTORA
9335
name: riscv_manual
@@ -226,7 +168,7 @@ end
226168
# rule to create instruction appendix page
227169
rule %r{#{MANUAL_GEN_DIR}/.*/.*/antora/modules/insts/pages/.*.adoc} => [
228170
__FILE__,
229-
"gen:arch",
171+
"#{$root}/.stamps/arch-gen-_64.stamp",
230172
($root / "backends" / "manual" / "templates" / "instruction.adoc.erb").to_s
231173
] do |t|
232174
inst_name = File.basename(t.name, ".adoc")
@@ -240,13 +182,13 @@ rule %r{#{MANUAL_GEN_DIR}/.*/.*/antora/modules/insts/pages/.*.adoc} => [
240182
erb.filename = inst_template_path.to_s
241183

242184
FileUtils.mkdir_p File.dirname(t.name)
243-
File.write t.name, AntoraUtils.resolve_links(erb.result(binding))
185+
File.write t.name, AntoraUtils.resolve_links(arch_def.find_replace_links(erb.result(binding)))
244186
end
245187

246188
# rule to create csr appendix page
247189
rule %r{#{MANUAL_GEN_DIR}/.*/.*/antora/modules/csrs/pages/.*.adoc} => [
248190
__FILE__,
249-
"gen:arch",
191+
"#{$root}/.stamps/arch-gen-_64.stamp",
250192
($root / "backends" / "manual" / "templates" / "csr.adoc.erb").to_s
251193
] do |t|
252194
csr_name = File.basename(t.name, ".adoc")
@@ -260,13 +202,33 @@ rule %r{#{MANUAL_GEN_DIR}/.*/.*/antora/modules/csrs/pages/.*.adoc} => [
260202
erb.filename = csr_template_path.to_s
261203

262204
FileUtils.mkdir_p File.dirname(t.name)
263-
File.write t.name, AntoraUtils.resolve_links(erb.result(binding))
205+
File.write t.name, AntoraUtils.resolve_links(arch_def.find_replace_links(erb.result(binding)))
206+
end
207+
208+
# rule to create ext appendix page
209+
rule %r{#{MANUAL_GEN_DIR}/.*/.*/antora/modules/exts/pages/.*.adoc} => [
210+
__FILE__,
211+
"#{$root}/.stamps/arch-gen-_64.stamp",
212+
($root / "backends" / "manual" / "templates" / "ext.adoc.erb").to_s
213+
] do |t|
214+
ext_name = File.basename(t.name, ".adoc")
215+
216+
arch_def = arch_def_for("_64")
217+
ext = arch_def.extension(ext_name)
218+
raise "Can't find extension '#{ext_name}'" if ext.nil?
219+
220+
ext_template_path = $root / "backends" / "manual" / "templates" / "ext.adoc.erb"
221+
erb = ERB.new(ext_template_path.read, trim_mode: "-")
222+
erb.filename = ext_template_path.to_s
223+
224+
FileUtils.mkdir_p File.dirname(t.name)
225+
File.write t.name, AntoraUtils.resolve_links(arch_def.find_replace_links(erb.result(binding)))
264226
end
265227

266228
# rule to create IDL function appendix page
267229
rule %r{#{MANUAL_GEN_DIR}/.*/.*/antora/modules/funcs/pages/funcs.adoc} => [
268230
__FILE__,
269-
"gen:arch",
231+
"#{$root}/.stamps/arch-gen-_64.stamp",
270232
($root / "backends" / "manual" / "templates" / "func.adoc.erb").to_s
271233
] do |t|
272234
arch_def = arch_def_for("_64")
@@ -276,7 +238,7 @@ rule %r{#{MANUAL_GEN_DIR}/.*/.*/antora/modules/funcs/pages/funcs.adoc} => [
276238
erb.filename = funcs_template_path.to_s
277239

278240
FileUtils.mkdir_p File.dirname(t.name)
279-
File.write t.name, AntoraUtils.resolve_links(erb.result(binding))
241+
File.write t.name, AntoraUtils.resolve_links(arch_def.find_replace_links(erb.result(binding)))
280242
end
281243

282244
rule %r{#{MANUAL_GEN_DIR}/.*/top/.*/antora/landing/antora.yml} => [
@@ -429,6 +391,9 @@ namespace :gen do
429391
version.csrs.each do |csr|
430392
Rake::Task[antora_path / "modules" / "csrs" / "pages" / "#{csr.name}.adoc"].invoke
431393
end
394+
version.extensions.each do |ext|
395+
Rake::Task[antora_path / "modules" / "exts" / "pages" / "#{ext.name}.adoc"].invoke
396+
end
432397
end
433398

434399
landing_page_path = MANUAL_GEN_DIR / ENV["MANUAL_NAME"] / "top" / output_hash / "antora" / "landing" / "modules" / "ROOT" / "pages" / "index.adoc"

‎backends/manual/templates/ext.adoc.erb‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
[ext:$<%= ext.name %>-def]
2+
= <%= ext.name %> Extension
3+
<%= ext.long_name %>
4+
5+
== Versions
6+
7+
<%- ext.versions.each do |v| -%>
8+
<%- implemented = arch_def.implemented_extensions.include?(ExtensionVersion.new(ext.name, v["version"])) -%>
9+
<%= v["version"] %>::
10+
State:::
11+
<%= v["state"] %>
12+
<%- if v["state"] == "ratified" -%>
13+
Ratification date:::
14+
<%= v["ratification_date"] %>
15+
<%- end -%>
16+
<%- if v.key?("changes") -%>
17+
Changes:::
18+
<%- v["changes"].each do |change| %>
19+
* <%= change %>
20+
<%- end -%>
21+
<%- end -%>
22+
<%- if v.key?("url") -%>
23+
Ratification document:::
24+
<%= v["url"] %>
25+
<%- end -%>
26+
<%- if v.key?("implies") -%>
27+
Implies:::
28+
<%- implications = v["implies"][0].is_a?(Array) ? v["implies"] : [v["implies"]] -%>
29+
<%- implications.each do |i| -%>
30+
* `<%= i[0] %>` version <%= i[1] %>
31+
<%- end -%>
32+
<%- end -%>
33+
<%- end -%>
34+
35+
== Synopsis
36+
37+
<%= ext.description %>
38+
39+
<%- insts = arch_def.instructions.select { |i| ext.versions.any? { |v| i.defined_by?(ext.name, v["version"]) } } -%>
40+
<%- unless insts.empty? -%>
41+
== Instructions
42+
43+
The following instructions are defined by this extension:
44+
45+
[cols="1,3"]
46+
|===
47+
<%- insts.each do |inst| -%>
48+
| <%= "`#{inst.name}`" %> | *<%= inst.long_name %>*
49+
<%- end -%>
50+
|===
51+
<%- end -%>
52+
53+
<%- unless ext.params.empty? -%>
54+
== Parameters
55+
56+
This extension has the following implementation options:
57+
58+
<%- ext.params.sort_by { |p| p.name }.each do |param| -%>
59+
<%= param.name %>::
60+
+
61+
--
62+
|===
63+
h| Type | <%= param.schema["type"] %>
64+
h| Valid Values | <%= Schema.new(param.schema).to_pretty_s %>
65+
h| Description a| <%= param.desc %>
66+
|===
67+
--
68+
<%- end -%>
69+
70+
<%- end -%>

‎backends/manual/templates/isa_nav.adoc.erb‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,5 +16,10 @@
1616
* xref:csrs:<%= csr.name %>.adoc[<%= csr.name %>]
1717
<%- end -%>
1818

19+
.Alphabetical list of extensions
20+
<%- manual_version.extensions.sort { |a, b| a.name <=> b.name }.each do |ext| -%>
21+
* xref:exts:<%= ext.name %>.adoc[<%= ext.name %>]
22+
<%- end -%>
23+
1924
.Execution functions (IDL)
2025
* xref:funcs:funcs.adoc[Functions]

0 commit comments

Comments
 (0)