Software UART implementation. More...

#include <stdint.h>
#include <stdbool.h>
#include <osmocom/core/bits.h>
#include <osmocom/core/msgb.h>

Data Structures
struct	osmo_soft_uart_cfg
	Configuration for a soft-UART. More...

Enumerations
enum	osmo_soft_uart_parity_mode { OSMO_SUART_PARITY_NONE , OSMO_SUART_PARITY_EVEN , OSMO_SUART_PARITY_ODD , OSMO_SUART_PARITY_MARK , OSMO_SUART_PARITY_SPACE , _OSMO_SUART_PARITY_NUM }
	Parity mode. More...

enum	osmo_soft_uart_flags { OSMO_SUART_F_FRAMING_ERROR = (1 << 0) , OSMO_SUART_F_PARITY_ERROR = (1 << 1) , OSMO_SUART_F_BREAK = (1 << 2) }
	Flags passed to the application. More...

enum	osmo_soft_uart_status { OSMO_SUART_STATUS_F_DTR = (1 << 0) , OSMO_SUART_STATUS_F_DCD = (1 << 1) , OSMO_SUART_STATUS_F_DSR = (1 << 2) , OSMO_SUART_STATUS_F_RI = (1 << 3) , OSMO_SUART_STATUS_F_RTS_RTR = (1 << 4) , OSMO_SUART_STATUS_F_CTS = (1 << 5) }
	Modem status "line" flags. More...

enum	osmo_soft_uart_flow_ctrl_mode { OSMO_SUART_FLOW_CTRL_NONE , OSMO_SUART_FLOW_CTRL_DTR_DSR , OSMO_SUART_FLOW_CTRL_RTS_CTS }
	Flow control mode. More...

Functions
struct osmo_soft_uart *	osmo_soft_uart_alloc (void ctx, const char name, const struct osmo_soft_uart_cfg *cfg)
	Allocate a soft-UART instance. More...

void	osmo_soft_uart_free (struct osmo_soft_uart *suart)
	Release memory taken by the given soft-UART. More...

int	osmo_soft_uart_configure (struct osmo_soft_uart suart, const struct osmo_soft_uart_cfg cfg)
	Change soft-UART configuration to the user-provided config. More...

const char *	osmo_soft_uart_get_name (const struct osmo_soft_uart *suart)
	Get a name for the given soft-UART instance. More...

void	osmo_soft_uart_set_name (struct osmo_soft_uart suart, const char name)
	Set a new name for the given soft-UART instance. More...

int	osmo_soft_uart_set_rx (struct osmo_soft_uart *suart, bool enable)
	Enable/disable receiver of the given soft-UART. More...

int	osmo_soft_uart_set_tx (struct osmo_soft_uart *suart, bool enable)
	Enable/disable transmitter of the given soft-UART. More...

int	osmo_soft_uart_rx_ubits (struct osmo_soft_uart suart, const ubit_t ubits, size_t n_ubits)
	Feed a number of unpacked bits into the soft-UART receiver. More...

int	osmo_soft_uart_tx_ubits (struct osmo_soft_uart suart, ubit_t ubits, size_t n_ubits)
	Pull a number of unpacked bits out of the soft-UART transmitter. More...

unsigned int	osmo_soft_uart_get_status (const struct osmo_soft_uart *suart)
	Get the modem status bitmask of the given soft-UART. More...

int	osmo_soft_uart_set_status (struct osmo_soft_uart *suart, unsigned int status)
	Set the modem status bitmask of the given soft-UART. More...

void	osmo_soft_uart_set_status_line (struct osmo_soft_uart *suart, enum osmo_soft_uart_status line, bool active)
	Activate/deactivate a modem status line of the given soft-UART. More...

void	osmo_soft_uart_flush_rx (struct osmo_soft_uart *suart)
	Flush the receive buffer, passing ownership of the msgb to the .rx_cb(). More...

Variables
const struct osmo_soft_uart_cfg	osmo_soft_uart_default_cfg
	Default soft-UART configuration (8-N-1) More...

Detailed Description

Software UART implementation.

Enumeration Type Documentation

◆ osmo_soft_uart_flags

enum osmo_soft_uart_flags

Flags passed to the application.

Enumerator
OSMO_SUART_F_FRAMING_ERROR	Framing error occurred.
OSMO_SUART_F_PARITY_ERROR	Parity error occurred.
OSMO_SUART_F_BREAK	Break condition (not implemented)

◆ osmo_soft_uart_flow_ctrl_mode

enum osmo_soft_uart_flow_ctrl_mode

Flow control mode.

https://en.wikipedia.org/wiki/Flow_control_(data)#Hardware_flow_control

Enumerator

OSMO_SUART_FLOW_CTRL_NONE

No flow control.

OSMO_SUART_FLOW_CTRL_DTR_DSR

DTR/DSR flow control: Tx if DSR is active and drop DTR if cannot Rx anymore.

OSMO_SUART_FLOW_CTRL_RTS_CTS

RTS/CTS flow control: Tx if CTS is active and drop RTS if cannot Rx anymore.

The technically correct name would be RTR/CTS, because the RTS signal actually indicates readiness to receive data (Ready To Receive), and not really used to request a transmission (Request To Send) nowadays. Alternatively, the RTS signal can be interpreted as "Request To Send to me".

◆ osmo_soft_uart_parity_mode

enum osmo_soft_uart_parity_mode

Parity mode.

https://en.wikipedia.org/wiki/Parity_bit

Enumerator
OSMO_SUART_PARITY_NONE	No parity bit.
OSMO_SUART_PARITY_EVEN	Even parity.
OSMO_SUART_PARITY_ODD	Odd parity.
OSMO_SUART_PARITY_MARK	Always 1.
OSMO_SUART_PARITY_SPACE	Always 0.
_OSMO_SUART_PARITY_NUM

◆ osmo_soft_uart_status

enum osmo_soft_uart_status

Modem status "line" flags.

https://en.wikipedia.org/wiki/RS-232#Data_and_control_signals

Enumerator
OSMO_SUART_STATUS_F_DTR	Data Terminal Ready.
OSMO_SUART_STATUS_F_DCD	Data Carrier Detect.
OSMO_SUART_STATUS_F_DSR	Data Set Ready.
OSMO_SUART_STATUS_F_RI	Ring Indicator.
OSMO_SUART_STATUS_F_RTS_RTR	Request To Send or Ready To Receive.
OSMO_SUART_STATUS_F_CTS	Clear To Send.

Function Documentation

◆ osmo_soft_uart_alloc()

struct osmo_soft_uart * osmo_soft_uart_alloc	(	void *	ctx,
		const char *	name,
		const struct osmo_soft_uart_cfg *	cfg
	)

Allocate a soft-UART instance.

Parameters

[in]	ctx	parent talloc context.
[in]	name	name of the soft-UART instance.
[in]	cfg	initial configuration of the soft-UART instance.

Returns: pointer to allocated soft-UART instance; NULL on error.

References osmo_soft_uart::cfg, name, osmo_soft_uart::name, and OSMO_ASSERT.

◆ osmo_soft_uart_configure()

int osmo_soft_uart_configure	(	struct osmo_soft_uart *	suart,
		const struct osmo_soft_uart_cfg *	cfg
	)

Change soft-UART configuration to the user-provided config.

Parameters

[in]	suart	soft-UART instance to be re-configured.
[in]	cfg	the user-provided config to be applied.

Returns: 0 on success; negative on error.

References _OSMO_SUART_PARITY_NUM, osmo_soft_uart::cfg, osmo_soft_uart_cfg::num_data_bits, osmo_soft_uart_cfg::num_stop_bits, osmo_soft_uart_flush_rx(), osmo_timer_setup(), osmo_soft_uart_cfg::parity_mode, osmo_soft_uart::rx, osmo_soft_uart_cfg::rx_buf_size, osmo_soft_uart_cfg::rx_timeout_ms, suart_rx_timer_cb(), and osmo_soft_uart::timer.

◆ osmo_soft_uart_flush_rx()

void osmo_soft_uart_flush_rx ( struct osmo_soft_uart * suart )

Flush the receive buffer, passing ownership of the msgb to the .rx_cb().

Parameters

[in] suart soft-UART instance holding the receive buffer.

References osmo_soft_uart::cfg, osmo_soft_uart::flags, osmo_soft_uart::msg, msgb_alloc_c(), msgb_length(), msgb_reset(), osmo_timer_del(), osmo_soft_uart_cfg::priv, osmo_soft_uart::rx, osmo_soft_uart_cfg::rx_buf_size, osmo_soft_uart_cfg::rx_cb, and osmo_soft_uart::timer.

Referenced by osmo_soft_uart_configure(), osmo_soft_uart_set_rx(), suart_rx_ch(), and suart_rx_timer_cb().

◆ osmo_soft_uart_free()

void osmo_soft_uart_free ( struct osmo_soft_uart * suart )

Release memory taken by the given soft-UART.

Parameters

[in] suart soft-UART instance to be free()d.

References osmo_soft_uart::msg, msgb_free(), osmo_soft_uart::name, osmo_timer_del(), osmo_soft_uart::rx, and osmo_soft_uart::timer.

◆ osmo_soft_uart_get_name()

const char * osmo_soft_uart_get_name ( const struct osmo_soft_uart * suart )

Get a name for the given soft-UART instance.

Parameters

[in] suart soft-UART instance to get the name from.

Returns: name of the given soft-UART instance.

References osmo_soft_uart::name.

◆ osmo_soft_uart_get_status()

unsigned int osmo_soft_uart_get_status ( const struct osmo_soft_uart * suart )

Get the modem status bitmask of the given soft-UART.

Parameters

[in] suart soft-UART instance to get the modem status.

Returns: bitmask of OSMO_SUART_STATUS_F_*.

References osmo_soft_uart::status.

◆ osmo_soft_uart_rx_ubits()

int osmo_soft_uart_rx_ubits	(	struct osmo_soft_uart *	suart,
		const ubit_t *	ubits,
		size_t	n_ubits
	)

Feed a number of unpacked bits into the soft-UART receiver.

Parameters

[in]	suart	soft-UART instance to feed bits into.
[in]	ubits	pointer to the unpacked bits.
[in]	n_ubits	number of unpacked bits to be fed.

Returns: 0 on success; negative on error. -EAGAIN indicates that the receiver is disabled.

References osmo_soft_uart::running, osmo_soft_uart::rx, and suart_rx_bit().

◆ osmo_soft_uart_set_name()

void osmo_soft_uart_set_name	(	struct osmo_soft_uart *	suart,
		const char *	name
	)

Set a new name for the given soft-UART instance.

Parameters

[in]	suart	soft-UART instance to set the name for.
[in]	name	the new name.

References name, osmo_soft_uart::name, and osmo_talloc_replace_string().

◆ osmo_soft_uart_set_rx()

int osmo_soft_uart_set_rx	(	struct osmo_soft_uart *	suart,
		bool	enable
	)

Enable/disable receiver of the given soft-UART.

Parameters

[in]	suart	soft-UART instance to be re-configured.
[in]	enable	enable/disable state of the receiver.

Returns: 0 on success; negative on error.

References osmo_soft_uart::cfg, osmo_soft_uart::flow_state, osmo_soft_uart::msg, msgb_alloc_c(), osmo_soft_uart_flush_rx(), osmo_soft_uart::running, osmo_soft_uart::rx, osmo_soft_uart_cfg::rx_buf_size, and SUART_FLOW_ST_IDLE.

◆ osmo_soft_uart_set_status()

int osmo_soft_uart_set_status	(	struct osmo_soft_uart *	suart,
		unsigned int	status
	)

Set the modem status bitmask of the given soft-UART.

Parameters

[in]	suart	soft-UART instance to set the modem status.
[in]	status	bitmask of OSMO_SUART_STATUS_F_*.

Returns: 0 on success; negative on error.

References osmo_soft_uart::cfg, osmo_soft_uart_cfg::priv, osmo_soft_uart::status, and osmo_soft_uart_cfg::status_change_cb.

Referenced by osmo_soft_uart_set_status_line().

◆ osmo_soft_uart_set_status_line()

void osmo_soft_uart_set_status_line	(	struct osmo_soft_uart *	suart,
		enum osmo_soft_uart_status	line,
		bool	active
	)

Activate/deactivate a modem status line of the given soft-UART.

Parameters

[in]	suart	soft-UART instance to update the modem status.
[in]	line	a modem status line, one of OSMO_SUART_STATUS_F_*.
[in]	active	activate (true) or deactivate (false) the line.

References osmo_soft_uart_set_status(), and osmo_soft_uart::status.

◆ osmo_soft_uart_set_tx()

int osmo_soft_uart_set_tx	(	struct osmo_soft_uart *	suart,
		bool	enable
	)

Enable/disable transmitter of the given soft-UART.

Parameters

[in]	suart	soft-UART instance to be re-configured.
[in]	enable	enable/disable state of the transmitter.

Returns: 0 on success; negative on error.

References osmo_soft_uart::flow_state, osmo_soft_uart::running, SUART_FLOW_ST_IDLE, and osmo_soft_uart::tx.

◆ osmo_soft_uart_tx_ubits()

int osmo_soft_uart_tx_ubits	(	struct osmo_soft_uart *	suart,
		ubit_t *	ubits,
		size_t	n_ubits
	)

Pull a number of unpacked bits out of the soft-UART transmitter.

Parameters

[in]	suart	soft-UART instance to pull the bits from.
[out]	ubits	pointer to a buffer where to store pulled bits.
[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.

References osmo_soft_uart::cfg, osmo_soft_uart_cfg::flow_ctrl_mode, osmo_soft_uart::flow_state, msg, msgb_alloc_c(), msgb_free(), osmo_soft_uart_cfg::num_data_bits, osmo_soft_uart_cfg::num_stop_bits, OSMO_ASSERT, OSMO_SUART_FLOW_CTRL_DTR_DSR, OSMO_SUART_FLOW_CTRL_NONE, OSMO_SUART_FLOW_CTRL_RTS_CTS, OSMO_SUART_PARITY_NONE, OSMO_SUART_STATUS_F_CTS, OSMO_SUART_STATUS_F_DSR, OSMO_UNLIKELY, osmo_soft_uart_cfg::parity_mode, osmo_soft_uart_cfg::priv, osmo_soft_uart::running, osmo_soft_uart::status, SUART_FLOW_ST_IDLE, suart_tx_bit(), suart_tx_pending(), osmo_soft_uart::tx, and osmo_soft_uart_cfg::tx_cb.

Variable Documentation

◆ osmo_soft_uart_default_cfg

const struct osmo_soft_uart_cfg osmo_soft_uart_default_cfg

extern

Default soft-UART configuration (8-N-1)

Data Structures

Enumerations

Functions

Variables

Detailed Description

Enumeration Type Documentation

◆ osmo_soft_uart_flags

◆ osmo_soft_uart_flow_ctrl_mode

◆ osmo_soft_uart_parity_mode

◆ osmo_soft_uart_status

Function Documentation

◆ osmo_soft_uart_alloc()

◆ osmo_soft_uart_configure()

◆ osmo_soft_uart_flush_rx()

◆ osmo_soft_uart_free()

◆ osmo_soft_uart_get_name()

◆ osmo_soft_uart_get_status()

◆ osmo_soft_uart_rx_ubits()

◆ osmo_soft_uart_set_name()

◆ osmo_soft_uart_set_rx()

◆ osmo_soft_uart_set_status()

◆ osmo_soft_uart_set_status_line()

◆ osmo_soft_uart_set_tx()

◆ osmo_soft_uart_tx_ubits()

Variable Documentation

◆ osmo_soft_uart_default_cfg