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_PortMuxConfig::mux_map_entry_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_USI, ArchAVR_WDT, ArchXT_ACP, ArchXT_ADC, ArchXT_Fuses, ArchXT_MiscRegCtrl, ArchXT_NVM, ArchXT_PortMuxCtrl, 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_TRANSFER

Request to transfer a byte bypassing . A byte is directly dropped into the RX buffer and a byte popped from the TX buffer of the SPI interface with bypassing the actual line shifting. This is meant for debugging purposes.

In argument, data is a 8-bits frame to be pushed to the RX buffer.
data is returned set to a 8-bits frame popped from the TX buffer.

struct ArchAVR_SPIConfig: #include <arch_avr_spi.h>

Configuration structure for ArchAVR_SPI.

class ArchAVR_SPI : public Peripheral

#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

#include <arch_xt_spi.h>

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

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 hosts/clients, arbitration and bus collision detections. Hoever, it is not multi-thread safe.

It is implemented by 3 classes:

EndPoint is an abstract interface defining a generic device connected to a TWI bus.
Client : Basic state machine & transitions for a client side interface.
Host : Basic state machine & transitions for a host side interface.

These classes are abstract, the way classes access the SCL and SDA line must be defined by reimplementation by overriding set_line_state() and using line_state_changed().

Client and Host are designed to be controlled by an upper level object (a controller). The controller gets notified or events on the bus by signalling, and shall use the interface API to react accordingly.

Controller requests definition for SPI

AVR_CTLREQ_TWI_BUS_ERROR

Request to inject a TWI bus error.

data->index is 0 for the host side, 1 for the client side.

class EndPoint

#include <sim_twi.h>

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

See also

Client, Host

Subclassed by TWI::Client, TWI::Host

class Client : public TWI::EndPoint, public CycleTimer

#include <sim_twi.h>

Base abstract definition for a TWI client.

See also

EndPoint, Host This class implements the basic state machine to interface a TWI bus as a client. It is design to be controlled by a upper layer object (a controller). The interface notifies the controller of bus events (start, address, etc) via the signals and the controller shall use the API of this class to react accordingly.

Subclassed by ArchAVR_TWI::_Client, ArchXT_TWI::_Client

class Host : public TWI::EndPoint, public CycleTimer

#include <sim_twi.h>

Base abstract definition for a TWI host.

See also

EndPoint, Client This class implements the basic state machine to interface a TWI bus as a host. It is design to be controlled by a upper layer object (a controller). The interface notifies the controller of bus events (start, address, etc) via the signals and the controller shall use the API of this class to react accordingly.

Subclassed by ArchAVR_TWI::_Host, ArchXT_TWI::_Host

struct ArchAVR_TWIConfig: #include <arch_avr_twi.h>

Configuration structure for ArchAVR_TWI.

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

Implementation of a TWI model for the AVR series.

struct ArchXT_TWIConfig: #include <arch_xt_twi.h>

Configuration structure for ArchXT_TWI.

class ArchXT_TWI : public Peripheral

#include <arch_xt_twi.h>

Implementation of a Two Wire Interface for XT core series.

Unsupported features:

SDA Setup time
DBGRUN
Bus timeout
SMBus compatibility
Fast mode
Quick Command

CTLREQs supported:

AVR_CTLREQ_TWI_BUS_ERROR : Trigger a bus error data.index : if =0, trigger a bus error in the host and client sides, if enabled if !=0, trigger a bus error for the client side only, if enabled
AVR_CTLREQ_GET_SIGNAL: returns the signal of the underlying TWI interface; for debug purpose data.index : if =0, returns the signal of the host side if !=0, returns the signal of the client side

See also

TWI, TWIEndPoint

Universal Asynchronous Serial Interface

group api_uart

Controller requests definition for USART

AVR_CTLREQ_USART_BYTES: adds frame to the underlying RX buffer, bypassing the bus logic. For debugging purpose.

class USART

#include <sim_uart.h>

Generic model defining an universal synchronous/asynchronous serial interface a.k.a. USART.

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: Received frames and pending frames (yet to be received); Disabling the RX does not prevent receiving frames. They are simply discarded when actually received by the device. (i.e. when moved from the pending FIFO to the received FIFO) 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.

Subclassed by ArchAVR_USART::_Controller, ArchXT_USART::_Controller

struct ArchAVR_USARTConfig: #include <arch_avr_usart.h>

Configuration structure for ArchAVR_USART.

class ArchAVR_USART : public Peripheral

#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

#include <arch_xt_usart.h>

Implementation of a USART interface for XT core series.

Limitations:

MSPI, MPCM or IRCOM modes are not supported
Auto-baud not supported

CTLREQs supported:

AVR_CTLREQ_GET_SIGNAL : returns in data.p the signal of the underlying USART object (see sim_uart.h)
AVR_CTLREQ_USART_BYTES

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.