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