Mirrors/esp-idf
1
0
Fork 0
mirror of https://github.com/espressif/esp-idf.git synced 2026-08-13 04:42:01 +03:00
Code Issues Packages Projects Releases Wiki Activity

fix(storage/esp_blockdev): Update docs for doxygen

Browse Source
This commit is contained in:
Tomáš Rohlínek
2025-11-19 10:11:17 +01:00
parent 8232fe077a
commit ec1969c1fc
2 changed files with 33 additions and 13 deletions
Download Patch File Download Diff File Expand all files Collapse all files

44
components/esp_blockdev/include/esp_blockdev.h
View File

@@ -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_<INST>_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"