342 lines
15 KiB
C
342 lines
15 KiB
C
|
/**
|
||
|
|
* Copyright (c) 2016 - 2020, Nordic Semiconductor ASA
|
||
|
|
*
|
||
|
|
* All rights reserved.
|
||
|
|
*
|
||
|
|
* Redistribution and use in source and binary forms, with or without modification,
|
||
|
|
* are permitted provided that the following conditions are met:
|
||
|
|
*
|
||
|
|
* 1. Redistributions of source code must retain the above copyright notice, this
|
||
|
|
* list of conditions and the following disclaimer.
|
||
|
|
*
|
||
|
|
* 2. Redistributions in binary form, except as embedded into a Nordic
|
||
|
|
* Semiconductor ASA integrated circuit in a product or a software update for
|
||
|
|
* such product, must reproduce the above copyright notice, this list of
|
||
|
|
* conditions and the following disclaimer in the documentation and/or other
|
||
|
|
* materials provided with the distribution.
|
||
|
|
*
|
||
|
|
* 3. Neither the name of Nordic Semiconductor ASA nor the names of its
|
||
|
|
* contributors may be used to endorse or promote products derived from this
|
||
|
|
* software without specific prior written permission.
|
||
|
|
*
|
||
|
|
* 4. This software, with or without modification, must only be used with a
|
||
|
|
* Nordic Semiconductor ASA integrated circuit.
|
||
|
|
*
|
||
|
|
* 5. Any software provided in binary form under this license must not be reverse
|
||
|
|
* engineered, decompiled, modified and/or disassembled.
|
||
|
|
*
|
||
|
|
* THIS SOFTWARE IS PROVIDED BY NORDIC SEMICONDUCTOR ASA "AS IS" AND ANY EXPRESS
|
||
|
|
* OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
|
||
|
|
* OF MERCHANTABILITY, NONINFRINGEMENT, AND FITNESS FOR A PARTICULAR PURPOSE ARE
|
||
|
|
* DISCLAIMED. IN NO EVENT SHALL NORDIC SEMICONDUCTOR ASA OR CONTRIBUTORS BE
|
||
|
|
* LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
|
||
|
|
* CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
|
||
|
|
* GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
||
|
|
* HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
||
|
|
* LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
|
||
|
|
* OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
||
|
|
*
|
||
|
|
*/
|
||
|
|
#ifndef NRF_FSTORAGE_H__
|
||
|
|
#define NRF_FSTORAGE_H__
|
||
|
|
|
||
|
|
/**
|
||
|
|
* @file
|
||
|
|
*
|
||
|
|
* @defgroup nrf_fstorage Flash storage (fstorage)
|
||
|
|
* @ingroup app_common
|
||
|
|
* @{
|
||
|
|
*
|
||
|
|
* @brief Flash abstraction library that provides basic read, write, and erase operations.
|
||
|
|
*
|
||
|
|
* @details The fstorage library can be implemented in different ways. Two implementations are provided:
|
||
|
|
* - The @ref nrf_fstorage_sd implements flash access through the SoftDevice.
|
||
|
|
* - The @ref nrf_fstorage_nvmc implements flash access through the non-volatile memory controller.
|
||
|
|
*
|
||
|
|
* You can select the implementation that should be used independently for each instance of fstorage.
|
||
|
|
*/
|
||
|
|
|
||
|
|
#include <stdint.h>
|
||
|
|
#include <stdbool.h>
|
||
|
|
#include "sdk_errors.h"
|
||
|
|
#include "nrf_section.h"
|
||
|
|
|
||
|
|
#ifdef __cplusplus
|
||
|
|
extern "C" {
|
||
|
|
#endif
|
||
|
|
|
||
|
|
|
||
|
|
/**@brief Macro for defining an fstorage instance.
|
||
|
|
*
|
||
|
|
* Users of fstorage must define an instance variable by using this macro.
|
||
|
|
* Each instance is tied to an API implementation and contains information such
|
||
|
|
* as the program and erase units for the target flash peripheral.
|
||
|
|
* Instance variables are placed in the "fs_data" section of the binary.
|
||
|
|
*
|
||
|
|
* @param[in] inst A definition of an @ref nrf_fstorage_t variable.
|
||
|
|
*/
|
||
|
|
#define NRF_FSTORAGE_DEF(inst) NRF_SECTION_ITEM_REGISTER(fs_data, inst)
|
||
|
|
|
||
|
|
/**@brief Macro for retrieving an fstorage instance. */
|
||
|
|
#define NRF_FSTORAGE_INSTANCE_GET(i) NRF_SECTION_ITEM_GET(fs_data, nrf_fstorage_t, (i))
|
||
|
|
|
||
|
|
/**@brief Macro for retrieving the total number of fstorage instances. */
|
||
|
|
#define NRF_FSTORAGE_INSTANCE_CNT NRF_SECTION_ITEM_COUNT(fs_data, nrf_fstorage_t)
|
||
|
|
|
||
|
|
|
||
|
|
/**@brief Event IDs. */
|
||
|
|
typedef enum
|
||
|
|
{
|
||
|
|
NRF_FSTORAGE_EVT_READ_RESULT, //!< Unused event reserved for a possible future feature.
|
||
|
|
NRF_FSTORAGE_EVT_WRITE_RESULT, //!< Event for @ref nrf_fstorage_write.
|
||
|
|
NRF_FSTORAGE_EVT_ERASE_RESULT //!< Event for @ref nrf_fstorage_erase.
|
||
|
|
} nrf_fstorage_evt_id_t;
|
||
|
|
|
||
|
|
|
||
|
|
/**@brief An fstorage event. */
|
||
|
|
typedef struct
|
||
|
|
{
|
||
|
|
nrf_fstorage_evt_id_t id; //!< The event ID.
|
||
|
|
ret_code_t result; //!< Result of the operation.
|
||
|
|
uint32_t addr; //!< Address at which the operation was performed.
|
||
|
|
void const * p_src; //!< Buffer written to flash.
|
||
|
|
uint32_t len; //!< Length of the operation.
|
||
|
|
void * p_param; //!< User-defined parameter passed to the event handler.
|
||
|
|
} nrf_fstorage_evt_t;
|
||
|
|
|
||
|
|
|
||
|
|
/**@brief Event handler function prototype.
|
||
|
|
*
|
||
|
|
* @param[in] p_evt The event.
|
||
|
|
*/
|
||
|
|
typedef void (*nrf_fstorage_evt_handler_t)(nrf_fstorage_evt_t * p_evt);
|
||
|
|
|
||
|
|
|
||
|
|
/**@brief Information about the implementation and the flash peripheral. */
|
||
|
|
typedef struct
|
||
|
|
{
|
||
|
|
uint32_t erase_unit; //!< Size of a flash page (in bytes). A flash page is the smallest unit that can be erased.
|
||
|
|
uint32_t program_unit; //!< Size of the smallest programmable unit (in bytes).
|
||
|
|
bool rmap; //!< The device address space is memory mapped to the MCU address space.
|
||
|
|
bool wmap; //!< The device address space is memory mapped to a writable MCU address space.
|
||
|
|
} const nrf_fstorage_info_t;
|
||
|
|
|
||
|
|
|
||
|
|
/* Necessary forward declaration. */
|
||
|
|
struct nrf_fstorage_api_s;
|
||
|
|
|
||
|
|
|
||
|
|
/**@brief An fstorage instance.
|
||
|
|
*
|
||
|
|
* @details Use the @ref NRF_FSTORAGE_DEF macro to define an fstorage instance.
|
||
|
|
*
|
||
|
|
* An instance is tied to an API implementation and contains information about the flash device,
|
||
|
|
* such as the program and erase units as well and implementation-specific functionality.
|
||
|
|
*/
|
||
|
|
typedef struct
|
||
|
|
{
|
||
|
|
/**@brief The API implementation used by this instance. */
|
||
|
|
struct nrf_fstorage_api_s const * p_api;
|
||
|
|
|
||
|
|
/**@brief Information about the implementation functionality and the flash peripheral. */
|
||
|
|
nrf_fstorage_info_t * p_flash_info;
|
||
|
|
|
||
|
|
/**@brief The event handler function.
|
||
|
|
*
|
||
|
|
* If set to NULL, no events will be sent.
|
||
|
|
*/
|
||
|
|
nrf_fstorage_evt_handler_t evt_handler;
|
||
|
|
|
||
|
|
/**@brief The beginning of the flash space on which this fstorage instance should operate.
|
||
|
|
* All flash operations must be within the address specified in
|
||
|
|
* this field and @ref end_addr.
|
||
|
|
*
|
||
|
|
* This field must be set manually.
|
||
|
|
*/
|
||
|
|
uint32_t start_addr;
|
||
|
|
|
||
|
|
/**@brief The last address (exclusive) of flash on which this fstorage instance should operate.
|
||
|
|
* All flash operations must be within the address specified in
|
||
|
|
* this field and @ref start_addr.
|
||
|
|
*
|
||
|
|
* This field must be set manually.
|
||
|
|
*/
|
||
|
|
uint32_t end_addr;
|
||
|
|
} nrf_fstorage_t;
|
||
|
|
|
||
|
|
|
||
|
|
/**@brief Functions provided by the API implementation. */
|
||
|
|
typedef struct nrf_fstorage_api_s
|
||
|
|
{
|
||
|
|
/**@brief Initialize the flash peripheral. */
|
||
|
|
ret_code_t (*init)(nrf_fstorage_t * p_fs, void * p_param);
|
||
|
|
/**@brief Uninitialize the flash peripheral. */
|
||
|
|
ret_code_t (*uninit)(nrf_fstorage_t * p_fs, void * p_param);
|
||
|
|
/**@brief Read data from flash. */
|
||
|
|
ret_code_t (*read)(nrf_fstorage_t const * p_fs, uint32_t src, void * p_dest, uint32_t len);
|
||
|
|
/**@brief Write bytes to flash. */
|
||
|
|
ret_code_t (*write)(nrf_fstorage_t const * p_fs, uint32_t dest, void const * p_src, uint32_t len, void * p_param);
|
||
|
|
/**@brief Erase flash pages. */
|
||
|
|
ret_code_t (*erase)(nrf_fstorage_t const * p_fs, uint32_t addr, uint32_t len, void * p_param);
|
||
|
|
/**@brief Map a device address to a readable address within the MCU address space. */
|
||
|
|
uint8_t const * (*rmap)(nrf_fstorage_t const * p_fs, uint32_t addr);
|
||
|
|
/**@brief Map a device address to a writable address within the MCU address space. */
|
||
|
|
uint8_t * (*wmap)(nrf_fstorage_t const * p_fs, uint32_t addr);
|
||
|
|
/**@brief Check if there are any pending flash operations. */
|
||
|
|
bool (*is_busy)(nrf_fstorage_t const * p_fs);
|
||
|
|
} const nrf_fstorage_api_t;
|
||
|
|
|
||
|
|
|
||
|
|
/**@brief Function for initializing fstorage.
|
||
|
|
*
|
||
|
|
* @param[in] p_fs The fstorage instance to initialize.
|
||
|
|
* @param[in] p_api The API implementation to use.
|
||
|
|
* @param[in] p_param An optional parameter to pass to the implementation-specific API call.
|
||
|
|
*
|
||
|
|
* @retval NRF_SUCCESS If initialization was successful.
|
||
|
|
* @retval NRF_ERROR_NULL If @p p_fs or @p p_api field in @p p_fs is NULL.
|
||
|
|
* @retval NRF_ERROR_INTERNAL If another error occurred.
|
||
|
|
*/
|
||
|
|
ret_code_t nrf_fstorage_init(nrf_fstorage_t * p_fs,
|
||
|
|
nrf_fstorage_api_t * p_api,
|
||
|
|
void * p_param);
|
||
|
|
|
||
|
|
|
||
|
|
/**@brief Function for uninitializing an fstorage instance.
|
||
|
|
*
|
||
|
|
* @param[in] p_fs The fstorage instance to uninitialize.
|
||
|
|
* @param[in] p_param An optional parameter to pass to the implementation-specific API call.
|
||
|
|
*
|
||
|
|
* @retval NRF_SUCCESS If uninitialization was successful.
|
||
|
|
* @retval NRF_ERROR_NULL If @p p_fs is NULL.
|
||
|
|
* @retval NRF_ERROR_INVALID_STATE If the module is not initialized.
|
||
|
|
* @retval NRF_ERROR_INTERNAL If another error occurred.
|
||
|
|
*/
|
||
|
|
ret_code_t nrf_fstorage_uninit(nrf_fstorage_t * p_fs, void * p_param);
|
||
|
|
|
||
|
|
|
||
|
|
/**@brief Function for reading data from flash.
|
||
|
|
*
|
||
|
|
* Copy @p len bytes from @p addr to @p p_dest.
|
||
|
|
*
|
||
|
|
* @param[in] p_fs The fstorage instance.
|
||
|
|
* @param[in] addr Address in flash where to read from.
|
||
|
|
* @param[in] p_dest Buffer where the data should be copied.
|
||
|
|
* @param[in] len Length of the data to be copied (in bytes).
|
||
|
|
*
|
||
|
|
* @retval NRF_SUCCESS If the operation was successful.
|
||
|
|
* @retval NRF_ERROR_NULL If @p p_fs or @p p_dest is NULL.
|
||
|
|
* @retval NRF_ERROR_INVALID_STATE If the module is not initialized.
|
||
|
|
* @retval NRF_ERROR_INVALID_LENGTH If @p len is zero or otherwise invalid.
|
||
|
|
* @retval NRF_ERROR_INVALID_ADDR If the address @p addr is outside the flash memory
|
||
|
|
* boundaries specified in @p p_fs, or if it is unaligned.
|
||
|
|
*/
|
||
|
|
ret_code_t nrf_fstorage_read(nrf_fstorage_t const * p_fs,
|
||
|
|
uint32_t addr,
|
||
|
|
void * p_dest,
|
||
|
|
uint32_t len);
|
||
|
|
|
||
|
|
|
||
|
|
/**@brief Function for writing data to flash.
|
||
|
|
*
|
||
|
|
* Write @p len bytes from @p p_src to @p dest.
|
||
|
|
*
|
||
|
|
* When using @ref nrf_fstorage_sd, the data is written by several calls to @ref sd_flash_write if
|
||
|
|
* the length of the data exceeds @ref NRF_FSTORAGE_SD_MAX_WRITE_SIZE bytes.
|
||
|
|
* Only one event is sent upon completion.
|
||
|
|
*
|
||
|
|
* @note The data to be written to flash must be kept in memory until the operation has
|
||
|
|
* terminated and an event is received.
|
||
|
|
*
|
||
|
|
* @param[in] p_fs The fstorage instance.
|
||
|
|
* @param[in] dest Address in flash memory where to write the data.
|
||
|
|
* @param[in] p_src Data to be written.
|
||
|
|
* @param[in] len Length of the data (in bytes).
|
||
|
|
* @param[in] p_param User-defined parameter passed to the event handler (may be NULL).
|
||
|
|
*
|
||
|
|
* @retval NRF_SUCCESS If the operation was accepted.
|
||
|
|
* @retval NRF_ERROR_NULL If @p p_fs or @p p_src is NULL.
|
||
|
|
* @retval NRF_ERROR_INVALID_STATE If the module is not initialized.
|
||
|
|
* @retval NRF_ERROR_INVALID_LENGTH If @p len is zero or not a multiple of the program unit,
|
||
|
|
* or if it is otherwise invalid.
|
||
|
|
* @retval NRF_ERROR_INVALID_ADDR If the address @p dest is outside the flash memory
|
||
|
|
* boundaries specified in @p p_fs, or if it is unaligned.
|
||
|
|
* @retval NRF_ERROR_NO_MEM If no memory is available to accept the operation.
|
||
|
|
* When using the @ref nrf_fstorage_sd, this error
|
||
|
|
* indicates that the internal queue of operations is full.
|
||
|
|
*/
|
||
|
|
ret_code_t nrf_fstorage_write(nrf_fstorage_t const * p_fs,
|
||
|
|
uint32_t dest,
|
||
|
|
void const * p_src,
|
||
|
|
uint32_t len,
|
||
|
|
void * p_param);
|
||
|
|
|
||
|
|
|
||
|
|
/**@brief Function for erasing flash pages.
|
||
|
|
*
|
||
|
|
* @details This function erases @p len pages starting from the page at address @p page_addr.
|
||
|
|
* The erase operation must be initiated on a page boundary.
|
||
|
|
*
|
||
|
|
* @param[in] p_fs The fstorage instance.
|
||
|
|
* @param[in] page_addr Address of the page to erase.
|
||
|
|
* @param[in] len Number of pages to erase.
|
||
|
|
* @param[in] p_param User-defined parameter passed to the event handler (may be NULL).
|
||
|
|
*
|
||
|
|
* @retval NRF_SUCCESS If the operation was accepted.
|
||
|
|
* @retval NRF_ERROR_NULL If @p p_fs is NULL.
|
||
|
|
* @retval NRF_ERROR_INVALID_STATE If the module is not initialized.
|
||
|
|
* @retval NRF_ERROR_INVALID_LENGTH If @p len is zero.
|
||
|
|
* @retval NRF_ERROR_INVALID_ADDR If the address @p page_addr is outside the flash memory
|
||
|
|
* boundaries specified in @p p_fs, or if it is unaligned.
|
||
|
|
* @retval NRF_ERROR_NO_MEM If no memory is available to accept the operation.
|
||
|
|
* When using the @ref nrf_fstorage_sd, this error
|
||
|
|
* indicates that the internal queue of operations is full.
|
||
|
|
*/
|
||
|
|
ret_code_t nrf_fstorage_erase(nrf_fstorage_t const * p_fs,
|
||
|
|
uint32_t page_addr,
|
||
|
|
uint32_t len,
|
||
|
|
void * p_param);
|
||
|
|
|
||
|
|
|
||
|
|
/**@brief Map a flash address to a pointer in the MCU address space that can be dereferenced.
|
||
|
|
*
|
||
|
|
* @param p_fs The fstorage instance.
|
||
|
|
* @param addr The address to map.
|
||
|
|
*
|
||
|
|
* @retval A pointer to the specified address,
|
||
|
|
* or @c NULL if the address cannot be mapped or if @p p_fs is @c NULL.
|
||
|
|
*/
|
||
|
|
uint8_t const * nrf_fstorage_rmap(nrf_fstorage_t const * p_fs, uint32_t addr);
|
||
|
|
|
||
|
|
|
||
|
|
/**@brief Map a flash address to a pointer in the MCU address space that can be written to.
|
||
|
|
*
|
||
|
|
* @param p_fs The fstorage instance.
|
||
|
|
* @param addr The address to map.
|
||
|
|
*
|
||
|
|
* @retval A pointer to the specified address,
|
||
|
|
* or @c NULL if the address cannot be mapped or if @p p_fs is @c NULL.
|
||
|
|
*/
|
||
|
|
uint8_t * nrf_fstorage_wmap(nrf_fstorage_t const * p_fs, uint32_t addr);
|
||
|
|
|
||
|
|
|
||
|
|
/**@brief Function for querying the status of fstorage.
|
||
|
|
*
|
||
|
|
* @details An uninitialized instance of fstorage is treated as not busy.
|
||
|
|
*
|
||
|
|
* @param[in] p_fs The fstorage instance. Pass NULL to query all instances.
|
||
|
|
*
|
||
|
|
* @returns If @p p_fs is @c NULL, this function returns true if any fstorage instance is busy or false otherwise.
|
||
|
|
* @returns If @p p_fs is not @c NULL, this function returns true if the fstorage instance is busy or false otherwise.
|
||
|
|
*/
|
||
|
|
bool nrf_fstorage_is_busy(nrf_fstorage_t const * p_fs);
|
||
|
|
|
||
|
|
/** @} */
|
||
|
|
|
||
|
|
|
||
|
|
#ifdef __cplusplus
|
||
|
|
}
|
||
|
|
#endif
|
||
|
|
|
||
|
|
#endif // NRF_FSTORAGE_H__
|