Merge branch 'main' into example/gray-to-binary

.github/configs/mlc_config.json

@@ -2,6 +2,9 @@
   "ignorePatterns": [
     {
       "pattern":"^https://www.intel.com/content/www/us/en/security-center/vulnerability-handling-guidelines.html$"
+    },
+    {
+      "pattern":"^https://stackoverflow.com"
     }
   ]
 }

.github/workflows/general.yml

@@ -49,7 +49,7 @@ jobs:
         run: tool/gh_actions/analyze_source.sh
 
       - name: Check project documentation
-        run: tool/gh_actions/check_documentation.sh
+        run: tool/gh_actions/generate_documentation.sh
 
       - name: Run project tests
         run: tool/gh_actions/run_tests.sh

CONTRIBUTING.md

@@ -64,6 +64,13 @@ The below button will allow you to create a GitHub Codespace with ROHD-HCL alrea
 
 [![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://github.com/codespaces/new?hide_repo_select=true&ref=main&repo=621521356)
 
+To run the component Configurator, especially useful for visualizing the RTL output of your component using different parameters:
+
+```shell
+cd confapp
+flutter run --profile -d web-server --web-hostname=0.0.0.0 --web-port=3000
+```
+
 ### Cloning and Running the Tests
 
 Once requirements are installed, you can clone and run the test suite:

analysis_options.yaml

@@ -9,17 +9,17 @@ analyzer:
   exclude:
     - confapp/**
 
-# keep up to date, matching https://dart-lang.github.io/linter/lints/options/options.html
+# keep up to date, matching https://dart.dev/tools/linter-rules/all
 # some lints are not yet available, so disabled and marked with [not currently recognized]
 linter:
   rules:
     - always_declare_return_types
     - always_put_control_body_on_new_line
     - always_put_required_named_parameters_first
-    - always_require_non_null_named_parameters
     # - always_specify_types
     - always_use_package_imports
     - annotate_overrides
+    - annotate_redeclares
     # - avoid_annotating_with_dynamic
     - avoid_bool_literals_in_conditional_expressions
     - avoid_catches_without_on_clauses
@@ -45,8 +45,6 @@ linter:
     - avoid_relative_lib_imports
     - avoid_renaming_method_parameters
     - avoid_return_types_on_setters
-    - avoid_returning_null
-    - avoid_returning_null_for_future
     - avoid_returning_null_for_void
     - avoid_returning_this
     - avoid_setters_without_getters
@@ -94,15 +92,13 @@ linter:
     - implicit_call_tearoffs
     - implicit_reopen
     - invalid_case_patterns
-    # - iterable_contains_unrelated_type [deprecated]
     - join_return_with_assignment
     - leading_newlines_in_multiline_strings
     - library_annotations
     - library_names
     - library_prefixes
     - library_private_types_in_public_api
     - lines_longer_than_80_chars
-    # - list_remove_unrelated_type [deprecated]
     - literal_only_boolean_expressions
     - matching_super_parameters
     - missing_whitespace_between_adjacent_strings

doc/README.md

@@ -27,6 +27,8 @@ Some in-development items will have opened issues, as well. Feel free to create
 - Count
   - [Count bit occurence](./components/count.md)
   - Count pattern occurence
+- Detection
+  - [Edge detection](./components/edge_detector.md)
 - Sort
   - [Bitonic sort](./components/sort.md#bitonic-sort)
 - Arithmetic
@@ -45,16 +47,19 @@ Some in-development items will have opened issues, as well. Feel free to create
     - BFloat16 (16-bit)
     - BFloat8 (8-bit)
     - BFloat4 (4-bit)
+  - Fixed point
+  - Binary-Coded Decimal (BCD)
 - [Rotate](./components/rotate.md)
 - Counters
   - Binary counter
   - Gray counter
 - Pseudorandom
   - LFSR
 - Error checking & correction
-  - ECC
+  - [ECC](./components/ecc.md)
   - CRC
   - [Parity](./components/parity.md)
+  - Interleaving
 - Data flow
   - Ready/Valid
   - Connect/Disconnect
@@ -85,8 +90,10 @@ Some in-development items will have opened issues, as well. Feel free to create
 - Models
   - [APB](./components/apb_bfm.md)
   - [Ready/Valid](./components/ready_valid_bfm.md)
+  - SPI
+  - CXL
 
 ----------------
 
-Copyright (C) 2023 Intel Corporation  
+Copyright (C) 2023-2024 Intel Corporation  
 SPDX-License-Identifier: BSD-3-Clause

doc/components/ecc.md

@@ -0,0 +1,14 @@
+# Error Correcting Codes (ECC)
+
+ROHD-HCL implements [Hamming codes](https://en.wikipedia.org/wiki/Hamming_code) for error correction and detection. The Wikipedia article does a good job explaining the background and functionality of Hamming codes, for those unfamiliar.
+
+An error correcting code is a code that can be included in a transmission with some data that enables the receiver to check whether there was an error (up to some number of bit flips), and possibly correct the error (up to a limit). There is a trade-off where increasing the number of additional bits included in the code improves error checking/correction, but costs more bits (area/power/storage).
+
+ROHD-HCL only has Hamming codes currently, but there are many types of error correcting codes. The `HammingEccTransmitter` and `HammingEccReceiver` can support any data width, and support the following configurations:
+
+| Type | Errors detectable | Errors correctable | Extra parity bit |
+|------|-------------------|--------------------|------------------|
+| Single Error Correction (SEC) | 1 | 1 | No |
+| Double Error Detection (SEDDED) | 2 | 0 | No |
+| Single Error Correction, Double Error Detection (SECDED) | 2 | 1 | Yes |
+| Triple Error Detection (SEDDEDTED) | 3 | 0 | Yes |

doc/components/edge_detector.md

@@ -0,0 +1,3 @@
+# Edge Detection
+
+The `EdgeDetector` is a simple utility to determine whether the current value of a 1-bit signal is different from the value in the previous cycle.  It is a fully synchronous design, so it does not asynchronously detect edges.  It optionally supports a reset, with an optional reset value.  It can be configured to detect positive, negative, or "any" edges.

doc/components/parallel_prefix_operations.md

@@ -0,0 +1,12 @@
+# 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']
+- ['Sklansky]
+- ['KoggeStone']
+- ['BrentKung]

lib/rohd_hcl.dart

@@ -1,4 +1,4 @@
-// Copyright (C) 2023 Intel Corporation
+// Copyright (C) 2023-2024 Intel Corporation
 // SPDX-License-Identifier: BSD-3-Clause
 
 export 'src/adder.dart';
@@ -7,15 +7,17 @@ export 'src/binary_gray.dart';
 export 'src/carry_save_mutiplier.dart';
 export 'src/component_config/component_config.dart';
 export 'src/count.dart';
+export 'src/edge_detector.dart';
 export 'src/encodings/encodings.dart';
+export 'src/error_checking/error_checking.dart';
 export 'src/exceptions.dart';
 export 'src/fifo.dart';
 export 'src/find.dart';
 export 'src/interfaces/interfaces.dart';
 export 'src/memory/memories.dart';
 export 'src/models/models.dart';
 export 'src/multiplier.dart';
-export 'src/parity.dart';
+export 'src/parallel_prefix_operations.dart';
 export 'src/ripple_carry_adder.dart';
 export 'src/rotate.dart';
 export 'src/shift_register.dart';

lib/src/component_config/components/component_registry.dart

@@ -1,4 +1,4 @@
-// Copyright (C) 2023 Intel Corporation
+// Copyright (C) 2023-2024 Intel Corporation
 // SPDX-License-Identifier: BSD-3-Clause
 //
 // component_registry.dart
@@ -13,11 +13,15 @@ import 'package:rohd_hcl/rohd_hcl.dart';
 List<Configurator> get componentRegistry => [
       RotateConfigurator(),
       FifoConfigurator(),
-      PriorityArbiterConfigurator(),
+      EccConfigurator(),
       RoundRobinArbiterConfigurator(),
+      PriorityArbiterConfigurator(),
       RippleCarryAdderConfigurator(),
       CarrySaveMultiplierConfigurator(),
       BitonicSortConfigurator(),
       OneHotConfigurator(),
       RegisterFileConfigurator(),
+      EdgeDetectorConfigurator(),
+      FindConfigurator(),
+      ParallelPrefixAdderConfigurator(),
     ];

lib/src/component_config/components/components.dart

@@ -1,9 +1,13 @@
-// Copyright (C) 2023 Intel Corporation
+// Copyright (C) 2023-2024 Intel Corporation
 // SPDX-License-Identifier: BSD-3-Clause
 
 export 'config_carry_save_multiplier.dart';
+export 'config_ecc.dart';
+export 'config_edge_detector.dart';
 export 'config_fifo.dart';
+export 'config_find.dart';
 export 'config_one_hot.dart';
+export 'config_parallel_prefix_adder.dart';
 export 'config_priority_arbiter.dart';
 export 'config_rf.dart';
 export 'config_ripple_carry_adder.dart';

lib/src/component_config/components/config_ecc.dart

@@ -0,0 +1,39 @@
+// Copyright (C) 2024 Intel Corporation
+// SPDX-License-Identifier: BSD-3-Clause
+//
+// config_ecc.dart
+// Configurator for ECC.
+//
+// 2024 January 18
+// Author: Max Korbel <[email protected]>
+
+import 'package:rohd/rohd.dart';
+import 'package:rohd_hcl/rohd_hcl.dart';
+
+/// A [Configurator] for [HammingEccReceiver] and [HammingEccTransmitter].
+class EccConfigurator extends Configurator {
+  /// A knob controlling the [HammingType].
+  final ChoiceConfigKnob<HammingType> typeKnob =
+      ChoiceConfigKnob(HammingType.values, value: HammingType.sec);
+
+  /// A knob controlling the data width.
+  final IntConfigKnob dataWidthKnob = IntConfigKnob(value: 4);
+
+  @override
+  Module createModule() => HammingEccReceiver(
+        HammingEccTransmitter(
+          Logic(width: dataWidthKnob.value),
+          hammingType: typeKnob.value,
+        ).transmission,
+        hammingType: typeKnob.value,
+      );
+
+  @override
+  late final Map<String, ConfigKnob<dynamic>> knobs = {
+    'Data Width': dataWidthKnob,
+    'Hamming Type': typeKnob,
+  };
+
+  @override
+  final String name = 'ECC';
+}

lib/src/component_config/components/config_edge_detector.dart

@@ -0,0 +1,51 @@
+// Copyright (C) 2024 Intel Corporation
+// SPDX-License-Identifier: BSD-3-Clause
+//
+// config_edge_detector.dart
+// Configurator for a EdgeDetector.
+//
+// 2024 January 29
+// Author: Max Korbel <[email protected]>
+
+import 'dart:collection';
+
+import 'package:rohd/rohd.dart';
+import 'package:rohd_hcl/rohd_hcl.dart';
+import 'package:rohd_vf/rohd_vf.dart';
+
+/// A [Configurator] for [EdgeDetector].
+class EdgeDetectorConfigurator extends Configurator {
+  /// A knob controlling the type of edge detector.
+  final ChoiceConfigKnob<Edge> edgeTypeKnob =
+      ChoiceConfigKnob(Edge.values, value: Edge.pos);
+
+  /// A knob controlling whether there is a reset.
+  final ToggleConfigKnob hasResetKnob = ToggleConfigKnob(value: true);
+
+  /// A knob controlling the reset value.
+  final ChoiceConfigKnob<dynamic> resetValueKnob =
+      ChoiceConfigKnob([0, 1, 'Input'], value: 0);
+
+  @override
+  Module createModule() => EdgeDetector(
+        Logic(),
+        clk: Logic(),
+        reset: hasResetKnob.value ? Logic() : null,
+        edgeType: edgeTypeKnob.value,
+        resetValue: hasResetKnob.value
+            ? resetValueKnob.value == 'Input'
+                ? Logic()
+                : resetValueKnob.value
+            : null,
+      );
+
+  @override
+  Map<String, ConfigKnob<dynamic>> get knobs => UnmodifiableMapView({
+        'Edge Type': edgeTypeKnob,
+        'Has Reset': hasResetKnob,
+        if (hasResetKnob.value) 'Reset Value': resetValueKnob,
+      });
+
+  @override
+  final String name = 'Edge Detector';
+}

lib/src/component_config/components/config_find.dart

@@ -0,0 +1,49 @@
+// Copyright (C) 2024 Intel Corporation
+// SPDX-License-Identifier: BSD-3-Clause
+//
+// config_priority_arbiter.dart
+// Configurator for a PriorityArbiter.
+//
+// 2024 February 7
+// Author: Max Korbel <[email protected]>
+
+import 'dart:collection';
+
+import 'package:rohd/rohd.dart';
+import 'package:rohd_hcl/rohd_hcl.dart';
+
+/// A [Configurator] for [Find].
+class FindConfigurator extends Configurator {
+  /// A knob controlling the width of the bus.
+  final IntConfigKnob busWidthKnob = IntConfigKnob(value: 8);
+
+  /// A knob controlling whether it should count ones or zeros.
+  final ToggleConfigKnob countOneKnob = ToggleConfigKnob(value: true);
+
+  /// A knob controlling the generation of an error signal.
+  final ToggleConfigKnob generateErrorKnob = ToggleConfigKnob(value: false);
+
+  /// A knob controlling whether it should have `n` as an input.
+  final ToggleConfigKnob includeNKnob = ToggleConfigKnob(value: false);
+
+  @override
+  late final Map<String, ConfigKnob<dynamic>> knobs = UnmodifiableMapView({
+    'Bus Width': busWidthKnob,
+    'Count Ones': countOneKnob,
+    'Generate Error': generateErrorKnob,
+    'Include N': includeNKnob,
+  });
+
+  @override
+  Module createModule() => Find(
+        Logic(width: busWidthKnob.value),
+        countOne: countOneKnob.value,
+        generateError: generateErrorKnob.value,
+        n: includeNKnob.value
+            ? Logic(width: log2Ceil(busWidthKnob.value))
+            : null,
+      );
+
+  @override
+  final String name = 'Find';
+}