owner-nrf52sdk/nRF5_SDK_17.0.2/components/libraries/fstorage/nrf_fstorage.h

/**
 * 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__