Tools specification

.github/workflows/ci.yml

@@ -57,6 +57,10 @@ jobs:
         run: |
           util/clang_tidy.py
 
+      - name: Tool schema validation
+        run: |
+          util/tool_schema_validate.py
+
   verilator-test:
     runs-on: ["self-hosted", "nixos", "X64"]
     needs: lint-check

.gitignore

@@ -27,3 +27,7 @@ __pycache__
 scratch/
 # clangd
 .cache
+
+# JSON schema
+node_modules/
+tool_schema.json

flake.nix

@@ -74,20 +74,21 @@
 
       commonPackages = with pkgs; [
         cmake
+        d2
+        dtc
+        ftditool-cli
         gnumake
-        screen
-        picocom
         gtkwave
         openfpgaloader
-        ftditool-cli
         openocd
-        uv
+        picocom
         pythonEnv
+        screen
+        srecord
+        uv
         verilator
         verible
-        srecord
-        d2
-        dtc
+        wget
       ];
     in {
       formatter = pkgs.alejandra;

package.json

@@ -0,0 +1,5 @@
+{
+  "dependencies": {
+    "ajv-cli": "^5.0.0"
+  }
+}

pyproject.toml

@@ -37,6 +37,9 @@ dependencies = [
     "dvsim>=1.33",
     "svgwrite>=1.4.3",
     "pyelftools>=0.32",
+    # Tool schema validation.
+    "jsonschema>=4.26.0",
+    "types-jsonschema>=4.26.0",
 ]
 
 [tool.setuptools]

tool_data.json

@@ -0,0 +1,34 @@
+[
+    {
+        "name": "FuseSoC",
+        "vendor": "olofk",
+        "version": "2.4.3",
+        "source-url": "https://github.com/olofk/fusesoc",
+        "doc-url": "https://fusesoc.readthedocs.io/en/stable/index.html",
+        "comment": "FuseSoC is a build system for digital hardware."
+    },
+    {
+        "name": "Jasper",
+        "vendor": "Cadence",
+        "version": "2025.09p002",
+        "comment": "Formal verification."
+    },
+    {
+        "name": "Verilator",
+        "vendor": "Veripool",
+        "version": "v5.0.40",
+        "comment": "Open source simulation tool."
+    },
+    {
+        "name": "Vivado",
+        "vendor": "Xilinx",
+        "version": "v2021.1",
+        "comment": "Used to build bitstreams for Genesys 2."
+    },
+    {
+        "name": "Xcelium",
+        "vendor": "Cadence",
+        "version": "24.03-s007",
+        "comment": "Provides xrun for simulations and is used to run our full DV environment."
+    }
+]

util/tool_schema_validate.py

@@ -0,0 +1,40 @@
+#!/usr/bin/env python
+# Copyright lowRISC contributors (COSMIC project).
+# Licensed under the Apache License, Version 2.0, see LICENSE for details.
+# SPDX-License-Identifier: Apache-2.0
+
+import jsonschema
+
+try:
+    import json
+    import pathlib
+    import urllib.error
+    import urllib.request
+
+    url_string = ('https://raw.githubusercontent.com/'
+                  'marnovandermaas/tool-schema/refs/'
+                  'heads/main/tool_schema.json')
+
+    with urllib.request.urlopen(url_string) as url:
+        schema = json.loads(url.read())
+
+    with pathlib.Path('tool_data.json').open() as valid_data_file:
+        tool_data = json.load(valid_data_file)
+except FileNotFoundError as err:
+    print('Error: The tool data file was not found.')
+    raise SystemExit(1) from err
+except json.JSONDecodeError as err:
+    print('Error: Failed to decode JSON from the file.')
+    raise SystemExit(2) from err
+except urllib.error.URLError as err:
+    print('Failed to fetch tool schema.')
+    raise SystemExit(3) from err
+
+try:
+    jsonschema.validate(instance=tool_data, schema=schema)
+except jsonschema.ValidationError as err:
+    print('Tool data is invalid according to the schema.')
+    raise SystemExit(10) from err
+
+# If we get here the tool data has successfully been validated.
+raise SystemExit(0)