Bounded mutex-protected output queue for USHER UART frames. More...
#include "serial_tx.h"#include "usher_protocol.h"#include <errno.h>#include <fcntl.h>#include <pthread.h>#include <unistd.h>
Go to the source code of this file.
Macros | |
| #define | SERIAL_TX_CAPACITY 4096 |
Functions | |
| static int | flush_locked (void) |
| Flush as much queued output as the descriptor currently accepts. | |
| int | serial_tx_start (int descriptor) |
| Attach an already-open non-blocking UART descriptor. | |
| void | serial_tx_stop (void) |
| Discard pending output and detach the UART during shutdown/restart. | |
| static int | send_frame (uint8_t message, const uint8_t *payload, size_t length, bool idle_only) |
| Construct, enqueue, and opportunistically transmit one framed message. | |
| int | serial_tx_send (uint8_t message, const uint8_t *payload, size_t length) |
| Queue and opportunistically flush one complete USHER frame. | |
| int | serial_tx_send_if_idle (uint8_t message, const uint8_t *payload, size_t length) |
| Send only when no earlier frame is queued, for low-priority probes. | |
| int | serial_tx_flush (void) |
| Continue writing queued bytes after POLLOUT reports readiness. | |
| bool | serial_tx_pending (void) |
| Report queued data or a latched output error needing event-loop handling. | |
Variables | |
| static pthread_mutex_t | transmit_mutex = PTHREAD_MUTEX_INITIALIZER |
| static uint8_t | pending [SERIAL_TX_CAPACITY] |
| static size_t | head |
| static size_t | count |
| static int | output_fd = -1 |
| static int | output_error |
Detailed Description
Bounded mutex-protected output queue for USHER UART frames.
Writes are non-blocking and may be partial. The ring buffer retains the unsent suffix until the main event loop sees POLLOUT. A permanent write failure is latched instead of silently dropping later messages, allowing USHER to exit and let systemd recover the UART connection.
Definition in file serial_tx.c.
Macro Definition Documentation
◆ SERIAL_TX_CAPACITY
| #define SERIAL_TX_CAPACITY 4096 |
Definition at line 34 of file serial_tx.c.
Function Documentation
◆ flush_locked()
|
static |
Flush as much queued output as the descriptor currently accepts.
- Precondition
- transmit_mutex is held.
- Returns
- 0 for success or temporary backpressure, -1 for a latched terminal error.
EAGAIN/EINTR deliberately retain the ring contents. Other errors are retained in output_error so the owning event loop can surface the failure.
Definition at line 47 of file serial_tx.c.
◆ send_frame()
|
static |
Construct, enqueue, and opportunistically transmit one framed message.
- Parameters
-
message Protocol ID. payload Payload, if any. length Payload byte count. idle_only Whether low-priority traffic must avoid an occupied queue.
- Returns
- 0 on acceptance or -1 with errno on validation, queue, or I/O failure.
The frame is first built on the stack, then copied atomically while the mutex is held. This avoids exposing an incomplete frame to another producer.
Definition at line 109 of file serial_tx.c.
◆ serial_tx_flush()
| int serial_tx_flush | ( | void | ) |
Continue writing queued bytes after POLLOUT reports readiness.
- Returns
- 0 when output remains usable, or -1 for a terminal transport failure.
Definition at line 166 of file serial_tx.c.
◆ serial_tx_pending()
| bool serial_tx_pending | ( | void | ) |
Report queued data or a latched output error needing event-loop handling.
- Returns
- True while the event loop should request POLLOUT and call serial_tx_flush().
Once set, output_error never clears itself; also report pending when it is set (even with an empty queue) so the caller's poll loop keeps asking for POLLOUT and promptly calls serial_tx_flush(), which surfaces the failure instead of leaving UART output silently and permanently stuck.
Definition at line 174 of file serial_tx.c.
◆ serial_tx_send()
| int serial_tx_send | ( | uint8_t | message, |
| const uint8_t * | payload, | ||
| size_t | length ) |
Queue and opportunistically flush one complete USHER frame.
- Parameters
-
message Protocol message ID. payload Payload bytes, or NULL when lengthis zero.length Payload size, limited by the one-byte protocol length field.
- Returns
- 0 if queued/flushed, or -1 when the buffer or transport cannot accept it.
Definition at line 156 of file serial_tx.c.
◆ serial_tx_send_if_idle()
| int serial_tx_send_if_idle | ( | uint8_t | message, |
| const uint8_t * | payload, | ||
| size_t | length ) |
Send only when no earlier frame is queued, for low-priority probes.
Avoids delaying flight-critical status traffic with a clock probe.
- Returns
- 0 on acceptance, or -1 with EAGAIN when output is busy.
Definition at line 161 of file serial_tx.c.
◆ serial_tx_start()
| int serial_tx_start | ( | int | descriptor | ) |
Attach an already-open non-blocking UART descriptor.
- Parameters
-
descriptor Descriptor configured with O_NONBLOCK.
- Returns
- 0 on success, or -1 with errno describing an invalid/busy descriptor.
Definition at line 71 of file serial_tx.c.
◆ serial_tx_stop()
| void serial_tx_stop | ( | void | ) |
Discard pending output and detach the UART during shutdown/restart.
Definition at line 92 of file serial_tx.c.
Variable Documentation
◆ count
|
static |
Definition at line 38 of file serial_tx.c.
◆ head
|
static |
Definition at line 38 of file serial_tx.c.
◆ output_error
|
static |
Definition at line 40 of file serial_tx.c.
◆ output_fd
|
static |
Definition at line 39 of file serial_tx.c.
◆ pending
|
static |
Definition at line 37 of file serial_tx.c.
◆ transmit_mutex
|
static |
Definition at line 36 of file serial_tx.c.