libosmo-netif 1.7.0.10-3a9e 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#include <osmocom/core/msgb.h>
17
35struct osmo_twjit;
36
48struct osmo_twjit_config;
49
59 struct osmo_twjit_stats {
60 /* For ABI reasons, none of the following fields may be deleted
61 * or reordered! */
62
63 /* normal operation */
64 uint32_t rx_packets;
65 uint32_t delivered_pkt;
66 uint32_t handovers_in;
67 uint32_t handovers_out;
68 uint32_t marker_resets;
69 /* undesirable, but not totally unexpected */
70 uint32_t too_old;
71 uint32_t underruns;
72 uint32_t ho_underruns;
73 uint32_t output_gaps;
74 uint32_t thinning_drops;
75 /* unusual error events */
76 uint32_t bad_packets;
77 uint32_t duplicate_ts;
78 /* independent analysis of Rx packet stream */
79 uint32_t ssrc_changes;
80 uint32_t seq_skips;
81 uint32_t seq_backwards;
82 uint32_t seq_repeats;
83 uint32_t intentional_gaps;
84 uint32_t ts_resets;
85 uint32_t jitter_max;
86 /* new counters added after first osmo_twjit ABI freeze */
87 uint32_t soft_underruns;
88
89 /* New fields may be added here at the end; once added, they become
90 * permanent like the initially defined ones. */
91};
92
103 struct osmo_twjit_rr_info {
104 /* For ABI reasons, none of the following fields may be deleted
105 * or reordered! */
106
108 uint32_t ssrc;
110 uint32_t rx_packets;
112 uint32_t base_seq;
114 uint32_t max_seq_ext;
116 uint32_t expected_pkt;
120 uint32_t jitter_accum;
121 /* New fields may be added here at the end; once added, they become
122 * permanent like the initially defined ones. */
123};
124
125/* twjit API: managing configuration structures */
126
127struct osmo_twjit_config *osmo_twjit_config_alloc(void *ctx);
128void osmo_twjit_config_free(struct osmo_twjit_config *conf);
129
130int osmo_twjit_config_set_buffer_depth(struct osmo_twjit_config *conf,
131 uint16_t bd_start, uint16_t bd_hiwat);
132int osmo_twjit_config_set_thinning_int(struct osmo_twjit_config *conf,
133 uint16_t thinning_int);
134int osmo_twjit_config_set_max_future_sec(struct osmo_twjit_config *conf,
135 uint16_t max_future_sec);
136int osmo_twjit_config_set_start_min_delta(struct osmo_twjit_config *conf,
137 uint16_t delta_ms);
138int osmo_twjit_config_set_start_max_delta(struct osmo_twjit_config *conf,
139 uint16_t delta_ms);
140int osmo_twjit_config_set_underrun_ext(struct osmo_twjit_config *conf,
141 uint16_t underrun_ext);
142int osmo_twjit_config_set_handover_on_marker(struct osmo_twjit_config *conf,
143 bool hom);
144
145/* twjit API: actual twjit instances */
146
147struct osmo_twjit *osmo_twjit_create(void *ctx, uint16_t clock_khz,
148 uint16_t quantum_ms,
149 const struct osmo_twjit_config *config);
150void osmo_twjit_destroy(struct osmo_twjit *twjit);
151
152int osmo_twjit_set_config(struct osmo_twjit *twjit,
153 const struct osmo_twjit_config *config);
154void osmo_twjit_reset(struct osmo_twjit *twjit);
155
156/* RTP input, takes ownership of msgb */
157void osmo_twjit_input(struct osmo_twjit *twjit, struct msgb *msg);
158
159/* output function, to be called by TDM/GSM/etc fixed-timing side */
160struct msgb *osmo_twjit_output(struct osmo_twjit *twjit);
161
162/* Stats and RR info structures are contained inside opaque struct osmo_twjit.
163 * We need to provide access to these stats and RR info structures to API
164 * users, but we don't want to make the whole twjit instance struct public.
165 * Also we would like to have fast external access to these stats, hence an API
166 * that copies our stats to caller-provided storage would be very inefficient.
167 * Compromise: we allow direct external access to just these selected parts
168 * of the full internal state structure by providing API functions that
169 * return pointers to these selected parts.
170 */
171const struct osmo_twjit_stats *
172 osmo_twjit_get_stats(struct osmo_twjit *twjit);
173
174const struct osmo_twjit_rr_info *
175 osmo_twjit_get_rr_info(struct osmo_twjit *twjit);
176
177/* When we compose outgoing RTCP packets in the upper layer of twrtp,
178 * we need to know whether or not we have received at least one valid
179 * RTP data packet so far. If we haven't received any RTP yet, then
180 * we have no Rx SSRC, all data in struct osmo_twjit_rr_info are invalid,
181 * and we cannot send RTCP reception reports.
182 */
183bool osmo_twjit_rr_info_valid(struct osmo_twjit *twjit);
184
185/* vty configuration functions */
186
187void osmo_twjit_vty_init(int twjit_node);
188
189struct vty;
190
191int osmo_twjit_config_write(struct vty *vty,
192 const struct osmo_twjit_config *conf,
193 const char *prefix);
194
osmo_twjit_config_alloc
struct osmo_twjit_config * osmo_twjit_config_alloc(void *ctx)
\addgroup twjit
Definition: twjit_conf.c:45
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.
Definition: twjit_conf.c:350
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.
Definition: twjit.c:754
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.
Definition: twjit_conf.c:286
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.
Definition: twjit_conf.c:320
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.
Definition: twjit_conf.c:377
osmo_twjit_reset
void osmo_twjit_reset(struct osmo_twjit *twjit)
Reset twjit instance to empty initial state.
Definition: twjit.c:216
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
Definition: twjit.c:133
osmo_twjit_rr_info_valid
bool osmo_twjit_rr_info_valid(struct osmo_twjit *twjit)
Did this twjit instance ever receive RTP input?
Definition: twjit.c:765
osmo_twjit_destroy
void osmo_twjit_destroy(struct osmo_twjit *twjit)
Destroy a twjit instance.
Definition: twjit.c:171
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.
Definition: twjit_conf.c:304
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.
Definition: twjit_conf.c:336
osmo_twjit_set_config
int osmo_twjit_set_config(struct osmo_twjit *twjit, const struct osmo_twjit_config *config)
Change twjit config parameters.
Definition: twjit.c:192
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.
Definition: twjit_conf.c:364
osmo_twjit_output
struct msgb * osmo_twjit_output(struct osmo_twjit *twjit)
Fixed-timing output poll from twjit buffer.
Definition: twjit.c:674
osmo_twjit_config_free
void osmo_twjit_config_free(struct osmo_twjit_config *conf)
Free a twjit config instance.
Definition: twjit_conf.c:102
osmo_twjit_get_stats
const struct osmo_twjit_stats * osmo_twjit_get_stats(struct osmo_twjit *twjit)
Retrieve lifetime stats from twjit instance.
Definition: twjit.c:728
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.
Definition: twjit_conf.c:117
osmo_twjit_input
void osmo_twjit_input(struct osmo_twjit *twjit, struct msgb *msg)
Feed received RTP packet to twjit.
Definition: twjit.c:464
osmo_twjit_rr_info
Info collected from the incoming RTP data stream for the purpose of generating RTCP reception report ...
Definition: twjit.h:103
osmo_twjit_rr_info::base_seq
uint32_t base_seq
"base" sequence number for "expected packets" computation
Definition: twjit.h:112
osmo_twjit_rr_info::rx_packets
uint32_t rx_packets
count of "received packets" for RTCP RR packet loss calculation
Definition: twjit.h:110
osmo_twjit_rr_info::jitter_accum
uint32_t jitter_accum
"interarrival jitter" measure of RFC 3550, accumulator for the leaky integrator algorithm prescribed ...
Definition: twjit.h:120
osmo_twjit_rr_info::ssrc
uint32_t ssrc
received SSRC to which all following info applies
Definition: twjit.h:108
osmo_twjit_rr_info::max_seq_ext
uint32_t max_seq_ext
"extended highest sequence number" field of RTCP RR
Definition: twjit.h:114
osmo_twjit_rr_info::expected_pkt
uint32_t expected_pkt
count of "expected packets" for RTCP RR packet loss calculation
Definition: twjit.h:116
osmo_twjit_stats
Stats collected during the lifetime of a twjit instance.
Definition: twjit.h:59