Merge pull request #238 from riscv/add_func_of

james-ball-qualcomm · web-flow · commit 78567fd20d65 · 2026-03-26T16:06:19.000-07:00
Added optional func-of to WARL/WLRL schema.
diff --git a/schemas/param-common-schema.json b/schemas/param-common-schema.json
@@ -136,5 +136,17 @@
       "$ref": "#/csrNamePattern"
     },
     "minItems": 1
+  },
+  "funcOfRegName": {
+    "allOf": [
+      { "$ref": "#/csrName" },
+      { "description": "CSR name associated with function-of relationship" }
+    ]
+  },
+  "funcOfFieldName": {
+    "allOf": [
+      { "$ref": "#/csrName" },
+      { "description": "CSR field name associated with function-of relationship" }
+    ]
   }
 }
diff --git a/schemas/param-defs-schema.json b/schemas/param-defs-schema.json
@@ -144,6 +144,12 @@
             "$ref": "param-common-schema.json#/csrName",
             "description": "Single CSR field name"
           },
+          "func-of-reg-name": {
+            "$ref": "param-common-schema.json#/funcOfRegName"
+          },
+          "func-of-field-name": {
+            "$ref": "param-common-schema.json#/funcOfFieldName"
+          },
           "field-names": {
             "$ref": "param-common-schema.json#/csrNameArray",
             "description": "Multiple CSR field names"
diff --git a/schemas/params-schema.json b/schemas/params-schema.json
@@ -114,6 +114,12 @@
             "type": "string",
             "description": "CSR field name"
           },
+          "func-of-reg-name": {
+            "$ref": "param-common-schema.json#/funcOfRegName"
+          },
+          "func-of-field-name": {
+            "$ref": "param-common-schema.json#/funcOfFieldName"
+          },
           "def_filename": {
             "type": "string",
             "description": "Parameter definition file that defines this CSR"
@@ -176,6 +182,14 @@
                 "required": ["width-parameter"]
               }
             }
+          },
+          {
+            "if": {
+              "required": ["func-of-field-name"]
+            },
+            "then": {
+              "required": ["func-of-reg-name"]
+            }
           }
         ],
         "additionalProperties": false
diff --git a/tests/norm-rule/expected/test-ch2-norm-tags.json b/tests/norm-rule/expected/test-ch2-norm-tags.json
@@ -17,7 +17,7 @@
     "norm:mock-csr-x": "Here&#8217;s a normative rule for mock CSR \"X\".",
     "norm:mock-csr-field-y": "Here&#8217;s a normative rule for mock CSR field \"Y\".",
     "norm:mock-ext-dep-A-on-B": "Here&#8217;s a normative rule for mock extension dependency of extension A on extension B.",
-    "norm:foo_abc_warl_enum": "An implementation may support any or all of the following values for the 4-bit foo.ABC field: 0, 4, 15.",
+    "norm:foo_abc_warl_enum": "An implementation may support any or all of the following values for the 4-bit foo.ABC field: When foo.GHI is 0, legal values are 0, 4, 15. When foo.GHI is non-zero, legal values are 1, 2, 3.",
     "norm:foo_ghi_warl_var_width": "The foo.GHI CSR field width ranges from 4 to 8 bits as specified by the UINT_4TO8 parameter value.",
     "norm:zort_xyz_wlrl_ro_mask": "An implementation may treat each bit of the zort.XYZ\nCSR as read-only or read-write",
     "norm:qux_qqq_wlrl_other": "The qux.QQQ CSR field has implementation-defined behavior\nthat doesn't match any of the defined WARL/WLRL types."
diff --git a/tests/norm-rule/expected/test-norm-rules.html b/tests/norm-rule/expected/test-norm-rules.html
@@ -1065,7 +1065,7 @@ <h1 class="grand-total-heading">94 Normative Rules: Includes 31 Implementation-D
               <td>Implementation-defined behavior category</td>
             </tr>
             <tr>
-              <td>An implementation may support any or all of the following values for the 4-bit foo.ABC field: 0, 4, 15.</td>
+              <td>An implementation may support any or all of the following values for the 4-bit foo.ABC field: When foo.GHI is 0, legal values are 0, 4, 15. When foo.GHI is non-zero, legal values are 1, 2, 3.</td>
               <td><a href="test-ch2.html#norm:foo_abc_warl_enum">norm:foo_abc_warl_enum</a></td>
             </tr>
             <tr>
@@ -1499,7 +1499,7 @@ <h1 class="grand-total-heading">94 Normative Rules: Includes 31 Implementation-D
               <td>Instance</td>
             </tr>
             <tr>
-              <td>An implementation may support any or all of the following values for the 4-bit foo.ABC field: 0, 4, 15.</td>
+              <td>An implementation may support any or all of the following values for the 4-bit foo.ABC field: When foo.GHI is 0, legal values are 0, 4, 15. When foo.GHI is non-zero, legal values are 1, 2, 3.</td>
               <td><a href="test-ch2.html#norm:foo_abc_warl_enum">norm:foo_abc_warl_enum</a></td>
             </tr>
             <tr>
@@ -1959,7 +1959,7 @@ <h1 class="grand-total-heading">94 Normative Rules: Includes 31 Implementation-D
               <td>Implementation-defined behavior category</td>
             </tr>
             <tr>
-              <td>An implementation may support any or all of the following values for the 4-bit foo.ABC field: 0, 4, 15.</td>
+              <td>An implementation may support any or all of the following values for the 4-bit foo.ABC field: When foo.GHI is 0, legal values are 0, 4, 15. When foo.GHI is non-zero, legal values are 1, 2, 3.</td>
               <td><a href="test-ch2.html#norm:foo_abc_warl_enum">norm:foo_abc_warl_enum</a></td>
             </tr>
             <tr>
diff --git a/tests/norm-rule/expected/test-norm-rules.json b/tests/norm-rule/expected/test-norm-rules.json
@@ -1541,7 +1541,7 @@
         {
           "name": "norm:foo_abc_warl_enum",
           "context": false,
-          "text": "An implementation may support any or all of the following values for the 4-bit foo.ABC field: 0, 4, 15.",
+          "text": "An implementation may support any or all of the following values for the 4-bit foo.ABC field: When foo.GHI is 0, legal values are 0, 4, 15. When foo.GHI is non-zero, legal values are 1, 2, 3.",
           "tag_filename": "/build/test-ch2-norm-tags.json",
           "stds_doc_url": "test-ch2.html"
         }
diff --git a/tests/norm-rule/test-ch2.adoc b/tests/norm-rule/test-ch2.adoc
@@ -82,7 +82,7 @@ Here's a normative rule for mock extension dependency of extension A on extensio
 
 === Chapter 2.3 - CSR Field Types
 
-[#norm:foo_abc_warl_enum]#An implementation may support any or all of the following values for the 4-bit `foo.ABC` field: 0, 4, 15.#
+[#norm:foo_abc_warl_enum]#An implementation may support any or all of the following values for the 4-bit `foo.ABC` field: When `foo.GHI` is 0, legal values are 0, 4, 15. When `foo.GHI` is non-zero, legal values are 1, 2, 3.#
 
 [#norm:foo_ghi_warl_var_width]#The `foo.GHI` CSR field width ranges from 4 to 8 bits as specified by the UINT_4TO8 parameter value.#
 
diff --git a/tests/params/expected/test-csr-appendix-adoc-includes/test-ch2/foo.ABC.adoc b/tests/params/expected/test-csr-appendix-adoc-includes/test-ch2/foo.ABC.adoc
@@ -1,5 +1,6 @@
 | foo.ABC
-| LegalEnum
+a| LegalEnum +
+func-of: foo.GHI
 | FLD:foo.ABC
 a|
 * https://riscv.github.io/riscv-isa-manual/snapshot/norm-rules/norm-rules.html#FOO_ABC_WARL_ENUM[FOO_ABC_WARL_ENUM]
diff --git a/tests/params/expected/test-csr-appendix-adoc-includes/test-ch2/qux.QQQ.adoc b/tests/params/expected/test-csr-appendix-adoc-includes/test-ch2/qux.QQQ.adoc
@@ -1,5 +1,6 @@
 | qux.QQQ
-| Other
+a| Other +
+func-of: foo.GHI
 | FLD:qux.QQQ
 a|
 * https://riscv.github.io/riscv-isa-manual/snapshot/norm-rules/norm-rules.html#QUX_QQQ_WLRL_OTHER[QUX_QQQ_WLRL_OTHER]
diff --git a/tests/params/expected/test-csr-table-variants/test-csr-table-full-default/test-ch2/foo.ABC.adoc b/tests/params/expected/test-csr-table-variants/test-csr-table-full-default/test-ch2/foo.ABC.adoc
@@ -1,5 +1,6 @@
 | foo.ABC
-| LegalEnum
+a| LegalEnum +
+func-of: foo.GHI
 | FLD:foo.ABC
 a|
 * https://riscv.github.io/riscv-isa-manual/snapshot/norm-rules/norm-rules.html#FOO_ABC_WARL_ENUM[FOO_ABC_WARL_ENUM]
diff --git a/tests/params/expected/test-csr-table-variants/test-csr-table-full-default/test-ch2/qux.QQQ.adoc b/tests/params/expected/test-csr-table-variants/test-csr-table-full-default/test-ch2/qux.QQQ.adoc
@@ -1,5 +1,6 @@
 | qux.QQQ
-| Other
+a| Other +
+func-of: foo.GHI
 | FLD:qux.QQQ
 a|
 * https://riscv.github.io/riscv-isa-manual/snapshot/norm-rules/norm-rules.html#QUX_QQQ_WLRL_OTHER[QUX_QQQ_WLRL_OTHER]
diff --git a/tests/params/expected/test-csr-table-variants/test-csr-table-reordered/test-ch2/foo.ABC.adoc b/tests/params/expected/test-csr-table-variants/test-csr-table-reordered/test-ch2/foo.ABC.adoc
@@ -1,4 +1,5 @@
-| LegalEnum
+a| LegalEnum +
+func-of: foo.GHI
 | FLD:foo.ABC
 | foo.ABC
 a|
diff --git a/tests/params/expected/test-csr-table-variants/test-csr-table-reordered/test-ch2/qux.QQQ.adoc b/tests/params/expected/test-csr-table-variants/test-csr-table-reordered/test-ch2/qux.QQQ.adoc
@@ -1,4 +1,5 @@
-| Other
+a| Other +
+func-of: foo.GHI
 | FLD:qux.QQQ
 | qux.QQQ
 a|
diff --git a/tests/params/expected/test-params.html b/tests/params/expected/test-params.html
@@ -421,9 +421,9 @@ <h1 class="grand-total-heading">42 Parameters, 5 WARL/WLRL CSRs</h1>
           <tbody>
             <tr>
               <td rowspan=1 id="foo.ABC">foo.ABC</td>
-              <td rowspan=1>LegalEnum</td>
+              <td rowspan=1>LegalEnum<br>func-of: foo.GHI</td>
               <td rowspan=1>FLD:foo.ABC</td>
-              <td><a href="test-ch2.html#norm:foo_abc_warl_enum">An implementation may support any or all of the following values for the 4-bit foo.ABC field: 0, 4, 15.</a></td>
+              <td><a href="test-ch2.html#norm:foo_abc_warl_enum">An implementation may support any or all of the following values for the 4-bit foo.ABC field: When foo.GHI is 0, legal values are 0, 4, 15. When foo.GHI is non-zero, legal values are 1, 2, 3.</a></td>
             </tr>
             <tr>
               <td rowspan=1 id="foo.GHI">foo.GHI</td>
@@ -456,7 +456,7 @@ <h1 class="grand-total-heading">42 Parameters, 5 WARL/WLRL CSRs</h1>
             </tr>
             <tr>
               <td rowspan=1 id="qux.QQQ">qux.QQQ</td>
-              <td rowspan=1>Other</td>
+              <td rowspan=1>Other<br>func-of: foo.GHI</td>
               <td rowspan=1>FLD:qux.QQQ</td>
               <td><a href="test-ch2.html#norm:qux_qqq_wlrl_other">The qux.QQQ CSR field has implementation-defined behavior<br>that doesn't match any of the defined WARL/WLRL types.</a></td>
             </tr>
diff --git a/tests/params/expected/test-params.json b/tests/params/expected/test-params.json
@@ -1535,6 +1535,8 @@
       "chapter_name": "Two",
       "category": "WARL",
       "type": "LegalEnum",
+      "func-of-reg-name": "foo",
+      "func-of-field-name": "GHI",
       "impl-defs": [
         {
           "name": "FOO_ABC_WARL_ENUM",
@@ -1550,7 +1552,7 @@
             {
               "name": "norm:foo_abc_warl_enum",
               "context": false,
-              "text": "An implementation may support any or all of the following values for the 4-bit foo.ABC field: 0, 4, 15.",
+              "text": "An implementation may support any or all of the following values for the 4-bit foo.ABC field: When foo.GHI is 0, legal values are 0, 4, 15. When foo.GHI is non-zero, legal values are 1, 2, 3.",
               "tag_filename": "/build/test-ch2-norm-tags.json",
               "stds_doc_url": "test-ch2.html"
             }
@@ -1622,6 +1624,8 @@
       "chapter_name": "Two",
       "category": "WLRL",
       "type": "Other",
+      "func-of-reg-name": "foo",
+      "func-of-field-name": "GHI",
       "impl-defs": [
         {
           "name": "QUX_QQQ_WLRL_OTHER",
diff --git a/tests/params/test-ch2.yaml b/tests/params/test-ch2.yaml
@@ -54,6 +54,7 @@ csr_definitions:
   - reg-name: foo
     field-name: ABC
     type: LegalEnum
+    func-of-field-name: GHI
     impl-def: FOO_ABC_WARL_ENUM
 
   # Case 2: CSR field with width specified by a named parameter's value.
@@ -70,7 +71,10 @@ csr_definitions:
     impl-def: ZORT_XYZ_WLRL_RO_MASK
 
   # Case 4: CSR field that doesn't match any of the above cases.
+  # Also test func-of relationship to a field in a different register.
   - reg-name: qux
     field-name: QQQ
+    func-of-reg-name: foo
+    func-of-field-name: GHI
     type: Other
     impl-def: QUX_QQQ_WLRL_OTHER
diff --git a/tools/README.md b/tools/README.md
@@ -174,15 +174,27 @@ CSR Definition Encoding:
   - At least one referenced normative rule must provide `impl-def-category`.
   - Any provided `impl-def-category` values across referenced impl-defs must agree.
   - The category is mapped into CSR category (`WARL`/`WLRL`) for output grouping.
+- If CSR/field type values are a function of another CSR/field:
+  - `func-of-reg-name`: Name of other CSR register (can be omitted if same CSR as this one)
+  - `func-of-field-name`: Name of other CSR field (can be omitted if entire CSR value)
+- In HTML and AsciiDoc output, the `Type` column adds `func-of: <reg>[.<field>]` on a new line when either of these properties is present.
 
 Examples:
 ```yaml
-# Implementation's config file provides legal values and behavior when writing illegal values
+# Implementation supports a list of legal values (specified in config file)
 - reg-name: mtvec
   field-name: MODE
   impl-def: MTVEC_MODE_WARL
   type: LegalEnum
 
+# Implementation has field legal values a function of another field (specified in config file)
+- reg-name: mtvec
+  field-name: BASE
+  impl-def: MTVEC_BASE_WARL
+  type: LegalEnum
+  func-of-reg-name: mtvec
+  func-of-field-name: MODE
+
 # Width-based CSR field (VarWidth parameter name provided by `width-parameter` property)
 - reg-name: satp
   field-name: ASID
diff --git a/tools/create_csr_appendix.py b/tools/create_csr_appendix.py
@@ -233,6 +233,35 @@ def render_type_cell(csr: Dict[str, Any]) -> str:
         if isinstance(width_parameter, str) and width_parameter:
             type_display = f"VarWidth = {width_parameter}"
 
+    func_of_reg_name = csr.get("func-of-reg-name")
+    func_of_field_name = csr.get("func-of-field-name")
+    if (
+        isinstance(func_of_reg_name, str)
+        and func_of_reg_name
+    ) or (
+        isinstance(func_of_field_name, str)
+        and func_of_field_name
+    ):
+        # Determine the base register name for func-of:
+        # 1. Prefer an explicit func-of-reg-name if provided.
+        # 2. Otherwise, when only func-of-field-name is given, default to this CSR's reg-name.
+        base_reg_name: str = ""
+        if isinstance(func_of_reg_name, str) and func_of_reg_name:
+            base_reg_name = func_of_reg_name
+        elif isinstance(func_of_field_name, str) and func_of_field_name:
+            reg_name = csr.get("reg-name")
+            if isinstance(reg_name, str) and reg_name:
+                base_reg_name = reg_name
+
+        func_of_target = base_reg_name
+        if isinstance(func_of_field_name, str) and func_of_field_name:
+            if func_of_target:
+                func_of_target = f"{func_of_target}.{func_of_field_name}"
+            else:
+                # No usable register name; fall back to just the field name.
+                func_of_target = func_of_field_name
+        return f"a| {type_display} +\nfunc-of: {func_of_target}"
+
     return f"| {type_display}"
 
 
diff --git a/tools/create_params.py b/tools/create_params.py
@@ -483,6 +483,8 @@ def add_csr_entries(
     """Expand one CSR definition entry into one or more output CSR objects."""
     raw_csr_type = entry.get("type")
     raw_parameter_name = entry.get("width-parameter")
+    raw_func_of_reg_name = entry.get("func-of-reg-name")
+    raw_func_of_field_name = entry.get("func-of-field-name")
 
     if not isinstance(raw_csr_type, str):
         fatal(f"Found CSR entry with missing or non-string type in {def_filename}")
@@ -500,6 +502,18 @@ def add_csr_entries(
             fatal(f"Found CSR entry with non-string width-parameter in {def_filename}")
         parameter_name = raw_parameter_name
 
+    func_of_reg_name: Optional[str] = None
+    if raw_func_of_reg_name is not None:
+        if not isinstance(raw_func_of_reg_name, str):
+            fatal(f"Found CSR entry with non-string func-of-reg-name in {def_filename}")
+        func_of_reg_name = raw_func_of_reg_name
+
+    func_of_field_name: Optional[str] = None
+    if raw_func_of_field_name is not None:
+        if not isinstance(raw_func_of_field_name, str):
+            fatal(f"Found CSR entry with non-string func-of-field-name in {def_filename}")
+        func_of_field_name = raw_func_of_field_name
+
     if csr_type == "VarWidth":
         if parameter_name is None:
             fatal(
@@ -621,6 +635,13 @@ def csr_id(field_name: Optional[str] = None) -> str:
 
         if parameter_name is not None:
             out_entry["width-parameter"] = parameter_name
+        effective_func_of_reg_name = func_of_reg_name
+        if effective_func_of_reg_name is None and func_of_field_name is not None:
+            effective_func_of_reg_name = name
+        if effective_func_of_reg_name is not None:
+            out_entry["func-of-reg-name"] = effective_func_of_reg_name
+        if func_of_field_name is not None:
+            out_entry["func-of-field-name"] = func_of_field_name
 
         note = entry.get("note")
         if note is not None:
@@ -1208,6 +1229,30 @@ def html_csr_table_row(f, csr: Dict[str, Any], chapter_name: Optional[str]):
         if isinstance(width_param, str) and width_param:
             type_display = f"VarWidth = {width_param}"
 
+    func_of_reg_name = csr.get("func-of-reg-name")
+    func_of_field_name = csr.get("func-of-field-name")
+    if (
+        isinstance(func_of_reg_name, str)
+        and func_of_reg_name
+    ) or (
+        isinstance(func_of_field_name, str)
+        and func_of_field_name
+    ):
+        base_reg_name: str = ""
+        if isinstance(func_of_reg_name, str) and func_of_reg_name:
+            base_reg_name = func_of_reg_name
+        elif isinstance(func_of_field_name, str) and func_of_field_name:
+            if isinstance(reg_name, str) and reg_name:
+                base_reg_name = reg_name
+
+        func_of_target = base_reg_name
+        if isinstance(func_of_field_name, str) and func_of_field_name:
+            if func_of_target:
+                func_of_target = f"{func_of_target}.{func_of_field_name}"
+            else:
+                func_of_target = func_of_field_name
+        type_display = f"{type_display}<br>func-of: {func_of_target}"
+
     feature_csr = dict(csr)
     if isinstance(impl_defs_all, list):
         feature_csr["impl-defs"] = impl_defs

Original file line number	Diff line number	Diff line change
`@@ -1541,7 +1541,7 @@`
`1541`	`1541`	`{`
`1542`	`1542`	`"name": "norm:foo_abc_warl_enum",`
`1543`	`1543`	`"context": false,`
`1544`		`- "text": "An implementation may support any or all of the following values for the 4-bit foo.ABC field: 0, 4, 15.",`
	`1544`	`+ "text": "An implementation may support any or all of the following values for the 4-bit foo.ABC field: When foo.GHI is 0, legal values are 0, 4, 15. When foo.GHI is non-zero, legal values are 1, 2, 3.",`
`1545`	`1545`	`"tag_filename": "/build/test-ch2-norm-tags.json",`
`1546`	`1546`	`"stds_doc_url": "test-ch2.html"`
`1547`	`1547`	`}`