FreeCalypso > hg > themwi-rtp-lib

annotate include/twjit.h @ 3:d10ea5dc61b3

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
twjit: initial import from previous work repository The initial development of twjit was done in a private branch of osmo-bts git repository; the intent was to prototype twjit in osmo-bts. However, as I am getting a better feel for the full scope of the problem (producing a replacement for libortp), I changed course to the present themwi-rtp-lib (libtwrtp) approach.
author Mychaela Falconia <falcon@freecalypso.org>
date Fri, 05 Jul 2024 18:50:48 +0000
parents
children 668b84c52094
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
3
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1 /*
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
2 * Themyscira Wireless jitter buffer implementation: definition of
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
3 * structures and API functions.
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
4 */
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
5
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
6 #pragma once
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
7
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
8 #include <stdint.h>
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
9 #include <stdbool.h>
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
10
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
11 #include <osmocom/core/linuxlist.h>
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
12 #include <osmocom/core/timer.h>
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
13
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
14 /*
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
15 * twjit configuration tunings, usually set via vty.
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
16 */
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
17 struct twrtp_jibuf_config {
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
18 /* buffer depth: starting minimum and high watermark */
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
19 uint16_t bd_start;
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
20 uint16_t bd_hiwat;
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
21 /* interval for thinning of too-deep standing queue */
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
22 uint16_t thinning_int;
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
23 /* guard against time traveler RTP packets */
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
24 uint16_t max_future_sec;
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
25 /* min and max time delta in starting state, 0 means not set */
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
26 uint16_t start_min_delta;
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
27 uint16_t start_max_delta;
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
28 };
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
29
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
30 /*
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
31 * Stats collected during the lifetime of a twjit instance.
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
32 */
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
33 struct twrtp_jibuf_stats {
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
34 /* normal operation */
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
35 uint32_t delivered_pkt;
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
36 uint32_t delivered_bytes;
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
37 uint32_t handovers;
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
38 /* undesirable, but not totally unexpected */
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
39 uint32_t too_old;
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
40 uint32_t underruns;
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
41 uint32_t output_gaps;
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
42 uint32_t thinning_drops;
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
43 /* unusual error events */
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
44 uint32_t bad_packets;
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
45 uint32_t duplicate_ts;
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
46 /* independent analysis of Rx packet stream */
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
47 uint32_t ssrc_changes;
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
48 uint32_t seq_skips;
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
49 uint32_t seq_backwards;
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
50 uint32_t seq_repeats;
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
51 uint32_t intentional_gaps;
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
52 uint32_t ts_resets;
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
53 };
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
54
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
55 /*
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
56 * Each twjit instance has two sub-buffers; each subbuf is a queue of
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
57 * received RTP packets that have the same SSRC and whose timestamps
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
58 * increment in the expected cadence, with each ts delta being an
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
59 * integral multiple of the samples-per-quantum constant.
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
60 */
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
61 struct twrtp_jibuf_sub {
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
62 uint32_t ssrc;
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
63 uint32_t head_ts;
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
64 struct llist_head queue;
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
65 uint32_t depth;
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
66 /* last packet arrival time, used only in starting state */
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
67 struct timeval last_arrival;
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
68 uint32_t delta_ms;
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
69 /* thinning mechanism */
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
70 uint16_t drop_int_count;
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
71 /* running config for this subbuf */
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
72 struct twrtp_jibuf_config conf;
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
73 };
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
74
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
75 /*
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
76 * Each twjit instance is in one of 4 fundamental states at any moment,
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
77 * as enumerated here.
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
78 */
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
79 enum twrtp_jibuf_state {
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
80 TWJIT_STATE_EMPTY,
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
81 TWJIT_STATE_HUNT,
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
82 TWJIT_STATE_FLOWING,
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
83 TWJIT_STATE_HANDOVER,
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
84 };
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
85
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
86 /* Main structure for one instance of twjit */
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
87 struct twrtp_jibuf_inst {
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
88 /* pointer to config structure given to twrtp_jibuf_create(),
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
89 * memory must remain valid, but content can change at any time. */
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
90 struct twrtp_jibuf_config *ext_config;
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
91 /* count of RTP timestamp units per quantum */
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
92 uint32_t ts_quantum;
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
93 /* quanta per second, used to scale max_future_sec */
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
94 uint32_t quanta_per_sec;
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
95 /* operational state */
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
96 enum twrtp_jibuf_state state;
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
97 struct twrtp_jibuf_sub sb[2];
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
98 uint8_t read_sb; /* 0 or 1 */
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
99 uint8_t write_sb; /* ditto */
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
100 /* Rx packet stream analysis */
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
101 uint32_t last_ssrc;
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
102 uint32_t last_ts;
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
103 uint16_t last_seq;
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
104 bool got_first_packet;
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
105 /* stats over lifetime of this instance */
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
106 struct twrtp_jibuf_stats stats;
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
107 };
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
108
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
109 /* twjit module API functions */
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
110
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
111 struct twrtp_jibuf_inst *twrtp_jibuf_create(void *ctx, uint16_t quantum_ms,
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
112 uint32_t quantum_ts_inc,
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
113 struct twrtp_jibuf_config *config);
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
114
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
115 void twrtp_jibuf_destroy(struct twrtp_jibuf_inst *twjit);
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
116
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
117 struct msgb;
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
118
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
119 /* RTP input, takes ownership of msgb */
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
120 void twrtp_jibuf_input(struct twrtp_jibuf_inst *twjit, struct msgb *msg);
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
121
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
122 /* output function, to be called by TDM/GSM/etc fixed-timing side */
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
123 struct msgb *twrtp_jibuf_output(struct twrtp_jibuf_inst *twjit);
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
124
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
125 /* vty configuration functions */
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
126
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
127 void twrtp_jibuf_init_defaults(struct twrtp_jibuf_config *config);
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
128
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
129 void twrtp_jibuf_vty_init(int twjit_node);
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
130
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
131 struct vty;
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
132
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
133 int twrtp_jibuf_config_write(struct vty *vty,
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
134 const struct twrtp_jibuf_config *conf,
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
135 const char *name, const char *prefix);