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
31typedef struct agcf_state_s agcf_state_t;
32
33typedef 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;
45} agcf_descriptor_t;
46
47#define AGC_SAMPLES_PER_CHUNK 40
48
49#if defined(__cplusplus)
50extern "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. */
62SPAN_DECLARE(agcf_descriptor_t *) agcf_make_descriptor(agcf_descriptor_t *s,
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
69SPAN_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. */
77SPAN_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. */
85SPAN_DECLARE(bool) agcf_from_int16_rx(agcf_state_t *s, float out[], const int16_t in[], int len);
86
87SPAN_DECLARE(float) agcf_current_power_dbm0(agcf_state_t *s);
88
89/*! Get the current scaling. */
90SPAN_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. */
94SPAN_DECLARE(void) agcf_set_scaling(agcf_state_t *s, float scaling);
95
96/*! Enable or disable AGC adpation. */
97SPAN_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 */
103SPAN_DECLARE(logging_state_t *) agcf_get_logging_state(agcf_state_t *s);
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*/
110SPAN_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*/
116SPAN_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*/
122SPAN_DECLARE(int) agcf_free(agcf_state_t *s);
123
124#if defined(__cplusplus)
125}
126#endif
127
128#endif
129/*- End of file ------------------------------------------------------------*/
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
float agcf_get_scaling(agcf_state_t *s)
Definition agc_float.c:247
void agcf_set_adaption(agcf_state_t *s, bool adapt)
Definition agc_float.c:265
int agcf_release(agcf_state_t *s)
Release an AGC receive context.
Definition agc_float.c:301
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
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
int agcf_free(agcf_state_t *s)
Free the resources of an ADSI receive context.
Definition agc_float.c:307
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
void agcf_set_scaling(agcf_state_t *s, float scaling)
Definition agc_float.c:253
agcf_state_t * agcf_init(agcf_state_t *s, const agcf_descriptor_t *desc)
Initialise an AGC context.
Definition agc_float.c:279
struct logging_state_s logging_state_t
Definition logging.h:72
Definition agc_float.h:34
Definition private/agc_float.h:32