USRP Hardware Driver and USRP Manual Version: 4.1.0.3
UHD and USRP Manual
database.hpp
Go to the documentation of this file.
1//
2// Copyright 2020 Ettus Research, a National Instruments Brand
3//
4// SPDX-License-Identifier: GPL-3.0-or-later
5//
6
7#pragma once
8
9#include <uhd/config.hpp>
10#include <stddef.h>
11#include <string>
12#include <vector>
13#include <functional>
14
15namespace uhd { namespace usrp { namespace cal {
16
18//
19// This enum lists the sources in reverse order of priority, i.e., user-provided
20// data has the highest priority, and hard-coded data from the resource compiler
21// has the lowest priority.
22enum class source {
23 NONE,
24 ANY,
25 RC,
26 FLASH,
28 USER
29};
30
67{
68public:
70 //
71 // Note: the \p source_type parameter can be used to specify where to read
72 // cal data from. However, this class only has
73 // access to RC and FILESYSTEM type cal data. ANY
74 // will pick FILESYSTEM data if both are available,
75 // and RC data if only RC data is available.
76 // \param key The calibration type key (e.g., "rx_iq")
77 // \param serial The serial number of the device this data is for. See also
78 // \ref cal_db_serial
79 // \param source_type Where to read the calibration data from. See comments
80 // above. For anything other than RC, FILESYSTEM, or ANY,
81 // this will always throw a uhd::key_error because this
82 // class does not have access to user data or EEPROM data.
83 //
84 // \throws uhd::key_error if no calibration data is found matching the source
85 // type.
86 static std::vector<uint8_t> read_cal_data(const std::string& key,
87 const std::string& serial,
88 const source source_type = source::ANY);
89
91 //
92 // This can be called before calling read_cal_data() to avoid having to
93 // catch an exception. If \p source_type is FILESYSTEM, then it will only
94 // return true if a file is found with the appropriate cal data. The same
95 // is true for RC. If \p is ANY, then having either RC or FILESYSTEM data
96 // will yield true.
97 //
98 // \param key The calibration type key (e.g., "rx_iq")
99 // \param serial The serial number of the device this data is for. See also
100 // \ref cal_db_serial
101 // \param source_type Where to read the calibration data from. For anything
102 // other than RC, FILESYSTEM, or ANY, this will always
103 // return false because this class does not have access
104 // to user data or EEPROM data.
105 // \return true if calibration data is available that matches this key/serial
106 // pair.
107 static bool has_cal_data(const std::string& key,
108 const std::string& serial,
109 const source source_type = source::ANY);
110
112 //
113 // This implies a source type of FILESYSTEM. Note that writing the data does
114 // not apply it to a currently running UHD session. Devices will typically
115 // load calibration data at initialization time, and thus this call will
116 // take effect only for future UHD sessions.
117 //
118 // If calibration data for this key/serial pair already exists in the
119 // database, the original data will be backed up by renaming the original
120 // file from `filename.cal` to `filename.cal.$TIMESTAMP`. Alternatively, a
121 // custom extension can be chosen instead of `$TIMESTAMP`.
122 //
123 // \param key The calibration type key (e.g., "rx_iq")
124 // \param serial The serial number of the device this data is for. See also
125 // \ref cal_db_serial
126 // \param cal_data The calibration data to be written
127 // \param backup_ext A custom extension for backing up calibration data. If
128 // left empty, a POSIX timestamp is used.
129 static void write_cal_data(const std::string& key,
130 const std::string& serial,
131 const std::vector<uint8_t>& cal_data,
132 const std::string& backup_ext = "");
133
135 using has_data_fn_type = std::function<bool(const std::string&, const std::string&)>;
136
138 //
139 // These functions should throw a uhd::runtime_error if called with invalid
140 // key/serial pairs, although database will internally always call the
141 // corresponding 'has' function before calling this.
143 std::function<std::vector<uint8_t>(const std::string&, const std::string&)>;
144
146 //
147 // \param has_cal_data A function object to a function that returns true if
148 // cal data is available
149 // \param get_cal_data A function object to a function that returns serialized
150 // cal data
151 // \param source_type Reserved. Must be source::FLASH.
152 static void register_lookup(has_data_fn_type has_cal_data,
153 get_data_fn_type get_cal_data,
154 const source source_type = source::FLASH);
155};
156
157
158}}} // namespace uhd::usrp::cal
Definition: database.hpp:67
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.
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.
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.
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:143
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
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.
#define UHD_API
Definition: config.h:70
source
Identify the source of calibration data, i.e., where was it stored.
Definition: database.hpp:22
@ FLASH
Stored on device flash memory, e.g. EEPROM.
@ USER
Provided by the user.
@ RC
Internal Resource Compiler (i.e., hard-coded within UHD)
@ FILESYSTEM
Stored on the local filesystem.
@ ANY
Undefined source.
@ NONE
No calibration data available.
Definition: build_info.hpp:12