Dynamic base address support

[lexszero]

My application uses register blocks that are memory-mapped during runtime (controlling FPGAs over PCIe bus from Linux with VFIO), so there's no way to know the exact base address in advance. Is there a way to accommodate such a usecase? I briefly looked into provided headers and it appears that `all classes are either calling default constructors, or using constexpr functionality, however for my usecase I need to somehow pass the base address when instantiating the HAL object (and it need to support multiple instances of the same HAL at different bases). This scenario doesn't feel too exotic or obscure to me, so I'm wondering if I'm missing something.

I'm open to implementing this feature myself and sending a MR, if you could advise whether this make sense at all and what would be the best way to go about it.

Otherwise, great piece of software! It would be awesome if I could actually use it.

Thank you in advance =)

[Risto97]

Hello @lexszero ,

Sounds like an interesting use case, however is this type of HAL for you, I am not sure.

As you noticed everything that is possible is done at compile time in the generated HAL.
The addresses of loads and stores when accessing the fields/registers are resolved by the compiler, all the function calls are also done at compile time, so there are no jumps at runtime.
This results in saving on the memory footprint as we don't have to save pointers and also less instructions as we don't need to load base addresses when writing to fields/registers.
This all makes sense when you target a very constrained system, think Cortex-M0+, minimal RV32, ... where every byte and instruction matters.

From the system you are describing, you might not have such a constrained system, and might not notice if you use hundreds of bytes of flash more.

On the other hand I think it could be done up to some degree.
All the memory IO is done through MemIoNode.
This class is meant to be overridden by the user in case they want to mock IO, like in this quick sketch:

#ifndef _ARCH_IO_H_
#define _ARCH_IO_H_

#include <array>
#include <cstdint>
#include <iostream>
#include <ostream>

class MockMemIO
{
public:
    inline static uintptr_t addr_offset = 0;

    static void set_addr_offset(uintptr_t offset) {
        addr_offset = offset;
    }

    static inline std::array<uint32_t, 115200> mem;

    static inline uint32_t read32(uint32_t addr) {
        uint32_t offsetted_addr = addr+addr_offset;
        std::cout << "Read32 at addr 0x" << std::hex << offsetted_addr << " Read data: 0x" << std::hex << MockMemIO::mem[addr] << std::endl;

        return MockMemIO::mem[addr+addr_offset];
    }

    static inline void write32(uint32_t addr, uint32_t val) {
        uint32_t offsetted_addr = addr+addr_offset;
        std::cout << "Write32 at addr 0x" << std::hex << offsetted_addr << " Write data: 0x" << std::hex << val << std::endl;
        MockMemIO::mem[offsetted_addr] = val;
    }
};

class ArchIoNode : public MockMemIO
{
public:
};

#endif // !_ARCH_IO_H_

My first idea was to just add the addr_offset variable that you can set to provide your base address for the whole HAL.
And then would use it something like this:

int main() {

    ENUM_EXAMPLE_HAL<0> hal;
    ENUM_EXAMPLE_HAL<1000> hal2;

    hal.set_addr_offset(1000);
    hal2.set_addr_offset(0);

    hal.r1.f1 = enum_example_nm::system_state_e::SHUTDOWN; 
    std::cout << "hal.DATA.RDATA = " << (uint32_t) hal.r1.get() << "\n";

    hal.set_addr_offset(0);

    hal.r1.f1 = enum_example_nm::system_state_e::SHUTDOWN; 
    std::cout << "hal.DATA.RDATA = " << (uint32_t) hal.r1.get() << "\n";

    return 0;
}

But this does not work when you have multiple HAL instances, as they would be sharing the same static variable for offset.
For this we need to allow the user to pass a custom ArchIoNode when they instantiate the HAL, something like:

    ENUM_EXAMPLE_HAL<0, ArchIo1> hal;
    ENUM_EXAMPLE_HAL<1000, ArchIo2> hal2;

But again this is compile time, so you cannot make these instances at runtime.
The question for you is what is drawing you for using this HAL, does the memory usage and HAL access time matter for you?
If you don't care about these 2 much, maybe a different approach might be better.
We welcome if you want to try and explore using this HAL and contribute to make it possible.

Best regards,
Risto.

[emrebayrm]

I actually have similar use case using UIO, my base address is also defined in runtime. whole write, read operations happens in set/get function eventually, so only place you need vary is actually set/get functions. @Risto97 is right, they will share the same offset and variables. But still you can get around with this using templates, yet with limitations. One hal shall be created per resource (VFIO fd, for you).

Here is my UIONode for example (I also add a little bit abstraction and sort of RAII style objects);

#include <cstdint>
#include <format>
#include <iostream>
#include <string_view>
#include <stdexcept>
#include <fcntl.h>
#include <sys/mman.h>
#include <unistd.h>

// Forward-declare so the friend declaration below compiles without
// pulling in the full addrmap_node.h here.
// That makes highly coupled with generated code and framework.
template<uint32_t BASE, typename PARENT_TYPE> class AddrmapNode;

enum class UIOResource_tag { Module1, Module2, /*etc.*/ };

template<UIOResource_tag UIO_Tag>
struct UioMappedIO {
private:
    static inline void *base = nullptr;
    static inline size_t mapped_size = 0;
    static inline int fd = -1;

    // Only AddrmapNode (the direct caller in the HAL chain) may call
    // set / get / get_abs_addr.  User code cannot call them directly,
    // which makes bypassing the Guard a compile-time error.
    template<uint32_t B, typename P> friend class AddrmapNode;

    static uintptr_t get_abs_addr() { return reinterpret_cast<uintptr_t>(base); }

    static void set(uint32_t addr, uint32_t val) {
        *reinterpret_cast<volatile uint32_t *>(static_cast<char *>(base) + addr) = val;
    }

    static uint32_t get(uint32_t addr) {
        return *reinterpret_cast<volatile uint32_t *>(static_cast<char *>(base) + addr);
    }

public:
    // Guard<HAL_TMPL, BASE> owns the HAL instance and the mmap lifetime together.
    // The only way to reach the HAL is through an lvalue Guard, so the mapping is
    // always alive when the HAL is accessed.
    template<
        template<uint32_t, typename> class HAL_TMPL,
        uint32_t BASE = 0>
    struct Guard {
        using HAL_TYPE = HAL_TMPL<BASE, UioMappedIO<UIO_Tag>>;

        Guard() = default;
        Guard(const Guard &) = delete;
        Guard &operator=(const Guard &) = delete;
        ~Guard() {
            if (UioMappedIO::base != MAP_FAILED && UioMappedIO::base != nullptr)
                ::munmap(UioMappedIO::base, UioMappedIO::mapped_size);
            if (UioMappedIO::fd >= 0)
                ::close(UioMappedIO::fd);
            UioMappedIO::base = nullptr;
            UioMappedIO::fd = -1;
        }

        // Lvalue ref-qualifiers prevent calling on a temporary Guard, which would
        // give a reference to a HAL whose mapping is already destroyed.
        HAL_TYPE &operator*()  &  { return hal_; }
        HAL_TYPE *operator->() &  { return &hal_; }

    private:
        HAL_TYPE hal_{};
    };

    template<template<uint32_t, typename> class HAL_TMPL, uint32_t BASE = 0>
    [[nodiscard]] static Guard<HAL_TMPL, BASE> init(std::string_view path, size_t size) {
        fd = ::open(path.data(), O_RDWR);
        if (fd < 0)
            throw std::runtime_error("UioMappedIO: failed to open " + std::string(path));

        mapped_size = size;
        base = ::mmap(nullptr, size, PROT_READ | PROT_WRITE, MAP_SHARED, fd, 0);
        std::cout << std::format("base address for {} is {:x}\n", path.data(), uint64_t(base));
        if (base == MAP_FAILED) {
            ::close(fd);
            fd = -1;
            throw std::runtime_error("UioMappedIO: mmap failed");
        }
        return Guard<HAL_TMPL, BASE>{};
    }
};

in main.cpp

   /// they use the same hal, but from different bases.
    auto guard_module_1   = UioMappedIO<UIOResource_tag::Module_1  >::init<EXAMPLE_HAL>("/dev/uio0", 0x1000);
    auto guard_module_2   = UioMappedIO<UIOResource_tag::Module_2  >::init<EXAMPLE_HAL>("/dev/uio1", 0x1000);

Not the best part is ofc, if your app is really big, then your enum will be really big.. not seem very maintainable and not something people can understand the intention naturally.

PS: this is still I'm experimenting, tho.