1 // 2 // Copyright 2010-2011,2014 Ettus Research LLC 3 // Copyright 2018 Ettus Research, a National Instruments Company 4 // 5 // SPDX-License-Identifier: GPL-3.0-or-later 6 // 7 8 #pragma once 9 10 #include <uhd/config.hpp> 11 #include <uhd/property_tree.hpp> 12 #include <uhd/stream.hpp> 13 #include <uhd/types/device_addr.hpp> 14 #include <uhd/utils/noncopyable.hpp> 15 #include <functional> 16 #include <memory> 17 18 namespace uhd { 19 20 class property_tree; // forward declaration 21 22 /*! 23 * The device interface represents the hardware. 24 * The API allows for discovery, configuration, and streaming. 25 */ 26 class UHD_API device : uhd::noncopyable 27 { 28 public: 29 typedef std::shared_ptr<device> sptr; 30 typedef std::function<device_addrs_t(const device_addr_t&)> find_t; 31 typedef std::function<sptr(const device_addr_t&)> make_t; 32 33 //! Device type, used as a filter in make 34 enum device_filter_t { ANY, USRP, CLOCK }; 35 virtual ~device(void) = 0; 36 37 /*! 38 * Register a device into the discovery and factory system. 39 * 40 * \param find a function that discovers devices 41 * \param make a factory function that makes a device 42 * \param filter include only USRP devices, clock devices, or both 43 */ 44 static void register_device( 45 const find_t& find, const make_t& make, const device_filter_t filter); 46 47 /*! 48 * \brief Find devices attached to the host. 49 * 50 * The hint device address should be used to narrow down the search 51 * to particular transport types and/or transport arguments. 52 * 53 * \param hint a partially (or fully) filled in device address 54 * \param filter an optional filter to exclude USRP or clock devices 55 * \return a vector of device addresses for all devices on the system 56 */ 57 static device_addrs_t find(const device_addr_t& hint, device_filter_t filter = ANY); 58 59 /*! 60 * \brief Create a new device from the device address hint. 61 * 62 * The method will go through the registered device types and pick one of 63 * the discovered devices. 64 * 65 * By default, the first result will be used to create a new device. 66 * Use the which parameter as an index into the list of results. 67 * 68 * \param hint a partially (or fully) filled in device address 69 * \param filter an optional filter to exclude USRP or clock devices 70 * \param which which address to use when multiple are found 71 * \return a shared pointer to a new device instance 72 */ 73 static sptr make( 74 const device_addr_t& hint, device_filter_t filter = ANY, size_t which = 0); 75 76 /*! \brief Make a new receive streamer from the streamer arguments 77 * 78 * Note: There can always only be one streamer. When calling get_rx_stream() 79 * a second time, the first streamer must be destroyed beforehand. 80 */ 81 virtual rx_streamer::sptr get_rx_stream(const stream_args_t& args) = 0; 82 83 /*! \brief Make a new transmit streamer from the streamer arguments 84 * 85 * Note: There can always only be one streamer. When calling get_tx_stream() 86 * a second time, the first streamer must be destroyed beforehand. 87 */ 88 virtual tx_streamer::sptr get_tx_stream(const stream_args_t& args) = 0; 89 90 /*! DEPRECATED: Receive asynchronous message from the device 91 * 92 * Prefer calling recv_async_msg on the associated TX streamer. This method 93 * has the problem that it doesn't necessarily know which Tx streamer is 94 * being addressed, and thus might not be delivering the expected outcome. 95 * 96 * \param async_metadata the metadata to be filled in 97 * \param timeout the timeout in seconds to wait for a message 98 * \return true when the async_metadata is valid, false for timeout 99 */ 100 virtual bool recv_async_msg( 101 async_metadata_t& async_metadata, double timeout = 0.1) = 0; 102 103 //! Get access to the underlying property structure 104 uhd::property_tree::sptr get_tree(void) const; 105 106 //! Get device type 107 device_filter_t get_device_type() const; 108 109 protected: 110 uhd::property_tree::sptr _tree; 111 device_filter_t _type; 112 }; 113 114 } // namespace uhd 115