summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorHarald Welte <laforge@gnumonks.org>2017-05-02 21:24:48 +0200
committerHarald Welte <laforge@gnumonks.org>2017-05-17 15:15:09 +0100
commitea3d3ba595458024cfd4b55f6c8fcf510b234a32 (patch)
treefc31ee0d37a4ad50fa13095a5e1297739c9fd4bb
parent1a97e2c962a640e8e13eef50a8509788be349138 (diff)
sercomm: Add doxygen-style documentation to public API
Change-Id: I2d8b11905692920d328262836420f01305be489e
-rw-r--r--include/osmocom/core/sercomm.h29
-rw-r--r--src/sercomm.c16
2 files changed, 32 insertions, 13 deletions
diff --git a/include/osmocom/core/sercomm.h b/include/osmocom/core/sercomm.h
index d84786e1..3d986c60 100644
--- a/include/osmocom/core/sercomm.h
+++ b/include/osmocom/core/sercomm.h
@@ -22,27 +22,44 @@ enum sercomm_dlci {
};
struct osmo_sercomm_inst;
+/*! \brief call-back function for per-DLC receive handler
+ * \param[in] sercomm instance on which msg was received
+ * \param[in] dlci DLC Identifier of received msg
+ * \param[in] msg received message that needs to be processed */
typedef void (*dlci_cb_t)(struct osmo_sercomm_inst *sercomm, uint8_t dlci, struct msgb *msg);
+/*! \brief one instance of a sercomm multiplex/demultiplex */
struct osmo_sercomm_inst {
+ /*! \brief Has this instance been initialized? */
int initialized;
+ /*! \brief UART Identifier */
int uart_id;
- /* transmit side */
+ /*! \brief transmit side */
struct {
+ /*! \brief per-DLC queue of pending transmit msgbs */
struct llist_head dlci_queues[_SC_DLCI_MAX];
+ /*! \brief msgb currently being transmitted */
struct msgb *msg;
+ /*! \brief transmit state */
int state;
+ /*! \brief next to-be-transmitted char in msg */
uint8_t *next_char;
} tx;
- /* receive side */
+ /*! \brief receive side */
struct {
+ /*! \brief per-DLC handler call-back functions */
dlci_cb_t dlci_handler[_SC_DLCI_MAX];
+ /*! \brief msgb allocation size for rx msgs */
unsigned int msg_size;
+ /*! \brief currently received msgb */
struct msgb *msg;
+ /*! \brief receive state */
int state;
+ /*! \brief DLCI of currently received msgb */
uint8_t dlci;
+ /*! \brief CTRL of currently received msgb */
uint8_t ctrl;
} rx;
};
@@ -60,23 +77,15 @@ void osmo_sercomm_init(struct osmo_sercomm_inst *sercomm);
int osmo_sercomm_initialized(struct osmo_sercomm_inst *sercomm);
/* User Interface: Tx */
-
-/* user interface for transmitting messages for a given DLCI */
void osmo_sercomm_sendmsg(struct osmo_sercomm_inst *sercomm, uint8_t dlci, struct msgb *msg);
-/* how deep is the Tx queue for a given DLCI */
unsigned int osmo_sercomm_tx_queue_depth(struct osmo_sercomm_inst *sercomm, uint8_t dlci);
/* User Interface: Rx */
-
-/* receiving messages for a given DLCI */
int osmo_sercomm_register_rx_cb(struct osmo_sercomm_inst *sercomm, uint8_t dlci, dlci_cb_t cb);
/* Driver Interface */
-/* fetch one octet of to-be-transmitted serial data. returns 0 if no more data */
int osmo_sercomm_drv_pull(struct osmo_sercomm_inst *sercomm, uint8_t *ch);
-/* the driver has received one byte, pass it into sercomm layer.
- returns 1 in case of success, 0 in case of unrecognized char */
int osmo_sercomm_drv_rx_char(struct osmo_sercomm_inst *sercomm, uint8_t ch);
static inline struct msgb *osmo_sercomm_alloc_msgb(unsigned int len)
diff --git a/src/sercomm.c b/src/sercomm.c
index 111565f2..dbe3d057 100644
--- a/src/sercomm.c
+++ b/src/sercomm.c
@@ -168,7 +168,10 @@ void osmo_sercomm_change_speed(struct osmo_sercomm_inst *sercomm, enum uart_baud
}
#endif
-/* fetch one octet of to-be-transmitted serial data */
+/*! \brief fetch one octet of to-be-transmitted serial data
+ * \param[in] sercomm Sercomm Instance from which to fetch pending data
+ * \param[out] ch pointer to caller-allocaed output memory
+ * \returns 1 in case of succss; 0 if no data available; negative on error */
int osmo_sercomm_drv_pull(struct osmo_sercomm_inst *sercomm, uint8_t *ch)
{
unsigned long flags;
@@ -230,7 +233,11 @@ int osmo_sercomm_drv_pull(struct osmo_sercomm_inst *sercomm, uint8_t *ch)
return 1;
}
-/* register a handler for a given DLCI */
+/*! \brief Register a handler for a given DLCI
+ * \param sercomm Sercomm Instance in which caller wishes to register
+ * \param[in] dlci Data Ling Connection Identifier to register
+ * \param[in] cb Callback function for \a dlci
+ * \returns 0 on success; negative on error */
int osmo_sercomm_register_rx_cb(struct osmo_sercomm_inst *sercomm, uint8_t dlci, dlci_cb_t cb)
{
if (dlci >= ARRAY_SIZE(sercomm->rx.dlci_handler))
@@ -254,7 +261,10 @@ static void dispatch_rx_msg(struct osmo_sercomm_inst *sercomm, uint8_t dlci, str
sercomm->rx.dlci_handler[dlci](sercomm, dlci, msg);
}
-/* the driver has received one byte, pass it into sercomm layer */
+/*! \brief the driver has received one byte, pass it into sercomm layer
+ * \param[in] sercomm Sercomm Instance for which a byte was received
+ * \param[in] ch byte that was received from line for said instance
+ * \returns 1 on success; 0 on unrecognized char; negative on error */
int osmo_sercomm_drv_rx_char(struct osmo_sercomm_inst *sercomm, uint8_t ch)
{
uint8_t *ptr;