Cache2 subset (#281)

* Reorganized filesystem, especially memories/

* Added `ReadyValidInterface` and `ReadyValidFifo`

* Added `Cam` component

* Documentation 'How to build a great component'

* Migrated to `addTypedInput` on components

Author: desmonddak

README.md

@@ -50,7 +50,5 @@ Some examples of component categories include:
 - Standard interfaces
 - Models
 
-----------------
-
 Copyright (C) 2023-2025 Intel Corporation  
 SPDX-License-Identifier: BSD-3-Clause

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/Component.md

@@ -0,0 +1,164 @@
+# 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.
+
+Since ROHD is written in Dart, you should use the Dart best practices, such as
+camel-case variable naming, commenting patterns for all public APIs, and take
+advantage of dart format and dart analyze tools.
+
+## 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 multidimensional 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 midway 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,7 @@ 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
+  - [Cams](./components/memory.md#basic-cam)
   - [Memory Model](./components/memory.md#memory-models)
   - [Control/Status Registers (CSRs)](./components/csr.md)
 - Standard interfaces
@@ -136,6 +135,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 [Component](./Component.md.md) for the best practices for creating new components.
+
 ----------------
 
 Copyright (C) 2023-2025 Intel Corporation  

doc/components/memory.md

@@ -4,11 +4,11 @@ ROHD-HCL provides a generic `abstract` [`Memory`](https://intel.github.io/rohd-h
 
 ## Masks
 
-A sub-class of `DataPortInterface` is the[`MaskedDataPortInterface`](https://intel.github.io/rohd-hcl/rohd_hcl/MaskedDataPortInterface-class.html), which adds `mask` to the `data` group of signals.  The `mask` signal is a byte-enable signal, where each bit of `mask` controls one byte of `data`.
+A subclass of `DataPortInterface` is the[`MaskedDataPortInterface`](https://intel.github.io/rohd-hcl/rohd_hcl/MaskedDataPortInterface-class.html), which adds `mask` to the `data` group of signals.  The `mask` signal is a byte-enable signal, where each bit of `mask` controls one byte of `data`.
 
 ## Register Files
 
-A sub-class of `Memory` is the [`RegisterFile`](https://intel.github.io/rohd-hcl/rohd_hcl/RegisterFile-class.html), which inherits the same flexible interface from `Memory`.  It has a configurable number of entries via `numEntries`.
+A subclass of `Memory` is the [`RegisterFile`](https://intel.github.io/rohd-hcl/rohd_hcl/RegisterFile-class.html), which inherits the same flexible interface from `Memory`.  It has a configurable number of entries via `numEntries`.
 
 The `RegisterFile` accepts masks on writes, but not on reads.
 
@@ -20,8 +20,82 @@ The `RegisterFile` can be initialized with data on reset using `resetValue` foll
 
 [RegisterFile Schematic](https://intel.github.io/rohd-hcl/RegisterFile.html)
 
+## First-In First-Out (FIFO) Buffers
+
+Please see [`Fifo`](./fifo.md)
+
 ## Memory Models
 
 The `MemoryModel` has the same interface as a `Memory`, but is non-synthesizable and uses a software-based `SparseMemoryStorage` as a backing for data storage. This is a useful tool for testing systems that have relatively large memories.
 
-The `MemoryStorage` class also provides utilities for reading (`loadMemString`) and writing (`dumpMemString`) verilog-compliant memory files (e.g. for `readmemh`).
+The `MemoryStorage` class also provides utilities for reading (`loadMemString`) and writing (`dumpMemString`) Verilog-compliant memory files (e.g. for `readmemh`).
+
+## Cam
+
+A content-addressable memory or `Cam` is provided which allows for associative lookup using a `tag` that produces an index to help with building specialized forms of caches where the actual data is stored in a separate register file. The index is to be separately used as a linear address in another component (like a `RegisterFile`) to find the associated data.  In this case the `tag` is matched during a read and the position in memory is returned, which is the index. For the fill ports, the user can simply write a new tag at a given index location. This means the `Cam` is a fine-grained component for use in building associative look of positions of objects in another memory.
+
+Both write and lookup ports use the `TagInterface`, which provides a consistent interface for CAM operations:
+
+- For **writes**: `en` enables the write, `idx` specifies the destination address, `tag` is the data to write, and `hit` sets/clears the valid bit for the entry (hit=1 marks entry valid, hit=0 marks entry invalid).
+- For **lookups**: `tag` is the query, `idx` returns the matching index, and `hit` indicates whether a valid match was found. Only entries with their valid bit set will match.
+
+Each CAM entry has a valid bit that must be set for the entry to participate in lookups. This allows distinguishing between "entry contains tag 0x00" and "entry is empty/invalid".
+
+### Read-with-Invalidate Pattern
+
+A read-with-invalidate operation can be implemented by using a dedicated write port wired to the lookup port's outputs:
+
+- Wire `invalidatePort.idx <= lookupPort.idx` to target the found entry
+- Wire `invalidatePort.tag <= lookupPort.tag` to match the lookup
+- Set `invalidatePort.hit = 0` (always invalidate, never validate)
+- Set `invalidatePort.en = lookupPort.hit` (only invalidate if found)
+
+This pattern allows atomic "find and remove" operations where the lookup returns the matching index while simultaneously invalidating that entry.
+
+An example use is:
+
+```dart
+      const tagWidth = 8;
+      const numEntries = 4;
+      const idWidth = 2;
+
+      final clk = SimpleClockGenerator(10).clk;
+      final reset = Logic();
+
+      final writePort = TagInterface(idWidth, tagWidth);
+      final invalidatePort = TagInterface(idWidth, tagWidth);
+      final lookupPort = TagInterface(idWidth, tagWidth);
+
+      final cam = Cam(
+        clk,
+        reset,
+        [writePort, invalidatePort],
+        [lookupPort],
+        numEntries: numEntries,
+      );
+
+      // Wire invalidatePort to use lookupPort's combinational output
+      invalidatePort.idx <= lookupPort.idx;
+      invalidatePort.tag <= lookupPort.tag;
+      invalidatePort.hit.inject(0);  // Always clear valid bit
+
+      // Write tag 0x99 to index position 1 (hit=1 marks it valid)
+      writePort.en.inject(1);
+      writePort.hit.inject(1);
+      writePort.idx.inject(1);
+      writePort.tag.inject(0x99);
+      await clk.nextPosedge;
+
+      // Lookup tag 0x99 without invalidate
+      lookupPort.tag.inject(0x99);
+      invalidatePort.en.inject(0);
+      await clk.nextPosedge;
+      // We found our matching tag at index 1 where we stored it!
+      expect(lookupPort.idx.value.toInt(), equals(1),
+          reason: 'Should return index 1');
+
+      // Lookup and invalidate: enable invalidatePort when hit
+      invalidatePort.en.inject(1);  // Invalidate on hit
+      await clk.nextPosedge;
+      // Entry is now invalidated - subsequent lookup will miss
+```

lib/rohd_hcl.dart

@@ -13,7 +13,6 @@ export 'src/encodings/encodings.dart';
 export 'src/error_checking/error_checking.dart';
 export 'src/exceptions.dart';
 export 'src/extrema.dart';
-export 'src/fifo.dart';
 export 'src/find.dart';
 export 'src/find_pattern.dart';
 export 'src/gaskets/gaskets.dart';
@@ -23,10 +22,8 @@ export 'src/models/models.dart';
 export 'src/priority_encoder.dart';
 export 'src/reduction_tree.dart';
 export 'src/reduction_tree_generator.dart';
-export 'src/resettable_entries.dart';
 export 'src/rotate.dart';
 export 'src/serialization/serialization.dart';
-export 'src/shift_register.dart';
 export 'src/signed_shifter.dart';
 export 'src/sort.dart';
 export 'src/static_or_runtime_parameter.dart';

lib/src/arithmetic/fixed_sqrt.dart

@@ -23,7 +23,7 @@ abstract class FixedPointSqrtBase extends Module {
   late final FixedPoint a;
 
   /// getter for the computed output.
-  late final FixedPoint sqrt = a.clone(name: 'sqrt')..gets(output('sqrt'));
+  late final FixedPoint sqrt;
 
   /// Square root a fixed point number [a], returning result in [sqrt].
   FixedPointSqrtBase(FixedPoint a,
@@ -35,9 +35,9 @@ abstract class FixedPointSqrtBase extends Module {
         super(
             definitionName:
                 definitionName ?? 'FixedPointSquareRoot${a.width}') {
-    this.a = a.clone(name: 'a')..gets(addInput('a', a, width: a.width));
+    this.a = addTypedInput('a', a);
 
-    addOutput('sqrt', width: width);
+    sqrt = addTypedOutput('sqrt', a.clone);
   }
 }