Loading...
Searching...
No Matches
soft_uart.h File Reference

Software UART implementation. More...

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

Go to the source code of this file.

## 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.
void | osmo_soft_uart_free (struct osmo_soft_uart *suart)
| Release memory taken by the given soft-UART.
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.
const char * | osmo_soft_uart_get_name (const struct osmo_soft_uart *suart)
| Get a name for the given soft-UART instance.
void | osmo_soft_uart_set_name (struct osmo_soft_uart *suart, const char *name)
| Set a new name for the given soft-UART instance.
int | osmo_soft_uart_set_rx (struct osmo_soft_uart *suart, bool enable)
| Enable/disable receiver of the given soft-UART.
int | osmo_soft_uart_set_tx (struct osmo_soft_uart *suart, bool enable)
| Enable/disable transmitter of the given soft-UART.
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.
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.
unsigned int | osmo_soft_uart_get_status (const struct osmo_soft_uart *suart)
| Get the modem status bitmask of the given soft-UART.
int | osmo_soft_uart_set_status (struct osmo_soft_uart *suart, unsigned int status)
| Set the modem status bitmask of the given soft-UART.
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.
void | osmo_soft_uart_flush_rx (struct osmo_soft_uart *suart)
| Flush the receive buffer, passing ownership of the msgb to the .rx_cb().

## Variables

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

## 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, 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).