libosmo-netif 1.7.0.10-3a9e Osmocom network interface library

twrtp.h
1/*
2 * Themyscira Wireless RTP endpoint 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#include <osmocom/core/socket.h>
18
121struct osmo_twrtp;
122
132 struct osmo_twrtp_stats {
133 /* For ABI reasons, none of the following fields may be deleted
134 * or reordered! */
135 uint32_t rx_rtp_pkt;
136 uint32_t rx_rtp_badsrc;
137 uint32_t rx_rtcp_pkt;
138 uint32_t rx_rtcp_badsrc;
139 uint32_t rx_rtcp_invalid;
140 uint32_t rx_rtcp_wrong_ssrc;
141 uint32_t tx_rtp_pkt;
142 uint32_t tx_rtp_bytes;
143 uint32_t tx_rtcp_pkt;
144 /* New fields may be added here at the end; once added, they become
145 * permanent like the initially defined ones. */
146};
147
148/* declare structs that are used in our API */
149
150struct osmo_twjit;
151struct osmo_twjit_config;
152struct osmo_twjit_stats;
153struct osmo_twjit_rr_info;
154
155/* public API functions: create & destroy, local and remote addresses */
156
157struct osmo_twrtp *
158 osmo_twrtp_create(void *ctx, uint16_t clock_khz, uint16_t quantum_ms,
159 bool random_ts_seq,
160 const struct osmo_twjit_config *twjit_config);
161void osmo_twrtp_destroy(struct osmo_twrtp *endp);
162
163int osmo_twrtp_supply_fds(struct osmo_twrtp *endp, int rtp_fd, int rtcp_fd);
164int osmo_twrtp_bind_local(struct osmo_twrtp *endp,
165 const struct osmo_sockaddr *rtp_addr, bool bind_rtcp);
166int osmo_twrtp_set_remote(struct osmo_twrtp *endp,
167 const struct osmo_sockaddr *rtp_addr);
168
169/* receiving incoming RTP via twjit */
170
171void osmo_twrtp_twjit_rx_ctrl(struct osmo_twrtp *endp, bool rx_enable);
172
173/* output function, to be called by TDM/GSM/etc fixed-timing side */
174struct msgb *osmo_twrtp_twjit_rx_poll(struct osmo_twrtp *endp);
175
176/* receiving incoming RTP without twjit */
177
178/* callback function takes ownership of msgb *if* it returns true */
179typedef bool (*osmo_twrtp_raw_rx_cb)(struct osmo_twrtp *endp, void *user_data,
180 struct msgb *msg);
181
182void osmo_twrtp_set_raw_rx_cb(struct osmo_twrtp *endp, osmo_twrtp_raw_rx_cb cb,
183 void *user_data);
184
185/* RTP Tx direction */
186
187int osmo_twrtp_tx_quantum(struct osmo_twrtp *endp, const uint8_t *payload,
188 unsigned payload_len, uint8_t payload_type,
189 bool marker, bool auto_marker, bool send_rtcp);
190void osmo_twrtp_tx_skip(struct osmo_twrtp *endp);
191void osmo_twrtp_tx_restart(struct osmo_twrtp *endp);
192
193int osmo_twrtp_tx_forward(struct osmo_twrtp *endp, struct msgb *msg);
194
195/* support for emitting RTCP SR & RR */
196
197int osmo_twrtp_set_sdes(struct osmo_twrtp *endp, const char *cname,
198 const char *name, const char *email, const char *phone,
199 const char *loc, const char *tool, const char *note);
200void osmo_twrtp_set_auto_rtcp_interval(struct osmo_twrtp *endp,
201 uint16_t interval);
202
203int osmo_twrtp_send_rtcp_rr(struct osmo_twrtp *endp);
204
205/* information retrieval functions */
206
207struct osmo_twjit *osmo_twrtp_get_twjit(struct osmo_twrtp *endp);
208
209const struct osmo_twrtp_stats *osmo_twrtp_get_stats(struct osmo_twrtp *endp);
210
211/* have we received at least one RTCP RR matching our RTP Tx output? */
212bool osmo_twrtp_got_rtcp_rr(struct osmo_twrtp *endp);
213
214/* retrieving RTCP RR info: valid only if above function returned true */
215uint32_t osmo_twrtp_rr_lost_word(struct osmo_twrtp *endp);
216int32_t osmo_twrtp_rr_lost_cumulative(struct osmo_twrtp *endp);
217uint32_t osmo_twrtp_rr_jitter_last(struct osmo_twrtp *endp);
218uint32_t osmo_twrtp_rr_jitter_max(struct osmo_twrtp *endp);
219
220/* socket-related miscellany */
221
222int osmo_twrtp_get_rtp_fd(struct osmo_twrtp *endp);
223int osmo_twrtp_get_rtcp_fd(struct osmo_twrtp *endp);
224
225int osmo_twrtp_set_dscp(struct osmo_twrtp *endp, uint8_t dscp);
226int osmo_twrtp_set_socket_prio(struct osmo_twrtp *endp, int prio);
227
osmo_twrtp_get_rtp_fd
int osmo_twrtp_get_rtp_fd(struct osmo_twrtp *endp)
Retrieve file descriptor for RTP UDP socket.
Definition: twrtp.c:1203
osmo_twrtp_rr_lost_cumulative
int32_t osmo_twrtp_rr_lost_cumulative(struct osmo_twrtp *endp)
Info from received RTCP RR: cumulative number of packets lost.
Definition: twrtp.c:1123
osmo_twrtp_rr_lost_word
uint32_t osmo_twrtp_rr_lost_word(struct osmo_twrtp *endp)
Info from received RTCP RR: lost packets word.
Definition: twrtp.c:1109
osmo_twrtp_supply_fds
int osmo_twrtp_supply_fds(struct osmo_twrtp *endp, int rtp_fd, int rtcp_fd)
Equip twrtp endpoint with RTP and RTCP sockets (supplied file descriptors)
Definition: twrtp.c:298
osmo_twrtp_tx_forward
int osmo_twrtp_tx_forward(struct osmo_twrtp *endp, struct msgb *msg)
Forward RTP packet between endpoints.
Definition: twrtp.c:739
osmo_twrtp_tx_restart
void osmo_twrtp_tx_restart(struct osmo_twrtp *endp)
Reset output stream cadence.
Definition: twrtp.c:721
osmo_twrtp_set_dscp
int osmo_twrtp_set_dscp(struct osmo_twrtp *endp, uint8_t dscp)
Set DSCP (Differentiated Services Code Point) for emitted RTP and RTCP packets.
Definition: twrtp.c:1237
osmo_twrtp_destroy
void osmo_twrtp_destroy(struct osmo_twrtp *endp)
Destroy a twrtp endpoint.
Definition: twrtp.c:253
osmo_twrtp_set_auto_rtcp_interval
void osmo_twrtp_set_auto_rtcp_interval(struct osmo_twrtp *endp, uint16_t interval)
Configure automatic emission of periodic RTCP SR packets.
Definition: twrtp.c:975
osmo_twrtp_set_sdes
int osmo_twrtp_set_sdes(struct osmo_twrtp *endp, const char *cname, const char *name, const char *email, const char *phone, const char *loc, const char *tool, const char *note)
Set SDES strings for RTCP SR and RR packet generation.
Definition: twrtp.c:1000
osmo_twrtp_set_socket_prio
int osmo_twrtp_set_socket_prio(struct osmo_twrtp *endp, int prio)
Set socket priority for emitted RTP and RTCP packets.
Definition: twrtp.c:1260
osmo_twrtp_tx_skip
void osmo_twrtp_tx_skip(struct osmo_twrtp *endp)
Incur an intentional gap in the emitted RTP stream.
Definition: twrtp.c:704
osmo_twrtp_set_raw_rx_cb
void osmo_twrtp_set_raw_rx_cb(struct osmo_twrtp *endp, osmo_twrtp_raw_rx_cb cb, void *user_data)
Set callback function for unbuffered/non-delayed Rx path.
Definition: twrtp.c:555
osmo_twrtp_get_twjit
struct osmo_twjit * osmo_twrtp_get_twjit(struct osmo_twrtp *endp)
Get twjit from twrtp.
Definition: twrtp.c:1174
osmo_twrtp_set_remote
int osmo_twrtp_set_remote(struct osmo_twrtp *endp, const struct osmo_sockaddr *rtp_addr)
Set RTP remote address.
Definition: twrtp.c:449
osmo_twrtp_bind_local
int osmo_twrtp_bind_local(struct osmo_twrtp *endp, const struct osmo_sockaddr *rtp_addr, bool bind_rtcp)
Equip twrtp endpoint with locally bound RTP and RTCP sockets.
Definition: twrtp.c:375
osmo_twrtp_get_stats
const struct osmo_twrtp_stats * osmo_twrtp_get_stats(struct osmo_twrtp *endp)
Retrieve lifetime stats from twrtp instance.
Definition: twrtp.c:1189
osmo_twrtp_twjit_rx_ctrl
void osmo_twrtp_twjit_rx_ctrl(struct osmo_twrtp *endp, bool rx_enable)
Enable or disable Rx via twjit.
Definition: twrtp.c:509
osmo_twrtp_send_rtcp_rr
int osmo_twrtp_send_rtcp_rr(struct osmo_twrtp *endp)
Emit RTCP RR packet.
Definition: twrtp.c:964
osmo_twrtp_got_rtcp_rr
bool osmo_twrtp_got_rtcp_rr(struct osmo_twrtp *endp)
Have we received any RTCP RR?
Definition: twrtp.c:1093
osmo_twrtp_twjit_rx_poll
struct msgb * osmo_twrtp_twjit_rx_poll(struct osmo_twrtp *endp)
Fixed-timing output poll from the twrtp endpoint's twjit buffer.
Definition: twrtp.c:527
osmo_twrtp_rr_jitter_max
uint32_t osmo_twrtp_rr_jitter_max(struct osmo_twrtp *endp)
Info from received RTCP RR: interarrival jitter, highest received.
Definition: twrtp.c:1150
osmo_twrtp_create
struct osmo_twrtp * osmo_twrtp_create(void *ctx, uint16_t clock_khz, uint16_t quantum_ms, bool random_ts_seq, const struct osmo_twjit_config *twjit_config)
\addgroup twrtp
Definition: twrtp.c:217
osmo_twrtp_get_rtcp_fd
int osmo_twrtp_get_rtcp_fd(struct osmo_twrtp *endp)
Retrieve file descriptor for RTCP UDP socket.
Definition: twrtp.c:1219
osmo_twrtp_tx_quantum
int osmo_twrtp_tx_quantum(struct osmo_twrtp *endp, const uint8_t *payload, unsigned payload_len, uint8_t payload_type, bool marker, bool auto_marker, bool send_rtcp)
Emit RTP packet carrying a locally sourced quantum of speech/data.
Definition: twrtp.c:606
osmo_twrtp_rr_jitter_last
uint32_t osmo_twrtp_rr_jitter_last(struct osmo_twrtp *endp)
Info from received RTCP RR: interarrival jitter, most recent.
Definition: twrtp.c:1139
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_stats
Stats collected during the lifetime of a twjit instance.
Definition: twjit.h:59
osmo_twrtp_stats
Stats collected during the lifetime of a twrtp instance.
Definition: twrtp.h:132