Development (#6)

Numerous enhancements:

 * Added passes to detect which functions are reachable and which exceptions might occur in an AST
 * Add landing page for cfg html doc
 * Actually parsing CSR read/write functinos
 * Add htimedelta and hcountern CSRs
 * Only show the implemented functions in the cfg html docs
 * Show which exceptions might be raised for each instruction in cfg html docs
 * Add String types to IDL so that configuration parameter strings can be compared
 * Improve IDL documentation
 * Improved pruning
 * Add gen_adoc for all AstNodes
 * Add action to publich cfg_html example and YARD docs to GitHub pages
 * find/replace links on the entire adoc document, rather than specific sections
 * Completed refactoring to make AstNodes independent of SyntaxNodes

Author: dhower-qc

.github/workflows/pages.yml

@@ -0,0 +1,60 @@
+name: Deploy pages
+on:
+  push:
+    branches:
+    - main
+  workflow_dispatch:
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+jobs:
+  pages:
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+    - name: Clone Github Repo Action
+      uses: actions/checkout@v4
+    - name: Setup apptainer
+      uses: eWaterCycle/[email protected]
+    - name: Get container from cache
+      id: cache-sif
+      uses: actions/cache@v3
+      with:
+        path: .singularity/image.sif
+        key: ${{ hashFiles('container.def') }}
+    - name: Get gems and node files from cache
+      id: cache-bundle-npm
+      uses: actions/cache@v3
+      with:
+        path: |
+          .home/.gems
+          node_modules
+        key: ${{ hashFiles('Gemfile.lock') }}-${{ hashFiles('package-lock.json') }}
+    - if: ${{ steps.cache-sif.outputs.cache-hit != 'true' }}
+      name: Build container
+      run: ./bin/build_container
+    - name: Setup project
+      run: ./bin/setup
+    - name: Build html documentation for generic_rv64
+      run: ./do gen:html[generic_rv64]
+    - name: Generate YARD docs
+      run: ./do gen:tool_doc
+    - name: Create _site
+      run: mkdir -p _site
+    - name: Copy cfg html
+      run: cp -R gen/cfg_html_doc/generic_rv64/html _site
+    - name: Setup Pages
+      uses: actions/configure-pages@v5
+    - name: Upload artifact
+      uses: actions/upload-pages-artifact@v3
+      with:
+        path: '_site'
+    - name: Deploy to GitHub Pages
+      id: deployment
+      uses: actions/deploy-pages@v4

.yardopts

@@ -1 +1 @@
--o docs/ruby --embed-mixins 'lib/**/*.rb'
+-o _site/ruby --embed-mixins 'lib/**/*.rb'

Gemfile

@@ -20,4 +20,5 @@ gem "yard"
 group :development do
   gem "solargraph"
   gem 'rubocop-minitest'
+  gem 'ruby-prof'
 end

Gemfile.lock

@@ -107,6 +107,7 @@ GEM
     rubocop-minitest (0.35.1)
       rubocop (>= 1.61, < 2.0)
       rubocop-ast (>= 1.31.1, < 2.0)
+    ruby-prof (1.7.0)
     ruby-progressbar (1.13.0)
     ruby-rc4 (0.1.5)
     simpleidn (0.2.3)
@@ -154,6 +155,7 @@ DEPENDENCIES
   minitest
   rake (~> 13.0)
   rubocop-minitest
+  ruby-prof
   slim (~> 5.1)
   solargraph
   treetop (= 1.6.12)

README.adoc

@@ -1,4 +1,4 @@
-# RISC-V Unified Database
+= RISC-V Unified Database
 
 The RISC-V Unified Database is intended to hold *all* the information needed to describe RISC-V,
 including a list of extensions, instruction specifications, CSR specifications, and documentation prose. The vision is that anything one would need for RISC-V can be generated from the information in this repository.
@@ -11,7 +11,32 @@ This repository contains:
  ** [COMING SOON] A configuration-specific Instruction Set Simulator
  ** More backends are planned
 
-## Prerequisites
+== What can it do?
+
+=== Working examples:
+
+ * Generate https://riscv-software-src.github.io/riscv-unified-db/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/unimplmented 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.
+ ** A dedication documentation page for every implemented CSR, including its (possibly runtime-changing) encoding, fields, and pruned behavior on reads and writes
+ ** Clickable links to all mentions of instructions, extensions, CSRs, CSR fields, and glossary terms.
+ * Generate documentation for specific extensions (_e.g._, `./do gen:ext_pdf[B]`)
+ ** Automatically include a complete list of added instructions and CSRs
+ ** Per-instruction documentation
+ ** Per-CSR documentation
+ ** Formal specification
+ * Generate a single YAML file containing *everything* knowable about a configuration (_e.g._, `./do gen:cfg_arch[generic_rv64]`).
+
+=== Possibilities:
+
+  * Generate binutils files for an extension
+  * Generate instruction tables for compilers
+  * Generate https://github.com/riscv/riscv-opcodes[riscv-opcodes]
+  * Generate the full RISC-V specification, along with an appendix of instructions and CSRs
+  * ...
+
+== Prerequisites
 
 The only requirement is the `Singularity CE` or `Apptainer` container system. Either one will work (they are forks).
 
@@ -24,7 +49,7 @@ 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
+== Setup
 
 Do once:
 
@@ -39,7 +64,7 @@ Do once:
 [NOTE]
 If you forget, don't worry. Setup will be invoked by any program in bin/ if necessary.
 
-### VSCode
+=== VSCode
 
 If using Visual Studio Code and want to use development tools, you will need to restart the editor
 after setup.
@@ -54,7 +79,7 @@ Helpful extensions are
 The `.vscode/settings.json` file in the repo will ensure that Solargraph works without any additional
 configuration (assuming you've already run ./bin/setup).
 
-## Tasks
+== Tasks
 
 Quick start:
 
@@ -67,7 +92,7 @@ Quick start:
 ./do validate                # validate against the schema
 ----
 
-## More info
+== More info
 
  * xref:arch/README.adoc[Architecture specification format]
  * xref:arch/README.adoc[Documentation for the generator tool and IDL]

Rakefile

@@ -178,6 +178,16 @@ file "#{$root}/arch/csr/S/scounteren.yaml" => [
   File.write(t.name, insert_warning(erb.result(binding), t.prerequisites.first))
 end
 
+file "#{$root}/arch/csr/H/hcounteren.yaml" => [
+  "#{$root}/arch/csr/H/hcounteren.layout",
+  __FILE__
+] do |t|
+  puts "Generating #{Pathname.new(t.name).relative_path_from($root)}"
+  erb = ERB.new(File.read($root / "arch/csr/H/hcounteren.layout"), trim_mode: "-")
+  erb.filename = "#{$root}/arch/csr/H/hcounteren.layout"
+  File.write(t.name, insert_warning(erb.result(binding), t.prerequisites.first))
+end
+
 file "#{$root}/arch/csr/Zicntr/mcountinhibit.yaml" => [
   "#{$root}/arch/csr/Zicntr/mcountinhibit.layout",
   __FILE__
@@ -203,6 +213,7 @@ namespace :gen do
 
     Rake::Task["#{$root}/arch/csr/I/mcounteren.yaml"].invoke
     Rake::Task["#{$root}/arch/csr/S/scounteren.yaml"].invoke
+    Rake::Task["#{$root}/arch/csr/H/hcounteren.yaml"].invoke
     Rake::Task["#{$root}/arch/csr/Zicntr/mcountinhibit.yaml"].invoke
 
     (0..63).each do |pmpaddr_num|

arch/csr/H/hcounteren.layout

@@ -0,0 +1,91 @@
+# yaml-language-server: $schema=../../../schemas/csr_schema.json
+
+hcounteren:
+  long_name: Hypervisor Counter Enable
+  address: 0x606
+  priv_mode: S
+  length: 32
+  description: |
+    Together with `scounteren`, delegates control of the hardware performance-monitoring counters
+    to VS/VU-mode
+
+    See `cycle` for a table describing how exceptions occur.
+  definedBy: H
+  fields:
+    CY:
+      location: 0
+      description: |
+        When all of `scounteren.CY`, `mcounteren.CY`, and `hcounteren.CY` are set,
+        the `cycle` CSR (an alias of `mcycle`) is accessible to VU-mode.
+
+        When `mcounteren.CY` and `hcounteren.CY` are set,
+        the `cycle` CSR (an alias of `mcycle`) is accessible to VS-mode.
+
+        This bit is read-only 0 when `mcounteren.CY` is clear.
+
+        Summary:
+
+        !===
+        ! `mcounteren.CY` ! `hcounteren.CY` behavior
+
+        ! 0 ! read-only 0
+        ! 1 ! writeable
+        !===
+      definedBy: Zicntr
+      type: RW-H
+      reset_value: UNDEFINED_LEGAL
+    IR:
+      location: 2
+      description: |
+        When all of `scounteren.IR`, `mcounteren.IR`, and `hcounteren.IR` are set,
+        the `instret` CSR (an alias of `minstret`) is accessible to VU-mode.
+
+        When `mcounteren.IR` and `hcounteren.IR` are set,
+        the `instret` CSR (an alias of `minstret`) is accessible to VS-mode.
+
+        This bit is read-only 0 when `mcounteren.IR` is clear.
+
+        Summary:
+
+        !===
+        ! `mcounteren.IR` ! `hcounteren.IR` behavior
+
+        ! 0 ! read-only 0
+        ! 1 ! writeable
+        !===
+
+
+      type: RW-H
+      reset_value: UNDEFINED_LEGAL
+    <%- (3..31).each do |hpm_num| -%>
+    HPM<%= hpm_num %>:
+      location: <%= hpm_num %>
+      description: |
+        When all of `scounteren.HPM<%= hpm_num %>`, `mcounteren.HPM<%= hpm_num %>`, and `hcounteren.HPM<%= hpm_num %>` are set,
+        the `hpmcounter<%= hpm_num %>` CSR (an alias of `mhpmcounter<%= hpm_num %>`) is accessible to VU-mode.
+
+        When `mcounteren.HPM<%= hpm_num %>` and `hcounteren.HPM<%= hpm_num %>` are set,
+        the `hpmcounter<%= hpm_num %>` CSR (an alias of `mhpmconuter<%= hpm_num %>`) is accessible to VS-mode.
+
+        This bit is read-only 0 when `mcounteren.HPM<%= hpm_num %>` is clear.
+
+        Summary:
+
+        !===
+        ! `mcounteren.HPM<%= hpm_num %>` ! `hcounteren.HPM<%= hpm_num %>` behavior
+
+        ! 0 ! read-only 0
+        ! 1 ! writeable
+        !===
+
+      type: RW
+      reset_value: UNDEFINED_LEGAL
+    <%- end -%>
+  sw_read(): |
+    if (!implemented?(ExtensionName::Zicntr) && !implemented?(ExtensionName::Zihpm)) {
+      # this CSR isn't supposed to exist when Zicntr and Zihpm are not implemented
+      raise(ExceptionCode::IllegalInstruction, $encoding);
+    }
+
+    # any bit of mcounteren that is zero forces that same bit of hcounteren to 0
+    return $bits(CSR[hcounteren]) & $bits(CSR[mcounteren]);