Initial release
Fork of nrf51-sdk by
Embed:
(wiki syntax)
Show/hide line numbers
fstorage.h
Go to the documentation of this file.
00001 /* 00002 * Copyright (c) Nordic Semiconductor ASA 00003 * All rights reserved. 00004 * 00005 * Redistribution and use in source and binary forms, with or without modification, 00006 * are permitted provided that the following conditions are met: 00007 * 00008 * 1. Redistributions of source code must retain the above copyright notice, this 00009 * list of conditions and the following disclaimer. 00010 * 00011 * 2. Redistributions in binary form must reproduce the above copyright notice, this 00012 * list of conditions and the following disclaimer in the documentation and/or 00013 * other materials provided with the distribution. 00014 * 00015 * 3. Neither the name of Nordic Semiconductor ASA nor the names of other 00016 * contributors to this software may be used to endorse or promote products 00017 * derived from this software without specific prior written permission. 00018 * 00019 * 00020 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND 00021 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 00022 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 00023 * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR 00024 * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES 00025 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 00026 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON 00027 * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 00028 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS 00029 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 00030 * 00031 */ 00032 00033 00034 #ifndef FS_H__ 00035 #define FS_H__ 00036 00037 /** @file 00038 * 00039 * @defgroup fstorage FStorage 00040 * @{ 00041 * @ingroup app_common 00042 * @brief Module which provides low level functionality to store data to flash. 00043 * 00044 */ 00045 00046 00047 #include <stdint.h> 00048 #include "section_vars.h" 00049 #include "fstorage_config.h" 00050 #include "sdk_errors.h " 00051 00052 00053 typedef uint16_t fs_length_t; 00054 00055 00056 typedef enum 00057 { 00058 FS_OP_NONE = 0, 00059 FS_OP_STORE = 1, 00060 FS_OP_ERASE = 2 00061 } fs_oper_t; 00062 00063 00064 /**@brief Callback for flash operations. 00065 * 00066 * @param[in] op_code Flash access operation code. 00067 * @param[in] result Result of the operation. 00068 * @param[in] data Pointer to resulting data (or NULL if not in use). 00069 * @param[in] length_words Length of data in words. 00070 */ 00071 typedef void (*fs_cb_t)(uint8_t op_code, 00072 uint32_t result, 00073 uint32_t const * p_data, 00074 fs_length_t length_words); 00075 00076 00077 /**@brief Function prototype for a callback handler. 00078 * 00079 * @details This function is expected to be implemented by the module that 00080 * registers for fstorage usage. Its usage is described 00081 * in the function pointer type fs_cb_t. 00082 * 00083 * @param[in] op_code Flash operation code. 00084 * @param[in] result Result of the flash operation. 00085 * @param[in] p_data Pointer to the resulting data (or NULL if not in use). 00086 * @param[in] length_words Length of data in words. 00087 */ 00088 static void fs_callback(uint8_t op_code, 00089 uint32_t result, 00090 uint32_t const * p_data, 00091 fs_length_t length_words); 00092 00093 00094 /**@brief Flash storage config variable. 00095 * 00096 * @details The fstorage module will update the start_addr and end_address according to 00097 * ordering rules and the number of pages requested by the fstorage module user. 00098 */ 00099 typedef struct 00100 { 00101 const fs_cb_t cb; /**< Callback to run when flash operation has completed. */ 00102 const uint8_t num_pages; /**< The number of pages to reserve for flash storage. */ 00103 const uint8_t page_order; /**< The order used to allocate pages. */ 00104 uint32_t * p_start_addr; /**< Pointer to the start address of the allocated flash storage. Set by running @ref fs_init. */ 00105 uint32_t * p_end_addr; /**< Pointer to the end address of the allcoated flash storage. Set by running @ref fs_init. */ 00106 } fs_config_t; 00107 00108 00109 /**@brief Macro for registering of flash storage configuration variable. 00110 * 00111 * @details This macro is expected to be invoked in the code unit that that require 00112 * flash storage. Invoking this places the registered configuration variable 00113 * in a section named "fs_data" that the fstorage module uses during initialization 00114 * and regular operation. 00115 */ 00116 #define FS_SECTION_VARS_ADD(type_def) NRF_SECTION_VARS_ADD(fs_data, type_def) 00117 00118 00119 /**@brief Function to initialize FStorage. 00120 * 00121 * @details This function allocates flash data pages according to the 00122 * number requested in the config variable. The data used to initialize. 00123 * the fstorage is section placed variables in the data section "fs_data". 00124 */ 00125 ret_code_t fs_init(void); 00126 00127 00128 /**@brief Function to store data in flash. 00129 * 00130 * @warning The data to be written to flash has to be kept in memory until the operation has 00131 * terminated, i.e., a callback is received. 00132 * 00133 * @param[in] p_config Const pointer to configiguration of module user that requests a store operation. 00134 * @param[in] p_addr Write address of store operation. 00135 * @param[in] p_data Pointer to the data to store. 00136 * @param[in] length_words Length of the data to store. 00137 * 00138 * @retval NRF_SUCCESS Success. Command queued. 00139 * @retval NRF_ERROR_INVALID_STATE Error. The module is not initialized. 00140 * @retval NRF_ERROR_INVALID_ADDR Error. Data is unaligned or invalid configuration. 00141 * @retval Any error returned by the SoftDevice flash API. 00142 */ 00143 ret_code_t fs_store(fs_config_t const * p_config, 00144 uint32_t const * p_addr, 00145 uint32_t const * const p_data, 00146 fs_length_t length_words); 00147 00148 00149 /** Function to erase a page in flash. 00150 * 00151 * @note The erase address must be aligned on a page boundary. The length in words must be 00152 * equivalent to the page size. 00153 * 00154 * @param[in] p_config Pointer to the configuration of the user that requests the operation. 00155 * @param[in] p_addr Address of page to erase (the same as first word in the page). 00156 * @param[in] length_words Length (in 4 byte words) of the area to erase. 00157 * 00158 * @retval NRF_SUCCESS Success. Command queued. 00159 * @retval NRF_ERROR_INVALID_STATE Error. The module is not initialized. 00160 * @retval NRF_ERROR_INVALID_ADDR Error. Data is unaligned or invalid configuration. 00161 * @retval Any error returned by the SoftDevice flash API. 00162 */ 00163 ret_code_t fs_erase(fs_config_t const * p_config, 00164 uint32_t * const p_addr, 00165 fs_length_t length_words); 00166 00167 00168 /**@brief Function to call to handle events from the SoftDevice 00169 * 00170 * @param sys_evt System event from the SoftDevice 00171 */ 00172 void fs_sys_event_handler(uint32_t sys_evt); 00173 00174 /** @} */ 00175 00176 #endif // FS_H__
Generated on Tue Jul 12 2022 11:17:17 by 1.7.2