Merge pull request #297 from ShashankVM/main

Update IDL doc

Author: dhower-qc

arch/isa/fp.idl

@@ -416,27 +416,6 @@ function softfloat_normSubnormalF16Sig {
   }
 }
 
-function softfloat_normRoundPackToF32 {
-  returns Bits<32>
-  arguments
-    Bits<1> sign,
-    Bits<8> exp,
-    Bits<23> sig,
-    RoundingMode mode
-  description {
-    Normalize, round, and pack into a 32-bit floating point value
-  }
-  body {
-    Bits<8> shiftDist = count_leading_zeros<32>(sig) - 1;
-    exp = exp - shiftDist;
-    if ((7 <= shiftDist) && (exp < 0xFD)) {
-      return packToF32UI(sign, (sig != 0) ? exp : 0, sig << (shiftDist - 7));
-    } else {
-      return softfloat_roundPackToF32(sign, exp, sig << shiftDist, mode);
-    }
-  }
-}
-
 function softfloat_roundPackToF32 {
   returns Bits<32>     # single precision value
   arguments
@@ -485,3 +464,24 @@ function softfloat_roundPackToF32 {
     return packToF32UI(sign, exp, sig);
   }
 }
+
+function softfloat_normRoundPackToF32 {
+  returns Bits<32>
+  arguments
+    Bits<1> sign,
+    Bits<8> exp,
+    Bits<23> sig,
+    RoundingMode mode
+  description {
+    Normalize, round, and pack into a 32-bit floating point value
+  }
+  body {
+    Bits<8> shiftDist = count_leading_zeros<32>(sig) - 1;
+    exp = exp - shiftDist;
+    if ((7 <= shiftDist) && (exp < 0xFD)) {
+      return packToF32UI(sign, (sig != 0) ? exp : 0, sig << (shiftDist - 7));
+    } else {
+      return softfloat_roundPackToF32(sign, exp, sig << shiftDist, mode);
+    }
+  }
+}

arch/prose/idl.adoc

@@ -161,7 +161,7 @@ All strings must be compile-time-known values.
 
 === Composite Types
 
-IDL also supports three composite types: enumerations, bitfields, and arrays.
+IDL also supports four composite types: enumerations, bitfields, structs, and arrays.
 
 ==== Enumerations
 
@@ -240,6 +240,24 @@ Sv39PageTableEntry pte = pte_data;
 Bits<2> pbmt = pte.PBMT;
 ----
 
+==== Structs
+
+A struct is a collection of unrelated types, similar to a `struct` in C/C++ or Verilog. Structs are declared using the `struct` keyword. Struct names must begin with a capital letter. Struct members can begin with either lowercase or uppercase; in the former, the member is mutable and in the former the member is const. Struct members may be any type, including other structs.
+
+Struct declarations do _not_ need to be followed by a semicolon (as they are in C/C++).
+
+.example Struct
+[source,idl]
+----
+struct TranslationResult {
+  Bits<PHYS_ADDR_WIDTH> paddr; # a bit vector
+  Pbmt pbmt;                   # an enum
+  PteFlags pte_flags;          # another enum
+}
+----
+
+Structs can be the return value of a function. Structs, like every other variable in IDL, are always passed-by-value.
+
 ==== Arrays
 
 Fixed-size arrays of other data types may also be created in IDL. The size of the array must be known at compile time (_i.e._, there are no unbounded arrays like in C/C++).
@@ -592,7 +610,7 @@ Bitfields can be converted to a `Bits<N>` type, where N is the width of the bitf
 
 == Casting
 
-There are two explicit cast operators in IDL: `$isigned` and `$bits`.
+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.
 
@@ -630,6 +648,55 @@ $bits(CSR[mstatus])  # => XLEN'd??
 $bits(Sv39PageTableEntry) # => 64'd??
 ----
 
+The `$enum` cast will convert a `Bits<N>` type into an enum.
+
+[source,idl]
+----
+$enum(RoundingMode, 1'b1)  # => RoundingMode::RTZ
+----
+
+The `$enum_to_a` cast will convert an enumeration type into an array of the enumeration values. The values will in the declaration order of the enum members.
+
+[source,idl]
+----
+$enum_to_a(RoundingMode)  # => [0, 1, 2, 3, 4]
+----
+
+== Builtins
+
+IDL provides a several builtins to access implicit machine state or query data structure properties.
+
+=== Implicit Machine State
+
+The current program counter (virtual address of the instruction being executed) is available in `$pc` in Instruction and CSR scope. `$pc` is not available in function scope or global scope.
+
+The current instruction encoding (of the instruction being executed) is available in `$encoding` in Instruction and CSR scope. `$encoding` is not available in function scope or global scope.
+
+=== Data Type Queries
+
+The size (number of members) of an enum can be found with `$enum_size`.
+
+[source,idl]
+----
+$enum_size(RoundingMode) # => 5
+----
+
+The size of an enum element (the number of bits needed to represent the largest enum value) can be
+found with `$enum_element_size`.
+
+[source,idl]
+----
+$enum_element_size(RoundingMode) # => 3
+----
+
+The size (number of elements) of an array can be found with `$array_size`.
+
+[source,idl]
+----
+Bits<32> array [13];
+$array_size(array) # => 13
+----
+
 == Control flow
 
 IDL provides if/else and for loops for control flow.
@@ -926,22 +993,3 @@ mstatus:
       reset_value(): |
         return (M_MODE_ENDIANESS == "big") ? 1 : 0;
 ----
-
-== Compilation order
-
-The order of declaration is important in IDL (like C/C++, unlike Verilog). A variable, constant, or function must be declared *before* it is used.
-
-.Compilation order
-[source,idl]
-----
-function mod {
-  ...
-  body {
-    # (-, remainder) = divmod(value); # compilation error: divmod not defined
-    # return remainder;
-  }
-}
-
-function divmod { ... }
-
-----