FreeCalypso > hg > themwi-rtp-lib

annotate src/twjit.c @ 41:bda6b24385f7

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
twjit config: revisit default settings The only actual change here is bumping the high water mark setting from 2 to 3; the rest of this patch is comment changes.
author Mychaela Falconia <falcon@freecalypso.org>
date Fri, 20 Dec 2024 22:13:01 +0000
parents 1485211d4492
children 334d883b96ba
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 /*
5
1bb26347e253 twjit: split into separate base/in/out modules
Mychaela Falconia <falcon@freecalypso.org>
parents: 3
diff changeset
2 * Themyscira Wireless jitter buffer implementation: main body.
3
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
3 */
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 #include <stdint.h>
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
6 #include <stdbool.h>
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
7 #include <string.h>
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
8
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
9 #include <osmocom/core/linuxlist.h>
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
10 #include <osmocom/core/msgb.h>
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
11 #include <osmocom/core/talloc.h>
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
12 #include <osmocom/core/utils.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 #include <themwi/rtp/twjit.h>
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
15
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
16 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
17 {
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
18 memset(config, 0, sizeof(struct twrtp_jibuf_config));
41
bda6b24385f7 twjit config: revisit default settings
Mychaela Falconia <falcon@freecalypso.org>
parents: 39
diff changeset
19
bda6b24385f7 twjit config: revisit default settings
Mychaela Falconia <falcon@freecalypso.org>
parents: 39
diff changeset
20 /* While the theoretical minimum starting fill level is 1, the
bda6b24385f7 twjit config: revisit default settings
Mychaela Falconia <falcon@freecalypso.org>
parents: 39
diff changeset
21 * practically useful minimum (achieving lowest latency, but not
bda6b24385f7 twjit config: revisit default settings
Mychaela Falconia <falcon@freecalypso.org>
parents: 39
diff changeset
22 * incurring underruns in normal healthy operation) is 2 for typical
bda6b24385f7 twjit config: revisit default settings
Mychaela Falconia <falcon@freecalypso.org>
parents: 39
diff changeset
23 * network configurations that combine elements with "perfect" 20 ms
bda6b24385f7 twjit config: revisit default settings
Mychaela Falconia <falcon@freecalypso.org>
parents: 39
diff changeset
24 * timing (T1/E1 interfaces, external IP-PSTN links, software
bda6b24385f7 twjit config: revisit default settings
Mychaela Falconia <falcon@freecalypso.org>
parents: 39
diff changeset
25 * transcoders timed by system clock etc) and GSM-to-IP OsmoBTS
bda6b24385f7 twjit config: revisit default settings
Mychaela Falconia <falcon@freecalypso.org>
parents: 39
diff changeset
26 * whose 20 ms timing contains the small inherent jitter of TDMA. */
bda6b24385f7 twjit config: revisit default settings
Mychaela Falconia <falcon@freecalypso.org>
parents: 39
diff changeset
27 config->bd_start = 2;
bda6b24385f7 twjit config: revisit default settings
Mychaela Falconia <falcon@freecalypso.org>
parents: 39
diff changeset
28
bda6b24385f7 twjit config: revisit default settings
Mychaela Falconia <falcon@freecalypso.org>
parents: 39
diff changeset
29 /* The high water mark setting determines when the standing queue
bda6b24385f7 twjit config: revisit default settings
Mychaela Falconia <falcon@freecalypso.org>
parents: 39
diff changeset
30 * thinning mechanism kicks in. A standing queue that is longer
bda6b24385f7 twjit config: revisit default settings
Mychaela Falconia <falcon@freecalypso.org>
parents: 39
diff changeset
31 * than the starting fill level will occur when the flow starts
bda6b24385f7 twjit config: revisit default settings
Mychaela Falconia <falcon@freecalypso.org>
parents: 39
diff changeset
32 * during a network latency spike, but then the network latency
bda6b24385f7 twjit config: revisit default settings
Mychaela Falconia <falcon@freecalypso.org>
parents: 39
diff changeset
33 * goes down. If this setting is too high, deep standing queues
bda6b24385f7 twjit config: revisit default settings
Mychaela Falconia <falcon@freecalypso.org>
parents: 39
diff changeset
34 * will persist, adding needless latency to speech or CSD.
bda6b24385f7 twjit config: revisit default settings
Mychaela Falconia <falcon@freecalypso.org>
parents: 39
diff changeset
35 * If this setting is too low, the thinning mechanism will be
bda6b24385f7 twjit config: revisit default settings
Mychaela Falconia <falcon@freecalypso.org>
parents: 39
diff changeset
36 * too invasive, needlessly and perhaps frequently deleting a quantum
bda6b24385f7 twjit config: revisit default settings
Mychaela Falconia <falcon@freecalypso.org>
parents: 39
diff changeset
37 * of speech or data from the stream and incurring a phase shift.
bda6b24385f7 twjit config: revisit default settings
Mychaela Falconia <falcon@freecalypso.org>
parents: 39
diff changeset
38 * Starting fill level plus 2 seems like a good default. */
bda6b24385f7 twjit config: revisit default settings
Mychaela Falconia <falcon@freecalypso.org>
parents: 39
diff changeset
39 config->bd_hiwat = 4;
bda6b24385f7 twjit config: revisit default settings
Mychaela Falconia <falcon@freecalypso.org>
parents: 39
diff changeset
40
bda6b24385f7 twjit config: revisit default settings
Mychaela Falconia <falcon@freecalypso.org>
parents: 39
diff changeset
41 /* When the standing queue thinning mechanism does kick in,
bda6b24385f7 twjit config: revisit default settings
Mychaela Falconia <falcon@freecalypso.org>
parents: 39
diff changeset
42 * it drops every Nth packet, where N is the thinning interval.
bda6b24385f7 twjit config: revisit default settings
Mychaela Falconia <falcon@freecalypso.org>
parents: 39
diff changeset
43 * Given that this mechanism forcibly deletes a quantum of speech
bda6b24385f7 twjit config: revisit default settings
Mychaela Falconia <falcon@freecalypso.org>
parents: 39
diff changeset
44 * or data from the stream, these induced disruptions should be
bda6b24385f7 twjit config: revisit default settings
Mychaela Falconia <falcon@freecalypso.org>
parents: 39
diff changeset
45 * spaced out, and the managing operator should also keep in mind
bda6b24385f7 twjit config: revisit default settings
Mychaela Falconia <falcon@freecalypso.org>
parents: 39
diff changeset
46 * that the incurred phase shift may be a problem for some
bda6b24385f7 twjit config: revisit default settings
Mychaela Falconia <falcon@freecalypso.org>
parents: 39
diff changeset
47 * applications, particularly CSD. Our current default is
bda6b24385f7 twjit config: revisit default settings
Mychaela Falconia <falcon@freecalypso.org>
parents: 39
diff changeset
48 * a prime number, reducing the probability that the thinning
bda6b24385f7 twjit config: revisit default settings
Mychaela Falconia <falcon@freecalypso.org>
parents: 39
diff changeset
49 * mechanism will interfere badly with intrinsic features of the
bda6b24385f7 twjit config: revisit default settings
Mychaela Falconia <falcon@freecalypso.org>
parents: 39
diff changeset
50 * stream being thinned. 17 quantum units at 20 ms per quantum
bda6b24385f7 twjit config: revisit default settings
Mychaela Falconia <falcon@freecalypso.org>
parents: 39
diff changeset
51 * is 340 ms, which should be sufficiently long spacing to make
bda6b24385f7 twjit config: revisit default settings
Mychaela Falconia <falcon@freecalypso.org>
parents: 39
diff changeset
52 * speech quantum deletions tolerable. */
bda6b24385f7 twjit config: revisit default settings
Mychaela Falconia <falcon@freecalypso.org>
parents: 39
diff changeset
53 config->thinning_int = 17;
bda6b24385f7 twjit config: revisit default settings
Mychaela Falconia <falcon@freecalypso.org>
parents: 39
diff changeset
54
bda6b24385f7 twjit config: revisit default settings
Mychaela Falconia <falcon@freecalypso.org>
parents: 39
diff changeset
55 /* With RTP timestamps being 32 bits and with the usual RTP
bda6b24385f7 twjit config: revisit default settings
Mychaela Falconia <falcon@freecalypso.org>
parents: 39
diff changeset
56 * clock rate of 8000 timestamp units per second, a packet may
bda6b24385f7 twjit config: revisit default settings
Mychaela Falconia <falcon@freecalypso.org>
parents: 39
diff changeset
57 * arrive that claims to be as far as 3 days into the future.
bda6b24385f7 twjit config: revisit default settings
Mychaela Falconia <falcon@freecalypso.org>
parents: 39
diff changeset
58 * Such aberrant RTP packets are jocularly referred to as
bda6b24385f7 twjit config: revisit default settings
Mychaela Falconia <falcon@freecalypso.org>
parents: 39
diff changeset
59 * time travelers. Assuming that actual time travel either
bda6b24385f7 twjit config: revisit default settings
Mychaela Falconia <falcon@freecalypso.org>
parents: 39
diff changeset
60 * does not exist at all or at least does not happen in the
bda6b24385f7 twjit config: revisit default settings
Mychaela Falconia <falcon@freecalypso.org>
parents: 39
diff changeset
61 * present context, we reason that when such "time traveler" RTP
bda6b24385f7 twjit config: revisit default settings
Mychaela Falconia <falcon@freecalypso.org>
parents: 39
diff changeset
62 * packets do arrive, we must be dealing with the effect of a
bda6b24385f7 twjit config: revisit default settings
Mychaela Falconia <falcon@freecalypso.org>
parents: 39
diff changeset
63 * software bug or misdesign or misconfiguration in whatever
bda6b24385f7 twjit config: revisit default settings
Mychaela Falconia <falcon@freecalypso.org>
parents: 39
diff changeset
64 * foreign network element is sending us RTP. In any case,
bda6b24385f7 twjit config: revisit default settings
Mychaela Falconia <falcon@freecalypso.org>
parents: 39
diff changeset
65 * irrespective of the cause, we must be prepared for the
bda6b24385f7 twjit config: revisit default settings
Mychaela Falconia <falcon@freecalypso.org>
parents: 39
diff changeset
66 * possibility of seeming "time travel" in the incoming RTP stream.
bda6b24385f7 twjit config: revisit default settings
Mychaela Falconia <falcon@freecalypso.org>
parents: 39
diff changeset
67 * We implement an arbitrary threshold: if the received RTP ts
bda6b24385f7 twjit config: revisit default settings
Mychaela Falconia <falcon@freecalypso.org>
parents: 39
diff changeset
68 * is too far into the future, we treat that packet as the
bda6b24385f7 twjit config: revisit default settings
Mychaela Falconia <falcon@freecalypso.org>
parents: 39
diff changeset
69 * beginning of a new stream, same as SSRC change or non-quantum
bda6b24385f7 twjit config: revisit default settings
Mychaela Falconia <falcon@freecalypso.org>
parents: 39
diff changeset
70 * ts increment. This threshold has 1 s granularity, which is
bda6b24385f7 twjit config: revisit default settings
Mychaela Falconia <falcon@freecalypso.org>
parents: 39
diff changeset
71 * sufficient for its intended purpose of catching gross errors.
bda6b24385f7 twjit config: revisit default settings
Mychaela Falconia <falcon@freecalypso.org>
parents: 39
diff changeset
72 * The minimum setting of this threshold is 1 s, but let's
bda6b24385f7 twjit config: revisit default settings
Mychaela Falconia <falcon@freecalypso.org>
parents: 39
diff changeset
73 * default to 10 s, being generous to networks with really bad
bda6b24385f7 twjit config: revisit default settings
Mychaela Falconia <falcon@freecalypso.org>
parents: 39
diff changeset
74 * latency. */
bda6b24385f7 twjit config: revisit default settings
Mychaela Falconia <falcon@freecalypso.org>
parents: 39
diff changeset
75 config->max_future_sec = 10;
3
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
76 }
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
77
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
78 /* create and destroy functions */
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
79
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
80 struct twrtp_jibuf_inst *
15
355de6301404 twjit: simplify create API, factor out clock & quantum config
Mychaela Falconia <falcon@freecalypso.org>
parents: 8
diff changeset
81 twrtp_jibuf_create(void *ctx, struct twrtp_jibuf_config *config)
3
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
82 {
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
83 struct twrtp_jibuf_inst *twjit;
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 twjit = talloc_zero(ctx, struct twrtp_jibuf_inst);
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
86 if (!twjit)
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
87 return NULL;
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
88
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
89 twjit->ext_config = config;
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
90 twjit->state = TWJIT_STATE_EMPTY;
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
91 INIT_LLIST_HEAD(&twjit->sb[0].queue);
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
92 INIT_LLIST_HEAD(&twjit->sb[1].queue);
15
355de6301404 twjit: simplify create API, factor out clock & quantum config
Mychaela Falconia <falcon@freecalypso.org>
parents: 8
diff changeset
93 /* default of 8 kHz clock, 20 ms quantum */
355de6301404 twjit: simplify create API, factor out clock & quantum config
Mychaela Falconia <falcon@freecalypso.org>
parents: 8
diff changeset
94 twrtp_jibuf_set_ts_quant(twjit, 8, 20);
3
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
95
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
96 return twjit;
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
97 }
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
98
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
99 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
100 {
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
101 msgb_queue_free(&twjit->sb[0].queue);
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
102 msgb_queue_free(&twjit->sb[1].queue);
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
103 talloc_free(twjit);
d10ea5dc61b3 twjit: initial import from previous work repository
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
104 }
15
355de6301404 twjit: simplify create API, factor out clock & quantum config
Mychaela Falconia <falcon@freecalypso.org>
parents: 8
diff changeset
105
355de6301404 twjit: simplify create API, factor out clock & quantum config
Mychaela Falconia <falcon@freecalypso.org>
parents: 8
diff changeset
106 /* basic housekeeping */
355de6301404 twjit: simplify create API, factor out clock & quantum config
Mychaela Falconia <falcon@freecalypso.org>
parents: 8
diff changeset
107
355de6301404 twjit: simplify create API, factor out clock & quantum config
Mychaela Falconia <falcon@freecalypso.org>
parents: 8
diff changeset
108 void twrtp_jibuf_set_ts_quant(struct twrtp_jibuf_inst *twjit,
355de6301404 twjit: simplify create API, factor out clock & quantum config
Mychaela Falconia <falcon@freecalypso.org>
parents: 8
diff changeset
109 uint16_t clock_khz, uint16_t quantum_ms)
355de6301404 twjit: simplify create API, factor out clock & quantum config
Mychaela Falconia <falcon@freecalypso.org>
parents: 8
diff changeset
110 {
355de6301404 twjit: simplify create API, factor out clock & quantum config
Mychaela Falconia <falcon@freecalypso.org>
parents: 8
diff changeset
111 twjit->ts_quantum = (uint32_t) quantum_ms * clock_khz;
355de6301404 twjit: simplify create API, factor out clock & quantum config
Mychaela Falconia <falcon@freecalypso.org>
parents: 8
diff changeset
112 twjit->quanta_per_sec = 1000 / quantum_ms;
355de6301404 twjit: simplify create API, factor out clock & quantum config
Mychaela Falconia <falcon@freecalypso.org>
parents: 8
diff changeset
113 twjit->ts_units_per_ms = clock_khz;
355de6301404 twjit: simplify create API, factor out clock & quantum config
Mychaela Falconia <falcon@freecalypso.org>
parents: 8
diff changeset
114 twjit->ts_units_per_sec = (uint32_t) clock_khz * 1000;
355de6301404 twjit: simplify create API, factor out clock & quantum config
Mychaela Falconia <falcon@freecalypso.org>
parents: 8
diff changeset
115 twjit->ns_to_ts_units = 1000000 / clock_khz;
355de6301404 twjit: simplify create API, factor out clock & quantum config
Mychaela Falconia <falcon@freecalypso.org>
parents: 8
diff changeset
116 }
16
58e9719d1a84 twjit: add reset function
Mychaela Falconia <falcon@freecalypso.org>
parents: 15
diff changeset
117
58e9719d1a84 twjit: add reset function
Mychaela Falconia <falcon@freecalypso.org>
parents: 15
diff changeset
118 void twrtp_jibuf_reset(struct twrtp_jibuf_inst *twjit)
58e9719d1a84 twjit: add reset function
Mychaela Falconia <falcon@freecalypso.org>
parents: 15
diff changeset
119 {
58e9719d1a84 twjit: add reset function
Mychaela Falconia <falcon@freecalypso.org>
parents: 15
diff changeset
120 msgb_queue_free(&twjit->sb[0].queue);
58e9719d1a84 twjit: add reset function
Mychaela Falconia <falcon@freecalypso.org>
parents: 15
diff changeset
121 msgb_queue_free(&twjit->sb[1].queue);
58e9719d1a84 twjit: add reset function
Mychaela Falconia <falcon@freecalypso.org>
parents: 15
diff changeset
122 twjit->state = TWJIT_STATE_EMPTY;
58e9719d1a84 twjit: add reset function
Mychaela Falconia <falcon@freecalypso.org>
parents: 15
diff changeset
123 twjit->sb[0].depth = 0;
58e9719d1a84 twjit: add reset function
Mychaela Falconia <falcon@freecalypso.org>
parents: 15
diff changeset
124 twjit->sb[1].depth = 0;
58e9719d1a84 twjit: add reset function
Mychaela Falconia <falcon@freecalypso.org>
parents: 15
diff changeset
125 twjit->got_first_packet = false;
58e9719d1a84 twjit: add reset function
Mychaela Falconia <falcon@freecalypso.org>
parents: 15
diff changeset
126 }