Guide

Overview

SimuHW is a behavioral hardware simulator provided as a Python module.

Python 3.11 or later is required.

Installation

Release Version

You can install the release version by the following command.

$ python -m pip install simuhw

Development Version

You can install the development version by the following commands.

$ cd simuhw   # the repository root directory
$ make req
$ make dist
$ python -m pip install --no-index --find-links=./dist simuhw

Usage

Concept

Word: a chunk of bits being transferred by wires.
Device: a hardware element such as a wire, switching devices, and memory devices.
Channel: a wire to transfer words.
Memory: a memory device to memorize words associated with specific addresses.
Port: an endpoint provided by a device to input or output words.
Probe: an entity to record word values with the respective times, whenever the value of the word passing through a specific port or stored at a specific address in a memory changes.

Import of Module

To use SimuHW, import simuhw module. An example is shown below.

import simuhw as hw

Simulation of Hardware Devices

Create instances of the derived classes of Device class. As of version 0.3.0, the following device classes are available.
- Utility
- Clock
  - Clock
- Channel
  - Channel
  - MultiplexChannel
- Branch
- Elementary Combinational Circuit
  - BufferGate
  - NOTGate
  - ANDGate
  - ORGate
  - XORGate
  - NANDGate
  - NORGate
  - XNORGate
- Elementary Sequential Circuit
  - DLatch
  - DFlipFlop
- Counter
  - SynchronousBinaryCounter74161
  - SynchronousBinaryCounter74163
- Bit Operation
- Integer Arithmetic
- Memory
  - LevelTriggeredMemory
  - EdgeTriggeredMemory
An example is shown below.
```
width: int = 16  # Word size in bits
source: hw.Source = hw.Source(width, [
    (b'\x00\x01', 0.0e-9),
    (b'\xc1\x85', 3.0e-9),
    (b'\xd3\xbb', 6.0e-9),
    (b'\xf2\x3a', 10.0e-9)
])
drain: hw.Drain = hw.Drain(width)
```
Connect the output ports to the input ports of the device class instances. An example is shown below.
```
source.port_o.connect(drain.port_i)
```
Create instances of ChannelProbe class or MemoryProbe class. ChannelProbe class instances can be added to input ports or output ports, and MemoryProbe class instances can be added to instances of the derived classes of Memory class. An example is shown below.
```
probe: hw.ChannelProbe = hw.ChannelProbe('out', width)
```
Add the probes to the ports or the memory. An example is shown below.
```
drain.port_i.add_probe(probe)
```
Create an instances of LogicAnalyzer class. An example is shown below.
```
la: hw.LogicAnalyzer = hw.LogicAnalyzer()
```
Add the probes to the logic analyzer. An example is shown below.
```
la.add_probe(probe)
```
Create an instance of Simulator class. An example is shown below.
```
sim: hw.Simulator = hw.Simulator([source, drain])
```
Start the simulation. An example is shown below.
```
sim.start()
```
Save the word value change timings recorded in the probes to a VCD file. An example is shown below.
```
with open('test.vcd', mode='w') as file:
    la.save_as_vcd(file)
```
View the VCD file using a waveform viewer such as GTKWave.

The whole source code of the example above is shown below.

import simuhw as hw

width: int = 16  # Word size in bits
source: hw.Source = hw.Source(width, [
    (b'\x00\x01', 0.0e-9),
    (b'\xc1\x85', 3.0e-9),
    (b'\xd3\xbb', 6.0e-9),
    (b'\xf2\x3a', 10.0e-9)
])
drain: hw.Drain = hw.Drain(width)
source.port_o.connect(drain.port_i)
probe: hw.ChannelProbe = hw.ChannelProbe('out', width)
drain.port_i.add_probe(probe)
la: hw.LogicAnalyzer = hw.LogicAnalyzer()
la.add_probe(probe)
sim: hw.Simulator = hw.Simulator([source, drain])
sim.start()
with open('test.vcd', mode='w') as file:
    la.save_as_vcd(file)

This example simulates a Source device and a Drain device which are connected directly, and saves word value change timings at the input port of the Drain device to the file test.vcd.