This is merely a historical archive of years 2008-2021, before the migration to mailman3.
A maintained and still updated list archive can be found at https://lists.osmocom.org/hyperkitty/list/gerrit-log@lists.osmocom.org/.
Harald Welte gerrit-no-reply at lists.osmocom.orgReview at https://gerrit.osmocom.org/2646 sercomm: More API documentation Change-Id: I5d5002ceedd10e10d772693478f4f9cab6b1290a --- M include/osmocom/core/sercomm.h M src/sercomm.c 2 files changed, 62 insertions(+), 5 deletions(-) git pull ssh://gerrit.osmocom.org:29418/libosmocore refs/changes/46/2646/1 diff --git a/include/osmocom/core/sercomm.h b/include/osmocom/core/sercomm.h index e263080..5ad1d73 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 @@ 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 409efba..2f693ef 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 @@ 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 @@ 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 @@ 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 @@ 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 @@ return 1; } + +/*! @} */ -- To view, visit https://gerrit.osmocom.org/2646 To unsubscribe, visit https://gerrit.osmocom.org/settings Gerrit-MessageType: newchange Gerrit-Change-Id: I5d5002ceedd10e10d772693478f4f9cab6b1290a Gerrit-PatchSet: 1 Gerrit-Project: libosmocore Gerrit-Branch: master Gerrit-Owner: Harald Welte <laforge at gnumonks.org>