parallel prefix operations

.github/workflows/general.yml

@@ -17,6 +17,8 @@ jobs:
     steps:
       - name: Checkout
         uses: actions/checkout@v3
+        with:
+          submodules: recursive
 
       - name: Lint Markdown files
         uses: DavidAnson/markdownlint-cli2-action@v11

.gitignore

@@ -1,3 +1,5 @@
+# NOTE: Be sure to update .pubignore as well!
+
 # Files and directories created by pub
 .dart_tool/
 .packages
@@ -7,12 +9,17 @@ pubspec.lock
 build/
 
 # Directory created by dartdoc
-doc/api/
+doc/api
 
 # Other stuff
 tmp*
 *.vcd
-.vscode/
+.vscode/*
+confapp/.vscode/*
+*tracker.json
+*tracker.log
 
 # Exceptions
-!.vscode/extensions.json
+!.vscode/extensions.json
+!confapp/.vscode/extensions.json
+!confapp/.vscode/launch.json

CONTRIBUTING.md

@@ -134,6 +134,21 @@ Here is an example of a recommended file header template:
 // Author: Max Korbel <[email protected]>
 ```
 
+#### Adding a New Component
+
+To add a new component to the library, you can follow the steps below, referencing other components as examples.
+
+1. Create the dart code for constructing the module in `lib/src`.
+1. Create unit tests in `test/`.
+1. Create a `Configurator` for the component (enabling things like schematic generation, web-app generation, etc.).
+   1. Create a new config in `lib/src/component_config/commponents`.
+   1. Update the component registry in `lib/src/component_config/components/component_registry.dart`.
+1. Add documentation to `doc/components/name.md`.
+
+If you would like to generate and view schematics locally, you'll need to have access to some tools.  You can either use the dev container (via Codespaces or VS Code) or install the software from `tool/gh_actions/install_opencadsuite.sh` and `tool/gh_actions/install_d3_hwschematic.sh`.  Then you can just run `tool/gh_actions/create_htmls.sh`, which will generate component schematic HTML documents in the `build/` directory.
+
+The `confapp/` directory contains the source code for the Flutter configuration app, if you would like to run that locally.
+
 ### Creating a New Package
 
 Not every new contribution has to go directly into the ROHD or ROHD-HCL frameworks! If you have an idea for a reusable piece of hardware, tooling, verification collateral, or anything else that helps the ROHD ecosystem but is somewhat standalone, you can make your own package that depends on ROHD. Building an ecosystem of reusable components is important to the success of ROHD. Reach out if you want some help or guidance deciding if or how you should create a new package.

README.md

@@ -48,6 +48,5 @@ Some examples of component categories include:
 - Models
 
 ----------------
-
 Copyright (C) 2023 Intel Corporation  
 SPDX-License-Identifier: BSD-3-Clause

doc/components/parallel_prefix_operations.md

@@ -0,0 +1,14 @@
+# Parallel Prefix Operations
+
+ROHD HCL implements a set of parallel prefix compute operations using different parallel prefix computation trees based on the ['ParallelPrefix'] node class carrying carry/save or generate/propagate bits.
+
+For example, we have unary operations like a word-level 'or' [`ParallelPrefixOrScan`] class, and a priority encoder [`ParallelPrefixPriorityEncoder`] class which computes the position of the first bit set to '1'. We have simple unary arithmetic operations like an increment [`ParallelPrefixIncr`] class, and a decrement [`ParallelPrefixDecr`] class. Finally, we have a binary adder [`ParallelPrefixAdder`] 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'] types:
+
+- ['Ripple'](https://intel.github.io/rohd-hcl/rohd_hcl/Ripple-class.html)
+- ['Sklansky](https://intel.github.io/rohd-hcl/rohd_hcl/Sklansky-class.html)
+- ['KoggeStone'](https://intel.github.io/rohd-hcl/rohd_hcl/KoggeStone-class.html)
+- ['BrentKung](https://intel.github.io/rohd-hcl/rohd_hcl/BrentKung-class.html)
+
+[PPAdder_BrentKung Schematic](https://intel.github.io/rohd-hcl/PPAdder_BrentKung.html)

gen/generate.dart

@@ -10,16 +10,15 @@
 // 2023 May 09
 // Author: Desmond Kirkpatrick <[email protected]>
 
-import 'arbiter_gen.dart';
-import 'fifo_gen.dart';
-import 'one_hot_gen.dart';
-import 'rf_gen.dart';
-import 'rotate_gen.dart';
+import 'dart:io';
+
+import 'package:rohd_hcl/src/component_config/components/component_registry.dart';
 
 void main() async {
-  await arbiterGen();
-  await fifoGen();
-  await oneHotGen();
-  await rfGen();
-  await rotateGen();
+  Directory('build').createSync(recursive: true);
+  for (final configurator in componentRegistry) {
+    final sv = await configurator.generateSV();
+    final name = configurator.createModule().definitionName;
+    File('build/$name.v').writeAsStringSync(sv);
+  }
 }

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;
+  }
+}