Group baton_link¶

Byte-level half-duplex link between the UART and the node layer. More...

Classes¶

Type	Name
struct	baton_link Link state.
struct	baton_link_config Link configuration passed to baton_link_init .
struct	baton_link_counters Link diagnostic counters.

Public Types¶

Type	Name
typedef int(*	baton_write_fn Start a non-blocking transmission.

Public Functions¶

Type	Name
void	baton_link_cancel (struct baton_link * link) Drop a requested transmission that has not started yet.
const struct baton_frame *	baton_link_frame (const struct baton_link * link) Last frame reported by BATON_LINK_FRAME.
uint32_t	baton_link_frame_ms (const struct baton_link * link, uint32_t bytes) Duration of `bytes` bytes on the wire (10 bits per byte), rounded up.
int	baton_link_init (struct baton_link * link, const struct baton_link_config * config, uint32_t now_ms) Initialize a link and reset its parser, ring and counters.
int	baton_link_receive (struct baton_link * link, uint32_t now_ms) Process received bytes until something happens.
bool	baton_link_rx_busy (const struct baton_link * link, uint32_t now_ms) Whether a frame is being received right now.
void	baton_link_rx_isr (struct baton_link * link, uint8_t byte) Store one received byte.
int	baton_link_send (struct baton_link * link, const uint8_t * data, size_t length) Request the transmission of a complete frame.
int	baton_link_transmit (struct baton_link * link, uint32_t now_ms) Start a requested transmission when the bus is silent; supervise a running one.
void	baton_link_tx_done_isr (struct baton_link * link) Signal the end of a transmission.

Macros¶

Type	Name
define	BATON_LINK_FRAME `1` A valid frame was received; read it with baton_link_frame() .
define	BATON_LINK_NONE `0` Nothing happened; the receive ring is empty or the transmitter has nothing to report.
define	BATON_LINK_TX_DONE `2` The frame passed to baton_link_send() was transmitted, failed or timed out.

Detailed Description¶

The link owns the receive ring (filled from the UART interrupt), a parser with an inter-byte timeout and a transmitter that waits for a silent bus, checks the echo of its own bytes on a single-wire UART and detects a missing end of transmission. It reports what happened as events; the node layer (Node) uses it, applications normally do not call it directly.

The library never reads a clock: every function that needs the time takes now_ms, a monotonic millisecond counter that may wrap.

** **

Lifecycle: baton_link_init.
Interrupt entry points: baton_link_rx_isr, baton_link_tx_done_isr.
Processing: baton_link_receive, baton_link_transmit, baton_link_send, baton_link_cancel.
Queries: baton_link_frame, baton_link_rx_busy, baton_link_frame_ms.

Public Types Documentation¶

typedef baton_write_fn¶

Start a non-blocking transmission.

typedef int(* baton_write_fn) (void *context, const uint8_t *data, size_t length);

The buffer stays valid and unchanged until the link reports BATON_LINK_TX_DONE. The UART driver sends the bytes in the background (interrupt or DMA).

Parameters:

context Value of baton_link_config::context.
data Complete frame, SYNC to CRC.
length Number of bytes in data.

Returns:

0 when the transmission was started, a negative value otherwise.

Public Functions Documentation¶

function baton_link_cancel¶

Drop a requested transmission that has not started yet.

void baton_link_cancel (
    struct baton_link * link
)

Parameters:

link Link state; NULL is ignored.

function baton_link_frame¶

Last frame reported by BATON_LINK_FRAME.

const struct baton_frame * baton_link_frame (
    const struct baton_link * link
)

Parameters:

link Link state.

Returns:

Frame, valid until the next call of baton_link_receive(); NULL when link is NULL.

function baton_link_frame_ms¶

Duration of bytes bytes on the wire (10 bits per byte), rounded up.

uint32_t baton_link_frame_ms (
    const struct baton_link * link,
    uint32_t bytes
)

Parameters:

link Link state.
bytes Number of bytes.

Returns:

Milliseconds; 0 when link is NULL.

function baton_link_init¶

Initialize a link and reset its parser, ring and counters.

int baton_link_init (
    struct baton_link * link,
    const struct baton_link_config * config,
    uint32_t now_ms
)

Parameters:

link Link state to initialize.
config Configuration copied into the link.
now_ms Current time.

Return value:

0 Link ready.
BATON_PARSE_ERROR NULL argument, no write function, zero baud rate or timeout.

function baton_link_receive¶

Process received bytes until something happens.

int baton_link_receive (
    struct baton_link * link,
    uint32_t now_ms
)

Echo bytes of the own transmission are compared and consumed; the other bytes go to the parser. Call again after every event until it returns BATON_LINK_NONE.

Parameters:

link Link state.
now_ms Current time.

Return value:

BATON_LINK_FRAME A valid frame is available through baton_link_frame().
BATON_LINK_TX_DONE The echo of the own frame is complete.
BATON_LINK_NONE The ring is empty (or link is NULL).

function baton_link_rx_busy¶

Whether a frame is being received right now.

bool baton_link_rx_busy (
    const struct baton_link * link,
    uint32_t now_ms
)

Parameters:

link Link state.
now_ms Current time.

Returns:

true when the parser is inside a frame and the inter-byte timeout has not expired.

function baton_link_rx_isr¶

Store one received byte.

void baton_link_rx_isr (
    struct baton_link * link,
    uint8_t byte
)

Call from the UART receive interrupt.

A byte that does not fit into the ring is counted and dropped.

Parameters:

link Link state; NULL is ignored.
byte Received byte.

function baton_link_send¶

Request the transmission of a complete frame.

int baton_link_send (
    struct baton_link * link,
    const uint8_t * data,
    size_t length
)

The frame is sent by baton_link_transmit() after the bus has been silent for tx_gap_ms. The buffer must stay valid until the link reports BATON_LINK_TX_DONE. A new request replaces a pending one.

Parameters:

link Link state.
data Complete frame, SYNC to CRC.
length Number of bytes (1..BATON_FRAME_MAX).

Return value:

0 Request stored.
BATON_PARSE_ERROR NULL argument or invalid length.

function baton_link_transmit¶

Start a requested transmission when the bus is silent; supervise a running one.

int baton_link_transmit (
    struct baton_link * link,
    uint32_t now_ms
)

Parameters:

link Link state.
now_ms Current time.

Return value:

BATON_LINK_TX_DONE The transmission finished, failed to start or timed out.
BATON_LINK_NONE Nothing to report (or link is NULL).

function baton_link_tx_done_isr¶

Signal the end of a transmission.

void baton_link_tx_done_isr (
    struct baton_link * link
)

Call from the UART TX-complete interrupt.

Needed only when baton_link_config::rx_echo is false.

Parameters:

link Link state; NULL is ignored.

Macro Definition Documentation¶

define BATON_LINK_FRAME¶

A valid frame was received; read it with baton_link_frame() .

#define BATON_LINK_FRAME `1`

define BATON_LINK_NONE¶

Nothing happened; the receive ring is empty or the transmitter has nothing to report.

#define BATON_LINK_NONE `0`

define BATON_LINK_TX_DONE¶

The frame passed to baton_link_send() was transmitted, failed or timed out.

#define BATON_LINK_TX_DONE `2`