Serial Peripheral Interface

doc/README.md

@@ -109,14 +109,14 @@ Some in-development items will have opened issues, as well. Feel free to create
   - PCIe
   - UCIe
   - JTAG
-  - SPI
+  - [SPI](./components/standard_interfaces.md#spi)
   - UART
   - DDR
   - HBM
 - Models
   - [APB](./components/apb_bfm.md)
   - [Ready/Valid](./components/ready_valid_bfm.md)
-  - SPI
+  - [SPI](./components/spi_bfm.md)
   - CXL
 
 ----------------

doc/components/spi_bfm.md

@@ -0,0 +1,17 @@
+# SPI BFM
+
+The SPI BFM is a collection of [ROHD-VF](https://github.com/intel/rohd-vf) components and objects that are helpful for validating hardware that contains an SPI interface.  It includes all the basic SPI interface features for sending and responding to data between a main-sub connection.
+
+The main two components are the `SpiMainAgent` and the `SpiSubAgent`, which behave like a "Main" and "Sub" as commonly seen in SPI implementations. Both have a standard `Sequencer` that accepts `SpiPacket`s to be driven out to each other.  Both also have a corresponding `Driver` as `SpiMainDriver` and `SpiSubDriver`, respectively, that handle the driving of data onto the `SpiInterface`.
+
+An `SpiMonitor` is also included, which implements the standard `Monitor` and provides a stream of `SpiPacket`s monitored on positive edges of the clock.  The `SpiTracker` can be used to log all items detected by the monitor by implementing the standard `Tracker` API (log file or JSON both supported).
+
+Finally, a `SpiChecker` monitors an `SpiInterface` for a subset of the rules commonly used in SPI implementations. Errors are flagged using the `severe` log messages, as is standard for errors in ROHD-VF.
+
+The unit tests in `spi_bfm_test.dart`, which have a main and sub communicating with each other, are a good example for setting up the SPI BFM. The unit test in `spi_gaskets_test` also have good example of the SPI BFM interacting with their corresponding hardware components.
+
+## Unsupported features
+
+The following features are currently not supported by or have no utilities within the BFM:
+
+- **CPOL/CPHA**: different clock polarity and clock phase are not considered, the BFM is implemented with a SPI Mode = 0 (CPOL/CPHA = 0).

doc/components/spi_gaskets.md

@@ -0,0 +1,37 @@
+# SPI Gaskets
+
+ROHD-HCL implements a `SpiMain` and `SpiSub` set of components that enable communication via a Serial Peripheral Interface.
+
+## SpiMain
+
+Interacts as the provider on the `SpiInterface`.
+
+The inputs to the `SpiMain` component are:
+
+* `clk` => clock for synchronous logic and driving `SpiInterface.sclk`
+* `reset` => asynchronous reset for component and to reset `busIn` values
+* `start` => to initiate a data transfer
+* `busIn` => to load data to transmit
+
+The outputs to the `SpiSub` component are:
+
+* `busOut` => to output data received
+* `done` => signals completion of a data transfer
+
+When data is available on `busIn`, pulsing `reset` will load the data into the internal shift register. Pulsing `start` will make `SpiInterface.csb` active and begin driving a clock signal on `SpiInterface.sclk`. On every clock pulse data will shift out onto `SpiInterface.mosi` and shift in from `SpiInterface.miso`. Data shifted in will be avaible on `busOut`. The `done` signal will indicate when transmissions are complete.
+
+## SpiSub
+
+Interacts as the consumer on the `SpiInterface`.
+
+The inputs to the `SpiSub` component are:
+
+* `reset` => optional input, asynchronous reset for component and to reset `busIn` values
+* `busIn` => optional input, to load data to transmit
+
+The outputs to the `SpiSub` component are:
+
+* `busOut` => to output data received
+* `done` => signals completion of a data transfer
+
+When data is available on `busIn`, pulsing `reset` will load the data into the internal shift register. When `SpiInterface.csb` is active and clock signal is present on `SpiInterface.sclk`, data will shift out onto `SpiInterface.miso` and shift in from `SpiInterface.mosi`. Data shifted in will be avaible on `busOut`. The `done` signal will indicate when transmissions are complete.

doc/components/standard_interfaces.md

@@ -5,3 +5,7 @@ ROHD-HCL provides a set of standard interfaces using ROHD `Interface`s.  This ma
 ## APB
 
 The [ABP Interface](https://developer.arm.com/documentation/ihi0024/latest/) is a standard AMBA interface.  ROHD HCL has a configurable version of the APB interface called [`ApbInterface`](https://intel.github.io/rohd-hcl/rohd_hcl/ApbInterface-class.html).
+
+## SPI
+
+The Serial Peripheral Interface (SPI) is a common serial communicaton interface. ROHD HCL has a configurable version of the SPI interface called [`SpiInterface`](https://intel.github.io/rohd-hcl/rohd_hcl/SpiInterface-class.html).

lib/rohd_hcl.dart

@@ -1,4 +1,4 @@
-// Copyright (C) 2023-2024 Intel Corporation
+// Copyright (C) 2023-2025 Intel Corporation
 // SPDX-License-Identifier: BSD-3-Clause
 
 export 'src/arbiters/arbiters.dart';
@@ -14,6 +14,7 @@ export 'src/exceptions.dart';
 export 'src/extrema.dart';
 export 'src/fifo.dart';
 export 'src/find.dart';
+export 'src/gaskets/spi/spi_gaskets.dart';
 export 'src/interfaces/interfaces.dart';
 export 'src/memory/memories.dart';
 export 'src/models/models.dart';

lib/src/gaskets/spi/spi_gaskets.dart

@@ -0,0 +1,5 @@
+// Copyright (C) 2024-2025 Intel Corporation
+// SPDX-License-Identifier: BSD-3-Clause
+
+export 'spi_main.dart';
+export 'spi_sub.dart';

lib/src/gaskets/spi/spi_main.dart

@@ -0,0 +1,101 @@
+// Copyright (C) 2024-2025 Intel Corporation
+// SPDX-License-Identifier: BSD-3-Clause
+//
+// spi_main.dart
+// Implementation of SPI Main component.
+//
+// 2024 October 1
+// Author: Roberto Torres <roberto.torres@intel.com>
+
+import 'package:rohd/rohd.dart';
+import 'package:rohd_hcl/rohd_hcl.dart';
+
+/// Main component for Serial Peripheral Interface (SPI).
+class SpiMain extends Module {
+  /// Output bus from Main.
+  Logic get busOut => output('busOut');
+
+  /// Done signal from Main.
+  Logic get done => output('done');
+
+  /// Creates a SPI Main component that interfaces with [SpiInterface].
+  ///
+  /// The SPI Main component will drive a clock signal on [SpiInterface.sclk],
+  /// chip select on [SpiInterface.csb], shift data out on [SpiInterface.mosi],
+  /// and shift data in from [SpiInterface.miso]. Data to shift out is provided
+  /// on [busIn]. Data shifted in from [SpiInterface.miso] will be available on
+  /// [busOut]. After data is available on [busIn], pulsing [reset] will load
+  /// the data, and pulsing [start] will begin transmitting data until all bits
+  /// from [busIn] are shifted out. After transmissions is complete [done]
+  /// signal will go high.
+  SpiMain(SpiInterface intf,
+      {required Logic clk,
+      required Logic reset,
+      required Logic start,
+      required Logic busIn,
+      super.name = 'spiMain'}) {
+    busIn = addInput('busIn', busIn, width: busIn.width);
+
+    clk = addInput('clk', clk);
+
+    reset = addInput('reset', reset);
+
+    start = addInput('start', start);
+
+    addOutput('busOut', width: busIn.width);
+
+    addOutput('done');
+
+    intf = SpiInterface.clone(intf)
+      ..pairConnectIO(this, intf, PairRole.provider);
+
+    final isRunning = Logic(name: 'isRunning');
+
+    // Counter to track of the number of bits shifted out.
+    final count = Counter.simple(
+        clk: ~clk,
+        enable: start | isRunning,
+        reset: reset,
+        asyncReset: true,
+        minValue: 1,
+        maxValue: busIn.width);
+
+    // Done signal will be high when the counter is at the max value.
+    done <= count.equalsMax;
+
+    // isRunning will be high when start is pulsed high or counter is not done.
+    isRunning <=
+        flop(
+          clk,
+          start | ~done,
+          reset: reset,
+          asyncReset: true,
+        );
+
+    // Shift register in from MISO.
+    // NOTE: Reset values are set to busIn values.
+    final shiftReg = ShiftRegister(
+      intf.miso,
+      clk: intf.sclk,
+      depth: intf.dataLength,
+      reset: reset,
+      asyncReset: true,
+      resetValue: busIn.elements,
+    );
+
+    // busOut bits are connected to the corresponding shift register data stage.
+    // NOTE: dataStage0 corresponds to the last bit shifted in.
+    busOut <= shiftReg.stages.rswizzle();
+
+    // SCLK runs off clk when isRunning is true or start is pulsed high.
+    intf.sclk <= ~clk & (isRunning | start);
+
+    // CS is active low. It will go low when isRunning or start is pulsed high.
+    intf.csb <= ~(isRunning | start);
+
+    // MOSI is connected shift register dataOut.
+    intf.mosi <=
+        flop(~intf.sclk, shiftReg.dataOut,
+            reset: reset, asyncReset: true, resetValue: busIn[-1]);
+  }
+}

lib/src/gaskets/spi/spi_sub.dart

@@ -0,0 +1,93 @@
+// Copyright (C) 2024-2025 Intel Corporation
+// SPDX-License-Identifier: BSD-3-Clause
+//
+// spi_sub.dart
+// Implementation of SPI Sub component.
+//
+// 2024 October 4
+// Author: Roberto Torres <roberto.torres@intel.com>
+
+import 'package:rohd/rohd.dart';
+import 'package:rohd_hcl/rohd_hcl.dart';
+
+/// Sub component for Serial Peripheral Interface (SPI).
+class SpiSub extends Module {
+  /// Output bus from Sub.
+  Logic get busOut => output('busOut');
+
+  /// Done signal from Sub.
+  Logic get done => output('done');
+
+  /// Creates a SPI Sub component that interfaces with [SpiInterface].
+  ///
+  /// The SPI Sub component will enable via chip select from [SpiInterface.csb].
+  /// Clock signal will be received on [SpiInterface.sclk], data will shift in
+  /// from [SpiInterface.mosi], and shift data out from [SpiInterface.miso].
+  /// Data shifted in from [SpiInterface.mosi] will be available on [busOut].
+  ///
+  /// If [busIn] and [reset] are provided, data to shift out will be loaded from
+  /// [busIn]. After data is available on [busIn], pulsing [reset] will load the
+  /// data asynchronously, and a bit of data will be transmitted per pulse of
+  /// [SpiInterface.sclk]. After all data is shifted out, an optional [done]
+  /// signal will indicate completion.
+  SpiSub(
+      {required SpiInterface intf,
+      Logic? busIn,
+      Logic? reset,
+      super.name = 'spiSub'}) {
+    // SPI Interface
+    intf = SpiInterface.clone(intf)
+      ..pairConnectIO(this, intf, PairRole.consumer);
+
+    // Bus Input to sub, if provided.
+    if (busIn != null) {
+      busIn = addInput('busIn', busIn, width: intf.dataLength);
+    }
+
+    // Reset signal for sub, if provided.
+    if (reset != null) {
+      reset = addInput('reset', reset);
+    }
+
+    // Bus Output from Sub
+    addOutput('busOut', width: intf.dataLength);
+
+    addOutput('done');
+
+    // Counter to track of the number of bits shifted out.
+    final count = Counter.simple(
+        clk: intf.sclk,
+        enable: ~intf.csb,
+        reset: reset ?? Const(0, width: 1),
+        asyncReset: true,
+        minValue: 1,
+        maxValue: intf.dataLength);
+
+    // Done signal will be high when the counter is at the max value.
+    done <= count.equalsMax;
+
+    // Shift Register in from MOSI.
+    // NOTE: Reset values are set to busIn values.
+    final shiftReg = ShiftRegister(
+      intf.mosi,
+      enable: ~intf.csb,
+      clk: intf.sclk,
+      depth: intf.dataLength,
+      reset: reset,
+      asyncReset: true,
+      resetValue: busIn?.elements,
+    );
+
+    // busOut bits are connected to the corresponding shift register data stage.
+    // NOTE: dataStage0 corresponds to the last bit shifted in.
+    busOut <= shiftReg.stages.rswizzle();
+
+    // MISO is connected to shift register dataOut.
+    intf.miso <=
+        flop(~intf.sclk, shiftReg.dataOut,
+            en: ~intf.csb,
+            reset: reset,
+            asyncReset: true,
+            resetValue: busIn?[-1]);
+  }
+}

lib/src/interfaces/interfaces.dart

@@ -2,3 +2,4 @@
 // SPDX-License-Identifier: BSD-3-Clause
 
 export 'apb.dart';
+export 'spi.dart';

lib/src/interfaces/spi.dart

@@ -0,0 +1,39 @@
+// Copyright (C) 2024-2025 Intel Corporation
+// SPDX-License-Identifier: BSD-3-Clause
+//
+// spi.dart
+// Definitions for Serial Peripheral Interface (SPI).
+//
+// 2024 September 23
+// Author: Roberto Torres <roberto.torres@intel.com>
+
+import 'package:rohd/rohd.dart';
+
+/// A standard Serial Peripheral Interface.
+class SpiInterface extends PairInterface {
+  /// The data length for serial transmissions on this interface.
+  final int dataLength;
+
+  /// Serial clock (SCLK). Clock signal from main to sub(s).
+  Logic get sclk => port('SCLK');
+
+  /// Main Out Sub In (MOSI). Serial data from main to sub(s).
+  Logic get mosi => port('MOSI');
+
+  /// Main In Sub Out (MISO). Serial data from sub(s) to main.
+  Logic get miso => port('MISO');
+
+  /// Chip select (active low). Chip select signal from main to sub.
+  Logic get csb => port('CSB');
+
+  /// Creates a new [SpiInterface].
+  SpiInterface({this.dataLength = 1})
+      : super(
+            portsFromConsumer: [Port('MISO')],
+            portsFromProvider: [Port('MOSI'), Port('CSB'), Port('SCLK')]);
+
+  /// Clones this [SpiInterface].
+  SpiInterface.clone(SpiInterface super.otherInterface)
+      : dataLength = otherInterface.dataLength,
+        super.clone();
+}

lib/src/models/models.dart

@@ -5,3 +5,4 @@ export 'apb_bfm/apb_bfm.dart';
 export 'memory_model.dart';
 export 'ready_valid_bfm/ready_valid_bfm.dart';
 export 'sparse_memory_storage.dart';
+export 'spi_bfm/spi_bfm.dart';

lib/src/models/spi_bfm/spi_bfm.dart

@@ -0,0 +1,17 @@
+// Copyright (C) 2024 Intel Corporation
+// SPDX-License-Identifier: BSD-3-Clause
+//
+// spi_bfm.dart
+// BFM for SPI interface
+//
+// 2024 September 23
+// Author: Roberto Torres <roberto.torres@intel.com>
+
+export 'spi_checker.dart';
+export 'spi_main_agent.dart';
+export 'spi_main_driver.dart';
+export 'spi_monitor.dart';
+export 'spi_packet.dart';
+export 'spi_sub_agent.dart';
+export 'spi_sub_driver.dart';
+export 'spi_tracker.dart';