FreeCalypso > hg > gsm-codec-lib

comparison doc/EFR-library-API @ 544:bd32bb1e8dab

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
doc/EFR-library-API: document malloc-alternative provision
author Mychaela Falconia <falcon@freecalypso.org>
date Thu, 03 Oct 2024 08:22:41 +0000
parents 2d46abdfbe91
children b07dba7b8a4f
comparison
equal deleted inserted replaced
543:53d3f48af107 544:bd32bb1e8dab
20 extern struct EFR_decoder_state *EFR_decoder_create(void); 20 extern struct EFR_decoder_state *EFR_decoder_create(void);
21 21
22 struct EFR_encoder_state and struct EFR_decoder_state are opaque structures to 22 struct EFR_encoder_state and struct EFR_decoder_state are opaque structures to
23 library users: you only get pointers which you remember and pass around, but 23 library users: you only get pointers which you remember and pass around, but
24 <gsm_efr.h> does not give you full definitions of these structs. As a library 24 <gsm_efr.h> does not give you full definitions of these structs. As a library
25 user, you don't even get to know the size of these structs, hence the necessary 25 user, you ordinarily don't even need to know the size of these structs, hence
26 malloc() operation happens inside EFR_encoder_create() and EFR_decoder_create(). 26 the necessary malloc() operation happens inside EFR_encoder_create() and
27 However, each structure is malloc'ed as a single chunk, hence when you are done 27 EFR_decoder_create(). (But see a later section of this document regarding
28 with it, simply call free() to relinquish each encoder or decoder state 28 alternative memory allocation schemes.) However, each structure is malloc'ed
29 instance. 29 as a single chunk, hence when you are done with it, simply call free() to
30 relinquish each encoder or decoder state instance.
30 31
31 EFR_encoder_create() and EFR_decoder_create() functions can fail if the malloc() 32 EFR_encoder_create() and EFR_decoder_create() functions can fail if the malloc()
32 call inside fails, in which case the two libgsmefr functions in question return 33 call inside fails, in which case the two libgsmefr functions in question return
33 NULL. 34 NULL.
34 35
204 If you call EFR_encoder_reset() manually, you can change the DTX enable/disable 205 If you call EFR_encoder_reset() manually, you can change the DTX enable/disable
205 flag from its initial value given to EFR_encoder_create() - the new value of 206 flag from its initial value given to EFR_encoder_create() - the new value of
206 this flag passed to EFR_encoder_reset() always takes effect. There is no 207 this flag passed to EFR_encoder_reset() always takes effect. There is no
207 provision for changing this mode within an encoder session without a full reset. 208 provision for changing this mode within an encoder session without a full reset.
208 209
210 These reset functions may be used to implement an alternative memory allocation
211 scheme, if there is a requirement or desire to use something other than plain
212 malloc(). To make such alternative schemes possible, the following const
213 "variables" are provided beginning with libgsmefr version 1.2.0:
214
215 extern const unsigned EFR_encoder_state_size;
216 extern const unsigned EFR_decoder_state_size;
217
218 Using this feature, one can replace EFR_encoder_create() and
219 EFR_decoder_create() with something like the following (example for
220 applications based on Osmocom libraries):
221
222 struct EFR_encoder_state *enc_state;
223 enc_state = talloc_size(ctx, EFR_encoder_state_size);
224 if (enc_state)
225 EFR_encoder_reset(enc_state, dtx_flag);
226
227 struct EFR_decoder_state *dec_state;
228 dec_state = talloc_size(ctx, EFR_decoder_state_size);
229 if (dec_state)
230 EFR_decoder_reset(dec_state);
231
209 Public const datum: decoder homing frame 232 Public const datum: decoder homing frame
210 ======================================== 233 ========================================
211 234
212 While the encoder homing frame is the same for all codecs defined by ETSI and 235 While the encoder homing frame is the same for all codecs defined by ETSI and
213 then later 3GPP, each codec has its own unique decoder homing frame (DHF). A 236 then later 3GPP, each codec has its own unique decoder homing frame (DHF). A