Documentation cleanup (#66)

.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,15 @@ pubspec.lock
 build/
 
 # Directory created by dartdoc
-doc/api/
+doc/api
 
 # Other stuff
 tmp*
 *.vcd
-.vscode/
+.vscode/*
+confapp/.vscode/*
 
 # Exceptions
-!.vscode/extensions.json
+!.vscode/extensions.json
+!confapp/.vscode/extensions.json
+!confapp/.vscode/launch.json

.pubignore

@@ -1 +1,29 @@
-confapp
+# NOTE: Everything (probably) from .gitignore should be in here!
+
+# Files and directories created by pub
+.dart_tool/
+.packages
+pubspec.lock
+
+# Conventional directory for build outputs
+build/
+
+# Directory created by dartdoc
+doc/api
+
+# Other stuff
+tmp*
+*.vcd
+.vscode/*
+confapp/.vscode/*
+
+# Exceptions
+!.vscode/extensions.json
+!confapp/.vscode/extensions.json
+!confapp/.vscode/launch.json
+
+#########
+
+# Special things for .pubignore
+confapp
+doc/d3-hwschematic

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

@@ -1,5 +1,6 @@
 [![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://github.com/codespaces/new?hide_repo_select=true&ref=main&repo=621521356)
 
+[![Generator Web App](https://img.shields.io/badge/Generator_Web_App-live-brightgreen)](https://intel.github.io/rohd-hcl/confapp/)
 [![Tests](https://github.com/intel/rohd-hcl/actions/workflows/general.yml/badge.svg?event=push)](https://github.com/intel/rohd-hcl/actions/workflows/general.yml)
 [![API Docs](https://img.shields.io/badge/API%20Docs-generated-success)](https://intel.github.io/rohd-hcl/rohd_hcl/rohd_hcl-library.html)
 [![Chat](https://img.shields.io/discord/1001179329411166267?label=Chat)](https://discord.gg/jubxF84yGw)
@@ -10,6 +11,8 @@
 
 A hardware component library developed with [ROHD](https://github.com/intel/rohd). This library aims to collect a set of reusable, configurable components that can be leveraged in other designs. These components are also intended as good examples of ROHD hardware implementations.
 
+Check out the [generator web app](https://intel.github.io/rohd-hcl/confapp/), which lets you explore some of the available components, configure them, and generate SystemVerilog.
+
 This project is always improving and growing! In a given category, initial components are primarily focused on correctness with room for optimization from there. Please feel free to contribute or provide feedback. Check out [`CONTRIBUTING`](https://github.com/intel/rohd-hcl/blob/main/CONTRIBUTING.md) for details on how to contribute.
 
 This project is *not* intended to be the *only* place for reusable hardware components developed in ROHD. It's not even intended to be the only *library*. Contributions are welcomed to this library, but developers are also welcome to build independent packages or libraries, even if they may overlap.

confapp/.vscode/extensions.json

@@ -0,0 +1,8 @@
+{
+  "recommendations": [
+    "Dart-Code.dart-code",
+    "ms-vscode-remote.remote-containers",
+    "DavidAnson.vscode-markdownlint",
+    "Dart-Code.flutter"
+  ]
+}

confapp/README.md

@@ -8,3 +8,8 @@ This is a web app that allows RTL generation (SystemVerilog) based on the specif
 flowchart TD;
     HCLAPP:material_widget-->HCLPage:register_cubit-->HCLView-->MainPage --> ComponentSideBar:Nav & SVGenerator:Content
 ```
+
+----------------
+
+Copyright (C) 2023 Intel Corporation  
+SPDX-License-Identifier: BSD-3-Clause

doc/README.md

@@ -14,24 +14,24 @@ Some in-development items will have opened issues, as well. Feel free to create
   - PLAs
 - Arbiters
   - [Priority Arbiter](./components/arbiter.md#priority-arbiter)
-  - Round-robin Arbiter
+  - [Round-robin Arbiter](./components/arbiter.md#round-robin-arbiter)
 - FIFOs & Queues
   - [Synchronous FIFO](./components/fifo.md)
   - Asynchronous / clock-crossing FIFO
   - [Shift register](./components/shift_register.md)
 - Find
-  - Find N'th bit (0 or 1) from the start/end
+  - [Find N'th bit (0 or 1) from the start/end](./components/find.md#find-nth)
   - Find minimum
   - Find maximum
   - Find N'th pattern from the start/end
 - Count
-  - Count bit occurence
+  - [Count bit occurence](./components/count.md)
   - Count pattern occurence
 - Sort
   - [Bitonic sort](./components/sort.md#bitonic-sort)
 - Arithmetic
   - Prefix Trees
-  - Adders
+  - [Adders](./components/adder.md)
   - Subtractors
   - Multipliers
     - [Pipelined Integer Multiplier](./components/multiplier.md#carry-save-multiplier)
@@ -54,7 +54,7 @@ Some in-development items will have opened issues, as well. Feel free to create
 - Error checking & correction
   - ECC
   - CRC
-  - Parity
+  - [Parity](./components/parity.md)
 - Data flow
   - Ready/Valid
   - Connect/Disconnect

doc/components/adder.md

@@ -6,9 +6,9 @@ ROHD HCL provides an adder module to get the sum from a list of logic. As of now
 
 ## Ripple Carry Adder
 
-An 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 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.
 
-The [`RippleCarryAdder`](https://intel.github.io/rohd-hcl/rohd_hcl/RippleCarryAdder-class.html) module in ROHD-HCL accept input parameters `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 `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` will be thrown.
 
 An example is shown below to add two inputs of signals that have 8-bits of width.
 

doc/components/arbiter.md

@@ -10,7 +10,7 @@ A `StatefulArbiter` is an `Arbiter` which can hold state, and thus requires a `c
 
 The [`PriorityArbiter`](https://intel.github.io/rohd-hcl/rohd_hcl/PriorityArbiter-class.html) is a combinational (stateless) arbiter that always grants to the lowest-indexed request.
 
-[PriorityArbiter Schematic](https://intel.github.io/rohd-hcl/Priority_Arbiter.html)
+[PriorityArbiter Schematic](https://intel.github.io/rohd-hcl/PriorityArbiter.html)
 
 ## Round Robin Arbiter
 

doc/components/count.md

@@ -1,18 +1,18 @@
 # Count
 
-ROHD HCL comes with a Count.  The detailed API docs are available [here](https://intel.github.io/rohd-hcl/rohd_hcl/rohd_hcl-library.html).
+ROHD HCL comes with a `Count` component.  The detailed API docs are available [here](https://intel.github.io/rohd-hcl/rohd_hcl/rohd_hcl-library.html).
 
-A Count will count all one(`1`)/zero(`0`) within a given Logic `bus`.
+A `Count` will count all one(`1`)/zero(`0`) within a given Logic `bus`.
 
-It takes a Binary Logic `bus` and counts all one or zero within the `bus`. A Count function without any constructor arguments will only count all Ones (`1`).
-That is to say, By default a Count will go for counting with a `countOne` which is set as `true` by default.
+It takes a binary Logic `bus` and counts all one or zero within the `bus`. A Count function without any constructor arguments will only count all Ones (`1`).
+That is to say, by default a Count will go for counting with a `countOne` which is set as `true` by default.
 The boolean `countOne` is optional. Only Logic `bus` is mandatory argument.
 
 This will return a Logic value labeled as `countOne` for `1` and `countZero` for `0`. The value is a result of count of all occurrence parsed (with `countOne` as `1` or `0`) through the entire Logic `bus`.
 
 ## Count One
 
-To count all ones just pass in the `bus` with `countOne` as `true`. by default countOne is `true`.
+To count all ones just pass in the `bus` with `countOne` as `true`. By default countOne is `true`.
 
 ## Count Zero
 

doc/components/fifo.md

@@ -18,21 +18,21 @@ The `empty` signal indicates when nothing is in the FIFO.  The `full` signal ind
 
 ## Bypass
 
-THe FIFO optionally supports a bypass if `generateBypass` is set.  When generated, if the FIFO is empty and both `readEnable` and `writeEnable` are high at the same time, then the FIFO will do a bypass of the internal storage, allowing for a combinational passthrough.
+The FIFO optionally supports a bypass if `generateBypass` is set.  When generated, if the FIFO is empty and both `readEnable` and `writeEnable` are high at the same time, then the FIFO will do a bypass of the internal storage, allowing for a combinational passthrough.
 
 ## Errors
 
 Error information can optionally be generated and provided if `generateError` is set.  If data is popped when the FIFO is empty, or pushed when the FIFO is full, then the `error` signal will assert.
 
-There is no guarantee that the `error` signal will hold high once asserted once.  Behavior after an error condition is undefined.
+There is no guarantee that the `error` signal will hold high once asserted.  Behavior after an error condition is undefined.
 
 ## Occupancy
 
 Occupancy information can optionally be generated and provided if `generateOccupancy` is set.  The `occupancy` signal will indicate the number of items currently stored in the FIFO.
 
 ## Example Schematic
 
-An example schematic for one configuration is viewable here: [FIFO Schematic](https://intel.github.io/rohd-hcl/FIFO.html)
+An example schematic for one configuration is viewable here: [FIFO Schematic](https://intel.github.io/rohd-hcl/Fifo.html)
 
 ## Testbench Utilities
 

doc/components/memory.md

@@ -16,7 +16,7 @@ Currently, `RegisterFile` only generates flop-based memory (no latches).
 
 The read path is combinational, so data is provided immediately according to the control signals.
 
-[RegisterFile Schematic](https://intel.github.io/rohd-hcl/Register_File.html)
+[RegisterFile Schematic](https://intel.github.io/rohd-hcl/RegisterFile.html)
 
 ## Memory Models
 

doc/components/onehot.md

@@ -8,4 +8,4 @@ The encoders take a Logic bitvector, with the constraint that only a single bit
 
 The decoders take a Logic input representing the bit position to be set to '1', and returns a Logic bitvector with that bit position set to '1', and all others set to '0'
 
-[OneHotToBinary Schematic](https://intel.github.io/rohd-hcl/One_hot_Converter.html)
+[OneHotToBinary Schematic](https://intel.github.io/rohd-hcl/CaseOneHotToBinary.html)

doc/components/parity.md

@@ -1,13 +1,13 @@
 # Parity
 
-ROHD HCL implements `Parity` functionality class that other modules can apply error checking. For satisfying the functionality of Parity error checking in `Logic` data, ROHD HCL provides 2 `Module`, namely `ParityTransmitter` and `ParityReceiver`.
+ROHD HCL implements a `Parity` component for error checking. For satisfying the functionality of Parity error checking in `Logic` data, ROHD HCL provides 2 `Module`, namely `ParityTransmitter` and `ParityReceiver`.
 
 ## Parity Transmitter
 
 The `ParityTransmitter` is a module that accepts a Logic `bus` for data and makes the data `bus` suitable for transmission with parity. A parity check is handled by appending parity bit to `bus` data.
 
 ## Parity Receiver
 
-The `ParityReceiver` is a module that accepts a Logic `bus` for transmitted data with a parity bit appended. The receiver functionality splits the provided `bus` into original `data` and `parityBit`. Also, the process of parity error check is handled within this module at result output `checkError`.
+The `ParityReceiver` is a module that accepts a Logic `bus` for transmitted data with a parity bit appended. The receiver functionality splits the provided `bus` into original `data` and `parity`. Also, the process of parity error check is handled within this module at result output `checkError`.
 
 Please visit [API docs](https://intel.github.io/rohd-hcl/rohd_hcl/rohd_hcl-library.html) for more details about parity.

doc/components/rotate.md

@@ -61,4 +61,4 @@ Also included are `extension`s for `LogicValue` with a similar rotation API for
 LogicValue.ofInt(0xf000, 16).rotateLeft(8); // results in 0x00f0
 ```
 
-[Rotate Right Schematic](https://intel.github.io/rohd-hcl/Rotate.html)
+[Rotate Right Schematic](https://intel.github.io/rohd-hcl/RotateRight.html)

doc/components/sort.md

@@ -1,6 +1,6 @@
 # Sort
 
-ROHD HCL provides a module to perform sort of a list of logic. As of now, we have
+ROHD HCL provides a component to perform sort of a list of Logic. As of now, we have
 
 - [Bitonic Sort](#bitonic-sort)
 
@@ -10,7 +10,7 @@ Bitonic sort is a pipelined sorting algorithm commonly used in hardware implemen
 
 The [`BitonicSort`](https://intel.github.io/rohd-hcl/rohd_hcl/BitonicSort-class.html) module in ROHD-HCL accept four inputs: the clock `clk` signal, reset `reset` signal, a List of Logic()'s `toSort`, sort order `isAscending` and the name of the module `name`.
 
-Note that bitonic sort **MUST** have List of inputs Logic of length power of two. To sort inputs that do not have length power of two, you must pre-process the inputs ahead by padding with `Const(0)` to have inputs length of power of two. Besides, all the width in the List of `toSort` must have same width.
+Note that bitonic sort **MUST** have List of inputs Logic of length power of two. To sort inputs that do not have length power of two, you must pre-process the inputs ahead by padding with `Const(0)` to have inputs length of power of two. Additionally, all the widths in the List of `toSort` must have same width.
 
 An example is shown below sorting 4 inputs of Logic signal that have width 8-bits to descending order.
 

lib/src/component_config/components/config_rotate.dart

@@ -9,8 +9,6 @@
 import 'dart:collection';
 
 import 'package:rohd/rohd.dart';
-// ignore: implementation_imports
-import 'package:rohd/src/utilities/simcompare.dart';
 import 'package:rohd_hcl/rohd_hcl.dart';
 
 /// A [Configurator] for rotation.
@@ -52,10 +50,4 @@ class RotateConfigurator extends Configurator {
       maxAmount: maxAmountKnob.value,
     );
   }
-
-  @override
-  List<Vector> get exampleTestVectors => [
-        for (var i = 0; i <= 9; i++)
-          Vector({'original': bin('11000'), 'rotate_amount': i}, {}),
-      ];
 }

lib/src/component_config/configurator.dart

@@ -11,8 +11,6 @@ import 'dart:convert';
 import 'package:rohd/rohd.dart';
 // ignore: implementation_imports
 import 'package:rohd/src/utilities/sanitizer.dart';
-// ignore: implementation_imports
-import 'package:rohd/src/utilities/simcompare.dart';
 import 'package:rohd_hcl/rohd_hcl.dart';
 
 /// An object that enables a consisten API for configuring a [Module] and
@@ -41,13 +39,6 @@ abstract class Configurator {
   /// Creates a [Module] instance as configured.
   Module createModule();
 
-  /// A collection of test vectors, one per cycle, that can be used to generate
-  /// a simple test and waveform as an example for this component.
-  List<Vector> get exampleTestVectors => throw UnimplementedError();
-
-  /// Runs the [exampleTestVectors] in simulation.
-  void runExampleTest() => UnimplementedError();
-
   /// Serializes the configuration information into a JSON structure.
   String toJson({bool pretty = false}) =>
       JsonEncoder.withIndent(pretty ? '  ' : null).convert({
@@ -63,6 +54,9 @@ abstract class Configurator {
     assert(decoded['name'] == name, 'Expect name to be the same.');
 
     for (final decodedKnob in (decoded['knobs'] as Map).entries) {
+      assert(knobs.containsKey(decodedKnob.key),
+          'Expect knobs in JSON to exist in configurator.');
+
       knobs[decodedKnob.key]!
           .loadJson(decodedKnob.value as Map<String, dynamic>);
     }

lib/src/count.dart

@@ -13,15 +13,15 @@ import 'dart:math';
 import 'package:rohd/rohd.dart';
 import 'package:rohd_hcl/src/utils.dart';
 
-/// [Count] `1` or `0`
+/// [Count] `1` or `0`.
 class Count extends Module {
   /// [_output] is output of Count (use index for accessing from outside Module)
   late Logic _output;
 
   /// [index] is an getter for output of Count
   Logic get index => _output;
 
-  /// [Count] `1` or `0`
+  /// [Count] `1` or `0`.
   ///
   /// Takes in [bus] of type [Logic]. by default performs [countOne] (`1`)
   /// if [countOne] is `false` will count `0`