From 47379ca95bd926759d34abcdd1b4b0465fd448c0 Mon Sep 17 00:00:00 2001 From: Harald Welte Date: Wed, 17 Aug 2011 16:35:24 +0200 Subject: [PATCH] doxygen: Add documentation for gsmtap_util.[ch] --- include/osmocom/core/gsmtap_util.h | 25 ++++++------- src/gsmtap_util.c | 57 ++++++++++++++++++++++++++---- 2 files changed, 61 insertions(+), 21 deletions(-) diff --git a/include/osmocom/core/gsmtap_util.h b/include/osmocom/core/gsmtap_util.h index f553c17a8..36cbf5321 100644 --- a/include/osmocom/core/gsmtap_util.h +++ b/include/osmocom/core/gsmtap_util.h @@ -5,46 +5,41 @@ #include #include -/* convert RSL channel number to GSMTAP channel type */ +/*! \defgroup gsmtap GSMTAP + * @{ + */ +/*! \file gsmtap_util.h */ + uint8_t chantype_rsl2gsmtap(uint8_t rsl_chantype, uint8_t rsl_link_id); -/* generate msgb from data + metadata */ struct msgb *gsmtap_makemsg(uint16_t arfcn, uint8_t ts, uint8_t chan_type, uint8_t ss, uint32_t fn, int8_t signal_dbm, uint8_t snr, const uint8_t *data, unsigned int len); -/* one gsmtap instance */ +/*! \brief one gsmtap instance */ struct gsmtap_inst { - int ofd_wq_mode; - struct osmo_wqueue wq; - struct osmo_fd sink_ofd; + int ofd_wq_mode; /*!< \brief wait queue mode? */ + struct osmo_wqueue wq; /*!< \brief the wait queue */ + struct osmo_fd sink_ofd;/*!< \brief file descriptor */ }; +/*! \brief obtain the file descriptor associated with a gsmtap instance */ static inline int gsmtap_inst_fd(struct gsmtap_inst *gti) { return gti->wq.bfd.fd; } -/* Open a GSMTAP source (sending) socket, conncet it to host/port and - * return resulting fd */ int gsmtap_source_init_fd(const char *host, uint16_t port); -/* Add a local sink to an existing GSMTAP source and return fd */ int gsmtap_source_add_sink_fd(int gsmtap_fd); -/* Open GSMTAP source (sending) socket, connect it to host/port, - * allocate 'struct gsmtap_inst' and optionally osmo_fd/osmo_wqueue - * registration */ struct gsmtap_inst *gsmtap_source_init(const char *host, uint16_t port, int ofd_wq_mode); -/* Add a local sink to an existing GSMTAP source instance */ int gsmtap_source_add_sink(struct gsmtap_inst *gti); -/* Send a msgb through a GSMTAP source */ int gsmtap_sendmsg(struct gsmtap_inst *gti, struct msgb *msg); -/* generate a message and send it via GSMTAP */ int gsmtap_send(struct gsmtap_inst *gti, uint16_t arfcn, uint8_t ts, uint8_t chan_type, uint8_t ss, uint32_t fn, int8_t signal_dbm, uint8_t snr, const uint8_t *data, diff --git a/src/gsmtap_util.c b/src/gsmtap_util.c index c8c26c622..0e4d61e55 100644 --- a/src/gsmtap_util.c +++ b/src/gsmtap_util.c @@ -42,6 +42,17 @@ #include #include +/*! \addtogroup gsmtap + * @{ + */ +/*! \file gsmtap_util.c */ + + +/*! \brief convert RSL channel number to GSMTAP channel type + * \param[in] rsl_cantype RSL channel type + * \param[in] link_id RSL link identifier + * \returns GSMTAP channel type + */ uint8_t chantype_rsl2gsmtap(uint8_t rsl_chantype, uint8_t link_id) { uint8_t ret = GSMTAP_CHANNEL_UNKNOWN; @@ -77,7 +88,20 @@ uint8_t chantype_rsl2gsmtap(uint8_t rsl_chantype, uint8_t link_id) return ret; } -/* receive a message from L1/L2 and put it in GSMTAP */ +/*! \brief create L1/L2 data and put it into GSMTAP + * \param[in] arfcn GSM ARFCN (Channel Number) + * \param[in] ts GSM time slot + * \param[in] chan_type Channel Type + * \param[in] ss Sub-slot + * \param[in] fn GSM Frame Number + * \param[in] signal_dbm Signal Strength (dBm) + * \param[in] snr Signal/Noise Ratio (SNR) + * \param[in] data Pointer to data buffer + * \param[in] len Length of \ref data + * + * This function will allocate a new msgb and fill it with a GSMTAP + * header containing the information + */ struct msgb *gsmtap_makemsg(uint16_t arfcn, uint8_t ts, uint8_t chan_type, uint8_t ss, uint32_t fn, int8_t signal_dbm, uint8_t snr, const uint8_t *data, unsigned int len) @@ -115,8 +139,15 @@ struct msgb *gsmtap_makemsg(uint16_t arfcn, uint8_t ts, uint8_t chan_type, #include #include -/* Open a GSMTAP source (sending) socket, conncet it to host/port and - * return resulting fd */ +/*! \brief Create a new (sending) GSMTAP source socket + * \param[in] host host name or IP address in string format + * \param[in] port UDP port number in host byte order + * + * Opens a GSMTAP source (sending) socket, conncet it to host/port and + * return resulting fd. If \a host is NULL, the destination address + * will be localhost. If \a port is 0, the default \ref + * GSMTAP_UDP_PORT will be used. + * */ int gsmtap_source_init_fd(const char *host, uint16_t port) { if (port == 0) @@ -128,6 +159,7 @@ int gsmtap_source_init_fd(const char *host, uint16_t port) OSMO_SOCK_F_CONNECT); } +/*! \brief Add a local sink to an existing GSMTAP source and return fd */ int gsmtap_source_add_sink_fd(int gsmtap_fd) { struct sockaddr_storage ss; @@ -148,6 +180,10 @@ int gsmtap_source_add_sink_fd(int gsmtap_fd) return -ENODEV; } +/*! \brief Send a \ref msgb through a GSMTAP source + * \param[in] gti GSMTAP instance + * \param[in] msgb message buffer + */ int gsmtap_sendmsg(struct gsmtap_inst *gti, struct msgb *msg) { if (!gti) @@ -172,7 +208,7 @@ int gsmtap_sendmsg(struct gsmtap_inst *gti, struct msgb *msg) } } -/* receive a message from L1/L2 and put it in GSMTAP */ +/*! \brief receive a message from L1/L2 and put it in GSMTAP */ int gsmtap_send(struct gsmtap_inst *gti, uint16_t arfcn, uint8_t ts, uint8_t chan_type, uint8_t ss, uint32_t fn, int8_t signal_dbm, uint8_t snr, const uint8_t *data, @@ -228,7 +264,7 @@ static int gsmtap_sink_fd_cb(struct osmo_fd *fd, unsigned int flags) return 0; } -/* Add a local sink to an existing GSMTAP source instance */ +/*! \brief Add a local sink to an existing GSMTAP source instance */ int gsmtap_source_add_sink(struct gsmtap_inst *gti) { int fd; @@ -251,7 +287,16 @@ int gsmtap_source_add_sink(struct gsmtap_inst *gti) return fd; } -/* like gsmtap_init2() but integrated with libosmocore select.c */ + +/*! \brief Open GSMTAP source socket, connect and register osmo_fd + * \param[in] host host name or IP address in string format + * \param[in] port UDP port number in host byte order + * \param[in] osmo_wq_mode Register \ref osmo_wqueue (1) or not (0) + * + * Open GSMTAP source (sending) socket, connect it to host/port, + * allocate 'struct gsmtap_inst' and optionally osmo_fd/osmo_wqueue + * registration. This means it is like \ref gsmtap_init2 but integrated + * with libosmocore \ref select */ struct gsmtap_inst *gsmtap_source_init(const char *host, uint16_t port, int ofd_wq_mode) {