udb 0.1.9 → 0.1.13

data/.data/spec/schemas/config_schema.json

@@ -1,6 +1,8 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "v0.1",
+  "title": "Configuration Schema",
+  "description": "A configuration represents RISC-V architectural choices - ranging from complete design specifications to requirement sets to unconstrained baselines.\n\n> **See also:** Configurations Overview for a narrative introduction with examples and use cases.\n\nConfigurations come in three forms:\n\n- **Fully configured**: Concrete implementations with all extensions and parameters explicitly specified. These represent actual processor implementations where every architectural detail is known. Each extension must specify an exact version (e.g., `2.1.0` or `2.1`). Used for generating implementations, documentation, and test suites for specific hardware.\n\n- **Partially configured**: Profiles or configurable IP that define mandatory, optional, and prohibited extensions using version constraints (e.g., `>= 2.0`). These specify requirements that multiple implementations can satisfy. Can restrict whether additional extensions beyond those listed are allowed. Used for RISC-V compliance profiles, configurable IP offerings (a class of implementations a vendor may offer), and platform requirements.\n\n- **Unconfigured**: Special case representing the entire RISC-V specification without any implementation choices. Used to model the complete RISC-V architecture space before any configuration decisions are made.\n\nThe variant is selected by the `type` field. Fields common to all variants: `name`, `description`, `arch_overlay`. The `params` field is available on `fully configured` and `partially configured` variants.\n\n> **Note:** Schema validation checks structural correctness only. A schema-valid file can still be semantically invalid - for example, referencing an extension version that does not exist in the database, or omitting a parameter that is required by the implemented extensions.",
   "$defs": {
     "full_configuration": {
       "type": "object",
@@ -15,17 +17,18 @@
       ],
       "properties": {
         "$schema": {
-          "type": "string",
-          "format": "uri-reference",
-          "const": "config_schema.json#"
+          "const": "config_schema.json#",
+          "description": "Schema reference - must be `config_schema.json#`"
         },
         "kind": {
           "type": "string",
-          "const": "architecture configuration"
+          "const": "architecture configuration",
+          "description": "Document type identifier - must be `architecture configuration`"
         },
         "type": {
           "type": "string",
-          "const": "fully configured"
+          "const": "fully configured",
+          "description": "Configuration specificity level - `fully configured` means all extensions and parameters are explicitly specified"
         },
         "name": {
           "type": "string",
@@ -33,19 +36,32 @@
         },
         "description": {
           "type": "string",
-          "description": "An asciidoc description of the configuration"
+          "description": "Human-readable description of this configuration (AsciiDoc format)"
         },
         "arch_overlay": {
           "type": "string",
-          "description": "Optional arch overlay to apply. Can be either the name of a directory under arch_overlay/ or a (absolute or relative) path to an overlay directory"
+          "description": "Optional arch overlay to apply. Can be either the name of a directory under arch_overlay/ or an absolute or relative path to an overlay directory"
         },
         "$source": {
           "type": "string",
           "format": "uri",
-          "description": "Path to original file, when this is a copy"
+          "description": "Source file path when this configuration was generated or copied from another file"
+        },
+        "compatible": {
+          "description": "Declares that this configuration is compatible with one or more other configurations — meaning there exists at least one concrete hardware implementation that satisfies both this config and each listed config simultaneously. Each pointer is either the name of a config in the repository cfgs/ directory or a path to a config YAML file (absolute, or relative to this file). Compatibility is checked transitively: if config B lists config C as compatible, then this config must also be compatible with C.",
+          "examples": [
+            "profile/RVA23U64",
+            ["profile/RVA23U64", "profile/RVB23U64"],
+            "../other/my_config.yaml"
+          ],
+          "oneOf": [
+            { "type": "string" },
+            { "type": "array", "items": { "type": "string" } }
+          ]
         },
         "params": {
-          "type": "object"
+          "type": "object",
+          "description": "Architecture parameters that define implementation choices (e.g., `MXLEN: 64`, privilege modes, physical address width, etc.). Parameter names and valid values are defined by the parameter data files in `spec/std/isa/param/`."
         },
         "implemented_extensions": {
           "description": "Extensions implemented by this architecture",
@@ -62,7 +78,23 @@
                 "$ref": "schema_defs.json#/$defs/extension_version"
               }
             }
-          }
+          },
+          "examples": [
+            [
+              {
+                "name": "I",
+                "version": "2.1.0"
+              },
+              {
+                "name": "M",
+                "version": "2.0.0"
+              },
+              {
+                "name": "Zicsr",
+                "version": "2.0.0"
+              }
+            ]
+          ]
         }
       },
       "additionalProperties": false
@@ -81,15 +113,18 @@
         "$schema": {
           "type": "string",
           "format": "uri-reference",
-          "const": "config_schema.json#"
+          "const": "config_schema.json#",
+          "description": "Schema reference - must be `config_schema.json#`"
         },
         "kind": {
           "type": "string",
-          "const": "architecture configuration"
+          "const": "architecture configuration",
+          "description": "Document type identifier - must be `architecture configuration`"
         },
         "type": {
           "type": "string",
-          "const": "partially configured"
+          "const": "partially configured",
+          "description": "Configuration specificity level - `partially configured` means some extensions/parameters are specified as requirements while others are left open"
         },
         "name": {
           "type": "string",
@@ -97,19 +132,32 @@
         },
         "description": {
           "type": "string",
-          "description": "An asciidoc description of the configuration"
+          "description": "Human-readable description of this configuration (AsciiDoc format)"
         },
         "params": {
-          "type": "object"
+          "type": "object",
+          "description": "Architecture parameters that constrain compliant implementations. The entire `params` key may be omitted if no parameter constraints are needed. Parameter names and valid values are defined by the parameter data files in `spec/std/isa/param/`."
         },
         "arch_overlay": {
           "type": "string",
-          "description": "Optional arch overlay to apply. Can be either the name of a directory under arch_overlay/ or a (absolute or relative) path to an overlay directory"
+          "description": "Optional arch overlay to apply. Can be either the name of a directory under arch_overlay/ or an absolute or relative path to an overlay directory"
         },
         "$source": {
           "type": "string",
           "format": "uri",
-          "description": "Path to original file, when this is a copy"
+          "description": "Source file path when this configuration was generated or copied from another file"
+        },
+        "compatible": {
+          "description": "Declares that this configuration is compatible with one or more other configurations — meaning there exists at least one concrete hardware implementation that satisfies both this config and each listed config simultaneously. Each pointer is either the name of a config in the repository cfgs/ directory or a path to a config YAML file (absolute, or relative to this file). Compatibility is checked transitively: if config B lists config C as compatible, then this config must also be compatible with C.",
+          "examples": [
+            "profile/RVA23U64",
+            ["profile/RVA23U64", "profile/RVB23U64"],
+            "../other/my_config.yaml"
+          ],
+          "oneOf": [
+            { "type": "string" },
+            { "type": "array", "items": { "type": "string" } }
+          ]
         },
         "mandatory_extensions": {
           "description": "Extensions mandatory in this architecture",
@@ -119,7 +167,7 @@
           }
         },
         "non_mandatory_extensions": {
-          "description": "Extensions that are not mandatory but are still _special_ in this architecture. This could mean different things depending on the context: for certificates or generated IP, this would correspond to _optional supported_, and extensions not in non_mandatory are not possible. For profiles, this corresponds to some type of _profile optional_, but extensions in non_mandatory are still possible.",
+          "description": "Optional extensions with special significance in this architecture. For configurable IP, these are optionally supported extensions. For profiles, these are profile-optional extensions.",
           "type": "array",
           "items": {
             "$ref": "schema_defs.json#/$defs/extension_requirement"
@@ -138,10 +186,11 @@
         "additional_extensions": {
           "type": "boolean",
           "default": true,
-          "description": "Whether or not a compliant instance of this partial config can have more extensions than those listed in mandatory_extensions/non_mandatory_extensions"
+          "description": "Whether a compliant instance may implement extensions beyond those listed in `mandatory_extensions`/`non_mandatory_extensions`. Defaults to `true` if omitted."
         },
         "requirements": {
-          "$ref": "schema_defs.json#/$defs/condition"
+          "$ref": "schema_defs.json#/$defs/condition",
+          "description": "Additional condition that must be satisfied for this configuration to be valid (e.g., a parameter constraint or extension dependency)."
         }
       },
       "additionalProperties": false
@@ -153,15 +202,18 @@
         "$schema": {
           "type": "string",
           "format": "uri-reference",
-          "const": "config_schema.json#"
+          "const": "config_schema.json#",
+          "description": "Schema reference - must be `config_schema.json#`"
         },
         "kind": {
           "type": "string",
-          "const": "architecture configuration"
+          "const": "architecture configuration",
+          "description": "Document type identifier - must be `architecture configuration`"
         },
         "type": {
           "type": "string",
-          "const": "unconfigured"
+          "const": "unconfigured",
+          "description": "Configuration specificity level - `unconfigured` represents the entire RISC-V specification with all implementation choices left unresolved"
         },
         "name": {
           "type": "string",
@@ -169,16 +221,16 @@
         },
         "arch_overlay": {
           "type": "string",
-          "description": "Optional arch overlay to apply. Can be either the name of a directory under arch_overlay/ or a (absolute or relative) path to an overlay directory"
+          "description": "Optional arch overlay to apply. Can be either the name of a directory under arch_overlay/ or an absolute or relative path to an overlay directory"
         },
         "$source": {
           "type": "string",
           "format": "uri",
-          "description": "Path to original file, when this is a copy"
+          "description": "Source file path when this configuration was generated or copied from another file"
         },
         "description": {
           "type": "string",
-          "description": "An asciidoc description of the configuration"
+          "description": "Human-readable description of this configuration (AsciiDoc format)"
         }
       },
       "additionalProperties": false
@@ -194,5 +246,146 @@
     {
       "$ref": "#/$defs/unconfiguration"
     }
+  ],
+  "examples": [
+    {
+      "_title": "Minimal Fully Configured",
+      "_quick_start": true,
+      "$schema": "config_schema.json#",
+      "kind": "architecture configuration",
+      "type": "fully configured",
+      "name": "MyProcessor",
+      "description": "A minimal 64-bit RISC-V processor",
+      "params": {
+        "MXLEN": 64
+      },
+      "implemented_extensions": [
+        { "name": "I", "version": "2.1" },
+        { "name": "Sm", "version": "1.12" }
+      ]
+    },
+    {
+      "_title": "Minimal Partially Configured",
+      "_quick_start": true,
+      "$schema": "config_schema.json#",
+      "kind": "architecture configuration",
+      "type": "partially configured",
+      "name": "MyProfile",
+      "description": "A minimal profile requiring base integer instructions",
+      "mandatory_extensions": [{ "name": "I", "version": ">= 2.1" }]
+    },
+    {
+      "_title": "Minimal Unconfigured",
+      "_quick_start": true,
+      "$schema": "config_schema.json#",
+      "kind": "architecture configuration",
+      "type": "unconfigured",
+      "name": "generic",
+      "description": "The complete RISC-V specification with no implementation choices"
+    },
+    {
+      "_title": "Full Configuration Example (RV64)",
+      "$schema": "config_schema.json#",
+      "kind": "architecture configuration",
+      "type": "fully configured",
+      "name": "RV64GC",
+      "description": "64-bit RISC-V with General-purpose and Compressed extensions",
+      "params": {
+        "XLEN": 64,
+        "MXLEN": 64,
+        "SXLEN": 64,
+        "UXLEN": 64
+      },
+      "implemented_extensions": [
+        {
+          "name": "I",
+          "version": "2.1"
+        },
+        {
+          "name": "M",
+          "version": "2.0"
+        },
+        {
+          "name": "A",
+          "version": "2.1"
+        },
+        {
+          "name": "F",
+          "version": "2.2"
+        },
+        {
+          "name": "D",
+          "version": "2.2"
+        },
+        {
+          "name": "C",
+          "version": "2.0"
+        },
+        {
+          "name": "Zicsr",
+          "version": "2.0"
+        },
+        {
+          "name": "Zifencei",
+          "version": "2.0"
+        }
+      ]
+    },
+    {
+      "_title": "Partial Configuration Example (Profile)",
+      "$schema": "config_schema.json#",
+      "kind": "architecture configuration",
+      "type": "partially configured",
+      "name": "RVA22U64",
+      "description": "RISC-V Application Profile for 64-bit Unix-like systems",
+      "mandatory_extensions": [
+        {
+          "name": "I",
+          "version": ">= 2.1"
+        },
+        {
+          "name": "M",
+          "version": ">= 2.0"
+        },
+        {
+          "name": "A",
+          "version": ">= 2.1"
+        },
+        {
+          "name": "F",
+          "version": ">= 2.2"
+        },
+        {
+          "name": "D",
+          "version": ">= 2.2"
+        },
+        {
+          "name": "C",
+          "version": ">= 2.0"
+        },
+        {
+          "name": "Zicsr",
+          "version": ">= 2.0"
+        }
+      ],
+      "non_mandatory_extensions": [
+        {
+          "name": "V",
+          "version": ">= 1.0"
+        }
+      ],
+      "params": {
+        "XLEN": 64
+      },
+      "additional_extensions": false
+    },
+    {
+      "_title": "Unconfigured Example",
+      "$schema": "config_schema.json#",
+      "kind": "architecture configuration",
+      "type": "unconfigured",
+      "name": "generic",
+      "description": "Generic unconfigured RISC-V architecture"
+    }
   ]
 }

data/.data/spec/schemas/csr_schema.json

@@ -115,9 +115,6 @@
             }
           ],
           "description": "Extension(s) that affect the definition of the field beyond the extension (or base) the field is originally defined in"
-        },
-        "cert_normative_rules": {
-          "$ref": "schema_defs.json#/$defs/cert_normative_rules"
         }
       },
       "allOf": [
@@ -272,9 +269,6 @@
     "$source": {
       "description": "Path to the source file this definition came from; used by downstream tooling -- not expected to be in handwritten files",
       "type": "string"
-    },
-    "cert_normative_rules": {
-      "$ref": "schema_defs.json#/$defs/cert_normative_rules"
     }
   },
   "additionalProperties": false,

data/.data/spec/schemas/ext_schema.json

@@ -1,6 +1,7 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "v0.1",
+  "description": "An ISA extension defines a named set of instructions, CSRs, and behaviors that can be implemented by a RISC-V processor. Each extension has one or more versioned releases, with various ratification states (development, frozen, public-review, ratification-ready, ratified, or nonstandard-released).\n\n## Key Fields\n\n- `name`: Short identifier used throughout the database (e.g., `I`, `M`, `Zicsr`, `Smstateen`)\n- `long_name`: Human-readable one-line description\n- `description`: Full AsciiDoc documentation of the extension\n- `type`: Whether the extension is `unprivileged` or `privileged`\n- `versions`: Array of versioned releases, each with a `state` and optional `ratification_date`\n- `requirements`: Optional condition that must be true for the extension to be implementable (e.g., requires another extension)\n- `company`: Organization that developed the extension (defaults to RISC-V International for standard extensions)\n- `doc_license`: License for the extension documentation",
   "type": "object",
   "required": [
     "$schema",
@@ -11,50 +12,105 @@
     "long_name",
     "versions"
   ],
+  "examples": [
+    {
+      "_title": "Minimal Extension (Zicsr)",
+      "_quick_start": true,
+      "$schema": "ext_schema.json#",
+      "kind": "extension",
+      "name": "Zicsr",
+      "long_name": "Control and status register instructions",
+      "description": "Control and status register instructions",
+      "type": "unprivileged",
+      "versions": [
+        {
+          "version": "2.0.0",
+          "state": "ratified",
+          "ratification_date": "2019-04"
+        }
+      ]
+    },
+    {
+      "_title": "Extension with Requirements (B)",
+      "$schema": "ext_schema.json#",
+      "kind": "extension",
+      "name": "B",
+      "long_name": "Bit Manipulation",
+      "description": "The B standard extension comprises instructions provided by the Zba, Zbb, and Zbs extensions.",
+      "type": "unprivileged",
+      "company": {
+        "name": "RISC-V International",
+        "url": "https://riscv.org"
+      },
+      "doc_license": {
+        "name": "Creative Commons Attribution 4.0 International License",
+        "url": "https://creativecommons.org/licenses/by/4.0/"
+      },
+      "versions": [
+        {
+          "version": "1.0.0",
+          "state": "ratified",
+          "ratification_date": "2024-04",
+          "url": "https://drive.google.com/file/d/1SgLoasaBjs5WboQMaU3wpHkjUwV71UZn/view",
+          "requirements": {
+            "extension": {
+              "allOf": [
+                { "name": "Zba", "version": "= 1.0.0" },
+                { "name": "Zbb", "version": "= 1.0.0" },
+                { "name": "Zbs", "version": "= 1.0.0" }
+              ]
+            }
+          }
+        }
+      ]
+    }
+  ],
   "properties": {
     "$schema": {
       "type": "string",
       "format": "uri-reference",
-      "description": "Path to schema, relative to <UDB ROOT>/schemas",
+      "description": "Schema reference - must be `ext_schema.json#`",
       "const": "ext_schema.json#"
     },
     "kind": {
       "type": "string",
       "const": "extension",
-      "description": "Object type"
+      "description": "Document type identifier - must be `extension`"
     },
     "name": {
       "$ref": "schema_defs.json#/$defs/extension_name"
     },
     "long_name": {
       "type": "string",
-      "description": "One line description for the extension"
+      "description": "One-line human-readable name for the extension (e.g., `Address generation`, `Bit Manipulation`)"
     },
     "description": {
       "$ref": "schema_defs.json#/$defs/spec_text",
-      "description": "Full documentation of the extension"
+      "description": "Full AsciiDoc documentation of the extension. May include multiple paragraphs, code examples, and cross-references."
     },
     "rvi_jira_issue": {
       "type": "string",
-      "description": "JIRA issue number for the RVI issue that tracks this extension"
+      "description": "JIRA issue number tracking this extension in the RISC-V International issue tracker"
     },
     "company": {
-      "description": "The company that developed this extension",
+      "description": "Organization that developed this extension. Omit for RISC-V International standard extensions.",
       "$ref": "schema_defs.json#/$defs/company"
     },
     "doc_license": {
+      "description": "License for the extension documentation",
       "$ref": "schema_defs.json#/$defs/license"
     },
     "type": {
       "enum": ["unprivileged", "privileged"],
-      "description": "Either unprivileged or privileged"
+      "description": "Privilege level of the extension. `unprivileged` extensions add instructions or behaviors accessible in user mode; `privileged` extensions add supervisor- or machine-mode functionality."
     },
     "requirements": {
-      "description": "Condition represeting requirements of this extension. If the condition is false, the extension cannot be implemented",
+      "description": "Condition that must be true for this extension to be implementable. If the condition is false, the extension cannot be implemented. Typically used to express that one extension requires another (e.g., `D` requires `F`).",
       "$ref": "schema_defs.json#/$defs/condition"
     },
     "versions": {
       "type": "array",
+      "description": "Ordered list of versioned releases of this extension, from oldest to newest.",
       "items": {
         "type": "object",
         "required": ["version", "state"],
@@ -100,31 +156,34 @@
         ],
         "properties": {
           "version": {
-            "$ref": "schema_defs.json#/$defs/extension_version"
+            "$ref": "schema_defs.json#/$defs/extension_version",
+            "description": "Version number in `MAJOR.MINOR.PATCH` format (e.g., `1.0.0`, `2.1.0`)"
           },
           "state": {
             "$ref": "schema_defs.json#/$defs/spec_state",
-            "description": "Current state of this version"
+            "description": "Ratification state of this version. See `spec_state` in schema_defs for all possible values and their meanings."
           },
           "repositories": {
-            "description": "Repositories associated with this extension",
+            "description": "Source repositories where this version of the extension is developed",
             "type": "array",
             "items": {
               "type": "object",
               "properties": {
                 "url": {
                   "type": "string",
-                  "format": "uri"
+                  "format": "uri",
+                  "description": "Repository URL"
                 },
                 "branch": {
                   "type": "string",
-                  "description": "Branch/tag where the work is done"
+                  "description": "Branch or tag containing the work for this version"
                 }
               },
               "additionalProperties": false
             }
           },
           "ratification_date": {
+            "description": "Month when this version was ratified, in `YYYY-MM` format. Use `unknown` if the date is not recorded. Required when `state` is `ratified`.",
             "oneOf": [
               {
                 "type": "string",
@@ -169,37 +228,37 @@
             "items": {
               "type": "string"
             },
-            "description": "Changes since last version"
+            "description": "List of changes introduced in this version relative to the previous version"
           },
           "url": {
             "type": "string",
             "format": "uri",
-            "description": "Link to ratified document"
+            "description": "URL to the ratified specification document (e.g., a PDF on the RISC-V website)"
           },
           "contributors": {
-            "description": "List of contributors to this version of the extension",
+            "description": "People who contributed to this version of the extension",
             "type": "array",
             "items": {
               "type": "object",
               "properties": {
                 "name": {
                   "type": "string",
-                  "description": "Contributor name, in 'GIVEN_NAME SURNAME' format"
+                  "description": "Contributor name in `GIVEN_NAME SURNAME` format"
                 },
                 "company": {
                   "type": "string",
-                  "description": "Company the contributor worked for, or 'Individual'"
+                  "description": "Company the contributor worked for at the time, or `Individual`"
                 },
                 "email": {
                   "type": "string",
                   "format": "email",
-                  "description": "E-mail address for the contributor"
+                  "description": "Contributor email address"
                 }
               }
             }
           },
           "requirements": {
-            "description": "Condition represeting requirements of this extension version _in addition to any specified for the extension overall_. If the condition is false, the extension version cannot be implemented",
+            "description": "Additional condition that must be true for this specific version to be implementable, beyond any requirements on the extension overall. If the condition is false, this version cannot be implemented.",
             "$ref": "schema_defs.json#/$defs/condition"
           }
         },
@@ -208,10 +267,7 @@
     },
     "$source": {
       "type": "string",
-      "description": "Source file where this extension was defined"
-    },
-    "cert_normative_rules": {
-      "$ref": "schema_defs.json#/$defs/cert_normative_rules"
+      "description": "Source file path when this extension was generated or copied from another file"
     }
   },
   "additionalProperties": false

data/.data/spec/schemas/inst_schema.json

@@ -386,9 +386,6 @@
     "operation_ast": {
       "type": "object"
     },
-    "cert_normative_rules": {
-      "$ref": "schema_defs.json#/$defs/cert_normative_rules"
-    },
     "assembly": {
       "type": "string",
       "description": "Assembly format of the instruction. Can use decode variables"

data/.data/spec/schemas/profile_release_schema.json

@@ -14,7 +14,7 @@
       "type": "string",
       "description": "Name (database key) of this Profile Release"
     },
-    "long name": {
+    "long_name": {
       "type": "string",
       "description": "One line description of this Profile Release"
     }

data/.data/spec/schemas/profile_schema.json

@@ -32,9 +32,6 @@
       "type": "integer",
       "description": "32 for RV32I or 64 for RV64I"
     },
-    "cert_normative_rules": {
-      "$ref": "schema_defs.json#/$defs/cert_normative_rules"
-    },
     "requirements": {
       "$ref": "schema_defs.json#/$defs/condition"
     },