Instruction indexes#3178
Conversation
|
Normative Rule Changes DetectedThis PR modifies normatively tagged text. Please review the changes below to ensure they are intentional. View Detected ChangesNormative Tag Change Reportriscv-spec SpecificationWhat happens next:
How to update reference files (if needed): make update-ref
git add ref/*.json
git commit -m "Update normative tag reference files"
This comment was automatically generated by the normative tag check workflow. |
|
Bill Traynor (@wmat) Thank you. I am playing around with an alternate scheme to generate these from UDB as part of the spec build process, rather than committing the compiled result. It might not pan out, in which case this route is OK. Let's sit on this for now. |
|
|
Sounds good. Note that I have a PR to UDB as well that splits the single adoc file. In the meantime, I'll clean up the check failures. |
|
Also, the script I've pushed to UDB can be easily automated. I didn't immediately do it as I wanted to ensure the ISA docs were good. |
|
Yeah, whichever approach we take, we'll want to automate it. Give me some time to keep pushing on my scheme and then we can decide. |
59ebeab to
5a2ab2a
Compare
|
1 similar comment
|
Signed-off-by: Bill Traynor wmat@riscv.org Signed-off-by: wmat <wmat@riscv.org>
Adds rv32 and rv64 instruction appendixes to Unpriv & Priv. Signed-off-by: Bill Traynor wmat@riscv.org Signed-off-by: wmat <wmat@riscv.org>
Regenerated with gen:sync_isa_manual_appendixes from riscv-unified-db split-all-instructions branch. Key changes: - Anchors are now base-qualified: [#udb:doc:inst:add] becomes [#udb:doc:inst:rv32:add] or [#udb:doc:inst:rv64:add] so that instructions present in both appendixes have unique IDs. - The :wavedrom: header attribute (machine-local absolute path) is stripped from all four files. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> Signed-off-by: wmat <wmat@riscv.org>
Fixes "macro ext:Zdinx[] does not accept arguments" build errors. Antora-style extension xrefs (xref:exts:D.adoc#...[D]) are now converted to the ISA manual's native ext:D[] inline macro form. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> Signed-off-by: wmat <wmat@riscv.org>
Fixes appendixes being rendered as regular chapters. Each split file now opens with [appendix] followed by == Title as required by AsciiDoc. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> Signed-off-by: wmat <wmat@riscv.org>
Instruction headings are now === (subordinate to the == appendix title) with all deeper levels incremented accordingly. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> Signed-off-by: wmat <wmat@riscv.org>
Each instruction entry now has a [#insn:name] alias anchor ahead of the [#udb:doc:inst:rv32:name] anchor, enabling insnlink: macros in the ISA manual body text to hyperlink directly to the appendix entry. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> Signed-off-by: wmat <wmat@riscv.org>
Replace insn:name[] with insnlink:name[] for all 1351 instruction names that have a corresponding [#insn:name] anchor in the instruction appendixes. This makes every such reference in the body text a live hyperlink to the instruction's appendix entry, with no change to rendered formatting (both macros produce the same code-font display). 2451 occurrences changed across 67 files. References to pseudo- instructions (li, mv, ret), assembler shorthands (lr, amo), wildcard patterns (*w, .uw), and other names with no appendix entry are left as insn: and produce no link. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> Signed-off-by: wmat <wmat@riscv.org>
Replace stacked block anchors with inline passthrough anchors so that href="#insn:add" links from insnlink: macros navigate correctly in the built HTML. Both id="udb:doc:inst:rv32:add" and id="insn:add" are now present in the output. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> Signed-off-by: wmat <wmat@riscv.org>
Each instruction heading now uses a simple [[insn:name]] block anchor. The udb:doc:inst: anchors and passthrough workaround are removed. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> Signed-off-by: wmat <wmat@riscv.org>
Instructions valid in both RV32 and RV64 now carry [[insn:name]] only in the rv64 file. The rv32 files drop the anchor for those instructions to avoid "id assigned to section already in use" Asciidoctor warnings. insnlink: cross-references still resolve correctly via the rv64 entry. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> Signed-off-by: wmat <wmat@riscv.org>
The three body-text anchors ([[insn:fence]], [[insn:fence.i]], [[insn:c.ebreak]]) duplicated the anchors now defined in the generated appendix files. Since the appendix is the canonical instruction reference, remove the body-text anchors; insnlink: cross-references resolve via the appendix entry. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> Signed-off-by: wmat <wmat@riscv.org>
Re-synced from riscv-unified-db after fixing split_instructions.rb to strip trailing blank lines, satisfying the pre-commit "fix end of files" check. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> Signed-off-by: wmat <wmat@riscv.org>
5a2ab2a to
c1dc6c2
Compare
|
Andrew Waterman (@aswaterman) fixed up the DCO Check failure so once the Build ISA completes the artifacts will be available. Note that the instructions in the body of the books will link to their single page description in their respective books. This means that something like ADD will reside in both Unpriv and Priv indexes. This is OK though, as those indexes are generated from UDB's single all_instructions.adoc file, not manually added twice. Also, with the additions of theses indexes the ISA build step takes 1-2 an hours, so that will need considerable improvement. |
|
Bill Traynor (@wmat) While I continue working on the generation aspect, can you research where all the runtime is going and start looking into solutions to improve it? |
|
Will do. |
Andrew Waterman (@aswaterman) here is the instruction indexes for unpriv_rv32, unpriv_rv64, priv_rv32, and priv_rv64. The 4 new adoc files were created from all_instructions.adoc in UDB. I have a PR to add the script that creates them to riscv-unified-db. Currently these are manually created, however, it could be automated and synced to riscv-isa-manual with a GH action.
Please review the indexes in the PDFs and HTML before merging.