doc: documentation of flash_area and flash_map
Initial documentation. fixes #14789 Signed-off-by: Andrzej Puzdrowski <andrzej.puzdrowski@nordicsemi.no>
This commit is contained in:
Andrzej Puzdrowski
Anas Nashif
parent
dea4394ef4
commit
4a8e4de0f1
37
doc/reference/storage/flash_map/flash_map.rst
Normal file
37
doc/reference/storage/flash_map/flash_map.rst
Normal file
|
|
@ -0,0 +1,37 @@
|
|||
.. _flash_map_flash_area:
|
||||
|
||||
Flash map (flash_map)
|
||||
##########################
|
||||
|
||||
Flash map is a way for storing flash partitioning information in one central
|
||||
location in flash_area structures array form.
|
||||
|
||||
Flash map is generated from DTS based on content of :ref:`flash_partitions`
|
||||
nodes.
|
||||
The flash_area API provides a way to access data in the flash map.
|
||||
The flash_area_open() API is the interface for obtaining the flash partitions
|
||||
flash_area from the flash map.
|
||||
|
||||
|
||||
Flash Area API (flash_area)
|
||||
###########################
|
||||
|
||||
The flash_area concept combines methods for operating on a flash chunk
|
||||
together with a description of this chunk. Its methods are basically wrappers
|
||||
around the flash API, with input parameter range checks. Not all flash
|
||||
operation are wrapped so an API call to retrieve the flash area driver is
|
||||
included as well. The flash area methods are designed to be used along with
|
||||
the flash_area structures of flash_map and user-specific flash_areas, with
|
||||
the exception of the area_open API used to fetch a flash_area from
|
||||
the flash_map.
|
||||
|
||||
|
||||
API Reference
|
||||
*************
|
||||
|
||||
flash_area API
|
||||
==============
|
||||
|
||||
.. doxygengroup:: flash_area_api
|
||||
:project: Zephyr
|
||||
|
||||
|
|
@ -9,3 +9,4 @@ Storage
|
|||
settings/settings.rst
|
||||
nvs/nvs.rst
|
||||
disk/sdhc.rst
|
||||
flash_map/flash_map.rst
|
||||
|
|
|
|||
|
|
@ -5,9 +5,22 @@
|
|||
* SPDX-License-Identifier: Apache-2.0
|
||||
*/
|
||||
|
||||
/**
|
||||
* @file
|
||||
* @brief Public API for flash map
|
||||
*/
|
||||
|
||||
#ifndef ZEPHYR_INCLUDE_FLASH_MAP_H_
|
||||
#define ZEPHYR_INCLUDE_FLASH_MAP_H_
|
||||
|
||||
/**
|
||||
* @brief Abstraction over flash area and its driver which helps to operate on
|
||||
* flash regions easily and effectively.
|
||||
*
|
||||
* @defgroup flash_area_api flash area Interface
|
||||
* @{
|
||||
*/
|
||||
|
||||
#ifdef __cplusplus
|
||||
extern "C" {
|
||||
#endif
|
||||
|
|
@ -33,47 +46,128 @@ extern "C" {
|
|||
#include <stddef.h>
|
||||
#include <sys/types.h>
|
||||
|
||||
#define SOC_FLASH_0_ID 0 /* device_id for SoC flash memory driver */
|
||||
#define SPI_FLASH_0_ID 1 /* device_id for external SPI flash driver */
|
||||
#define SOC_FLASH_0_ID 0 /** device_id for SoC flash memory driver */
|
||||
#define SPI_FLASH_0_ID 1 /** device_id for external SPI flash driver */
|
||||
|
||||
/**
|
||||
* @brief Structure for store flash partition data
|
||||
*
|
||||
* It is used as the flash_map array entry or stand-alone user data. Structure
|
||||
* contains all data needed to operate on the flash partitions.
|
||||
*/
|
||||
struct flash_area {
|
||||
u8_t fa_id;
|
||||
u8_t fa_id; /** ID of flash area */
|
||||
u8_t fa_device_id;
|
||||
u16_t pad16;
|
||||
off_t fa_off;
|
||||
size_t fa_size;
|
||||
const char *fa_dev_name;
|
||||
off_t fa_off; /** flash partition offset */
|
||||
size_t fa_size; /** flash partition size */
|
||||
const char *fa_dev_name; /** flash device name */
|
||||
};
|
||||
|
||||
/**
|
||||
* @brief Structure for transfer flash sector boundaries
|
||||
*
|
||||
* This temlate is use for presentation of flash memory structure. It consume
|
||||
* much less RAM than @ref flash_area
|
||||
*/
|
||||
struct flash_sector {
|
||||
off_t fs_off;
|
||||
size_t fs_size;
|
||||
off_t fs_off; /** flash sector offset */
|
||||
size_t fs_size; /** flash sector size */
|
||||
};
|
||||
|
||||
/*
|
||||
* Start using flash area.
|
||||
/**
|
||||
* @brief Retrieve partitions flash area form the flash_mpa.
|
||||
*
|
||||
* Function Retrieves flash_area form flash_map for given partition.
|
||||
*
|
||||
* @param[in] id ID of the flash partition.
|
||||
* @param[out] fa Pointer which has to refernce flash_area. If
|
||||
* @p ID is unknown, it will be NULL on output.
|
||||
*/
|
||||
int flash_area_open(u8_t id, const struct flash_area **fa);
|
||||
|
||||
/**
|
||||
* @brief Close flash_area
|
||||
*
|
||||
* Reserved for future usage and external projects compatibility reason.
|
||||
* Currently is NOP.
|
||||
*
|
||||
* @param[in] fa Flash area to be closed.
|
||||
*/
|
||||
void flash_area_close(const struct flash_area *fa);
|
||||
|
||||
/*
|
||||
* Read/write/erase. Offset is relative from beginning of flash area.
|
||||
/**
|
||||
* @brief Read flash area data
|
||||
*
|
||||
* Read data from flash area. Area readout boundaries are asserted before read
|
||||
* request. API has the same limitation regard read-block alignment and size
|
||||
* as wrapped flash driver.
|
||||
*
|
||||
* @param[in] fa Flash area
|
||||
* @param[in] off Offset relative from beginning of flash area to read
|
||||
* @param[out] dst Buffer to store read data
|
||||
* @param[in] len Number of bytes to read
|
||||
*
|
||||
* @return 0 on success, negative errno code on fail.
|
||||
*/
|
||||
int flash_area_read(const struct flash_area *fa, off_t off, void *dst,
|
||||
size_t len);
|
||||
|
||||
/**
|
||||
* @brief Write data to flash area
|
||||
*
|
||||
* Write data to flash area. Area write boundaries are asserted before write
|
||||
* request. API has the same limitation regard write-block alignment and size
|
||||
* as wrapped flash driver.
|
||||
*
|
||||
* @param[in] fa Flash area
|
||||
* @param[in] off Offset relative from beginning of flash area to read
|
||||
* @param[out] src Buffer with data to be written
|
||||
* @param[in] len Number of bytes to write
|
||||
*
|
||||
* @return 0 on success, negative errno code on fail.
|
||||
*/
|
||||
int flash_area_write(const struct flash_area *fa, off_t off, const void *src,
|
||||
size_t len);
|
||||
int flash_area_erase(const struct flash_area *fa, off_t off, size_t len);
|
||||
/* int flash_area_is_empty(const struct flash_area *, bool *); */
|
||||
|
||||
/*
|
||||
* Alignment restriction for flash writes.
|
||||
/**
|
||||
* @brief Erase flash area
|
||||
*
|
||||
* Erase given flash area range. Area boundaries are asserted before erase
|
||||
* request. API has the same limitation regard erase-block alignment and size
|
||||
* as wrapped flash driver.
|
||||
*
|
||||
* @param[in] fa Flash area
|
||||
* @param[in] off Offset relative from beginning of flash area.
|
||||
* @param[in] len Number of bytes to be erase
|
||||
*
|
||||
* @return 0 on success, negative errno code on fail.
|
||||
*/
|
||||
int flash_area_erase(const struct flash_area *fa, off_t off, size_t len);
|
||||
|
||||
/**
|
||||
* @brief Get write block size of the flash area
|
||||
*
|
||||
* Currently write block size might be treated as read block size, altought
|
||||
* most of drivers supports unaligned readout.
|
||||
*
|
||||
* @param[in] fa Flash area
|
||||
*
|
||||
* @return Alignment restriction for flash writes in [B].
|
||||
*/
|
||||
u8_t flash_area_align(const struct flash_area *fa);
|
||||
|
||||
/*
|
||||
* Given flash area ID, return info about sectors within the area.
|
||||
* Retrieve info about sectors within the area.
|
||||
*
|
||||
* @param[in] fa_id Given flash area ID
|
||||
* @param[out] sectors buffer for sectors data
|
||||
* @param[in,out] count On input Capacity of @p sectors, on output number of
|
||||
* sectors Retrieved.
|
||||
*
|
||||
* @return 0 on success, negative errno code on fail. Especially returns
|
||||
* -ENOMEM if There are too many flash pages on the flash_area to fit in the
|
||||
* array.
|
||||
*/
|
||||
int flash_area_get_sectors(int fa_id, u32_t *count,
|
||||
struct flash_sector *sectors);
|
||||
|
|
@ -82,7 +176,7 @@ int flash_area_get_sectors(int fa_id, u32_t *count,
|
|||
* Check whether given flash area has supporting flash driver
|
||||
* in the system.
|
||||
*
|
||||
* @param fa Flash area.
|
||||
* @param[in] fa Flash area.
|
||||
*
|
||||
* @return 1 On success. -ENODEV if no driver match.
|
||||
*/
|
||||
|
|
@ -101,4 +195,8 @@ struct device *flash_area_get_device(const struct flash_area *fa);
|
|||
}
|
||||
#endif
|
||||
|
||||
/**
|
||||
* @}
|
||||
*/
|
||||
|
||||
#endif /* ZEPHYR_INCLUDE_FLASH_MAP_H_ */
|
||||
|
|
|
|||
Loading…
Reference in a new issue