fstorage.h

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__