libosmo-netif 1.6.0.16-c51c Osmocom network interface library

Loading...
Searching...
No Matches
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 fields may be added here at the end; once added, they become
87 * permanent like the initially defined ones. */
88};
89
100 struct osmo_twjit_rr_info {
101 /* For ABI reasons, none of the following fields may be deleted
102 * or reordered! */
103
105 uint32_t ssrc;
107 uint32_t rx_packets;
109 uint32_t base_seq;
111 uint32_t max_seq_ext;
113 uint32_t expected_pkt;
117 uint32_t jitter_accum;
118 /* New fields may be added here at the end; once added, they become
119 * permanent like the initially defined ones. */
120};
121
122/* twjit API: managing configuration structures */
123
124struct osmo_twjit_config *osmo_twjit_config_alloc(void *ctx);
125void osmo_twjit_config_free(struct osmo_twjit_config *conf);
126
127int osmo_twjit_config_set_buffer_depth(struct osmo_twjit_config *conf,
128 uint16_t bd_start, uint16_t bd_hiwat);
129int osmo_twjit_config_set_thinning_int(struct osmo_twjit_config *conf,
130 uint16_t thinning_int);
131int osmo_twjit_config_set_max_future_sec(struct osmo_twjit_config *conf,
132 uint16_t max_future_sec);
133int osmo_twjit_config_set_start_min_delta(struct osmo_twjit_config *conf,
134 uint16_t delta_ms);
135int osmo_twjit_config_set_start_max_delta(struct osmo_twjit_config *conf,
136 uint16_t delta_ms);
137int osmo_twjit_config_set_handover_on_marker(struct osmo_twjit_config *conf,
138 bool hom);
139
140/* twjit API: actual twjit instances */
141
142struct osmo_twjit *osmo_twjit_create(void *ctx, uint16_t clock_khz,
143 uint16_t quantum_ms,
144 const struct osmo_twjit_config *config);
145void osmo_twjit_destroy(struct osmo_twjit *twjit);
146
147int osmo_twjit_set_config(struct osmo_twjit *twjit,
148 const struct osmo_twjit_config *config);
149void osmo_twjit_reset(struct osmo_twjit *twjit);
150
151/* RTP input, takes ownership of msgb */
152void osmo_twjit_input(struct osmo_twjit *twjit, struct msgb *msg);
153
154/* output function, to be called by TDM/GSM/etc fixed-timing side */
155struct msgb *osmo_twjit_output(struct osmo_twjit *twjit);
156
157/* Stats and RR info structures are contained inside opaque struct osmo_twjit.
158 * We need to provide access to these stats and RR info structures to API
159 * users, but we don't want to make the whole twjit instance struct public.
160 * Also we would like to have fast external access to these stats, hence an API
161 * that copies our stats to caller-provided storage would be very inefficient.
162 * Compromise: we allow direct external access to just these selected parts
163 * of the full internal state structure by providing API functions that
164 * return pointers to these selected parts.
165 */
166const struct osmo_twjit_stats *
167 osmo_twjit_get_stats(struct osmo_twjit *twjit);
168
169const struct osmo_twjit_rr_info *
170 osmo_twjit_get_rr_info(struct osmo_twjit *twjit);
171
172/* When we compose outgoing RTCP packets in the upper layer of twrtp,
173 * we need to know whether or not we have received at least one valid
174 * RTP data packet so far. If we haven't received any RTP yet, then
175 * we have no Rx SSRC, all data in struct osmo_twjit_rr_info are invalid,
176 * and we cannot send RTCP reception reports.
177 */
178bool osmo_twjit_rr_info_valid(struct osmo_twjit *twjit);
179
180/* vty configuration functions */
181
182void osmo_twjit_vty_init(int twjit_node);
183
184struct vty;
185
186int osmo_twjit_config_write(struct vty *vty,
187 const struct osmo_twjit_config *conf,
188 const char *prefix);
189
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:325
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:690
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:261
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:295
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:338
osmo_twjit_reset
void osmo_twjit_reset(struct osmo_twjit *twjit)
Reset twjit instance to empty initial state.
Definition twjit.c:212
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:129
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:701
osmo_twjit_destroy
void osmo_twjit_destroy(struct osmo_twjit *twjit)
Destroy a twjit instance.
Definition twjit.c:167
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:279
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:311
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:188
osmo_twjit_output
struct msgb * osmo_twjit_output(struct osmo_twjit *twjit)
Fixed-timing output poll from twjit buffer.
Definition twjit.c:618
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:664
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:460
osmo_twjit_rr_info
Info collected from the incoming RTP data stream for the purpose of generating RTCP reception report ...
Definition twjit.h:100
osmo_twjit_rr_info::base_seq
uint32_t base_seq
"base" sequence number for "expected packets" computation
Definition twjit.h:109
osmo_twjit_rr_info::rx_packets
uint32_t rx_packets
count of "received packets" for RTCP RR packet loss calculation
Definition twjit.h:107
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:117
osmo_twjit_rr_info::ssrc
uint32_t ssrc
received SSRC to which all following info applies
Definition twjit.h:105
osmo_twjit_rr_info::max_seq_ext
uint32_t max_seq_ext
"extended highest sequence number" field of RTCP RR
Definition twjit.h:111
osmo_twjit_rr_info::expected_pkt
uint32_t expected_pkt
count of "expected packets" for RTCP RR packet loss calculation
Definition twjit.h:113
osmo_twjit_stats
Stats collected during the lifetime of a twjit instance.
Definition twjit.h:59