sercomm: More API documentation

Change-Id: I5d5002ceedd10e10d772693478f4f9cab6b1290a
changes/46/2646/3
Harald Welte 6 years ago
parent 799bef5cf6
commit 7711713b7a
  1. 28
      include/osmocom/core/sercomm.h
  2. 39
      src/sercomm.c

@ -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 */

@ -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;
}
/*! @} */

Loading…
Cancel
Save