P-1 Floating

.github/workflows/general.yml

@@ -67,6 +67,9 @@ jobs:
       - name: Check project documentation
         run: tool/gh_actions/generate_documentation.sh
 
+      - name: Install Icarus Verilog
+        run: sudo apt-get update && sudo apt-get install -y iverilog
+
       - name: Run root package tests
         run: tool/gh_actions/run_tests.sh
 

CHANGELOG.md

@@ -57,6 +57,115 @@
 - Updated GitHub workflows to Node.js 24 (<https://github.com/intel/rohd-hcl/pull/288>).
 - Updated compatibility to ROHD 0.6.11 and set the Dart SDK range to `^3.6.0`.
 
+## Unreleased
+
+### Breaking Changes
+
+- `FloatingPointSqrtSimple` now rejects explicit-J-bit inputs. Use an implicit-J-bit format or normalize the input before connecting it to the square-root component.
+- Explicit-J-bit NaN construction now requires at least one payload bit in addition to the J bit. Formats with a one-bit explicit mantissa are rejected because they cannot encode a quiet-NaN payload.
+- Automatic definition names for `MultiplyAccumulate`, `CompressionTreeMultiplyAccumulate`, and `GenericMultiplyAccumulate` now include the effective `outputWidth`. Consumers that reference generated HDL definition names must update those names; explicitly supplied `definitionName` values are unchanged.
+- Automatic `FixedToFloat` definition names now include `roundingMode` so converters with different rounding logic cannot share an HDL definition.
+- Automatic `FloatingPointAdderSinglePath` definition names now include `roundingMode` for the same reason.
+- Automatic `FloatingPointConverter`, `FloatingPointSqrt`, and `FloatingPointSqrtSimple` definition names now include `roundingMode`. Consumers that reference generated HDL definition names must update those names; explicitly supplied `definitionName` values are unchanged.
+- Automatic `DotProduct`, `CompressionTreeDotProduct`, and `GeneralDotProduct` definition names now include lane count, operand widths, radix, implementation identity, and signedness. Consumers that reference generated HDL definition names must update those names; explicitly supplied `definitionName` values are unchanged.
+
+### Deprecated APIs
+
+- Deprecated the unsigned-default `FixedPointValue` constructor and `FixedPointValue.populator` while preserving their existing behavior. Use `FixedPointValue.withSignedness` and `FixedPointValue.populatorWithSignedness`, which default to `signed: true` to match `FixedPoint` (<https://github.com/intel/rohd-hcl/issues/249>).
+- Deprecated `FixedPoint.operator *` while preserving its previous unsigned result width and behavior. Use `FixedPoint.multiply` for a correctly signed, full-width product.
+- Deprecated the `static_or_runtime_parameter.dart` import path. Import `static_or_runtime_control.dart` instead.
+- Deprecated the `subtractIn` constructor parameter and protected member on `OnesComplementAdder` and `CarrySelectOnesComplementCompoundAdder`. Use `subtract` and `subtractParameter`, respectively.
+
+### New Features
+
+#### IEEE Rounding Compatibility
+
+- Added all `FloatingPointRoundingMode`s to floating-point value and logic operations, including adders, multipliers, converters, square root, `FixedToFloat`, and `FloatToFixed` (<https://github.com/intel/rohd-hcl/issues/191>).
+- Added `roundingMode` to `FixedToFloat` and `FloatToFixed`, retaining their previous defaults of `roundNearestEven` and `truncate`, respectively.
+- Unified fixed- and floating-point value rounding APIs (<https://github.com/intel/rohd-hcl/issues/173>).
+
+#### Conversions
+
+- Added exact, host-`double`-independent conversion between `FloatingPointValue` and `FixedPointValue`, with automatic-width lossless methods and width-constrained populator methods (<https://github.com/intel/rohd-hcl/issues/112>).
+- Added `toLogic()` conversion from `FixedPointValue` and `FloatingPointValue` to constant corresponding signal types (<https://github.com/intel/rohd-hcl/issues/200>).
+
+#### Arithmetic Signal Operations
+
+- Added typed `add`, `subtract`, and `multiply` methods and direct `+` and `-` operators to `FixedPoint` signals, and arithmetic methods and operators to `FloatingPoint` signals (<https://github.com/intel/rohd-hcl/issues/199>).
+
+#### Integer Arithmetic Components
+
+- Added an optional `carryIn` to `SignMagnitudeAdder`.
+- Added configurable `outputWidth` to `MultiplyAccumulate`, `CompressionTreeMultiplyAccumulate`, and `MultiplyOnly`.
+- Added `GenericMultiplyAccumulate`, which composes configurable multiplier and adder generators.
+- Added independent multiplicand and multiplier widths to `NativeMultiplier` and `GeneralDotProduct`; `CompressionTreeDotProduct` retains its equal-width fused-partial-product contract.
+
+#### Parameterized Configuration
+
+- Added generic `StaticOrRuntimeControl<T>` support for statically configured values or multi-bit runtime `Logic` inputs while preserving `StaticOrRuntimeParameter` as the boolean specialization.
+
+### Bug Fixes
+
+#### IEEE Rounding Compatibility Bugs
+
+- Corrected round-nearest-even sticky-bit handling in `FloatingPointMultiplierSimple` near the subnormal boundary (<https://github.com/intel/rohd-hcl/issues/194>).
+- Replaced `FixedToFloat`'s custom rounding with the shared `FloatingPointRounder`.
+- Verified round-nearest-even behavior across mantissa widths and subnormal boundaries (<https://github.com/intel/rohd-hcl/issues/190>).
+- `FixedToFloat` overflow results now respect the selected rounding mode and use the largest finite value for formats without infinity.
+
+#### Conversion Fixes
+
+- Fixed `FloatingPointConverter` when narrowing the mantissa and widening the exponent of a subnormal value (<https://github.com/intel/rohd-hcl/issues/241>).
+- Fixed `FloatToFixed` conversion from explicit-j-bit formats.
+- Fixed `FloatToFixed` overflow detection for reduced precision, rounding carry, and the exact negative power-of-two boundary.
+- Fixed wide `FloatingPointValue.toString(integer: true)` conversions.
+
+#### NaN and Special Values
+
+- Corrected IEEE-754 NaN comparisons and added `hasSameEncoding()` (<https://github.com/intel/rohd-hcl/issues/252>).
+- Fixed explicit-j-bit infinity and NaN encodings and quiet/signaling NaN classification.
+- Fixed E4M3 exponent limits and prevented finite results from rounding into its reserved NaN encoding (<https://github.com/intel/rohd-hcl/issues/115>).
+- Fixed `FloatingPointValuePopulator.random(excludeInfinity: true)` for formats without infinity.
+- Fixed `FloatingPointValue.isLegalValue()` accepting explicit-j-bit unnormal encodings.
+
+#### Subnormal Handling
+
+- Fixed `FloatingPointValue.ulp()` for subnormal values and removed its dependency on host `double` precision (<https://github.com/intel/rohd-hcl/issues/206>).
+- Fixed zero multiplication with a widened output exponent in `FloatingPointMultiplierSimple` (<https://github.com/intel/rohd-hcl/issues/194>).
+- `FloatingPointSqrtSimple` now reports underflow when an inexact result remains subnormal.
+
+#### Fixed-Point Fixes
+
+- Added `FixedPoint.multiply` to produce a correctly signed, full-width product.
+- Fixed `FixedPointValuePopulator.canStore()` to use the rounded value and the asymmetric two's-complement range.
+
+#### Integer Arithmetic Components Fixes
+
+- Fixed `GeneralDotProduct` truncating intermediate sums and sign-extending unsigned products in uneven reduction trees. Static and runtime operand signedness now control partial-sum extension.
+- Fixed `GeneralDotProduct` passing static signedness to child multipliers as constant-valued runtime ports, and strengthened automatic definition names with lane count, operand widths, radix, implementation identity, and signedness.
+- Fixed runtime-signed `GeneralDotProduct` synthesis by keeping its signed-extension control inside the inline reduction generator rather than capturing a parent signal across a reduction-module hierarchy boundary.
+
+#### Floating-Point Arithmetic
+
+- Made `FloatingPointValue.operator /` exact and correctly rounded for arbitrary widths, removing its host-`double` dependency (<https://github.com/intel/rohd-hcl/issues/113>).
+- Fixed `FloatingPointMultiplierSimple` when the output format is narrower than its inputs (<https://github.com/intel/rohd-hcl/issues/194>).
+- Fixed `FloatingPointValue()` forwarding of the `signed` argument.
+
+### Verification and Maintenance
+
+- Added common smoke coverage for all `FloatingPointValue` formats (<https://github.com/intel/rohd-hcl/issues/133>).
+- Expanded exhaustive coverage for conversions, rounding, floating-point arithmetic, fixed-point multiplication, and multiply-accumulate widths.
+- Re-enabled `previousFloatingPointValue` regressions after the upstream ROHD fix (<https://github.com/intel/rohd/pull/565>).
+- Resolved stale arithmetic TODOs where exhaustive testing confirmed the existing implementation.
+
+### Known Issues
+
+- Berkeley TestFloat integration remains unimplemented (<https://github.com/intel/rohd-hcl/issues/135>).
+- `MultiCycleDivider` improvements (<https://github.com/intel/rohd-hcl/issues/139>) and a 4:2 `ColumnCompressor` (<https://github.com/intel/rohd-hcl/issues/120>) remain in stale pull requests.
+- `Sum` and `Counter` still generate avoidable overflow/underflow logic (<https://github.com/intel/rohd-hcl/issues/90>).
+- `CompressionTreeMultiplyAccumulate` can discard precision when `c` exceeds its natural accumulation width; `GenericMultiplyAccumulate` does not.
+- Potential optimizations remain in compact sign extension, `FixedToFloat` exponent prediction, and the dual-path floating-point adder N-path.
+
 ## 0.2.1
 
 - New Components:

doc/README.md

@@ -5,6 +5,7 @@ Below is a list of components grouped by category. Ones with links are documente
 
 Some in-development items will have opened issues, as well. Feel free to create a pull request or file issues to add more ideas to this list. If you plan to develop and contribute a component, please be sure to open an issue so that there are not multiple people working on the same thing. Make sure to check if someone else has an open issue for a certain component before starting.
 
+- [Static or Runtime Parameters](./static_or_runtime_parameters.md)
 - Encoders & Decoders
   - [1-hot to Binary](./components/onehot.md)
   - [Binary to 1-hot](./components/onehot.md)

doc/components/fixed_point.md

@@ -8,7 +8,7 @@ A [FixedPointValue](https://intel.github.io/rohd-hcl/rohd_hcl/FixedPointValue-cl
 
 ## FixedPointValue Populator
 
-A `FixedPointValuePopulator` is similar to a builder design pattern that helps populate the components of a `FixedPointValue` predictably across different special subtypes. The general pattern is to call the `populator` static function on a `FixedPointValue` (or special subtype), then subsequently call one of the population methods on the provided populator to receive a completed object.
+A `FixedPointValuePopulator` is similar to a builder design pattern that helps populate the components of a `FixedPointValue` predictably across different special subtypes. The general pattern is to call `FixedPointValue.populatorWithSignedness`, then subsequently call one of the population methods on the provided populator to receive a completed object. The deprecated `FixedPointValue.populator` remains available with its historical unsigned default.
 
 Included in the `FixedPointValuePopulator` is a `random()` floating-point value generator that can generate `FixedPointValue`s in a constrained range such as
 
@@ -23,8 +23,11 @@ or any other variants of $<$, $<=$, $>$, and $>=$. An example of its use is
 ```dart
 const m = 4;
 const n = 4;
-FixedPointValuePopulator populator() => FixedPointValue.populator(signed: true,
-        integerWidth: m, fractionWidth: n);
+FixedPointValuePopulator populator() =>
+    FixedPointValue.populatorWithSignedness(
+      integerWidth: m,
+      fractionWidth: n,
+    );
 
 final lt = populator().ofDouble(0.0);
 final gt = populator().ofDouble(0.5);
@@ -37,6 +40,15 @@ This example produces random `FixedPointValue` `fxv`s in the range $0.0 < fxv.to
 
 The [FixedPoint](https://intel.github.io/rohd-hcl/rohd_hcl/FixedPoint-class.html) type is an extension of [LogicStructure](https://intel.github.io/rohd/rohd/LogicStructure-class.html) with additional attributes (signed or unsigned, integer width and fraction width). This type is provided to simplify the design of fixed-point arithmetic blocks.  
 
+`FixedPoint` supports direct `+`, `-`, and unary `-` operators as well as
+`add`, `subtract`, and `multiply` methods. Addition, subtraction, and
+`multiply` return full-precision results. The deprecated `*` operator retains
+its historical unsigned result behavior; new code should use `multiply`.
+Comparisons use `eq`, `neq`, `lt`, `lte`, `gt`, and `gte`; `>` and `>=` are
+also available as operators. ROHD reserves `<` and `<=` for signal assignment,
+so they cannot be comparison operators. A `FixedPointValue` can be converted
+to a constant `FixedPoint` signal with `toLogic()`.
+
 ## FixedToFloat
 
 The [FixedToFloat](https://intel.github.io/rohd-hcl/rohd_hcl/FixedToFloat-class.html) component converts a fixed-point signal to a floating point signal specified by exponent and mantissa width. The output is rounded to the nearest even (RNE) when applicable and set to infinity if the input exceed the representable range.

doc/components/floating_point.md

@@ -20,6 +20,8 @@ Conversions from the native `double` are supported, both in rounded and unrounde
 
 Appropriate string representations, comparison operations, and operators are available.  The usefulness of [FloatingPointValue](https://intel.github.io/rohd-hcl/rohd_hcl/FloatingPointValue-class.html) is in the testing of [FloatingPoint](https://intel.github.io/rohd-hcl/rohd_hcl/FloatingPoint-class.html) components, where we can leverage the abstraction of a floating-point value type to drive and compare floating-point values operated upon by floating-point components.
 
+A `FloatingPointValue` can be converted to a constant `FloatingPoint` signal with `toLogic()`. `FloatingPoint` signals support direct `+`, `-`, unary `-`, and `*` operators as well as `add`, `subtract`, and `multiply` methods. The named arithmetic methods optionally select a `FloatingPointRoundingMode` and default to round-nearest-even. Comparisons use `eq`, `neq`, `lt`, `lte`, `gt`, and `gte`; `>` and `>=` are also available as operators. ROHD reserves `<` and `<=` for signal assignment, so they cannot be comparison operators.
+
 ### Subnormals As Zero
 
 Both for compatibility and for optimization we provide an option to flag floating-point numbers to be treated as zero when they become subnormal.  On input to a component, this is commonly known as Denormal-as-Zero (or DAZ).  On output from a component this is commonly known as Flush-to-Zero (FTZ).  By setting the boolean on the input `FloatingPoint` called `subNormalAsZero` you indicate DAZ for components that support this mode (our floating-point adders, currently).  By setting the same flag on the output `FloatingPoint`, you indicate FTZ.
@@ -121,14 +123,18 @@ A second `FloatingPointAdderDualPath` component is available which is optimized
 
 ## FloatingPointSqrt
 
-A very basic [FloatingPointSqrtSimple] component is available which does not perform any
-rounding and does not support DeNorm numbers. It also only operates on variable mantissas of an odd value (1,3,5,etc) but these odd mantissas can be of variable length up to 51. It takes one
-[FloatingPoint](https://intel.github.io/rohd-hcl/rohd_hcl/FloatingPoint-class.html) [LogicStructure](https://intel.github.io/rohd/rohd/LogicStructure-class.html) and
-performs a square root on it, returning the [FloatingPoint](https://intel.github.io/rohd-hcl/rohd_hcl/FloatingPoint-class.html) value on the output.
-
-Currently, the [FloatingPointSqrtSimple](https://intel.github.io/rohd-hcl/rohd_hcl/FloatingPointSqrtSimple-class.html) is close in accuracy (as it has no rounding) and is not
-optimized for circuit performance, but provides the key functionalities of floating-point square root. Still, this component is a starting point for more realistic
-floating-point components that leverage the the logical [FloatingPoint](https://intel.github.io/rohd-hcl/rohd_hcl/FloatingPoint-class.html) and literal [FloatingPointValue](https://intel.github.io/rohd-hcl/rohd_hcl/FloatingPointValue-class.html) type abstractions.
+The [FloatingPointSqrtSimple](https://intel.github.io/rohd-hcl/rohd_hcl/FloatingPointSqrtSimple-class.html)
+component computes a square root with the selected `FloatingPointRoundingMode`.
+It accepts normal and subnormal inputs, produces correctly rounded normal or
+subnormal outputs, and supports both odd and even mantissa widths. It also
+handles the floating-point special values defined by the input format. The
+component currently requires the implicit-J-bit representation; explicit-J-bit
+inputs are not supported. It is not optimized for circuit performance, but
+provides the key functional behavior of floating-point square root using the logical
+[FloatingPoint](https://intel.github.io/rohd-hcl/rohd_hcl/FloatingPoint-class.html)
+and literal
+[FloatingPointValue](https://intel.github.io/rohd-hcl/rohd_hcl/FloatingPointValue-class.html)
+type abstractions.
 
 ## FloatingPointMultiplier
 

doc/components/multiplier.md

@@ -165,9 +165,25 @@ Here is an example of using the `CompressionTreeMultiplyAccumulate` with all inp
 
 ## Dot Product
 
-The `DotProduct` component is built from multiplier components but rather than instantiating full multipliers for each product and then adding those, it builds a large compression tree of all products and the uses `CompressionTree` to reduce to a pair of addends, and then does the final addition using a provided `adderGen` function (defaulting to `NativeAdder`).
-
-The parameters to the `DotProduct` are two `List<Logic>`s for the multiplicands and multipliers.  The current restriction is that these must all be the same width. The `radix` to encode the partial products is another argument (default = 4).  Finally, two parameters are available to control whether the multiplicands and the multipliers are signed: these parameters can either be `bool` for static generation of signedness, or `Logic` for runtime control. The default, `null` results in an unsigned dot-product component.
+ROHD-HCL provides `CompressionTreeDotProduct` and `GeneralDotProduct`.
+`CompressionTreeDotProduct` combines every multiply's partial products into
+one column-compression tree and requires equal multiplicand and multiplier
+widths. `GeneralDotProduct` instantiates a selected multiplier per lane and
+uses a balanced `ReductionTree` for lossless accumulation.
+
+Both components accept two equal-length `List<Logic>` operand vectors. Every
+multiplicand must have one common width and every multiplier must have one
+common width. The two common widths may differ when using `GeneralDotProduct`
+with a multiplier generator that supports mixed widths, such as
+`CompressionTreeMultiplier`. `CompressionTreeDotProduct` retains its
+equal-width requirement because its fused partial-product matrix assumes a
+common lane geometry.
+
+Signedness for each operand vector can be a static `bool` or runtime 1-bit
+`Logic`. Static values are passed to child multipliers as static
+configuration; runtime values are passed as internal module inputs. The
+accumulated output widens by one bit at each reduction level as required to
+preserve the lossless sum.
 
 Here is an example use of `DotProduct` for a simple depth-2 dot-product computation.
 
@@ -183,7 +199,7 @@ Here is an example use of `DotProduct` for a simple depth-2 dot-product computat
       multiplicands[i].put(multiplicandValues[i]);
       multipliers[i].put(multiplierValues[i]);
     }
-    final dotProduct = DotProduct(multiplicands, multipliers);
+    final dotProduct = GeneralDotProduct(multiplicands, multipliers);
 
     final dotValue = dotProduct.product;
     // Should be 4*2 + 8*3 = 32