osmocom
/
libosmo-netif
mirror of https://gerrit.osmocom.org/libosmo-netif
11
0
Fork 0
Code Issues Releases Wiki Activity

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
This commit is contained in:
Harald Welte 2024-03-15 14:06:11 +01:00
parent 34a657d1e1
commit 2136d599af
4 changed files with 42 additions and 40 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

11
include/osmocom/netif/osmux.h
View File

@ -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 @@ struct osmux_hdr {
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 @@ struct osmux_in_handle {
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 @@ struct osmux_out_handle {
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);

16
src/osmux.c
View File

@ -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 @@ static uint32_t osmux_get_payload_len(struct osmux_hdr *osmuxh)
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;

39
src/osmux_input.c
View File

@ -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 @@ static int osmux_xfrm_input_talloc_destructor(struct osmux_in_handle *h)
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 @@ static int osmux_xfrm_input_talloc_destructor(struct osmux_in_handle *h)
* 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 @@ struct osmux_in_handle *osmux_xfrm_input_alloc(void *ctx)
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 @@ void osmux_xfrm_input_close_circuit(struct osmux_in_handle *h, int ccid)
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);

16
src/osmux_output.c
View File

@ -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 @@ struct osmux_out_handle *osmux_xfrm_output_alloc(void *ctx)
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() */