soft_register.hpp

Go to the documentation of this file.

//
// Copyright 2014 Ettus Research LLC
// Copyright 2018 Ettus Research, a National Instruments Company
//
// SPDX-License-Identifier: GPL-3.0-or-later
//

#ifndef INCLUDED_UHD_UTILS_SOFT_REGISTER_HPP
#define INCLUDED_UHD_UTILS_SOFT_REGISTER_HPP

#include <uhd/exception.hpp>
#include <uhd/types/wb_iface.hpp>
#include <uhd/utils/dirty_tracked.hpp>
#include <stdint.h>
#include <boost/foreach.hpp>
#include <boost/noncopyable.hpp>
#include <boost/thread/locks.hpp>
#include <boost/thread/mutex.hpp>
#include <boost/tokenizer.hpp>
#include <boost/unordered_map.hpp>
#include <list>

//==================================================================
// Soft Register Definition
//==================================================================

#define UHD_DEFINE_SOFT_REG_FIELD(name, width, shift) \
    static const uhd::soft_reg_field_t name = (((shift & 0xFF) << 8) | (width & 0xFF))

namespace uhd {

// TODO: These hints were added to boost 1.53.

UHD_INLINE bool likely(bool expr)
{
#ifdef __GNUC__
    return __builtin_expect(expr, true);
#else
    return expr;
#endif
}

UHD_INLINE bool unlikely(bool expr)
{
#ifdef __GNUC__
    return __builtin_expect(expr, false);
#else
    return expr;
#endif
}

typedef uint32_t soft_reg_field_t;

namespace soft_reg_field {
UHD_INLINE size_t width(const soft_reg_field_t field)
{
    return (field & 0xFF);
}

UHD_INLINE size_t shift(const soft_reg_field_t field)
{
    return ((field >> 8) & 0xFF);
}

template <typename data_t> UHD_INLINE data_t mask(const soft_reg_field_t field)
{
    constexpr data_t ONE      = static_cast<data_t>(1);
    constexpr data_t ALL_ONES = ~static_cast<data_t>(0);
    // Behavior for the left shift operation is undefined in C++
    // if the shift amount is >= bitwidth of the datatype
    // So we treat that as a special case with a branch predicition hint
    if (likely((sizeof(data_t) * 8) != width(field))) {
        return ((ONE << width(field)) - ONE) << shift(field);
    } else {
        return ALL_ONES << shift(field);
    }
}
} // namespace soft_reg_field

class soft_register_base : public boost::noncopyable
{
public:
    virtual ~soft_register_base() {}

    virtual void initialize(wb_iface& iface, bool sync = false) = 0;
    virtual void flush()                                        = 0;
    virtual void refresh()                                      = 0;
    virtual size_t get_bitwidth()                               = 0;
    virtual bool is_readable()                                  = 0;
    virtual bool is_writable()                                  = 0;

    template <typename soft_reg_t>
    UHD_INLINE static soft_reg_t& cast(soft_register_base& reg)
    {
        soft_reg_t* ptr = dynamic_cast<soft_reg_t*>(&reg);
        if (ptr) {
            return *ptr;
        } else {
            throw uhd::type_error("failed to cast register to specified type");
        }
    }
};

enum soft_reg_flush_mode_t { OPTIMIZED_FLUSH, ALWAYS_FLUSH };

template <typename reg_data_t, bool readable, bool writable>
class UHD_API soft_register_t : public soft_register_base
{
public:
    typedef boost::shared_ptr<soft_register_t<reg_data_t, readable, writable> > sptr;

    // Reserved field. Represents all bits in the register.
    UHD_DEFINE_SOFT_REG_FIELD(REGISTER, sizeof(reg_data_t) * 8, 0); //[WIDTH-1:0]

    soft_register_t(wb_iface::wb_addr_type wr_addr,
        wb_iface::wb_addr_type rd_addr,
        soft_reg_flush_mode_t mode = ALWAYS_FLUSH)
        : _iface(NULL)
        , _wr_addr(wr_addr)
        , _rd_addr(rd_addr)
        , _soft_copy(0)
        , _flush_mode(mode)
    {
    }

    explicit soft_register_t(
        wb_iface::wb_addr_type addr, soft_reg_flush_mode_t mode = ALWAYS_FLUSH)
        : _iface(NULL), _wr_addr(addr), _rd_addr(addr), _soft_copy(0), _flush_mode(mode)
    {
    }

    UHD_INLINE void initialize(wb_iface& iface, bool sync = false)
    {
        _iface = &iface;

        // Synchronize with hardware. For RW register, flush THEN refresh.
        if (sync && writable)
            flush();
        if (sync && readable)
            refresh();
    }

    UHD_INLINE void set(const soft_reg_field_t field, const reg_data_t value)
    {
        _soft_copy = (_soft_copy & ~soft_reg_field::mask<reg_data_t>(field))
                     | ((value << soft_reg_field::shift(field))
                           & soft_reg_field::mask<reg_data_t>(field));
    }

    UHD_INLINE reg_data_t get(const soft_reg_field_t field)
    {
        return (_soft_copy & soft_reg_field::mask<reg_data_t>(field))
               >> soft_reg_field::shift(field);
    }

    UHD_INLINE void flush()
    {
        if (writable && _iface) {
            // If optimized flush then poke only if soft copy is dirty
            // If flush mode is ALWAYS, the dirty flag should get optimized
            // out by the compiler because it is never read
            if (_flush_mode == ALWAYS_FLUSH || _soft_copy.is_dirty()) {
                if (get_bitwidth() <= 16) {
                    _iface->poke16(_wr_addr, static_cast<uint16_t>(_soft_copy));
                } else if (get_bitwidth() <= 32) {
                    _iface->poke32(_wr_addr, static_cast<uint32_t>(_soft_copy));
                } else if (get_bitwidth() <= 64) {
                    _iface->poke64(_wr_addr, static_cast<uint64_t>(_soft_copy));
                } else {
                    throw uhd::not_implemented_error(
                        "soft_register only supports up to 64 bits.");
                }
                _soft_copy.mark_clean();
            }
        } else {
            throw uhd::not_implemented_error(
                "soft_register is not writable or uninitialized.");
        }
    }

    UHD_INLINE void refresh()
    {
        if (readable && _iface) {
            if (get_bitwidth() <= 16) {
                _soft_copy = static_cast<reg_data_t>(_iface->peek16(_rd_addr));
            } else if (get_bitwidth() <= 32) {
                _soft_copy = static_cast<reg_data_t>(_iface->peek32(_rd_addr));
            } else if (get_bitwidth() <= 64) {
                _soft_copy = static_cast<reg_data_t>(_iface->peek64(_rd_addr));
            } else {
                throw uhd::not_implemented_error(
                    "soft_register only supports up to 64 bits.");
            }
            _soft_copy.mark_clean();
        } else {
            throw uhd::not_implemented_error(
                "soft_register is not readable or uninitialized.");
        }
    }

    UHD_INLINE void write(const soft_reg_field_t field, const reg_data_t value)
    {
        set(field, value);
        flush();
    }

    UHD_INLINE reg_data_t read(const soft_reg_field_t field)
    {
        refresh();
        return get(field);
    }

    UHD_INLINE size_t get_bitwidth()
    {
        static const size_t BITS_IN_BYTE = 8;
        return sizeof(reg_data_t) * BITS_IN_BYTE;
    }

    UHD_INLINE bool is_readable()
    {
        return readable;
    }

    UHD_INLINE bool is_writable()
    {
        return writable;
    }

private:
    wb_iface* _iface;
    const wb_iface::wb_addr_type _wr_addr;
    const wb_iface::wb_addr_type _rd_addr;
    dirty_tracked<reg_data_t> _soft_copy;
    const soft_reg_flush_mode_t _flush_mode;
};

template <typename reg_data_t, bool readable, bool writable>
class UHD_API soft_register_sync_t
    : public soft_register_t<reg_data_t, readable, writable>
{
public:
    typedef boost::shared_ptr<soft_register_sync_t<reg_data_t, readable, writable> > sptr;

    soft_register_sync_t(wb_iface::wb_addr_type wr_addr,
        wb_iface::wb_addr_type rd_addr,
        soft_reg_flush_mode_t mode = ALWAYS_FLUSH)
        : soft_register_t<reg_data_t, readable, writable>(wr_addr, rd_addr, mode)
        , _mutex()
    {
    }

    explicit soft_register_sync_t(
        wb_iface::wb_addr_type addr, soft_reg_flush_mode_t mode = ALWAYS_FLUSH)
        : soft_register_t<reg_data_t, readable, writable>(addr, mode), _mutex()
    {
    }

    UHD_INLINE void initialize(wb_iface& iface, bool sync = false)
    {
        boost::lock_guard<boost::mutex> lock(_mutex);
        soft_register_t<reg_data_t, readable, writable>::initialize(iface, sync);
    }

    UHD_INLINE void set(const soft_reg_field_t field, const reg_data_t value)
    {
        boost::lock_guard<boost::mutex> lock(_mutex);
        soft_register_t<reg_data_t, readable, writable>::set(field, value);
    }

    UHD_INLINE reg_data_t get(const soft_reg_field_t field)
    {
        boost::lock_guard<boost::mutex> lock(_mutex);
        return soft_register_t<reg_data_t, readable, writable>::get(field);
    }

    UHD_INLINE void flush()
    {
        boost::lock_guard<boost::mutex> lock(_mutex);
        soft_register_t<reg_data_t, readable, writable>::flush();
    }

    UHD_INLINE void refresh()
    {
        boost::lock_guard<boost::mutex> lock(_mutex);
        soft_register_t<reg_data_t, readable, writable>::refresh();
    }

    UHD_INLINE void write(const soft_reg_field_t field, const reg_data_t value)
    {
        boost::lock_guard<boost::mutex> lock(_mutex);
        soft_register_t<reg_data_t, readable, writable>::write(field, value);
    }

    UHD_INLINE reg_data_t read(const soft_reg_field_t field)
    {
        boost::lock_guard<boost::mutex> lock(_mutex);
        return soft_register_t<reg_data_t, readable, writable>::read(field);
    }

private:
    boost::mutex _mutex;
};

/*
 * Register Shortcut Formats:
 * - soft_reg<bits>_<mode>_t: Soft register object with an unsynchronized soft-copy.
 *                            Thread unsafe but lightweight. Mostly const propagated.
 * - soft_reg<bits>_<mode>_sync_t: Soft register object with a synchronized soft-copy.
 *                                 Thread safe but with memory/speed overhead.
 * where:
 * - <bits> = {16, 32 or 64}
 * - <mode> = {wo(write-only), rw(read-write) or ro(read-only)}
 *
 */

// 16-bit shortcuts
typedef soft_register_t<uint16_t, false, true> soft_reg16_wo_t;
typedef soft_register_t<uint16_t, true, false> soft_reg16_ro_t;
typedef soft_register_t<uint16_t, true, true> soft_reg16_rw_t;
typedef soft_register_sync_t<uint16_t, false, true> soft_reg16_wo_sync_t;
typedef soft_register_sync_t<uint16_t, true, false> soft_reg16_ro_sync_t;
typedef soft_register_sync_t<uint16_t, true, true> soft_reg16_rw_sync_t;
// 32-bit shortcuts
typedef soft_register_t<uint32_t, false, true> soft_reg32_wo_t;
typedef soft_register_t<uint32_t, true, false> soft_reg32_ro_t;
typedef soft_register_t<uint32_t, true, true> soft_reg32_rw_t;
typedef soft_register_sync_t<uint32_t, false, true> soft_reg32_wo_sync_t;
typedef soft_register_sync_t<uint32_t, true, false> soft_reg32_ro_sync_t;
typedef soft_register_sync_t<uint32_t, true, true> soft_reg32_rw_sync_t;
// 64-bit shortcuts
typedef soft_register_t<uint64_t, false, true> soft_reg64_wo_t;
typedef soft_register_t<uint64_t, true, false> soft_reg64_ro_t;
typedef soft_register_t<uint64_t, true, true> soft_reg64_rw_t;
typedef soft_register_sync_t<uint64_t, false, true> soft_reg64_wo_sync_t;
typedef soft_register_sync_t<uint64_t, true, false> soft_reg64_ro_sync_t;
typedef soft_register_sync_t<uint64_t, true, true> soft_reg64_rw_sync_t;


/*
 * Usage example
 *
  //===Define bit width, RW mode, and synchronization using base class===
  class example_reg_t : public soft_reg32_wo_sync_t (or soft_reg32_wo_t) {
  public:
    //===Define all the fields===
    UHD_DEFINE_SOFT_REG_FIELD(FIELD0,  1,  0);  //[0]
    UHD_DEFINE_SOFT_REG_FIELD(FIELD1, 15,  1);  //[15:1]
    UHD_DEFINE_SOFT_REG_FIELD(FIELD2, 16, 16);  //[31:16]

    example_reg_t():    //ctor with no args
      soft_reg32_wo_t(SR_CORE_EXAMPLE_REG_OFFSET)) //===Bind to offset===
    {
      //===Set Initial values===
      set(FIELD0, 0);
      set(FIELD1, 1);
      set(FIELD2, 0xFFFF);
    }
  }; //===Full register definition encapsulated in one class===

  void main() {
    example_reg_t reg_obj;
    reg_obj.initialize(iface);
    reg_obj.write(example_reg_t::FIELD2, 0x1234);

    example_reg_t::sptr reg_sptr = boost::make_shared<example_reg_t>();
    reg_obj->initialize(iface);
    reg_obj->write(example_reg_t::FIELD2, 0x1234);
  }
*/
} // namespace uhd

//==================================================================
// Soft Register Map and Database Definition
//==================================================================

namespace uhd {

class UHD_API soft_regmap_accessor_t
{
public:
    typedef boost::shared_ptr<soft_regmap_accessor_t> sptr;

    virtual ~soft_regmap_accessor_t(){};
    virtual soft_register_base& lookup(const std::string& path) const = 0;
    virtual std::vector<std::string> enumerate() const                = 0;
    virtual const std::string& get_name() const                       = 0;
};

class UHD_API soft_regmap_t : public soft_regmap_accessor_t, public boost::noncopyable
{
public:
    soft_regmap_t(const std::string& name) : _name(name) {}
    virtual ~soft_regmap_t(){};

    virtual UHD_INLINE const std::string& get_name() const
    {
        return _name;
    }

    void initialize(wb_iface& iface, bool sync = false)
    {
        boost::lock_guard<boost::mutex> lock(_mutex);
        BOOST_FOREACH (soft_register_base* reg, _reglist) {
            reg->initialize(iface, sync);
        }
    }

    void flush()
    {
        boost::lock_guard<boost::mutex> lock(_mutex);
        BOOST_FOREACH (soft_register_base* reg, _reglist) {
            reg->flush();
        }
    }

    void refresh()
    {
        boost::lock_guard<boost::mutex> lock(_mutex);
        BOOST_FOREACH (soft_register_base* reg, _reglist) {
            reg->refresh();
        }
    }

    virtual soft_register_base& lookup(const std::string& name) const
    {
        regmap_t::const_iterator iter = _regmap.find(name);
        if (iter != _regmap.end()) {
            return *(iter->second);
        } else {
            throw uhd::runtime_error("register not found in map: " + name);
        }
    }

    virtual std::vector<std::string> enumerate() const
    {
        std::vector<std::string> temp;
        BOOST_FOREACH (const regmap_t::value_type& reg, _regmap) {
            temp.push_back(_name + "/" + reg.first);
        }
        return temp;
    }

protected:
    enum visibility_t {
        PUBLIC, // Is accessible through the soft_regmap_accessor_t interface
        PRIVATE // Is NOT accessible through the soft_regmap_accessor_t interface
    };

    UHD_INLINE void add_to_map(soft_register_base& reg,
        const std::string& name,
        const visibility_t visible = PRIVATE)
    {
        boost::lock_guard<boost::mutex> lock(_mutex);
        if (visible == PUBLIC) {
            // Only add to the map if this register is publicly visible
            if (not _regmap.insert(regmap_t::value_type(name, &reg)).second) {
                throw uhd::assertion_error(
                    "cannot add two registers with the same name to regmap: " + name);
            }
        }
        _reglist.push_back(&reg);
    }

private:
    typedef boost::unordered_map<std::string, soft_register_base*> regmap_t;
    typedef std::list<soft_register_base*> reglist_t;

    const std::string _name;
    regmap_t _regmap; // For lookups
    reglist_t _reglist; // To maintain order
    boost::mutex _mutex;
};


class UHD_API soft_regmap_db_t : public soft_regmap_accessor_t, public boost::noncopyable
{
public:
    typedef boost::shared_ptr<soft_regmap_db_t> sptr;

    soft_regmap_db_t() : _name("") {}

    soft_regmap_db_t(const std::string& name) : _name(name) {}

    const std::string& get_name() const
    {
        return _name;
    }

    void add(soft_regmap_t& regmap)
    {
        boost::lock_guard<boost::mutex> lock(_mutex);
        _regmaps.push_back(&regmap);
    }

    void add(soft_regmap_db_t& db)
    {
        boost::lock_guard<boost::mutex> lock(_mutex);
        if (&db == this) {
            throw uhd::assertion_error("cannot add regmap db to itself" + _name);
        } else {
            _regmap_dbs.push_back(&db);
        }
    }

    soft_register_base& lookup(const std::string& path) const
    {
        // Turn the slash separated path string into tokens
        std::list<std::string> tokens;
        BOOST_FOREACH (const std::string& node,
            boost::tokenizer<boost::char_separator<char> >(
                path, boost::char_separator<char>("/"))) {
            tokens.push_back(node);
        }
        if ((tokens.size() > 2 && tokens.front() == _name) || // If this is a nested DB
            (tokens.size() > 1 && _name == "")) { // If this is a top-level DB
            if (_name != "")
                tokens.pop_front();
            if (tokens.size() == 2) { // 2 tokens => regmap/register path
                BOOST_FOREACH (const soft_regmap_accessor_t* regmap, _regmaps) {
                    if (regmap->get_name() == tokens.front()) {
                        return regmap->lookup(tokens.back());
                    }
                }
                throw uhd::runtime_error("could not find register map: " + path);
            } else if (not _regmap_dbs
                               .empty()) { //>2 tokens => <1 or more dbs>/regmap/register
                // Reconstruct path from tokens
                std::string newpath;
                BOOST_FOREACH (const std::string& node, tokens) {
                    newpath += ("/" + node);
                }
                // Dispatch path to hierarchical DB
                BOOST_FOREACH (const soft_regmap_accessor_t* db, _regmap_dbs) {
                    try {
                        return db->lookup(newpath.substr(1));
                    } catch (std::exception&) {
                        continue;
                    }
                }
            }
        }
        throw uhd::runtime_error("could not find register: " + path);
    }

    virtual std::vector<std::string> enumerate() const
    {
        std::vector<std::string> paths;
        BOOST_FOREACH (const soft_regmap_accessor_t* regmap, _regmaps) {
            const std::vector<std::string>& regs = regmap->enumerate();
            paths.insert(paths.end(), regs.begin(), regs.end());
        }
        BOOST_FOREACH (const soft_regmap_accessor_t* db, _regmap_dbs) {
            const std::vector<std::string>& regs = db->enumerate();
            paths.insert(paths.end(), regs.begin(), regs.end());
        }
        return paths;
    }

private:
    typedef std::list<soft_regmap_accessor_t*> db_t;

    const std::string _name;
    db_t _regmaps;
    db_t _regmap_dbs;
    boost::mutex _mutex;
};

} // namespace uhd

#endif /* INCLUDED_UHD_UTILS_SOFT_REGISTER_HPP */