feat(idl): add widening operators in IDL (#736)

dhower-qc · web-flow · commit 5291a501e49e · 2025-05-06T18:50:29.000Z
Adds four widening `Bits&lt;N&gt;` operators in IDL:

* `` `&lt;&lt; `` : widening shift left. If the shift amount is a constant,
the result is `Bits&lt;N + shamt&gt;`. Otherwise, the result type is
`Bits&lt;Infinite&gt;`.
* `` `* ``: widening multiply. The result type when multiplying
`Bits&lt;N&gt;` * `Bits&lt;M&gt;` is `Bits&lt;N + M&gt;`
* `` `+ ``: widening add. The result type when adding `Bits&lt;N&gt;` +
`Bits&lt;M&gt;` is `Bits&lt;max(M, N) + 1&gt;`
* `` `- ``: widening sub. The result type when subtracting `Bits&lt;N&gt; +
Bits&lt;M&gt;` is `Bits&lt;max(M, N) + 1&gt;`.
diff --git a/arch/csr/H/vsatp.yaml b/arch/csr/H/vsatp.yaml
@@ -98,8 +98,8 @@ fields:
         }
       } else {
         XReg shamt = ((xlen() == 32) || (CSR[mstatus].SXL == $bits(XRegWidth::XLEN32))) ? 9 : 16;
-        XReg all_ones = ((1 << shamt) - 1);
-        XReg largest_allowed_asid = (1 << shamt) - 1;
+        XReg all_ones = ((MXLEN'1 << shamt) - 1);
+        XReg largest_allowed_asid = (MXLEN'1 << shamt) - 1;
 
         if (csr_value.ASID == all_ones) {
           # the specification states that if all 1's are written to the ASID field, then
diff --git a/arch/csr/satp.yaml b/arch/csr/satp.yaml
@@ -125,8 +125,8 @@ fields:
         }
       } else {
         XReg shamt = (xlen() == 32 || (CSR[mstatus].SXL == $bits(XRegWidth::XLEN32))) ? 9 : 16;
-        XReg all_ones = ((1 << shamt) - 1);
-        XReg largest_allowed_asid = (1 << shamt) - 1;
+        XReg all_ones = ((MXLEN'1 << shamt) - 1);
+        XReg largest_allowed_asid = (MXLEN'1 << shamt) - 1;
 
         if (csr_value.ASID == all_ones) {
           # the specification states that if all 1's are written to the ASID field, then
diff --git a/arch/inst/F/fclass.s.yaml b/arch/inst/F/fclass.s.yaml
@@ -54,24 +54,24 @@ operation(): |
   if (is_sp_neg_inf?(sp_value)) {
     X[rd] = 1 << 0;
   } else if (is_sp_neg_norm?(sp_value)) {
-    X[rd] = 1 << 1;
+    X[rd] = 1 `<< 1;
   } else if (is_sp_neg_subnorm?(sp_value)) {
-    X[rd] = 1 << 2;
+    X[rd] = 1 `<< 2;
   } else if (is_sp_neg_zero?(sp_value)) {
-    X[rd] = 1 << 3;
+    X[rd] = 1 `<< 3;
   } else if (is_sp_pos_zero?(sp_value)) {
-    X[rd] = 1 << 4;
+    X[rd] = 1 `<< 4;
   } else if (is_sp_pos_subnorm?(sp_value)) {
-    X[rd] = 1 << 5;
+    X[rd] = 1 `<< 5;
   } else if (is_sp_pos_norm?(sp_value)) {
-    X[rd] = 1 << 6;
+    X[rd] = 1 `<< 6;
   } else if (is_sp_pos_inf?(sp_value)) {
-    X[rd] = 1 << 7;
+    X[rd] = 1 `<< 7;
   } else if (is_sp_signaling_nan?(sp_value)) {
-    X[rd] = 1 << 8;
+    X[rd] = 1 `<< 8;
   } else {
     assert(is_sp_quiet_nan?(sp_value), "Unexpected SP value");
-    X[rd] = 1 << 9;
+    X[rd] = 1 `<< 9;
   }
 
 # SPDX-SnippetBegin
diff --git a/arch/inst/M/mulh.yaml b/arch/inst/M/mulh.yaml
@@ -41,10 +41,10 @@ operation(): |
 
   # enlarge and sign extend the sources
   Bits<1> rs1_sign_bit = X[rs1][xlen()-1];
-  Bits<MXLEN*2> src1 = {{xlen(){rs1_sign_bit}}, X[rs1]};
+  Bits<MXLEN `* 2> src1 = {{xlen(){rs1_sign_bit}}, X[rs1]};
 
   Bits<1> rs2_sign_bit = X[rs2][xlen()-1];
-  Bits<MXLEN*2> src2 = {{xlen(){rs2_sign_bit}}, X[rs2]};
+  Bits<MXLEN `* 2> src2 = {{xlen(){rs2_sign_bit}}, X[rs2]};
 
   # grab the high half of the result, and put it in rd
   X[rd] = (src1 * src2)[(xlen()*8'd2)-1:xlen()];
diff --git a/arch/isa/globals.isa b/arch/isa/globals.isa
@@ -314,15 +314,15 @@ function exception_handling_mode {
       # mode is M, the value of medeleg is irrelevant
       return PrivilegeMode::M;
     } else if (implemented?(ExtensionName::S) && ((mode() == PrivilegeMode::HS) || (mode() == PrivilegeMode::U))) {
-      if (($bits(CSR[medeleg]) & (1 << $bits(exception_code))) != 0) {
+      if (($bits(CSR[medeleg]) & (MXLEN'1 << $bits(exception_code))) != 0) {
         return PrivilegeMode::HS;
       } else {
         return PrivilegeMode::M;
       }
     } else {
       assert(implemented?(ExtensionName::H) && ((mode() == PrivilegeMode::VS) || (mode() == PrivilegeMode::VU)), "Unexpected mode");
-      if (($bits(CSR[medeleg]) &  (1 << $bits(exception_code))) != 0) {
-        if (($bits(CSR[hedeleg]) & (1 << $bits(exception_code))) != 0) {
+      if (($bits(CSR[medeleg]) &  (MXLEN'1 << $bits(exception_code))) != 0) {
+        if (($bits(CSR[hedeleg]) & (MXLEN'1 << $bits(exception_code))) != 0) {
           return PrivilegeMode::VS;
         } else {
           return PrivilegeMode::HS;
@@ -830,7 +830,7 @@ function valid_interrupt_code? {
     Returns true if _code_ is a legal interrupt number.
   }
   body {
-    if (code > ((1 << $enum_element_size(InterruptCode)) - 1)) {
+    if (code > ((1 `<< $enum_element_size(InterruptCode)) - 1)) {
       # code is too large
       return false;
     }
@@ -849,7 +849,7 @@ function valid_exception_code? {
     Returns true if _code_ is a legal exception number.
   }
   body {
-    if (code > ((1 << $enum_element_size(ExceptionCode)) - 1)) {
+    if (code > ((1 `<< $enum_element_size(ExceptionCode)) - 1)) {
       # code is too large
       return false;
     }
@@ -2083,7 +2083,7 @@ function stage1_page_walk {
     }
 
     for (U32 i = (LEVELS - 1); i >= 0; i--) {
-      U32 vpn = (vaddr >> (12 + VPN_SIZE*i)) & ((1 << VPN_SIZE) - 1);
+      U32 vpn = (vaddr >> (12 + VPN_SIZE*i)) & ((1 `<< VPN_SIZE) - 1);
 
       Bits<PA_SIZE> pte_gpaddr = (ppn << 12) + (vpn * (PTESIZE/8));
 
diff --git a/backends/cpp_hart_gen/lib/gen_cpp.rb b/backends/cpp_hart_gen/lib/gen_cpp.rb
@@ -599,16 +599,20 @@ class BinaryExpressionAst
     def gen_cpp(symtab, indent = 0, indent_spaces: 2)
       if op == ">>>"
         "#{' '*indent}(#{lhs.gen_cpp(symtab, 0, indent_spaces:)}.sra(#{rhs.gen_cpp(symtab, 0, indent_spaces:)}))"
-      elsif op == "<<"
+      elsif op == "`<<"
         if rhs.constexpr?(symtab)
           # use template form of shift
           "#{' '*indent}(#{lhs.gen_cpp(symtab, 0, indent_spaces:)}.template sll<#{rhs.value(symtab)}>())"
-        elsif rhs.type(symtab).const?
+        else
           # use widening shift
           "#{' '*indent}(#{lhs.gen_cpp(symtab, 0, indent_spaces:)}.widening_sll(#{rhs.gen_cpp(symtab, 0, indent_spaces:)}))"
-        else
-        "#{' '*indent}(#{lhs.gen_cpp(symtab, 0, indent_spaces:)} << #{rhs.gen_cpp(symtab, 0, indent_spaces:)})"
         end
+      elsif op == "`+"
+        "#{' '*indent}(#{lhs.gen_cpp(symtab, 0, indent_spaces:)}.widening_add(#{rhs.gen_cpp(symtab, 0, indent_spaces:)}))"
+      elsif op == "`-"
+        "#{' '*indent}(#{lhs.gen_cpp(symtab, 0, indent_spaces:)}.widening_sub(#{rhs.gen_cpp(symtab, 0, indent_spaces:)}))"
+      elsif op == "`*"
+        "#{' '*indent}(#{lhs.gen_cpp(symtab, 0, indent_spaces:)}.widening_mul(#{rhs.gen_cpp(symtab, 0, indent_spaces:)}))"
       else
         "#{' '*indent}(#{lhs.gen_cpp(symtab, 0, indent_spaces:)} #{op} #{rhs.gen_cpp(symtab, 0, indent_spaces:)})"
       end
diff --git a/doc/idl.adoc b/doc/idl.adoc
@@ -414,6 +414,7 @@ Binary operators between operands of different bit widths will extend the smalle
 
 The result of a binary operation is signed if both operands are signed; otherwise, the result is unsigned.
 
+[#operators]
 .IDL operators in precedence order, with 0 being highest. For an operand `i` (which may be an expression), `L(i)` is the number of bits in `i` and `typeof(i)` is the exact type of `i`
 [cols="1,2,3,4"]
 |===
@@ -445,9 +446,11 @@ The result of a binary operation is signed if both operands are signed; otherwis
                                                            `i` must be a `Bits<N>` type. +
                                                            N must be a literal or compile-time constant.
 
-.3+| 6          | `i * j`    | `Bits<max(L(i), L(j))>`   | Multiply `i` times `j`. +
+.4+| 6          | `i * j`    | `Bits<max(L(i), L(j))>`   | Multiply `i` times `j`. +
                                                            The result is the same width as the widest operand. +
-                                                           The upper half of the multiplication result is discarded (if the upper half is needed, the operands can be widened ahead of the multiplication).
+                                                           The upper half of the multiplication result is discarded.
+
+                | `i \`* j`  | `Bits<L(i) + L(j)>`   | Widening multiply `i` times `j`.
 
                 | `i / j`    | `Bits<max(L(i), L(j))>`   | Divide `i` by `j`. +
                                                            The result is the same width as the widest operand. +
@@ -461,25 +464,22 @@ The result of a binary operation is signed if both operands are signed; otherwis
                                                            Division by zero is undefined, and must be avoided.
                                                            When `i` and `j` are signed, signed overflow is undefined, and must be avoided.
 
-.2+| 7          | `i + j`    | `Bits<max(L(i), L(j))>`   | Addition +
+.4+| 7          | `i + j`    | `Bits<max(L(i), L(j))>`   | Addition +
                                                            The carry bit is discarded. +
                                                            If the carry bit is needed, the operands can be widened prior to addition.
 
+                | `i \`+ j`    | `Bits<max(L(i), L(j)) + 1>`   | Widening Addition
+
                 | `i - j`    | `Bits<max(L(i), L(j))>`   | Subtraction +
                                                            The carry bit is discarded. +
                                                            If the carry bit is needed, the operands can be widened prior to subtraction.
 
-.3+| 8          | `i << j`   a|
-[%autowidth]
-!===
-! When ! Then
-! `j` is literal  ! `Bits<L(i) + j>`
-! `j` is variable ! `typeof(i)`
-!===
-                                                           | Left logical shift. +
-                                                             When the shift amount is known at compile time, the result is widened to not lose any data. +
-                                                             When the shift amount is not known at compile time, the shifted bits are discarded.
+                | `i \`- j`    | `Bits<max(L(i), L(j)) + 1>`   | Widening Subtraction
 
+.4+| 8          | `i << j`   | `typeof(i)` | Left logical shift
+                | `i \`<< j`   | `Bits<L(i) + value(j)>`   | Widening left logic shift. +
+                                                             `j` *must* be known at compile time -- +
+                                                             otherwise, this is a type error
                 | `i >> j`   | `typeof(i)`                 | Right logical shift.
                 | `i >>> j`  | `typeof(i)`                 | Right arithmetic shift.
 
@@ -607,6 +607,8 @@ Bitfields can be converted to a `Bits<N>` type, where N is the width of the bitf
 
 == Casting
 
+=== Explicit casting
+
 There are four explicit cast operators in IDL: `$signed`, `$bits`, `$enum`, and `$enum_to_a`.
 
 Unsigned Bits<N> values may be cast to signed values using the `$signed` cast operator.
@@ -622,7 +624,7 @@ XReg cmp1 = ($signed(src1) < $signed(src2)) ? 1 : 0;  # cmp = 1
 
 The '$bits' cast can convert Enumeration references, Bitfields, and CSRs into a Bits<N> type.
 When the casted value is an enumeration reference, the resulting type will be large enough to hold the largest value in the enumeration type, regardless of the specific reference value.
-When the casted value is a CSR, the resulting type will the width of the CSR, or the maximum width when a CSR width is dynamic.
+When the casted value is a CSR, the resulting type will the width of the CSR, or the maximum width when a CSR width is dynamic (changable at runtime).
 When the casted value is a bitfield, the resulting type will be the width of the bitfield.
 
 [source,idl]
@@ -659,6 +661,30 @@ The `$enum_to_a` cast will convert an enumeration type into an array of the enum
 $enum_to_a(RoundingMode)  # => [0, 1, 2, 3, 4]
 ----
 
+=== Implicit casting
+
+Operations involving Bits<N> type with different N involve an implicit cast to the larger bitwidth according to xref:operators[xrefstyle=short].
+
+When the Bits<N> type is unsigned, it zero-extends to the larger width.
+
+When the Bits<N> type is signed, it sign-extends to the larger width.
+
+[source,idl]
+----
+
+Bits<4> a = 1;
+Bits<2> b = 3;
+
+Bits<4> c = a | b;           # c = 3
+Bits<4> d = a | $signed(b);  # d = 0xf
+
+Bits<4> e = a + b;           # e = 4
+Bits<4> f = a + $signed(b);  # f = 0
+
+Bits<4> g = $signed(a) | b;  # g = 3
+
+----
+
 == Builtins
 
 IDL provides a several builtins to access implicit machine state or query data structure properties.
diff --git a/lib/idl/ast.rb b/lib/idl/ast.rb
diff --git a/lib/idl/idl.treetop b/lib/idl/idl.treetop
diff --git a/lib/idl/passes/gen_adoc.rb b/lib/idl/passes/gen_adoc.rb
