A flash partition. More...

Classes
class	mmap_handle
	A memory-mapped partition region. More...

Public Types
enum class	type : int { app = 0x00 , data = 0x01 , bootloader = 0x02 , partition_table = 0x03 , any = 0xff }
	Partition type. More...

enum class	subtype : int { bootloader_primary = 0x00 , bootloader_ota = 0x01 , bootloader_recovery = 0x02 , partition_table_primary = 0x00 , partition_table_ota = 0x01 , 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_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 }
	Partition subtype. More...

enum class	mmap_memory : int { data = 0 , inst }
	Memory type for memory-mapped partition access. More...

Public Member Functions
	partition (const partition &)=default

	partition (partition &&)=default

partition &	operator= (const partition &)=default

partition &	operator= (partition &&)=default

constexpr bool	operator== (const partition &) const noexcept=default
	Compares two partitions for equality.

enum type	type () const
	Returns the partition type.

enum subtype	subtype () const
	Returns the partition subtype.

uint32_t	address () const
	Returns the starting address in flash.

uint32_t	size () const
	Returns the partition size in bytes.

uint32_t	erase_size () const
	Returns the erase block size.

std::string_view	label () const
	Returns the partition label.

bool	encrypted () const
	Returns true if the partition is encrypted.

bool	readonly () const
	Returns true if the partition is read-only.

constexpr const esp_partition_t *	idf_handle () const
	Returns the underlying ESP-IDF partition handle.

void	read (size_t offset, void *dst, size_t size) const
	Reads data from the partition with decryption if applicable.

void	read (size_t offset, std::span< uint8_t > dst) const
	Reads data from the partition with decryption if applicable.

void	write (size_t offset, const void *src, size_t size)
	Writes data to the partition with encryption if applicable.

void	write (size_t offset, std::span< const uint8_t > src)
	Writes data to the partition with encryption if applicable.

void	read_raw (size_t offset, void *dst, size_t size) const
	Reads data from the partition without decryption.

void	read_raw (size_t offset, std::span< uint8_t > dst) const
	Reads data from the partition without decryption.

void	write_raw (size_t offset, const void *src, size_t size)
	Writes data to the partition without encryption.

void	write_raw (size_t offset, std::span< const uint8_t > src)
	Writes data to the partition without encryption.

void	erase_range (size_t offset, size_t size)
	Erases a range of the partition.

std::array< uint8_t, 32 >	sha256 () const
	Computes the SHA-256 hash of the partition contents.

mmap_handle	mmap (size_t offset, size_t size, enum mmap_memory memory=mmap_memory::data) const
	Memory-maps a region of the partition.

result< void >	try_read (size_t offset, void *dst, size_t size) const
	Reads data from the partition with decryption if applicable.

result< void >	try_read (size_t offset, std::span< uint8_t > dst) const
	Reads data from the partition with decryption if applicable.

result< void >	try_write (size_t offset, const void *src, size_t size)
	Writes data to the partition with encryption if applicable.

result< void >	try_write (size_t offset, std::span< const uint8_t > src)
	Writes data to the partition with encryption if applicable.

result< void >	try_read_raw (size_t offset, void *dst, size_t size) const
	Reads data from the partition without decryption.

result< void >	try_read_raw (size_t offset, std::span< uint8_t > dst) const
	Reads data from the partition without decryption.

result< void >	try_write_raw (size_t offset, const void *src, size_t size)
	Writes data to the partition without encryption.

result< void >	try_write_raw (size_t offset, std::span< const uint8_t > src)
	Writes data to the partition without encryption.

result< void >	try_erase_range (size_t offset, size_t size)
	Erases a range of the partition.

result< std::array< uint8_t, 32 > >	try_sha256 () const
	Computes the SHA-256 hash of the partition contents.

result< mmap_handle >	try_mmap (size_t offset, size_t size, enum mmap_memory memory=mmap_memory::data) const
	Memory-maps a region of the partition.

bool	check_identity (const partition &other) const
	Checks if two partitions have identical contents by comparing SHA-256 hashes.

Static Public Member Functions
static partition	find (enum type type, enum subtype subtype=subtype::any, std::string_view label={})
	Finds the first partition matching the given criteria.

static partition	find (std::string_view label)
	Finds the first partition with the given label.

static result< partition >	try_find (enum type type, enum subtype subtype=subtype::any, std::string_view label={})
	Finds the first partition matching the given criteria.

static result< partition >	try_find (std::string_view label)
	Finds the first partition with the given label.

static std::vector< partition >	find_all (enum type type=type::any, enum subtype subtype=subtype::any, std::string_view label={})
	Finds all partitions matching the given criteria.

static constexpr partition	from_handle (const esp_partition_t *handle)
	Constructs a partition from an ESP-IDF partition handle.

Detailed Description

A flash partition.

Represents a region of flash storage defined in the partition table. Provides discovery, reading, writing, erasing, and memory mapping.

Use the static find methods to discover partitions from the partition table. Partitions are copyable and remain valid for the entire application lifetime.

auto part = idfxx::partition::find("storage");
std::array<uint8_t, 256> buf{};
part.read(0, buf.data(), buf.size());

Definition at line 51 of file partition.hpp.

Member Enumeration Documentation

◆ mmap_memory

enum class idfxx::partition::mmap_memory : int

strong

Memory type for memory-mapped partition access.

Enumerator
data	Map to data memory, allows byte-aligned access.
inst	Map to instruction memory, allows only 4-byte-aligned access.

Definition at line 112 of file partition.hpp.

◆ subtype

enum class idfxx::partition::subtype : int

strong

Partition subtype.

Enumerator
bootloader_primary	Primary bootloader.
bootloader_ota	OTA bootloader.
bootloader_recovery	Recovery bootloader.
partition_table_primary	Primary partition table.
partition_table_ota	OTA partition table.
app_factory	Factory application.
app_ota_0	OTA application slot 0.
app_ota_1	OTA application slot 1.
app_ota_2	OTA application slot 2.
app_ota_3	OTA application slot 3.
app_ota_4	OTA application slot 4.
app_ota_5	OTA application slot 5.
app_ota_6	OTA application slot 6.
app_ota_7	OTA application slot 7.
app_ota_8	OTA application slot 8.
app_ota_9	OTA application slot 9.
app_ota_10	OTA application slot 10.
app_ota_11	OTA application slot 11.
app_ota_12	OTA application slot 12.
app_ota_13	OTA application slot 13.
app_ota_14	OTA application slot 14.
app_ota_15	OTA application slot 15.
app_test	Test application.
data_ota	OTA data.
data_phy	PHY init data.
data_nvs	NVS data.
data_coredump	Core dump data.
data_nvs_keys	NVS encryption keys.
data_efuse_em	eFuse emulation data
data_undefined	Undefined data.
data_esphttpd	ESPHTTPD data.
data_fat	FAT filesystem data.
data_spiffs	SPIFFS data.
data_littlefs	LittleFS data.
any	Match any subtype (for searching)

Definition at line 63 of file partition.hpp.

◆ type

enum class idfxx::partition::type : int

strong

Partition type.

Enumerator
app	Application partition.
data	Data partition.
bootloader	Bootloader partition.
partition_table	Partition table.
any	Match any partition type (for searching)

Definition at line 54 of file partition.hpp.

Constructor & Destructor Documentation

◆ partition() [1/2]

idfxx::partition::partition ( const partition & )

default

◆ partition() [2/2]

idfxx::partition::partition ( partition && )

default

Member Function Documentation

◆ address()

uint32_t idfxx::partition::address ( ) const

inline

Returns the starting address in flash.

Definition at line 220 of file partition.hpp.

◆ check_identity()

bool idfxx::partition::check_identity ( const partition & other ) const

Checks if two partitions have identical contents by comparing SHA-256 hashes.

Parameters

other The other partition to compare with.

Returns: true if the partitions have identical content.

◆ encrypted()

bool idfxx::partition::encrypted ( ) const

inline

Returns true if the partition is encrypted.

Definition at line 232 of file partition.hpp.

◆ erase_range()

void idfxx::partition::erase_range	(	size_t	offset,
		size_t	size
	)

inline

Erases a range of the partition.

Both offset and size must be aligned to erase_size().

Parameters

offset	Byte offset within the partition (must be erase-aligned).
size	Number of bytes to erase (must be erase-aligned).

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error on failure.

Definition at line 348 of file partition.hpp.

References size(), try_erase_range(), and idfxx::unwrap().

◆ erase_size()

uint32_t idfxx::partition::erase_size ( ) const

inline

Returns the erase block size.

Definition at line 226 of file partition.hpp.

◆ find() [1/2]

static partition idfxx::partition::find	(	enum type	type,
		enum subtype	subtype = `subtype::any`,
		std::string_view	label = `{}`
	)

static

Finds the first partition matching the given criteria.

Parameters

type	Partition type to match, or type::any for all types.
subtype	Partition subtype to match, or subtype::any for all subtypes.
label	Optional partition label to match. Empty matches all labels.

Returns: The matching partition.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error with idfxx::errc::not_found if no partition matches.

◆ find() [2/2]

static partition idfxx::partition::find ( std::string_view label )

static

Finds the first partition with the given label.

Searches across all partition types and subtypes.

Parameters

label Partition label to match.

Returns: The matching partition.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error with idfxx::errc::not_found if no partition matches.

◆ find_all()

static std::vector< partition > idfxx::partition::find_all	(	enum type	type = `type::any`,
		enum subtype	subtype = `subtype::any`,
		std::string_view	label = `{}`
	)

static

Finds all partitions matching the given criteria.

Parameters

type	Partition type to match, or type::any for all types.
subtype	Partition subtype to match, or subtype::any for all subtypes.
label	Optional partition label to match. Empty matches all labels.

Returns: A vector of matching partitions (may be empty).

◆ from_handle()

static constexpr partition idfxx::partition::from_handle ( const esp_partition_t * handle )

inlinestaticconstexpr

Constructs a partition from an ESP-IDF partition handle.

Parameters

handle Pointer to an ESP-IDF partition structure. Must not be null.

Returns: A partition wrapping the given handle.

Definition at line 198 of file partition.hpp.

◆ idf_handle()

constexpr const esp_partition_t * idfxx::partition::idf_handle ( ) const

inlineconstexpr

Returns the underlying ESP-IDF partition handle.

Definition at line 238 of file partition.hpp.

◆ label()

std::string_view idfxx::partition::label ( ) const

inline

Returns the partition label.

Definition at line 229 of file partition.hpp.

◆ mmap()

partition::mmap_handle idfxx::partition::mmap	(	size_t	offset,
		size_t	size,
		enum mmap_memory	memory = `mmap_memory::data`
	)		const

inline

Memory-maps a region of the partition.

Parameters

offset	Byte offset within the partition (must be aligned to 0x10000 for data, or SPI_FLASH_MMU_PAGE_SIZE for instruction memory).
size	Number of bytes to map.
memory	Memory type to map to.

Returns: A handle to the mapped memory region.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error on failure.

Definition at line 592 of file partition.hpp.

References idfxx::partition::mmap_handle::size(), try_mmap(), and idfxx::unwrap().

◆ operator=() [1/2]

partition & idfxx::partition::operator= ( const partition & )

default

◆ operator=() [2/2]

partition & idfxx::partition::operator= ( partition && )

default

◆ operator==()

constexpr bool idfxx::partition::operator== ( const partition & ) const

constexprdefaultnoexcept

Compares two partitions for equality.

◆ read() [1/2]

void idfxx::partition::read	(	size_t	offset,
		std::span< uint8_t >	dst
	)		const

inline

Reads data from the partition with decryption if applicable.

Parameters

offset	Byte offset within the partition.
dst	Destination span.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error on failure.

Definition at line 266 of file partition.hpp.

References try_read(), and idfxx::unwrap().

◆ read() [2/2]

void idfxx::partition::read	(	size_t	offset,
		void *	dst,
		size_t	size
	)		const

inline

Reads data from the partition with decryption if applicable.

Parameters

offset	Byte offset within the partition.
dst	Destination buffer.
size	Number of bytes to read.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error on failure.

Definition at line 255 of file partition.hpp.

References size(), try_read(), and idfxx::unwrap().

◆ read_raw() [1/2]

void idfxx::partition::read_raw	(	size_t	offset,
		std::span< uint8_t >	dst
	)		const

inline

Reads data from the partition without decryption.

Parameters

offset	Byte offset within the partition.
dst	Destination span.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error on failure.

Definition at line 312 of file partition.hpp.

References try_read_raw(), and idfxx::unwrap().

◆ read_raw() [2/2]

void idfxx::partition::read_raw	(	size_t	offset,
		void *	dst,
		size_t	size
	)		const

inline

Reads data from the partition without decryption.

Parameters

offset	Byte offset within the partition.
dst	Destination buffer.
size	Number of bytes to read.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error on failure.

Definition at line 301 of file partition.hpp.

References size(), try_read_raw(), and idfxx::unwrap().

◆ readonly()

bool idfxx::partition::readonly ( ) const

inline

Returns true if the partition is read-only.

Definition at line 235 of file partition.hpp.

◆ sha256()

std::array< uint8_t, 32 > idfxx::partition::sha256 ( ) const

inline

Computes the SHA-256 hash of the partition contents.

Returns: A 32-byte SHA-256 hash.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error on failure.

Definition at line 358 of file partition.hpp.

References try_sha256(), and idfxx::unwrap().

◆ size()

uint32_t idfxx::partition::size ( ) const

inline

Returns the partition size in bytes.

Definition at line 223 of file partition.hpp.

Referenced by erase_range(), read(), read_raw(), write(), and write_raw().

◆ subtype()

enum subtype idfxx::partition::subtype ( ) const

inline

Returns the partition subtype.

Definition at line 217 of file partition.hpp.

◆ try_erase_range()

result< void > idfxx::partition::try_erase_range	(	size_t	offset,
		size_t	size
	)

Erases a range of the partition.

Both offset and size must be aligned to erase_size().

Parameters

offset	Byte offset within the partition (must be erase-aligned).
size	Number of bytes to erase (must be erase-aligned).

Returns: Success, or an error.

Referenced by erase_range().

◆ try_find() [1/2]

static result< partition > idfxx::partition::try_find	(	enum type	type,
		enum subtype	subtype = `subtype::any`,
		std::string_view	label = `{}`
	)

static

Finds the first partition matching the given criteria.

Parameters

type	Partition type to match, or type::any for all types.
subtype	Partition subtype to match, or subtype::any for all subtypes.
label	Optional partition label to match. Empty matches all labels.

Returns: The matching partition, or an error.

Return values

idfxx::errc::not_found if no partition matches the criteria.

◆ try_find() [2/2]

static result< partition > idfxx::partition::try_find ( std::string_view label )

static

Finds the first partition with the given label.

Searches across all partition types and subtypes.

Parameters

label Partition label to match.

Returns: The matching partition, or an error.

Return values

idfxx::errc::not_found if no partition matches.

◆ try_mmap()

result< mmap_handle > idfxx::partition::try_mmap	(	size_t	offset,
		size_t	size,
		enum mmap_memory	memory = `mmap_memory::data`
	)		const

Memory-maps a region of the partition.

Parameters

offset	Byte offset within the partition (must be aligned to 0x10000 for data, or SPI_FLASH_MMU_PAGE_SIZE for instruction memory).
size	Number of bytes to map.
memory	Memory type to map to.

Returns: A handle to the mapped memory region, or an error.

Referenced by mmap().

◆ try_read() [1/2]

result< void > idfxx::partition::try_read	(	size_t	offset,
		std::span< uint8_t >	dst
	)		const

Reads data from the partition with decryption if applicable.

Parameters

offset	Byte offset within the partition.
dst	Destination span.

Returns: Success, or an error.

◆ try_read() [2/2]

result< void > idfxx::partition::try_read	(	size_t	offset,
		void *	dst,
		size_t	size
	)		const

Reads data from the partition with decryption if applicable.

Parameters

offset	Byte offset within the partition.
dst	Destination buffer.
size	Number of bytes to read.

Returns: Success, or an error.

Referenced by read(), and read().

◆ try_read_raw() [1/2]

result< void > idfxx::partition::try_read_raw	(	size_t	offset,
		std::span< uint8_t >	dst
	)		const

Reads data from the partition without decryption.

Parameters

offset	Byte offset within the partition.
dst	Destination span.

Returns: Success, or an error.

◆ try_read_raw() [2/2]

result< void > idfxx::partition::try_read_raw	(	size_t	offset,
		void *	dst,
		size_t	size
	)		const

Reads data from the partition without decryption.

Parameters

offset	Byte offset within the partition.
dst	Destination buffer.
size	Number of bytes to read.

Returns: Success, or an error.

Referenced by read_raw(), and read_raw().

◆ try_sha256()

result< std::array< uint8_t, 32 > > idfxx::partition::try_sha256 ( ) const

Computes the SHA-256 hash of the partition contents.

Returns: A 32-byte SHA-256 hash, or an error.

Referenced by sha256().

◆ try_write() [1/2]

result< void > idfxx::partition::try_write	(	size_t	offset,
		const void *	src,
		size_t	size
	)

Writes data to the partition with encryption if applicable.

Parameters

offset	Byte offset within the partition.
src	Source buffer.
size	Number of bytes to write.

Returns: Success, or an error.

Referenced by write(), and write().

◆ try_write() [2/2]

result< void > idfxx::partition::try_write	(	size_t	offset,
		std::span< const uint8_t >	src
	)

Writes data to the partition with encryption if applicable.

Parameters

offset	Byte offset within the partition.
src	Source span.

Returns: Success, or an error.

◆ try_write_raw() [1/2]

result< void > idfxx::partition::try_write_raw	(	size_t	offset,
		const void *	src,
		size_t	size
	)

Writes data to the partition without encryption.

Parameters

offset	Byte offset within the partition.
src	Source buffer.
size	Number of bytes to write.

Returns: Success, or an error.

Referenced by write_raw(), and write_raw().

◆ try_write_raw() [2/2]

result< void > idfxx::partition::try_write_raw	(	size_t	offset,
		std::span< const uint8_t >	src
	)

Writes data to the partition without encryption.

Parameters

offset	Byte offset within the partition.
src	Source span.

Returns: Success, or an error.

◆ type()

enum type idfxx::partition::type ( ) const

inline

Returns the partition type.

Definition at line 214 of file partition.hpp.

◆ write() [1/2]

void idfxx::partition::write	(	size_t	offset,
		const void *	src,
		size_t	size
	)

inline

Writes data to the partition with encryption if applicable.

Parameters

offset	Byte offset within the partition.
src	Source buffer.
size	Number of bytes to write.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error on failure.

Definition at line 278 of file partition.hpp.

References size(), try_write(), and idfxx::unwrap().

◆ write() [2/2]

void idfxx::partition::write	(	size_t	offset,
		std::span< const uint8_t >	src
	)

inline

Writes data to the partition with encryption if applicable.

Parameters

offset	Byte offset within the partition.
src	Source span.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error on failure.

Definition at line 289 of file partition.hpp.

References try_write(), and idfxx::unwrap().

◆ write_raw() [1/2]

void idfxx::partition::write_raw	(	size_t	offset,
		const void *	src,
		size_t	size
	)

inline

Writes data to the partition without encryption.

Parameters

offset	Byte offset within the partition.
src	Source buffer.
size	Number of bytes to write.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error on failure.

Definition at line 324 of file partition.hpp.

References size(), try_write_raw(), and idfxx::unwrap().

◆ write_raw() [2/2]

void idfxx::partition::write_raw	(	size_t	offset,
		std::span< const uint8_t >	src
	)

inline

Writes data to the partition without encryption.

Parameters

offset	Byte offset within the partition.
src	Source span.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error on failure.

Definition at line 335 of file partition.hpp.

References try_write_raw(), and idfxx::unwrap().

The documentation for this class was generated from the following file:

idfxx_partition/include/idfxx/partition.hpp

Classes

Public Types

Public Member Functions

Static Public Member Functions

Detailed Description

Member Enumeration Documentation

◆ mmap_memory

◆ subtype

◆ type

Constructor & Destructor Documentation

◆ partition() [1/2]

◆ partition() [2/2]

Member Function Documentation

◆ address()

◆ check_identity()

◆ encrypted()

◆ erase_range()

◆ erase_size()

◆ find() [1/2]

◆ find() [2/2]

◆ find_all()

◆ from_handle()

◆ idf_handle()

◆ label()

◆ mmap()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ operator==()

◆ read() [1/2]

◆ read() [2/2]

◆ read_raw() [1/2]

◆ read_raw() [2/2]

◆ readonly()

◆ sha256()

◆ size()

◆ subtype()

◆ try_erase_range()

◆ try_find() [1/2]

◆ try_find() [2/2]

◆ try_mmap()

◆ try_read() [1/2]

◆ try_read() [2/2]

◆ try_read_raw() [1/2]

◆ try_read_raw() [2/2]

◆ try_sha256()

◆ try_write() [1/2]

◆ try_write() [2/2]

◆ try_write_raw() [1/2]

◆ try_write_raw() [2/2]

◆ type()

◆ write() [1/2]

◆ write() [2/2]

◆ write_raw() [1/2]

◆ write_raw() [2/2]