Osmocom Multiplex Protocol

Files
file	osmux.h
file	osmux.c
	Osmocom multiplex protocol helpers.
file	osmux_input.c
	Osmocom multiplex protocol helpers (input)
file	osmux_output.c
	Osmocom multiplex protocol helpers (output)

Data Structures
struct	osmux_hdr
struct	osmux_in_handle
struct	osmux_out_handle
struct	osmux_batch
struct	osmux_circuit
struct	osmux_input_state
struct	osmux_tx_handle

Macros
#define	OSMUX_DEFAULT_PORT   1984
#define	OSMUX_FT_SIGNAL   0
#define	OSMUX_FT_VOICE_AMR   1
#define	OSMUX_FT_DUMMY   2
#define	OSMUX_MAX_CONCURRENT_CALLS   8
#define	OSMUX_BATCH_DEFAULT_MAX   1472
#define	SNPRINTF_BUFFER_SIZE(ret, remain, offset)
#define	DELTA_RTP_MSG   20000
#define	DELTA_RTP_TIMESTAMP   160
#define	DELTA_RTP_MSG   20000
#define	DELTA_RTP_TIMESTAMP   160

Typedefs
typedef struct msgb *(*	rtp_msgb_alloc_cb_t) (void *rtp_msgb_alloc_priv_data, unsigned int msg_len)

Functions
struct osmux_hdr	__attribute__ ((packed))
static uint8_t *	osmux_get_payload (struct osmux_hdr *osmuxh)
int	osmux_snprintf (char *buf, size_t size, struct msgb *msg)
struct osmux_in_handle *	osmux_xfrm_input_alloc (void *ctx)
	Allocate a new osmux in handle (osmux source, tx side) More...
void	osmux_xfrm_input_init (struct osmux_in_handle *h) OSMO_DEPRECATED("Use osmux_xfrm_input_alloc() instead")
void	osmux_xfrm_input_fini (struct osmux_in_handle *h) OSMO_DEPRECATED("Use talloc_free() instead")
int	osmux_xfrm_input_set_batch_factor (struct osmux_in_handle *h, uint8_t batch_factor)
void	osmux_xfrm_input_set_batch_size (struct osmux_in_handle *h, uint16_t batch_size)
void	osmux_xfrm_input_set_initial_seqnum (struct osmux_in_handle *h, uint8_t osmux_seqnum)
void	osmux_xfrm_input_set_deliver_cb (struct osmux_in_handle *h, void(*deliver_cb)(struct msgb *msg, void *data), void *data)
void *	osmux_xfrm_input_get_deliver_cb_data (struct osmux_in_handle *h)
int	osmux_xfrm_input_open_circuit (struct osmux_in_handle *h, int ccid, int dummy)
void	osmux_xfrm_input_close_circuit (struct osmux_in_handle *h, int ccid)
int	osmux_xfrm_input (struct osmux_in_handle *h, struct msgb *msg, int ccid)
void	osmux_xfrm_input_deliver (struct osmux_in_handle *h)
struct osmux_out_handle *	osmux_xfrm_output_alloc (void *ctx)
	Allocate a new osmux out handle. More...
void	osmux_xfrm_output_init (struct osmux_out_handle *h, uint32_t rtp_ssrc) OSMO_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) OSMO_DEPRECATED("Use osmux_xfrm_output_alloc() and osmux_xfrm_output_set_rtp_*() instead")
void	osmux_xfrm_output_set_rtp_ssrc (struct osmux_out_handle *h, uint32_t rtp_ssrc)
	Set SSRC of generated RTP packets from Osmux frames. More...
void	osmux_xfrm_output_set_rtp_pl_type (struct osmux_out_handle *h, uint32_t rtp_payload_type)
	Set Payload Type of generated RTP packets from Osmux frames. More...
void	osmux_xfrm_output_set_tx_cb (struct osmux_out_handle *h, void(*tx_cb)(struct msgb *msg, void *data), void *data)
	Set transmission callback to call when a generated RTP packet is to be transmitted. More...
void	osmux_xfrm_output_set_rtp_msgb_alloc_cb (struct osmux_out_handle *h, rtp_msgb_alloc_cb_t cb, void *cb_data)
	Set callback to call when an RTP packet to be generated is to be allocated. More...
int	osmux_xfrm_output_sched (struct osmux_out_handle *h, struct osmux_hdr *osmuxh)
	Generate RTP packets from osmux frame AMR payload set and schedule them for transmission at appropriate time. More...
void	osmux_xfrm_output_flush (struct osmux_out_handle *h)
	Flush all scheduled RTP packets still pending to be transmitted. More...
struct osmux_hdr *	osmux_xfrm_output_pull (struct msgb *msg)
static uint32_t	osmux_get_payload_len (struct osmux_hdr *osmuxh)
static int	osmux_snprintf_header (char *buf, size_t size, struct osmux_hdr *osmuxh)
static int	osmux_snprintf_payload (char *buf, size_t size, const uint8_t *payload, int payload_len)
static uint32_t	osmux_ft_dummy_size (uint8_t amr_ft, uint8_t batch_factor)
static int	osmux_circuit_enqueue (struct osmux_circuit *circuit, struct msgb *msg, uint8_t batch_factor)
static void	osmux_circuit_dequeue (struct osmux_circuit *circuit, struct msgb *msg)
static void	osmux_circuit_del_msgs (struct osmux_batch *batch, struct osmux_circuit *circuit)
static int	osmux_batch_put (struct osmux_batch *batch, struct osmux_input_state *state)
static void	osmux_encode_dummy (struct osmux_batch *batch, uint8_t batch_factor, struct osmux_input_state *state)
static struct msgb *	osmux_build_batch (struct osmux_batch *batch, uint32_t batch_size, uint8_t batch_factor)
static void	osmux_batch_timer_expired (void *data)
static int	osmux_rtp_amr_payload_len (struct amr_hdr *amrh, uint32_t amr_len)
static int	osmux_circuit_get_last_stored_amr_ft (struct osmux_circuit *circuit)
static int	osmux_replay_lost_packets (struct osmux_circuit *circuit, struct rtp_hdr *cur_rtph, int batch_factor)
static struct osmux_circuit *	osmux_batch_find_circuit (struct osmux_batch *batch, int ccid)
static void	osmux_batch_del_circuit (struct osmux_batch *batch, struct osmux_circuit *circuit)
static int	osmux_batch_add (struct osmux_batch *batch, uint32_t batch_factor, struct msgb *msg, struct rtp_hdr *rtph, int ccid)
static int	osmux_xfrm_input_talloc_destructor (struct osmux_in_handle *h)
static struct msgb *	osmux_rebuild_rtp (struct osmux_out_handle *h, struct osmux_hdr *osmuxh, void *payload, int payload_len, bool first_pkt)
static void	osmux_xfrm_output_trigger (void *data)
static int	osmux_xfrm_output_talloc_destructor (struct osmux_out_handle *h)

Variables
struct osmux_in_handle	__attribute__
static void *	osmux_ctx

Detailed Description

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

Macro Definition Documentation

SNPRINTF_BUFFER_SIZE

#define SNPRINTF_BUFFER_SIZE	(		ret,
			remain,
			offset
	)

Value:

if (ret < 0)                                    \
                ret = 0;                                \
        offset += ret;                                  \
        if (ret > remain)                               \
                ret = remain;                           \
        remain -= ret;

Function Documentation

osmux_snprintf()

int osmux_snprintf	(	char *	buf,
		size_t	size,
		struct msgb *	msg
	)

Print osmux header fields and payload from msg into buffer buf.

Parameters

[out]	buf	buffer to store the output into
[in]	len	length of buf in bytes
[in]	msgb	message buffer containing one or more osmux frames

Returns

the number of characters printed (excluding the null byte used to end output to strings).

If the output was truncated due to this limit, then the return value is the number of characters (excluding the terminating null byte) which would have been written to the final string if enough space had been available.

osmux_xfrm_input()

int osmux_xfrm_input	(	struct osmux_in_handle *	h,
		struct msgb *	msg,
		int	ccid
	)

osmux_xfrm_input - add RTP message to OSmux batch

Parameters

msg	RTP message that you want to batch into one OSmux message

If 0 is returned, this indicates that the message has been batched and the msgb is now owned by the osmux layer. If negative value is returned, an error occurred and the message has been dropped (and freed). If 1 is returned, you have to invoke osmux_xfrm_input_deliver and try again.

The function takes care of releasing the messages in case of error and when building the batch.

osmux_xfrm_input_alloc()

struct osmux_in_handle * osmux_xfrm_input_alloc

(

void *

ctx

)

Allocate a new osmux in handle (osmux source, tx side)

Parameters

[in]

ctx

talloc context to use when allocating the returned struct

Returns

Allocated osmux in handle

This object contains configuration and state to handle a group of circuits (trunk), receiving RTP packets from the upper layer (API user) and sending batched & trunked Osmux messages containing all the data of those circuits down the 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.

osmux_xfrm_output_alloc()

struct osmux_out_handle * osmux_xfrm_output_alloc

(

void *

ctx

)

Allocate a new osmux out handle.

Parameters

[in]

ctx

talloc context to use when allocating the returned struct

Returns

Allocated osmux out handle

This object contains configuration and state to handle a specific CID in incoming network Osmux messages, repackaging the frames for that CID as RTP packets and pushing them up the protocol stack. Returned pointer can be freed with regular talloc_free, queue will be flushed and all internal data will be freed.

osmux_xfrm_output_flush()

void osmux_xfrm_output_flush

(

struct osmux_out_handle *

h

)

Flush all scheduled RTP packets still pending to be transmitted.

Parameters

[in]

h

the osmux out handle to flush

This function will immediately call the transmit callback for all queued RTP packets, making sure the list ends up empty. It will also stop all internal timers to make sure the osmux_out_handle can be dropped or re-used by calling osmux_xfrm_output on it.

osmux_xfrm_output_sched()

int osmux_xfrm_output_sched	(	struct osmux_out_handle *	h,
		struct osmux_hdr *	osmuxh
	)

Generate RTP packets from osmux frame AMR payload set and schedule them for transmission at appropriate time.

Parameters

[in]	h	the osmux out handle handling a specific CID
[in]	osmuxh	Buffer pointing to osmux frame header structure and AMR payload

Returns

Number of generated RTP packets

The osmux frame passed to this function must be of the type OSMUX_FT_VOICE_AMR. The generated RTP packets are kept into h's internal list and sent to the callback configured through osmux_xfrm_output_set_tx_cb when are ready to be transmitted according to schedule.

osmux_xfrm_output_set_rtp_msgb_alloc_cb()

void osmux_xfrm_output_set_rtp_msgb_alloc_cb	(	struct osmux_out_handle *	h,
		rtp_msgb_alloc_cb_t	cb,
		void *	cb_data
	)

Set callback to call when an RTP packet to be generated is to be allocated.

Parameters

[in]	h	the osmux out handle handling a specific CID
[in]	cb	User defined msgb alloc function for generated RTP pkts
[in]	cb_data	Opaque data pointer set by user and passed in cb

Returns

msgb structure to be used to fill in generated RTP pkt content

osmux_xfrm_output_set_rtp_pl_type()

void osmux_xfrm_output_set_rtp_pl_type	(	struct osmux_out_handle *	h,
		uint32_t	rtp_payload_type
	)

Set Payload Type of generated RTP packets from Osmux frames.

Parameters

[in]	h	the osmux out handle handling a specific CID
[in]	rtp_payload_type	the RTP Payload Type to set

osmux_xfrm_output_set_rtp_ssrc()

void osmux_xfrm_output_set_rtp_ssrc	(	struct osmux_out_handle *	h,
		uint32_t	rtp_ssrc
	)

Set SSRC of generated RTP packets from Osmux frames.

Parameters

[in]	h	the osmux out handle handling a specific CID
[in]	rtp_ssrc	the RTP SSRC to set

osmux_xfrm_output_set_tx_cb()

void osmux_xfrm_output_set_tx_cb	(	struct osmux_out_handle *	h,
		void(*)(struct msgb *msg, void *data)	tx_cb,
		void *	data
	)

Set transmission callback to call when a generated RTP packet is to be transmitted.

Parameters

[in]	h	the osmux out handle handling a specific CID
[in]	osmuxh	Buffer pointing to osmux frame header structure and AMR payload

Returns

Number of generated RTP packets

This Function sets the callback called by the interal timer set by osmux_xfrm_out_sched function.