[TASK] Implement and deploy full doc+config generation flow based on riscv-config specs

[zchamski]

Is there an existing CVA6 task for this?

• I have searched the existing task issues

Task Description

In the spirit of the "Single Source of Truth", integrate and complete the existing proof-of-concept tools in order to generate the following project components from a single riscv-config specification:

• CSR design specification (including custom CSRs);
• ISA design specification (including custom instructions);
• RTL configuration file;
• Spike configuration file;
• linker configuration file (and optionally assembler/compiler command line options);
• directed tests of CSRs (including custom ones);
• directed tests of instructions (including custom ones);
• directed tests of platform (e.g., memory mapping, memory-mapped registers).

Required Changes

• the riscv-config tool (under vendor/riscv/riscv-config): new features to be added, bug fixes;
• the riscv-config specification files for various targets: updates/fixes to existing files, new configurations to be added;
• the output generation scripts under config/gen_from_riscv_config: need bug fixes, rewrites, addition of new scripts;
• the production flow of specification documents: to be updated;
• the test suites under verif/tests: new test families may be added;
• the CI infrastructure: new processes, new jobs to be added;
• the overall project operation: introduction of new processes to update/generate specification documents, configuration files and test suites.

Current Status

[2025-01-24]

• riscv-config specification file available for CV32A65X (needs fixes/updates/extensions);
• prototype of ISA design spec generator available, generated ISA doc used in production;
• prototype of CSR design spec generator available (spec patched manually prior to publication), patched CSR doc used in production;
• prototype of Spike Yaml configuration file generator available (file patched manually prior to deployment), patched Yaml files used in production;
• prototype of CSR directed test generator likely available (TBC);
• prototype of ISA directed test generator likely available (TBC);
• NO generator available for:
  • RTL configuration file;
  • linker configuration file.

Risks

• some target config properties not easily representable in stock riscv-config;
  • mitigation: learn/understand the structure and operation of riscv-config to introduce enhancements if/as/when needed.
• CSR directed test generator to be (re-)written from scratch
  • mitigation: current test suites are deemed sufficient to achieve complete coverage.
• ISA directed test generator to be (re-)written from scratch
  • mitigation: test suites are deemed sufficient to achieve complete coverage.

Prerequisites

None

KPI (KEY Performance Indicators)

• amount of manual changes (as number of lines to be altered: sum of git + and - counts) needed to make generated files production-ready
  • per file category: CSR design spec, ISA design spec, RTL configuration file, Spike configuration file, test suite (if generated)
  • per supported target configuration (CV32A65X, CV32A60X)
  • partial values per file category x target configuration
  • total across all file categories and target configurations

Description of Done

All of:

• ISA design spec generated automatically from riscv-config specifications with 0 lines to be altered manually;
• CSR design spec generated automatically from riscv-config specifications with 0 lines to be altered manually;
• RTL configuration file generated automatically from riscv-config specifications with 0 lines to be altered manually;
• Spike configuration file generated automatically from riscv-config specifications with 0 lines to be altered manually;
• Linker configuration file generated automatically from riscv-config specifications with 0 lines to be altered manually;
• CSR directed tests generated automatically from riscv-config specifications with 0 lines to be altered manually.

Associated PRs

List non exhaustive, to be updated when related issues are identified:

• [BUG] (spinoff of #2404 / #2699) Update CV32A65X riscv-config specs to match Zinctr ISA spec update. #2701
• [BUG][cv32a65x] Zicntr support: conflicting information between documentation and RTL  #2404
• Issue with MTVEC CSR default value #1312

NOTE: When adding new issues to the list please keep them in newest first order.

[JeanRochCoulon]

This task superseeds #2701, #1312 and #1739. These bugs must be fixed by this task.