memory.hpp

Go to the documentation of this file.

// SPDX-License-Identifier: Apache-2.0
// Copyright 2026 Chris Leishman
 
#pragma once
 
#include <idfxx/error.hpp>
#include <idfxx/flags.hpp>
 
#include <cstddef>
#include <cstdint>
#include <esp_heap_caps.h>
#include <limits>
#include <type_traits>
 
namespace idfxx::memory {
 
enum class caps : uint32_t {
#ifdef CONFIG_HEAP_HAS_EXEC_HEAP
    exec = MALLOC_CAP_EXEC, 
#endif
    access_32bit = MALLOC_CAP_32BIT,          
    access_8bit = MALLOC_CAP_8BIT,            
    dma = MALLOC_CAP_DMA,                     
    spiram = MALLOC_CAP_SPIRAM,               
    internal = MALLOC_CAP_INTERNAL,           
    default_heap = MALLOC_CAP_DEFAULT,        
    iram = MALLOC_CAP_IRAM_8BIT,              
    retention = MALLOC_CAP_RETENTION,         
    rtc = MALLOC_CAP_RTCRAM,                  
    dma_desc_ahb = MALLOC_CAP_DMA_DESC_AHB,   
    dma_desc_axi = MALLOC_CAP_DMA_DESC_AXI,   
    cache_aligned = MALLOC_CAP_CACHE_ALIGNED, 
 
    dram = internal | access_8bit, 
};
 
} // namespace idfxx::memory
 
template<>
inline constexpr bool idfxx::enable_flags_operators<idfxx::memory::caps> = true;
 
// ---- Heap info queries ------------------------------------------------------
 
namespace idfxx::memory {
 
struct info {
    size_t total_free_bytes;      
    size_t total_allocated_bytes; 
    size_t largest_free_block;    
    size_t minimum_free_bytes;    
    size_t allocated_blocks;      
    size_t free_blocks;           
    size_t total_blocks;          
};
 
[[nodiscard]] inline size_t total_size(flags<caps> c) noexcept {
    return heap_caps_get_total_size(to_underlying(c));
}
 
[[nodiscard]] inline size_t free_size(flags<caps> c) noexcept {
    return heap_caps_get_free_size(to_underlying(c));
}
 
[[nodiscard]] inline size_t largest_free_block(flags<caps> c) noexcept {
    return heap_caps_get_largest_free_block(to_underlying(c));
}
 
[[nodiscard]] inline size_t minimum_free_size(flags<caps> c) noexcept {
    return heap_caps_get_minimum_free_size(to_underlying(c));
}
 
[[nodiscard]] inline info get_info(flags<caps> c) noexcept {
    multi_heap_info_t raw{};
    heap_caps_get_info(&raw, to_underlying(c));
    return {
        .total_free_bytes = raw.total_free_bytes,
        .total_allocated_bytes = raw.total_allocated_bytes,
        .largest_free_block = raw.largest_free_block,
        .minimum_free_bytes = raw.minimum_free_bytes,
        .allocated_blocks = raw.allocated_blocks,
        .free_blocks = raw.free_blocks,
        .total_blocks = raw.total_blocks,
    };
}
 
// ---- Heap walking -----------------------------------------------------------
 
struct region {
    intptr_t start; 
    intptr_t end;   
};
 
struct block {
    void* ptr;   
    size_t size; 
    bool used;   
};
 
template<typename F>
void walk(flags<caps> c, F&& walker) {
    auto cb = [](walker_heap_into_t heap_info, walker_block_info_t block_info, void* user_data) -> bool {
        auto& fn = *static_cast<std::remove_reference_t<F>*>(user_data);
        return fn(region{heap_info.start, heap_info.end}, block{block_info.ptr, block_info.size, block_info.used});
    };
    heap_caps_walk(to_underlying(c), cb, &walker);
}
 
template<typename F>
void walk(F&& walker) {
    auto cb = [](walker_heap_into_t heap_info, walker_block_info_t block_info, void* user_data) -> bool {
        auto& fn = *static_cast<std::remove_reference_t<F>*>(user_data);
        return fn(region{heap_info.start, heap_info.end}, block{block_info.ptr, block_info.size, block_info.used});
    };
    heap_caps_walk_all(cb, &walker);
}
 
// ---- Heap integrity checking ------------------------------------------------
 
[[nodiscard]] inline bool check_integrity(flags<caps> c, bool print_errors = false) noexcept {
    return heap_caps_check_integrity(to_underlying(c), print_errors);
}
 
[[nodiscard]] inline bool check_integrity(bool print_errors = false) noexcept {
    return heap_caps_check_integrity_all(print_errors);
}
 
// ---- Heap dump --------------------------------------------------------------
 
inline void dump(flags<caps> c) noexcept {
    heap_caps_dump(to_underlying(c));
}
 
inline void dump() noexcept {
    heap_caps_dump_all();
}
 
} // namespace idfxx::memory
 
// ---- Heap allocation --------------------------------------------------------
 
namespace idfxx {
 
[[nodiscard]] inline void* malloc(size_t size, flags<memory::caps> c) noexcept {
    return heap_caps_malloc(size, to_underlying(c));
}
 
[[nodiscard]] inline void* calloc(size_t n, size_t size, flags<memory::caps> c) noexcept {
    return heap_caps_calloc(n, size, to_underlying(c));
}
 
[[nodiscard]] inline void* realloc(void* ptr, size_t size, flags<memory::caps> c) noexcept {
    return heap_caps_realloc(ptr, size, to_underlying(c));
}
 
inline void free(void* ptr) noexcept {
    heap_caps_free(ptr);
}
 
[[nodiscard]] inline void* aligned_alloc(size_t alignment, size_t size, flags<memory::caps> c) noexcept {
    return heap_caps_aligned_alloc(alignment, size, to_underlying(c));
}
 
[[nodiscard]] inline void* aligned_calloc(size_t alignment, size_t n, size_t size, flags<memory::caps> c) noexcept {
    return heap_caps_aligned_calloc(alignment, n, size, to_underlying(c));
}
 
// ---- STL-compatible allocators ----------------------------------------------
 
template<typename T, flags<memory::caps> Caps, size_t Alignment = 0>
struct caps_allocator {
    using value_type = T; 
    template<typename U>
    struct rebind {
        using other = caps_allocator<U, Caps, Alignment>; 
    };
 
    caps_allocator() = default;
 
    template<typename U>
    constexpr caps_allocator(const caps_allocator<U, Caps, Alignment>&) noexcept {}
 
    [[nodiscard]] T* allocate(size_t n) {
        if (n > std::numeric_limits<size_t>::max() / sizeof(T)) {
            raise_no_mem();
        }
        void* p;
        if constexpr (Alignment == 0) {
            p = heap_caps_malloc(n * sizeof(T), to_underlying(Caps));
        } else {
            static_assert((Alignment & (Alignment - 1)) == 0, "Alignment must be a power of two");
            p = heap_caps_aligned_alloc(Alignment, n * sizeof(T), to_underlying(Caps));
        }
        if (!p) {
            raise_no_mem();
        }
        return static_cast<T*>(p);
    }
 
    void deallocate(T* p, size_t) noexcept { heap_caps_free(p); }
};
 
template<typename T, typename U, flags<memory::caps> Caps, size_t Alignment>
constexpr bool
operator==(const caps_allocator<T, Caps, Alignment>&, const caps_allocator<U, Caps, Alignment>&) noexcept {
    return true;
}
 
template<typename T>
using dram_allocator = caps_allocator<T, memory::caps::dram>;
 
template<typename T>
using spiram_allocator = caps_allocator<T, memory::caps::spiram>;
 
template<typename T>
using dma_allocator = caps_allocator<T, memory::caps::dma>;
 
template<typename T, size_t Alignment>
using aligned_dram_allocator = caps_allocator<T, memory::caps::dram, Alignment>;
 
template<typename T, size_t Alignment>
using aligned_spiram_allocator = caps_allocator<T, memory::caps::spiram, Alignment>;
 
template<typename T, size_t Alignment>
using aligned_dma_allocator = caps_allocator<T, memory::caps::dma, Alignment>;
 
 
} // namespace idfxx