Class UART

Nested Relationships

Nested Types

Inheritance Relationships

Base Type

Class Documentation

class UART : public SignalHook

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.

Public Types

enum SignalId

Values:

enumerator Signal_DataFrame

Raised in TX and RX with sigdata containing the single frame.

enumerator Signal_DataString

Raised when receiving a c-style string, pointed by sigdata.

enumerator Signal_DataBytes

Raised when receiving an array of frames, pointed by sigdata.

enumerator Signal_TX_Start

Raised at the start of a frame transmission, with sigdata containing the frame.

enumerator Signal_TX_Complete

Raised at the end of a frame transmission. sigdata contains 1 if the transmission completed successfully or 0 if it was interrupted.

enumerator Signal_RX_Start

Raised at the start of a frame reception.

enumerator Signal_RX_Complete

Raised at the end of a frame reception. sigdata contains 1 if the frame is received successfully or 0 if it was discarded.

Public Functions

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

Initialise the interface.

Parameters:

  • cycle_manager – Cycle manager used for time-related operations

  • logger – Logger used for the interface

void reset()

Reset the interface.

inline Signal &signal()

Getter for the internal signal used for operation signaling.

inline void set_frame_delay(cycle_count_t delay)

Set the delay in clock ticks to emit or receive a frame. The minimum valid value is 1.

void set_tx_buffer_limit(size_t limit)

Set the TX buffer size, including the TX shift register. A zero size means unlimited. Stored frames are discarded to adjust if necessary.

void push_tx(uint8_t frame)

Push a 8-bits frame to be emitted by the interface. If no TX is already ongoing, it will be started immediately.

void cancel_tx_pending()

Cancel all pending TX but let the current one finish, if any.

inline unsigned int tx_pending() const

Getter for the no of frames waiting in the buffer to be emitted.

inline bool has_tx_collision() const

Getter for the TX collision flag.

inline void clear_tx_collision()

Clear the TX collision flag.

void set_rx_buffer_limit(size_t limit)

Set the RX buffer size, including the RX shift register. A zero size means unlimited. Stored frames are discarded to adjust if necessary.

void set_rx_enabled(bool enabled)

Enable/disable the reception. If disabled, the RX buffer is flushed.

inline size_t rx_available() const

Getter for the number of frames stored in the RX buffer.

uint8_t pop_rx()

Pop a frame from the RX buffer. Use rx_available() to know if any frame is available.

Returns:

the popped frame, 0 if no frame is available.

inline bool has_rx_overflow() const

Getter for the RX overflow flag.

inline void clear_rx_overflow()

Clear the RX overflow flag.

void set_paused(bool enabled)

Enable/disable the pause mode.

If pause is enabled, any ongoing communication will complete as normal, and further TX frames won’t be emitted (but remain in the FIFO). Frames already in the RX FIFO are kept but further received frames will be ignored.

UART(const UART&) = delete
UART &operator=(const UART&) = delete
virtual void raised(const signal_data_t &sigdata, int hooktag) override

Pure virtual callback called during signal raises.

Parameters:

  • sigdata – Data structure passed on when raising a signal

  • hooktag – integer passed on when connecting a hook to a signal. For hooks connected to several signals, it provides a mean to identify the caller.

class RxTimer : public CycleTimer

Public Functions

inline RxTimer(UART &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.

class TxTimer : public CycleTimer

Public Functions

inline TxTimer(UART &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.