aboutsummaryrefslogtreecommitdiffstats
path: root/src/sercomm.c
diff options
context:
space:
mode:
authorHarald Welte <laforge@gnumonks.org>2017-05-15 17:33:02 +0200
committerHarald Welte <laforge@gnumonks.org>2017-05-17 15:15:09 +0100
commit7711713b7a30dab16bcba3920433f3fa58f89149 (patch)
tree35f79fc85cb891bb45ce66cf6c16b80506d84b3f /src/sercomm.c
parent799bef5cf614c303df1f88c1a7c4cc46a02e8c34 (diff)
sercomm: More API documentation
Diffstat (limited to 'src/sercomm.c')
-rw-r--r--src/sercomm.c39
1 files changed, 35 insertions, 4 deletions
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;
}
+
+/*! @} */