doc, configurator, cleanup

.github/workflows/general.yml

@@ -13,7 +13,7 @@ jobs:
     name: Run Checks
     permissions: {}
     timeout-minutes: 30
-    runs-on: intel-ubuntu-latest
+    runs-on: ${{ github.repository_owner == 'intel' && 'intel-ubuntu-latest' || 'ubuntu-latest' }}
     steps:
       - name: Checkout
         uses: actions/checkout@v3
@@ -70,7 +70,7 @@ jobs:
     name: Run Flutter Checks
     permissions: {}
     timeout-minutes: 30
-    runs-on: intel-ubuntu-latest
+    runs-on: ${{ github.repository_owner == 'intel' && 'intel-ubuntu-latest' || 'ubuntu-latest' }}
     steps:
       - name: Checkout
         uses: actions/checkout@v3
@@ -99,7 +99,7 @@ jobs:
     permissions:
       contents: write # required for "JamesIves/github-pages-deploy-action"
     timeout-minutes: 30
-    runs-on: intel-ubuntu-latest
+    runs-on: ${{ github.repository_owner == 'intel' && 'intel-ubuntu-latest' || 'ubuntu-latest' }}
     steps:
       - name: Checkout
         uses: actions/checkout@v3
@@ -137,7 +137,7 @@ jobs:
     permissions:
       contents: write # required for "JamesIves/github-pages-deploy-action"
     timeout-minutes: 30
-    runs-on: intel-ubuntu-latest
+    runs-on: ${{ github.repository_owner == 'intel' && 'intel-ubuntu-latest' || 'ubuntu-latest' }}
     steps:
       - name: Checkout
         uses: actions/checkout@v3

.pubignore

@@ -0,0 +1 @@
+confapp

lib/src/arbiters/arbiter.dart

@@ -2,7 +2,7 @@
 // SPDX-License-Identifier: BSD-3-Clause
 //
 // arbiter.dart
-// Implementation of arbiters.
+// Definition for an interface for a generic arbiter.
 //
 // 2023 March 13
 // Author: Max Korbel <[email protected]>

lib/src/arbiters/arbiters.dart

@@ -1,3 +1,6 @@
+// Copyright (C) 2023 Intel Corporation
+// SPDX-License-Identifier: BSD-3-Clause
+
 export 'arbiter.dart';
 export 'mask_round_robin_arbiter.dart';
 export 'priority_arbiter.dart';

lib/src/arbiters/mask_round_robin_arbiter.dart

@@ -1,7 +1,15 @@
+// Copyright (C) 2023 Intel Corporation
+// SPDX-License-Identifier: BSD-3-Clause
+//
+// mask_round_robin_arbiter.dart
+// Implementation of a masked round-robin arbiter.
+//
+// 2023
+
 import 'package:rohd/rohd.dart';
 import 'package:rohd_hcl/rohd_hcl.dart';
 
-/// Round Robin Arbiter.
+/// A [RoundRobinArbiter] implemented using request and grant masks.
 class MaskRoundRobinArbiter extends StatefulArbiter
     implements RoundRobinArbiter {
   /// Mask to define pending requests to be attended
@@ -51,8 +59,6 @@ class MaskRoundRobinArbiter extends StatefulArbiter
           // In case [_grants] are all 0s, requestMask gets a reset
         ], defaultItem: [
           // leave request mask as-is if there was no grant
-          //TODO: bug, shouldn't reset masks if no grants!
-          // for (var g = 0; g < count; g++) _requestMask[g] < 1,
         ])
       ])
     ]);

lib/src/arbiters/priority_arbiter.dart

@@ -1,3 +1,12 @@
+// Copyright (C) 2023 Intel Corporation
+// SPDX-License-Identifier: BSD-3-Clause
+//
+// priority_arbiter.dart
+// Implementation of a priority arbiter.
+//
+// 2023 March 13
+// Author: Max Korbel <[email protected]>
+
 import 'package:rohd/rohd.dart';
 import 'package:rohd_hcl/rohd_hcl.dart';
 

lib/src/arbiters/rotate_round_robin_arbiter.dart

@@ -1,7 +1,16 @@
+// Copyright (C) 2023 Intel Corporation
+// SPDX-License-Identifier: BSD-3-Clause
+//
+// rotate_round_robin_arbiter.dart
+// Implementation of arbiters.
+//
+// 2023
+// Author: Max Korbel <[email protected]>
+
 import 'package:rohd/rohd.dart';
 import 'package:rohd_hcl/rohd_hcl.dart';
 
-/// A round-robin arbiter.
+/// A [RoundRobinArbiter] implemented using rotations and a [PriorityArbiter].
 class RotateRoundRobinArbiter extends StatefulArbiter
     implements RoundRobinArbiter {
   /// Creates an [Arbiter] that fairly takes turns between [requests].

lib/src/arbiters/round_robin_arbiter.dart

@@ -1,7 +1,18 @@
+// Copyright (C) 2023 Intel Corporation
+// SPDX-License-Identifier: BSD-3-Clause
+//
+// round_robin_arbiter.dart
+// Interface for round-robin arbiters.
+//
+// 2023 December
+// Author: Max Korbel <[email protected]>
+
 import 'package:rohd/rohd.dart';
 import 'package:rohd_hcl/rohd_hcl.dart';
 
+/// A [StatefulArbiter] which fairly arbitrates between requests.
 abstract class RoundRobinArbiter extends StatefulArbiter {
+  /// By default, creates an instance of a [MaskRoundRobinArbiter].
   factory RoundRobinArbiter(List<Logic> requests,
           {required Logic clk, required Logic reset}) =>
       MaskRoundRobinArbiter(requests, clk: clk, reset: reset);

lib/src/arbiters/stateful_arbiter.dart

@@ -1,14 +1,31 @@
+// Copyright (C) 2023 Intel Corporation
+// SPDX-License-Identifier: BSD-3-Clause
+//
+// stateful_arbiter.dart
+// Implementation of an arbiter that holds state.
+//
+// 2023 December
+// Author: Max Korbel <[email protected]>
+
 import 'package:meta/meta.dart';
 import 'package:rohd/rohd.dart';
 import 'package:rohd_hcl/rohd_hcl.dart';
 
+/// An [Arbiter] which holds state in order to arbitrate.
 abstract class StatefulArbiter extends Arbiter {
+  /// The clock used for sequential elements.
+  ///
+  /// Should only be used by implementations.
   @protected
   late final Logic clk = input('clk');
 
+  /// The reset used for sequential elements (active high).
+  ///
+  /// Should only be used by implementations.
   @protected
   late final Logic reset = input('reset');
 
+  /// Creates a new [StatefulArbiter] with associated [clk] and [reset].
   StatefulArbiter(super.requests, {required Logic clk, required Logic reset}) {
     addInput('clk', clk);
     addInput('reset', reset);

lib/src/component_config/components/component_registry.dart

@@ -8,12 +8,14 @@
 // Author: Max Korbel <[email protected]>
 
 import 'package:rohd_hcl/rohd_hcl.dart';
+import 'package:rohd_hcl/src/component_config/components/config_round_robin_arbiter.dart';
 
 /// A list of [Configurator]s for ROHD-HCL components.
 List<Configurator> get componentRegistry => [
       RotateConfigurator(),
       FifoConfigurator(),
       PriorityArbiterConfigurator(),
+      RoundRobinArbiterConfigurator(),
       RippleCarryAdderConfigurator(),
       CarrySaveMultiplierConfigurator(),
       BitonicSortConfigurator(),

lib/src/component_config/components/components.dart

@@ -8,4 +8,5 @@ export 'config_priority_arbiter.dart';
 export 'config_rf.dart';
 export 'config_ripple_carry_adder.dart';
 export 'config_rotate.dart';
+export 'config_round_robin_arbiter.dart';
 export 'config_sort.dart';

lib/src/component_config/components/config_rotate.dart

@@ -17,7 +17,7 @@ import 'package:rohd_hcl/rohd_hcl.dart';
 class RotateConfigurator extends Configurator {
   /// A knob controlling the direction of rotation.
   final directionKnob = ChoiceConfigKnob<RotateDirection>(
-    [RotateDirection.left, RotateDirection.right],
+    RotateDirection.values,
     value: RotateDirection.right,
   );
 

lib/src/component_config/components/config_round_robin_arbiter.dart

@@ -0,0 +1,53 @@
+// Copyright (C) 2023 Intel Corporation
+// SPDX-License-Identifier: BSD-3-Clause
+//
+// config_round_robin_arbiter.dart
+// Configurator for a PriorityArbiter.
+//
+// 2023 December 26
+// Author: Max Korbel <[email protected]>
+
+import 'dart:collection';
+
+import 'package:rohd/rohd.dart';
+import 'package:rohd_hcl/rohd_hcl.dart';
+
+/// The type of round-robin arbiter.
+enum RoundRobinImplmentation {
+  /// A [MaskRoundRobinArbiter].
+  mask,
+
+  /// A [RotateRoundRobinArbiter]
+  rotate
+}
+
+/// A [Configurator] for [PriorityArbiter].
+class RoundRobinArbiterConfigurator extends Configurator {
+  /// A knob controlling the number of requests and grants.
+  final IntConfigKnob numRequestKnob = IntConfigKnob(value: 8);
+
+  /// A knob controlling the implementation.
+  final ChoiceConfigKnob<RoundRobinImplmentation> implementationKnob =
+      ChoiceConfigKnob(RoundRobinImplmentation.values,
+          value: RoundRobinImplmentation.mask);
+
+  @override
+  final String name = 'Round Robin Arbiter';
+
+  @override
+  late final Map<String, ConfigKnob<dynamic>> knobs = UnmodifiableMapView({
+    'Number of Requestors': numRequestKnob,
+    'Implementation': implementationKnob,
+  });
+
+  @override
+  Module createModule() {
+    final reqs = List.generate(numRequestKnob.value, (i) => Logic());
+    switch (implementationKnob.value) {
+      case RoundRobinImplmentation.mask:
+        return MaskRoundRobinArbiter(reqs, clk: Logic(), reset: Logic());
+      case RoundRobinImplmentation.rotate:
+        return RotateRoundRobinArbiter(reqs, clk: Logic(), reset: Logic());
+    }
+  }
+}