uhd: cal: Add database class

This class contains methods to store and retrieve data from the local
calibration database. Note that in this case, the "database" is just a
bunch of files on the local filesystem.

3 files changed, 152 insertions, 0 deletions

diff --git a/host/include/uhd/CMakeLists.txt b/host/include/uhd/CMakeLists.txt
index 429d4fe63..f6bdd2a8f 100644
--- a/host/include/uhd/CMakeLists.txt
+++ b/host/include/uhd/CMakeLists.txt
@@ -6,6 +6,7 @@
 # SPDX-License-Identifier: GPL-3.0-or-later
 #
 
+add_subdirectory(cal)
 add_subdirectory(rfnoc)
 add_subdirectory(transport)
 add_subdirectory(types)
diff --git a/host/include/uhd/cal/CMakeLists.txt b/host/include/uhd/cal/CMakeLists.txt
new file mode 100644
index 000000000..6c8355fec
--- /dev/null
+++ b/host/include/uhd/cal/CMakeLists.txt
@@ -0,0 +1,12 @@
+#
+# Copyright 2020 Ettus Research, a National Instruments Brand
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+#
+
+UHD_INSTALL(FILES
+    database.hpp
+    DESTINATION ${INCLUDE_DIR}/uhd/cal
+    COMPONENT headers
+)
+
diff --git a/host/include/uhd/cal/database.hpp b/host/include/uhd/cal/database.hpp
new file mode 100644
index 000000000..ca607de06
--- /dev/null
+++ b/host/include/uhd/cal/database.hpp
@@ -0,0 +1,139 @@
+//
+// Copyright 2020 Ettus Research, a National Instruments Brand
+//
+// SPDX-License-Identifier: GPL-3.0-or-later
+//
+
+#ifndef INCLUDED_LIBUHD_CAL_DATABASE_HPP
+#define INCLUDED_LIBUHD_CAL_DATABASE_HPP
+
+#include <uhd/config.hpp>
+#include <stddef.h>
+#include <string>
+#include <vector>
+
+namespace uhd { namespace usrp { namespace cal {
+
+//! Identify the source of calibration data, i.e., where was it stored
+//
+// 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, //!< No calibration data available
+    ANY, //!< Undefined source
+    RC, //!< Internal Resource Compiler (i.e., hard-coded within UHD)
+    FLASH, //!< Stored on device flash memory, e.g. EEPROM
+    FILESYSTEM, //!< Stored on the local filesystem
+    USER //!< Provided by the user
+};
+
+/*! Calibration Data Storage/Retrieval Class
+ *
+ * UHD can store calibration data on disk or compiled within UHD. This class
+ * provides access to both locations.
+ *
+ * \section cal_db_blob Format of binary data
+ *
+ * This class can read and write binary data, but it does not verify the data
+ * or expect any kind of format. It simply manages BLOBs (binary large objects).
+ * It is up to the consumers and producers of this data to agree on a format.
+ * Typically, since this class stores calibration data, it will be consuming
+ * data that was produced by uhd::usrp::cal::container::serialize().
+ *
+ * \section cal_db_serial Serial number and key
+ *
+ * Calibration data is indexed by two keys: An arbitrary key that describes the
+ * type of calibration data (e.g., "rx_iq") and a serial number. The serial
+ * number has to uniquely identify the device for which the calibration data was
+ * obtained. This can either be the serial number of the daughterboard (if the
+ * calibration data only relates to the daughterboard), the motherboard (for
+ * example, if there is no such thing as a daughterboard, or the data only
+ * relates to the motherboard), it can be combination of both daughterboard and
+ * motherboard serial (if the calibration data is only valid for a combination),
+ * or it can be a combination of a device serial number and a channel index
+ * (if a device with single serial has different channels that have separate
+ * characteristics).
+ *
+ * It is up to the individual device drivers which value they use for the serial
+ * numbers and keys.
+ *
+ * Note that the serial number is irrelevant when the data is pulled out of the
+ * resource compiler. By definition, it is not permitted to store data in the
+ * resource compiler that is specific to a certain serial number, only data that
+ * applies to an entire family of devices is permitted.
+ */
+class UHD_API database
+{
+public:
+
+    //! Return a calibration data set as a serialized string
+    //
+    // 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);
+
+    //! Check if calibration data exists for a given source type
+    //
+    // 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);
+
+    //! Store calibration data to the local filesystem database
+    //
+    // 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 = "");
+};
+
+
+}}} // namespace uhd::usrp::cal
+
+#endif /* INCLUDED_LIBUHD_CAL_DATABASE_HPP */