partition.hpp

Go to the documentation of this file.

// SPDX-License-Identifier: Apache-2.0
// Copyright 2026 Chris Leishman
 
#pragma once
 
#include <idfxx/error>
 
#include <array>
#include <cassert>
#include <cstddef>
#include <cstdint>
#include <esp_partition.h>
#include <span>
#include <string_view>
#include <type_traits>
#include <vector>
 
namespace idfxx {
 
class partition {
public:
    enum class type : int {
        app = 0x00,             
        data = 0x01,            
        bootloader = 0x02,      
        partition_table = 0x03, 
        any = 0xff,             
    };
 
    enum class subtype : int {
        // clang-format off
        // Bootloader subtypes
        bootloader_primary  = 0x00, 
        bootloader_ota      = 0x01, 
        bootloader_recovery = 0x02, 
 
        // Partition table subtypes
        partition_table_primary = 0x00, 
        partition_table_ota     = 0x01, 
 
        // App subtypes
        app_factory = 0x00, 
        app_ota_0   = 0x10, 
        app_ota_1   = 0x11, 
        app_ota_2   = 0x12, 
        app_ota_3   = 0x13, 
        app_ota_4   = 0x14, 
        app_ota_5   = 0x15, 
        app_ota_6   = 0x16, 
        app_ota_7   = 0x17, 
        app_ota_8   = 0x18, 
        app_ota_9   = 0x19, 
        app_ota_10  = 0x1a, 
        app_ota_11  = 0x1b, 
        app_ota_12  = 0x1c, 
        app_ota_13  = 0x1d, 
        app_ota_14  = 0x1e, 
        app_ota_15  = 0x1f, 
        app_test    = 0x20, 
 
        // Data subtypes
        data_ota       = 0x00, 
        data_phy       = 0x01, 
        data_nvs       = 0x02, 
        data_coredump  = 0x03, 
        data_nvs_keys  = 0x04, 
        data_efuse_em  = 0x05, 
        data_undefined = 0x06, 
        data_esphttpd  = 0x80, 
        data_fat       = 0x81, 
        data_spiffs    = 0x82, 
        data_littlefs  = 0x83, 
 
        any = 0xff, 
        // clang-format on
    };
 
    enum class mmap_memory : int {
        data = 0, 
        inst,     
    };
 
    class mmap_handle;
 
    // =========================================================================
    // Discovery
    // =========================================================================
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    [[nodiscard]] static partition
    find(enum type type, enum subtype subtype = subtype::any, std::string_view label = {});
 
    [[nodiscard]] static partition find(std::string_view label);
#endif
 
    [[nodiscard]] static result<partition>
    try_find(enum type type, enum subtype subtype = subtype::any, std::string_view label = {});
 
    [[nodiscard]] static result<partition> try_find(std::string_view label);
 
    [[nodiscard]] static std::vector<partition>
    find_all(enum type type = type::any, enum subtype subtype = subtype::any, std::string_view label = {});
 
    [[nodiscard]] static constexpr partition from_handle(const esp_partition_t* handle) { return partition{handle}; }
 
    // Copyable and movable
    partition(const partition&) = default;
    partition(partition&&) = default;
    partition& operator=(const partition&) = default;
    partition& operator=(partition&&) = default;
 
    // =========================================================================
    // Accessors
    // =========================================================================
 
    [[nodiscard]] constexpr bool operator==(const partition&) const noexcept = default;
 
    [[nodiscard]] enum type type() const { return static_cast<enum partition::type>(_part->type); }
 
    [[nodiscard]] enum subtype subtype() const { return static_cast<enum partition::subtype>(_part->subtype); }
 
    [[nodiscard]] uint32_t address() const { return _part->address; }
 
    [[nodiscard]] uint32_t size() const { return _part->size; }
 
    [[nodiscard]] uint32_t erase_size() const { return _part->erase_size; }
 
    [[nodiscard]] std::string_view label() const { return _part->label; }
 
    [[nodiscard]] bool encrypted() const { return _part->encrypted; }
 
    [[nodiscard]] bool readonly() const { return _part->readonly; }
 
    [[nodiscard]] constexpr const esp_partition_t* idf_handle() const { return _part; }
 
    // =========================================================================
    // Read / Write / Erase
    // =========================================================================
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    void read(size_t offset, void* dst, size_t size) const { unwrap(try_read(offset, dst, size)); }
 
    void read(size_t offset, std::span<uint8_t> dst) const { unwrap(try_read(offset, dst)); }
 
    void write(size_t offset, const void* src, size_t size) { unwrap(try_write(offset, src, size)); }
 
    void write(size_t offset, std::span<const uint8_t> src) { unwrap(try_write(offset, src)); }
 
    void read_raw(size_t offset, void* dst, size_t size) const { unwrap(try_read_raw(offset, dst, size)); }
 
    void read_raw(size_t offset, std::span<uint8_t> dst) const { unwrap(try_read_raw(offset, dst)); }
 
    void write_raw(size_t offset, const void* src, size_t size) { unwrap(try_write_raw(offset, src, size)); }
 
    void write_raw(size_t offset, std::span<const uint8_t> src) { unwrap(try_write_raw(offset, src)); }
 
    void erase_range(size_t offset, size_t size) { unwrap(try_erase_range(offset, size)); }
 
    [[nodiscard]] std::array<uint8_t, 32> sha256() const { return unwrap(try_sha256()); }
 
    [[nodiscard]] mmap_handle mmap(size_t offset, size_t size, enum mmap_memory memory = mmap_memory::data) const;
#endif
 
    [[nodiscard]] result<void> try_read(size_t offset, void* dst, size_t size) const;
 
    [[nodiscard]] result<void> try_read(size_t offset, std::span<uint8_t> dst) const;
 
    [[nodiscard]] result<void> try_write(size_t offset, const void* src, size_t size);
 
    [[nodiscard]] result<void> try_write(size_t offset, std::span<const uint8_t> src);
 
    [[nodiscard]] result<void> try_read_raw(size_t offset, void* dst, size_t size) const;
 
    [[nodiscard]] result<void> try_read_raw(size_t offset, std::span<uint8_t> dst) const;
 
    [[nodiscard]] result<void> try_write_raw(size_t offset, const void* src, size_t size);
 
    [[nodiscard]] result<void> try_write_raw(size_t offset, std::span<const uint8_t> src);
 
    [[nodiscard]] result<void> try_erase_range(size_t offset, size_t size);
 
    [[nodiscard]] result<std::array<uint8_t, 32>> try_sha256() const;
 
    [[nodiscard]] result<mmap_handle>
    try_mmap(size_t offset, size_t size, enum mmap_memory memory = mmap_memory::data) const;
 
    [[nodiscard]] bool check_identity(const partition& other) const;
 
private:
    explicit constexpr partition(const esp_partition_t* part)
        : _part(part) {}
 
    const esp_partition_t* _part;
};
 
[[nodiscard]] constexpr enum partition::subtype app_ota(unsigned i) {
    assert(i <= 15);
    return static_cast<enum partition::subtype>(0x10 + i);
}
 
class partition::mmap_handle {
public:
    mmap_handle() = default;
 
    ~mmap_handle();
 
    mmap_handle(const mmap_handle&) = delete;
    mmap_handle& operator=(const mmap_handle&) = delete;
 
    mmap_handle(mmap_handle&& other) noexcept;
 
    mmap_handle& operator=(mmap_handle&& other) noexcept;
 
    [[nodiscard]] explicit operator bool() const { return _ptr != nullptr; }
 
    [[nodiscard]] const void* data() const { return _ptr; }
 
    [[nodiscard]] size_t size() const { return _size; }
 
    template<typename T>
    [[nodiscard]] std::span<T> as_span() const {
        static_assert(std::is_const_v<T>, "T must be const-qualified; mapped partition memory is read-only");
        return {static_cast<T*>(_ptr), _size / sizeof(T)};
    }
 
    esp_partition_mmap_handle_t release() noexcept;
 
private:
    friend class partition;
 
    mmap_handle(const void* ptr, size_t size, esp_partition_mmap_handle_t handle);
 
    const void* _ptr = nullptr;
    size_t _size = 0;
    esp_partition_mmap_handle_t _handle = 0;
};
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
inline partition::mmap_handle partition::mmap(size_t offset, size_t size, enum mmap_memory memory) const {
    return unwrap(try_mmap(offset, size, memory));
}
#endif
 
} // namespace idfxx