osmocom
/
libosmocore
mirror of https://gerrit.osmocom.org/libosmocore
11
0
Fork 1
Code Issues Releases Wiki Activity

soft_uart: improve doxygen documentation 

Change-Id: I415a5e5392a7f91da4bf117d59694278779acc94
Related: OS#4396
This commit is contained in:
Vadim Yanitskiy 2023-12-04 01:44:09 +07:00
parent 2203db5b9a
commit 275c86e7ee
1 changed files with 45 additions and 24 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

69
include/osmocom/core/soft_uart.h
View File

@ -25,19 +25,22 @@
#include <osmocom/core/bits.h> #include <osmocom/core/bits.h>
#include <osmocom/core/msgb.h> #include <osmocom/core/msgb.h>
/*! Parity mode.
* https://en.wikipedia.org/wiki/Parity_bit */
enum osmo_soft_uart_parity_mode { enum osmo_soft_uart_parity_mode {
OSMO_SUART_PARITY_NONE, OSMO_SUART_PARITY_NONE, /*!< No parity bit */
OSMO_SUART_PARITY_EVEN, OSMO_SUART_PARITY_EVEN, /*!< Even parity */
OSMO_SUART_PARITY_ODD, OSMO_SUART_PARITY_ODD, /*!< Odd parity */
OSMO_SUART_PARITY_MARK, /* always 1 */ OSMO_SUART_PARITY_MARK, /*!< Always 1 */
OSMO_SUART_PARITY_SPACE, /* always 0 */ OSMO_SUART_PARITY_SPACE, /*!< Always 0 */
_OSMO_SUART_PARITY_NUM _OSMO_SUART_PARITY_NUM
}; };
/*! Flags passed to the application. */
enum osmo_soft_uart_flags { enum osmo_soft_uart_flags {
OSMO_SUART_F_FRAMING_ERROR = (1 << 0), OSMO_SUART_F_FRAMING_ERROR = (1 << 0), /*!< Framing error occurred */
OSMO_SUART_F_PARITY_ERROR = (1 << 1), OSMO_SUART_F_PARITY_ERROR = (1 << 1), /*!< Parity error occurred */
OSMO_SUART_F_BREAK = (1 << 2), OSMO_SUART_F_BREAK = (1 << 2), /*!< Break condition (not implemented) */
}; };
#if 0 #if 0
@ -47,35 +50,53 @@ enum osmo_soft_uart_status {
}; };
#endif #endif
/* configuration for a soft-uart */ /*! Configuration for a soft-UART. */
struct osmo_soft_uart_cfg { struct osmo_soft_uart_cfg {
/*! number of data bits (typically 5, 6, 7 or 8) */ /*! Number of data bits (typically 5, 6, 7 or 8). */
uint8_t num_data_bits; uint8_t num_data_bits;
/*! number of stop bits (typically 1 or 2) */ /*! Number of stop bits (typically 1 or 2). */
uint8_t num_stop_bits; uint8_t num_stop_bits;
/*! parity mode (none, even, odd) */ /*! Parity mode (none, even, odd, space, mark). */
enum osmo_soft_uart_parity_mode parity_mode; enum osmo_soft_uart_parity_mode parity_mode;
/*! size of receive buffer; UART will buffer up to that number of characters /*! Size of the receive buffer; UART will buffer up to that number
* before calling the receive call-back */ * of characters before calling the receive call-back. */
unsigned int rx_buf_size; unsigned int rx_buf_size;
/*! receive timeout; UART will flush receive buffer via the receive call-back /*! Receive timeout; UART will flush the receive buffer via the receive call-back
* after indicated number of milliseconds even if it is not full yet */ * after indicated number of milliseconds, even if it is not full yet. */
unsigned int rx_timeout_ms; unsigned int rx_timeout_ms;
/*! opaque application-private data; passed to call-backs */ /*! Opaque application-private data; passed to call-backs. */
void *priv; void *priv;
/*! receive call-back. Either rx_buf_size characters were received or rx_timeout_ms /*! Receive call-back of the application.
* expired, or an error flag was detected (related to last byte received). *
* 'flags' is a bit-mask of osmo_soft_uart_flags, */ * Called if at least one of the following conditions is met:
* a) rx_buf_size characters were received (Rx buffer is full);
* b) rx_timeout_ms expired and Rx buffer is not empty;
* c) a parity or framing error is occurred.
*
* \param[in] priv opaque application-private data.
* \param[in] rx_data msgb holding the received data.
* Must be free()ed by the application.
* \param[in] flags bit-mask of OSMO_SUART_F_*. */
void (*rx_cb)(void *priv, struct msgb *rx_data, unsigned int flags); void (*rx_cb)(void *priv, struct msgb *rx_data, unsigned int flags);
/*! transmit call-back. The implementation is expected to provide at most /*! Transmit call-back of the application.
* tx_data->data_len characters (the actual amount is determined by the *
* number of requested bits and the effective UART configuration). */ * The implementation is expected to provide at most tx_data->data_len
* characters (the actual amount is determined by the number of requested
* bits and the effective UART configuration).
*
* \param[in] priv opaque application-private data.
* \param[inout] tx_data msgb for writing to be transmitted data. */
void (*tx_cb)(void *priv, struct msgb *tx_data); void (*tx_cb)(void *priv, struct msgb *tx_data);
/*! modem status line change call-back. gets bitmask of osmo_soft_uart_status */ /*! Modem status line change call-back.
*
* FIXME: flow control is not implemented, so it's never called.
*
* \param[in] priv opaque application-private data.
* \param[in] status bit-mask of osmo_soft_uart_status. */
void (*status_change_cb)(void *priv, unsigned int status); void (*status_change_cb)(void *priv, unsigned int status);
}; };