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 <stddef.h>
#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