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 <stdint.h>
#include <boost/noncopyable.hpp>
#include <uhd/types/wb_iface.hpp>
#include <uhd/exception.hpp>
#include <uhd/utils/dirty_tracked.hpp>
#include <boost/thread/mutex.hpp>
#include <boost/thread/locks.hpp>
#include <boost/unordered_map.hpp>
#include <boost/tokenizer.hpp>
#include <boost/foreach.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);
        }
    }
}

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);
  }
*/
}

//==================================================================
// 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 */