parallel prefix operations

.gitignore

@@ -13,6 +13,7 @@ doc/api/
 tmp*
 *.vcd
 .vscode/
+*~
 
 # Exceptions
-!.vscode/extensions.json
+!.vscode/extensions.json

CONTRIBUTING.md

@@ -151,3 +151,22 @@ Here are some links to help guide you on style as recommended by Dart:
 * Design: <https://dart.dev/guides/language/effective-dart/design>
 
 We recommend following these same guidelines for any of your own packages you may create for the ecosystem, as well.
+
+## Adding a New Component
+
+1. Create the dart code for constructing the module in lib/src
+
+1. Create testing code in test/
+
+1. Create a generator in gen
+
+   1. Add generator to gen/generate.dart
+
+   1. Run dart gen/generate.dart to make sure generation works.
+
+1. Add documentation to doc/name.dart
+
+1. How to test documentation in a dart container
+
+   1. gh_actions/install_oss_cad_suite.sh
+   1. install_d3_hwschematic.sh

doc/components/parallel_prefix_operations.md

@@ -0,0 +1,16 @@
+# Parallel Prefix Operations
+
+ROHD HCL implements a set of parallel prefix compute operations using different parallel prefix computation trees based on the ['ParallePrefix'] node class carrying carry/save or generate/propagate bits.
+
+For example, we have unary operations like a word-level 'or' [`OrScan`] class, and a priority encoder [`PriorityEncoder`] class which computes the position of the first bit set to '1'. We have simple unary arithmetic operations like an increment [`PPIncr`] class, and a decrement [`PPDecr`] class. Finally, we have a binary adder [`PPAdder`] class. For background on basic parallel prefix adder structures, see <https://en.wikipedia.org/wiki/Kogge%E2%80%93Stone_adder>.
+
+Each of these operations can be implemented with different ['ParallelPrefix'] tree structures:
+
+- ['Ripple']
+- ['Sklansky]
+- ['KoggeStone']
+- ['BrentKung]
+
+[ParallelPrefixAdder (BrentKung) Schematic]
+
+[ParallelPrefixPriorityEncoder (KoggeStone) Schematic]

gen/generate.dart

@@ -13,6 +13,7 @@
 import 'arbiter_gen.dart';
 import 'fifo_gen.dart';
 import 'one_hot_gen.dart';
+import 'parallel_prefix_operations_gen.dart';
 import 'rf_gen.dart';
 import 'rotate_gen.dart';
 
@@ -22,4 +23,5 @@ void main() async {
   await oneHotGen();
   await rfGen();
   await rotateGen();
+  await parallelPrefixGen();
 }

gen/parallel_prefix_operations_gen.dart

@@ -0,0 +1,35 @@
+// Copyright (C) 2023 Intel Corporation
+// SPDX-License-Identifier: BSD-3-Clause
+//
+// one_hot_gen.dart
+// Generate one_hot codecs.
+//
+// 2023 Oct 02
+// Author: Desmond Kirkpatrick <[email protected]>
+
+import 'dart:io';
+import 'package:rohd/rohd.dart';
+import 'package:rohd_hcl/src/parallel_prefix_operations.dart';
+
+Future<void> parallelPrefixGen() async {
+  const n = 8;
+  final a = Logic(name: 'a', width: n);
+  final b = Logic(name: 'b', width: n);
+
+  final generators = [Ripple.new, Sklansky.new, KoggeStone.new, BrentKung.new];
+  final names = ['Ripple', 'Sklansky', 'KoggeStone', 'BrentKung'];
+  var i = 0;
+  for (final ppGen in generators) {
+    final m1 = ParallelPrefixAdder(a, b, ppGen);
+    await m1.build();
+    File('build/${m1.definitionName}_${names[i]}.v').writeAsStringSync(m1
+        .generateSynth()
+        .replaceAll(m1.definitionName, '${m1.definitionName}_${names[i]}'));
+    final m2 = ParallelPrefixPriorityEncoder(a, ppGen);
+    await m2.build();
+    File('build/${m2.definitionName}_${names[i]}.v').writeAsStringSync(m2
+        .generateSynth()
+        .replaceAll(m2.definitionName, '${m2.definitionName}_${names[i]}'));
+    i = i + 1;
+  }
+}

lib/src/one_hot.dart

@@ -5,7 +5,7 @@
 // Implementation of one hot codec for Logic
 //
 // 2023 February 24
-// Author: Desmond Kirkpatrick
+// Author: Desmond Kirkpatrick <[email protected]>
 
 import 'dart:math';
 import 'package:rohd/rohd.dart';

lib/src/parallel_prefix_operations.dart

@@ -0,0 +1,255 @@
+// Copyright (C) 2023 Intel Corporation
+// SPDX-License-Identifier: BSD-3-Clause
+//
+// parallel-prefix_operations.dart
+// Implementation of operators using various parallel-prefix trees.
+//
+// 2023 Sep 29
+// Author: Desmond Kirkpatrick <[email protected]>
+//   Borrowed from https://github.com/stevenmburns/rohd_sklansky.git
+
+import 'dart:math';
+
+import 'package:collection/collection.dart';
+import 'package:rohd/rohd.dart';
+import 'package:rohd_hcl/rohd_hcl.dart';
+
+/// This computes the power of 2 less than x
+int largestPow2LessThan(int x) => pow(2, log2Ceil(x) - 1).toInt();
+
+/// ParallePrefix is the core parallel prefix tree structure node
+/// The output is a List of multi-bit Logic vectors (typicall 2-bit) that
+/// represent things like carry-save or generate-propagate signaling in adder
+/// networks.  Each node in a parallel prefix tree transforms a row of inputs
+/// to an equal length row of outputs of these multi-bit Logic values.
+class ParallelPrefix extends Module {
+  final List<Logic> _oseq = [];
+
+  /// Output sequence value
+  List<Logic> get val => _oseq;
+
+  /// ParallePrefix recursion
+  ParallelPrefix(List<Logic> inps, String name) : super(name: name) {
+    if (inps.isEmpty) {
+      throw Exception("Don't use {name} with an empty sequence");
+    }
+  }
+}
+
+/// Ripple shaped ParallelPrefix tree
+class Ripple extends ParallelPrefix {
+  /// Ripple constructor
+  Ripple(List<Logic> inps, Logic Function(Logic, Logic) op)
+      : super(inps, 'ripple') {
+    final iseq = <Logic>[];
+
+    inps.forEachIndexed((i, el) {
+      iseq.add(addInput('i$i', el, width: el.width));
+      _oseq.add(addOutput('o$i', width: el.width));
+    });
+
+    for (var i = 0; i < iseq.length; ++i) {
+      if (i == 0) {
+        _oseq[i] <= iseq[i];
+      } else {
+        _oseq[i] <= op(_oseq[i - 1], iseq[i]);
+      }
+    }
+  }
+}
+
+/// Sklansky shaped ParallelPrefix tree
+class Sklansky extends ParallelPrefix {
+  /// Sklansky constructor
+  Sklansky(List<Logic> inps, Logic Function(Logic, Logic) op)
+      : super(inps, 'sklansky') {
+    final iseq = <Logic>[];
+
+    inps.forEachIndexed((i, el) {
+      iseq.add(addInput('i$i', el, width: el.width));
+      _oseq.add(addOutput('o$i', width: el.width));
+    });
+
+    if (iseq.length == 1) {
+      _oseq[0] <= iseq[0];
+    } else {
+      final n = iseq.length;
+      final m = largestPow2LessThan(n);
+      final u = Sklansky(iseq.getRange(0, m).toList(), op).val;
+      final v = Sklansky(iseq.getRange(m, n).toList(), op).val;
+      u.forEachIndexed((i, el) {
+        _oseq[i] <= el;
+      });
+      v.forEachIndexed((i, el) {
+        _oseq[m + i] <= op(u[m - 1], el);
+      });
+    }
+  }
+}
+
+/// KoggeStone shaped ParallelPrefix tree
+class KoggeStone extends ParallelPrefix {
+  /// KoggeStone constructor
+  KoggeStone(List<Logic> inps, Logic Function(Logic, Logic) op)
+      : super(inps, 'kogge_stone') {
+    final iseq = <Logic>[];
+
+    inps.forEachIndexed((i, el) {
+      iseq.add(addInput('i$i', el, width: el.width));
+      _oseq.add(addOutput('o$i', width: el.width));
+    });
+
+    var skip = 1;
+
+    while (skip < inps.length) {
+      for (var i = inps.length - 1; i >= skip; --i) {
+        iseq[i] = op(iseq[i - skip], iseq[i]);
+      }
+      skip *= 2;
+    }
+
+    iseq.forEachIndexed((i, el) {
+      _oseq[i] <= el;
+    });
+  }
+}
+
+/// BrentKung shaped ParallelPrefix tree
+class BrentKung extends ParallelPrefix {
+  /// BrentKung constructor
+  BrentKung(List<Logic> inps, Logic Function(Logic, Logic) op)
+      : super(inps, 'brent_kung') {
+    final iseq = <Logic>[];
+
+    inps.forEachIndexed((i, el) {
+      iseq.add(addInput('i$i', el, width: el.width));
+      _oseq.add(addOutput('o$i', width: el.width));
+    });
+
+    // Reduce phase
+    var skip = 2;
+    while (skip <= inps.length) {
+      for (var i = skip - 1; i < inps.length; i += skip) {
+        iseq[i] = op(iseq[i - skip ~/ 2], iseq[i]);
+      }
+      skip *= 2;
+    }
+
+    // Prefix Phase
+    skip = largestPow2LessThan(inps.length);
+    while (skip > 2) {
+      for (var i = 3 * (skip ~/ 2) - 1; i < inps.length; i += skip) {
+        iseq[i] = op(iseq[i - skip ~/ 2], iseq[i]);
+      }
+      skip ~/= 2;
+    }
+
+    // Final row
+    for (var i = 2; i < inps.length; i += 2) {
+      iseq[i] = op(iseq[i - 1], iseq[i]);
+    }
+
+    iseq.forEachIndexed((i, el) {
+      _oseq[i] <= el;
+    });
+  }
+}
+
+/// Or scan based on ParallelPrefix tree
+class ParallelPrefixOrScan extends Module {
+  /// Output [out] is the or of bits of the input
+  Logic get out => output('out');
+
+  /// OrScan constructor
+  ParallelPrefixOrScan(
+      Logic inp,
+      ParallelPrefix Function(List<Logic>, Logic Function(Logic, Logic))
+          ppGen) {
+    inp = addInput('inp', inp, width: inp.width);
+    final u =
+        ppGen(List<Logic>.generate(inp.width, (i) => inp[i]), (a, b) => a | b);
+    addOutput('out', width: inp.width) <= u.val.rswizzle();
+  }
+}
+
+/// Priority Encoder based on ParallelPrefix tree
+class ParallelPrefixPriorityEncoder extends Module {
+  /// Output [out] is the bit position of the first '1' in the Logic input
+  /// Search is counted from the LSB
+  Logic get out => output('out');
+
+  /// PriorityEncoder constructor
+  ParallelPrefixPriorityEncoder(
+      Logic inp,
+      ParallelPrefix Function(List<Logic>, Logic Function(Logic, Logic))
+          ppGen) {
+    inp = addInput('inp', inp, width: inp.width);
+    final u = ParallelPrefixOrScan(inp, ppGen);
+    addOutput('out', width: inp.width) <= (u.out & ~(u.out << Const(1)));
+  }
+}
+
+/// Adder based on ParallelPrefix tree
+class ParallelPrefixAdder extends Module {
+  /// Output [out] the arithmetic sum of the two Logic inputs
+  Logic get out => output('out');
+
+  /// Adder constructor
+  ParallelPrefixAdder(
+      Logic a,
+      Logic b,
+      ParallelPrefix Function(List<Logic>, Logic Function(Logic, Logic))
+          ppGen) {
+    a = addInput('a', a, width: a.width);
+    b = addInput('b', b, width: b.width);
+    final u = ppGen(
+        //                                    generate,    propagate or generate
+        List<Logic>.generate(
+            a.width, (i) => [a[i] & b[i], a[i] | b[i]].swizzle()),
+        (lhs, rhs) => [rhs[1] | rhs[0] & lhs[1], rhs[0] & lhs[0]].swizzle());
+    addOutput('out', width: a.width) <=
+        List<Logic>.generate(a.width,
+                (i) => (i == 0) ? a[i] ^ b[i] : a[i] ^ b[i] ^ u.val[i - 1][1])
+            .rswizzle();
+  }
+}
+
+/// Incrementer based on ParallelPrefix tree
+class ParallelPrefixIncr extends Module {
+  /// Output is '1' added to the Logic input
+  Logic get out => output('out');
+
+  /// Increment constructor
+  ParallelPrefixIncr(
+      Logic inp,
+      ParallelPrefix Function(List<Logic>, Logic Function(Logic, Logic))
+          ppGen) {
+    inp = addInput('inp', inp, width: inp.width);
+    final u = ppGen(List<Logic>.generate(inp.width, (i) => inp[i]),
+        (lhs, rhs) => rhs & lhs);
+    addOutput('out', width: inp.width) <=
+        (List<Logic>.generate(
+                inp.width, (i) => ((i == 0) ? ~inp[i] : inp[i] ^ u.val[i - 1]))
+            .rswizzle());
+  }
+}
+
+/// Decrementer based on ParallelPrefix tree
+class ParallelPrefixDecr extends Module {
+  /// Output is '1' subtracted from the Logic input
+  Logic get out => output('out');
+
+  /// Decrement constructor
+  ParallelPrefixDecr(
+      Logic inp,
+      ParallelPrefix Function(List<Logic>, Logic Function(Logic, Logic))
+          ppGen) {
+    inp = addInput('inp', inp, width: inp.width);
+    final u = ppGen(List<Logic>.generate(inp.width, (i) => ~inp[i]),
+        (lhs, rhs) => rhs & lhs);
+    addOutput('out', width: inp.width) <=
+        (List<Logic>.generate(
+                inp.width, (i) => ((i == 0) ? ~inp[i] : inp[i] ^ u.val[i - 1]))
+            .rswizzle());
+  }
+}

pubspec.yaml

@@ -10,6 +10,7 @@ environment:
   sdk: '>=2.18.0 <3.0.0'
 
 dependencies:
+  collection: ^1.18.0
   meta: ^1.9.1
   rohd: ^0.5.0
   rohd_vf: ^0.5.0

test/one_hot_test.dart

@@ -5,7 +5,7 @@
 // Test of one_hot codec.
 //
 // 2023 February 24
-// Author: Desmond Kirkpatrick
+// Author: Desmond Kirkpatrick <[email protected]>
 
 import 'dart:math';