simuhw 0.7.3

A behavioral hardware simulator

SimuHW

Overview

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

Python 3.11 or later is required.

The GitHub page is https://github.com/arithy/simuhw.

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 clean
$ 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

1. Create instances of the derived classes of Device class. As of version 0.3.0, the following device classes are available.

   • Utility
     • Source
     • LogicLowSource
     • LogicHighSource
     • LogicUnknownSource
     • HighZSource
     • Drain
     • Delay
     • Group
   • Clock
     • Clock
   • Channel
     • Channel
   • Branch
     • WordCombiner
     • WordSplitter
     • Multiplexer
     • Demultiplexer
     • WordRetainDemultiplexer
     • Junction
     • Distributor
   • Elementary Combinational Circuit
     • Buffer
     • Inverter
     • TriStateBuffer
     • TriStateInverter
     • ANDGate
     • ORGate
     • XORGate
     • NANDGate
     • NORGate
     • XNORGate
   • Elementary Sequential Circuit
     • DLatch
     • DFlipFlop
   • Lookup Table
     • LookupTable
   • Bit Operation
     • LeftShifter
     • RightShifter
     • ArithmeticRightShifter
     • LeftRotator
     • RightRotator
     • PopulationCounter
     • LeadingZeroCounter
     • TrailingZeroCounter
     • BitReverser
     • SIMD_LeftShifter
     • SIMD_RightShifter
     • SIMD_ArithmeticRightShifter
     • SIMD_LeftRotator
     • SIMD_RightRotator
     • SIMD_PopulationCounter
     • SIMD_LeadingZeroCounter
     • SIMD_TrailingZeroCounter
     • SIMD_BitReverser
   • Integer Arithmetic
     • Adder
     • HalfAdder
     • FullAdder
     • Subtractor
     • HalfSubtractor
     • FullSubtractor
     • Multiplier
     • SignedMultiplier
     • Divider
     • SignedDivider
     • Remainder
     • SignedRemainder
     • SIMD_Adder
     • SIMD_Subtractor
     • SIMD_Multiplier
     • SIMD_SignedMultiplier
     • SIMD_Divider
     • SIMD_SignedDivider
     • SIMD_Remainder
     • SIMD_SignedRemainder
   • Floating-Point Arithmetic

     Available only if an appropriate version of softfloatpy module is found.

     • fp.FPNegator
     • fp.FPAdder
     • fp.FPSubtractor
     • fp.FPMultiplier
     • fp.FPFusedMultiplyAdder
     • fp.FPDivider
     • fp.FPRemainder
     • fp.FPSquareRoot
     • fp.FPComparator
     • fp.FPClassifier
     • fp.FPToIntegerRounder
     • fp.FPToIntegerConverter
     • fp.FPToSignedIntegerConverter
     • fp.FPFromIntegerRounder
     • fp.FPFromSignedIntegerConverter
     • fp.FPConverter
     • fp.SIMD_FPNegator
     • fp.SIMD_FPAdder
     • fp.SIMD_FPSubtractor
     • fp.SIMD_FPMultiplier
     • fp.SIMD_FPFusedMultiplyAdder
     • fp.SIMD_FPDivider
     • fp.SIMD_FPRemainder
     • fp.SIMD_FPSquareRoot
     • fp.SIMD_FPComparator
     • fp.SIMD_FPClassifier
     • fp.SIMD_FPToIntegerRounder
     • fp.SIMD_FPToIntegerConverter
     • fp.SIMD_FPToSignedIntegerConverter
     • fp.SIMD_FPFromIntegerConverter
     • fp.SIMD_FPFromSignedIntegerConverter
     • fp.SIMD_FPConverter
     • fp.riscv.FRec7
     • fp.riscv.FRSqrt7
     • fp.riscv.SIMD_FRec7
     • fp.riscv.SIMD_FRSqrt7
   • Arithmetic Logic Unit
     • alu.GenericArithmeticLogicUnit
     • alu.FullArithmeticLogicUnit
     • alu.SIMD_FullArithmeticLogicUnit
     • alu.ArithmeticLogicUnit74181
     • alu.LookAheadCarryGenerator74182
   • Counter
     • counter.SynchronousBinaryCounter74161
     • counter.SynchronousBinaryCounter74163
   • Memory
     • memory.LevelTriggeredMemory
     • memory.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)
   

2. 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)
   

3. 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)
   

4. Add the probes to the ports or the memory. An example is shown below.

   drain.port_i.add_probe(probe)
   

5. Create an instances of LogicAnalyzer class. An example is shown below.

   la: hw.LogicAnalyzer = hw.LogicAnalyzer()
   

6. Add the probes to the logic analyzer. An example is shown below.

   la.add_probe(probe)
   

7. Create an instance of Simulator class. An example is shown below.

   sim: hw.Simulator = hw.Simulator([source, drain])
   

8. Start the simulation. An example is shown below.

   sim.start()
   

9. 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)
   

10. 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.