laforge has uploaded this change for review. (
https://gerrit.osmocom.org/c/libosmo-netif/+/36299?usp=email )
Change subject: doc: various osmux API documentation updates
......................................................................
doc: various osmux API documentation updates
Let's make sure
* only exported / user-relevant #defines appear in the manual
* deprecated functions are marked in a way doxygen can mark them
* descriptive comments are using doxygen syntax
Change-Id: I5af0133322ddd5345a13380f1c007474c0bea117
---
M include/osmocom/netif/osmux.h
M src/osmux.c
M src/osmux_input.c
M src/osmux_output.c
4 files changed, 56 insertions(+), 40 deletions(-)
git pull ssh://gerrit.osmocom.org:29418/libosmo-netif refs/changes/99/36299/1
diff --git a/include/osmocom/netif/osmux.h b/include/osmocom/netif/osmux.h
index 609ca3b..b18b71f 100644
--- a/include/osmocom/netif/osmux.h
+++ b/include/osmocom/netif/osmux.h
@@ -15,7 +15,8 @@
#define OSMUX_DEFAULT_PORT 1984
-/* OSmux header:
+/*! \struct osmux_hdr
+ * OSmux header:
*
* rtp_m (1 bit): RTP M field (RFC3550, RFC4867)
* ft (2 bits): 0=signalling, 1=voice, 2=dummy
@@ -32,6 +33,7 @@
#define OSMUX_FT_VOICE_AMR 1
#define OSMUX_FT_DUMMY 2
+/*! Osmux protocol header */
struct osmux_hdr {
#if OSMO_IS_LITTLE_ENDIAN
uint8_t amr_q:1,
@@ -56,9 +58,9 @@
uint8_t data[0];
} __attribute__((packed));
-/* one to handle all existing RTP flows */
+/*! one to handle all existing RTP flows */
struct osmux_in_handle {
- /* Initial Osmux seqnum for each circuit, set during
osmux_xfrm_input_open_circuit() */
+ /*! Initial Osmux seqnum for each circuit, set during
osmux_xfrm_input_open_circuit() */
uint8_t osmux_seq;
uint8_t batch_factor;
uint16_t batch_size;
@@ -79,7 +81,7 @@
typedef struct msgb *(*rtp_msgb_alloc_cb_t)(void *rtp_msgb_alloc_priv_data,
unsigned int msg_len);
-/* one per OSmux circuit_id, ie. one per RTP flow. */
+/*! one per OSmux circuit_id, ie. one per RTP flow. */
struct osmux_out_handle {
uint16_t rtp_seq;
uint32_t rtp_timestamp;
@@ -94,6 +96,7 @@
void *rtp_msgb_alloc_cb_data; /* Opaque data pointer set by user and
passed in rtp_msgb_alloc_cb() */
};
+/*! return pointer to osmux payload (behind osmux_hdr */
static inline uint8_t *osmux_get_payload(struct osmux_hdr *osmuxh)
{
return (uint8_t *)osmuxh + sizeof(struct osmux_hdr);
diff --git a/src/osmux.c b/src/osmux.c
index d3294de..999aedd 100644
--- a/src/osmux.c
+++ b/src/osmux.c
@@ -27,6 +27,14 @@
#include <arpa/inet.h>
+#define SNPRINTF_BUFFER_SIZE(ret, remain, offset) \
+ if (ret < 0) \
+ ret = 0; \
+ offset += ret; \
+ if (ret > remain) \
+ ret = remain; \
+ remain -= ret;
+
/*! \addtogroup osmux Osmocom Multiplex Protocol
* @{
*
@@ -49,14 +57,6 @@
return osmo_amr_bytes(osmuxh->amr_ft) * (osmuxh->ctr+1);
}
-#define SNPRINTF_BUFFER_SIZE(ret, remain, offset) \
- if (ret < 0) \
- ret = 0; \
- offset += ret; \
- if (ret > remain) \
- ret = remain; \
- remain -= ret;
-
static int osmux_snprintf_header(char *buf, size_t size, struct osmux_hdr
*osmuxh)
{
unsigned int remain = size, offset = 0;
diff --git a/src/osmux_input.c b/src/osmux_input.c
index 120f95f..2184a08 100644
--- a/src/osmux_input.c
+++ b/src/osmux_input.c
@@ -28,23 +28,6 @@
#include <arpa/inet.h>
-/*! \addtogroup osmux Osmocom Multiplex Protocol
- * @{
- *
- * This code implements a variety of utility functions related to the
- * OSMUX user-plane multiplexing protocol, an efficient alternative to
- * plain UDP/RTP streams for voice transport in back-haul of cellular
- * networks.
- *
- * For information about the OSMUX protocol design, please see the
- * OSMUX reference manual at
- * http://ftp.osmocom.org/docs/latest/osmux-reference.pdf
- */
-
-/*! \file osmux_input.c
- * \brief Osmocom multiplex protocol helpers (input)
- */
-
/* This allows you to debug osmux message transformations (spamming) */
#if 0
#define DEBUG_MSG 0
@@ -68,6 +51,22 @@
LOGMUXLK_(link, lvl, "[CID=%" PRIu8 ",batched=%u/%u] " fmt, \
(circuit)->ccid, (circuit)->nmsgs, (link)->h->batch_factor,
## args)
+/*! \addtogroup osmux Osmocom Multiplex Protocol
+ * @{
+ *
+ * This code implements a variety of utility functions related to the
+ * OSMUX user-plane multiplexing protocol, an efficient alternative to
+ * plain UDP/RTP streams for voice transport in back-haul of cellular
+ * networks.
+ *
+ * For information about the OSMUX protocol design, please see the
+ * OSMUX reference manual at
+ * http://ftp.osmocom.org/docs/latest/osmux-reference.pdf
+ */
+
+/*! \file osmux_input.c
+ * \brief Osmocom multiplex protocol helpers (input)
+ */
static void *osmux_ctx;
@@ -698,6 +697,7 @@
return 0;
}
+static unsigned int next_default_name_idx = 0;
/*! \brief Allocate a new osmux in handle (osmux source, tx side)
* \param[in] ctx talloc context to use when allocating the returned struct
* \return Allocated osmux in handle
@@ -708,7 +708,6 @@
* stack outgoing network Osmux messages.
* Returned pointer can be freed with regular talloc_free, all pending messages
* in queue and all internal data will be freed. */
-static unsigned int next_default_name_idx = 0;
struct osmux_in_handle *osmux_xfrm_input_alloc(void *ctx)
{
struct osmux_in_handle *h;
@@ -735,7 +734,7 @@
return h;
}
-/* DEPRECATED: Use osmux_xfrm_input_alloc() instead */
+/*! \deprecated: Use osmux_xfrm_input_alloc() instead */
void osmux_xfrm_input_init(struct osmux_in_handle *h)
{
struct osmux_link *link;
@@ -849,7 +848,7 @@
osmux_link_del_circuit(link, circuit);
}
-/* DEPRECATED: Use talloc_free() instead (will call
osmux_xfrm_input_talloc_destructor()) */
+/*! \deprecated: Use talloc_free() instead (will call
osmux_xfrm_input_talloc_destructor()) */
void osmux_xfrm_input_fini(struct osmux_in_handle *h)
{
(void)osmux_xfrm_input_talloc_destructor(h);
diff --git a/src/osmux_output.c b/src/osmux_output.c
index f48e1c9..664ed60 100644
--- a/src/osmux_output.c
+++ b/src/osmux_output.c
@@ -27,6 +27,12 @@
#include <arpa/inet.h>
+/* delta time between two RTP messages (in microseconds) */
+#define DELTA_RTP_MSG 20000
+/* delta time between two RTP messages (in samples, 8kHz) */
+#define DELTA_RTP_TIMESTAMP 160
+
+
/*! \addtogroup osmux Osmocom Multiplex Protocol
* @{
*
@@ -43,12 +49,6 @@
/*! \file osmux_output.c
* \brief Osmocom multiplex protocol helpers (output)
*/
-
-/* delta time between two RTP messages (in microseconds) */
-#define DELTA_RTP_MSG 20000
-/* delta time between two RTP messages (in samples, 8kHz) */
-#define DELTA_RTP_TIMESTAMP 160
-
static uint32_t osmux_ft_dummy_size(uint8_t amr_ft, uint8_t batch_factor)
{
return sizeof(struct osmux_hdr) + (osmo_amr_bytes(amr_ft) *
batch_factor);
@@ -330,14 +330,14 @@
return h;
}
-/* DEPRECATED: Use osmux_xfrm_output_alloc() and osmux_xfrm_output_set_rtp_*()
instead */
+/*! \deprecated: Use osmux_xfrm_output_alloc() and
osmux_xfrm_output_set_rtp_*() instead */
void osmux_xfrm_output_init2(struct osmux_out_handle *h, uint32_t rtp_ssrc,
uint8_t rtp_payload_type)
{
memset(h, 0, sizeof(*h));
_osmux_xfrm_output_init(h, rtp_ssrc, rtp_payload_type);
}
-/* DEPRECATED: Use osmux_xfrm_output_alloc() and osmux_xfrm_output_set_rtp_*()
instead */
+/*! \deprecated: Use osmux_xfrm_output_alloc() and
osmux_xfrm_output_set_rtp_*() instead */
void osmux_xfrm_output_init(struct osmux_out_handle *h, uint32_t rtp_ssrc)
{
/* backward compatibility with old users, where 98 was harcoded in
osmux_rebuild_rtp() */
--
To view, visit https://gerrit.osmocom.org/c/libosmo-netif/+/36299?usp=email
To unsubscribe, or for help writing mail filters, visit
https://gerrit.osmocom.org/settings
Gerrit-Project: libosmo-netif
Gerrit-Branch: master
Gerrit-Change-Id: I5af0133322ddd5345a13380f1c007474c0bea117
Gerrit-Change-Number: 36299
Gerrit-PatchSet: 1
Gerrit-Owner: laforge <lafo...@osmocom.org>
Gerrit-MessageType: newchange
