mirror of https://gerrit.osmocom.org/libosmocore
sercomm: More API documentation
Change-Id: I5d5002ceedd10e10d772693478f4f9cab6b1290a
This commit is contained in:
parent
799bef5cf6
commit
7711713b7a
|
@ -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…
Reference in New Issue