Frameworks

Peripheral

The class Peripheral provides the basis to implement all peripherals built in a device model. It provide the facilities to allocate and access I/O registers and interrupts.

group core_peripheral

Controller requests definition

Definition of common and builtin CTLREQs

See also

Device::ctlreq

See also

ctlreq_data_t

typedef int ctlreq_id_t

CTLREQ identifier type

AVR_CTLREQ_BASE

Base value for peripheral-specific requests. The range 0-255 is reserved for generic requests

AVR_CTLREQ_GET_SIGNAL

Common request identifier used to obtain a pointer to a particular signal

  • data.index should contain the identifier of the signal

  • data.p is returned pointing to the signal

AVR_CTLREQ_CORE_BREAK

Request sent by the CPU to the core when a BREAK instruction is executed, no data provided.

AVR_CTLREQ_CORE_SLEEP

Request sent by the Sleep Controller to the core to enter a sleep mode

  • data.u contains the sleep mode enum value

AVR_CTLREQ_CORE_WAKEUP

Request sent by the Sleep Controller to the core to wake up from a sleep mode, no data provided

AVR_CTLREQ_CORE_SHORTING

Request sent by the Port Controller to the core when a pin shorting is detected

AVR_CTLREQ_CORE_CRASH

Request sent to the core to crash.

  • data.index is the reason code,

  • data.p is the optional reason string

AVR_CTLREQ_CORE_RESET

Request sent to the core to trigger a MCU reset.

  • data.u is the corresponding ResetFlag enum value

AVR_CTLREQ_CORE_RESET_FLAG

Request sent to the core to query the latest cause of reset.

  • data.u is set to the ResetFlag enum value

AVR_CTLREQ_CORE_NVM

Request sent to the core to query the pointer to a NVM block

  • data.index indicates which block with one of the AVR_NVM enum values

AVR_CTLREQ_CORE_HALT

Request to halt the CPU, used during a SPM instruction. a non-zero data.u enables the halt, data.u == 0 disables the halt.

AVR_CTLREQ_CORE_SECTIONS

Request to get the section manager. data.p is returned pointing to the instance of MemorySectionManager.

AVR_CTLREQ_WATCHDOG_RESET

Request sent by the CPU to the watchdog when executing a WDR instruction, no data provided

AVR_CTLREQ_NVM_REQUEST

Request sent by the CPU to the NVM controller when executing a SPM instruction, or a LPM instruction if the LPM direct mode is disabled with the core.

  • data.p points to a NVM_request_t structure filled with the instruction information

AVR_CTLREQ_SLEEP_CALL

Request sent by the CPU to the Sleep Controller when executing a SLEEP instruction, no data provided

AVR_CTLREQ_SLEEP_PSEUDO

Request sent by the CPU to the Sleep Controller when executing a “RJMP .-2” instruction, no data provided

Register field lookup

The structure base_reg_config_t and the functions find_reg_config() are useful for configuration that maps a register field value to a set of parameters. (see the timer classes for examples)

template<typename T>
int find_reg_config(const std::vector<T> &v, uint64_t reg_value)
template<typename T>
const T *find_reg_config_p(const std::vector<T> &v, uint64_t reg_value)

Peripheral identifier definition

All peripherals are uniquely identified by a 32-bits integer which is actually composed of 4 characters. This section defines the identifiers for the usual peripherals.

See also

Peripheral

AVR_IOCTL_CORE

CTLID for the core: “CORE”

AVR_IOCTL_WDT

CTLID for the watchdog timer: “WTDG”

AVR_IOCTL_INTR

CTLID for the interrupt controller: “INTR”

AVR_IOCTL_SLEEP

CTLID for the sleep controller: “SLP”

AVR_IOCTL_CLOCK

CTLID for the clock controller: “CLK”

AVR_IOCTL_PORT(n)

CTLID for the I/O port controller: “IOGx” x=’A’,’B’,…

AVR_IOCTL_PORTMUX

CTLID for the port mux controller

AVR_IOCTL_ADC(n)

CTLID for the analog-to-digital converter: “ADCn”, n=0,1,…

AVR_IOCTL_ACP(n)

CTLID for the analog comparator: “ACPn”, n=0,1,…

AVR_IOCTL_TIMER(t, n)

CTLID for the timer/counter: “TCtn”, t=’A’,’B’; n=0,1,…

AVR_IOCTL_EEPROM

CTLID for the EEPROM controller: “EPRM”

AVR_IOCTL_NVM

CTLID for the NVM controller: “NVM”

AVR_IOCTL_VREF

CTLID for the voltage reference controller: “VREF”

AVR_IOCTL_EXTINT

CTLID for the external interrupt controller: “EINT”

AVR_IOCTL_RST

CTLID for the reset controller: “RST”

AVR_IOCTL_RTC

CTLID for the real-time counter: “RTC”

AVR_IOCTL_UART(n)

CTLID for the USART interface: “UAXn”

AVR_IOCTL_SPI(n)

CTLID for the SPI interface: “SPIn”

AVR_IOCTL_TWI(n)

CTLID for the TWI interface: “TWIn”

struct NVM_request_t
#include <sim_peripheral.h>

Structure used for AVR_CTLREQ_NVM_REQUEST requests.

These structure are used when :

  • a SPM instruction is executed, or

  • flash memory is read and direct mode is disabled.

These requests are processed by the NVM controller (if it exists) and returned with the result field set. This system allows to implement access control measures and self-programming features.

struct ctlreq_data_t
#include <sim_peripheral.h>

Structure exchanged with CTL requests

struct base_reg_config_t
#include <sim_peripheral.h>

Subclassed by ACP::channel_config_t, ADC::channel_config_t, ArchAVR_ACPConfig::mux_config_t, ArchAVR_ADCConfig::reference_config_t, ArchAVR_ADCConfig::trigger_config_t, ArchAVR_FusesConfig::bootsize_config_t, ArchAVR_TimerConfig::COM_config_t, ArchAVR_TimerConfig::OC_config_t, ArchAVR_TimerConfig::clock_config_t, ArchAVR_TimerConfig::mode_config_t, ArchXT_ADCConfig::reference_config_t, ArchXT_RTCConfig::clksel_config_t, ArchXT_VREFConfig::reference_config_t, SleepConfig::mode_config_t

class Peripheral : public IO_RegHandler
#include <sim_peripheral.h>

Abstract class defining a framework for MCU peripherals.

Subclassed by ArchAVR_ACP, ArchAVR_ADC, ArchAVR_ExtInt, ArchAVR_Fuses, ArchAVR_MiscRegCtrl, ArchAVR_NVM, ArchAVR_ResetCtrl, ArchAVR_SPI, ArchAVR_TWI, ArchAVR_Timer, ArchAVR_USART, ArchAVR_WDT, ArchXT_ACP, ArchXT_ADC, ArchXT_Fuses, ArchXT_MiscRegCtrl, ArchXT_NVM, ArchXT_RTC, ArchXT_ResetCtrl, ArchXT_SPI, ArchXT_TWI, ArchXT_TimerA, ArchXT_TimerB, ArchXT_USART, ArchXT_USERROW, DummyController, InterruptController, Port, SleepController, VREF, WatchdogTimer

Analog to Digital converter

group api_adc

Controller requests definition for ADC

AVR_CTLREQ_ADC_SET_TEMP

Request to set the value reported by the simulated temperature sensor

  • data set to the temperature value in °C (as a double)

AVR_CTLREQ_ADC_TRIGGER

Request to force trigger an ADC conversion. The request only has effect if the ADC must be enabled, idle (no conversion running) and configured to use an external trigger. No data used.

class ADC
#include <sim_adc.h>

Generic ADC definitions.

Definition of enumerations, configuration structures and signal Ids used for ADC models, common to all architectures.

Subclassed by ArchAVR_ADC, ArchXT_ADC

struct ArchAVR_ADCConfig
#include <arch_avr_adc.h>

Configuration structure for ArchAVR_ADC.

class ArchAVR_ADC : public ADC, public Peripheral, public SignalHook
#include <arch_avr_adc.h>

Implementation of an ADC for AVR series.

Limitations:

  • No automatic start on ADR Noise Reduction sleep mode

  • No digital input disabling

CTLREQs supported:

  • AVR_CTLREQ_GET_SIGNAL : returns a pointer to the instance signal

  • AVR_CTLREQ_ADC_SET_TEMP : Sets the temperature reported by the internal sensor. The reqdata should carry the temperature in Celsius as a double.

  • AVR_CTLREQ_ADC_TRIGGER : Allows other peripherals to trigger a conversion. The trigger only works when the ADC is enabled and idle, auto-trigger is enabled and an external trigger source is selected.

struct ArchXT_ADCConfig
#include <arch_xt_adc.h>

Configuration structure for ArchXT_ADC.

class ArchXT_ADC : public ADC, public Peripheral, public SignalHook
#include <arch_xt_adc.h>

Implementation of an ADC for XT series.

Limitations:

  • Sampling cap and duty cycle settings have no effect

  • No Debug Run override

CTLREQs supported:

  • AVR_CTLREQ_GET_SIGNAL : returns a pointer to the instance signal

  • AVR_CTLREQ_ADC_SET_TEMP : Sets the temperature reported by the internal sensor. The reqdata should carry the temperature in Celsius as a double.

  • AVR_CTLREQ_ADC_TRIGGER : Allows other peripherals to trigger a conversion. The trigger only works when the ADC is enabled and idle, and the bit STARTEI is set.

Timer/Counter

group api_timer

Controller requests definition for ArchAVR_Timer

AVR_CTLREQ_TMR_GET_EXTCLK_HOOK

Request to obtain a pointer to the SignalHook entry point for external clock ticks

AVR_CTLREQ_TMR_GET_CAPT_HOOK

Request to obtain a pointer to the SignalHook entry point for event capture

Controller requests definition for ArchXT_TimerA

AVR_CTLREQ_TCA_REGISTER_TCB

Request for a Timer type B to register with the timer type A. this is necessary for the TCB to use the same “clock” as the TCA.

Defines

AVR_CTLREQ_TCA_GET_EVENT_HOOK

Request for the event input hook for a timer type A. It returns with data as a pointer to a SignalHook instance.

class PrescaledTimer : public CycleTimer
#include <sim_timer.h>

Generic model of a Timer with prescaling.

Implementation of a clock cycle timer, used by peripherals such as TCx, WDT, RTC.

It is structured with two consecutive stages:

  • Prescaler

  • Timer

The prescaler works as a counter of simulated clock cycles, starting at 0, wrapping at ‘ps_max’, and generating timer ‘ticks’ once every ‘ps_factor’ cycles. The timer generates a timeout signal after a delay given in prescaler ticks.

The timeout is transmitted though a Signal, available via signal() and raised in 2 ways:

  • When the programmed timeout delay is reached.

  • When update() is called, and enough clock cycles have passed, resulting in at least one tick.

If, during the update, the number of generated ticks is enough to reach the timer delay, the signal index is set to 1, otherwise it is set to 0. The signal data field is set to the generated tick count.

Timers can be daisy-chained, so that the prescaler tick output of a timer feeds into the prescaler clock input of another.

class TimerCounter
#include <sim_timer.h>

Generic model of a Counter.

Implementation of a clock cycle counter, used by peripherals such as TCx, WDT, RTC. Features :

  • 2 ‘tick’ sources: internal (using a PrescaledTimer object) or external via a signal hook

  • Up/down counting and dual slope

  • Arbitrary number of compare channels

  • Signalling on top, bottom, max and compare value

struct ArchAVR_TimerConfig
#include <arch_avr_timer.h>

Configuration structure for ArchAVR_Timer.

class ArchAVR_Timer : public Peripheral, public SignalHook
#include <arch_avr_timer.h>

Timer/Counter model for AVR series.

Implementation of a 8bits/16bits Timer/Counter for AVR series

This timer is a flexible implementation aiming at covering most modes found in AVR timer/counter. It covers normal, CTC, PWM in both single and dual slopes. The behaviour is defined by a mode_config_t structure selected by the mode field. It has a number of Output Compare channels, each defined by a OC_config_t structure. Each OC channel behaviour is defined by a set of Compare Output Mode (COM) values.

Unsupported features:

  • Asynchronous operations

struct ArchXT_TimerAConfig
#include <arch_xt_timer_a.h>

Configuration structure for ArchXT_TimerA.

class ArchXT_TimerA : public Peripheral, public SignalHook
#include <arch_xt_timer_a.h>

Implementation of a Timer/Counter type A for the XT core series.

Unsupported features:

  • Debug run override

The model supports two versions, defined by the versionattribute of ArchXT_TimerAConfig

struct ArchXT_TimerBConfig
#include <arch_xt_timer_b.h>

Configuration structure for ArchXT_TimerB.

class ArchXT_TimerB : public Peripheral, public SignalHook
#include <arch_xt_timer_b.h>

Implementation of a Timer/Counter type B for the XT core series.

Unsupported features:

  • Debug run override

  • Synchronize Update (SYNCUPD)

Serial Peripheral Interface

group api_spi

Controller requests definition for SPI

AVR_CTLREQ_SPI_ADD_CLIENT

Request to register a SPI client to a SPI interface

  • data must be a pointer to a SPIClient object

AVR_CTLREQ_SPI_CLIENT

Request to obtain a pointer to the SPI interface as a SPI client

  • data is returned as a pointer to a SPIClient object

AVR_CTLREQ_SPI_SELECT

Request to select/deselect the SPI interface when used as a client

  • data must be an integer : select if > 0, deselect if == 0

class SPIClient
#include <sim_spi.h>

Abstract interface for a SPI Client.

Subclassed by SPI

class SPI : public SPIClient, public CycleTimer
#include <sim_spi.h>

Generic model defining an serial peripheral interface a.k.a. SPI.

The interface can act in either host or client mode.

The class is composed of two FIFOs, one for TX, the other for RX. The transfer of a frame starts immediately after pushing it in the TX FIFO.

struct ArchAVR_SPIConfig
#include <arch_avr_spi.h>

Configuration structure for ArchAVR_SPI.

class ArchAVR_SPI : public Peripheral, public SignalHook
#include <arch_avr_spi.h>

Implementation of a SPI interface for AVR series Features:

  • Host/client mode

  • data order, phase and polarity settings have no effect

  • write collision flag not supported

See also

sim_spi.h

struct ArchXT_SPIConfig
#include <arch_xt_spi.h>

Configuration structure for ArchXT_SPI.

class ArchXT_SPI : public Peripheral, public SignalHook
#include <arch_xt_spi.h>

Implementation of a Serial Peripheral Interface controller for the XT core series.

Features:

  • Host/client mode

  • data order, phase and polarity settings have no effect

  • write collision flag not supported

  • buffer mode not supported

  • multi-host mode not supported

  • Slave Select has no effect in host mode (the SSD setting has no effect)

for supported CTLREQs, see sim_spi.h

Two-Wire Interface

group api_twi

This code (tentatively) defines a simulation of a TWI (a.k.a. I2C or SMBus) implementation.

It supports multiple masters/slaves.

It does not support arbitration beyond the START condition and (currently) is not multi-thread safe.

It is implemented by 4 classes:

  • TWIPacket defines a packet circulating on a bus simulating the successive exchange of information between mater and slave.

  • TWIEndPoint is an abstract interface defining a generic device connected to a TWI bus.

  • TWIBus defines a central object to circulate packets between multiple endpoints.

  • TWI is an implementation of a TWI interface for an AVR MCU, as generic as possible. It manages master and slave operations independently and communicates with upper layers via signals.

Controller requests definition for SPI

AVR_CTLREQ_TWI_ENDPOINT

Request to get the TWI endpoint.

class TWIPacket
#include <sim_twi.h>
class TWIEndPoint
#include <sim_twi.h>

An endpoint connected to a TWI bus. Represents a device connected to a TWI bus model and acting as a master, a slave or both.

See also

TWI_Bus, TWI_Packet

Subclassed by TWI

class TWIBus
#include <sim_twi.h>

A central object to circulate packets between multiple TWI endpoints.

See also

TWIEndPoint, TWIPacket

class TWI : public TWIEndPoint
#include <sim_twi.h>

Generic model defining a two-wire interface a.k.a. TWI.

The interface has a Master side and a Slave side that are independent of each other and can even communicate with each other;

struct ArchAVR_TWIConfig
#include <arch_avr_twi.h>

Configuration structure for ArchAVR_TWI.

class ArchAVR_TWI : public Peripheral, public SignalHook
#include <arch_avr_twi.h>

Implementation of a TWI model for the AVR series.

Features:

  • Host/client mode

  • data order, phase and polarity settings have no effect

  • write collision flag not supported

See also

sim_twi.h

struct ArchXT_TWIConfig
#include <arch_xt_twi.h>

Configuration structure for ArchXT_TWI.

class ArchXT_TWI : public Peripheral, public SignalHook
#include <arch_xt_twi.h>

Implementation of a Two Wire Interface for XT core series.

Unsupported features:

  • SDA Setup time

  • Dual mode control

  • DBGRUN

  • Bus timeout

  • write collision flag not supported

  • SMBus compatibility not supported

  • Fast mode not supported

CTLREQs supported:

  • AVR_CTLREQ_GET_SIGNAL : returns a pointer to the TWI signal.

  • AVR_CTLREQ_TWI_ENDPOINT : returns a pointer to the bus end point.

See also

TWI, TWIEndPoint

Universal Asynchronous Serial Interface

group api_uart

Controller requests definition for UART

AVR_CTLREQ_UART_ENDPOINT

Request that can be used by external code to access the end point of a UART

interface which can then be used to send & receive data via signaling both ways.

data is set to point to the

UARTEndPoint structure to connect to.

struct UARTEndPoint
#include <sim_uart.h>

Structure exchanged with CTLREQ_UART_ENDPOINT

class UART : public SignalHook
#include <sim_uart.h>

Generic model defining an universal asynchronous serial interface a.k.a. UART.

Emitter

The TX part is composed of a FIFO, whose front slot is the shift register push_tx() puts a new 8-bits frame into the FIFO and the transmission will start immediately. If a TX is already in progress, the frame will wait until it can be transmitted. If the TX buffer size reached the limit, the most recently pushed frames will be discarded and the collision flag will be set. Frames are sent via signaling, using both UART_Data_Frame and UART_TX_Start. At the end of transmission, a signal UART_TX_Complete is emitted with data = 1 if successful or 0 if canceled mid-way by a reset. On-going TX can only be canceled by a reset.

Receiver

The RX part is composed of a FIFO with two sub-parts: The front part is the actual device FIFO, from which received frames are read and popped. The back part has the frames yet to be received by the device. This is a convenient system that allows to send a whole string to the device in one signal, while the device will still receive the characters one by one with a proper timing. Disabling the RX does not prevent receiving frames. They are simply discarded when actually received by the device. (i.e. when moved from the back FIFO to the front FIFO) Frames are received when signaled with UART_Data_Frame or UART_Data_String. The signal UART_RX_Start is emitted at the start of a reception. The signal UART_RX_Complete are emitted at the end of a reception, with data = 1 if the frame if kept or data = 0 if canceled or discarded.

struct ArchAVR_USARTConfig
#include <arch_avr_usart.h>

Configuration structure for ArchAVR_USART.

class ArchAVR_USART : public Peripheral, public SignalHook
#include <arch_avr_usart.h>

Implementation of a USART interface for AVR series.

Supported features:

  • 8-bits frames only, regardless of the frame size setting

  • stop bits and parity settings have no effect

  • synchronous, SPI and MPCM modes are not supported

  • RXC, TXC, UDRE interrupts are supported

  • Error flags are not supported

CTLREQs supported:

  • AVR_CTLREQ_GET_SIGNAL : returns in data.p the signal of the underlying UART (see sim_uart.h)

  • AVR_CTLREQ_UART_ENDPOINT : returns in data.p the endpoint to use in order to transmit data in and out (see sim_uart.h)

struct ArchXT_USARTConfig
#include <arch_xt_usart.h>

Configuration structure for ArchXT_USART.

class ArchXT_USART : public Peripheral, public SignalHook
#include <arch_xt_usart.h>

Implementation of a USART interface for XT core series.

Features:

  • 8-bits frames only, regardless of the frame size setting

  • stop bits and parity settings have no effect

  • synchronous, SPI MPCM modes are not supported

  • one-wire / RS485 and IRCOM modes not supported

  • RXC, RXS, TXC, UDRE interrupts are supported

  • Start-of-Frame detection is supported

  • Error flags are not supported

  • Auto-baud not supported

CTLREQs supported:

  • AVR_CTLREQ_GET_SIGNAL : returns in data.p the signal of the underlying UART (see sim_uart.h)

  • AVR_CTLREQ_UART_ENDPOINT : returns in data.p the endpoint to use in order to transmit data in and out (see sim_uart.h)

Voltage References

group api_vref

Controller requests definition for VREF

AVR_CTLREQ_VREF_GET

Request to interrogate the VREF

controller and obtain a reference value.

The index shall be set to the required source (one of

VREF::Source

enum values)

For Internal references, data shall be set to the required channel, as an unsigned integer.

On return, data is set to the reference value as a double. Except for VCC, all values are relative to VCC.

AVR_CTLREQ_VREF_SET

Request to set VCC or AREF reference values.

The index shall be set to the required source (one of

VREF::Source enum values but only VCC and VREF

are accepted)

data shall be set to the required value as a double.

VCC shall be an absolute value in Volts, AREF shall be relative to VCC and contrainted to the range [0; 1].

class VREF : public Peripheral
#include <sim_vref.h>

Generic model for managing VREF for analog peripherals (ADC, analog comparator)

Note

Setting VCC in the firmware is required for using any analog feature of a MCU. Failing to do so will trigger a device crash.

Subclassed by ArchAVR_VREF, ArchXT_VREF

class ArchAVR_VREF : public VREF
#include <arch_avr_misc.h>

Implementation of a Voltage Reference controller for AVR series.

It supports only one fixed reference.

struct ArchXT_VREFConfig
#include <arch_xt_misc.h>

Configuration structure for ArchXT_VREF.

class ArchXT_VREF : public VREF
#include <arch_xt_misc.h>

Implementation of a voltage reference controller for XT core series.