diff options
Diffstat (limited to 'src/core/soft_uart.c')
-rw-r--r-- | src/core/soft_uart.c | 518 |
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; +} |