diff options
| -rw-r--r-- | include/osmocom/core/sercomm.h | 28 | ||||
| -rw-r--r-- | src/sercomm.c | 39 |
2 files changed, 62 insertions, 5 deletions
diff --git a/include/osmocom/core/sercomm.h b/include/osmocom/core/sercomm.h index e2630806..5ad1d73c 100644 --- a/include/osmocom/core/sercomm.h +++ b/include/osmocom/core/sercomm.h @@ -3,7 +3,15 @@ #include <osmocom/core/msgb.h> -/* a low sercomm_dlci means high priority. A high DLCI means low priority */ +/*! \defgroup sercomm Seriall Communications (HDLC) + * @{ + */ + +/*! \file sercomm.h + * \brief Osmocom Sercomm HDLC (de)multiplex + */ + +/*! \brief A low sercomm_dlci means high priority. A high DLCI means low priority */ enum sercomm_dlci { SC_DLCI_HIGHEST = 0, SC_DLCI_DEBUG = 4, @@ -77,12 +85,30 @@ int osmo_sercomm_drv_rx_char(struct osmo_sercomm_inst *sercomm, uint8_t ch); extern void sercomm_drv_lock(unsigned long *flags); extern void sercomm_drv_unlock(unsigned long *flags); + +/*! \brief low-level driver routine to request start of transmission + * The Sercomm code calls this function to inform the low-level driver + * that some data is pending for transmission, and the low-level driver + * should (if not active already) start enabling tx_empty interrupts + * and pull drivers out of sercomm using osmo_sercomm_drv_pull() until + * the latter returns 0. + * \param[in] sercomm Osmocom sercomm instance for which to change + */ extern void sercomm_drv_start_tx(struct osmo_sercomm_inst *sercomm); + +/*! \brief low-level driver routine to execute baud-rate change + * \param[in] sercomm Osmocom sercomm instance for which to change + * \param[in] bdrt New Baud-Rate (integer) + * \returns 0 on success; negative in case of error + */ extern int sercomm_drv_baudrate_chg(struct osmo_sercomm_inst *sercomm, uint32_t bdrt); +/*! \brief Sercomm msgb allocator function */ static inline struct msgb *osmo_sercomm_alloc_msgb(unsigned int len) { return msgb_alloc_headroom(len+4, 4, "sercomm_tx"); } +/*! @} */ + #endif /* _SERCOMM_H */ diff --git a/src/sercomm.c b/src/sercomm.c index 409efba3..2f693ef4 100644 --- a/src/sercomm.c +++ b/src/sercomm.c @@ -20,6 +20,13 @@ * */ +/*! \addtogroup sercomm + * @{ + */ + +/*! \file sercomm.c + */ + #include "config.h" #include <stdint.h> @@ -33,7 +40,9 @@ #ifndef EMBEDDED # define DEFAULT_RX_MSG_SIZE 2048 +/*! \brief Protect against IRQ context */ void sercomm_drv_lock(unsigned long __attribute__((unused)) *flags) {} +/*! \brief Release protection against IRQ context */ void sercomm_drv_unlock(unsigned long __attribute__((unused)) *flags) {} #else # define DEFAULT_RX_MSG_SIZE 256 @@ -61,6 +70,12 @@ enum rx_state { RX_ST_ESCAPE, }; +/*! \brief Initialize an Osmocom sercomm instance + * \param sercomm Caller-allocated sercomm instance to be initialized + * + * This function initializes the sercomm instance, including the + * registration of the ECHO service at the ECHO DLCI + */ void osmo_sercomm_init(struct osmo_sercomm_inst *sercomm) { unsigned int i; @@ -76,12 +91,19 @@ void osmo_sercomm_init(struct osmo_sercomm_inst *sercomm) osmo_sercomm_register_rx_cb(sercomm, SC_DLCI_ECHO, &osmo_sercomm_sendmsg); } +/*! \brief Determine if a given Osmocom sercomm instance has been initialized + * \param[in] sercomm Osmocom sercomm instance to be checked + * \returns 1 in case \a sercomm was previously initialized; 0 otherwise */ int osmo_sercomm_initialized(struct osmo_sercomm_inst *sercomm) { return sercomm->initialized; } -/* user interface for transmitting messages for a given DLCI */ +/*! \brief User interface for transmitting messages for a given DLCI + * \param[in] sercomm Osmocom sercomm instance through which to transmit + * \param[in] dlci DLCI through whcih to transmit \a msg + * \param[in] msg Message buffer to be transmitted via \a dlci on \a * sercomm + **/ void osmo_sercomm_sendmsg(struct osmo_sercomm_inst *sercomm, uint8_t dlci, struct msgb *msg) { unsigned long flags; @@ -102,7 +124,10 @@ void osmo_sercomm_sendmsg(struct osmo_sercomm_inst *sercomm, uint8_t dlci, struc sercomm_drv_start_tx(sercomm); } -/* how deep is the Tx queue for a given DLCI */ +/*! \brief How deep is the Tx queue for a given DLCI? + * \param[n] sercomm Osmocom sercomm instance on which to operate + * \param[in] dlci DLCI whose queue depthy is to be determined + * \returns number of elements in the per-DLCI transmit queue */ unsigned int osmo_sercomm_tx_queue_depth(struct osmo_sercomm_inst *sercomm, uint8_t dlci) { struct llist_head *le; @@ -115,8 +140,12 @@ unsigned int osmo_sercomm_tx_queue_depth(struct osmo_sercomm_inst *sercomm, uint return num; } -/* wait until everything has been transmitted, then grab the lock and - * change the baud rate as requested */ +/*! \brief wait until everything has been transmitted, then grab the lock and + * change the baud rate as requested + * \param[in] sercomm Osmocom sercomm instance + * \param[in] bdrt New UART Baud Rate + * \returns result of the operation as provided by sercomm_drv_baudrate_chg() + */ int osmo_sercomm_change_speed(struct osmo_sercomm_inst *sercomm, uint32_t bdrt) { unsigned int i, count; @@ -309,3 +338,5 @@ int osmo_sercomm_drv_rx_char(struct osmo_sercomm_inst *sercomm, uint8_t ch) return 1; } + +/*! @} */ |