uhd: Add discoverable_features API

The "discoverable features" API handles how clients access the myriad
features we offer, without simply adding a million has_FOO and do_FOO
methods to radio_control and multi_usrp. discoverable_features allows
clients to query the existance of, enumerate, and ultimately they get
(by enum or by type) an object which implements their wanted feature.

4 files changed, 115 insertions, 0 deletions

diff --git a/host/include/uhd/CMakeLists.txt b/host/include/uhd/CMakeLists.txt
index f6bdd2a8f..cf3fa62de 100644
--- a/host/include/uhd/CMakeLists.txt
+++ b/host/include/uhd/CMakeLists.txt
@@ -7,6 +7,7 @@
 #
 
 add_subdirectory(cal)
+add_subdirectory(features)
 add_subdirectory(rfnoc)
 add_subdirectory(transport)
 add_subdirectory(types)
diff --git a/host/include/uhd/features/CMakeLists.txt b/host/include/uhd/features/CMakeLists.txt
new file mode 100644
index 000000000..efba46dc2
--- /dev/null
+++ b/host/include/uhd/features/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
+    discoverable_feature.hpp
+    discoverable_feature_getter.hpp
+    DESTINATION ${INCLUDE_DIR}/uhd/features
+    COMPONENT headers
+)
diff --git a/host/include/uhd/features/discoverable_feature.hpp b/host/include/uhd/features/discoverable_feature.hpp
new file mode 100644
index 000000000..dfb0ede5b
--- /dev/null
+++ b/host/include/uhd/features/discoverable_feature.hpp
@@ -0,0 +1,39 @@
+//
+// Copyright 2020 Ettus Research, a National Instruments Brand
+//
+// SPDX-License-Identifier: GPL-3.0-or-later
+//
+
+#pragma once
+
+#include <stddef.h>
+#include <memory>
+#include <string>
+
+namespace uhd { namespace features {
+
+/*!
+ * The base class for discoverable features
+ *
+ * All discoverable features inherit from this class, which provides some basic
+ * functionality for features.
+ *
+ * Also note that all discoverable features must implement a static method
+ * get_feature_id() which returns a feature_id_t.
+ */
+class discoverable_feature
+{
+public:
+    using sptr = std::shared_ptr<discoverable_feature>;
+    enum feature_id_t {
+        RESERVED0,
+        RESERVED1,
+    };
+
+    virtual ~discoverable_feature() = default;
+
+    //! Returns a human-readonable string name of this feature.
+    virtual std::string get_feature_name() const = 0;
+};
+
+}} // namespace uhd::features
diff --git a/host/include/uhd/features/discoverable_feature_getter_iface.hpp b/host/include/uhd/features/discoverable_feature_getter_iface.hpp
new file mode 100644
index 000000000..9c759759f
--- /dev/null
+++ b/host/include/uhd/features/discoverable_feature_getter_iface.hpp
@@ -0,0 +1,63 @@
+//
+// Copyright 2020 Ettus Research, a National Instruments Brand
+//
+// SPDX-License-Identifier: GPL-3.0-or-later
+//
+
+#pragma once
+
+#include <uhd/exception.hpp>
+#include <uhd/features/discoverable_feature.hpp>
+#include <vector>
+
+namespace uhd { namespace features {
+
+/*! Interface for discovering and accessing discoverable features.
+ */
+class discoverable_feature_getter_iface
+{
+public:
+    virtual ~discoverable_feature_getter_iface() = default;
+
+    //! Retrieves a feature of the specified type.
+    //
+    // Note that if the given feature type does not exist, this function will
+    // assert. The user should first check that the feature exists via the
+    // has_feature method.
+    // Usage:
+    // auto feature_ref = radio.get_feature<desired_feature_class>();
+    template <typename T>
+    T& get_feature()
+    {
+        auto p = get_feature_ptr(T::get_feature_id());
+        UHD_ASSERT_THROW(p);
+        auto typed_p = dynamic_cast<T*>(p.get());
+        UHD_ASSERT_THROW(typed_p);
+        return *typed_p;
+    }
+
+    //! Determines whether a given feature exists
+    //
+    // This function should be used to gate functionality before calling
+    // get_feature().
+    template <typename T>
+    bool has_feature()
+    {
+        return bool(get_feature_ptr(T::get_feature_id()));
+    }
+
+    //! Enumerate all discoverable features present on the device.
+    //
+    // Returns a vector (in no particular order) of the features that this
+    // device supports.
+    virtual std::vector<std::string> enumerate_features() = 0;
+
+private:
+    //! Get a shared pointer to a feature, if it exists.
+    //
+    // If the feature does not exist on the device, returns a null pointer.
+    virtual discoverable_feature::sptr get_feature_ptr(
+        discoverable_feature::feature_id_t feature_id) = 0;
+};
+
+}} // namespace uhd::features