450 lines
14 KiB
C
450 lines
14 KiB
C
/****************************************************************************
|
|
* boot/nuttx/include/flash_map_backend/flash_map_backend.h
|
|
*
|
|
* Copyright (c) 2021 Espressif Systems (Shanghai) Co., Ltd.
|
|
*
|
|
* Licensed under the Apache License, Version 2.0 (the "License");
|
|
* you may not use this file except in compliance with the License.
|
|
* You may obtain a copy of the License at
|
|
*
|
|
* http://www.apache.org/licenses/LICENSE-2.0
|
|
*
|
|
* Unless required by applicable law or agreed to in writing, software
|
|
* distributed under the License is distributed on an "AS IS" BASIS,
|
|
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
* See the License for the specific language governing permissions and
|
|
* limitations under the License.
|
|
*
|
|
****************************************************************************/
|
|
|
|
#ifndef __BOOT_NUTTX_INCLUDE_FLASH_MAP_BACKEND_FLASH_MAP_BACKEND_H
|
|
#define __BOOT_NUTTX_INCLUDE_FLASH_MAP_BACKEND_FLASH_MAP_BACKEND_H
|
|
|
|
/****************************************************************************
|
|
* Included Files
|
|
****************************************************************************/
|
|
|
|
#include <inttypes.h>
|
|
|
|
#ifdef __cplusplus
|
|
extern "C" {
|
|
#endif
|
|
|
|
/****************************************************************************
|
|
* Public Types
|
|
****************************************************************************/
|
|
|
|
/* Structure describing a flash area. */
|
|
|
|
struct flash_area
|
|
{
|
|
/* MCUboot-API fields */
|
|
|
|
uint8_t fa_id; /* The slot/scratch ID */
|
|
uint8_t fa_device_id; /* The device ID (usually there's only one) */
|
|
uint16_t pad16; /* Padding */
|
|
uint32_t fa_off; /* The flash offset from the beginning */
|
|
uint32_t fa_size; /* The size of this sector */
|
|
|
|
/* NuttX implementation-specific fields */
|
|
|
|
const char *fa_mtd_path; /* Path for the MTD partition */
|
|
};
|
|
|
|
/* Structure describing a sector within a flash area. */
|
|
|
|
struct flash_sector
|
|
{
|
|
/* Offset of this sector, from the start of its flash area (not device). */
|
|
|
|
uint32_t fs_off;
|
|
|
|
/* Size of this sector, in bytes. */
|
|
|
|
uint32_t fs_size;
|
|
};
|
|
|
|
/****************************************************************************
|
|
* Inline Functions
|
|
****************************************************************************/
|
|
|
|
/****************************************************************************
|
|
* Name: flash_area_get_id
|
|
*
|
|
* Description:
|
|
* Obtain the ID of a given flash area.
|
|
*
|
|
* Input Parameters:
|
|
* fa - Flash area.
|
|
*
|
|
* Returned Value:
|
|
* The ID of the requested flash area.
|
|
*
|
|
****************************************************************************/
|
|
|
|
static inline uint8_t flash_area_get_id(const struct flash_area *fa)
|
|
{
|
|
return fa->fa_id;
|
|
}
|
|
|
|
/****************************************************************************
|
|
* Name: flash_area_get_device_id
|
|
*
|
|
* Description:
|
|
* Obtain the ID of the device in which a given flash area resides on.
|
|
*
|
|
* Input Parameters:
|
|
* fa - Flash area.
|
|
*
|
|
* Returned Value:
|
|
* The device ID of the requested flash area.
|
|
*
|
|
****************************************************************************/
|
|
|
|
static inline uint8_t flash_area_get_device_id(const struct flash_area *fa)
|
|
{
|
|
return fa->fa_device_id;
|
|
}
|
|
|
|
/****************************************************************************
|
|
* Name: flash_area_get_sector
|
|
*
|
|
* Description:
|
|
* Retrieve the flash sector a given offset belongs to.
|
|
*
|
|
* Input Parameters:
|
|
* fap - flash area structure
|
|
* off - address offset.
|
|
* sector - flash sector
|
|
*
|
|
* Returned Value:
|
|
* Returns 0 on success, or an error code on failure.
|
|
*
|
|
****************************************************************************/
|
|
|
|
int flash_area_get_sector(const struct flash_area *fap, off_t off,
|
|
struct flash_sector *fs);
|
|
|
|
/****************************************************************************
|
|
* Name: flash_area_get_off
|
|
*
|
|
* Description:
|
|
* Obtain the offset, from the beginning of a device, where a given flash
|
|
* area starts at.
|
|
*
|
|
* Input Parameters:
|
|
* fa - Flash area.
|
|
*
|
|
* Returned Value:
|
|
* The offset value of the requested flash area.
|
|
*
|
|
****************************************************************************/
|
|
|
|
static inline uint32_t flash_area_get_off(const struct flash_area *fa)
|
|
{
|
|
return fa->fa_off;
|
|
}
|
|
|
|
/****************************************************************************
|
|
* Name: flash_area_get_size
|
|
*
|
|
* Description:
|
|
* Obtain the size, from the offset, of a given flash area.
|
|
*
|
|
* Input Parameters:
|
|
* fa - Flash area.
|
|
*
|
|
* Returned Value:
|
|
* The size value of the requested flash area.
|
|
*
|
|
****************************************************************************/
|
|
|
|
static inline uint32_t flash_area_get_size(const struct flash_area *fa)
|
|
{
|
|
return fa->fa_size;
|
|
}
|
|
|
|
/****************************************************************************
|
|
* Name: flash_sector_get_off
|
|
*
|
|
* Description:
|
|
* Obtain the offset, from the beginning of its flash area, where a given
|
|
* flash sector starts at.
|
|
*
|
|
* Input Parameters:
|
|
* fs - Flash sector.
|
|
*
|
|
* Returned Value:
|
|
* The offset value of the requested flash sector.
|
|
*
|
|
****************************************************************************/
|
|
|
|
static inline uint32_t flash_sector_get_off(const struct flash_sector *fs)
|
|
{
|
|
return fs->fs_off;
|
|
}
|
|
|
|
/****************************************************************************
|
|
* Name: flash_sector_get_size
|
|
*
|
|
* Description:
|
|
* Obtain the size, from the offset, of a given flash sector.
|
|
*
|
|
* Input Parameters:
|
|
* fs - Flash sector.
|
|
*
|
|
* Returned Value:
|
|
* The size in bytes of the requested flash sector.
|
|
*
|
|
****************************************************************************/
|
|
|
|
static inline uint32_t flash_sector_get_size(const struct flash_sector *fs)
|
|
{
|
|
return fs->fs_size;
|
|
}
|
|
|
|
/****************************************************************************
|
|
* Public Function Prototypes
|
|
****************************************************************************/
|
|
|
|
/****************************************************************************
|
|
* Name: flash_area_open
|
|
*
|
|
* Description:
|
|
* Retrieve flash area from the flash map for a given partition.
|
|
*
|
|
* Input Parameters:
|
|
* id - ID of the flash partition.
|
|
*
|
|
* Output Parameters:
|
|
* fa - Pointer which will contain the reference to flash_area.
|
|
* If ID is unknown, it will be NULL on output.
|
|
*
|
|
* Returned Value:
|
|
* Zero on success, or negative value in case of error.
|
|
*
|
|
****************************************************************************/
|
|
|
|
int flash_area_open(uint8_t id, const struct flash_area **fa);
|
|
|
|
/****************************************************************************
|
|
* Name: flash_area_close
|
|
*
|
|
* Description:
|
|
* Close a given flash area.
|
|
*
|
|
* Input Parameters:
|
|
* fa - Flash area to be closed.
|
|
*
|
|
* Returned Value:
|
|
* None.
|
|
*
|
|
****************************************************************************/
|
|
|
|
void flash_area_close(const struct flash_area *fa);
|
|
|
|
/****************************************************************************
|
|
* Name: flash_area_read
|
|
*
|
|
* Description:
|
|
* Read data from flash area.
|
|
* Area readout boundaries are asserted before read request. API has the
|
|
* same limitation regarding read-block alignment and size as the
|
|
* underlying flash driver.
|
|
*
|
|
* Input Parameters:
|
|
* fa - Flash area to be read.
|
|
* off - Offset relative from beginning of flash area to be read.
|
|
* len - Number of bytes to read.
|
|
*
|
|
* Output Parameters:
|
|
* dst - Buffer to store read data.
|
|
*
|
|
* Returned Value:
|
|
* Zero on success, or negative value in case of error.
|
|
*
|
|
****************************************************************************/
|
|
|
|
int flash_area_read(const struct flash_area *fa, uint32_t off,
|
|
void *dst, uint32_t len);
|
|
|
|
/****************************************************************************
|
|
* Name: flash_area_write
|
|
*
|
|
* Description:
|
|
* Write data to flash area.
|
|
* Area write boundaries are asserted before write request. API has the
|
|
* same limitation regarding write-block alignment and size as the
|
|
* underlying flash driver.
|
|
*
|
|
* Input Parameters:
|
|
* fa - Flash area to be written.
|
|
* off - Offset relative from beginning of flash area to be written.
|
|
* src - Buffer with data to be written.
|
|
* len - Number of bytes to write.
|
|
*
|
|
* Returned Value:
|
|
* Zero on success, or negative value in case of error.
|
|
*
|
|
****************************************************************************/
|
|
|
|
int flash_area_write(const struct flash_area *fa, uint32_t off,
|
|
const void *src, uint32_t len);
|
|
|
|
/****************************************************************************
|
|
* Name: flash_area_erase
|
|
*
|
|
* Description:
|
|
* Erase a given flash area range.
|
|
* Area boundaries are asserted before erase request. API has the same
|
|
* limitation regarding erase-block alignment and size as the underlying
|
|
* flash driver.
|
|
*
|
|
* Input Parameters:
|
|
* fa - Flash area to be erased.
|
|
* off - Offset relative from beginning of flash area to be erased.
|
|
* len - Number of bytes to be erase.
|
|
*
|
|
* Returned Value:
|
|
* Zero on success, or negative value in case of error.
|
|
*
|
|
****************************************************************************/
|
|
|
|
int flash_area_erase(const struct flash_area *fa, uint32_t off,
|
|
uint32_t len);
|
|
|
|
/****************************************************************************
|
|
* Name: flash_area_align
|
|
*
|
|
* Description:
|
|
* Get write block size of the flash area.
|
|
* Write block size might be treated as read block size, although most
|
|
* drivers support unaligned readout.
|
|
*
|
|
* Input Parameters:
|
|
* fa - Flash area.
|
|
*
|
|
* Returned Value:
|
|
* Alignment restriction for flash writes in the given flash area.
|
|
*
|
|
****************************************************************************/
|
|
|
|
uint32_t flash_area_align(const struct flash_area *fa);
|
|
|
|
/****************************************************************************
|
|
* Name: flash_area_erased_val
|
|
*
|
|
* Description:
|
|
* Get the value expected to be read when accessing any erased flash byte.
|
|
* This API is compatible with the MCUboot's porting layer.
|
|
*
|
|
* Input Parameters:
|
|
* fa - Flash area.
|
|
*
|
|
* Returned Value:
|
|
* Byte value of erased memory.
|
|
*
|
|
****************************************************************************/
|
|
|
|
uint8_t flash_area_erased_val(const struct flash_area *fa);
|
|
|
|
/****************************************************************************
|
|
* Name: flash_area_get_sectors
|
|
*
|
|
* Description:
|
|
* Retrieve info about sectors within the area.
|
|
*
|
|
* Input Parameters:
|
|
* fa_id - ID of the flash area whose info will be retrieved.
|
|
* count - On input, represents the capacity of the sectors buffer.
|
|
*
|
|
* Output Parameters:
|
|
* count - On output, it shall contain the number of retrieved sectors.
|
|
* sectors - Buffer for sectors data.
|
|
*
|
|
* Returned Value:
|
|
* Zero on success, or negative value in case of error.
|
|
*
|
|
****************************************************************************/
|
|
|
|
int flash_area_get_sectors(int fa_id, uint32_t *count,
|
|
struct flash_sector *sectors);
|
|
|
|
/****************************************************************************
|
|
* Name: flash_area_id_from_multi_image_slot
|
|
*
|
|
* Description:
|
|
* Return the flash area ID for a given slot and a given image index
|
|
* (in case of a multi-image setup).
|
|
*
|
|
* Input Parameters:
|
|
* image_index - Index of the image.
|
|
* slot - Image slot, which may be 0 (primary) or 1 (secondary).
|
|
*
|
|
* Returned Value:
|
|
* Flash area ID (0 or 1), or negative value in case the requested slot
|
|
* is invalid.
|
|
*
|
|
****************************************************************************/
|
|
|
|
int flash_area_id_from_multi_image_slot(int image_index, int slot);
|
|
|
|
/****************************************************************************
|
|
* Name: flash_area_id_from_image_slot
|
|
*
|
|
* Description:
|
|
* Return the flash area ID for a given slot.
|
|
*
|
|
* Input Parameters:
|
|
* slot - Image slot, which may be 0 (primary) or 1 (secondary).
|
|
*
|
|
* Returned Value:
|
|
* Flash area ID (0 or 1), or negative value in case the requested slot
|
|
* is invalid.
|
|
*
|
|
****************************************************************************/
|
|
|
|
int flash_area_id_from_image_slot(int slot);
|
|
|
|
/****************************************************************************
|
|
* Name: flash_area_id_to_multi_image_slot
|
|
*
|
|
* Description:
|
|
* Convert the specified flash area ID and image index (in case of a
|
|
* multi-image setup) to an image slot index.
|
|
*
|
|
* Input Parameters:
|
|
* image_index - Index of the image.
|
|
* area_id - Unique identifier that is represented by fa_id in the
|
|
* flash_area struct.
|
|
* Returned Value:
|
|
* Image slot index (0 or 1), or negative value in case ID doesn't
|
|
* correspond to an image slot.
|
|
*
|
|
****************************************************************************/
|
|
|
|
int flash_area_id_to_multi_image_slot(int image_index, int area_id);
|
|
|
|
/****************************************************************************
|
|
* Name: flash_area_id_from_image_offset
|
|
*
|
|
* Description:
|
|
* Return the flash area ID for a given image offset.
|
|
*
|
|
* Input Parameters:
|
|
* offset - Image offset.
|
|
*
|
|
* Returned Value:
|
|
* Flash area ID (0 or 1), or negative value in case the requested offset
|
|
* is invalid.
|
|
*
|
|
****************************************************************************/
|
|
|
|
int flash_area_id_from_image_offset(uint32_t offset);
|
|
|
|
#ifdef __cplusplus
|
|
}
|
|
#endif
|
|
|
|
#endif /* __BOOT_NUTTX_INCLUDE_FLASH_MAP_BACKEND_FLASH_MAP_BACKEND_H */
|