libosmo-netif: Themyscira Wireless RTP jitter buffer implementation

libosmo-netif 1.7.0.15-fe2d Osmocom network interface library

Data Structures | Functions
Themyscira Wireless RTP jitter buffer implementation

The present twjit layer is an interface mechanism from an incoming RTP stream to an output application that has fixed timing requirements, e.g., the Tx side of GSM Um TCH or a T1/E1 TDM interface. More...

## Data Structures
struct | osmo_twjit_stats
| Stats collected during the lifetime of a twjit instance. More...
struct | osmo_twjit_rr_info
| Info collected from the incoming RTP data stream for the purpose of generating RTCP reception report blocks. More...

## Functions
struct osmo_twjit_config * | osmo_twjit_config_alloc (void *ctx)
| \addgroup twjit More...
void | osmo_twjit_config_free (struct osmo_twjit_config *conf)
| Free a twjit config instance. More...
int | osmo_twjit_config_set_buffer_depth (struct osmo_twjit_config *conf, uint16_t bd_start, uint16_t bd_hiwat)
| Non-vty function for buffer-depth setting. More...
int | osmo_twjit_config_set_thinning_int (struct osmo_twjit_config *conf, uint16_t thinning_int)
| Non-vty function for thinning-interval setting. More...
int | osmo_twjit_config_set_max_future_sec (struct osmo_twjit_config *conf, uint16_t max_future_sec)
| Non-vty function for max-future-sec setting. More...
int | osmo_twjit_config_set_start_min_delta (struct osmo_twjit_config *conf, uint16_t delta_ms)
| Non-vty function for start-min-delta setting. More...
int | osmo_twjit_config_set_start_max_delta (struct osmo_twjit_config *conf, uint16_t delta_ms)
| Non-vty function for start-max-delta setting. More...
int | osmo_twjit_config_set_underrun_ext (struct osmo_twjit_config *conf, uint16_t underrun_ext)
| Non-vty function for underrun-extension setting. More...
int | osmo_twjit_config_set_handover_on_marker (struct osmo_twjit_config *conf, bool hom)
| Non-vty function for marker-handling setting. More...
struct osmo_twjit * | osmo_twjit_create (void *ctx, uint16_t clock_khz, uint16_t quantum_ms, const struct osmo_twjit_config *config)
| \addgroup twjit More...
void | osmo_twjit_destroy (struct osmo_twjit *twjit)
| Destroy a twjit instance. More...
int | osmo_twjit_set_config (struct osmo_twjit *twjit, const struct osmo_twjit_config *config)
| Change twjit config parameters. More...
void | osmo_twjit_reset (struct osmo_twjit *twjit)
| Reset twjit instance to empty initial state. More...
void | osmo_twjit_input (struct osmo_twjit *twjit, struct msgb *msg)
| Feed received RTP packet to twjit. More...
struct msgb * | osmo_twjit_output (struct osmo_twjit *twjit)
| Fixed-timing output poll from twjit buffer. More...
const struct osmo_twjit_stats * | osmo_twjit_get_stats (struct osmo_twjit *twjit)
| Retrieve lifetime stats from twjit instance. More...
const struct osmo_twjit_rr_info * | osmo_twjit_get_rr_info (struct osmo_twjit *twjit)
| Retrieve RR info from twjit instance. More...
bool | osmo_twjit_rr_info_valid (struct osmo_twjit *twjit)
| Did this twjit instance ever receive RTP input? More...
void | osmo_twjit_vty_init (int twjit_node)
int | osmo_twjit_config_write (struct vty *vty, const struct osmo_twjit_config *conf, const char *prefix)
| Write out vty form of twjit config structure. More...
| DEFUN (cfg_buffer_depth, cfg_buffer_depth_cmd, "buffer-depth <1-65535> <1-65535>", "Buffer depth configuration\n" "Minimum fill required to start flow\n" "High water mark fill level\n")
| DEFUN (cfg_thinning, cfg_thinning_cmd, "thinning-interval <2-65535>", "Standing queue thinning configuration\n" "Drop every Nth packet\n")
| DEFUN (cfg_max_future, cfg_max_future_cmd, "max-future-sec <1-65535>", "Guard against time traveler packets\n" "Maximum permissible number of seconds into the future\n")
| DEFUN (cfg_start_min_delta, cfg_start_min_delta_cmd, "start-min-delta <1-65535>", "Minimum required delta in time-of-arrival to start flow\n" "Time delta value in ms\n")
| DEFUN (cfg_no_start_min_delta, cfg_no_start_min_delta_cmd, "no start-min-delta", NO_STR "Minimum required delta in time-of-arrival to start flow\n")
| DEFUN (cfg_start_max_delta, cfg_start_max_delta_cmd, "start-max-delta <1-65535>", "Maximum permitted gap in time-of-arrival in starting state\n" "Time delta value in ms\n")
| DEFUN (cfg_no_start_max_delta, cfg_no_start_max_delta_cmd, "no start-max-delta", NO_STR "Maximum permitted gap in time-of-arrival in starting state\n")
| DEFUN (cfg_underrun_ext, cfg_underrun_ext_cmd, "underrun-extension <1-65535>", "Underrun extension for intentional gaps (DTX)\n" "Maximum number of consecutive omitted packets\n")
| DEFUN (cfg_no_underrun_ext, cfg_no_underrun_ext_cmd, "no underrun-extension", NO_STR "Underrun extension for intentional gaps\n")
| DEFUN (cfg_marker_handling, cfg_marker_handling_cmd, "marker-handling (handover|ignore)", "How to handle RTP packets with marker bit set\n" "Invoke handover handling, same as SSRC change\n" "Ignore marker bit\n")

## Detailed Description

The present twjit layer is an interface mechanism from an incoming RTP stream to an output application that has fixed timing requirements, e.g., the Tx side of GSM Um TCH or a T1/E1 TDM interface.

For a more detailed description, please consult the full twrtp guide document that can be found in doc/twrtp directory. This document is required reading for anyone seeking to properly understand the present jitter buffer facility, its domain of application and how to use it. Specific section references to this document will be made in subsequent comments.

## Function Documentation

## ◆ osmo_twjit_config_alloc()

struct osmo_twjit_config * osmo_twjit_config_alloc | ( | void * | ctx | ) |

\addgroup twjit

Allocate and initialize twjit config structure

Parameters

  [in] | ctx | Parent talloc context under which struct osmo_twjit_config should be allocated.

Returns
  pointer to the newly created twjit config instance, or NULL on errors.

A typical application will have a struct osmo_twjit_config somewhere in the application config data structures, editable via vty. More complex applications may even have several such twjit config structures, to be used in different contexts such as GSM vs PSTN. However, in the present Osmocom-integrated version of twjit, this config structure has been made opaque for ABI reasons - hence config instances now have to be allocated by the library, rather than merely initialized in content.

## ◆ osmo_twjit_config_free()

void osmo_twjit_config_free | ( | struct osmo_twjit_config * | conf | ) |

Free a twjit config instance.

Parameters

  [in] | conf | Instance to be freed

## ◆ osmo_twjit_config_set_buffer_depth()

int osmo_twjit_config_set_buffer_depth | ( | struct osmo_twjit_config * | conf,
|  | uint16_t | bd_start,
|  | uint16_t | bd_hiwat
| ) |  |

Non-vty function for buffer-depth setting.

Parameters

  [in] | conf | twjit config instance to operate on.
  [in] | bd_start | Flow-starting fill level, document section 2.3.3.
  [in] | bd_hiwat | High water mark fill level, document section 2.3.4.2.

Returns
  0 if successful, negative on errors.

## ◆ osmo_twjit_config_set_handover_on_marker()

int osmo_twjit_config_set_handover_on_marker | ( | struct osmo_twjit_config * | conf,
|  | bool | hom
| ) |  |

Non-vty function for marker-handling setting.

Parameters

  [in] | conf | twjit config instance to operate on.
  [in] | hom | Handover on marker if true, ignore marker bit if false.

Returns
  0 if successful, negative on errors.

## ◆ osmo_twjit_config_set_max_future_sec()

int osmo_twjit_config_set_max_future_sec | ( | struct osmo_twjit_config * | conf,
|  | uint16_t | max_future_sec
| ) |  |

Non-vty function for max-future-sec setting.

Parameters

  [in] | conf | twjit config instance to operate on.
  [in] | max_future_sec | Maximum number of seconds into the future, document section 2.3.4.3.

Returns
  0 if successful, negative on errors.

## ◆ osmo_twjit_config_set_start_max_delta()

int osmo_twjit_config_set_start_max_delta | ( | struct osmo_twjit_config * | conf,
|  | uint16_t | delta_ms
| ) |  |

Non-vty function for start-max-delta setting.

Parameters

  [in] | conf | twjit config instance to operate on.
  [in] | delta_ms | Maximum permitted ToA gap in ms, or 0 to disable this check; document section 2.3.3.2.

Returns
  0 if successful, negative on errors.

## ◆ osmo_twjit_config_set_start_min_delta()

int osmo_twjit_config_set_start_min_delta | ( | struct osmo_twjit_config * | conf,
|  | uint16_t | delta_ms
| ) |  |

Non-vty function for start-min-delta setting.

Parameters

  [in] | conf | twjit config instance to operate on.
  [in] | delta_ms | Minimum required ToA delta in ms, or 0 to disable this check; document section 2.3.3.2.

Returns
  0 if successful, negative on errors.

## ◆ osmo_twjit_config_set_thinning_int()

int osmo_twjit_config_set_thinning_int | ( | struct osmo_twjit_config * | conf,
|  | uint16_t | thinning_int
| ) |  |

Non-vty function for thinning-interval setting.

Parameters

  [in] | conf | twjit config instance to operate on.
  [in] | thinning_int | Thinning interval setting, document section 2.3.4.2.

Returns
  0 if successful, negative on errors.

## ◆ osmo_twjit_config_set_underrun_ext()

int osmo_twjit_config_set_underrun_ext | ( | struct osmo_twjit_config * | conf,
|  | uint16_t | underrun_ext
| ) |  |

Non-vty function for underrun-extension setting.

Parameters

  [in] | conf | twjit config instance to operate on.
  [in] | underrun_ext | Maximum permissible intentional gap, in packets, or 0 to disable this mechanism.

Returns
  0 if successful, negative on errors.

## ◆ osmo_twjit_config_write()

int osmo_twjit_config_write | ( | struct vty * | vty,
|  | const struct osmo_twjit_config * | conf,
|  | const char * | prefix
| ) |  |

Write out vty form of twjit config structure.

Parameters

  [in] | vty | The vty instance to which vty_out() calls should be made
  [in] | conf | The config structure to write out
  [in] | prefix | Additional indent prefix to be prepended to each output line, defaults to "" if NULL

Returns
  CMD_SUCCESS for vty system

## ◆ osmo_twjit_create()

struct osmo_twjit * osmo_twjit_create | ( | void * | ctx,
|  | uint16_t | clock_khz,
|  | uint16_t | quantum_ms,
|  | const struct osmo_twjit_config * | config
| ) |  |

\addgroup twjit

Create a twjit instance

Parameters

  [in] | ctx | Parent talloc context under which struct osmo_twjit should be allocated.
  [in] | clock_khz | RTP clock rate in kHz, i.e., number of RTP timestamp units per millisecond. The most common value is 8.
  [in] | quantum_ms | Duration of a single quantum (unit of speech or data carried in one RTP packet) in milliseconds. The most common value is 20.
  [in] | config | Set of tunable configuration parameters to be used.

Returns
  pointer to the newly created twjit instance, or NULL on errors.

In contrast to the original twrtp-proto version, this version of osmo_twjit_create() copies the config structure, thus the application is not required to maintain it in the originally passed memory.

Referenced by osmo_twrtp_create().

## ◆ osmo_twjit_destroy()

void osmo_twjit_destroy | ( | struct osmo_twjit * | twjit | ) |

Destroy a twjit instance.

Parameters

  [in] | twjit | Instance to be freed

Memory freed by this function includes not only the instance structure, but also any msgbs that are held by this instance.

Referenced by osmo_twrtp_destroy().

## ◆ osmo_twjit_get_rr_info()

const struct osmo_twjit_rr_info * osmo_twjit_get_rr_info | ( | struct osmo_twjit * | twjit | ) |

Retrieve RR info from twjit instance.

Parameters

  [in] | twjit | Instance to query

Returns
  pointer to RR info structure

The structure retrieved with this API is called RR info because it contains info that is needed in order to constuct RTCP reception reports describing the RTP stream received by this twjit instance. But of course this info can also be used for other statistics-related or monitoring-related purposes.

The structure returned by this API is fully valid only if osmo_twjit_rr_info_valid() returns true. If that API returns false, the RR info structure returned by the present API should be considered invalid. More precisely, the "invalid" RR info structure will be all zeros on a freshly created twjit, or stale info if this twjit received some RTP input prior to being reset. There may be some applications that retrieve the RR info structure to report some non-critical stats; such uses are allowed even when this structure is invalid in the strict sense.

## ◆ osmo_twjit_get_stats()

const struct osmo_twjit_stats * osmo_twjit_get_stats | ( | struct osmo_twjit * | twjit | ) |

Retrieve lifetime stats from twjit instance.

Parameters

  [in] | twjit | Instance to query

Returns
  pointer to lifetime stats structure

## ◆ osmo_twjit_input()

void osmo_twjit_input | ( | struct osmo_twjit * | twjit,
|  | struct msgb * | msg
| ) |  |

Feed received RTP packet to twjit.

Parameters

  [in] | twjit | Instance to which input is being fed
  [in] | msg | Message buffer containing the received packet

The msgb fed to this API is always consumed by the called function: if it isn't freed for being invalid or too old, it is queued to be regurgitated some time later on the output side. The design of twjit assumes that this API will be called as soon as each incoming RTP packet is received from the IP network, without any additional delays; in most applications, thus function will be called by twrtp layer from osmo_io Rx callback path.

## ◆ osmo_twjit_output()

struct msgb * osmo_twjit_output | ( | struct osmo_twjit * | twjit | ) |

Fixed-timing output poll from twjit buffer.

Parameters

  [in] | twjit | Instance to poll

Returns
  pointer to msgb holding a previously received RTP packet that was successfully mapped to the present quantum in the fixed-timing output, or NULL if no such packet is available.

Referenced by osmo_twrtp_twjit_rx_poll().

## ◆ osmo_twjit_reset()

void osmo_twjit_reset | ( | struct osmo_twjit * | twjit | ) |

Reset twjit instance to empty initial state.

Parameters

  [in] | twjit | Instance to be reset

This reset function is intended to be called when the application stops doing regular (once every time quantum) reads from the jitter buffer, but may resume this activity later. All packet Rx state and queues are cleared, but "lifetime" statistical counters are NOT reset.

Referenced by osmo_twrtp_twjit_rx_ctrl().

## ◆ osmo_twjit_rr_info_valid()

bool osmo_twjit_rr_info_valid | ( | struct osmo_twjit * | twjit | ) |

Did this twjit instance ever receive RTP input?

Parameters

  [in] | twjit | Instance to query

Returns
  true if this twjit instance received RTP input since it was created or last reset, false otherwise.

## ◆ osmo_twjit_set_config()

int osmo_twjit_set_config | ( | struct osmo_twjit * | twjit,
|  | const struct osmo_twjit_config * | config
| ) |  |

Change twjit config parameters.

Parameters

  [in] | twjit | Instance to be reconfigured
  [in] | config | Structure with new tuning parameters to be used

Returns
  0 if successful, negative on errors

The intended use for this API is applications that can use one of several different twjit config profiles depending on various conditions, but might not know the correct choice of profile at the time they create the twjit instance - or more likely, the containing twrtp instance.