Class TWI

Nested Relationships

Nested Types

Inheritance Relationships

Base Type

Class Documentation

class TWI : public TWIEndPoint

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;

Public Types

enum SignalId

Signal IDs raised by the TWI interface. For all the signals below, sigdata.index is set to either Cpt_Master or Cpt_Slave identifying which part of the endpoint is emitting the signal.

Values:

enumerator Signal_StateChange

For debug and logging purpose only.

enumerator Signal_BusStateChange

Emitted when the bus state changed. sigdata is set to one of the BusState enumeration values.

enumerator Signal_Address

Slave only signal. Emitted when received a address packet. sigdata is set to the raw byte received, so bit 0 is the RW flag, bits 1 to 7 contain the address

enumerator Signal_AddrAck

Master only signal. Emitted when received a address ACK/NACK from a slave. sigdata is set to TWIPacket::Ack or TWIPacket::Nack

enumerator Signal_TxComplete

Emitted when a data transmission complete, i.e. the ACK/NACK has been received in return. sigdata is set to TWIPacket::Ack or TWIPacket::Nack.

enumerator Signal_RxComplete

Emitted when a data reception completed. sigdata is set to the data byte received. A ACK/NACK has not been sent in return yet.

enum Component

Enum value used in signal indexes to identify the part of the interface raising a signal.

Values:

enumerator Cpt_Any

Master or Slave.

enumerator Cpt_Master

Master part.

enumerator Cpt_Slave

Slave part.

enum BusState

Enum values for the bus state.

Values:

enumerator Bus_Idle

The bus is idle.

enumerator Bus_Busy

The bus is owned by another master.

enumerator Bus_Owned

The bus is owned by this instance.

enum State

Enum value for the interface state. Each part (master/slave) has an independent state.

Enum values are split in 2 nibbles :

  • bits 0 to 3 : an OR’ed combination of StateFlag enum values

  • bits 4 to 7 : an integer incremented only to differentiate the values

Values:

enumerator StateFlag_Active

Flag indicating the interface is active, i.e. participating in bus traffic.

enumerator StateFlag_Busy

Flag indicating the interface is busy.

enumerator StateFlag_Data

Flag indicating data transmission is in progress.

enumerator StateFlag_Tx

Flag indicating the interface is sending data.

enumerator State_Disabled

Interface disabled.

enumerator State_Idle

Interface idle.

enumerator State_Waiting

Waiting for the bus to be released.

enumerator State_Addr

Pending a ADDR packet, where the next valid actions are either a STOP (bus release) or a RESTART (new Address packet)

enumerator State_Addr_Busy

Address packet transmitting/receiving or waiting for ACK/NACK.

enumerator State_TX

Slave address ACKed, in TX mode, ready to send.

enumerator State_TX_Req

Write data request sent, bus held still by the slave.

enumerator State_TX_Busy

Sending data in progress.

enumerator State_TX_Ack

Waiting for a TX ACK/NACK.

enumerator State_RX

Slave address ACKed, in RX mode, ready to receive.

enumerator State_RX_Req

Read data request sent, waiting for data packet (master only)

enumerator State_RX_Busy

Receiving data in progress.

enumerator State_RX_Ack

Waiting for a RX ACK/NACK.

Public Functions

TWI()
virtual ~TWI()
void init(CycleManager &cycle_manager, Logger &logger)

Initialise the interface.

void reset()

Reset the interface and cancel any transaction.

inline Signal &signal()
void set_master_enabled(bool enabled)

Enable the master part of the interface. Cancel any transfer and release the bus if disabled.

void set_bit_delay(cycle_count_t delay)

Set the duration of a bit in clock cycles.

bool start_transfer()

Start a transfer. Tries to obtain the ownership of the bus. Master-side only.

Returns:

true if the bus could be acquired, false if the arbitration was lost.

void end_transfer()

Terminate a transfer and release the bus. Master-side only.

bool send_address(uint8_t remote_addr, bool rw)

Send an address to the bus to select a slave device. Master only.

Parameters:

  • remote_addr – Slave address to select. Only the 7 LSBs are used.

  • rw – true for a Read request, false for a Write request.

Returns:

true if the operation was successful.

bool start_master_tx(uint8_t data)

Start a Write request and send a frame of data to the slave.

Parameters:

data – 8-bits frame to send

Returns:

true if the data could actually be sent, false otherwise.

bool start_master_rx()

Start a read request to the slave.

Returns:

true if the data could actually be sent, false otherwise.

void set_master_ack(bool ack)

Used when the slave is expecting a ACK/NACK response after a ReadData packet.

Parameters:

ack – true for ACK, false for NACK

void set_slave_enabled(bool enabled)

Enable/disable the slave part of the interface.

bool start_slave_tx(uint8_t data)

Send a byte of data to the master, in response to a read request. Slave only

Parameters:

data – 8-bits frame to send

Returns:

true if the data could actually be sent, false otherwise.

bool start_slave_rx()

Start receiving data from the master.

Returns:

true if the data could actually be sent, false otherwise.

void set_slave_ack(bool ack)

Used when the master is expecting a ACK/NACK response after an address or a Write data request.

Parameters:

ack – true for ACK, false for NACK

inline State master_state() const

Returns the current state of the master-side.

inline State slave_state() const

Returns the current state of the slave-side.

TWI(const TWI&) = delete
TWI &operator=(const TWI&) = delete

Protected Functions

virtual void packet(TWIPacket &packet) override

Called by the bus to transmit a packet.

virtual void packet_ended(TWIPacket &packet) override

Called by the bus to end a packet.

virtual void bus_acquired() override

Called by the bus to notify that the bus is acquired.

virtual void bus_released() override

Called by the bus to notify that the bus is released.

class Timer : public CycleTimer

Public Functions

inline Timer(TWI &ctl)
inline virtual cycle_count_t next(cycle_count_t when) override

Callback from the cycle loop.

Note

there’s no guarantee the method will be called exactly on the required ‘when’ cycle. The only guarantee is “called ‘when’ <= ‘current cycle’”, the implementations must account for this.

Note

The next ‘when’ can be in the ‘past’ (i.e. <= ‘current cycle’). In this case, the timer will be called again within the same cycle with the given next ‘when’. The only constraint is that it must be greater than the previous ‘when’. If it’s negative or zero, the timer is removed from the queue.

Parameters:

when – current ‘when’ cycle, at which the timer was scheduled

Returns:

the next ‘when’ the timer requires to be called at.