spandsp  3.0.0
agc_float.h
Go to the documentation of this file.
1 /*
2  * SpanDSP - a series of DSP components for telephony
3  *
4  * agcf.h - Floating point automatic gain contro for modems.
5  *
6  * Written by Steve Underwood <steveu@coppice.org>
7  *
8  * Copyright (C) 2024 Steve Underwood
9  *
10  * All rights reserved.
11  *
12  * This program is free software; you can redistribute it and/or modify
13  * it under the terms of the GNU Lesser General Public License version 2.1,
14  * as published by the Free Software Foundation.
15  *
16  * This program is distributed in the hope that it will be useful,
17  * but WITHOUT ANY WARRANTY; without even the implied warranty of
18  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
19  * GNU Lesser General Public License for more details.
20  *
21  * You should have received a copy of the GNU Lesser General Public
22  * License along with this program; if not, write to the Free Software
23  * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
24  */
25 
26 /*! \file */
27 
28 #if !defined(_SPANDSP_AGCF_H_)
29 #define _SPANDSP_AGCF_H_
30 
31 typedef struct agcf_state_s agcf_state_t;
32 
33 typedef struct agcf_descriptor_s
34 {
35  float signal_on_power_threshold;
36  float signal_off_power_threshold;
37  float signal_target_power;
38  /* A persistence check on a signal appearing. */
39  int16_t signal_on_persistence_check;
40  /* A persistence check on a signal disappearing. */
41  int16_t signal_off_persistence_check;
42  /* A long persistence check on a signal disappearing. That is
43  something that will ride over blips in the signal. */
44  int16_t signal_down_persistence_check;
46 
47 #define AGC_SAMPLES_PER_CHUNK 40
48 
49 #if defined(__cplusplus)
50 extern "C"
51 {
52 #endif
53 
54 /*! \brief Create an AGC descriptor
55  \param s The AGC context.
56  \param signal_target_power The power to normalize to, in dBm0.
57  \param signal_on_power_threshold The minimum power to declare signal on, in dBm0.
58  \param signal_off_power_threshold The maximum power to declare signal off, in dBm0.
59  \param signal_on_persistence_check Persistence check count for signal on.
60  \param signal_off_persistence_check Persistence check count for signal off.
61  \return A pointer to the initialised context, or NULL if there was a problem. */
63  float signal_target_power,
64  float signal_on_power_threshold,
65  float signal_off_power_threshold,
66  int signal_on_persistence_check,
67  int signal_off_persistence_check);
68 
69 SPAN_DECLARE(int) agcf_free_descriptor(agcf_descriptor_t *s);
70 
71 /*! Process a block of received samples.
72  \brief Process a block of received samples.
73  \param out The output buffer for the scaled samples.
74  \param in The input buffer for the samples.
75  \param len The length of the in and out buffers.
76  \return True if a signal is present. */
77 SPAN_DECLARE(bool) agcf_rx(agcf_state_t *s, float out[], const float in[], int len);
78 
79 /*! Process a block of received samples.
80  \brief Process a block of received samples.
81  \param out The output buffer for the scaled samples.
82  \param in The input buffer for the samples.
83  \param len The length of the in and out buffers.
84  \return True if a signal is present. */
85 SPAN_DECLARE(bool) agcf_from_int16_rx(agcf_state_t *s, float out[], const int16_t in[], int len);
86 
87 SPAN_DECLARE(float) agcf_current_power_dbm0(agcf_state_t *s);
88 
89 /*! Get the current scaling. */
90 SPAN_DECLARE(float) agcf_get_scaling(agcf_state_t *s);
91 
92 /*! Set the scaling, instead of adapting it. This allows a known good scaling factor
93  to be resused within a session. */
94 SPAN_DECLARE(void) agcf_set_scaling(agcf_state_t *s, float scaling);
95 
96 /*! Enable or disable AGC adpation. */
97 SPAN_DECLARE(void) agcf_set_adaption(agcf_state_t *s, bool adapt);
98 
99 /*! Get the logging context associated with an AGC context.
100  \brief Get the logging context associated with an AGC context.
101  \param s The AGC context.
102  \return A pointer to the logging context */
104 
105 /*! \brief Initialise an AGC context.
106  \param s The AGC context.
107  \param desc
108  \return A pointer to the initialised context, or NULL if there was a problem.
109 */
110 SPAN_DECLARE(agcf_state_t *) agcf_init(agcf_state_t *s, const agcf_descriptor_t *desc);
111 
112 /*! \brief Release an AGC receive context.
113  \param s The ADSI receive context.
114  \return 0 for OK.
115 */
116 SPAN_DECLARE(int) agcf_release(agcf_state_t *s);
117 
118 /*! \brief Free the resources of an ADSI receive context.
119  \param s The ADSI receive context.
120  \return 0 for OK.
121 */
122 SPAN_DECLARE(int) agcf_free(agcf_state_t *s);
123 
124 #if defined(__cplusplus)
125 }
126 #endif
127 
128 #endif
129 /*- End of file ------------------------------------------------------------*/
void agcf_set_scaling(agcf_state_t *s, float scaling)
Definition: agc_float.c:253
logging_state_t * agcf_get_logging_state(agcf_state_t *s)
Get the logging context associated with an AGC context.
Definition: agc_float.c:271
Definition: agc_float.h:33
float agcf_get_scaling(agcf_state_t *s)
Definition: agc_float.c:247
bool agcf_from_int16_rx(agcf_state_t *s, float out[], const int16_t in[], int len)
Process a block of received samples.
Definition: agc_float.c:85
int agcf_release(agcf_state_t *s)
Release an AGC receive context.
Definition: agc_float.c:301
agcf_state_t * agcf_init(agcf_state_t *s, const agcf_descriptor_t *desc)
Initialise an AGC context.
Definition: agc_float.c:279
int agcf_free(agcf_state_t *s)
Free the resources of an ADSI receive context.
Definition: agc_float.c:307
agcf_descriptor_t * agcf_make_descriptor(agcf_descriptor_t *s, float signal_target_power, float signal_on_power_threshold, float signal_off_power_threshold, int signal_on_persistence_check, int signal_off_persistence_check)
Create an AGC descriptor.
Definition: agc_float.c:50
Definition: private/agc_float.h:31
Definition: private/logging.h:33
void agcf_set_adaption(agcf_state_t *s, bool adapt)
Definition: agc_float.c:265
bool agcf_rx(agcf_state_t *s, float out[], const float in[], int len)
Process a block of received samples.
Definition: agc_float.c:166