Data Structures
struct	pg2sdr_gain_table_t
	Gain table entry. More...

Functions
int	pg2sdr_set_gain_tables (pg2sdr_device dev, const pg2sdr_gain_table_t gain_table, size_t gain_table_size, const double lna_table, const double mix_table, const double *vga_table)
	Set the gain tables used for the dB-based gain API.

int	pg2sdr_get_gain_tables (pg2sdr_device dev, pg2sdr_gain_table_t gain_table, size_t gain_table_size, double lna_table, double mix_table, double *vga_table)
	Get the current gain tables used for the dB-based gain API.

Detailed Description

The gain control APIs rely on a set of four precalculated gain tables which map gain values in dB to hardware settings.

libpg2sdr provides built-in defaults for these tables which reflect gain values measured during hardware development and should be okay for most uses. Advanced users can provide their own tables by calling pg2sdr_set_gain_tables().

There are three stage-specific gain tables:

LNA gain table: 16-entry array of doubles, mapping LNA gain steps to a gain in dB
MIX gain table: 16-entry array of doubles, mapping MIX gain steps to a gain in dB
VGA gain table: 16-entry array of doubles, mapping VGA gain steps to a gain in dB

The stage-specific tables are always exactly 16 entries long, with entry [i] containing the gain in dB for a hardware step of "i".

There is also one total gain table, which maps a total gain value to an appropriate combination of hardware settings for all three stages. This table is a variable length array of pg2sdr_gain_table_t structs.

Function Documentation

◆ pg2sdr_get_gain_tables()

int pg2sdr_get_gain_tables	(	pg2sdr_device *	dev,
		pg2sdr_gain_table_t **	gain_table,
		size_t *	gain_table_size,
		double *	lna_table,
		double *	mix_table,
		double *	vga_table
	)

Get the current gain tables used for the dB-based gain API.

Creates and returns copies of the currently used gain tables. These copies are a snapshot as at the time of the call, and will not reflect future changes to the gain tables.

If gain_table is not NULL, a copy of the current total-gain table will be allocated and returned via gain_table. It is the caller's responsibility to free this array via free() when done. The returned gain table will be sorted by increasing total_gain.

If lna_table, mix_table, or vga_table are not NULL, they should point to caller-managed memory with space for at least 16 entries. The current per-stage gain table will be copied there.

Parameters

[in]	dev	the device to query
[out]	gain_table	if not NULL, storage for a pointer to a copy of the total gain table
[out]	gain_table_size	if not NULL, stores the length of the array stored in `gain_table`
[out]	lna_table	if not NULL, points to a 16-entry array that will be filled with the LNA gain table
[out]	mix_table	if not NULL, points to a 16-entry array that will be filled with the MIX gain table
[out]	vga_table	if not NULL, points to a 16-entry array that will be filled with the VGA gain table

Return values

PG2SDR_SUCCESS	success
PG2SDR_ERROR_BAD_ARGUMENT	if all of `gain_table`, `lna_table`, `mix_table`, `vga_table` are NULL, or `gain_table` is NULL but `gain_table_size` is not NULL (or vice versa)
<0	negative error code on failure

◆ pg2sdr_set_gain_tables()

int pg2sdr_set_gain_tables	(	pg2sdr_device *	dev,
		const pg2sdr_gain_table_t *	gain_table,
		size_t	gain_table_size,
		const double *	lna_table,
		const double *	mix_table,
		const double *	vga_table
	)

Set the gain tables used for the dB-based gain API.

Update one or more of the internal gain tables. Gain tables are device-specific.

This can be called at any time, but changes to the gain table do not retrospectively affect gain settings (the hardware settings are not modified if the gain table is changed).

Not all gain tables need to be updated at once, pass NULL for tables to leave unchanged.

A copy of the tables is made at the point when pg2sdr_set_gain_tables() is called; ownership of provided tables (and responsibility for freeing any allocated memory) stays with the caller.

lna_table, mix_table, and vga_table, if provided, must be exactly 16 entries long.

gain_table, if provided, must be exactly gain_table_size entries long. It may be unsorted, and must have at least one entry.