diff options
Diffstat (limited to 'host/lib/include/uhdlib/rfnoc/chdr_packet.hpp')
| -rw-r--r-- | host/lib/include/uhdlib/rfnoc/chdr_packet.hpp | 296 |
1 files changed, 296 insertions, 0 deletions
diff --git a/host/lib/include/uhdlib/rfnoc/chdr_packet.hpp b/host/lib/include/uhdlib/rfnoc/chdr_packet.hpp new file mode 100644 index 000000000..89b33a66a --- /dev/null +++ b/host/lib/include/uhdlib/rfnoc/chdr_packet.hpp @@ -0,0 +1,296 @@ +// +// Copyright 2019 Ettus Research, a National Instruments Brand +// +// SPDX-License-Identifier: GPL-3.0-or-later +// + +#ifndef INCLUDED_RFNOC_CHDR_PACKET_HPP +#define INCLUDED_RFNOC_CHDR_PACKET_HPP + +#include <uhd/types/endianness.hpp> +#include <uhd/utils/byteswap.hpp> +#include <uhdlib/rfnoc/chdr_types.hpp> +#include <limits> + +namespace uhd { namespace rfnoc { namespace chdr { + +//---------------------------------------------------- +// Generic CHDR Packet Container +//---------------------------------------------------- + +//! A container class that wraps a generic buffer that contains a CHDR packet. The +// container provides a high level API to read and write the header, metadata and payload +// of the packet. The payload can be accessed as a generic buffer using this interface. +// +class chdr_packet +{ +public: + //! A unique pointer to a const chdr_packet. Useful as a read-only interface. + typedef std::unique_ptr<const chdr_packet> cuptr; + //! A unique pointer to a non-const chdr_packet. Useful as a read-write interface. + typedef std::unique_ptr<chdr_packet> uptr; + + virtual ~chdr_packet() = 0; + + /*! Updates the underlying storage of this packet. This is a const method and is + * only useful for read-only (RX) access. + * + * \param pkt_buff Pointer to a buffer that contains the RX packet + */ + virtual void refresh(const void* pkt_buff) const = 0; + + /*! Updates the underlying storage of this packet, and populates it with the specified + * arguments. This is a non-const method and is useful for read-write (TX) access. + * + * \param pkt_buff Pointer to a buffer that should be populated with the TX packet + * \param header The CHDR header to fill into the TX packet + * \param timestamp The timestamp to fill into the TX packet (if requested) + */ + virtual void refresh(void* pkt_buff, chdr_header& header, uint64_t timestamp = 0) = 0; + + /*! Updates the CHDR header with the written payload size + * + * \param payload_size_bytes The payload size in bytes + */ + virtual void update_payload_size(size_t payload_size_bytes) = 0; + + /*! Returns a class that represents the contents of the CHDR header + * + * \return The CHDR header + */ + virtual chdr_header get_chdr_header() const = 0; + + /*! Returns the timestamp in the packet as an optional value + * + * \return A boost::optional which if initialized has the timestamp + */ + virtual boost::optional<uint64_t> get_timestamp() const = 0; + + /*! Returns the endianness of the metadata and payload buffers + * + * \return The byte order as a uhd::endianness_t + */ + virtual endianness_t get_byte_order() const = 0; + + /*! Returns the maximum transfer unit in bytes + * + * \return The maximum transfer unit in bytes + */ + virtual size_t get_mtu_bytes() const = 0; + + /*! Returns the metadata size in bytes + * + * \return The size in bytes + */ + virtual size_t get_mdata_size() const = 0; + + /*! Returns a const void pointer to the metadata section in the packet + * + * \return A pointer to the metadata + */ + virtual const void* get_mdata_const_ptr() const = 0; + + /*! Returns a non-const void pointer to the metadata section in the packet + * + * \return A pointer to the metadata + */ + virtual void* get_mdata_ptr() = 0; + + /*! Returns the payload size in bytes + * + * \return The size in bytes + */ + virtual size_t get_payload_size() const = 0; + + /*! Returns a const void pointer to the payload section in the packet + * + * \return A pointer to the payload + */ + virtual const void* get_payload_const_ptr() const = 0; + + /*! Returns a non-const void pointer to the payload section in the packet + * + * \return A pointer to the payload + */ + virtual void* get_payload_ptr() = 0; + + //! Shortcut to return the const metadata pointer cast as a specific type + template <typename data_t> + inline const data_t* get_mdata_const_ptr_as() const + { + return reinterpret_cast<const data_t*>(get_mdata_const_ptr()); + } + + //! Shortcut to return the non-const metadata pointer cast as a specific type + template <typename data_t> + inline data_t* get_mdata_ptr_as() + { + return reinterpret_cast<data_t*>(get_mdata_ptr()); + } + + //! Shortcut to return the const payload pointer cast as a specific type + template <typename data_t> + inline const data_t* get_payload_const_ptr_as() const + { + return reinterpret_cast<const data_t*>(get_payload_const_ptr()); + } + + //! Shortcut to return the non-const payload pointer cast as a specific type + template <typename data_t> + inline data_t* get_payload_ptr_as() + { + return reinterpret_cast<data_t*>(get_payload_ptr()); + } + + //! Return a function to convert a word of type data_t to host order + template <typename data_t> + const std::function<data_t(data_t)> conv_to_host() const + { + return (get_byte_order() == uhd::ENDIANNESS_BIG) ? uhd::ntohx<data_t> + : uhd::wtohx<data_t>; + } + + //! Return a function to convert a word of type data_t from host order + template <typename data_t> + const std::function<data_t(data_t)> conv_from_host() const + { + return (get_byte_order() == uhd::ENDIANNESS_BIG) ? uhd::htonx<data_t> + : uhd::htowx<data_t>; + } +}; + +//---------------------------------------------------- +// Container for specific CHDR Packets +//---------------------------------------------------- + +//! A container class that wraps a generic buffer that contains a CHDR packet. The +// container provides a high level API to read and write the header, metadata and payload +// of the packet. The payload can be accessed as a specific type that will be serialized +// and deserialized appropriately. +// +template <typename payload_t> +class chdr_packet_specific +{ +public: + //! A unique pointer to a const chdr_packet. Useful as a read-only interface. + typedef std::unique_ptr<const chdr_packet_specific<payload_t>> cuptr; + //! A unique pointer to a non-const chdr_packet. Useful as a read-write interface. + typedef std::unique_ptr<chdr_packet_specific<payload_t>> uptr; + + chdr_packet_specific(chdr_packet::uptr chdr_pkt) : _chdr_pkt(std::move(chdr_pkt)) {} + ~chdr_packet_specific() = default; + + //! Updates the underlying storage of this packet. This is a const method and is + // only useful for read-only access. + inline void refresh(const void* pkt_buff) const + { + _chdr_pkt->refresh(pkt_buff); + } + + //! Updates the underlying storage of this packet, and populates it with the specified + // arguments. This is a non-const method and is useful for read-write access. + inline void refresh(void* pkt_buff, chdr_header& header, const payload_t& payload) + { + payload.populate_header(header); + _chdr_pkt->refresh(pkt_buff, header); + size_t bytes_copied = payload.serialize(_chdr_pkt->get_payload_ptr_as<uint64_t>(), + _chdr_pkt->get_mtu_bytes(), + _chdr_pkt->conv_from_host<uint64_t>()); + _chdr_pkt->update_payload_size(bytes_copied); + header = _chdr_pkt->get_chdr_header(); + } + + //! Returns a class that represents the contents of the CHDR header + inline chdr_header get_chdr_header() const + { + return std::move(_chdr_pkt->get_chdr_header()); + } + + //! Returns a class that represents the contents of the CHDR payload + inline payload_t get_payload() const + { + payload_t payload; + payload.deserialize(_chdr_pkt->get_payload_const_ptr_as<uint64_t>(), + _chdr_pkt->get_payload_size() / sizeof(uint64_t), + _chdr_pkt->conv_to_host<uint64_t>()); + return payload; + } + + //! Fills the CHDR payload into the specified parameter + inline void fill_payload(payload_t& payload) const + { + payload.deserialize(_chdr_pkt->get_payload_const_ptr_as<uint64_t>(), + _chdr_pkt->get_payload_size() / sizeof(uint64_t), + _chdr_pkt->conv_to_host<uint64_t>()); + } + +private: + chdr_packet::uptr _chdr_pkt; +}; + +//---------------------------------------------------- +// Specific CHDR packet types +//---------------------------------------------------- + +//! CHDR control packet +typedef chdr_packet_specific<ctrl_payload> chdr_ctrl_packet; + +//! CHDR stream status packet +typedef chdr_packet_specific<strs_payload> chdr_strs_packet; + +//! CHDR stream command packet +typedef chdr_packet_specific<strc_payload> chdr_strc_packet; + +//! CHDR management packet +typedef chdr_packet_specific<mgmt_payload> chdr_mgmt_packet; + +//---------------------------------------------------- +// CHDR packet factory +//---------------------------------------------------- + +//! A copyable and movable factory class that is capable of generating generic and +//! specific CHDR packet containers. +// +class chdr_packet_factory +{ +public: + //! A parametrized ctor that takes in all the info required to generate a CHDR packet + // + // \param chdr_w The CHDR width of the remote device + // \param endianness The endianness of the link being used (e.g., Ethernet + // typically uses big-endian, PCIe typically uses + // little-endian). Note: The host endianness is + // automatically derived. + chdr_packet_factory(chdr_w_t chdr_w, endianness_t endianness); + chdr_packet_factory() = delete; + chdr_packet_factory(const chdr_packet_factory& rhs) = default; + chdr_packet_factory(chdr_packet_factory&& rhs) = default; + + //! Makes a generic CHDR packet and transfers ownership to the client + chdr_packet::uptr make_generic( + size_t mtu_bytes = std::numeric_limits<size_t>::max()) const; + + //! Makes a CHDR control packet and transfers ownership to the client + chdr_ctrl_packet::uptr make_ctrl( + size_t mtu_bytes = std::numeric_limits<size_t>::max()) const; + + //! Makes a CHDR stream status packet and transfers ownership to the client + chdr_strs_packet::uptr make_strs( + size_t mtu_bytes = std::numeric_limits<size_t>::max()) const; + + //! Makes a CHDR stream cmd packet and transfers ownership to the client + chdr_strc_packet::uptr make_strc( + size_t mtu_bytes = std::numeric_limits<size_t>::max()) const; + + //! Makes a CHDR management packet and transfers ownership to the client + chdr_mgmt_packet::uptr make_mgmt( + size_t mtu_bytes = std::numeric_limits<size_t>::max()) const; + +private: + const chdr_w_t _chdr_w; + const endianness_t _endianness; +}; + +}}} // namespace uhd::rfnoc::chdr + +#endif /* INCLUDED_RFNOC_CHDR_PACKET_HPP */ |