Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

adder api and documentation cleanup #147

Merged
merged 3 commits into from
Dec 27, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 16 additions & 10 deletions doc/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,7 @@ Some in-development items will have opened issues, as well. Feel free to create
- [Binary to Gray](./components/binary_gray.md#binary-to-gray)
- [Gray to Binary](./components/binary_gray.md#gray-to-binary)
- Priority
- [Prefix-tree based Priority Encoder](./components/parallel_prefix_operations.md)
- PLAs
- Arbiters
- [Priority Arbiter](./components/arbiter.md#priority-arbiter)
Expand All @@ -19,7 +20,7 @@ Some in-development items will have opened issues, as well. Feel free to create
- [Synchronous FIFO](./components/fifo.md)
- Asynchronous / clock-crossing FIFO
- [Shift register](./components/shift_register.md)
- Find
- [Find](./components/find.md)
- [Find N'th bit (0 or 1) from the start/end](./components/find.md#find-nth)
- [Extrema](./components/extrema.md)
- Find N'th pattern from the start/end
Expand All @@ -37,10 +38,12 @@ Some in-development items will have opened issues, as well. Feel free to create
- [Incrementer](./components/parallel_prefix_operations.md)
- [Decrementer](./components/parallel_prefix_operations.md)
- [Adders](./components/adder.md)
- [Sign Magnitude Adder](./components/adder.md#ripple-carry-adder)
- [Ripple Carry Adder](./components/adder.md#ripple-carry-adder)
- [Parallel Prefix Adder](./components/parallel_prefix_operations.md)
- [Sign Magnitude Adder](./components/adder.md#sign-magnitude-adder)
- [Compound Adder](./components/adder.md#compound-adder)
- Subtractors
- [One's Complement Adder Subtractor](./components/adder.md#ones-complement-adder-subtractor)
- [Ones' Complement Adder Subtractor](./components/adder.md#ones-complement-adder-subtractor)
- Multipliers
- [Pipelined Integer Multiplier](./components/multiplier.md#carry-save-multiplier)
- [Compression Tree Multiplier](./components/multiplier.md#compression-tree-multiplier)
Expand All @@ -52,14 +55,17 @@ Some in-development items will have opened issues, as well. Feel free to create
- Square root
- Inverse square root
- Floating point
- [Floating-Point Value Types](./components/floating_point.md)
- Double (64-bit)
- Float (32-bit)
- BFloat16 (16-bit)
- BFloat8 (8-bit)
- BFloat4 (4-bit)
- [Floating-Point Value Types](./components/floating_point.md#floatingpointvalue)
- Double (64-bit)
- Float (32-bit)
- BFloat16 (16-bit)
- TensorFloat32 (19-bit)
- 8-bit E4/M3 and E5/M2
- [Simple Floating-Point Adder](./components/floating_point.md#floatingpointadder)
- Fixed point
- [Rounding Floating-Point Adder](./components/floating_point.md#floatingpointadder)
- [Fixed point](./components/fixed_point.md)
- [FloatToFixed](./components/fixed_point.md#floattofixed)
- [FixedToFloat](./components/fixed_point.md#fixedtofloat)
- Binary-Coded Decimal (BCD)
- [Rotate](./components/rotate.md)
- Counters
Expand Down
45 changes: 26 additions & 19 deletions doc/components/adder.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Adder
# Adders

ROHD-HCL provides a set of adder modules to get the sum from a pair of Logic. As of now, we have
ROHD-HCL provides a set of adder modules to get the sum from a pair of Logic. Some adders provide an optional carry input provided in the base class of [Adder](https://intel.github.io/rohd-hcl/rohd_hcl/Adder-class.html). As of now, ROHD-HCL supplies:

- [Ripple Carry Adder](#ripple-carry-adder)
- [Parallel Prefix Adder](#parallel-prefix-adder)
Expand All @@ -10,9 +10,9 @@ ROHD-HCL provides a set of adder modules to get the sum from a pair of Logic. As

## Ripple Carry Adder

A ripple carry adder is a digital circuit used for binary addition. It consists of a series of full adders connected in a chain, with the carry output of each adder linked to the carry input of the next one. Starting from the least significant bit (LSB) to most significant bit (MSB), the adder sequentially adds corresponding bits of two binary numbers.
A ripple carry adder is a digital circuit used for binary addition. It consists of a series of [FullAdder](https://intel.github.io/rohd-hcl/rohd_hcl/FullAdder-class.html)s connected in a chain, with the carry output of each adder linked to the carry input of the next one. Starting from the least significant bit (LSB) to most significant bit (MSB), the adder sequentially adds corresponding bits of two binary numbers.

The [`RippleCarryAdder`](https://intel.github.io/rohd-hcl/rohd_hcl/RippleCarryAdder-class.html) module in ROHD-HCL accept input `Logic`s a and b as the input pin and the name of the module `name`. Note that the width of the inputs must be the same or a `RohdHclException` will be thrown.
The [RippleCarryAdder](https://intel.github.io/rohd-hcl/rohd_hcl/RippleCarryAdder-class.html) module in ROHD-HCL accept input `Logic`s a and b as the input pin and the name of the module `name`. Note that the width of the inputs must be the same or a [RohdHclException](https://intel.github.io/rohd-hcl/rohd_hcl/RohdHclException-class.html) will be thrown.

An example is shown below to add two inputs of signals that have 8-bits of width.

Expand All @@ -29,9 +29,9 @@ final sum = rippleCarryAdder.sum;

## Parallel Prefix Adder

A parallel prefix adder is an adder that uses different varieties of a parallel prefix tree (see `Parallel Prefix Operations`) to efficiently connect a set of `Full Adder` circuits to form a complete adder.
A parallel prefix adder is an adder that uses different varieties of a parallel prefix tree (see [Parallel Prefix Operations](../components/parallel_prefix_operations.md)) to efficiently connect a set of `Full Adder` circuits to form a complete adder.

Here is an example of instantiating a `ParallelPrefixAdder`:
Here is an example of instantiating a [ParallelPrefixAdder](https://intel.github.io/rohd-hcl/rohd_hcl/ParallelPrefixAdder-class.html) :

```dart
const width = 6;
Expand All @@ -48,16 +48,16 @@ Here is an example of instantiating a `ParallelPrefixAdder`:
print('${sum.value.toBigInt()}');
```

## One's Complement Adder Subtractor
## Ones' Complement Adder Subtractor

A ones-complement adder (and subtractor) is useful in efficient arithmetic operations as the
end-around carry can be bypassed and used later.

The `OnesComplementAdder` can take a subtraction command as either a Logic `subtractIn` or a boolean `subtract` (the Logic overrides the boolean). If Logic `carry` is provided, the end-around carry is output on `carry` and the value will be one less than expected when `carry` is high. An `adderGen` adder function can be provided that generates your favorite internal adder (such as a parallel prefix adder).
The [OnesComplementAdder](https://intel.github.io/rohd-hcl/rohd_hcl/OnesComplementAdder-class.html) can take a subtraction command as either a `Logic` `subtractIn` or a boolean `subtract` (the Logic overrides the boolean). If Logic `carry` is provided, the end-around carry is output on `carry` and the value will be one less than expected when `carry` is high. An `adderGen` adder function can be provided that generates your favorite internal adder (such as a parallel prefix adder).

The output of `OnesComplementAdder` is a `sum` which is the magnitude and a `sign`.
The output of [OnesComplementAdder](https://intel.github.io/rohd-hcl/rohd_hcl/OnesComplementAdder-class.html) is a `sum` which is the magnitude and a `sign`.

Here is an example of instantiating a `OnesComplementAdder` as a subtractor, but saving the `carry`:
Here is an example of instantiating a [OnesComplementAdder](https://intel.github.io/rohd-hcl/rohd_hcl/OnesComplementAdder-class.html) as a subtractor, but saving the `carry`:

```dart
const width = 4;
Expand All @@ -76,13 +76,13 @@ Here is an example of instantiating a `OnesComplementAdder` as a subtractor, but

## Sign Magnitude Adder

A sign magnitude adder is useful in situations where the sign of the addends is separated from their magnitude (e.g., not 2s complement), such as in floating point multipliers. The `SignMagnitudeAdder` inherits from `Adder` but adds the `Logic` inputs for the two operands.
A sign magnitude adder is useful in situations where the sign of the addends is separated from their magnitude (e.g., not 2s complement), such as in floating point multipliers. The [SignMagnitudeAdder](https://intel.github.io/rohd-hcl/rohd_hcl/SignMagnitudeAdder-class.html) inherits from `Adder` but adds the `Logic` inputs for the two operands.

If you can supply the largest magnitude number first, then you can disable a comparator generation inside by declaring the `largestMagnitudeFirst` option as true.

The `SignMagnitudeAdder` uses a `OnesComplementAdder` internally.
The [SignMagnitudeAdder](https://intel.github.io/rohd-hcl/rohd_hcl/SignMagnitudeAdder-class.html) uses a [OnesComplementAdder](https://intel.github.io/rohd-hcl/rohd_hcl/OnesComplementAdder-class.html) internally.

Here is an example of instantiating a `SignMagnitudeAdder`:
Here is an example of instantiating a [SignMagnitudeAdder](https://intel.github.io/rohd-hcl/rohd_hcl/SignMagnitudeAdder-class.html):

```dart
const width = 6;
Expand All @@ -106,13 +106,20 @@ Here is an example of instantiating a `SignMagnitudeAdder`:

## Compound Adder

A compound carry adder is a digital circuit used for binary addition. It produces sum and sum+1 outputs.
A trivial compound adder component `TrivialCompoundAdder` doesnt use any RTL code optimization.
Carry-select adder-based compound adder `CarrySelectCompoundAdder` uses carry-select adder as a basis. Like a carry-select adder it consists of a multiple blocks of two ripple-carry adders <https://en.wikipedia.org/wiki/Carry-select_adder>. But the first block has two ripple-carry adders and two separate carry-propagate chains are used to select sum and sum+1 output bits. Sum selecting chain starts from carry input 0 driven block and sum+1 selecting chain starts from carry input 1 driven block.
The delay of the adder is defined by combination ripple-carry adder and accumulated carry-select chain delay.
A compound carry adder is a digital circuit used for binary addition. It efficiently produces both sum and sum+1 outputs.
A trivial compound adder component [TrivialCompoundAdder](https://intel.github.io/rohd-hcl/rohd_hcl/TrivialCompoundAdder-class.html) doesn't use any RTL code optimization, and uses the native '+' operation.
The [`CarrySelectCompoundAdder`](https://intel.github.io/rohd-hcl/rohd_hcl/CarrySelectCompoundAdder-class.html) uses a carry-select adder as a basis. Like a carry-select adder it consists of a multiple blocks of two parallel adders <https://en.wikipedia.org/wiki/Carry-select_adder>. The first block has two adders and two separate carry-propagate chains are used to select sum and sum+1 output bits. The sum selecting chain starts from the carry input 0 driven block and sum+1 selecting chain starts from the carry input 1 driven block.
The delay of the adder is defined by the combination of the sub-adders and the accumulated carry-select chain delay.

The `CarrySelectCompoundAdder` module in ROHD-HCL accept input `Logic`s a and b as the input pin and the name of the module `name`. Note that the width of the inputs must be the same or a `RohdHclException` will be thrown.
Compound adder generator provides two alogithms for splitting adder into ripple-carry blocks. `CarrySelectCompoundAdder.splitSelectAdderAlgorithm4Bit` algoritm splits adder into blocks of 4-bit ripple-carry adders with the first one width adjusted down. `CarrySelectCompoundAdder.splitSelectAdderAlgorithmSingleBlock` algorithm generates only one block of full bitwidth of the adder. Input List\<int\> Function(int adderFullWidth) `widthGen` should be used to specify custom adder splitting algorithm that returns a list of sub-adders width. The default one is `CarrySelectCompoundAdder.splitSelectAdderAlgorithmSingleBlock`.
The [CarrySelectCompoundAdder](https://intel.github.io/rohd-hcl/rohd_hcl/CarrySelectCompoundAdder-class.html) module in ROHD-HCL accepts input `Logic`s a and b as the input pin and the name of the module `name`. Note that the width of the inputs must be the same or a [RohdHclException](https://intel.github.io/rohd-hcl/rohd_hcl/RohdHclException-class.html) will be thrown.
The compound adder generator provides two alogithms for splitting the adder into adder sub-blocks:

- The [CarrySelectCompoundAdder.splitSelectAdderAlgorithm4Bit](https://intel.github.io/rohd-hcl/rohd_hcl/CarrySelectCompoundAdder/splitSelectAdderAlgorithm4Bit.html) algoritm splits the adder into blocks of 4-bit ripple-carry adders with the first one width adjusted down.
- The [CarrySelectCompoundAdder.splitSelectAdderAlgorithmSingleBlock](https://intel.github.io/rohd-hcl/rohd_hcl/CarrySelectCompoundAdder/splitSelectAdderAlgorithmSingleBlock.html) algorithm generates only one sub=block with the full bitwidth of the adder.

Input `List<int> Function(int adderFullWidth) widthGen` should be used to specify the custom adder splitting algorithm that returns a list of sub-adders width. The default one is [CarrySelectCompoundAdder.splitSelectAdderAlgorithmSingleBlock](<https://intel.github.io/rohd-hcl/rohd_hcl/CarrySelectCompoundAdder/splitSelectAdderAlgorithmSingleBlock.html>).

The `adderGen` input selects the type of sub-adder used, with the default being `ParallelPrefixAdder`.

An example is shown below to add two inputs of signals that have 8-bits of width.

Expand Down
8 changes: 4 additions & 4 deletions doc/components/fixed_point.md
Original file line number Diff line number Diff line change
@@ -1,14 +1,14 @@
# Fixed-Point Arithmetic

Fixed-point binary representation of numbers is useful several applications including digital signal processing and embedded systems. As a first step towards enabling fixed-point components, we created a new value system `FixedPointValue` similar to `LogicValue`.
Fixed-point binary representation of numbers is useful several applications including digital signal processing and embedded systems. As a first step towards enabling fixed-point components, we created a new value system [FixedPointValue](https://intel.github.io/rohd-hcl/rohd_hcl/FixedPointValue-class.html) similar to [LogicValue](https://intel.github.io/rohd/rohd/LogicValue-class.html).

## FixedPointValue

A `FixedPointValue` represents a signed or unsigned fixed-point value following the Q notation (Qm.n format) as introduced by [Texas Instruments](https://www.ti.com/lit/ug/spru565b/spru565b.pdf). It comprises an optional sign, integer part and/or a fractional part. `FixedPointValue`s can be constructed from individual fields or from a Dart `double`, converted to Dart `double`, can be compared and can be operated on (+, -, *, /).
A [FixedPointValue](https://intel.github.io/rohd-hcl/rohd_hcl/FixedPointValue-class.html) represents a signed or unsigned fixed-point value following the Q notation (Qm.n format) as introduced by [Texas Instruments](https://www.ti.com/lit/ug/spru565b/spru565b.pdf). It comprises an optional sign, integer part and/or a fractional part. [FixedPointValue](https://intel.github.io/rohd-hcl/rohd_hcl/FixedPointValue-class.html)s can be constructed from individual fields or from a Dart [double](https://api.dart.dev/stable/3.6.0/dart-core/double-class.html), converted to Dart [double](https://api.dart.dev/stable/3.6.0/dart-core/double-class.html), can be compared and can be operated on (+, -, *, /).

## FixedPoint

The `FixedPoint` type is an extension of `Logic` with additional attributes (signed or unsigned, integer width and fraction width). This type is provided to simplify the design of fixed-point arithmetic blocks.
The [FixedPoint](https://intel.github.io/rohd-hcl/rohd_hcl/FixedPoint-class.html) type is an extension of [Logic](https://intel.github.io/rohd/rohd/Logic-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.

## FixedToFloat

Expand All @@ -20,4 +20,4 @@ This component converts a floating-point signal to a signed fixed-point signal.

## Float8ToFixed

This component converts an 8-bit floating-point (FP8) representation (E5M2 or E4M3) to a signed fixed-point representation. This component offers using the same hardware for both FP8 formats. Therefore, both input and output are of type `Logic` and can be cast from/to floating point/fixed point by the producer/consumer based on the selected `mode`. Infinities and NaN's are not supported. The output width is 33 to accomodate E5M2 without loss.
This component converts an 8-bit floating-point (FP8) representation ([FloatingPoint8E4M3Value](https://intel.github.io/rohd-hcl/rohd_hcl/FloatingPoint8E4M3Value-class.html) or [FloatingPoint8E5M2Value](https://intel.github.io/rohd-hcl/rohd_hcl/FloatingPoint8E5M2Value-class.html)) to a signed fixed-point representation. This component offers using the same hardware for both FP8 formats. Therefore, both input and output are of type [Logic](https://intel.github.io/rohd/rohd/Logic-class.html) and can be cast from/to floating point/fixed point by the producer/consumer based on the selected `mode`. Infinities and NaN's are not supported. The output width is 33bits to accomodate [FloatingPoint8E5M2Value](https://intel.github.io/rohd-hcl/rohd_hcl/FloatingPoint8E5M2Value-class.html) without loss.
Loading