From 63f3fbdce4fe065e9f0516143ae54faa724da6e3 Mon Sep 17 00:00:00 2001 From: Derek Hower Date: Tue, 14 Jan 2025 12:53:27 -0800 Subject: [PATCH 1/5] Install pre-commit hook correctly using worktree --- bin/setup | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/bin/setup b/bin/setup index f0a46655b..e8cdc8531 100755 --- a/bin/setup +++ b/bin/setup @@ -204,14 +204,15 @@ else exit 1 fi -if [ ! -f $ROOT/.git/hooks/pre-commit ]; then - cat << HOOK > $ROOT/.git/hooks/pre-commit +GIT_REPO_ROOT=`git rev-parse --path-format=absolute --git-common-dir | tr -d '\n'` +if [ ! -f $GIT_REPO_ROOT/hooks/pre-commit ]; then + cat << HOOK > $GIT_REPO_ROOT/hooks/pre-commit #!/usr/bin/env bash # File generated by pre-commit: https://pre-commit.com # ID: 138fd403232d2ddd5efb44317e38bf03 # start templated -INSTALL_PYTHON=$ROOT/bin/python +INSTALL_PYTHON=$(realpath ./bin/python) ARGS=(hook-impl --config=.pre-commit-config.yaml --hook-type=pre-commit) # end templated @@ -227,5 +228,5 @@ else exit 1 fi HOOK - chmod +x $ROOT/.git/hooks/pre-commit + chmod +x $GIT_REPO_ROOT/hooks/pre-commit fi From ca02be87580198d1cc3d294cd19b826e4f837256 Mon Sep 17 00:00:00 2001 From: Derek Hower Date: Tue, 14 Jan 2025 12:54:16 -0800 Subject: [PATCH 2/5] Add pointers to manual from instruction pages --- .../isa/20240411/isa_20240411.yaml | 4 +++ backends/manual/tasks.rake | 4 +++ .../manual/templates/instruction.adoc.erb | 28 +++++++++++++++++ backends/manual/templates/playbook.yml.erb | 6 ++-- lib/arch_obj_models/manual.rb | 30 +++++++++++++++++++ 5 files changed, 70 insertions(+), 2 deletions(-) diff --git a/arch/manual_version/isa/20240411/isa_20240411.yaml b/arch/manual_version/isa/20240411/isa_20240411.yaml index ca0408516..d8add48fa 100644 --- a/arch/manual_version/isa/20240411/isa_20240411.yaml +++ b/arch/manual_version/isa/20240411/isa_20240411.yaml @@ -19,6 +19,8 @@ volumes: organization: name: SiFive, Inc. url: https://www.sifive.com/ + srcdir: src + main: riscv-unprivileged.adoc chapters: - src/colophon.adoc - src/intro.adoc @@ -175,6 +177,8 @@ volumes: organization: name: SiFive, Inc. url: https://www.sifive.com/ + srcdir: src + main: riscv-privileged.adoc chapters: - src/priv-preface.adoc - src/priv-intro.adoc diff --git a/backends/manual/tasks.rake b/backends/manual/tasks.rake index d7573071e..620240878 100644 --- a/backends/manual/tasks.rake +++ b/backends/manual/tasks.rake @@ -189,11 +189,15 @@ rule %r{#{MANUAL_GEN_DIR}/.*/.*/antora/modules/insts/pages/.*.adoc} => [ ($root / "backends" / "manual" / "templates" / "instruction.adoc.erb").to_s ] do |t| inst_name = File.basename(t.name, ".adoc") + manual_version_name = t.name.sub("/antora/modules/insts/pages/#{inst_name}.adoc", "").split("/").last cfg_arch = cfg_arch_for("_") inst = cfg_arch.instruction(inst_name) raise "Can't find instruction '#{inst_name}'" if inst.nil? + manual_version = cfg_arch.manual_version(manual_version_name) + raise "Can't find manual version '#{manual_version_name}'" if manual_version.nil? + inst_template_path = $root / "backends" / "manual" / "templates" / "instruction.adoc.erb" erb = ERB.new(inst_template_path.read, trim_mode: "-") erb.filename = inst_template_path.to_s diff --git a/backends/manual/templates/instruction.adoc.erb b/backends/manual/templates/instruction.adoc.erb index 1c67a226c..05a38e76f 100644 --- a/backends/manual/templates/instruction.adoc.erb +++ b/backends/manual/templates/instruction.adoc.erb @@ -71,6 +71,34 @@ This instruction must have data-independent timing when extension `Zkt` is enabl <%= inst.description %> +== Ratified text + +<%- +def get_section(block) + if block.context == :section + block + else + raise "?" if block.parent.nil? + + get_section(block.parent) + end +end +-%> + +<%- manual_version.volumes.each do |volume| -%> +<%- adoc_blocks = volume.find_normative_adoc_for(inst) -%> +<%- unless adoc_blocks.empty? -%> +The <%= inst.name %> instruction appears in <%= adoc_blocks.size %> <%= adoc_blocks.size == 1 ? 'paragraph' : 'paragraphs' %> of *<%= volume.title %>*: + +<%- adoc_blocks.each do |block| -%> +<%- section = get_section(block) -%> +.Section <%= section.sectnum %>, <%= section.title %> +<%= block.source %> + +<%- end -%> +<%- end -%> +<%- end -%> + == Access [cols="^,^,^,^,^"] |=== diff --git a/backends/manual/templates/playbook.yml.erb b/backends/manual/templates/playbook.yml.erb index 7c5018fe0..e46a818de 100644 --- a/backends/manual/templates/playbook.yml.erb +++ b/backends/manual/templates/playbook.yml.erb @@ -4,10 +4,12 @@ site: start_page: landing:ROOT:index.adoc content: sources: - - url: <%= $root %> + - url: /local/mnt/workspace/dhower/riscv-unified-db/repo/worktrees/doc-grep + branches: [<%= `git rev-parse --abbrev-ref HEAD | tr -d '\n'` %>] start_path: gen/manual/<%= manual.name %>/top/<%= output_hash %>/antora/landing <%- manual.versions.each do |version| -%> - - url: <%= $root %> + - url: /local/mnt/workspace/dhower/riscv-unified-db/repo/worktrees/doc-grep + branches: [<%= `git rev-parse --abbrev-ref HEAD | tr -d '\n'` %>] start_path: gen/manual/<%= manual.name %>/<%= version.name %>/antora <%- end -%> antora: diff --git a/lib/arch_obj_models/manual.rb b/lib/arch_obj_models/manual.rb index 396cb041d..8a47846d6 100644 --- a/lib/arch_obj_models/manual.rb +++ b/lib/arch_obj_models/manual.rb @@ -68,6 +68,36 @@ def initialize(data, version) @version = version end + def adoc + return @adoc unless @adoc.nil? + + srcdir = "#{@repo_path}/#{@data["srcdir"]}" + @adoc = Asciidoctor.load_file("#{srcdir}/#{@data["main"]}", base_dir: srcdir, sourcemap: true, parse: true, catalog_assets: true, safe: Asciidoctor::SafeMode::UNSAFE) + end + + # @return [Array] Blocks that mention obj + def find_normative_adoc_for(obj) + keyword = + if (obj.is_a?(Instruction)) + obj.name.upcase + else + raise "TODO: #{obj.class.name}" + end + + regex = %r{(^|[ /,])#{keyword}([ ,/.]|$)} + + def is_note?(block) + if block.context == :admonition + true + else + block.parent.nil? ? false : is_note?(block.parent) + end + end + + blocks = adoc.find_by context: :paragraph + blocks.reject { |block| !block.methods.include?(:source) || block.source.index(regex).nil? || is_note?(block) } + end + def chapters return @chapters unless @chapters.nil? From 10e1fd9b5ca0636d49436b1f5a31110d5c30b1f4 Mon Sep 17 00:00:00 2001 From: Derek Hower Date: Tue, 14 Jan 2025 13:29:10 -0800 Subject: [PATCH 3/5] Add note about community-driven documentation --- backends/manual/templates/instruction.adoc.erb | 4 ++++ backends/manual/templates/playbook.yml.erb | 6 ++++-- 2 files changed, 8 insertions(+), 2 deletions(-) diff --git a/backends/manual/templates/instruction.adoc.erb b/backends/manual/templates/instruction.adoc.erb index 05a38e76f..953368ffc 100644 --- a/backends/manual/templates/instruction.adoc.erb +++ b/backends/manual/templates/instruction.adoc.erb @@ -64,6 +64,10 @@ RV64:: == Synopsis +[NOTE] +The following Synopsis is _community-driven_, and has not been ratified by https://riscv.org[RISC-V International]. +You may suggest a correction or improvement by submitting a Pull Request of the https://github.com/riscv-software-src/riscv-unified-db/blob/main/arch/inst/<%= parts = inst.__source.split("/"); parts[parts.rindex("inst")..].join("/") %>[source file]. + <%- if inst.data_independent_timing? -%> [IMPORTANT] This instruction must have data-independent timing when extension `Zkt` is enabled. diff --git a/backends/manual/templates/playbook.yml.erb b/backends/manual/templates/playbook.yml.erb index e46a818de..67d170026 100644 --- a/backends/manual/templates/playbook.yml.erb +++ b/backends/manual/templates/playbook.yml.erb @@ -4,11 +4,13 @@ site: start_page: landing:ROOT:index.adoc content: sources: - - url: /local/mnt/workspace/dhower/riscv-unified-db/repo/worktrees/doc-grep + - url: <%= $root %> + worktrees: true branches: [<%= `git rev-parse --abbrev-ref HEAD | tr -d '\n'` %>] start_path: gen/manual/<%= manual.name %>/top/<%= output_hash %>/antora/landing <%- manual.versions.each do |version| -%> - - url: /local/mnt/workspace/dhower/riscv-unified-db/repo/worktrees/doc-grep + - url: <%= $root %> + worktrees: true branches: [<%= `git rev-parse --abbrev-ref HEAD | tr -d '\n'` %>] start_path: gen/manual/<%= manual.name %>/<%= version.name %>/antora <%- end -%> From 8fc9acbb22ea617c3eae9cd41d3e64a275852be7 Mon Sep 17 00:00:00 2001 From: Derek Hower Date: Tue, 14 Jan 2025 14:20:47 -0800 Subject: [PATCH 4/5] Fix nit --- backends/manual/templates/instruction.adoc.erb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/backends/manual/templates/instruction.adoc.erb b/backends/manual/templates/instruction.adoc.erb index 953368ffc..86d25eeb1 100644 --- a/backends/manual/templates/instruction.adoc.erb +++ b/backends/manual/templates/instruction.adoc.erb @@ -65,7 +65,7 @@ RV64:: == Synopsis [NOTE] -The following Synopsis is _community-driven_, and has not been ratified by https://riscv.org[RISC-V International]. +The following synopsis is _community-driven_, and has not been ratified by https://riscv.org[RISC-V International]. You may suggest a correction or improvement by submitting a Pull Request of the https://github.com/riscv-software-src/riscv-unified-db/blob/main/arch/inst/<%= parts = inst.__source.split("/"); parts[parts.rindex("inst")..].join("/") %>[source file]. <%- if inst.data_independent_timing? -%> From 4013edcb300eae0a4ca8160c0fdc8125dc9911ce Mon Sep 17 00:00:00 2001 From: Derek Hower Date: Wed, 15 Jan 2025 08:56:33 -0800 Subject: [PATCH 5/5] manual antora generator initializes a git repo --- backends/manual/tasks.rake | 17 +++++++++++++++++ backends/manual/templates/instruction.adoc.erb | 8 +++++--- backends/manual/templates/playbook.yml.erb | 10 ++-------- 3 files changed, 24 insertions(+), 11 deletions(-) diff --git a/backends/manual/tasks.rake b/backends/manual/tasks.rake index 620240878..a4ec4200f 100644 --- a/backends/manual/tasks.rake +++ b/backends/manual/tasks.rake @@ -299,6 +299,18 @@ rule %r{#{MANUAL_GEN_DIR}/.*/top/.*/antora/landing/antora.yml} => [ ANTORA end +rule %r{#{MANUAL_GEN_DIR}/.*/\.git} => proc { |tname| + [File.join(File.dirname(tname), "antora.yml")] +} do |t| + Dir.chdir(File.dirname(t.name)) do + sh "git init" + sh "git config --local commit.gpgsign false" + sh "git add antora.yml" + sh "git commit -m \"Antora needs one commit\"" + end +end + + rule %r{#{MANUAL_GEN_DIR}/.*/top/.*/antora/landing/modules/ROOT/pages/index.adoc} => proc { |tname| parts = tname.sub("#{MANUAL_GEN_DIR}/", "").split("/") manual_name = parts[0] @@ -433,6 +445,7 @@ namespace :gen do Rake::Task[antora_path / "modules" / "ROOT" / "pages" / "index.adoc"].invoke Rake::Task[antora_path / "antora.yml"].invoke Rake::Task[antora_path / "nav.adoc"].invoke + Rake::Task[antora_path / ".git"].invoke version_obj.csrs.each do |csr| Rake::Task[antora_path / "modules" / "csrs" / "pages" / "#{csr.name}.adoc"].invoke @@ -452,6 +465,10 @@ namespace :gen do landing_antora_path = MANUAL_GEN_DIR / ENV["MANUAL_NAME"] / "top" / output_hash / "antora" / "landing" / "antora.yml" Rake::Task[landing_antora_path].invoke + # turn the directory into a git repo, which Antora requires + landing_git_path = MANUAL_GEN_DIR / ENV["MANUAL_NAME"] / "top" / output_hash / "antora" / "landing" / ".git" + Rake::Task[landing_git_path].invoke + playbook_path = MANUAL_GEN_DIR / ENV["MANUAL_NAME"] / "top" / output_hash / "antora" / "playbook" / "playbook.yml" Rake::Task[playbook_path].invoke diff --git a/backends/manual/templates/instruction.adoc.erb b/backends/manual/templates/instruction.adoc.erb index 86d25eeb1..778f6e4e3 100644 --- a/backends/manual/templates/instruction.adoc.erb +++ b/backends/manual/templates/instruction.adoc.erb @@ -66,7 +66,7 @@ RV64:: [NOTE] The following synopsis is _community-driven_, and has not been ratified by https://riscv.org[RISC-V International]. -You may suggest a correction or improvement by submitting a Pull Request of the https://github.com/riscv-software-src/riscv-unified-db/blob/main/arch/inst/<%= parts = inst.__source.split("/"); parts[parts.rindex("inst")..].join("/") %>[source file]. +You may suggest a correction or improvement by submitting a Pull Request of the https://github.com/riscv-software-src/riscv-unified-db/blob/main/arch/<%= parts = inst.__source.split("/"); parts[parts.rindex("inst")..].join("/") %>[source file]. <%- if inst.data_independent_timing? -%> [IMPORTANT] @@ -96,8 +96,10 @@ The <%= inst.name %> instruction appears in <%= adoc_blocks.size %> <%= adoc_blo <%- adoc_blocks.each do |block| -%> <%- section = get_section(block) -%> -.Section <%= section.sectnum %>, <%= section.title %> -<%= block.source %> +.Section <%= section.sectnum %> <%= section.title %> +**** +<%= block.source.gsub(%r{(^|[ /,])(#{inst.name.upcase})([ ,/.]|$)}, "\\1*\\2*\\3") %> +**** <%- end -%> <%- end -%> diff --git a/backends/manual/templates/playbook.yml.erb b/backends/manual/templates/playbook.yml.erb index 67d170026..0715c3b21 100644 --- a/backends/manual/templates/playbook.yml.erb +++ b/backends/manual/templates/playbook.yml.erb @@ -4,15 +4,9 @@ site: start_page: landing:ROOT:index.adoc content: sources: - - url: <%= $root %> - worktrees: true - branches: [<%= `git rev-parse --abbrev-ref HEAD | tr -d '\n'` %>] - start_path: gen/manual/<%= manual.name %>/top/<%= output_hash %>/antora/landing + - url: <%= $root %>/gen/manual/<%= manual.name %>/top/<%= output_hash %>/antora/landing <%- manual.versions.each do |version| -%> - - url: <%= $root %> - worktrees: true - branches: [<%= `git rev-parse --abbrev-ref HEAD | tr -d '\n'` %>] - start_path: gen/manual/<%= manual.name %>/<%= version.name %>/antora + - url: <%= $root %>/gen/manual/<%= manual.name %>/<%= version.name %>/antora <%- end -%> antora: extensions: