Loading...
Searching...
No Matches
database.hpp
Go to the documentation of this file.
//
// Copyright 2020 Ettus Research, a National Instruments Brand
//
// SPDX-License-Identifier: GPL-3.0-or-later
//
#pragma once
#include <uhd/config.hpp>
#include <cstdint>
#include <functional>
#include <string>
#include <vector>
namespace uhd { namespace usrp { namespace cal {
//
// This enum lists the sources in reverse order of priority, i.e., user-provided
// data has the highest priority, and hard-coded data from the resource compiler
// has the lowest priority.
enum class source {
NONE,
ANY,
RC,
FLASH,
FILESYSTEM,
USER
};
class UHD_API database
{
public:
//
// Note: the \p source_type parameter can be used to specify where to read
// cal data from. However, this class only has
// access to RC and FILESYSTEM type cal data. ANY
// will pick FILESYSTEM data if both are available,
// and RC data if only RC data is available.
// \param key The calibration type key (e.g., "rx_iq")
// \param serial The serial number of the device this data is for. See also
// \ref cal_db_serial
// \param source_type Where to read the calibration data from. See comments
// above. For anything other than RC, FILESYSTEM, or ANY,
// this will always throw a uhd::key_error because this
// class does not have access to user data or EEPROM data.
//
// \throws uhd::key_error if no calibration data is found matching the source
// type.
static std::vector<uint8_t> read_cal_data(const std::string& key,
const std::string& serial,
const source source_type = source::ANY);
//
// This can be called before calling read_cal_data() to avoid having to
// catch an exception. If \p source_type is FILESYSTEM, then it will only
// return true if a file is found with the appropriate cal data. The same
// is true for RC. If \p is ANY, then having either RC or FILESYSTEM data
// will yield true.
//
// \param key The calibration type key (e.g., "rx_iq")
// \param serial The serial number of the device this data is for. See also
// \ref cal_db_serial
// \param source_type Where to read the calibration data from. For anything
// other than RC, FILESYSTEM, or ANY, this will always
// return false because this class does not have access
// to user data or EEPROM data.
// \return true if calibration data is available that matches this key/serial
// pair.
static bool has_cal_data(const std::string& key,
const std::string& serial,
const source source_type = source::ANY);
//
// This implies a source type of FILESYSTEM. Note that writing the data does
// not apply it to a currently running UHD session. Devices will typically
// load calibration data at initialization time, and thus this call will
// take effect only for future UHD sessions.
//
// If calibration data for this key/serial pair already exists in the
// database, the original data will be backed up by renaming the original
// file from `filename.cal` to `filename.cal.$TIMESTAMP`. Alternatively, a
// custom extension can be chosen instead of `$TIMESTAMP`.
//
// \param key The calibration type key (e.g., "rx_iq")
// \param serial The serial number of the device this data is for. See also
// \ref cal_db_serial
// \param cal_data The calibration data to be written
// \param backup_ext A custom extension for backing up calibration data. If
// left empty, a POSIX timestamp is used.
static void write_cal_data(const std::string& key,
const std::string& serial,
const std::vector<uint8_t>& cal_data,
const std::string& backup_ext = "");
using has_data_fn_type = std::function<bool(const std::string&, const std::string&)>;
//
// These functions should throw a uhd::runtime_error if called with invalid
// key/serial pairs, although database will internally always call the
// corresponding 'has' function before calling this.
using get_data_fn_type =
std::function<std::vector<uint8_t>(const std::string&, const std::string&)>;
//
// \param has_cal_data A function object to a function that returns true if
// cal data is available
// \param get_cal_data A function object to a function that returns serialized
// cal data
// \param source_type Reserved. Must be source::FLASH.
static void register_lookup(has_data_fn_type has_cal_data,
get_data_fn_type get_cal_data,
const source source_type = source::FLASH);
};
}}} // namespace uhd::usrp::cal
uhd::usrp::cal::database
Definition database.hpp:67
uhd::usrp::cal::database::get_data_fn_type
std::function< std::vector< uint8_t >(const std::string &, const std::string &)> get_data_fn_type
Function type to return serialized cal data key and serial.
Definition database.hpp:142
uhd::usrp::cal::database::register_lookup
static void register_lookup(has_data_fn_type has_cal_data, get_data_fn_type get_cal_data, const source source_type=source::FLASH)
Register a lookup function for cal data.
uhd::usrp::cal::database::has_cal_data
static bool has_cal_data(const std::string &key, const std::string &serial, const source source_type=source::ANY)
Check if calibration data exists for a given source type.
uhd::usrp::cal::database::read_cal_data
static std::vector< uint8_t > read_cal_data(const std::string &key, const std::string &serial, const source source_type=source::ANY)
Return a calibration data set as a serialized string.
uhd::usrp::cal::database::has_data_fn_type
std::function< bool(const std::string &, const std::string &)> has_data_fn_type
Function type to look up if there is cal data given a key and serial.
Definition database.hpp:135
uhd::usrp::cal::database::write_cal_data
static void write_cal_data(const std::string &key, const std::string &serial, const std::vector< uint8_t > &cal_data, const std::string &backup_ext="")
Store calibration data to the local filesystem database.
UHD_API
#define UHD_API
Definition config.h:87
config.hpp
uhd::usrp::cal
Definition container.hpp:15
uhd::usrp::cal::source
source
Identify the source of calibration data, i.e., where was it stored.
Definition database.hpp:22
uhd::usrp::cal::source::FLASH
@ FLASH
Stored on device flash memory, e.g. EEPROM.
Definition database.hpp:26
uhd::usrp::cal::source::USER
@ USER
Provided by the user.
Definition database.hpp:28
uhd::usrp::cal::source::RC
@ RC
Internal Resource Compiler (i.e., hard-coded within UHD).
Definition database.hpp:25
uhd::usrp::cal::source::FILESYSTEM
@ FILESYSTEM
Stored on the local filesystem.
Definition database.hpp:27
uhd::usrp::cal::source::ANY
@ ANY
Undefined source.
Definition database.hpp:24
uhd::usrp::cal::source::NONE
@ NONE
No calibration data available.
Definition database.hpp:23
uhd::usrp
Definition container.hpp:15
uhd
Definition build_info.hpp:12