1 files changed, 518 insertions, 0 deletions

diff --git a/src/core/soft_uart.c b/src/core/soft_uart.c
new file mode 100644
index 00000000..f969ab70
--- /dev/null
+++ b/src/core/soft_uart.c
@@ -0,0 +1,518 @@
+/*! \file soft_uart.c
+ *  Software UART implementation. */
+/*
+ * (C) 2022 by Harald Welte <laforge@gnumonks.org>
+ * (C) 2023 by sysmocom - s.f.m.c. GmbH <info@sysmocom.de>
+ *
+ * All Rights Reserved
+ *
+ * SPDX-License-Identifier: GPL-2.0+
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation; either version 2 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ */
+
+#include <stdbool.h>
+#include <stdint.h>
+#include <errno.h>
+
+#include <osmocom/core/utils.h>
+#include <osmocom/core/timer.h>
+#include <osmocom/core/soft_uart.h>
+
+/*! Rx/Tx flow state of a soft-UART */
+enum suart_flow_state {
+	SUART_FLOW_ST_IDLE,	/*!< waiting for a start bit or Tx data */
+	SUART_FLOW_ST_DATA,	/*!< receiving/transmitting data bits */
+	SUART_FLOW_ST_PARITY,	/*!< receiving/transmitting parity bits */
+	SUART_FLOW_ST_STOP,	/*!< receiving/transmitting stop bits */
+};
+
+/*! Internal state of a soft-UART */
+struct osmo_soft_uart {
+	struct osmo_soft_uart_cfg cfg;
+	const char *name;
+	/* modem status (bitmask of OSMO_SUART_STATUS_F_*) */
+	unsigned int status;
+	struct {
+		bool running;
+		uint8_t bit_count;
+		uint8_t shift_reg;
+		struct msgb *msg;
+		ubit_t parity_bit; /* 0 (even) / 1 (odd) */
+		unsigned int flags;
+		struct osmo_timer_list timer;
+		enum suart_flow_state flow_state;
+	} rx;
+	struct {
+		bool running;
+		uint8_t bit_count;
+		uint8_t shift_reg;
+		ubit_t parity_bit; /* 0 (even) / 1 (odd) */
+		enum suart_flow_state flow_state;
+	} tx;
+};
+
+/*! Default soft-UART configuration (8-N-1) */
+const struct osmo_soft_uart_cfg osmo_soft_uart_default_cfg = {
+	.num_data_bits = 8,
+	.num_stop_bits = 1,
+	.parity_mode = OSMO_SUART_PARITY_NONE,
+	.rx_buf_size = 1024,
+	.rx_timeout_ms = 100,
+	.flow_ctrl_mode = OSMO_SUART_FLOW_CTRL_NONE,
+};
+
+/*************************************************************************
+ * Receiver
+ *************************************************************************/
+
+/*! Flush the receive buffer, passing ownership of the msgb to the .rx_cb().
+ * \param[in] suart soft-UART instance holding the receive buffer. */
+void osmo_soft_uart_flush_rx(struct osmo_soft_uart *suart)
+{
+	if (suart->rx.msg && msgb_length(suart->rx.msg)) {
+		osmo_timer_del(&suart->rx.timer);
+		if (suart->cfg.rx_cb) {
+			suart->cfg.rx_cb(suart->cfg.priv, suart->rx.msg, suart->rx.flags);
+			/* call-back has taken ownership of msgb, no need to free() here */
+			suart->rx.msg = msgb_alloc_c(suart, suart->cfg.rx_buf_size, "soft_uart_rx");
+		} else {
+			msgb_reset(suart->rx.msg);
+		}
+	}
+}
+
+/* one character was received; add to receive buffer and notify user, if needed */
+static void suart_rx_ch(struct osmo_soft_uart *suart, uint8_t ch)
+{
+	unsigned int msg_len;
+
+	OSMO_ASSERT(suart->rx.msg);
+	msgb_put_u8(suart->rx.msg, ch);
+	msg_len = msgb_length(suart->rx.msg);
+
+	if (msg_len >= suart->cfg.rx_buf_size || suart->rx.flags) {
+		/* either the buffer is full, or we hit a parity and/or a framing error */
+		osmo_soft_uart_flush_rx(suart);
+	} else if (msg_len == 1) {
+		/* first character in new message: start timer */
+		osmo_timer_schedule(&suart->rx.timer, suart->cfg.rx_timeout_ms / 1000,
+				    (suart->cfg.rx_timeout_ms % 1000) * 1000);
+	}
+}
+
+/* receive a single bit */
+static inline void suart_rx_bit(struct osmo_soft_uart *suart, const ubit_t bit)
+{
+	switch (suart->rx.flow_state) {
+	case SUART_FLOW_ST_IDLE:
+		if (bit == 0) { /* start bit condition */
+			suart->rx.flow_state = SUART_FLOW_ST_DATA;
+			suart->rx.flags = 0x00;
+			suart->rx.shift_reg = 0;
+			suart->rx.bit_count = 0;
+			suart->rx.parity_bit = 0;
+		}
+		break;
+	case SUART_FLOW_ST_DATA:
+		suart->rx.bit_count++;
+		suart->rx.shift_reg >>= 1;
+		if (bit != 0) {
+			suart->rx.parity_bit = !suart->rx.parity_bit; /* flip */
+			suart->rx.shift_reg |= 0x80;
+		}
+		if (suart->rx.bit_count >= suart->cfg.num_data_bits) {
+			/* we have accumulated enough data bits */
+			if (suart->cfg.parity_mode != OSMO_SUART_PARITY_NONE)
+				suart->rx.flow_state = SUART_FLOW_ST_PARITY;
+			else
+				suart->rx.flow_state = SUART_FLOW_ST_STOP;
+			/* align the register if needed */
+			if (suart->cfg.num_data_bits < 8)
+				suart->rx.shift_reg >>= (8 - suart->cfg.num_data_bits);
+		}
+		break;
+	case SUART_FLOW_ST_PARITY:
+		switch (suart->cfg.parity_mode) {
+		case OSMO_SUART_PARITY_EVEN:
+			/* number of 1-bits (in both data and parity) shall be even */
+			if (suart->rx.parity_bit != bit)
+				suart->rx.flags |= OSMO_SUART_F_PARITY_ERROR;
+			break;
+		case OSMO_SUART_PARITY_ODD:
+			/* number of 1-bits (in both data and parity) shall be odd */
+			if (suart->rx.parity_bit == bit)
+				suart->rx.flags |= OSMO_SUART_F_PARITY_ERROR;
+			break;
+		case OSMO_SUART_PARITY_MARK:
+			/* parity bit must always be 1 */
+			if (bit != 1)
+				suart->rx.flags |= OSMO_SUART_F_PARITY_ERROR;
+			break;
+		case OSMO_SUART_PARITY_SPACE:
+			/* parity bit must always be 0 */
+			if (bit != 0)
+				suart->rx.flags |= OSMO_SUART_F_PARITY_ERROR;
+			break;
+		case OSMO_SUART_PARITY_NONE: /* shall not happen */
+		default:
+			OSMO_ASSERT(0);
+		}
+
+		suart->rx.flow_state = SUART_FLOW_ST_STOP;
+		break;
+	case SUART_FLOW_ST_STOP:
+		suart->rx.bit_count++;
+		if (bit != 1)
+			suart->rx.flags |= OSMO_SUART_F_FRAMING_ERROR;
+
+		if (suart->rx.bit_count >= (suart->cfg.num_data_bits + suart->cfg.num_stop_bits)) {
+			/* we have accumulated enough stop bits */
+			suart_rx_ch(suart, suart->rx.shift_reg);
+			suart->rx.flow_state = SUART_FLOW_ST_IDLE;
+		}
+		break;
+	}
+}
+
+/* receive timer expiration: flush rx-buffer to user call-back */
+static void suart_rx_timer_cb(void *data)
+{
+	struct osmo_soft_uart *suart = data;
+	osmo_soft_uart_flush_rx(suart);
+}
+
+/*! Feed a number of unpacked bits into the soft-UART receiver.
+ * \param[in] suart soft-UART instance to feed bits into.
+ * \param[in] ubits pointer to the unpacked bits.
+ * \param[in] n_ubits number of unpacked bits to be fed.
+ * \returns 0 on success; negative on error.
+ *          -EAGAIN indicates that the receiver is disabled. */
+int osmo_soft_uart_rx_ubits(struct osmo_soft_uart *suart, const ubit_t *ubits, size_t n_ubits)
+{
+	if (!suart->rx.running)
+		return -EAGAIN;
+	for (size_t i = 0; i < n_ubits; i++)
+		suart_rx_bit(suart, ubits[i]);
+	return 0;
+}
+
+/*************************************************************************
+ * Transmitter
+ *************************************************************************/
+
+/* pull a single bit out of the UART transmitter */
+static inline ubit_t suart_tx_bit(struct osmo_soft_uart *suart, struct msgb *msg)
+{
+	ubit_t tx_bit = 1;
+
+	switch (suart->tx.flow_state) {
+	case SUART_FLOW_ST_IDLE:
+		if (msg && msgb_length(msg) > 0) { /* if we have pending data */
+			suart->tx.shift_reg = msgb_pull_u8(msg);
+			suart->tx.flow_state = SUART_FLOW_ST_DATA;
+			suart->tx.bit_count = 0;
+			suart->tx.parity_bit = 0;
+			tx_bit = 0;
+		}
+		break;
+	case SUART_FLOW_ST_DATA:
+		tx_bit = suart->tx.shift_reg & 1;
+		suart->tx.parity_bit ^= tx_bit;
+		suart->tx.shift_reg >>= 1;
+		suart->tx.bit_count++;
+		if (suart->tx.bit_count >= suart->cfg.num_data_bits) {
+			/* we have transmitted all data bits */
+			if (suart->cfg.parity_mode != OSMO_SUART_PARITY_NONE)
+				suart->tx.flow_state = SUART_FLOW_ST_PARITY;
+			else
+				suart->tx.flow_state = SUART_FLOW_ST_STOP;
+		}
+		break;
+	case SUART_FLOW_ST_PARITY:
+		switch (suart->cfg.parity_mode) {
+		case OSMO_SUART_PARITY_EVEN:
+			/* number of 1-bits (in both data and parity) shall be even */
+			tx_bit = suart->tx.parity_bit;
+			break;
+		case OSMO_SUART_PARITY_ODD:
+			/* number of 1-bits (in both data and parity) shall be odd */
+			tx_bit = !suart->tx.parity_bit;
+			break;
+		case OSMO_SUART_PARITY_MARK:
+			/* parity bit must always be 1 */
+			tx_bit = 1;
+			break;
+		case OSMO_SUART_PARITY_SPACE:
+			/* parity bit must always be 0 */
+			tx_bit = 0;
+			break;
+		case OSMO_SUART_PARITY_NONE:
+		default: /* shall not happen */
+			OSMO_ASSERT(0);
+		}
+
+		suart->tx.flow_state = SUART_FLOW_ST_STOP;
+		break;
+	case SUART_FLOW_ST_STOP:
+		suart->tx.bit_count++;
+		if (suart->tx.bit_count >= (suart->cfg.num_data_bits + suart->cfg.num_stop_bits)) {
+			/* we have transmitted all stop bits, we're done */
+			suart->tx.flow_state = SUART_FLOW_ST_IDLE;
+		}
+		break;
+	}
+
+	return tx_bit;
+}
+
+/* pull pending bits out of the UART */
+static size_t suart_tx_pending(struct osmo_soft_uart *suart, ubit_t *ubits, size_t n_ubits)
+{
+	size_t i;
+
+	for (i = 0; i < n_ubits; i++) {
+		if (suart->tx.flow_state == SUART_FLOW_ST_IDLE)
+			break;
+		ubits[i] = suart_tx_bit(suart, NULL);
+	}
+
+	return i;
+}
+
+/*! Pull a number of unpacked bits out of the soft-UART transmitter.
+ * \param[in] suart soft-UART instance to pull the bits from.
+ * \param[out] ubits pointer to a buffer where to store pulled bits.
+ * \param[in] n_ubits number of unpacked bits to be pulled.
+ * \returns number of bits pulled (may be less than n_ubits); negative on error.
+ *          -EAGAIN indicates that the transmitter is disabled. */
+int osmo_soft_uart_tx_ubits(struct osmo_soft_uart *suart, ubit_t *ubits, size_t n_ubits)
+{
+	const struct osmo_soft_uart_cfg *cfg = &suart->cfg;
+	size_t n_frame_bits, n_chars;
+	struct msgb *msg = NULL;
+
+	if (OSMO_UNLIKELY(n_ubits == 0))
+		return -EINVAL;
+
+	if (!suart->tx.running)
+		return -EAGAIN;
+
+	switch (suart->cfg.flow_ctrl_mode) {
+	case OSMO_SUART_FLOW_CTRL_DTR_DSR:
+		/* if DSR is de-asserted, Tx pending bits and suspend */
+		if (~suart->status & OSMO_SUART_STATUS_F_DSR)
+			return suart_tx_pending(suart, ubits, n_ubits);
+		/* else: keep transmitting as usual */
+		break;
+	case OSMO_SUART_FLOW_CTRL_RTS_CTS:
+		/* if CTS is de-asserted, Tx pending bits and suspend */
+		if (~suart->status & OSMO_SUART_STATUS_F_CTS)
+			return suart_tx_pending(suart, ubits, n_ubits);
+		/* else: keep transmitting as usual */
+		break;
+	case OSMO_SUART_FLOW_CTRL_NONE:
+	default:
+		break;
+	}
+
+	/* calculate UART frame size for the effective config */
+	n_frame_bits = 1 + cfg->num_data_bits + cfg->num_stop_bits;
+	if (cfg->parity_mode != OSMO_SUART_PARITY_NONE)
+		n_frame_bits += 1;
+
+	/* calculate the number of characters we can fit into n_ubits */
+	n_chars = n_ubits / n_frame_bits;
+	if (n_chars == 0) {
+		/* we can transmit at least one character */
+		if (suart->tx.flow_state == SUART_FLOW_ST_IDLE)
+			n_chars = 1;
+	}
+
+	if (n_chars > 0) {
+		/* allocate a Tx buffer msgb */
+		msg = msgb_alloc_c(suart, n_chars, "soft_uart_tx");
+		OSMO_ASSERT(msg != NULL);
+
+		/* call the .tx_cb() to populate the Tx buffer */
+		OSMO_ASSERT(cfg->tx_cb != NULL);
+		suart->cfg.tx_cb(cfg->priv, msg);
+	}
+
+	for (size_t i = 0; i < n_ubits; i++)
+		ubits[i] = suart_tx_bit(suart, msg);
+	msgb_free(msg);
+
+	return n_ubits;
+}
+
+/*! Get the modem status bitmask of the given soft-UART.
+ * \param[in] suart soft-UART instance to get the modem status.
+ * \returns bitmask of OSMO_SUART_STATUS_F_*. */
+unsigned int osmo_soft_uart_get_status(const struct osmo_soft_uart *suart)
+{
+	return suart->status;
+}
+
+/*! Set the modem status bitmask of the given soft-UART.
+ * \param[in] suart soft-UART instance to set the modem status.
+ * \param[in] status bitmask of OSMO_SUART_STATUS_F_*.
+ * \returns 0 on success; negative on error. */
+int osmo_soft_uart_set_status(struct osmo_soft_uart *suart, unsigned int status)
+{
+	const struct osmo_soft_uart_cfg *cfg = &suart->cfg;
+
+	if (cfg->status_change_cb != NULL) {
+		if (suart->status != status)
+			cfg->status_change_cb(cfg->priv, status);
+	}
+
+	suart->status = status;
+	return 0;
+}
+
+/*! Activate/deactivate a modem status line of the given soft-UART.
+ * \param[in] suart soft-UART instance to update the modem status.
+ * \param[in] line a modem status line, one of OSMO_SUART_STATUS_F_*.
+ * \param[in] active activate (true) or deactivate (false) the line. */
+void osmo_soft_uart_set_status_line(struct osmo_soft_uart *suart,
+				    enum osmo_soft_uart_status line,
+				    bool active)
+{
+	unsigned int status = suart->status;
+
+	if (active) /* assert the given line */
+		status |= line;
+	else /* de-assert the given line */
+		status &= ~line;
+
+	osmo_soft_uart_set_status(suart, status);
+}
+
+
+/*************************************************************************
+ * Management / Initialization
+ *************************************************************************/
+
+/*! Allocate a soft-UART instance.
+ * \param[in] ctx parent talloc context.
+ * \param[in] name name of the soft-UART instance.
+ * \param[in] cfg initial configuration of the soft-UART instance.
+ * \returns pointer to allocated soft-UART instance; NULL on error. */
+struct osmo_soft_uart *osmo_soft_uart_alloc(void *ctx, const char *name,
+					    const struct osmo_soft_uart_cfg *cfg)
+{
+	struct osmo_soft_uart *suart = talloc_zero(ctx, struct osmo_soft_uart);
+	if (!suart)
+		return NULL;
+	suart->name = talloc_strdup(suart, name);
+
+	OSMO_ASSERT(cfg != NULL);
+	suart->cfg = *cfg;
+
+	return suart;
+}
+
+/*! Release memory taken by the given soft-UART.
+ * \param[in] suart soft-UART instance to be free()d. */
+void osmo_soft_uart_free(struct osmo_soft_uart *suart)
+{
+	if (suart == NULL)
+		return;
+
+	osmo_timer_del(&suart->rx.timer);
+	msgb_free(suart->rx.msg);
+
+	talloc_free((void *)suart->name);
+	talloc_free(suart);
+}
+
+/*! Change soft-UART configuration to the user-provided config.
+ * \param[in] suart soft-UART instance to be re-configured.
+ * \param[in] cfg the user-provided config to be applied.
+ * \returns 0 on success; negative on error. */
+int osmo_soft_uart_configure(struct osmo_soft_uart *suart, const struct osmo_soft_uart_cfg *cfg)
+{
+	/* consistency checks on the configuration */
+	if (cfg->num_data_bits > 8 || cfg->num_data_bits == 0)
+		return -EINVAL;
+	if (cfg->num_stop_bits == 0)
+		return -EINVAL;
+	if (cfg->parity_mode < 0 || cfg->parity_mode >= _OSMO_SUART_PARITY_NUM)
+		return -EINVAL;
+	if (cfg->rx_buf_size == 0)
+		return -EINVAL;
+
+	if (suart->cfg.rx_buf_size > cfg->rx_buf_size ||
+	    suart->cfg.rx_timeout_ms > cfg->rx_timeout_ms) {
+		osmo_soft_uart_flush_rx(suart);
+	}
+
+	suart->cfg = *cfg;
+
+	osmo_timer_setup(&suart->rx.timer, suart_rx_timer_cb, suart);
+
+	return 0;
+}
+
+/*! Get a name for the given soft-UART instance.
+ * \param[in] suart soft-UART instance to get the name from.
+ * \returns name of the given soft-UART instance. */
+const char *osmo_soft_uart_get_name(const struct osmo_soft_uart *suart)
+{
+	return suart->name;
+}
+
+/*! Set a new name for the given soft-UART instance.
+ * \param[in] suart soft-UART instance to set the name for.
+ * \param[in] name the new name. */
+void osmo_soft_uart_set_name(struct osmo_soft_uart *suart, const char *name)
+{
+	osmo_talloc_replace_string(suart, (char **)&suart->name, name);
+}
+
+/*! Enable/disable receiver of the given soft-UART.
+ * \param[in] suart soft-UART instance to be re-configured.
+ * \param[in] enable enable/disable state of the receiver.
+ * \returns 0 on success; negative on error. */
+int osmo_soft_uart_set_rx(struct osmo_soft_uart *suart, bool enable)
+{
+	if (!enable && suart->rx.running) {
+		osmo_soft_uart_flush_rx(suart);
+		suart->rx.running = false;
+		suart->rx.flow_state = SUART_FLOW_ST_IDLE;
+	} else if (enable && !suart->rx.running) {
+		if (!suart->rx.msg)
+			suart->rx.msg = msgb_alloc_c(suart, suart->cfg.rx_buf_size, "soft_uart_rx");
+		suart->rx.running = true;
+		suart->rx.flow_state = SUART_FLOW_ST_IDLE;
+	}
+
+	return 0;
+}
+
+/*! Enable/disable transmitter of the given soft-UART.
+ * \param[in] suart soft-UART instance to be re-configured.
+ * \param[in] enable enable/disable state of the transmitter.
+ * \returns 0 on success; negative on error. */
+int osmo_soft_uart_set_tx(struct osmo_soft_uart *suart, bool enable)
+{
+	if (!enable && suart->tx.running) {
+		suart->tx.running = false;
+		suart->tx.flow_state = SUART_FLOW_ST_IDLE;
+	} else if (enable && !suart->tx.running) {
+		suart->tx.running = true;
+		suart->tx.flow_state = SUART_FLOW_ST_IDLE;
+	}
+
+	return 0;
+}