[M] Change in libosmo-netif[master]: docs: various osmux API documentation updates

laforge has submitted this change. ( https://gerrit.osmocom.org/c/libosmo-netif/+/36299?usp=email ) Change subject: docs: various osmux API documentation updates ...................................................................... docs: 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(-) Approvals: laforge: Looks good to me, approved; Verified diff --git a/include/osmocom/netif/osmux.h b/include/osmocom/netif/osmux.h index 609ca3b..8a8bf88 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: 4 Gerrit-Owner: laforge &lt;laforge(a)osmocom.org&gt; Gerrit-Reviewer: fixeria &lt;vyanitskiy(a)sysmocom.de&gt; Gerrit-Reviewer: laforge &lt;laforge(a)osmocom.org&gt; Gerrit-Reviewer: pespin &lt;pespin(a)sysmocom.de&gt; Gerrit-MessageType: merged