Merge branch 'main' of https://github.com/riscv-software-src/riscv-unified-db into c_ext

Author: ayosher

.devcontainer/Dockerfile

@@ -0,0 +1,15 @@
+FROM ubuntu:24.04 AS spython-base
+RUN export DEBIAN_FRONTEND=noninteractive
+RUN apt-get update
+RUN apt-get install -y --no-install-recommends git
+RUN apt-get install -y --no-install-recommends python3
+RUN apt-get install -y --no-install-recommends python3.12-venv python3-pip
+RUN apt-get install -y --no-install-recommends build-essential
+RUN apt-get install -y --no-install-recommends ruby ruby-dev
+RUN apt-get install -y --no-install-recommends bundler
+RUN apt-get install -y --no-install-recommends nodejs
+RUN apt-get install -y --no-install-recommends npm
+RUN apt-get install -y --no-install-recommends ditaa
+RUN apt-get clean autoclean
+RUN apt-get autoremove -y
+RUN rm -rf /var/lib/{apt, dpkg, cache, log}

.devcontainer/devcontainer.json

@@ -0,0 +1,41 @@
+{
+  "name": "RISC-V UnifiedDB Dev",
+  "build": { "dockerfile": "Dockerfile" },
+  "updateContentCommand": "${containerWorkspaceFolder}/.devcontainer/updateContentCommand.sh",
+  "onCreateCommand": "${containerWorkspaceFolder}/.devcontainer/onCreateCommand.sh",
+  "remoteEnv": {
+    "DISPLAY": ":0"
+  },
+  "containerEnv": {
+    "DEVCONTAINER_ENV": "true"
+  },
+  // vscode extensions
+  "customizations": {
+    "vscode": {
+      "settings": {
+        "solargraph.bundlerPath": "bundle",
+        "solargraph.useBundler": true,
+        "files.exclude": {
+          "**/.home": true,
+          "**/.yardoc": true
+        },
+        "files.watcherExclude": {
+          "**/.home": true
+        },
+        "asciidoc.antora.showEnableAntoraPrompt": true
+      },
+      "extensions": [
+        "castwide.solargraph",
+        "redhat.vscode-yaml",
+        "asciidoctor.asciidoctor-vscode",
+        "zhwu95.riscv",
+        "tomoki1207.pdf",
+        "CraigMaslowski.erb",
+        "HowerLimited.idl-vscode"
+      ]
+    }
+  },
+  "forwardPorts": [
+    8000, 8080
+  ]
+}

.devcontainer/onCreateCommand.sh

@@ -0,0 +1,4 @@
+#!/bin/bash
+
+npm i 
+bundle install

.devcontainer/updateContentCommand.sh

@@ -0,0 +1,3 @@
+#!/bin/bash
+
+bundle

.github/ISSUE_TEMPLATE/data-entry.md

@@ -0,0 +1,10 @@
+---
+name: Data Entry
+about: Add new data into the database
+title: ''
+labels: data entry
+assignees: ''
+
+---
+
+**Describe the data**

.github/workflows/pages.yml

@@ -57,18 +57,26 @@ jobs:
       run: mkdir -p _site/htmls
     - name: Copy cfg html
       run: cp -R gen/cfg_html_doc/generic_rv64/html _site/example_cfg
-    - name: Create RVA Family PDF Spec
-      run: ./do gen:profile_pdf[rva]
-    - name: Copy RVA Family PDF
-      run: cp gen/profile_doc/pdf/rva.pdf _site/pdfs/rva.pdf
-    - name: Create MC-1 PDF Spec
-      run: ./do gen:crd_pdf[MC-1]
-    - name: Copy MC-1 PDF
-      run: cp gen/crd_doc/pdf/MC-1.pdf _site/pdfs/MC-1.pdf
-    - name: Create MC-1 HTML Spec
-      run: ./do gen:crd_html[MC-1]
-    - name: Copy MC-1 HTML
-      run: cp gen/crd_doc/html/MC-1.html _site/htmls/MC-1.html
+    - name: Create RVA20 Profile Release PDF Spec
+      run: ./do gen:profile[RVA20]
+    - name: Copy RVA20 Profile Release PDF
+      run: cp gen/profile_doc/pdf/RVA20.pdf _site/pdfs/RVA20.pdf
+    - name: Create RVA22 Profile Release PDF Spec
+      run: ./do gen:profile[RVA22]
+    - name: Copy RVA22 Profile Release PDF
+      run: cp gen/profile_doc/pdf/RVA22.pdf _site/pdfs/RVA22.pdf
+    - name: Create RVI20 Profile Release PDF Spec
+      run: ./do gen:profile[RVI20]
+    - name: Copy RVI20 Profile Release PDF
+      run: cp gen/profile_doc/pdf/RVA20.pdf _site/pdfs/RVI20.pdf
+    - name: Create MC100 PDF Spec
+      run: ./do gen:cert_model_pdf[MC100]
+    - name: Copy MC100 PDF
+      run: cp gen/certificate_doc/pdf/MC100.pdf _site/pdfs/MC100.pdf
+    - name: Create MC100 HTML Spec
+      run: ./do gen:cert_model_html[MC100]
+    - name: Copy MC100 HTML
+      run: cp gen/certificate_doc/html/MC100.html _site/htmls/MC100.html
     - name: Copy manual html
       run: cp -R gen/manual/isa/top/all/html _site/manual
     - name: Setup Pages

.vscode/settings.json

@@ -8,8 +8,10 @@ The following artifacts have been generated from the top of the `main` branch:
 * https://riscv-software-src.github.io/riscv-unified-db/example_cfg/html/index.html[configuration-specific documentation]
 * https://riscv-software-src.github.io/riscv-unified-db/ruby/arch_def/index.html[Ruby API documentation (database interface)]
 * https://riscv-software-src.github.io/riscv-unified-db/ruby/idl/index.html[Ruby IDL API documentation (IDL compiler)]
-* https://riscv-software-src.github.io/riscv-unified-db/pdfs/rva.pdf[RVA Profile Family]
-* https://riscv-software-src.github.io/riscv-unified-db/pdfs/MC-1.pdf[MC-1 Certification Requirements Document]
+* https://riscv-software-src.github.io/riscv-unified-db/pdfs/RVI20.pdf[RVI20 Profile Release]
+* https://riscv-software-src.github.io/riscv-unified-db/pdfs/RVA20.pdf[RVA20 Profile Release]
+* https://riscv-software-src.github.io/riscv-unified-db/pdfs/RVA22.pdf[RVA22 Profile Release]
+* https://riscv-software-src.github.io/riscv-unified-db/pdfs/MC100.pdf[MC100 Certification Requirements Document]
 
 == Overview
 
@@ -28,7 +30,7 @@ This repository contains:
 
 === Working examples:
 
- * Generate https://riscv-software-src.github.io/riscv-unified-db/manual/index.html[configuration-specific documentation] taylored to the set of implemented extensions and unnamed implementation options (_e.g._, `./do gen:html[generic_rv64]`).
+ * Generate https://riscv-software-src.github.io/riscv-unified-db/manual/html/index.html[configuration-specific documentation] taylored to the set of implemented extensions and unnamed implementation options (_e.g._, `./do gen:html[generic_rv64]`).
  ** Only implemented extensions/instructions/CSRs are included
  ** Unreachable/unimplemented parts of the formal specification are pruned away
  ** A dedicated documentation page for every implemented instruction, including its encoding, pruned execution behavior, and what types of exceptions it may cause.
@@ -51,9 +53,14 @@ This repository contains:
 
 == Prerequisites
 
-The only requirement is the `Singularity CE` (>= 3.3) or `Apptainer` (>= 1.0) container system. Either one will work (they are forks).
+There are two supported ways to run the RISC-V Unified Database,
+both of which are container-based.
 
-If it is not installed, either as your IT admin or:
+=== Singularity/Apptainer
+
+You can run within `Singularity CE` (>= 3.3) or `Apptainer` (>= 1.0) container system. Either one will work (they are forks).
+
+If it is not installed, either ask your IT admin or:
 
  * For Apptainer, see https://apptainer.org/docs/admin/main/installation.html[Apptainer Installation].
  * For Singularity CE, see https://docs.sylabs.io/guides/latest/admin-guide/installation.html[Singularity CE Installation].
@@ -62,35 +69,31 @@ If it is not installed, either as your IT admin or:
 You do *not* need root privileges to download or use the container. However, to modify/build the container,
 you will need either root privileges or the ability to run in `fakeroot` mode. See https://docs.sylabs.io/guides/4.1/user-guide/fakeroot.html[Singularity Fakeroot Documentation] for more information.
 
-== Setup
+When you run with Singularity/Apptainer, the files under `bin/`
+will run within the container, _e.g._:
 
-Do once:
+```bash
+./bin/ruby --version
+# => ruby 3.2.3 (2024-01-18 revision 52bb2ac0a6) [x86_64-linux-gnu]
+```
 
-[source,bash]
-----
-./bin/setup
+=== Devcontainer
 
-# or, if you also want development tools (:development group in Gemfile) installed
-# DEVELOPMENT=1 ./bin/setup
-----
+You can also leverage https://containers.dev/[devcontainers] to run the RISC-V Unified Database.
 
-[NOTE]
-If you forget, don't worry. Setup will be invoked by any program in bin/ if necessary.
+This is especially useful when using Visual Studio Code or GitHub codespaces, as it will setup up your IDE environment for you.
+
+==== VS Code
 
-=== VSCode
+To run the devcontainer locally, you will need to have https://docs.docker.com/engine/install[Docker installed].
 
-If using Visual Studio Code and want to use development tools, you will need to restart the editor
-after setup.
+With Docker installed, install the https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers[Dev Containers] extension in VS Code.
 
-Helpful extensions are
+You can then run `Dev Containers: Open Folder in Container...` from the Command Palette (Ctrl+Shift+P) and select the folder with this repository.
 
- * https://marketplace.visualstudio.com/items?itemName=asciidoctor.asciidoctor-vscode[AsciiDoc]
- * https://marketplace.visualstudio.com/items?itemName=redhat.vscode-yaml[YAML]
- * https://marketplace.visualstudio.com/items?itemName=castwide.solargraph[Solargraph] (for a Ruby Language Server)
- * https://marketplace.visualstudio.com/items?itemName=onnovalkering.vscode-singularity[Singularity] (if you plan on working on the container)
+==== GitHub Codespaces
 
-The `.vscode/settings.json` file in the repo will ensure that Solargraph works without any additional
-configuration (assuming you've already run ./bin/setup).
+You can start a GitHub Codespace for this repository by clicking the "Code" button and selecting "Open with Codespaces".
 
 == Tasks
 
@@ -100,13 +103,18 @@ Quick start:
 ----
 ./do --tasks                 # list all documented tasks
 
-# examples
-./do validate                # validate against the schema
-./do gen:arch[generic_rv64]  # generate arch spec for the 'generic_rv64' config
+## examples
+
+# validate against the schema
+./do validate
+
+# generate all versions of ISA manual, as an Antora static website
+./do gen:html_manual MANUAL_NAME=isa VERSIONS=all
+
+# generate an implementation-specific spec for the 'generic_rv64' config
+./do gen:arch[generic_rv64]
 ----
 
 == More info
 
  * xref:arch/README.adoc[Architecture specification format]
- * xref:_site/ruby/arch_def/index.html[Ruby database object model documentation]
- * xref:_site/ruby/idl/index.html[IDL Compiler documentation]

README.adoc

@@ -55,8 +55,20 @@ namespace :serve do
   end
 end
 
-Minitest::TestTask.create :idl_test do |t|
+desc "Run the IDL compiler test suite"
+task :idl_test do
+  t = Minitest::TestTask.new(:lib_test)
   t.test_globs = ["#{$root}/lib/idl/tests/test_*.rb"]
+  t.process_env
+  ruby t.make_test_cmd
+end
+
+desc "Run the Ruby library test suite"
+task :lib_test do
+  t = Minitest::TestTask.new(:lib_test)
+  t.test_globs = ["#{$root}/lib/test/test_*.rb"]
+  t.process_env
+  ruby t.make_test_cmd
 end
 
 desc "Clean up all generated files"
@@ -269,15 +281,60 @@ desc <<~DESC
 DESC
 task :regress do
   Rake::Task["idl_test"].invoke
+  Rake::Task["lib_test"].invoke
   Rake::Task["validate"].invoke
   ENV["MANUAL_NAME"] = "isa"
   ENV["VERSIONS"] = "all"
   Rake::Task["gen:html_manual"].invoke
   Rake::Task["gen:html"].invoke("generic_rv64")
-  Rake::Task["gen:crd_pdf"].invoke("MockCRD-1")
-  Rake::Task["gen:crd_pdf"].invoke("MC-1")
-  Rake::Task["gen:profile_pdf"].invoke("rva")
+  Rake::Task["#{$root}/gen/certificate_doc/pdf/MockCertificateModel.pdf"].invoke
+  Rake::Task["#{$root}/gen/certificate_doc/pdf/MC100.pdf"].invoke
+  Rake::Task["#{$root}/gen/profile_doc/pdf/MockProfileRelease.pdf"].invoke
+  Rake::Task["#{$root}/gen/profile_doc/pdf/RVA20.pdf"].invoke
+  Rake::Task["#{$root}/gen/profile_doc/pdf/RVA22.pdf"].invoke
+  Rake::Task["#{$root}/gen/profile_doc/pdf/RVI20.pdf"].invoke
 
   puts
   puts "Regression test PASSED"
 end
+
+desc <<~DESC
+  Generate all certificates and profile PDFs.
+DESC
+task :cert_profile_pdfs do
+  puts "==================================="
+  puts "cert_profile_pdfs: Generating MC100"
+  puts "                   1st target"
+  puts "==================================="
+  Rake::Task["#{$root}/gen/certificate_doc/pdf/MC100.pdf"].invoke
+
+  puts "=================================================="
+  puts "cert_profile_pdfs: Generating MockCertificateModel"
+  puts "                   2nd target"
+  puts "=================================================="
+  Rake::Task["#{$root}/gen/certificate_doc/pdf/MockCertificateModel.pdf"].invoke
+
+  puts "==================================="
+  puts "cert_profile_pdfs: Generating RVA20"
+  puts "                   3rd target"
+  puts "==================================="
+  Rake::Task["#{$root}/gen/profile_doc/pdf/RVA20.pdf"].invoke
+
+  puts "==================================="
+  puts "cert_profile_pdfs: Generating RVA22"
+  puts "                   4th target"
+  puts "==================================="
+  Rake::Task["#{$root}/gen/profile_doc/pdf/RVA22.pdf"].invoke
+
+  puts "==================================="
+  puts "cert_profile_pdfs: Generating RVI20"
+  puts "                   5th target"
+  puts "==================================="
+  Rake::Task["#{$root}/gen/profile_doc/pdf/RVI20.pdf"].invoke
+
+  puts "==================================="
+  puts "cert_profile_pdfs: Generating MockProfileRelease"
+  puts "                   6th target"
+  puts "==================================="
+  Rake::Task["#{$root}/gen/profile_doc/pdf/MockProfileRelease.pdf"].invoke
+end

Rakefile

@@ -0,0 +1,35 @@
+MC:
+  name: MC
+  long_name: Microcontroller Certificate Class
+
+  introduction: |
+    This certification class specifies requirements for microcontrollers.
+    It targets microcontrollers running low-level software on an RTOS or bare-metal.
+    This CRD is not intended for the smallest possible microcontrollers but rather for applications
+    benefiting from a standardized microcontroller.
+    See the https://docs.google.com/document/d/133SZKc18tLsQcT1o6gEmBUkjwrtg2ow63me54RQ1jiY[RISC-V CRDs]
+    document for information relevant to all RISC-V CRDs.
+
+  naming_scheme: |
+    The MC (M = Microcontroller, C = Certificate) has the following naming scheme (suffixes after MC
+    are optional but in the below order):
+
+     MC<model>[v<version>]
+
+    Where:
+
+    * Left & right square braces denote optional. 
+    * \<model> is a 3 digit integer. It is changed only when mandatory extensions are added to a CRD.
+    ** The one's digit is incremented when a small mandatory extension is added (e.g., Zicond)
+    ** The ten's digit is incremented when a medium mandatory extension is addded (e.g., PMP)
+    ** The hundreds's digit is incremented when a large mandatory extension is addded (e.g., V or H)
+    * \<version> is a semantic version (see semver.org) formatted as <major>[.<minor>.[patch]]. If \<version> is omitted, the reference applies equally to all versions. 
+    ** A <major> release indicates support for a new optional extension.
+    ** A <minor> release indicates one or more of the following changes to the certification tests associated with the CRD.
+    *** Fix test bug or increase test coverage
+    *** Add more allowed parameter values
+    *** Support new extension version
+    ** A <patch> release indicates just CRD specification changes without any difference in functional behavior
+
+  mandatory_priv_modes:
+  - M