Make enum/width/ro-mask optional for CSRs since not all will work with one of these pre-fab schemes.

james-ball-qualcomm · james-ball-qualcomm · commit 6572f1dbf3ff · 2026-03-24T17:03:18.000-07:00
Signed-off-by: James Ball &lt;jameball@qti.qualcomm.com&gt;
diff --git a/schemas/param-defs-schema.json b/schemas/param-defs-schema.json
@@ -186,11 +186,13 @@
             }
           },
           {
-            "oneOf": [
-              { "required": ["enum"] },
-              { "required": ["width"] },
-              { "required": ["ro-mask"] }
-            ]
+            "not": {
+              "anyOf": [
+                { "required": ["enum", "width"] },
+                { "required": ["enum", "ro-mask"] },
+                { "required": ["width", "ro-mask"] }
+              ]
+            }
           },
           {
             "if": {
diff --git a/schemas/params-schema.json b/schemas/params-schema.json
@@ -174,35 +174,13 @@
             }
           },
           {
-            "oneOf": [
-              {
-                "required": ["enum"],
-                "not": {
-                  "anyOf": [
-                    { "required": ["width"] },
-                    { "required": ["ro-mask"] }
-                  ]
-                }
-              },
-              {
-                "required": ["width"],
-                "not": {
-                  "anyOf": [
-                    { "required": ["enum"] },
-                    { "required": ["ro-mask"] }
-                  ]
-                }
-              },
-              {
-                "required": ["ro-mask"],
-                "not": {
-                  "anyOf": [
-                    { "required": ["enum"] },
-                    { "required": ["width"] }
-                  ]
-                }
-              }
-            ]
+            "not": {
+              "anyOf": [
+                { "required": ["enum", "width"] },
+                { "required": ["enum", "ro-mask"] },
+                { "required": ["width", "ro-mask"] }
+              ]
+            }
           }
         ],
         "additionalProperties": false
diff --git a/tests/norm-rule/expected/test-ch2-norm-tags.json b/tests/norm-rule/expected/test-ch2-norm-tags.json
@@ -21,7 +21,8 @@
     "norm:foo_def_warl_enum": "The architecturally-defined values for the 8-bit foo.DEF\nCSR field are -1 or 0xf0.  Ignores writes with an illegal value.",
     "norm:foo_ghi_warl_width_uint4to8": "The foo.GHI CSR field width ranges from 4 to 8 bits as specified by the UINT_4TO8 parameter value.",
     "norm:zort_xyz_wlrl_readonly_zero": "An implementation may treat each bit of the zort.XYZ CSR as\nread-only or read-write. Read-only bits can be 0 or 1.",
-    "norm:bar_warl_readonly_value": "An implementation may treat each bit of the bar CSR as\nread-only or read-write. Read-only bits are 0."
+    "norm:bar_warl_readonly_value": "An implementation may treat each bit of the bar CSR as\nread-only or read-write. Read-only bits are 0.",
+    "norm:qux_qqq_wlrl_no_selector": "The qux.QQQ CSR field has implementation-defined behavior\nwithout an enum, width, or read-only mask selector."
   },
   "sections": {
     "title": "",
@@ -71,7 +72,8 @@
               "norm:foo_def_warl_enum",
               "norm:foo_ghi_warl_width_uint4to8",
               "norm:zort_xyz_wlrl_readonly_zero",
-              "norm:bar_warl_readonly_value"
+              "norm:bar_warl_readonly_value",
+              "norm:qux_qqq_wlrl_no_selector"
             ]
           }
         ],
diff --git a/tests/norm-rule/expected/test-norm-rules.html b/tests/norm-rule/expected/test-norm-rules.html
@@ -155,7 +155,7 @@ <h2>Implementation-Defined Behaviors</h2>
   </aside>
     <main>
       <style>.grand-total-heading { font-size: 24px; font-weight: bold; }</style>
-      <h1 class="grand-total-heading">95 Normative Rules: Includes 32 Implementation-Defined Behaviors (26 No Category, 5 WARL, 1 WLRL)</h1>
+      <h1 class="grand-total-heading">96 Normative Rules: Includes 33 Implementation-Defined Behaviors (26 No Category, 5 WARL, 2 WLRL)</h1>
 
       <section id="table-norm-rules-ch-1" class="section">
         <table>
@@ -821,7 +821,7 @@ <h1 class="grand-total-heading">95 Normative Rules: Includes 32 Implementation-D
 
       <section id="table-norm-rules-ch-2" class="section">
         <table>
-          <caption class="sticky-caption">Chapter Two: 21 Normative Rules: Includes 16 Implementation-Defined Behaviors (11 No Category, 4 WARL, 1 WLRL)</caption>
+          <caption class="sticky-caption">Chapter Two: 22 Normative Rules: Includes 17 Implementation-Defined Behaviors (11 No Category, 4 WARL, 2 WLRL)</caption>
           <colgroup>
             <col class="col-name">
             <col class="col-description">
@@ -1144,6 +1144,27 @@ <h1 class="grand-total-heading">95 Normative Rules: Includes 32 Implementation-D
               <td>An implementation may treat each bit of the zort.XYZ CSR as<br>read-only or read-write. Read-only bits can be 0 or 1.</td>
               <td><a href="test-ch2.html#norm:zort_xyz_wlrl_readonly_zero">norm:zort_xyz_wlrl_readonly_zero</a></td>
             </tr>
+            <tr>
+              <td rowspan=5 id="QUX_QQQ_WLRL_NO_SELECTOR">QUX_QQQ_WLRL_NO_SELECTOR</td>
+              <td>csr_field</td>
+              <td>Kind</td>
+            </tr>
+            <tr>
+              <td>qux.QQQ</td>
+              <td>Instance</td>
+            </tr>
+            <tr>
+              <td>Implementation-defined behavior</td>
+              <td>Implementation-defined behavior</td>
+            </tr>
+            <tr>
+              <td>WLRL</td>
+              <td>Implementation-defined behavior category</td>
+            </tr>
+            <tr>
+              <td>The qux.QQQ CSR field has implementation-defined behavior<br>without an enum, width, or read-only mask selector.</td>
+              <td><a href="test-ch2.html#norm:qux_qqq_wlrl_no_selector">norm:qux_qqq_wlrl_no_selector</a></td>
+            </tr>
           </tbody>
         </table>
       </section>
@@ -1573,7 +1594,7 @@ <h1 class="grand-total-heading">95 Normative Rules: Includes 32 Implementation-D
 
       <section id="table-impldefs-impl-cat-WLRL" class="section">
         <table>
-          <caption class="sticky-caption">WLRL Category (A-Z): All 1 Implementation-Defined Behaviors</caption>
+          <caption class="sticky-caption">WLRL Category (A-Z): All 2 Implementation-Defined Behaviors</caption>
           <colgroup>
             <col class="col-name">
             <col class="col-description">
@@ -1583,6 +1604,19 @@ <h1 class="grand-total-heading">95 Normative Rules: Includes 32 Implementation-D
             <tr><th>Name</th><th>Information</th><th>Information Source</th></tr>
           </thead>
           <tbody>
+            <tr>
+              <td rowspan=3><a href="#QUX_QQQ_WLRL_NO_SELECTOR">QUX_QQQ_WLRL_NO_SELECTOR</a></td>
+              <td>csr_field</td>
+              <td>Kind</td>
+            </tr>
+            <tr>
+              <td>qux.QQQ</td>
+              <td>Instance</td>
+            </tr>
+            <tr>
+              <td>The qux.QQQ CSR field has implementation-defined behavior<br>without an enum, width, or read-only mask selector.</td>
+              <td><a href="test-ch2.html#norm:qux_qqq_wlrl_no_selector">norm:qux_qqq_wlrl_no_selector</a></td>
+            </tr>
             <tr>
               <td rowspan=3><a href="#ZORT_XYZ_WLRL_READONLY_ZERO">ZORT_XYZ_WLRL_READONLY_ZERO</a></td>
               <td>csr_field</td>
@@ -1834,7 +1868,7 @@ <h1 class="grand-total-heading">95 Normative Rules: Includes 32 Implementation-D
 
       <section id="table-impldefs-ch-2" class="section">
         <table>
-          <caption class="sticky-caption">Chapter Two: All 16 Implementation-Defined Behaviors</caption>
+          <caption class="sticky-caption">Chapter Two: All 17 Implementation-Defined Behaviors</caption>
           <colgroup>
             <col class="col-name">
             <col class="col-description">
@@ -2056,6 +2090,23 @@ <h1 class="grand-total-heading">95 Normative Rules: Includes 32 Implementation-D
               <td>An implementation may treat each bit of the zort.XYZ CSR as<br>read-only or read-write. Read-only bits can be 0 or 1.</td>
               <td><a href="test-ch2.html#norm:zort_xyz_wlrl_readonly_zero">norm:zort_xyz_wlrl_readonly_zero</a></td>
             </tr>
+            <tr>
+              <td rowspan=4><a href="#QUX_QQQ_WLRL_NO_SELECTOR">QUX_QQQ_WLRL_NO_SELECTOR</a></td>
+              <td>csr_field</td>
+              <td>Kind</td>
+            </tr>
+            <tr>
+              <td>qux.QQQ</td>
+              <td>Instance</td>
+            </tr>
+            <tr>
+              <td>WLRL</td>
+              <td>Implementation-defined behavior category</td>
+            </tr>
+            <tr>
+              <td>The qux.QQQ CSR field has implementation-defined behavior<br>without an enum, width, or read-only mask selector.</td>
+              <td><a href="test-ch2.html#norm:qux_qqq_wlrl_no_selector">norm:qux_qqq_wlrl_no_selector</a></td>
+            </tr>
           </tbody>
         </table>
       </section>
diff --git a/tests/norm-rule/expected/test-norm-rules.json b/tests/norm-rule/expected/test-norm-rules.json
@@ -1622,6 +1622,26 @@
           "stds_doc_url": "test-ch2.html"
         }
       ]
+    },
+    {
+      "name": "QUX_QQQ_WLRL_NO_SELECTOR",
+      "def_filename": "tests/norm-rule/test-ch2.yaml",
+      "chapter_name": "Two",
+      "kind": "csr_field",
+      "impl-def-behavior": true,
+      "instances": [
+        "qux.QQQ"
+      ],
+      "impl-def-category": "WLRL",
+      "tags": [
+        {
+          "name": "norm:qux_qqq_wlrl_no_selector",
+          "context": false,
+          "text": "The qux.QQQ CSR field has implementation-defined behavior\nwithout an enum, width, or read-only mask selector.",
+          "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
@@ -95,3 +95,6 @@ read-only or read-write. Read-only bits can be 0 or 1.#
 
 [#norm:bar_warl_readonly_value]#An implementation may treat each bit of the `bar` CSR as
 read-only or read-write. Read-only bits are 0.#
+
+[#norm:qux_qqq_wlrl_no_selector]#The `qux.QQQ` CSR field has implementation-defined behavior
+without an enum, width, or read-only mask selector.#
diff --git a/tests/norm-rule/test-ch2.yaml b/tests/norm-rule/test-ch2.yaml
@@ -99,3 +99,9 @@ normative_rule_definitions:
     impl-def-category: WLRL
     kind: csr_field
     instance: zort.XYZ
+  - name: QUX_QQQ_WLRL_NO_SELECTOR
+    tag: "norm:qux_qqq_wlrl_no_selector"
+    impl-def-behavior: true
+    impl-def-category: WLRL
+    kind: csr_field
+    instance: qux.QQQ
diff --git a/tests/params/expected/test-params.html b/tests/params/expected/test-params.html
@@ -54,12 +54,12 @@ <h2 style="margin-top:24px">WARL/WLRL by Chapter</h2>
       <nav class="nav">
         <a href="#table-csrs-ch-1-warl" data-target="table-csrs-ch-1-warl">One WARL<span class="subtitle">1 entry</span></a>
         <a href="#table-csrs-ch-2-warl" data-target="table-csrs-ch-2-warl">Two WARL<span class="subtitle">4 entries</span></a>
-        <a href="#table-csrs-ch-2-wlrl" data-target="table-csrs-ch-2-wlrl">Two WLRL<span class="subtitle">1 entry</span></a>
+        <a href="#table-csrs-ch-2-wlrl" data-target="table-csrs-ch-2-wlrl">Two WLRL<span class="subtitle">2 entries</span></a>
       </nav>
     </aside>
     <main>
       <style>.grand-total-heading { font-size: 24px; font-weight: bold; }</style>
-      <h1 class="grand-total-heading">42 Parameters, 6 WARL/WLRL CSRs</h1>
+      <h1 class="grand-total-heading">42 Parameters, 7 WARL/WLRL CSRs</h1>
 
       <section id="table-params-ch-1" class="section">
         <table>
@@ -449,7 +449,7 @@ <h1 class="grand-total-heading">42 Parameters, 6 WARL/WLRL CSRs</h1>
 
       <section id="table-csrs-ch-2-wlrl" class="section">
         <table>
-          <caption class="sticky-caption">Chapter Two WLRL: 1 CSR</caption>
+          <caption class="sticky-caption">Chapter Two WLRL: 2 CSRs</caption>
           <colgroup>
             <col class="col-name">
             <col class="col-type">
@@ -466,6 +466,12 @@ <h1 class="grand-total-heading">42 Parameters, 6 WARL/WLRL CSRs</h1>
               <td rowspan=1>FLD:zort.XYZ</td>
               <td><a href="test-ch2.html#norm:zort_xyz_wlrl_readonly_zero">An implementation may treat each bit of the zort.XYZ CSR as<br>read-only or read-write. Read-only bits can be 0 or 1.</a></td>
             </tr>
+            <tr>
+              <td rowspan=1 id="qux.QQQ">qux.QQQ</td>
+              <td rowspan=1>WLRL</td>
+              <td rowspan=1>FLD:qux.QQQ</td>
+              <td><a href="test-ch2.html#norm:qux_qqq_wlrl_no_selector">The qux.QQQ CSR field has implementation-defined behavior<br>without an enum, width, or read-only mask selector.</a></td>
+            </tr>
           </tbody>
         </table>
       </section>
diff --git a/tests/params/expected/test-params.json b/tests/params/expected/test-params.json
@@ -1685,6 +1685,35 @@
           ]
         }
       ]
+    },
+    {
+      "reg-name": "qux",
+      "field-name": "QQQ",
+      "def_filename": "test-ch2.yaml",
+      "chapter_name": "Two",
+      "category": "WLRL",
+      "impl-defs": [
+        {
+          "name": "QUX_QQQ_WLRL_NO_SELECTOR",
+          "def_filename": "tests/norm-rule/test-ch2.yaml",
+          "chapter_name": "Two",
+          "kind": "csr_field",
+          "impl-def-behavior": true,
+          "instances": [
+            "qux.QQQ"
+          ],
+          "impl-def-category": "WLRL",
+          "tags": [
+            {
+              "name": "norm:qux_qqq_wlrl_no_selector",
+              "context": false,
+              "text": "The qux.QQQ CSR field has implementation-defined behavior\nwithout an enum, width, or read-only mask selector.",
+              "tag_filename": "/build/test-ch2-norm-tags.json",
+              "stds_doc_url": "test-ch2.html"
+            }
+          ]
+        }
+      ]
     }
   ]
 }
diff --git a/tests/params/test-ch2.yaml b/tests/params/test-ch2.yaml
@@ -90,3 +90,8 @@ csr_definitions:
     field-name: XYZ
     impl-def: ZORT_XYZ_WLRL_READONLY_ZERO
     ro-mask: 0b1111
+
+  # Case 4: CSR field with no selector property (enum/width/ro-mask all omitted).
+  - reg-name: qux
+    field-name: QQQ
+    impl-def: QUX_QQQ_WLRL_NO_SELECTOR
diff --git a/tools/README.md b/tools/README.md
@@ -186,7 +186,7 @@ Examples:
 
 CSR Definition Encoding:
 - Use `csr_definitions` entries for CSRs, with `reg-name` (single CSR) or `reg-names` (multiple CSRs).
-- A CSR entry must include exactly one selector property:
+- CSR selector properties are optional. If provided, use at most one of:
   - `enum`
   - `width`
   - `ro-mask`
diff --git a/tools/create_params.py b/tools/create_params.py
@@ -593,9 +593,9 @@ def parse_multibase_int(value: Any, label: str, csr_name: str) -> int:
     has_read_only_value = "ro-value" in entry
 
     selector_count = int(has_enum) + int(has_width) + int(has_read_only_mask)
-    if selector_count != 1:
+    if selector_count > 1:
         fatal(
-            f"Found CSR entry in {def_filename} that must define exactly one of "
+            f"Found CSR entry in {def_filename} that cannot define more than one of "
             "'enum', 'width', or 'ro-mask'"
         )
     if has_read_only_value and not has_read_only_mask:

Original file line number	Diff line number	Diff line change
`@@ -186,11 +186,13 @@`
`186`	`186`	`}`
`187`	`187`	`},`
`188`	`188`	`{`
`189`		`- "oneOf": [`
`190`		`- { "required": ["enum"] },`
`191`		`- { "required": ["width"] },`
`192`		`- { "required": ["ro-mask"] }`
`193`		`- ]`
	`189`	`+ "not": {`
	`190`	`+ "anyOf": [`
	`191`	`+ { "required": ["enum", "width"] },`
	`192`	`+ { "required": ["enum", "ro-mask"] },`
	`193`	`+ { "required": ["width", "ro-mask"] }`
	`194`	`+ ]`
	`195`	`+ }`
`194`	`196`	`},`
`195`	`197`	`{`
`196`	`198`	`"if": {`
Original file line number	Diff line number	Diff line change
`@@ -1622,6 +1622,26 @@`
`1622`	`1622`	`"stds_doc_url": "test-ch2.html"`
`1623`	`1623`	`}`
`1624`	`1624`	`]`
	`1625`	`+ },`
	`1626`	`+ {`
	`1627`	`+ "name": "QUX_QQQ_WLRL_NO_SELECTOR",`
	`1628`	`+ "def_filename": "tests/norm-rule/test-ch2.yaml",`
	`1629`	`+ "chapter_name": "Two",`
	`1630`	`+ "kind": "csr_field",`
	`1631`	`+ "impl-def-behavior": true,`
	`1632`	`+ "instances": [`
	`1633`	`+ "qux.QQQ"`
	`1634`	`+ ],`
	`1635`	`+ "impl-def-category": "WLRL",`
	`1636`	`+ "tags": [`
	`1637`	`+ {`
	`1638`	`+ "name": "norm:qux_qqq_wlrl_no_selector",`
	`1639`	`+ "context": false,`
	`1640`	`+ "text": "The qux.QQQ CSR field has implementation-defined behavior\nwithout an enum, width, or read-only mask selector.",`
	`1641`	`+ "tag_filename": "/build/test-ch2-norm-tags.json",`
	`1642`	`+ "stds_doc_url": "test-ch2.html"`
	`1643`	`+ }`
	`1644`	`+ ]`
`1625`	`1645`	`}`
`1626`	`1646`	`]`
`1627`	`1647`	`}`