new components: cam and replacement

confapp/lib/hcl/view/screen/content_widget.dart

@@ -35,7 +35,8 @@ class SVGenerator extends StatefulWidget {
   State createState() => _SVGeneratorState();
 }
 
-class _SVGeneratorState extends State<SVGenerator> {
+class _SVGeneratorState extends State<SVGenerator>
+    with SingleTickerProviderStateMixin {
   final GlobalKey<FormState> _formKey = GlobalKey<FormState>();
   final ButtonStyle btnStyle =
       ElevatedButton.styleFrom(textStyle: const TextStyle(fontSize: 20));
@@ -148,7 +149,44 @@ class _SVGeneratorState extends State<SVGenerator> {
           ],
         ),
         for (final (index, subKnob) in knob.knobs.indexed)
-          _generateKnobControl('$index', subKnob),
+          // Animate size and add/remove transitions for each generated item.
+          // AnimatedSize handles height changes; AnimatedSwitcher provides
+          // a fade/size transition when items are added/removed.
+          AnimatedSize(
+            key: ValueKey('${knob.name}-$index-anim'),
+            duration: const Duration(milliseconds: 250),
+            curve: Curves.easeInOut,
+            child: AnimatedSwitcher(
+              duration: const Duration(milliseconds: 200),
+              transitionBuilder: (child, animation) => FadeTransition(
+                opacity: animation,
+                child: SizeTransition(
+                  sizeFactor: animation,
+                  axisAlignment: 0.0,
+                  child: child,
+                ),
+              ),
+              child: Container(
+                key: ValueKey('${knob.name}-$index'),
+                child: subKnob is GroupOfKnobs
+                    ? Column(children: [
+                        _containerOfKnobs(
+                            title: '${subKnob.name} $index',
+                            children: [
+                              for (final subKnobEntry
+                                  in subKnob.subKnobs.entries)
+                                _generateKnobControl(
+                                    subKnobEntry.key, subKnobEntry.value),
+                            ]),
+                        const SizedBox(height: 12),
+                      ])
+                    : Column(children: [
+                        _generateKnobControl('${knob.name} $index', subKnob),
+                        const SizedBox(height: 12),
+                      ]),
+              ),
+            ),
+          ),
       ]);
     } else if (knob is GroupOfKnobs) {
       selector = _containerOfKnobs(title: knob.name, children: [

doc/Module.md

@@ -0,0 +1,157 @@
+# How to Build a Great Component in ROHD
+
+Since ROHD is an extension of the Dart programming language, please follow all
+Dart programming and documentation conventions.
+
+The `Module` class is the base class used in ROHD to build components, and
+calling the constructor the `Module` instantiates the component and connects it
+to signals passed into the constructor.
+
+## Port Construction and Connection
+
+A `Module` constructor takes `Logic` arguments and parameters to generate a
+hardware component. The `Logic` arguments are actually the external signals
+being connected to by the `Module`, and so internal copies must be constructed
+and connected to these arguments by the constructor and only then can other
+logic signals be connected to these copies. If you do not do this, a trace error
+will occur, but that only happens when this module is instantiated in another --
+it will not show up while testing which just instantiates the module in a test
+environment.   See [Modules](https://intel.github.io/rohd-website/docs/modules/)
+for more detail.
+
+A key pattern used in ROHD-HCL is to have the constructor take only input
+signals as arguments and generate the output signal widths based on these
+signals and other parameters.
+
+## Port Types
+
+Signals can take various forms in ROHD and it is important to consider what form
+you want for the API of the `Module` you are building. ROHD supports the basic
+`Logic` signal which has its width encode (therefore you should not be using
+width as a parameter to a `Module`). ROHD provides basic cloning and accessor
+helper functions like `addInput` and `input`.
+
+`LogicArray` is a uniform multi-dimensional array of leaf `Logic` signals. Using
+this for input/output will require special routines like `addInputArray` to
+connect external and internal signals. Examples of using `LogicArray` are in the
+`Serializer` and `Deserializer` components.
+
+`LogicStructure` is a hierarchical concatenation of named `Logic` fields, where
+the `FloatingPoint` arithmetic type is an example used in the
+`FloatingPointMultiplierSimple` module. We can also pass in `LogicStructure` as
+a type for certain components so that the field structure is not lost on input
+and output. A good example of this is `Fifo`, which is templatized on
+`LogicType` to allow for us to generate a `Fifo` for a particular
+`LogicStructure` to use when pushing and popping the data in and out. Here,
+`addTypedInput` is a method used to help with creating the internal signals.
+
+`Interface` is similar to `LogicStructure` yet it provides an ability to define
+directionality to the internal fields, useful in connecting modules that share a
+common protocol such as the `ApbInterface`. See
+[Interfaces](https://intel.github.io/rohd-website/docs/interfaces). A few
+examples of key general interface types that you can inherit from are the
+`PairInterface` and the `DataPortInterface`.  the `Memory` module has a good
+example of how `DataPortInterface`s are cloned internally using its `connectIO`
+method.  
+The `Fifo` has a good example of using an `Interface` to wrap a `LogicStructure`.
+
+When wrapping `LogicStructure` with `Interface`, don't name the `LogicStructure`
+as `Interface` will need to uniquify (a known bug in `Interface`).
+
+An important kind of `Interface` is the `PairInterface` which is designed for
+bidirectional communication and provides a `pairConnectIO` method for connecting
+external and internal ports based on producer/consumer filtering.
+
+## Logic Internals
+
+Signal logic is constructed in a ROHD component by assignment and simple logic
+operations like and (`&`) and or (`|`) as well as multiplexing (`mux`) and
+flopping (`flop`).  See
+[operations](https://intel.github.io/rohd-website/docs/logic-math-compare/) for
+more detail.
+
+ More complex logic can be constructed using
+ [`Sequental`](https://intel.github.io/rohd-website/docs/sequentials/) and
+ [`Combinational`](https://intel.github.io/rohd-website/docs/conditionals/)
+ blocks similar to SystemVerilog `always` blocks.  There is also a
+ [`FiniteStateMachine`](https://intel.github.io/rohd-website/docs/fsm/)
+ construct for state machines and a
+ [`Pipeline`](https://intel.github.io/rohd-website/docs/pipelines/) construct
+ for assisting with pipelined logic.
+
+ Try to minimize the addition of new internal signals, by just reusing the
+ signals created by the ports or by subcomponents.  Use `.named` to create clean
+ SystemVerilog names.
+
+### Debug
+
+ If you want to expose internal signals onto the interface of a `Module` for debug, a simple method is to declare them as a field in the class (Use @protected in case this is exposed so it doesn't become part of the API). This signal will be available in tests as module.field.
+
+## Unit Testing
+
+ A good component has unit tests to validate the component and provide examples
+ of use. We use the Dart testing framework which requires that tests are stored
+ in the `test/` directory and are named ending in `_test.dart`. An example of
+ unit tests for a component is shown below.  Note that grouping of tests can
+ reuse a common component built for multiple tests.  Also note that each test
+ with sequential logic will need a `SimpleClockGenerator`, a `Simulator.run()`
+ and an `endSimulation`. Some helper methods (like `.waitCycles`) are available
+ in the rohd-fv package.
+
+ ```dart
+void main() {
+  tearDown(() async {
+    await Simulator.reset();
+  });
+
+  group('test narrow component', () {
+    final input = Logic(width: 5);
+    final component = MyComponent(input);
+    final output = component.out;
+
+    test('MyComponent smoke test', () async {
+      final clk = SimpleClockGenerator(10).clk;
+
+      unawaited(Simulator.run());
+        reset.inject(1);
+        await clk.waitCycles(3);
+        reset.inject(0);
+        await clk.waitCycles(1);
+        input.inject(1);
+        await clk.waitCycles(3);
+        expect(output.value, equals(Const(1, width: output.width)));
+
+      await Simulator.endSimulation();
+    });
+
+    test('MyComponent second test', () async {
+      final clk = SimpleClockGenerator(10).clk;
+
+      unawaited(Simulator.run());
+        reset.inject(1);
+        await clk.waitCycles(3);
+        reset.inject(0);
+        await clk.waitCycles(1);
+        input.inject(6);
+        await clk.waitCycles(3);
+        expect(output.value, equals(Const(6, width: output.width)));
+
+      await Simulator.endSimulation();
+    });
+  });
+}
+```
+
+Prefer using `waitCycles` instead of `nextPosedge` and use `inject` instead of
+`put` when working with sequential tests.
+
+When testing a combinational path, and you `inject` inputs after a positive
+clock edge, if you sample at the next clock edge, you will miss the
+combinational value.  Instead, use the output `previousValue` at the next clock
+edge, or sample the output at `nextNegEdge` to look at the value mid-way through
+the clock cycle.
+
+While creating unit tests, you can just run the tests for your component instead
+of running the entire suite of ROHD-HCL tests.  The entire regression suite
+takes quite a long time and is only necessary if you make changes to some core
+functionality.

doc/README.md

@@ -109,8 +109,9 @@ Some in-development items will have opened issues, as well. Feel free to create
 - Memory
   - [Register File](./components/memory.md#register-files)
   - [Masking](./components/memory.md#masks)
-  - Replacement Policies
-    - LRU
+  - [Caches](./components/memory.md#caches)
+    - [Replacement Policies](./components/memory.md#replacement-policy)
+  - [Cams](./components/memory.md#basic-cam)
   - [Memory Model](./components/memory.md#memory-models)
   - [Control/Status Registers (CSRs)](./components/csr.md)
 - Standard interfaces
@@ -133,6 +134,10 @@ Some in-development items will have opened issues, as well. Feel free to create
 - Gaskets
   - [SPI](./components/spi_gaskets.md)
 
+## Adding a New Component
+
+Please refer to [Module](./Module.md) for the best practices for creating new components.
+
 ----------------
 
 Copyright (C) 2023-2025 Intel Corporation