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_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_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_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.

Data Structures

Functions

Detailed Description

Function Documentation

◆ osmo_twjit_config_alloc()

◆ osmo_twjit_config_free()

◆ osmo_twjit_config_set_buffer_depth()

◆ osmo_twjit_config_set_handover_on_marker()

◆ osmo_twjit_config_set_max_future_sec()

◆ osmo_twjit_config_set_start_max_delta()

◆ osmo_twjit_config_set_start_min_delta()

◆ osmo_twjit_config_set_thinning_int()

◆ osmo_twjit_config_write()

◆ osmo_twjit_create()

◆ osmo_twjit_destroy()

◆ osmo_twjit_get_rr_info()

◆ osmo_twjit_get_stats()

◆ osmo_twjit_input()

◆ osmo_twjit_output()

◆ osmo_twjit_reset()

◆ osmo_twjit_rr_info_valid()

◆ osmo_twjit_set_config()