Nordic stack and drivers for the mbed BLE API
Dependents: Sensen-classic-v8-IAQ_copy_4
Fork of nRF51822 by
Diff: TARGET_MCU_NRF51822/sdk/source/libraries/fstorage/fstorage.h
- Revision:
- 638:c90ae1400bf2
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/TARGET_MCU_NRF51822/sdk/source/libraries/fstorage/fstorage.h Wed Sep 14 14:39:43 2016 +0100 @@ -0,0 +1,176 @@ +/* + * Copyright (c) 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 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 other + * contributors to this software may be used to endorse or promote products + * derived from this software without specific prior written permission. + * + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND + * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED + * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE + * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER 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 FS_H__ +#define FS_H__ + + /** @file + * + * @defgroup fstorage FStorage + * @{ + * @ingroup app_common + * @brief Module which provides low level functionality to store data to flash. + * + */ + + +#include <stdint.h> +#include "section_vars.h" +#include "fstorage_config.h" +#include "sdk_errors.h" + + +typedef uint16_t fs_length_t; + + +typedef enum +{ + FS_OP_NONE = 0, + FS_OP_STORE = 1, + FS_OP_ERASE = 2 +} fs_oper_t; + + +/**@brief Callback for flash operations. + * + * @param[in] op_code Flash access operation code. + * @param[in] result Result of the operation. + * @param[in] data Pointer to resulting data (or NULL if not in use). + * @param[in] length_words Length of data in words. + */ +typedef void (*fs_cb_t)(uint8_t op_code, + uint32_t result, + uint32_t const * p_data, + fs_length_t length_words); + + +/**@brief Function prototype for a callback handler. + * + * @details This function is expected to be implemented by the module that + * registers for fstorage usage. Its usage is described + * in the function pointer type fs_cb_t. + * + * @param[in] op_code Flash operation code. + * @param[in] result Result of the flash operation. + * @param[in] p_data Pointer to the resulting data (or NULL if not in use). + * @param[in] length_words Length of data in words. + */ +static void fs_callback(uint8_t op_code, + uint32_t result, + uint32_t const * p_data, + fs_length_t length_words); + + +/**@brief Flash storage config variable. + * + * @details The fstorage module will update the start_addr and end_address according to + * ordering rules and the number of pages requested by the fstorage module user. + */ +typedef struct +{ + const fs_cb_t cb; /**< Callback to run when flash operation has completed. */ + const uint8_t num_pages; /**< The number of pages to reserve for flash storage. */ + const uint8_t page_order; /**< The order used to allocate pages. */ + uint32_t * p_start_addr; /**< Pointer to the start address of the allocated flash storage. Set by running @ref fs_init. */ + uint32_t * p_end_addr; /**< Pointer to the end address of the allcoated flash storage. Set by running @ref fs_init. */ +} fs_config_t; + + +/**@brief Macro for registering of flash storage configuration variable. + * + * @details This macro is expected to be invoked in the code unit that that require + * flash storage. Invoking this places the registered configuration variable + * in a section named "fs_data" that the fstorage module uses during initialization + * and regular operation. + */ +#define FS_SECTION_VARS_ADD(type_def) NRF_SECTION_VARS_ADD(fs_data, type_def) + + +/**@brief Function to initialize FStorage. + * + * @details This function allocates flash data pages according to the + * number requested in the config variable. The data used to initialize. + * the fstorage is section placed variables in the data section "fs_data". + */ +ret_code_t fs_init(void); + + +/**@brief Function to store data in flash. + * + * @warning The data to be written to flash has to be kept in memory until the operation has + * terminated, i.e., a callback is received. + * + * @param[in] p_config Const pointer to configiguration of module user that requests a store operation. + * @param[in] p_addr Write address of store operation. + * @param[in] p_data Pointer to the data to store. + * @param[in] length_words Length of the data to store. + * + * @retval NRF_SUCCESS Success. Command queued. + * @retval NRF_ERROR_INVALID_STATE Error. The module is not initialized. + * @retval NRF_ERROR_INVALID_ADDR Error. Data is unaligned or invalid configuration. + * @retval Any error returned by the SoftDevice flash API. + */ +ret_code_t fs_store(fs_config_t const * p_config, + uint32_t const * p_addr, + uint32_t const * const p_data, + fs_length_t length_words); + + +/** Function to erase a page in flash. + * + * @note The erase address must be aligned on a page boundary. The length in words must be + * equivalent to the page size. + * + * @param[in] p_config Pointer to the configuration of the user that requests the operation. + * @param[in] p_addr Address of page to erase (the same as first word in the page). + * @param[in] length_words Length (in 4 byte words) of the area to erase. + * + * @retval NRF_SUCCESS Success. Command queued. + * @retval NRF_ERROR_INVALID_STATE Error. The module is not initialized. + * @retval NRF_ERROR_INVALID_ADDR Error. Data is unaligned or invalid configuration. + * @retval Any error returned by the SoftDevice flash API. + */ +ret_code_t fs_erase(fs_config_t const * p_config, + uint32_t * const p_addr, + fs_length_t length_words); + + +/**@brief Function to call to handle events from the SoftDevice + * + * @param sys_evt System event from the SoftDevice + */ +void fs_sys_event_handler(uint32_t sys_evt); + +/** @} */ + +#endif // FS_H__