From ec1969c1fcfdbb038fd759d2079ad48af649d7ea Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tom=C3=A1=C5=A1=20Rohl=C3=ADnek?= Date: Wed, 19 Nov 2025 10:11:17 +0100 Subject: [PATCH] fix(storage/esp_blockdev): Update docs for doxygen --- components/esp_blockdev/README.md | 2 +- .../esp_blockdev/include/esp_blockdev.h | 44 ++++++++++++++----- 2 files changed, 33 insertions(+), 13 deletions(-) diff --git a/components/esp_blockdev/README.md b/components/esp_blockdev/README.md index a869b63f6cb..d90e22d751f 100644 --- a/components/esp_blockdev/README.md +++ b/components/esp_blockdev/README.md @@ -28,7 +28,7 @@ The BDL interface follows the Open-Closed Principle (open for extension, closed The BDL interface structure is described by the following pseudo-code: ``` -struct esp_blockdev_t { +typedef struct esp_blockdev { //DEVICE FLAGS esp_blockdev_flags_t device_flags diff --git a/components/esp_blockdev/include/esp_blockdev.h b/components/esp_blockdev/include/esp_blockdev.h index f4becdddbd4..f388c82b7c4 100644 --- a/components/esp_blockdev/include/esp_blockdev.h +++ b/components/esp_blockdev/include/esp_blockdev.h @@ -40,7 +40,13 @@ extern "C" { #define ESP_BLOCKDEV_CMD_MARK_DELETED ESP_BLOCKDEV_CMD_SYSTEM_BASE /*!< mark given range as invalid, data to be deleted/overwritten eventually [ esp_blockdev_cmd_arg_erase_t* ]*/ #define ESP_BLOCKDEV_CMD_ERASE_CONTENTS (ESP_BLOCKDEV_CMD_SYSTEM_BASE + 1) /*!< erase required range and set the contents to the device's default bit values [ esp_blockdev_cmd_arg_erase_t* ]*/ -typedef struct esp_blockdev_cmd_arg_erase_t { +/** + * @brief Arguments for block device erase control commands + * + * Supplied to ESP_BLOCKDEV_CMD_ERASE_CONTENTS and similar ioctls to describe + * the erase window. + */ +typedef struct { uint64_t start_addr; /*!< IN - starting address of the disk space to erase/trim/discard/sanitize (in bytes), must be a multiple of erase block size */ size_t erase_len; /*!< IN - size of the area to erase/trim/discard/sanitize (in bytes), must be a multiple of erase block size */ } esp_blockdev_cmd_arg_erase_t; @@ -52,6 +58,17 @@ typedef struct esp_blockdev_cmd_arg_erase_t { * * @note Convenience macros ESP_BLOCKDEV_FLAGS__CONFIG_DEFAULT() provide the most common setup of usual ESP-IDF component equipped with BDL interface. They can be used as a starting point for own initializers. */ +#if defined(__DOXYGEN__) +typedef struct { + uint32_t read_only: 1; /*!< no erase/write operations allowed */ + uint32_t encrypted: 1; /*!< the device data is encrypted */ + uint32_t erase_before_write: 1; /*!< erasing required before any write operation */ + uint32_t and_type_write: 1; /*!< 0-bits can't be changed to 1-bits - NAND/NOR flash behavior */ + uint32_t default_val_after_erase: 1; /*!< default bit value after erasing (0 or 1) */ + uint32_t reserved: 27; /*!< Reserved for future blockdev flags */ + uint32_t val; /*!< Raw bitfield view for bulk initialization */ +} esp_blockdev_flags_t; +#else typedef union { struct { uint32_t read_only: 1; /*!< no erase/write operations allowed */ @@ -59,10 +76,11 @@ typedef union { uint32_t erase_before_write: 1; /*!< erasing required before any write operation */ uint32_t and_type_write: 1; /*!< 0-bits can't be changed to 1-bits - NAND/NOR flash behavior */ uint32_t default_val_after_erase: 1; /*!< default bit value after erasing (0 or 1) */ - uint32_t reserved: 27; + uint32_t reserved: 27; /*!< Reserved for future blockdev flags */ }; - uint32_t val; + uint32_t val; /*!< Raw bitfield view for bulk initialization */ } esp_blockdev_flags_t; +#endif #define ESP_BLOCKDEV_FLAGS_CONFIG_DEFAULT() { \ { \ @@ -89,7 +107,7 @@ typedef union { * * Various block size parameters needed for proper R/W/E processing on given device. */ -typedef struct esp_blockdev_geometry_t { +typedef struct { /** Size of the device disk space (in bytes). * Mandatory parameter. @@ -130,10 +148,12 @@ typedef struct esp_blockdev_geometry_t { } esp_blockdev_geometry_t; +typedef struct esp_blockdev esp_blockdev_t; + /** Standard BDL access handle, the only public BDL instance identifier. * Allocated and initialized by the device's class factory, optionally closed by the device release handler. */ -typedef struct esp_blockdev_t* esp_blockdev_handle_t; +typedef esp_blockdev_t* esp_blockdev_handle_t; #define ESP_BLOCKDEV_HANDLE_INVALID NULL /** @@ -141,7 +161,7 @@ typedef struct esp_blockdev_t* esp_blockdev_handle_t; * * Various block operations needed for proper R/W/E processing on given device. */ -typedef struct esp_blockdev_ops_t { +typedef struct { /** READ operation: * Read required number of bytes from the device at given offset, store the data into the output buffer. @@ -213,16 +233,16 @@ typedef struct esp_blockdev_ops_t { * @note The device context pointer is used to store the device-specific context. It is not used by the BDL layer and is intended to be used by the device implementation. * @note The ops pointer holds the address of the device operations structure which can be shared by multiple device instances of the same type (driver). */ -typedef struct esp_blockdev_t { +struct esp_blockdev { /* Device context pointer */ - void* ctx; + void* ctx; /*!< Owner-provided private data */ - esp_blockdev_flags_t device_flags; - esp_blockdev_geometry_t geometry; - const esp_blockdev_ops_t* ops; + esp_blockdev_flags_t device_flags; /*!< Capabilities and requirements */ + esp_blockdev_geometry_t geometry; /*!< Operation granularity and capacity */ + const esp_blockdev_ops_t* ops; /*!< Function table implementing the device */ -} esp_blockdev_t; +}; #ifdef __cplusplus } // extern "C"