Merge branch 'main' into dhower/refs

Author: dhower-qc

.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

.vscode/settings.json

@@ -51,9 +51,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 +67,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,9 +101,16 @@ 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

README.adoc

@@ -7,7 +7,7 @@ addiw:
   base: 64
   assembly: xd, xs1, imm
   encoding:
-    match: -----------------000-----0001011
+    match: -----------------000-----0011011
     variables:
     - name: imm
       location: 31-20

arch/inst/I/addiw.yaml

@@ -0,0 +1,8 @@
+Creates an index of the database using JSON Reference.
+
+== Tasks
+
+[source,bash]
+----
+./do gen:index # writes index to ROOT/gen/indexer/index-unifieddb.json
+----

backends/indexer/README.adoc

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+'use strict';
+
+const process = require('process');
+const path = require('path');
+const fs = require('fs');
+
+const { readdir, stat } = fs.promises;
+
+const rec = async (branch, root) => {
+  const node = {};
+  const localPath = path.resolve(root, ...branch);
+  const els = await readdir(localPath);
+  for (const el of els) {
+    const isFile = (await stat(path.resolve(localPath, el))).isFile();
+    const fileExt = path.extname(el);
+    const baseName = path.basename(el, fileExt);
+    if (isFile) {
+      if (['.yaml', '.json'].includes(fileExt)) {
+        node[baseName] = {$ref: path.join(...branch, el)};
+      }
+    } else {
+      node[el] = await rec([...branch, el], root);
+    }
+  }
+  return node;
+};
+
+const main = async () => {
+  const [, , root] = process.argv;
+  if (root === undefined) {
+    console.error('usage: ./index-unifieddb.js <path-to-unifieddb-arch-folder>');
+    return;
+  }
+  const rootPath = path.resolve('.', root);
+  const tree = await rec([], rootPath);
+  console.log(JSON.stringify(tree, null, 2));
+};
+
+main();

backends/indexer/index-unifieddb.js

@@ -0,0 +1,13 @@
+
+require "pathname"
+
+namespace :gen do
+  desc "Generate index of the database"
+  task :index do
+    index_path = Pathname.new("#{$root}/gen/indexer/index-unified.json")
+    Dir.chdir "#{$root}/backends/indexer" do
+      FileUtils.mkdir_p index_path.dirname
+      File.write index_path, `node index-unifieddb.js #{$root}`
+    end
+  end
+end