# HG changeset patch
# User Mychaela Falconia <falcon@freecalypso.org>
# Date 1727943761 0
# Node ID bd32bb1e8dabeea0c53974484433e42bb2fe61e0
# Parent  53d3f48af107368ef01de2e16342b5a9f1c6280e
doc/EFR-library-API: document malloc-alternative provision

diff -r 53d3f48af107 -r bd32bb1e8dab doc/EFR-library-API
--- a/doc/EFR-library-API	Sun Sep 29 02:41:28 2024 +0000
+++ b/doc/EFR-library-API	Thu Oct 03 08:22:41 2024 +0000
@@ -22,11 +22,12 @@
 struct EFR_encoder_state and struct EFR_decoder_state are opaque structures to
 library users: you only get pointers which you remember and pass around, but
 <gsm_efr.h> does not give you full definitions of these structs.  As a library
-user, you don't even get to know the size of these structs, hence the necessary
-malloc() operation happens inside EFR_encoder_create() and EFR_decoder_create().
-However, each structure is malloc'ed as a single chunk, hence when you are done
-with it, simply call free() to relinquish each encoder or decoder state
-instance.
+user, you ordinarily don't even need to know the size of these structs, hence
+the necessary malloc() operation happens inside EFR_encoder_create() and
+EFR_decoder_create().  (But see a later section of this document regarding
+alternative memory allocation schemes.)  However, each structure is malloc'ed
+as a single chunk, hence when you are done with it, simply call free() to
+relinquish each encoder or decoder state instance.
 
 EFR_encoder_create() and EFR_decoder_create() functions can fail if the malloc()
 call inside fails, in which case the two libgsmefr functions in question return
@@ -206,6 +207,28 @@
 this flag passed to EFR_encoder_reset() always takes effect.  There is no
 provision for changing this mode within an encoder session without a full reset.
 
+These reset functions may be used to implement an alternative memory allocation
+scheme, if there is a requirement or desire to use something other than plain
+malloc().  To make such alternative schemes possible, the following const
+"variables" are provided beginning with libgsmefr version 1.2.0:
+
+extern const unsigned EFR_encoder_state_size;
+extern const unsigned EFR_decoder_state_size;
+
+Using this feature, one can replace EFR_encoder_create() and
+EFR_decoder_create() with something like the following (example for
+applications based on Osmocom libraries):
+
+	struct EFR_encoder_state *enc_state;
+	enc_state = talloc_size(ctx, EFR_encoder_state_size);
+	if (enc_state)
+		EFR_encoder_reset(enc_state, dtx_flag);
+
+	struct EFR_decoder_state *dec_state;
+	dec_state = talloc_size(ctx, EFR_decoder_state_size);
+	if (dec_state)
+		EFR_decoder_reset(dec_state);
+
 Public const datum: decoder homing frame
 ========================================