FreeCalypso > hg > themwi-rtp-lib

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