ROHC compression/decompression library
rohc_comp_internals.h
Go to the documentation of this file.
1 /*
2  * Copyright 2010,2011,2012,2013,2014 Didier Barvaux
3  * Copyright 2012,2013,2014 Viveris Technologies
4  *
5  * This library is free software; you can redistribute it and/or
6  * modify it under the terms of the GNU Lesser General Public
7  * License as published by the Free Software Foundation; either
8  * version 2.1 of the License, or (at your option) any later version.
9  *
10  * This library is distributed in the hope that it will be useful,
11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13  * Lesser General Public License for more details.
14  *
15  * You should have received a copy of the GNU Lesser General Public
16  * License along with this library; if not, write to the Free Software
17  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
18  */
19 
20 /**
21  * @file rohc_comp_internals.h
22  * @brief Internal structures for ROHC compression
23  * @author Didier Barvaux <didier.barvaux@toulouse.viveris.com>
24  * @author Didier Barvaux <didier@barvaux.org>
25  */
26 
27 #ifndef ROHC_COMP_INTERNALS_H
28 #define ROHC_COMP_INTERNALS_H
29 
30 #include "rohc_internal.h"
31 #include "rohc_traces_internal.h"
32 #include "rohc_packets.h"
33 #include "rohc_comp.h"
34 #include "schemes/comp_wlsb.h"
35 #include "net_pkt.h"
36 #include "feedback.h"
37 
38 #ifdef __KERNEL__
39 # include <linux/types.h>
40 #else
41 # include <stdbool.h>
42 #endif
43 
44 
45 /*
46  * Constants and macros
47  */
48 
49 /** The number of ROHC profiles ready to be used */
50 #define C_NUM_PROFILES 7U
51 
52 /** The default maximal number of packets sent in > IR states (= FO and SO
53  * states) before changing back the state to IR (periodic refreshes) */
54 #define CHANGE_TO_IR_COUNT 1700
55 
56 /** The default maximal number of packets sent in > FO states (= SO state)
57  * before changing back the state to FO (periodic refreshes) */
58 #define CHANGE_TO_FO_COUNT 700
59 
60 /** The minimal number of packets that must be sent while in IR state before
61  * being able to switch to the FO state */
62 #define MAX_IR_COUNT 3U
63 
64 /** The minimal number of packets that must be sent while in FO state before
65  * being able to switch to the SO state */
66 #define MAX_FO_COUNT 3U
67 
68 /** The minimal number of packets that must be sent while in INIT_STRIDE
69  * state before being able to switch to the SEND_SCALED state */
70 #define ROHC_INIT_TS_STRIDE_MIN 3U
71 
72 /**
73  * @brief Default number of transmission for lists to become a reference list
74  *
75  * The minimal number of times of compressed list shall be sent to become
76  * a reference list. L is the name specified in the RFC.
77  */
78 #define ROHC_LIST_DEFAULT_L 5U
79 
80 
81 /** Print a warning trace for the given compression context */
82 #define rohc_comp_warn(context, format, ...) \
83  rohc_warning((context)->compressor, ROHC_TRACE_COMP, \
84  (context)->profile->id, \
85  format, ##__VA_ARGS__)
86 
87 /** Print a debug trace for the given compression context */
88 #define rohc_comp_debug(context, format, ...) \
89  rohc_debug((context)->compressor, ROHC_TRACE_COMP, \
90  (context)->profile->id, \
91  format, ##__VA_ARGS__)
92 
93 /** Dump a buffer for the given compression context */
94 #define rohc_comp_dump_buf(context, descr, buf, buf_len) \
95  do { \
96  if(((context)->compressor->features & ROHC_COMP_FEATURE_DUMP_PACKETS) != 0) { \
97  rohc_dump_buf((context)->compressor->trace_callback, \
98  (context)->compressor->trace_callback_priv, \
99  ROHC_TRACE_COMP, ROHC_TRACE_DEBUG, \
100  descr, buf, buf_len); \
101  } \
102  } while(0)
103 
104 
105 /*
106  * Declare ROHC compression structures that are defined at the end of this
107  * file but used by other structures at the beginning of the file.
108  */
109 
110 struct rohc_comp_ctxt;
111 
112 
113 /*
114  * Definitions of ROHC compression structures
115  */
116 
117 
118 /**
119  * @brief The ROHC compressor
120  */
121 struct rohc_comp
122 {
123  /** The medium associated with the decompressor */
125 
126  /** Enabled/disabled features for the compressor */
128 
129  /** The array of compression contexts that use the compressor */
131  /** The number of compression contexts in use in the array */
133 
134  /** Which profiles are enabled and with one are not? */
136 
137 
138  /* CRC-related variables: */
139 
140  /** The table to enable fast CRC-3 computation */
141  uint8_t crc_table_3[256];
142  /** The table to enable fast CRC-7 computation */
143  uint8_t crc_table_7[256];
144  /** The table to enable fast CRC-8 computation */
145  uint8_t crc_table_8[256];
146 
147 
148  /* segment-related variables */
149 
150 /** The maximal value for MRRU */
151 #define ROHC_MAX_MRRU 65535
152  /** The remaining bytes of the Reconstructed Reception Unit (RRU) waiting
153  * to be split into segments */
154  uint8_t rru[ROHC_MAX_MRRU];
155  /** The offset of the remaining bytes in the RRU buffer */
156  size_t rru_off;
157  /** The number of the remaining bytes in the RRU buffer */
158  size_t rru_len;
159 
160 
161  /* variables related to RTP detection */
162 
163  /** The callback function used to detect RTP packet */
165  /** Pointer to an external memory area provided/used by the callback user */
166  void *rtp_private;
167 
168 
169  /* some statistics about the compression process: */
170 
171  /** The number of sent packets */
173  /** The size of all the received uncompressed IP packets */
175  /** The size of all the sent compressed ROHC packets */
177 
178  /** The last context used by the compressor */
180 
181 
182  /* random callback */
183 
184  /** The user-defined callback for random numbers */
186  /** Private data that will be given to the callback for random numbers */
188 
189 
190  /* user interaction variables: */
191 
192  /** The width of the W-LSB sliding window */
194  /** The maximal number of packets sent in > IR states (= FO and SO
195  * states) before changing back the state to IR (periodic refreshes) */
197  /** The maximal number of packets sent in > FO states (= SO state)
198  * before changing back the state to FO (periodic refreshes) */
200  /** Maximum Reconstructed Reception Unit */
201  size_t mrru;
202  /** The connection type (currently not used) */
204  /** The number of uncompressed transmissions for list compression (L) */
206 
207  /** The callback function used to manage traces */
209  /** The private context of the callback function used to manage traces */
211 };
212 
213 
214 /**
215  * @brief The ROHC compression profile
216  *
217  * The object defines a ROHC profile. Each field must be filled in
218  * for each new profile.
219  */
221 {
222  /** The profile ID as reserved by IANA */
224 
225  /**
226  * @brief The IP protocol ID used to find out which profile is able to
227  * compress an IP packet
228  */
229  const unsigned short protocol;
230 
231  /**
232  * @brief The handler used to create the profile-specific part of the
233  * compression context
234  */
235  bool (*create)(struct rohc_comp_ctxt *const context,
236  const struct net_pkt *const packet)
237  __attribute__((warn_unused_result, nonnull(1, 2)));
238 
239  /**
240  * @brief The handler used to destroy the profile-specific part of the
241  * compression context
242  */
243  void (*destroy)(struct rohc_comp_ctxt *const context)
244  __attribute__((nonnull(1)));
245 
246  /**
247  * @brief The handler used to check whether an uncompressed IP packet
248  * fits the current profile or not
249  */
250  bool (*check_profile)(const struct rohc_comp *const comp,
251  const struct net_pkt *const packet)
252  __attribute__((warn_unused_result, nonnull(1, 2)));
253 
254  /**
255  * @brief The handler used to check whether an uncompressed IP packet
256  * belongs to a context or not
257  */
258  bool (*check_context)(const struct rohc_comp_ctxt *const context,
259  const struct net_pkt *const packet)
260  __attribute__((warn_unused_result, nonnull(1, 2)));
261 
262  /**
263  * @brief The handler used to encode uncompressed IP packets
264  *
265  * @param context The compression context
266  * @param ip The IP packet to encode
267  * @param packet_size The length of the IP packet to encode
268  * @param rohc_pkt OUT: The ROHC packet
269  * @param rohc_pkt_max_len The maximum length of the ROHC packet
270  * @param packet_type OUT: The type of ROHC packet that is created
271  * @param payload_offset OUT: The offset for the payload in the IP packet
272  * @return The length of the ROHC packet if successful,
273  * -1 otherwise
274  */
275  int (*encode)(struct rohc_comp_ctxt *const context,
276  const struct net_pkt *const uncomp_pkt,
277  uint8_t *const rohc_pkt,
278  const size_t rohc_pkt_max_len,
279  rohc_packet_t *const packet_type,
280  size_t *const payload_offset)
281  __attribute__((warn_unused_result, nonnull(1, 2, 3, 5, 6)));
282 
283  /**
284  * @brief The handler used to re-initialize a context
285  */
286  bool (*reinit_context)(struct rohc_comp_ctxt *const context)
287  __attribute__((nonnull(1), warn_unused_result));
288 
289  /**
290  * @brief The handler used to warn the profile-specific part of the
291  * context about the arrival of feedback data
292  */
293  bool (*feedback)(struct rohc_comp_ctxt *const context,
294  const enum rohc_feedback_type feedback_type,
295  const uint8_t *const packet,
296  const size_t packet_len,
297  const uint8_t *const feedback_data,
298  const size_t feedback_data_len)
299  __attribute__((warn_unused_result, nonnull(1, 3, 5)));
300 };
301 
302 
303 /**
304  * @brief The ROHC compression context
305  */
307 {
308  /** Whether the context is in use or not */
309  int used;
310  /** The time when the context was created (in seconds) */
311  uint64_t latest_used;
312  /** The time when the context was last used (in seconds) */
313  uint64_t first_used;
314 
315  /** The context unique ID (CID) */
317 
318  /** The key to help finding the context associated with a packet */
319  rohc_ctxt_key_t key; /* may not be unique */
320 
321  /** The associated compressor */
323 
324  /** The associated profile */
325  const struct rohc_comp_profile *profile;
326  /** Profile-specific data, defined by the profiles */
327  void *specific;
328 
329  /** The operation mode in which the context operates among:
330  * ROHC_U_MODE, ROHC_O_MODE, ROHC_R_MODE */
332  /** The operation state in which the context operates: IR, FO, SO */
334 
335  /* below are some statistics */
336 
337  /* The type of ROHC packet created for the last compressed packet */
339 
340  /** The number of packets sent while in Initialization & Refresh (IR) state */
341  size_t ir_count;
342  /** The number of packets sent while in First Order (FO) state */
343  size_t fo_count;
344  /** The number of packets sent while in Second Order (SO) state */
345  size_t so_count;
346 
347  /**
348  * @brief The number of packet sent while in SO state, used for the periodic
349  * refreshes of the context
350  * @see rohc_comp_periodic_down_transition
351  */
353  /**
354  * @brief The number of packet sent while in FO or SO state, used for the
355  * periodic refreshes of the context
356  * @see rohc_comp_periodic_down_transition
357  */
359 
360  /** The average size of the uncompressed packets */
362  /** The average size of the compressed packets */
364  /** The average size of the uncompressed headers */
366  /** The average size of the compressed headers */
368 
369  /** The total size of the last uncompressed packet */
371  /** The total size of the last compressed packet */
373  /** The header size of the last uncompressed packet */
375  /** The header size of the last compressed packet */
377 
378  /** The number of sent packets */
380 };
381 
382 
383 void rohc_comp_change_mode(struct rohc_comp_ctxt *const context,
384  const rohc_mode_t new_mode)
385  __attribute__((nonnull(1)));
386 
387 void rohc_comp_change_state(struct rohc_comp_ctxt *const context,
388  const rohc_comp_state_t new_state)
389  __attribute__((nonnull(1)));
390 
391 void rohc_comp_periodic_down_transition(struct rohc_comp_ctxt *const context)
392  __attribute__((nonnull(1)));
393 
394 bool rohc_comp_reinit_context(struct rohc_comp_ctxt *const context)
395  __attribute__((warn_unused_result, nonnull(1)));
396 
397 bool rohc_comp_feedback_parse_opts(const struct rohc_comp_ctxt *const context,
398  const uint8_t *const packet,
399  const size_t packet_len,
400  const uint8_t *const feedback_data,
401  const size_t feedback_data_len,
402  size_t opts_present[ROHC_FEEDBACK_OPT_MAX],
403  uint32_t *const sn_bits,
404  size_t *const sn_bits_nr,
405  uint8_t crc_in_packet,
406  size_t crc_pos_from_end)
407  __attribute__((warn_unused_result, nonnull(1, 2, 4, 6, 7, 8)));
408 
409 #endif
410 
int total_last_uncompressed_size
Definition: rohc_comp_internals.h:370
int(* rohc_comp_random_cb_t)(const struct rohc_comp *const comp, void *const user_context)
The prototype of the callback for random numbers.
Definition: rohc_comp.h:288
void(* destroy)(struct rohc_comp_ctxt *const context)
The handler used to destroy the profile-specific part of the compression context. ...
Definition: rohc_comp_internals.h:243
size_t periodic_refreshes_ir_timeout
Definition: rohc_comp_internals.h:196
rohc_ctxt_key_t key
Definition: rohc_comp_internals.h:319
struct rohc_comp_ctxt * contexts
Definition: rohc_comp_internals.h:130
void * random_cb_ctxt
Definition: rohc_comp_internals.h:187
size_t rohc_cid_t
Definition: rohc.h:195
int total_compressed_size
Definition: rohc_comp_internals.h:176
rohc_comp_features_t features
Definition: rohc_comp_internals.h:127
rohc_cid_t cid
Definition: rohc_comp_internals.h:316
rohc_mode_t
ROHC operation modes.
Definition: rohc.h:111
int connection_type
Definition: rohc_comp_internals.h:203
int header_last_uncompressed_size
Definition: rohc_comp_internals.h:374
int header_uncompressed_size
Definition: rohc_comp_internals.h:365
bool rohc_comp_reinit_context(struct rohc_comp_ctxt *const context)
Re-initialize the given context.
Definition: rohc_comp.c:2694
uint8_t crc_table_7[256]
Definition: rohc_comp_internals.h:143
void rohc_comp_change_mode(struct rohc_comp_ctxt *const context, const rohc_mode_t new_mode)
Change the mode of the context.
Definition: rohc_comp.c:2585
ROHC compression routines.
const unsigned short protocol
The IP protocol ID used to find out which profile is able to compress an IP packet.
Definition: rohc_comp_internals.h:229
The ROHC compressor.
Definition: rohc_comp_internals.h:121
int num_sent_packets
Definition: rohc_comp_internals.h:379
size_t num_contexts_used
Definition: rohc_comp_internals.h:132
rohc_comp_random_cb_t random_cb
Definition: rohc_comp_internals.h:185
uint64_t latest_used
Definition: rohc_comp_internals.h:311
struct rohc_comp * compressor
Definition: rohc_comp_internals.h:322
Network packet (may contains several IP headers)
struct rohc_comp_ctxt * last_context
Definition: rohc_comp_internals.h:179
void * trace_callback_priv
Definition: rohc_comp_internals.h:210
void(* rohc_trace_callback2_t)(void *const priv_ctxt, const rohc_trace_level_t level, const rohc_trace_entity_t entity, const int profile, const char *const format,...)
The function prototype for the trace callback.
Definition: rohc_traces.h:118
bool rohc_comp_feedback_parse_opts(const struct rohc_comp_ctxt *const context, const uint8_t *const packet, const size_t packet_len, const uint8_t *const feedback_data, const size_t feedback_data_len, size_t opts_present[ROHC_FEEDBACK_OPT_MAX], uint32_t *const sn_bits, size_t *const sn_bits_nr, uint8_t crc_in_packet, size_t crc_pos_from_end)
Parse FEEDBACK-2 options.
Definition: rohc_comp.c:2788
int total_compressed_size
Definition: rohc_comp_internals.h:363
bool(* feedback)(struct rohc_comp_ctxt *const context, const enum rohc_feedback_type feedback_type, const uint8_t *const packet, const size_t packet_len, const uint8_t *const feedback_data, const size_t feedback_data_len)
The handler used to warn the profile-specific part of the context about the arrival of feedback data...
Definition: rohc_comp_internals.h:293
Window-based Least Significant Bits (W-LSB) encoding.
size_t go_back_fo_count
The number of packet sent while in SO state, used for the periodic refreshes of the context...
Definition: rohc_comp_internals.h:352
The ROHC compression profile.
Definition: rohc_comp_internals.h:220
struct rohc_medium medium
Definition: rohc_comp_internals.h:124
int(* encode)(struct rohc_comp_ctxt *const context, const struct net_pkt *const uncomp_pkt, uint8_t *const rohc_pkt, const size_t rohc_pkt_max_len, rohc_packet_t *const packet_type, size_t *const payload_offset)
The handler used to encode uncompressed IP packets.
Definition: rohc_comp_internals.h:275
void rohc_comp_periodic_down_transition(struct rohc_comp_ctxt *const context)
Periodically change the context state after a certain number of packets.
Definition: rohc_comp.c:2647
rohc_rtp_detection_callback_t rtp_callback
Definition: rohc_comp_internals.h:164
size_t wlsb_window_width
Definition: rohc_comp_internals.h:193
uint32_t rohc_ctxt_key_t
Definition: net_pkt.h:35
bool(* rohc_rtp_detection_callback_t)(const unsigned char *const ip, const unsigned char *const udp, const unsigned char *const payload, const unsigned int payload_size, void *const rtp_private)
The prototype of the RTP detection callback.
Definition: rohc_comp.h:263
The ROHC compression context.
Definition: rohc_comp_internals.h:306
rohc_mode_t mode
Definition: rohc_comp_internals.h:331
const struct rohc_comp_profile * profile
Definition: rohc_comp_internals.h:325
int used
Definition: rohc_comp_internals.h:309
size_t rru_off
Definition: rohc_comp_internals.h:156
const rohc_profile_t id
Definition: rohc_comp_internals.h:223
void * specific
Definition: rohc_comp_internals.h:327
Definition: net_pkt.h:39
rohc_comp_state_t state
Definition: rohc_comp_internals.h:333
size_t rru_len
Definition: rohc_comp_internals.h:158
int total_uncompressed_size
Definition: rohc_comp_internals.h:174
size_t so_count
Definition: rohc_comp_internals.h:345
int total_last_compressed_size
Definition: rohc_comp_internals.h:372
bool(* reinit_context)(struct rohc_comp_ctxt *const context)
The handler used to re-initialize a context.
Definition: rohc_comp_internals.h:286
int total_uncompressed_size
Definition: rohc_comp_internals.h:361
bool(* check_context)(const struct rohc_comp_ctxt *const context, const struct net_pkt *const packet)
The handler used to check whether an uncompressed IP packet belongs to a context or not...
Definition: rohc_comp_internals.h:258
bool enabled_profiles[C_NUM_PROFILES]
Definition: rohc_comp_internals.h:135
#define C_NUM_PROFILES
Definition: rohc_comp_internals.h:50
uint8_t crc_table_3[256]
Definition: rohc_comp_internals.h:141
rohc_packet_t packet_type
Definition: rohc_comp_internals.h:338
size_t fo_count
Definition: rohc_comp_internals.h:343
uint64_t first_used
Definition: rohc_comp_internals.h:313
rohc_comp_features_t
The different features of the ROHC compressor.
Definition: rohc_comp.h:227
rohc_comp_state_t
The different ROHC compressor states.
Definition: rohc_comp.h:86
size_t ir_count
Definition: rohc_comp_internals.h:341
rohc_trace_callback2_t trace_callback
Definition: rohc_comp_internals.h:208
Definition of ROHC packets and extensions.
int header_compressed_size
Definition: rohc_comp_internals.h:367
bool(* create)(struct rohc_comp_ctxt *const context, const struct net_pkt *const packet)
The handler used to create the profile-specific part of the compression context.
Definition: rohc_comp_internals.h:235
void rohc_comp_change_state(struct rohc_comp_ctxt *const context, const rohc_comp_state_t new_state)
Change the state of the context.
Definition: rohc_comp.c:2621
int header_last_compressed_size
Definition: rohc_comp_internals.h:376
bool(* check_profile)(const struct rohc_comp *const comp, const struct net_pkt *const packet)
The handler used to check whether an uncompressed IP packet fits the current profile or not...
Definition: rohc_comp_internals.h:250
size_t list_trans_nr
Definition: rohc_comp_internals.h:205
void * rtp_private
Definition: rohc_comp_internals.h:166
size_t go_back_ir_count
The number of packet sent while in FO or SO state, used for the periodic refreshes of the context...
Definition: rohc_comp_internals.h:358
ROHC medium (CID characteristics)
Definition: rohc_internal.h:124
int num_packets
Definition: rohc_comp_internals.h:172
ROHC private common definitions and routines.
Definition: feedback.h:81
rohc_feedback_type
Definition: feedback.h:42
rohc_profile_t
The different ROHC compression/decompression profiles.
Definition: rohc.h:212
uint8_t crc_table_8[256]
Definition: rohc_comp_internals.h:145
uint8_t rru[ROHC_MAX_MRRU]
Definition: rohc_comp_internals.h:154
size_t periodic_refreshes_fo_timeout
Definition: rohc_comp_internals.h:199
rohc_packet_t
The different types of ROHC packets.
Definition: rohc_packets.h:49
size_t mrru
Definition: rohc_comp_internals.h:201
#define ROHC_MAX_MRRU
Definition: rohc_comp_internals.h:151
ROHC feedback definitions and formats.
Internal ROHC macros and functions for traces.