Python Utilities

VCD Output

class yasimavr.utils.vcd_recorder.VCD_Recorder(simloop, file, **kwargs)

Value Change Dump recorder.

A VCD file captures time-ordered changes to the value of variables as raised by signals.

It is built on top of a VCDWriter instance from PyVCD and uses Formatter objects to connect to signals from the simulation model, filter and format the values received from signal notifications and writes them into the VCD file.

Parameters:

simloop (AbstractSimLoop) – The simulation loop instance.
file (str) – file path to write the VCD data.
kwargs (dict) – other arguments passed on to the underlying VCDWriter object.

See PyVCD docs for details on VCDWriter and the VCD file format: PyVCD documentation

add(formatter, var_name)

Register a new VCD variable for a generic formatter.

Parameters:

formatter (Formatter) – Formatter object
var_name (str) – variable name

add_digital_pin(pin, var_name='')

Register a new VCD variable for a Pin instance.

Parameters:

pin (Pin) – Pin object
var_name (str) – optional variable name, defaults to the pin identifier

add_gpio_port(port_name, var_name='')

Register a new VCD variable for a GPIO port.

Parameters:

port_name (str) – Letter identifying the GPIO port
var_name (str) – optional variable name, defaults to the port identifier

add_interrupt(vector, var_name='')

Register a new VCD variable for an interrupt vector.

Parameters:

vector (int) – interrupt vector index
var_name (str) – optional variable name, defaults to the vector index

add_signal(sig, var_name, size=32, sigid=None, sigindex=None)

Register a new VCD variable for a generic peripheral signal.

Parameters:

sig (Signal) – Signal to connect to
var_name (str) – Variable name
size (int) – variable size, default is 32 bits
sigid (int) – optional SignalId value for filtering
sigindex (int) – optional index value for filtering

close(): Close the record. The recorder may not be used anymore afterwards.

flush(): Flush the recorded data into the destination file.

record_off(): Pause the recording.

record_on(): Start or resume the recording.

property writer: Return the underlying VCDWriter object.

class yasimavr.utils.vcd_recorder.Formatter(var_type, var_size, init_value)

Generic formatter class.

A formatter is a signal hook connected to receive data changes and format it for writing into a VCD file.

Parameters:

var_type (VarType) – VCD variable type (see pyvcd documentation)
var_size (int) – VCD variable size (see pyvcd documentation)
init_value (str) – initial value

filter(sigdata, hooktag)

Generic filtering facility to be reimplemented by subclasses.

Must return True if the value shall be recorded, based on the signal data fields. By default all values are recorded.

format(sigdata, hooktag)

Generic conversion facility to be reimplemented by subclasses.

Must return a value compatible with the variable type, to be recorded in the VCD file.

raised(sigdata, hooktag): Reimplementation of SignalHook, to filter, format and record the value associated to the signal.

register(recorder, var_name)

Called by the recorder to register this Formatter instance with a associated VCD Variable object.

Parameters:

recorder (VCD_Recorder) – VCD_Recorder instance
var_name (str) – VCD variable name (see pyvcd documentation)

Simulation State Dump

yasimavr.utils.sim_dump.sim_dump(simloop: AbstractSimLoop, stream: TextIOBase = None) → str | None

Dump the current state of a simulation into a I/O stream.

Parameters:

simloop (AbstractSimLoop) – instance of AbstractSimLoop to dump
stream (io.TextIOBase) – writable stream instance or None

If stream is None, the state is dumped into a string buffer and the string is returned. If stream is not None, the state is written into it and None is returned.

GDB Stub

class yasimavr.utils.gdb_server.GDB_Stub(conn_point, fw_source, simloop=None, device=None)

This class implements a stub that acts as an interface between yasimavr and the GNU Debugger. It is designed on top of a TCP server and implements the relevant parts of the Remote Serial Protocol.

Source: https://www.sourceware.org/gdb/onlinedocs/gdb/Remote-Protocol.html

Parameters:

conn_point (tuple[str, int]) – Tuple (IP, port) for the socket to listen for GDB connections
fw_source (str) – path to the firmware source code
simloop (AsyncSimLoop) – Simulation loop to connect to
device (Device) – Device simulation model to connect to

Note

At least one of simloop or device should be specified.

If simloop is provided, the stub will take control of it. If device is provided, the stub will create a simulation loop for it and dispose of it on shutdown.

SPI

This module defines SPISimpleClient and SPISimpleHost which are simple instances of SPI devices that can be used for SPI parts simulation.

class yasimavr.utils.spi.SPISimpleClient(mode=<class 'yasimavr.lib._mock_base._MockObject.__getattr__.<locals>.attr'>, bitorder=<class 'yasimavr.lib._mock_base._MockObject.__getattr__.<locals>.attr'>)

Simple implementation of a SPI client

property clock_line: Wire object representing the SPI clock line

property enabled: Enabling property

frame_completed(): Override of EndPoint

property miso_line: Wire object representing the SPI MISO line

property mosi_frame: Return the last frame received.

property mosi_line: Wire object representing the SPI MOSI line

read_data_input(): Override of EndPoint

property select_line: Wire object representing the SPI chip select line

set_miso_frame(frame): Set the frame to be sent at the next transfer

write_data_output(level): Override of EndPoint

class yasimavr.utils.spi.SPISimpleHost(cycle_manager, bitdelay, mode=<class 'yasimavr.lib._mock_base._MockObject.__getattr__.<locals>.attr'>, bitorder=<class 'yasimavr.lib._mock_base._MockObject.__getattr__.<locals>.attr'>)

Simple implementation of a SPI host. It features a TX FIFO and a RX FIFO to queue frames. Note that it doesn’t manage the chip select line.

Parameters:

cycle_manager (CycleManager) – instance associated with the simulation loop
bitdelay (int) – duration of a bit in simulation cycles
mode (SPI.SerialMode) – SPI mode (one of SPI.SerialMode enum values)
bitorder (SPI.BitOrder) – Bit order mode (one of SPI.BitOrder enum values)

cancel(): Cancel the current transfer.

property clock_line: Wire object representing the SPI clock line

frame_completed(): Override of EndPoint

property miso_line: Wire object representing the SPI MISO line

property mosi_line: Return the last frame received.

peek_miso_frame(): Return the front frame in the RX FIFO buffer without popping it.

pop_miso_frame(): Pop the front frame in the RX FIFO buffer and return it.

read_data_input(): Override of EndPoint

reset(): Cancel the current transfer and clear the FIFO buffers.

rx_available(): Return the number of frame stored in the RX FIFO buffer.

start_transfer(mosi_frame)

Start a transfer of a SPI frame If a transfer is already in progress, the frame is added to the TX FIFO buffer and transmitted after the current one.

Parameters:: mosi_frame (int) – 8-bits data frame to send

transfer_ended(): Callback that can be overriden by sub-classes to be notified when the transfer of one frame has completed.

transferring(): Returns True if a transfer is in progress.

write_data_output(state): Override of EndPoint

TWI

This module defines TWISimpleClient which is a simple reimplementation of a TWI client device that can be used for simple TWI/I2C part simulation.

class yasimavr.utils.twi.TWISimpleClient(address)

Simple TWI client used to emulate peripheral IC such as eeproms

Parameters:: address (int) – 7-bits TWI address for the client

Note

See example “uno_lcd” for a implementation of a TWI client

property address: Fixed address on the bus

address_match(addr_rw)

Test the received address for match. The default implementation returns True for the fixed address, given at initialisation time. It may be overriden to define different match requirements.

Parameters:: addr_rw (int) – ADDR+RW byte as sent by the host
Returns:: True to respond with ACK, False for NACK

packet_end(): Generic handler called once at the end of a packet, i.e. after data has been transferred and responded with a NACK. May be overriden by sub-classes for specific behaviour.

read_handler(): Generic handler for a read request Should be reimplemented to provide the data being read The handler is called only once for each byte of a read request. It should return a 8-bits integer, which will be sent over to the host.

property scl_wire: Wire object representing the SCL line

property sda_wire: Wire object representing the SDA line

set_line_state(line, state): TWI.Client override

transfer_start(rw)

Generic handler called once at the start of a packet transfer. May be overriden by sub-classes for specific behaviour.

Parameters:: rw (int) – RW bit: 1 for Read (client->host), 0 for Write (host->client)

transfer_stop(ok)

Generic handler called once at the end of a transfer, i.e. when detecting a STOP or a RESTART condition, or when the transfer is interrupted by a bus collision. May be overriden by sub-classes for specific behaviour.

Parameters:: ok (bool) – True for a STOP or RETART condition, False for a bus collision.

write_handler(data)

Generic handler for a write request Should be reimplemented to process the provided data and return True for ACK or False for NACK. The handler is called once for each byte being written by the host.

Parameters:: data (int) – data byte received with the write request

UART

This module defines UartIO which is a reimplementation of io.RawIOBase that can connect to a AVR device USART peripheral to exchange data with it as if writing to/reading from a file.

class yasimavr.utils.uart.UART_IO(device, portnum, mode='rw')

Reimplementation of io.RawIOBase that can connect to a device USART peripheral to exchange data with it as if writing to/reading from a file.

Parameters:

device (Device) – Simulation device model
portnum (int) – USART port index, i.e. 0 for USART0, 1 for USART1, etc.
mode (str) – file access mode. Valid values are “w”, “r”, “rw”

class yasimavr.utils.uart.RawUART

Simple reimplementation of a USART base class to allow the use of UART lines in simulation models.

Being bitwise, it is compatible with bit banging interfaces and it allows to visualise the traffic on the data lines.

:sa class UART.USART for more class members

Cpp:class:: UART.USART<UART::USART>

property lineRXD: Wire object representing the RXD line

property lineTXD: Wire object representing the TXD line

property lineXCK: Wire object representing the XCK line (used only in synchronous modes)