libosmo-netif: Osmocom Multiplex Protocol

libosmo-netif 1.7.0.15-fe2d Osmocom network interface library

Files | Data Structures | Macros | Typedefs | Functions | Variables
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. More...

## Files
file | osmux.h
| Osmocom multiplex protocol helpers.
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
| Osmux protocol header. More...
struct | osmux_in_handle
| one to handle all existing RTP flows More...
struct | osmux_out_handle
| one per OSmux circuit_id, ie. More...

## 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

## 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))
int | osmux_snprintf (char *buf, size_t size, struct msgb *msg)
| Print osmux header fields and payload from msg into buffer buf. More...
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")
void | osmux_xfrm_input_set_name (struct osmux_in_handle *h, const char *name)
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)
| osmux_xfrm_input - add RTP message to OSmux batch More...
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)

## Variables
struct osmux_in_handle | __attribute__

## 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

## 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_input_fini()

void osmux_xfrm_input_fini | ( | struct osmux_in_handle * | h | ) |

Deprecated:
  : Use talloc_free() instead (will call osmux_xfrm_input_talloc_destructor())

## ◆ osmux_xfrm_input_init()

void osmux_xfrm_input_init | ( | struct osmux_in_handle * | h | ) |

Deprecated:
  : Use osmux_xfrm_input_alloc() instead

## ◆ 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_init()

void osmux_xfrm_output_init | ( | struct osmux_out_handle * | h,
|  | uint32_t | rtp_ssrc
| ) |  |

Deprecated:
  : Use osmux_xfrm_output_alloc() and osmux_xfrm_output_set_rtp_*() instead

## ◆ osmux_xfrm_output_init2()

void osmux_xfrm_output_init2 | ( | struct osmux_out_handle * | h,
|  | uint32_t | rtp_ssrc,
|  | uint8_t | rtp_payload_type
| ) |  |

Deprecated:
  : Use osmux_xfrm_output_alloc() and osmux_xfrm_output_set_rtp_*() instead

## ◆ 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.