Illustrated C/C++ source sheets, symbol index, API relationship graph, compiler console and debug trace

LIVE AI / FLEXIBLE SENSING / FLIGHT CONTEXT

Sensoraia API

Live AI and sensing, connected to the flight.
See, listen, inspect and return supported results while airborne.

Loading...
Searching...
No Matches
serial_tx.c
Go to the documentation of this file.
1/*
2 * Copyright 2026 OpenUAS
3 * SPDX-License-Identifier: Apache-2.0
4 *
5 * Licensed under the Apache License, Version 2.0 (the "License");
6 * you may not use this file except in compliance with the License.
7 * You may obtain a copy of the License at
8 *
9 * http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17
18#include "serial_tx.h"
19#include "usher_protocol.h"
20#include <errno.h>
21#include <fcntl.h>
22#include <pthread.h>
23#include <unistd.h>
24
25/**
26 * @file serial_tx.c
27 * @brief Bounded mutex-protected output queue for USHER UART frames.
28 * @details Writes are non-blocking and may be partial. The ring buffer retains the
29 * unsent suffix until the main event loop sees POLLOUT. A permanent write failure is
30 * latched instead of silently dropping later messages, allowing USHER to exit and
31 * let systemd recover the UART connection.
32 */
33
34#define SERIAL_TX_CAPACITY 4096
35
36static pthread_mutex_t transmit_mutex = PTHREAD_MUTEX_INITIALIZER;
38static size_t head, count;
39static int output_fd = -1;
40static int output_error;
41
42/** @brief Flush as much queued output as the descriptor currently accepts.
43 * @pre transmit_mutex is held.
44 * @return 0 for success or temporary backpressure, -1 for a latched terminal error.
45 * @details EAGAIN/EINTR deliberately retain the ring contents. Other errors are
46 * retained in @c output_error so the owning event loop can surface the failure. */
47static int flush_locked(void)
48{
49 if (output_fd < 0 || output_error != 0) {
50 errno = output_error != 0 ? output_error : ENOTCONN;
51 return -1;
52 }
53 while (count > 0) {
54 size_t length = SERIAL_TX_CAPACITY - head;
55 if (length > count) length = count;
56 ssize_t sent = write(output_fd, pending + head, length);
57 if (sent > 0) {
58 head = (head + (size_t)sent) % SERIAL_TX_CAPACITY;
59 count -= (size_t)sent;
60 } else if (sent < 0 && (errno == EAGAIN || errno == EWOULDBLOCK || errno == EINTR)) {
61 return 0;
62 } else {
63 output_error = sent < 0 ? errno : EIO;
64 errno = output_error;
65 return -1;
66 }
67 }
68 return 0;
69}
70
72{
73 const int flags = fcntl(descriptor, F_GETFL);
74 if (flags < 0) return -1;
75 if (!(flags & O_NONBLOCK)) {
76 errno = EINVAL;
77 return -1;
78 }
79 pthread_mutex_lock(&transmit_mutex);
80 if (output_fd >= 0) {
81 pthread_mutex_unlock(&transmit_mutex);
82 errno = EBUSY;
83 return -1;
84 }
86 output_error = 0;
87 head = count = 0;
88 pthread_mutex_unlock(&transmit_mutex);
89 return 0;
90}
91
93{
94 pthread_mutex_lock(&transmit_mutex);
95 output_fd = -1;
96 output_error = 0;
97 head = count = 0;
98 pthread_mutex_unlock(&transmit_mutex);
99}
100
101/** @brief Construct, enqueue, and opportunistically transmit one framed message.
102 * @param message Protocol ID.
103 * @param payload Payload, if any.
104 * @param length Payload byte count.
105 * @param idle_only Whether low-priority traffic must avoid an occupied queue.
106 * @return 0 on acceptance or -1 with errno on validation, queue, or I/O failure.
107 * @details The frame is first built on the stack, then copied atomically while the
108 * mutex is held. This avoids exposing an incomplete frame to another producer. */
109static int send_frame(uint8_t message, const uint8_t *payload, size_t length, bool idle_only)
110{
111 if (length > 250 || (length > 0 && payload == NULL)) {
112 errno = EINVAL;
113 return -1;
114 }
115 uint8_t frame[255];
116 const size_t frame_length = length + 5;
117 frame[0] = STX;
118 frame[1] = (uint8_t)frame_length;
119 frame[2] = message;
120 uint8_t checksum_a = frame[1], checksum_b = checksum_a;
121 for (size_t index = 0; index <= length; ++index) {
122 if (index > 0) frame[index + 2] = payload[index - 1];
123 checksum_a += frame[index + 2];
124 checksum_b += checksum_a;
125 }
126 frame[frame_length - 2] = checksum_a;
127 frame[frame_length - 1] = checksum_b;
128 if (idle_only) {
129 if (pthread_mutex_trylock(&transmit_mutex) != 0) {
130 errno = EAGAIN;
131 return -1;
132 }
133 if (count > 0) {
134 pthread_mutex_unlock(&transmit_mutex);
135 errno = EAGAIN;
136 return -1;
137 }
138 } else {
139 pthread_mutex_lock(&transmit_mutex);
140 }
141 int result = flush_locked();
142 if (result == 0 && frame_length > SERIAL_TX_CAPACITY - count) {
143 errno = ENOBUFS;
144 result = -1;
145 } else if (result == 0) {
146 for (size_t index = 0; index < frame_length; ++index) {
147 pending[(head + count + index) % SERIAL_TX_CAPACITY] = frame[index];
148 }
149 count += frame_length;
151 }
152 pthread_mutex_unlock(&transmit_mutex);
153 return result;
154}
155
156int serial_tx_send(uint8_t message, const uint8_t *payload, size_t length)
157{
158 return send_frame(message, payload, length, false);
159}
160
161int serial_tx_send_if_idle(uint8_t message, const uint8_t *payload, size_t length)
162{
163 return send_frame(message, payload, length, true);
164}
165
167{
168 pthread_mutex_lock(&transmit_mutex);
169 int result = flush_locked();
170 pthread_mutex_unlock(&transmit_mutex);
171 return result;
172}
173
175{
176 pthread_mutex_lock(&transmit_mutex);
177 /** Once set, output_error never clears itself; also report pending when it is set
178 * (even with an empty queue) so the caller's poll loop keeps asking for POLLOUT and
179 * promptly calls serial_tx_flush(), which surfaces the failure instead of leaving
180 * UART output silently and permanently stuck. */
181 bool result = output_fd >= 0 && (count > 0 || output_error != 0);
182 pthread_mutex_unlock(&transmit_mutex);
183 return result;
184}
int descriptor
Definition chdk_pipe.c:142
static bool pending
uint8_t frame[LWIR_MAX_FRAME_BYTES]
Definition lwir_mock.c:58
static size_t head
Definition pose_log.c:79
static size_t count
Definition pose_log.c:79
static int output_error
Definition serial_tx.c:40
int serial_tx_start(int descriptor)
Attach an already-open non-blocking UART descriptor.
Definition serial_tx.c:71
int serial_tx_send(uint8_t message, const uint8_t *payload, size_t length)
Queue and opportunistically flush one complete USHER frame.
Definition serial_tx.c:156
#define SERIAL_TX_CAPACITY
Definition serial_tx.c:34
static int output_fd
Definition serial_tx.c:39
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.
Definition serial_tx.c:109
void serial_tx_stop(void)
Discard pending output and detach the UART during shutdown/restart.
Definition serial_tx.c:92
int serial_tx_flush(void)
Continue writing queued bytes after POLLOUT reports readiness.
Definition serial_tx.c:166
static int flush_locked(void)
Flush as much queued output as the descriptor currently accepts.
Definition serial_tx.c:47
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.
Definition serial_tx.c:161
bool serial_tx_pending(void)
Report queued data or a latched output error needing event-loop handling.
Definition serial_tx.c:174
static pthread_mutex_t transmit_mutex
Definition serial_tx.c:36
Thread-safe, non-blocking framed UART transmission for USHER.
struct usher_control_result result
Definition usher.c:377
Shared FC/MORA byte-stream UART framing, messages and payload layouts.
#define STX