diff options
Diffstat (limited to 'Radio/HW/BladeRF/include/device_calibration.h')
-rw-r--r-- | Radio/HW/BladeRF/include/device_calibration.h | 128 |
1 files changed, 128 insertions, 0 deletions
diff --git a/Radio/HW/BladeRF/include/device_calibration.h b/Radio/HW/BladeRF/include/device_calibration.h new file mode 100644 index 0000000..61cdd8a --- /dev/null +++ b/Radio/HW/BladeRF/include/device_calibration.h @@ -0,0 +1,128 @@ +/* + * This file is part of the bladeRF project: + * http://www.github.com/nuand/bladeRF + * + * Copyright (C) 2023 Nuand LLC + * + * This library is free software; you can redistribute it and/or + * modify it under the terms of the GNU Lesser General Public + * License as published by the Free Software Foundation; either + * version 2.1 of the License, or (at your option) any later version. + * + * This library is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + * Lesser General Public License for more details. + * + * You should have received a copy of the GNU Lesser General Public + * License along with this library; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +#ifndef BLADERF2_CALIBRATION_H_ +#define BLADERF2_CALIBRATION_H_ + +#include <stdint.h> +#include "libbladeRF.h" + +/** + * @brief Converts gain calibration CSV data to a binary format. + * + * This function reads frequency and gain data from a CSV file and writes it + * to a binary file. + * + * @param csv_path Path to the input CSV file. + * @param binary_path Path to the output binary file. + * @param ch bladeRF channel + * @return 0 on success, BLADERF_ERR_* code on failure. + */ +int gain_cal_csv_to_bin(struct bladerf *dev, const char *csv_path, const char *binary_path, bladerf_channel ch); + +/** + * @brief Loads gain calibration data from a binary file into a bladeRF device. + * + * This function reads frequency and gain calibration data from a binary file and + * loads it into the specified bladeRF device. + * + * @param dev Pointer to the bladeRF device structure. + * @param ch Channel for which the gain calibration data is loaded. + * @param binary_path Path to the binary file containing frequency-gain data. + * @return 0 on success, BLADERF_ERR_* code on failure. + */ +int load_gain_calibration(struct bladerf *dev, bladerf_channel ch, const char *binary_path); + +/** + * @brief Retrieve the gain correction gain delta between the current frequency and the target frequency. + * + * This function determines the gain correction difference between two frequencies, + * using the calibration table associated with the specified channel. + * The result is based on the gain correction values retrieved from the calibration table entries. + * + * @param dev Pointer to the bladeRF device structure. + * @param freq The target frequency for which the gain correction gain is to be determined. + * @param ch The bladeRF channel to use when fetching the gain calibration table. + * @param compensated_gain The gain correction result + * + * @return 0 on success, BLADERF_ERR_* code on failure. + */ +int get_gain_correction(struct bladerf *dev, + bladerf_frequency freq, + bladerf_channel ch, + bladerf_gain *compensated_gain); + + +/** + * Retrieves a gain calibration entry for a specified frequency by interpolating + * between the nearest lower and higher frequency calibration entries in the given + * calibration table. + * + * @param[in] tbl Pointer to the gain calibration table containing pre-calculated + * gain correction values across various frequencies. + * @param[in] freq The frequency for which the gain calibration entry is requested. + * @param[out] result Pointer to a `struct bladerf_gain_cal_entry` that will be filled + * with the interpolated gain calibration entry for the specified frequency. + * This structure must be allocated by the caller. + * + * The function first identifies the calibration entries immediately below and above the + * requested frequency. If the requested frequency matches a calibration point exactly, + * that entry is directly copied into `result`. If the requested frequency falls between + * two calibration points, a linear interpolation is performed to compute the gain + * correction value for the requested frequency, and the result is stored in `result`. + * + * @note This function assumes that the calibration table is sorted by frequency. + * + * @return 0 on success, indicating that `result` has been populated with the interpolated + * gain correction value. If the function fails, a negative error code is returned: + * - BLADERF_ERR_INVAL if the `result` pointer is NULL, + * - BLADERF_ERR_UNEXPECTED if suitable floor and ceiling entries cannot be found + * in the calibration table. + */ +int get_gain_cal_entry(const struct bladerf_gain_cal_tbl *tbl, + bladerf_frequency freq, + struct bladerf_gain_cal_entry *result); + +/** + * Applies compensated gain given the current gain target and center frequency + * + * @param dev The bladeRF device structure pointer. + * @param ch The bladeRF channel to use. + * @param frequency The target frequency. + */ +int apply_gain_correction(struct bladerf *dev, bladerf_channel ch, bladerf_frequency frequency); + +/** + * @brief Frees the resources of a gain calibration table and resets its fields. + * + * This function frees the dynamically allocated memory for the 'entries' and 'file_path' + * fields of the bladerf_gain_cal_tbl structure. After freeing these resources, it resets all fields + * of the structure to their default values, ensuring the structure is clean and can be + * reused or safely deallocated. The function logs a verbose message upon starting the + * freeing process. + * + * @param tbl Pointer to the bladerf_gain_cal_tbl structure. If this pointer is NULL, + * the function returns immediately without performing any operations. + * It is assumed that the caller ensures the validity of this pointer. + */ +void gain_cal_tbl_free(struct bladerf_gain_cal_tbl *tbl); + +#endif |