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.orgHarald Welte has submitted this change and it was merged.
Change subject: sercomm: More API documentation
......................................................................
sercomm: More API documentation
Change-Id: I5d5002ceedd10e10d772693478f4f9cab6b1290a
---
M include/osmocom/core/sercomm.h
M src/sercomm.c
2 files changed, 62 insertions(+), 5 deletions(-)
Approvals:
Harald Welte: Looks good to me, approved
Jenkins Builder: Verified
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: merged
Gerrit-Change-Id: I5d5002ceedd10e10d772693478f4f9cab6b1290a
Gerrit-PatchSet: 3
Gerrit-Project: libosmocore
Gerrit-Branch: master
Gerrit-Owner: Harald Welte <laforge at gnumonks.org>
Gerrit-Reviewer: Harald Welte <laforge at gnumonks.org>
Gerrit-Reviewer: Jenkins Builder