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