libosmo-netif 1.5.1.31-6b3f
Osmocom network interface library
twjit.h
1/*
2 * Themyscira Wireless RTP jitter buffer implementation:
3 * public API definition for Osmocom-integrated version.
4 *
5 * This code was contributed to Osmocom Cellular Network Infrastructure
6 * project by Mother Mychaela N. Falconia of Themyscira Wireless.
7 * Mother Mychaela's contributions are NOT subject to copyright:
8 * no rights reserved, all rights relinquished.
9 */
10
11#pragma once
12
13#include <stdint.h>
14#include <stdbool.h>
15
16/*
17 * Each instance of twjit in the present version exists as struct osmo_twjit.
18 * This structure is opaque, and always constitutes a talloc context.
19 */
20struct osmo_twjit;
21
22/*
23 * twjit configuration tunings, usually set via vty. This config structure
24 * always has to be provided in order to create a twjit instance.
25 */
27 /* buffer depth: starting minimum and high watermark */
28 uint16_t bd_start;
29 uint16_t bd_hiwat;
30 /* interval for thinning of too-deep standing queue */
31 uint16_t thinning_int;
32 /* guard against time traveler RTP packets */
33 uint16_t max_future_sec;
34 /* min and max time delta in starting state, 0 means not set */
35 uint16_t start_min_delta;
36 uint16_t start_max_delta;
37};
38
39/*
40 * Stats collected during the lifetime of a twjit instance.
41 */
43 /* normal operation */
44 uint32_t rx_packets;
45 uint32_t delivered_pkt;
46 uint32_t handovers_in;
47 uint32_t handovers_out;
48 /* undesirable, but not totally unexpected */
49 uint32_t too_old;
50 uint32_t underruns;
51 uint32_t ho_underruns;
52 uint32_t output_gaps;
53 uint32_t thinning_drops;
54 /* unusual error events */
55 uint32_t bad_packets;
56 uint32_t duplicate_ts;
57 /* independent analysis of Rx packet stream */
58 uint32_t ssrc_changes;
59 uint32_t seq_skips;
60 uint32_t seq_backwards;
61 uint32_t seq_repeats;
62 uint32_t intentional_gaps;
63 uint32_t ts_resets;
64 uint32_t jitter_max;
65};
66
67/*
68 * Info collected from the incoming RTP data stream
69 * for the purpose of generating RTCP reception report blocks.
70 * Key point: unlike the counters in struct osmo_twjit_stats,
71 * all RR info is reset to initial whenever incoming SSRC changes,
72 * as necessitated by RTCP data model being organized per SSRC.
73 */
75 uint32_t ssrc;
76 uint32_t rx_packets;
77 uint32_t base_seq;
78 uint32_t max_seq_ext;
79 uint32_t expected_pkt;
80 uint32_t jitter_accum;
81};
82
83/* twjit module API functions */
84
85struct osmo_twjit *osmo_twjit_create(void *ctx, uint16_t clock_khz,
86 uint16_t quantum_ms,
87 const struct osmo_twjit_config *config);
88void osmo_twjit_destroy(struct osmo_twjit *twjit);
89
90void osmo_twjit_new_config(struct osmo_twjit *twjit,
91 const struct osmo_twjit_config *config);
92void osmo_twjit_reset(struct osmo_twjit *twjit);
93
94struct msgb;
95
96/* RTP input, takes ownership of msgb */
97void osmo_twjit_input(struct osmo_twjit *twjit, struct msgb *msg);
98
99/* output function, to be called by TDM/GSM/etc fixed-timing side */
100struct msgb *osmo_twjit_output(struct osmo_twjit *twjit);
101
102/* Stats and RR info structures are contained inside opaque struct osmo_twjit.
103 * We need to provide access to these stats and RR info structures to API
104 * users, but we don't want to make the whole twjit instance struct public.
105 * Also we would like to have fast external access to these stats, hence an API
106 * that copies our stats to caller-provided storage would be very inefficient.
107 * Compromise: we allow direct external access to just these selected parts
108 * of the full internal state structure by providing API functions that
109 * return pointers to these selected parts.
110 */
111const struct osmo_twjit_stats *
112osmo_twjit_get_stats(struct osmo_twjit *twjit);
113
114const struct osmo_twjit_rr_info *
115osmo_twjit_get_rr_info(struct osmo_twjit *twjit);
116
117/* When we compose outgoing RTCP packets in the upper layer of twrtp,
118 * we need to know whether or not we have received at least one valid
119 * RTP data packet so far. If we haven't received any RTP yet, then
120 * we have no Rx SSRC, all data in struct osmo_twjit_rr_info are invalid,
121 * and we cannot send RTCP reception reports.
122 */
123bool osmo_twjit_got_any_input(struct osmo_twjit *twjit);
124
125/* vty configuration functions */
126
127void osmo_twjit_init_defaults(struct osmo_twjit_config *config);
128
129void osmo_twjit_vty_init(int twjit_node);
130
131struct vty;
132
133int osmo_twjit_config_write(struct vty *vty,
134 const struct osmo_twjit_config *conf,
135 const char *name, const char *prefix);
Definition: twjit.h:26
Definition: twjit.h:74
Definition: twjit.h:42
Definition: twjit_private.h:51