Adding CRD generators#1087
Draft
james-ball-qualcomm wants to merge 34 commits intoriscv:act4from
Draft
Conversation
Contributor
There was a problem hiding this comment.
Pull request overview
Adds new generators and a revamped CRD docs build pipeline to produce implementation-defined behavior tables and parameter appendix includes from normative rules + YAML parameter definitions.
Changes:
- Added a Python generator to output an AsciiDoc table of implementation-defined behaviors from
norm-rules.json. - Replaced hand-written parameter
.adocfiles with YAML parameter definitions and Makefile-driven generation of per-parameter AsciiDoc includes. - Updated CRD documents to include generated parameter appendix content and updated relevant submodules.
Reviewed changes
Copilot reviewed 15 out of 16 changed files in this pull request and generated 6 comments.
Show a summary per file
| File | Description |
|---|---|
| generators/crd/generate_impl_def_table.py | New generator for implementation-defined behavior AsciiDoc tables. |
| external/riscv-unified-db | Bumps submodule revision for unified DB dependency. |
| docs/docs-resources | Bumps docs-resources submodule revision (schemas/tools/themes/fonts). |
| docs/crd/src/rvi20_crd.adoc | Switches parameter includes to generated build outputs. |
| docs/crd/src/mc100_crd.adoc | Switches parameter includes to generated build outputs. |
| docs/crd/src/param_defs/HPM_COUNTER_SZ.adoc | Removes hand-authored parameter include (now generated). |
| docs/crd/src/param_defs/LRSC_RESERVATION_STRATEGY.adoc | Removes hand-authored parameter include (now generated). |
| docs/crd/src/param_defs/MISALIGNED_LDST_HW_SUPPORT.adoc | Removes hand-authored parameter include (now generated). |
| docs/crd/src/param_defs/MISALIGNED_ATOMICITY_GRANULE_SIZE.adoc | Removes hand-authored parameter include (now generated). |
| docs/crd/src/param_defs/TIME_CSR_HW_SUPPORT.adoc | Removes hand-authored parameter include (now generated). |
| docs/crd/src/all_impldefs.adoc | Removes large checked-in impl-defs table (now intended to be generated). |
| docs/crd/param_defs/rv32.yaml | Adds YAML param definition(s) for RV32I-related parameters. |
| docs/crd/param_defs/counters.yaml | Adds YAML param definition(s) for counters/time parameters. |
| docs/crd/param_defs/a-st-ext.yaml | Adds YAML param definition(s) for A extension / atomic-related parameters. |
| docs/crd/Makefile | Adds rules to generate params JSON/HTML and param-appendix include .adoc files; updates build dependencies. |
Contributor
There was a problem hiding this comment.
Pull request overview
Adds tooling and build plumbing to generate CRD documentation artifacts (implementation-defined behavior tables and parameter appendix includes) from structured inputs rather than maintaining large hand-written AsciiDoc fragments.
Changes:
- Added a Python generator to emit an AsciiDoc table of implementation-defined behaviors from
norm-rules.json. - Switched CRD parameter appendix content to be generated from new YAML parameter definition files and updated CRD AsciiDoc includes accordingly.
- Updated the CRD Makefile build to generate
params.json/params.htmland per-parameter include files, and updated submodules.
Reviewed changes
Copilot reviewed 15 out of 16 changed files in this pull request and generated 6 comments.
Show a summary per file
| File | Description |
|---|---|
| generators/crd/generate_impl_def_table.py | New generator that produces AsciiDoc tables of impl-defined behaviors from norm-rules.json. |
| external/riscv-unified-db | Bumps submodule SHA used for normative rule data. |
| docs/docs-resources | Bumps docs resources submodule SHA (schemas/tools/themes). |
| docs/crd/src/rvi20_crd.adoc | Updates parameter appendix includes to point at generated build outputs. |
| docs/crd/src/mc100_crd.adoc | Updates parameter appendix includes to point at generated build outputs. |
| docs/crd/src/param_defs/*.adoc | Removes legacy hand-maintained per-parameter AsciiDoc files (now generated). |
| docs/crd/src/all_impldefs.adoc | Removes large generated impl-defs table artifact from source tree (now generated). |
| docs/crd/param_defs/*.yaml | Adds structured YAML inputs for parameter definitions. |
| docs/crd/Makefile | Introduces targets/pipeline to generate params + include fragments and adds an impl-defs generator target. |
Contributor
There was a problem hiding this comment.
Pull request overview
Adds CRD-related generators and updates the CRD build pipeline to generate parameter appendix includes (and implementation-defined behavior tables) from structured inputs instead of maintaining large static AsciiDoc fragments.
Changes:
- Added a Python generator to produce an AsciiDoc table of implementation-defined behaviors from
norm-rules.json. - Reworked
docs/crd/Makefileto generate params JSON/HTML and per-parameter AsciiDoc include files from new YAML parameter definition files. - Updated CRD sources to include generated param-appendix include files and removed previously committed per-parameter/static impl-def AsciiDoc artifacts.
Reviewed changes
Copilot reviewed 15 out of 16 changed files in this pull request and generated 7 comments.
Show a summary per file
| File | Description |
|---|---|
| generators/crd/generate_impl_def_table.py | New generator to build impl-defined behavior tables from norm-rules.json. |
| external/riscv-unified-db | Submodule bump to a newer unified-db revision. |
| docs/docs-resources | Submodule bump (schemas/tools used by parameter generation). |
| docs/crd/src/rvi20_crd.adoc | Switched param appendix includes to generated build includes. |
| docs/crd/src/mc100_crd.adoc | Switched param appendix includes to generated build includes. |
| docs/crd/src/param_defs/HPM_COUNTER_SZ.adoc | Removed static generated param definition snippet. |
| docs/crd/src/param_defs/LRSC_RESERVATION_STRATEGY.adoc | Removed static generated param definition snippet. |
| docs/crd/src/param_defs/MISALIGNED_ATOMICITY_GRANULE_SIZE.adoc | Removed static generated param definition snippet. |
| docs/crd/src/param_defs/MISALIGNED_LDST_HW_SUPPORT.adoc | Removed static generated param definition snippet. |
| docs/crd/src/param_defs/TIME_CSR_HW_SUPPORT.adoc | Removed static generated param definition snippet. |
| docs/crd/src/all_impldefs.adoc | Removed large static impl-def table artifact (now intended to be generated). |
| docs/crd/param_defs/rv32.yaml | New YAML input for RV32I-related parameter definitions. |
| docs/crd/param_defs/counters.yaml | New YAML input for counter/time CSR parameter definitions. |
| docs/crd/param_defs/a-st-ext.yaml | New YAML input for A-extension parameter definitions. |
| docs/crd/Makefile | Added params/appendix generation steps and updated Asciidoctor build dependencies. |
Collaborator
|
Looks like the updated UDB submodule is breaking the ACT4 tests. I'll look into that soon and push another PR that updates the UDB submodule separately along with whatever needs to change in ACT4 to work with the new UDB version. Why is the updated UDB needed for this PR? |
Contributor
Author
|
The latest UDB isn't required. It just came along for the ride when I used a git command to update repos to their latest commit. I can back out the UDB. |
Contributor
Author
|
@jordancarlin, can you roll back the UDB commit to the previous version unless you get UDB working? I'm trying to figure out how to do this in git/github and having no luck. |
Collaborator
Done |
…spective appendices. Add all_impldefs as separate doc Signed-off-by: James Ball <jameball@qti.qualcomm.com>
Signed-off-by: James Ball <jameball@qti.qualcomm.com>
…of-of-concept. Signed-off-by: James Ball <jameball@qti.qualcomm.com>
Signed-off-by: James Ball <jameball@qti.qualcomm.com>
… parameters. Next will be a Python script to convert that to the adoc for each parameter. Signed-off-by: James Ball <jameball@qti.qualcomm.com>
Signed-off-by: James Ball <jameball@qti.qualcomm.com>
Signed-off-by: James Ball <jameball@qti.qualcomm.com>
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> Signed-off-by: James Ball <jameball@qti.qualcomm.com>
Signed-off-by: James Ball <jameball@qti.qualcomm.com>
…ta type but need to review those and correct as needed next. Signed-off-by: James Ball <jameball@qti.qualcomm.com>
james-ball-qualcomm
force-pushed
the
prep-for-crd-generators
branch
from
db44fd3 to
a494bd4
Compare
Contributor
There was a problem hiding this comment.
Pull request overview
This PR introduces a generated “parameter appendix” pipeline for CRD docs by moving parameter/CSR definitions into YAML inputs and updating the build to generate AsciiDoc includes from those definitions.
Changes:
- Replaced several hand-maintained parameter AsciiDoc fragments with YAML parameter definition files.
- Updated CRD source documents to include generated parameter-appendix AsciiDoc from
build/param-appendix/.... - Extended
docs/crd/Makefilewith targets to generate params JSON/HTML and per-parameter appendix AsciiDoc, and wired those into the PDF/HTML build.
Reviewed changes
Copilot reviewed 29 out of 30 changed files in this pull request and generated 8 comments.
Show a summary per file
| File | Description |
|---|---|
| external/riscv-unified-db | Bumps submodule pointer to pick up upstream changes needed for generation. |
| docs/docs-resources | Bumps submodule pointer (likely for tooling/schema updates used by generators). |
| docs/crd/src/rvi20_crd.adoc | Switches parameter includes to generated build/param-appendix/... paths. |
| docs/crd/src/mc100_crd.adoc | Switches parameter includes to generated build/param-appendix/... paths. |
| docs/crd/src/param_defs/TIME_CSR_HW_SUPPORT.adoc | Removes hand-authored parameter include (now generated). |
| docs/crd/src/param_defs/MISALIGNED_LDST_HW_SUPPORT.adoc | Removes hand-authored parameter include (now generated). |
| docs/crd/src/param_defs/MISALIGNED_ATOMICITY_GRANULE_SIZE.adoc | Removes hand-authored parameter include (now generated). |
| docs/crd/src/param_defs/LRSC_RESERVATION_STRATEGY.adoc | Removes hand-authored parameter include (now generated). |
| docs/crd/src/param_defs/HPM_COUNTER_SZ.adoc | Removes hand-authored parameter include (now generated). |
| docs/crd/src/all_impldefs.adoc | Removes the standalone impl-defined behaviors document from this CRD build set. |
| docs/crd/param_defs/zilsd.yaml | Adds YAML source definitions for Zilsd parameters. |
| docs/crd/param_defs/zihintntl.yaml | Adds YAML source definitions for Zihintntl parameters. |
| docs/crd/param_defs/zc.yaml | Adds YAML source definitions for Zc parameters and CSRs. |
| docs/crd/param_defs/v-st-ext.yaml | Adds YAML source definitions for V extension parameters. |
| docs/crd/param_defs/supervisor.yaml | Adds YAML source definitions for supervisor-mode parameters and CSRs. |
| docs/crd/param_defs/smstateen.yaml | Adds YAML source definitions for state-enable CSRs. |
| docs/crd/param_defs/smctr.yaml | Adds YAML source definitions for SmCtr parameters and CSRs. |
| docs/crd/param_defs/rv32.yaml | Adds YAML source definitions for RV32I-related parameters. |
| docs/crd/param_defs/rnmi.yaml | Adds YAML source definitions for RNMI CSRs. |
| docs/crd/param_defs/priv-csrs.yaml | Adds YAML source definitions for Zicsr (priv) param(s) and CSR(s). |
| docs/crd/param_defs/machine.yaml | Adds YAML source definitions for machine-mode parameters and CSRs. |
| docs/crd/param_defs/indirect-csr.yaml | Adds YAML source definitions for indirect CSR(s). |
| docs/crd/param_defs/hypervisor.yaml | Adds YAML source definitions for hypervisor-mode parameters and CSRs. |
| docs/crd/param_defs/f-st-ext.yaml | Adds YAML source definitions for F extension parameters. |
| docs/crd/param_defs/counters.yaml | Adds YAML source definitions for counters-related parameters. |
| docs/crd/param_defs/cmo.yaml | Adds YAML source definitions for cache-management parameters. |
| docs/crd/param_defs/a-st-ext.yaml | Adds YAML source definitions for A extension parameters. |
| docs/crd/param_defs/README.md | Documents the purpose/format of the new YAML definition files. |
| docs/crd/Makefile | Adds param generation + param-appendix generation and integrates appendix into doc builds. |
Signed-off-by: James Ball <jameball@qti.qualcomm.com>
…eep the build directory just containing the final PDF/HTML docs. Signed-off-by: James Ball <jameball@qti.qualcomm.com>
Collaborator
@james-ball-qualcomm looks like you force-pushed and overwrote this? |
…xcept M-mode, Zc, Zihintntl, and Zilsd. Signed-off-by: James Ball <jameball@qti.qualcomm.com>
Signed-off-by: James Ball <jameball@qti.qualcomm.com>
Contributor
There was a problem hiding this comment.
Pull request overview
This PR introduces a generated-parameter workflow for CRD documents by moving parameter definitions into YAML inputs and updating the CRD build to generate/copy parameter-appendix AsciiDoc includes.
Changes:
- Update CRD AsciiDoc sources to include generated parameter-appendix files from
build/param-appendix/.... - Add YAML parameter/CSR definition inputs under
docs/crd/param_defs/plus anall_paramsdocument. - Extend
docs/crd/Makefilewith targets to generateparams.jsonand per-parameter appendix include files, and update.gitignorefor generated artifacts.
Reviewed changes
Copilot reviewed 28 out of 30 changed files in this pull request and generated 6 comments.
Show a summary per file
| File | Description |
|---|---|
| external/riscv-unified-db | Bumps submodule ref to pull in unified DB updates needed for generation. |
| docs/docs-resources | Bumps submodule ref, likely to pick up updated schemas/tools used by generators. |
| docs/crd/src/rvi20_crd.adoc | Switches parameter appendix includes to generated build/param-appendix/... paths. |
| docs/crd/src/param_defs/TIME_CSR_HW_SUPPORT.adoc | Removes legacy static parameter include content in favor of generated appendices. |
| docs/crd/src/param_defs/MISALIGNED_LDST_HW_SUPPORT.adoc | Removes legacy static parameter include content in favor of generated appendices. |
| docs/crd/src/param_defs/MISALIGNED_ATOMICITY_GRANULE_SIZE.adoc | Removes legacy static parameter include content in favor of generated appendices. |
| docs/crd/src/param_defs/LRSC_RESERVATION_STRATEGY.adoc | Removes legacy static parameter include content in favor of generated appendices. |
| docs/crd/src/param_defs/HPM_COUNTER_SZ.adoc | Removes legacy static parameter include content in favor of generated appendices. |
| docs/crd/src/mc100_crd.adoc | Switches parameter appendix includes to generated build/param-appendix/... paths. |
| docs/crd/src/all_params.adoc | Adds a new doc that includes generated “all params” appendices. |
| docs/crd/src/all_impldefs.adoc | Removes a large static impl-defs listing (presumably replaced by generator outputs elsewhere). |
| docs/crd/param_defs/zilsd.yaml | Adds YAML parameter definition input for Zilsd. |
| docs/crd/param_defs/zihintntl.yaml | Adds YAML parameter definition input for Zihintntl. |
| docs/crd/param_defs/zc.yaml | Adds YAML parameter/CSR definitions for the Zc extension. |
| docs/crd/param_defs/v-st-ext.yaml | Adds YAML parameter definitions for the V extension. |
| docs/crd/param_defs/supervisor.yaml | Adds YAML parameter/CSR definitions for Supervisor mode. |
| docs/crd/param_defs/smstateen.yaml | Adds YAML CSR definitions for Smstateen. |
| docs/crd/param_defs/smctr.yaml | Adds YAML parameter/CSR definitions for Smctr. |
| docs/crd/param_defs/rv32.yaml | Adds YAML parameter definitions for RV32 base ISA misaligned behavior. |
| docs/crd/param_defs/rnmi.yaml | Adds YAML CSR definitions for RNMI extension. |
| docs/crd/param_defs/machine.yaml | Adds YAML parameter/CSR definitions for Machine mode. |
| docs/crd/param_defs/indirect-csr.yaml | Adds YAML CSR definitions for indirect CSR mechanism. |
| docs/crd/param_defs/hypervisor.yaml | Adds YAML parameter/CSR definitions for H extension. |
| docs/crd/param_defs/counters.yaml | Adds YAML parameter definitions for counters / time CSR behavior. |
| docs/crd/param_defs/cmo.yaml | Adds YAML parameter definition for CMO cache block size. |
| docs/crd/param_defs/a-st-ext.yaml | Adds YAML parameter definitions for the A extension (LR/SC + misaligned atomicity granule). |
| docs/crd/param_defs/README.md | Documents the purpose/format of the YAML definition files and related schemas/tools. |
| docs/crd/Makefile | Adds generation targets (params, param-appendix), wires docs builds to generated appendices, updates docker mounts/workdir setup. |
| .gitignore | Ignores new generated output directory docs/crd/generated. |
Signed-off-by: James Ball <jameball@qti.qualcomm.com>
Signed-off-by: James Ball <jameball@qti.qualcomm.com>
Signed-off-by: James Ball <jameball@qti.qualcomm.com>
…cs-resources to get support for arrays I just added. Signed-off-by: James Ball <jameball@qti.qualcomm.com>
…my way thru M-mode chapter Signed-off-by: James Ball <jameball@qti.qualcomm.com>
Signed-off-by: James Ball <jameball@qti.qualcomm.com>
Signed-off-by: James Ball <jameball@qti.qualcomm.com>
…able. Signed-off-by: James Ball <jameball@qti.qualcomm.com>
Signed-off-by: James Ball <jameball@qti.qualcomm.com>
Signed-off-by: James Ball <jameball@qti.qualcomm.com>
…MISALIGNED_ATOMICITY_GRANULE_SIZE as param after today's Parameter SIG meeting (it is a PMA). Signed-off-by: James Ball <jameball@qti.qualcomm.com>
…0 to include relevant parameters and WARL/WLRL registers. Signed-off-by: James Ball <jameball@qti.qualcomm.com>
Signed-off-by: James Ball <jameball@qti.qualcomm.com>
Signed-off-by: James Ball <jameball@qti.qualcomm.com>
Signed-off-by: James Ball <jameball@qti.qualcomm.com>
Signed-off-by: James Ball <jameball@qti.qualcomm.com>
Signed-off-by: James Ball <jameball@qti.qualcomm.com>
Signed-off-by: James Ball <jameball@qti.qualcomm.com>
…not yet listed. Signed-off-by: James Ball <jameball@qti.qualcomm.com>
Signed-off-by: James Ball <jameball@qti.qualcomm.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
No description provided.