pstorage.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 /**@file
00034  *
00035  * @defgroup persistent_storage Persistent Storage Interface
00036  * @{
00037  * @ingroup app_common
00038  * @brief Abstracted flash interface.
00039  *
00040  * @details  An abstracted interface is provided by the module to easily port the application and 
00041  *           SDK modules to an alternate option. This ensures that the SDK and application are moved 
00042  *           to alternate persistent storage instead of the one provided by default.
00043  */
00044 
00045 #ifndef PSTORAGE_H__
00046 #define PSTORAGE_H__
00047 
00048 #include "pstorage_platform.h"
00049 
00050 
00051 /**@defgroup ps_opcode Persistent Storage Access Operation Codes
00052  * @{
00053  * @brief    Persistent Storage Access Operation Codes. 
00054  *
00055  * @details  Persistent Storage Access Operation Codes are used by Persistent storage operation 
00056  *           completion callback @ref pstorage_ntf_cb_t to identify the operation type requested by 
00057  *           the application.
00058  */
00059 #define PSTORAGE_STORE_OP_CODE    0x01  /**< Store Operation type. */
00060 #define PSTORAGE_LOAD_OP_CODE     0x02  /**< Load Operation type. */
00061 #define PSTORAGE_CLEAR_OP_CODE    0x03  /**< Clear Operation type. */
00062 #define PSTORAGE_UPDATE_OP_CODE   0x04  /**< Update Operation type. */
00063 
00064 /**@} */
00065 
00066 /**@defgroup pstorage_data_types Persistent Memory Interface Data Types
00067  * @{
00068  * @brief Data Types needed for interfacing with persistent memory.
00069  *
00070  * @details Data Types needed for interfacing with persistent memory.
00071  */
00072 
00073 /**@brief Persistent storage operation completion callback function type.
00074  *
00075  * @details The persistent storage operation completion callback is used by the interface to report
00076  *          success or failure of a flash operation. Since data is not copied for a store operation, 
00077  *          a callback is an indication that the resident memory can now be reused or freed.
00078  * 
00079  * @param[in] handle   Identifies the module and block for the callback that is received.
00080  * @param[in] op_code  Identifies the operation for the event that is notified.
00081  * @param[in] result   Identifies the result of a flash access operation. NRF_SUCCESS implies 
00082  *                     operation succeeded.
00083  *
00084  *                     @note Unmanaged (abnormal behaviour) error codes from the SoftDevice flash 
00085  *                     access API are forwarded as is and are expected to be handled by the 
00086  *                     application. For details refer to the implementation file and corresponding 
00087  *                     SoftDevice flash API documentation.
00088  *                     
00089  * @param[in] p_data   Identifies the application data pointer. For a store operation, this points 
00090  *                     to the resident source of application memory that the application can now 
00091  *                     free or reuse. When there is a clear operation, this is NULL since no 
00092  *                     application pointer is needed for this operation.
00093  * @param[in] data_len Length data the application provided for the operation. 
00094  */
00095 typedef void (*pstorage_ntf_cb_t)(pstorage_handle_t * p_handle,
00096                                   uint8_t             op_code,
00097                                   uint32_t            result,
00098                                   uint8_t *           p_data,
00099                                   uint32_t            data_len);
00100 
00101 /**@brief Struct containing module registration context. */
00102 typedef struct
00103 {
00104     pstorage_ntf_cb_t cb;             /**< Persistent storage operation completion callback function @ref pstorage_ntf_cb_t.  */
00105     pstorage_size_t   block_size;     /**< Desired block size for persistent memory storage. For example, if a module has a table with 10 entries, and each entry is 64 bytes in size,
00106                                        *   it can request 10 blocks with a block size of 64 bytes. The module can also request one block that is 640 bytes depending 
00107                                        *   on how it would like to access or alter the memory in persistent memory.
00108                                        *   The first option is preferred when it is a single entry that needs to be updated often and doesn't impact the other entries.
00109                                        *   The second option is preferred when table entries are not changed individually but have a common point of loading and storing
00110                                        *   data. */
00111     pstorage_size_t   block_count;    /** Number of blocks requested by the module; minimum values is 1. */
00112 } pstorage_module_param_t;
00113 
00114 /**@} */
00115 
00116 /**@defgroup pstorage_routines Persistent Storage Access Routines
00117  * @{
00118  * @brief Functions/Interface SDK modules used to persistently store data.
00119  *
00120  * @details Interface for the Application and SDK modules to load/store information persistently.
00121  *          Note: While implementation of each of the persistent storage access functions
00122  *          depends on the system and is specific to system/solution, the signature of the
00123  *          interface routines should not be altered.
00124  */
00125 
00126 /**@brief Function for initializing the module.
00127  *
00128  * @details Function for initializing the module. This function is called once before any other APIs 
00129  *          of the module are used.
00130  *
00131  * @retval     NRF_SUCCESS             Operation success.
00132  */
00133 uint32_t pstorage_init(void);
00134 
00135 /**@brief Function for registering with persistent storage interface.
00136  *
00137  * @param[in]  p_module_param Module registration parameter.
00138  * @param[out] p_block_id     Block identifier to identify persistent memory blocks when 
00139  *                            registration succeeds. Application is expected to use the block IDs 
00140  *                            for subsequent operations on requested persistent memory. Maximum 
00141  *                            registrations permitted is determined by the configuration of the 
00142  *                            parameter PSTORAGE_NUM_OF_PAGES. If more than one memory block is 
00143  *                            requested, the identifier provided here is the base identifier for the 
00144  *                            first block and used to identify the subsequent block. The application 
00145  *                            uses \@ref pstorage_block_identifier_get with this base identifier and 
00146  *                            block number. Therefore if 10 blocks of size 64 are requested and the 
00147  *                            application wishes to store memory in the 6th block, it shall use
00148  *                            \@ref pstorage_block_identifier_get with the base ID and provide a 
00149  *                            block number of 5. This way the application is only expected to 
00150  *                            remember the base block identifier.
00151  *
00152  * @retval     NRF_SUCCESS             Operation success.
00153  * @retval     NRF_ERROR_INVALID_STATE Operation failure. API is called without module 
00154  *                                     initialization.
00155  * @retval     NRF_ERROR_NULL          Operation failure. NULL parameter has been passed.
00156  * @retval     NRF_ERROR_INVALID_PARAM Operation failure. Invalid parameter has been passed.
00157  * @retval     NRF_ERROR_NO_MEM        Operation failure. Additional registrations can't be 
00158  *                                     supported.
00159  */
00160 uint32_t pstorage_register(pstorage_module_param_t * p_module_param,
00161                            pstorage_handle_t *       p_block_id);
00162 
00163 /**@brief Function for getting block ID with reference to base block identifier provided at the time 
00164  *        of registration.
00165  *
00166  * @details Function to get the block ID with reference to base block identifier provided at the 
00167  *          time of registration.
00168  *          If more than one memory block was requested when registering, the identifier provided 
00169  *          here is the base identifier for the first block which is used to identify subsequent
00170  *          blocks. The application shall use this routine to get the block identifier, providing 
00171  *          input as base identifier and block number. Therefore, if 10 blocks of size 64 are 
00172  *          requested and the application wishes to store memory in the 6th block, it shall use
00173  *          \@ref pstorage_block_identifier_get with the base ID and provide a block number of 5.
00174  *          This way the application is only expected to remember the base block identifier.
00175  *
00176  * @param[in]  p_base_id  Base block ID received at the time of registration.
00177  * @param[in]  block_num  Block Number, with first block numbered zero.
00178  * @param[out] p_block_id Block identifier for the block number requested when the API succeeds.
00179  *
00180  * @retval     NRF_SUCCESS             Operation success. 
00181  * @retval     NRF_ERROR_INVALID_STATE Operation failure. API is called without module 
00182  *                                     initialization.
00183  * @retval     NRF_ERROR_NULL          Operation failure. NULL parameter has been passed.
00184  * @retval     NRF_ERROR_INVALID_PARAM Operation failure. Invalid parameter has been passed.
00185  */
00186 uint32_t pstorage_block_identifier_get(pstorage_handle_t * p_base_id,
00187                                        pstorage_size_t     block_num,
00188                                        pstorage_handle_t * p_block_id);
00189 
00190 /**@brief Function for persistently storing data of length 'size' contained in the 'p_src' address
00191  *        in the storage module at 'p_dest' address. Equivalent to Storage Write.
00192  *
00193  * @param[in]  p_dest Destination address where data is to be stored persistently.
00194  * @param[in]  p_src  Source address containing data to be stored. API assumes this to be resident
00195  *                    memory and no intermediate copy of data is made by the API. Must be word 
00196  *                    aligned.
00197  * @param[in]  size   Size of data to be stored expressed in bytes. Must be word aligned and size + 
00198  *                    offset must be <= block size.                      
00199  * @param[in]  offset Offset in bytes to be applied when writing to the block.
00200  *                    For example, if within a block of 100 bytes, the application wishes to
00201  *                    write 20 bytes at an offset of 12, then this field should be set to 12.
00202  *                    Must be word aligned.
00203  *
00204  * @retval     NRF_SUCCESS             Operation success. 
00205  * @retval     NRF_ERROR_INVALID_STATE Operation failure. API is called without module 
00206  *                                     initialization.
00207  * @retval     NRF_ERROR_NULL          Operation failure. NULL parameter has been passed.
00208  * @retval     NRF_ERROR_INVALID_PARAM Operation failure. Invalid parameter has been passed.
00209  * @retval     NRF_ERROR_INVALID_ADDR  Operation failure. Parameter is not aligned.
00210  * @retval     NRF_ERROR_NO_MEM        Operation failure. No storage space available.
00211  *
00212  * @warning    No copy of the data is made, meaning memory provided for the data source that is to 
00213  *             be written to flash cannot be freed or reused by the application until this procedure
00214  *             is complete. The application is notified when the procedure is finished using the
00215  *             notification callback registered by the application.
00216  */
00217 uint32_t pstorage_store(pstorage_handle_t * p_dest,
00218                         uint8_t *           p_src,
00219                         pstorage_size_t     size,
00220                         pstorage_size_t     offset);
00221 
00222 /**@brief Function for updating persistently stored data of length 'size' contained in the 'p_src' 
00223  *        address in the storage module at 'p_dest' address.
00224  *
00225  * @param[in]  p_dest Destination address where data is to be updated.
00226  * @param[in]  p_src  Source address containing data to be stored. API assumes this to be resident
00227  *                    memory and no intermediate copy of data is made by the API.
00228  * @param[in]  size   Size of data to be stored expressed in bytes. Must be word aligned and size + 
00229  *                    offset must be <= block size.
00230  * @param[in]  offset Offset in bytes to be applied when writing to the block.
00231  *                    For example, if within a block of 100 bytes, the application wishes to
00232  *                    write 20 bytes at an offset of 12 bytes, then this field should be set to 12.
00233  *                    Must be word aligned.
00234  *
00235  * @retval     NRF_SUCCESS             Operation success. 
00236  * @retval     NRF_ERROR_INVALID_STATE Operation failure. API is called without module 
00237  *                                     initialization.
00238  * @retval     NRF_ERROR_NULL          Operation failure. NULL parameter has been passed.
00239  * @retval     NRF_ERROR_INVALID_PARAM Operation failure. Invalid parameter has been passed.
00240  * @retval     NRF_ERROR_INVALID_ADDR  Operation failure. Parameter is not aligned.
00241  * @retval     NRF_ERROR_NO_MEM        Operation failure. No storage space available.
00242  *
00243  * @warning    No copy of the data is made, meaning memory provided for the data source that is to 
00244  *             be written to flash cannot be freed or reused by the application until this procedure
00245  *             is complete. The application is notified when the procedure is finished using the
00246  *             notification callback registered by the application.
00247  */
00248 uint32_t pstorage_update(pstorage_handle_t * p_dest,
00249                          uint8_t *           p_src,
00250                          pstorage_size_t     size,
00251                          pstorage_size_t     offset);
00252 
00253 /**@brief Function for loading persistently stored data of length 'size' from 'p_src' address
00254  *        to 'p_dest' address. Equivalent to Storage Read.
00255  *
00256  * @param[in]  p_dest Destination address where persistently stored data is to be loaded.
00257  * @param[in]  p_src  Source where data is loaded from persistent memory.
00258  * @param[in]  size   Size of data to be loaded from persistent memory expressed in bytes.
00259  *                    Should be word aligned.
00260  * @param[in]  offset Offset in bytes, to be applied when loading from the block.
00261  *                    For example, if within a block of 100 bytes, the application wishes to
00262  *                    load 20 bytes from offset of 12 bytes, then this field should be set to 12.
00263  *                    Should be word aligned.
00264  *
00265  * @retval     NRF_SUCCESS             Operation success. 
00266  * @retval     NRF_ERROR_INVALID_STATE Operation failure. API is called without module 
00267  *                                     initialization.
00268  * @retval     NRF_ERROR_NULL          Operation failure. NULL parameter has been passed.
00269  * @retval     NRF_ERROR_INVALID_PARAM Operation failure. Invalid parameter has been passed.
00270  * @retval     NRF_ERROR_INVALID_ADDR  Operation failure. Parameter is not aligned.
00271  * @retval     NRF_ERROR_NO_MEM        Operation failure. No storage space available.
00272  */
00273 uint32_t pstorage_load(uint8_t *           p_dest,
00274                        pstorage_handle_t * p_src,
00275                        pstorage_size_t     size,
00276                        pstorage_size_t     offset);
00277 
00278 /**@brief Function for clearing data in persistent memory.
00279  *
00280  * @param[in]  p_base_id Base block identifier in persistent memory that needs to be cleared;
00281  *                       equivalent to an Erase Operation.
00282  * @param[in]  size      Size of data to be cleared from persistent memory expressed in bytes.
00283  *                       This parameter is to provision for clearing of certain blocks
00284  *                       of memory, or all memory blocks in a registered module. If the total size 
00285  *                       of the application module is used (blocks * block size) in combination with
00286  *                       the identifier for the first block in the module, all blocks in the 
00287  *                       module will be erased. Must be multiple of block size.
00288  *
00289  * @retval     NRF_SUCCESS             Operation success. 
00290  * @retval     NRF_ERROR_INVALID_STATE Operation failure. API is called without module 
00291  *                                     initialization.
00292  * @retval     NRF_ERROR_NULL          Operation failure. NULL parameter has been passed.
00293  * @retval     NRF_ERROR_INVALID_PARAM Operation failure. Invalid parameter has been passed.
00294  * @retval     NRF_ERROR_INVALID_ADDR  Operation failure. Parameter is not aligned.
00295  * @retval     NRF_ERROR_NO_MEM        Operation failure. No storage space available.
00296  *
00297  * @note       Clear operations may take time. This API however, does not block until the clear
00298  *             procedure is complete. The application is notified of procedure completion using
00299  *             a notification callback registered by the application. The 'result' parameter of the
00300  *             callback indicates if the procedure was successful or not.
00301  */
00302 uint32_t pstorage_clear(pstorage_handle_t * p_base_id, pstorage_size_t size);
00303 
00304 /**@brief Function for getting the number of pending operations with the module.
00305  *
00306  * @param[out] p_count Number of storage operations pending with the module. If 0, there are no 
00307  *                     outstanding requests.
00308  *
00309  * @retval     NRF_SUCCESS             Operation success. 
00310  * @retval     NRF_ERROR_INVALID_STATE Operation failure. API is called without module 
00311  *                                     initialization.
00312  * @retval     NRF_ERROR_NULL          Operation failure. NULL parameter has been passed.
00313  */
00314 uint32_t pstorage_access_status_get(uint32_t * p_count);
00315 
00316 #ifdef PSTORAGE_RAW_MODE_ENABLE
00317 
00318 /**@brief Function for registering with the persistent storage interface.
00319  *
00320  * @param[in]  p_module_param Module registration parameter.
00321  * @param[out] p_block_id     Block identifier used to identify persistent memory blocks upon 
00322  *                            successful registration. The application is expected to use the block 
00323  *                            IDs for subsequent operations on requested persistent memory. When 
00324  *                            more than one memory block is requested, this identifier is the base 
00325  *                            identifier for the first block and used to identify subsequent blocks. 
00326  *                            The application shall use \@ref pstorage_block_identifier_get with 
00327  *                            this base identifier and block number. Therefore if 10 blocks of size 
00328  *                            64 are requested and the application wishes to store memory in the 6th 
00329  *                            block, it shall use \@ref pstorage_block_identifier_get with the base 
00330  *                            ID and provide a block number of 5. Therefore, the application is only 
00331  *                            expected to remember the base block identifier.
00332  *
00333  * @retval     NRF_SUCCESS             Operation success. 
00334  * @retval     NRF_ERROR_INVALID_STATE Operation failure. API is called without module 
00335  *                                     initialization.
00336  * @retval     NRF_ERROR_NULL          Operation failure. NULL parameter has been passed.
00337  * @retval     NRF_ERROR_INVALID_PARAM Operation failure. Invalid parameter has been passed.
00338  * @retval     NRF_ERROR_NO_MEM        Operation failure. No storage space available.
00339  */
00340 uint32_t pstorage_raw_register(pstorage_module_param_t * p_module_param,
00341                                pstorage_handle_t *       p_block_id);
00342 
00343 /**@brief Function for persistently storing data of length 'size' contained in 'p_src' address in 
00344  *        storage module at 'p_dest' address. Equivalent to Storage Write.
00345  *
00346  * @param[in]  p_dest Destination address where data is to be stored persistently.
00347  * @param[in]  p_src  Source address containing data to be stored. The API assumes this is resident
00348  *                    memory and no intermediate copy of data is made by the API. Must be word 
00349  *                    aligned.
00350  * @param[in]  size   Size of data to be stored expressed in bytes. Must be word aligned.
00351  * @param[in]  offset Offset in bytes to be applied when writing to the block.
00352  *                    For example, if within a block of 100 bytes, the application wishes to
00353  *                    write 20 bytes at an offset of 12 bytes, this field should be set to 12.
00354  *                    Must be word aligned.
00355  *
00356  * @retval     NRF_SUCCESS             Operation success. 
00357  * @retval     NRF_ERROR_INVALID_STATE Operation failure. API is called without module 
00358  *                                     initialization.
00359  * @retval     NRF_ERROR_NULL          Operation failure. NULL parameter has been passed.
00360  * @retval     NRF_ERROR_INVALID_PARAM Operation failure. Invalid parameter has been passed.
00361  * @retval     NRF_ERROR_INVALID_ADDR  Operation failure. Parameter is not aligned.
00362  * @retval     NRF_ERROR_NO_MEM        Operation failure. No storage space available.
00363  *
00364  * @warning    No copy of the data is made, meaning memory provided for data source that is to be 
00365  *             written to flash cannot be freed or reused by the application until this procedure
00366  *             is complete. The application is notified when the procedure is finished using the
00367  *             notification callback registered by the application.
00368  */
00369 uint32_t pstorage_raw_store(pstorage_handle_t * p_dest,
00370                             uint8_t *           p_src,
00371                             pstorage_size_t     size,
00372                             pstorage_size_t     offset);
00373 
00374 /**@brief Function for clearing data in persistent memory in raw mode.
00375  *
00376  * @param[in]  p_dest Base block identifier in persistent memory that needs to be cleared.
00377  *                    Equivalent to an Erase Operation.
00378  * @param[in]  size   Size of data to be cleared from persistent memory expressed in bytes. 
00379  *                    Not used.
00380  *
00381  * @retval     NRF_SUCCESS             Operation success. 
00382  * @retval     NRF_ERROR_INVALID_STATE Operation failure. API is called without module 
00383  *                                     initialization.
00384  * @retval     NRF_ERROR_NULL          Operation failure. NULL parameter has been passed.
00385  * @retval     NRF_ERROR_INVALID_PARAM Operation failure. Invalid parameter has been passed.
00386  * @retval     NRF_ERROR_NO_MEM        Operation failure. No storage space available.
00387  *
00388  * @note       Clear operations may take time. This API, however, does not block until the clear
00389  *             procedure is complete. The application is notified of procedure completion using
00390  *             a notification callback registered by the application. The 'result' parameter of the
00391  *             callback indicates if the procedure was successful or not.
00392  */
00393 uint32_t pstorage_raw_clear(pstorage_handle_t * p_dest, pstorage_size_t size);
00394 
00395 #endif // PSTORAGE_RAW_MODE_ENABLE
00396 
00397 /**@} */
00398 /**@} */
00399 
00400 #endif // PSTORAGE_H__
00401