pstorage.h

00001 /* Copyright (c) 2013 Nordic Semiconductor. All Rights Reserved.
00002  *
00003  * The information contained herein is property of Nordic Semiconductor ASA.
00004  * Terms and conditions of usage are described in detail in NORDIC
00005  * SEMICONDUCTOR STANDARD SOFTWARE LICENSE AGREEMENT.
00006  *
00007  * Licensees are granted free, non-transferable use of the information. NO
00008  * WARRANTY of ANY KIND is provided. This heading must NOT be removed from
00009  * the file.
00010  *
00011  */
00012 
00013 /**@file
00014  *
00015  * @defgroup persistent_storage Persistent Storage Interface
00016  * @{
00017  * @ingroup app_common
00018  * @brief Abstracted flash interface.
00019  *
00020  * @details In order to ensure that the SDK and application be moved to alternate persistent storage
00021  *          options other than the default provided with NRF solution, an abstracted interface is provided
00022  *          by the module to ensure SDK modules and application can be ported to alternate option with ease.
00023  */
00024 
00025 #ifndef PSTORAGE_H__
00026 #define PSTORAGE_H__
00027 
00028 #include "nordic_global.h"
00029 #include "pstorage_platform.h"
00030 
00031 
00032 /**@defgroup ps_opcode Persistent Storage Access Operation Codes
00033  * @{
00034  * @brief    Persistent Storage Access Operation Codes. These are used to report any error during
00035  *           a persistent storage access operation or any general error that may occur in the
00036  *           interface.
00037  *
00038  * @details  Persistent Storage Access Operation Codes used in error notification callback
00039  *           registered with the interface to report any error during an persistent storage access
00040  *           operation or any general error that may occur in the interface.
00041  */
00042  #define PSTORAGE_ERROR_OP_CODE    0x01  /**< General Error Code */
00043  #define PSTORAGE_STORE_OP_CODE    0x02  /**< Error when Store Operation was requested */
00044  #define PSTORAGE_LOAD_OP_CODE     0x03  /**< Error when Load Operation was requested */
00045  #define PSTORAGE_CLEAR_OP_CODE    0x04  /**< Error when Clear Operation was requested */
00046 
00047 /**@} */
00048 
00049 /**@defgroup pstorage_data_types Persistent Memory Interface Data Types
00050  * @{
00051  * @brief Data Types needed for interfacing with persistent memory.
00052  *
00053  * @details Data Types needed for interfacing with persistent memory.
00054  */
00055 
00056 /**@brief Persistent Storage Error Reporting Callback
00057  *
00058  * @details Persistent Storage Error Reporting Callback that is used by the interface to report
00059  *          success or failure of a flash operation. Therefore, for store operation or clear
00060  *          operations, that take time, application can know when the procedure was complete.
00061  *          For store operation, since no data copy is made, receiving a success or failure
00062  *          notification, indicated by the reason parameter of callback is an indication that
00063  *          the resident memory could now be reused or freed, as the case may be.
00064  *          This callback is not received for load operation.
00065  * 
00066  * @param handle   Identifies module and block for which callback is received.
00067  * @param op_code  Identifies the operation for which the event is notified.
00068  * @param result   Identifies the result of flash access operation.
00069  *                 NRF_SUCCESS implies, operation succeeded.
00070  * @param p_data   Identifies the application data pointer. In case of store operation, this points
00071  *                 to the resident source of application memory that application can now free or 
00072  *                 reuse. In case of clear, this is NULL as no application pointer is needed for
00073  *                 this operation.
00074  * @param data_len Length data application had provided for the operation.
00075  * 
00076  */
00077 typedef void (*pstorage_ntf_cb_t)(pstorage_handle_t *  p_handle,
00078                                   uint8_t              op_code,
00079                                   uint32_t             result,
00080                                   uint8_t *            p_data,
00081                                   uint32_t             data_len);
00082 
00083 
00084 typedef struct ps_module_param
00085 {
00086 
00087     pstorage_ntf_cb_t      cb;             /**< Callback registered with the module to be notified of any error occurring in persistent memory management */
00088     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,
00089                                             *   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
00090                                             *   how it would like to access or alter memory in persistent memory.
00091                                             *   First option is preferred when single entries that need to be updated often when having no impact on the other entries.
00092                                             *   While second option is preferred when entries of table are not changed on individually but have common point of loading and storing
00093                                             *   data.
00094                                             */
00095     pstorage_size_t        block_count;    /** Number of blocks requested by the module, minimum values is 1. */
00096 
00097 } pstorage_module_param_t;
00098 
00099 /**@} */
00100 
00101 /**@defgroup pstorage_routines Persistent Storage Access Routines
00102  * @{
00103  * @brief Functions/Interface SDK modules use to persistently store data.
00104  *
00105  * @details Interface for Application & SDK module to load/store information persistently.
00106  *          Note: that while implementation of each of the persistent storage access function
00107  *          depends on the system and can specific to system/solution, the signature of the
00108  *          interface routines should not be altered.
00109  */
00110 
00111 /**@brief Module Initialization Routine.
00112  *
00113  * @details Initializes module. To be called once before any other APIs of the module are used.
00114  *
00115  * @retval   NRF_SUCCESS on success, otherwise an appropriate error code.
00116  */
00117 uint32_t pstorage_init(void);
00118 
00119 
00120 /**@brief Register with persistent storage interface.
00121  *
00122  * @param[in]  p_module_param Module registration param.
00123  * @param[out] p_block_id Block identifier to identify persistent memory blocks in case registration
00124  *             succeeds. Application is expected to use the block ids for subsequent operations on
00125  *             requested persistent memory. Maximum registrations permitted is determined by
00126  *             configuration parameter PSTORAGE_MAX_APPLICATIONS.
00127  *             In case more than one memory blocks are requested, the identifier provided here is
00128  *             the base identifier for the first block and to identify subsequent block,
00129  *             application shall use \@ref pstorage_block_identifier_get with this base identifier
00130  *             and block number. Therefore if 10 blocks of size 64 are requested and application
00131  *             wishes to store memory in 6th block, it shall use
00132  *             \@ref pstorage_block_identifier_get with based id and provide a block number of 5.
00133  *             This way application is only expected to remember the base block identifier.
00134  *
00135  * @retval     NRF_SUCCESS on success, otherwise an appropriate error code.
00136  * @retval     NRF_ERROR_INVALID_STATE is returned is API is called without module initialization.
00137  * @retval     NRF_ERROR_NULL if NULL parameter has been passed.
00138  * @retval     NRF_ERROR_INVALID_PARAM if invalid parameters are passed to the API.
00139  * @retval     NRF_ERROR_NO_MEM in case no more registrations can be supported.
00140  */
00141 uint32_t pstorage_register(pstorage_module_param_t * p_module_param,
00142                            pstorage_handle_t*        p_block_id);
00143 
00144 
00145 /**
00146  * @brief Function to get block id with reference to base block identifier provided at time of
00147  *        registration.
00148  *
00149  * @details Function to get block id with reference to base block identifier provided at time of
00150  *          registration.
00151  *          In case more than one memory blocks were requested when registering, the identifier
00152  *          provided here is the base identifier for the first block and to identify subsequent
00153  *          block, application shall use this routine to get block identifier providing input as
00154  *          base identifier and block number. Therefore if 10 blocks of size 64 are requested and
00155  *          application wishes to store memory in 6th block, it shall use
00156  *          \@ref pstorage_block_identifier_get with based id and provide a block number of 5.
00157  *          This way application is only expected to remember the base block identifier.
00158  *
00159  * @param[in]  p_base_id Base block id received at the time of registration.
00160  * @param[in]  block_num Block Number, with first block numbered zero.
00161  * @param[out] p_block_id Block identifier for the block number requested in case the API succeeds.
00162  *
00163  * @retval     NRF_SUCCESS on success, else an error code indicating reason for failure.
00164  * @retval     NRF_ERROR_INVALID_STATE is returned is API is called without module initialization.
00165  * @retval     NRF_ERROR_NULL if NULL parameter has been passed.
00166  * @retval     NRF_ERROR_INVALID_PARAM if invalid parameters are passed to the API.
00167  */
00168 uint32_t pstorage_block_identifier_get(pstorage_handle_t * p_base_id,
00169                                        pstorage_size_t     block_num,
00170                                        pstorage_handle_t * p_block_id);
00171 
00172 
00173 /**@brief Routine to persistently store data of length 'size' contained in 'p_src' address
00174  *        in storage module at 'p_dest' address; Equivalent to Storage Write.
00175  *
00176  * @param[in]  p_dest Destination address where data is to be stored persistently.
00177  * @param[in]  p_src  Source address containing data to be stored. API assumes this to be resident
00178  *                    memory and no intermediate copy of data is made by the API.
00179  * @param[in]  size   Size of data to be stored expressed in bytes. Should be word aligned.
00180  * @param[in]  offset Offset in bytes to be applied when writing to the block.
00181  *                    For example, if within a block of 100 bytes, application wishes to
00182  *                    write 20 bytes at offset of 12, then this field should be set to 12.
00183  *                    Should be word aligned.
00184  *
00185  * @retval     NRF_SUCCESS on success, otherwise an appropriate error code.
00186  * @retval     NRF_ERROR_INVALID_STATE is returned is API is called without module initialization.
00187  * @retval     NRF_ERROR_NULL if NULL parameter has been passed.
00188  * @retval     NRF_ERROR_INVALID_PARAM if invalid parameters are passed to the API.
00189  * @retval     NRF_ERROR_INVALID_ADDR in case data address 'p_src' is not aligned.
00190  * @retval     NRF_ERROR_NO_MEM in case request cannot be processed.
00191  *
00192  * @warning    No copy of the data is made, and hence memory provided for data source to be written
00193  *             to flash cannot be freed or reused by the application until this procedure
00194  *             is complete. End of this procedure is notified to the application using the
00195  *             notification callback registered by the application.
00196  */
00197 uint32_t pstorage_store(pstorage_handle_t * p_dest,
00198                         uint8_t *           p_src,
00199                         pstorage_size_t     size,
00200                         pstorage_size_t     offset);
00201 
00202 
00203 /**@brief Routine to load persistently stored data of length 'size' from 'p_src' address
00204  *        to 'p_dest' address; Equivalent to Storage Read.
00205  *
00206  * @param[in]  p_dest Destination address where persistently stored data is to be loaded.
00207  * @param[in]  p_src  Source from where data is to be loaded from persistent memory.
00208  * @param[in]  size   Size of data to be loaded from persistent memory expressed in bytes.
00209  *                    Should be word aligned.
00210  * @param[in]  offset Offset in bytes to be applied when loading from the block.
00211  *                    For example, if within a block of 100 bytes, application wishes to
00212  *                    load 20 bytes from offset of 12, then this field should be set to 12.
00213  *                    Should be word aligned.
00214  *
00215  *
00216  * @retval     NRF_SUCCESS on success, otherwise an appropriate error code.
00217  * @retval     NRF_ERROR_INVALID_STATE is returned is API is called without module initialization.
00218  * @retval     NRF_ERROR_NULL if NULL parameter has been passed.
00219  * @retval     NRF_ERROR_INVALID_PARAM if invalid parameters are passed to the API.
00220  * @retval     NRF_ERROR_INVALID_ADDR in case data address 'p_dst' is not aligned.
00221  */
00222 uint32_t pstorage_load(uint8_t *           p_dest,
00223                        pstorage_handle_t * p_src,
00224                        pstorage_size_t     size,
00225                        pstorage_size_t     offset);
00226 
00227 
00228 /**@brief Routine to clear data in persistent memory.
00229  *
00230  * @param[in]  p_base_id Base block identifier in persistent memory that needs to cleared;
00231  *                       Equivalent to an Erase Operation.
00232  *
00233  * @param[in]  size      Size of data to be cleared from persistent memory expressed in bytes.
00234  *                       This is currently unused. And a clear would mean clearing all blocks,
00235  *                       however, this parameter is to provision for clearing of certain blocks
00236  *                       of memory only and not all if need be.
00237  *
00238  * @retval     NRF_SUCCESS on success, otherwise an appropriate error code.
00239  * @retval     NRF_ERROR_INVALID_STATE is returned is API is called without module initialization.
00240  * @retval     NRF_ERROR_NULL if NULL parameter has been passed.
00241  * @retval     NRF_ERROR_INVALID_PARAM if invalid parameters are passed to the API.
00242  * @retval     NRF_ERROR_NO_MEM in case request cannot be processed.
00243  *
00244  * @note       Clear operations may take time. This API however, does not block until the clear
00245  *             procedure is complete. Application is notified of procedure completion using
00246  *             notification callback registered by the application. 'result' parameter of the
00247  *             callback suggests if the procedure was successful or not.
00248  */
00249 uint32_t pstorage_clear(pstorage_handle_t * p_base_id, pstorage_size_t size);
00250 
00251 #ifdef PSTORAGE_RAW_MODE_ENABLE
00252 
00253 /**@brief      Function for registering with persistent storage interface.
00254  *
00255  * @param[in]  p_module_param Module registration param.
00256  * @param[out] p_block_id Block identifier to identify persistent memory blocks in case 
00257  *             registration succeeds. Application is expected to use the block ids for subsequent
00258  *             operations on requested persistent memory.
00259  *             In case more than one memory blocks are requested, the identifier provided here is
00260  *             the base identifier for the first block and to identify subsequent block,
00261  *             application shall use \@ref pstorage_block_identifier_get with this base identifier
00262  *             and block number. Therefore if 10 blocks of size 64 are requested and application
00263  *             wishes to store memory in 6th block, it shall use
00264  *             \@ref pstorage_block_identifier_get with based id and provide a block number of 5.
00265  *             This way application is only expected to remember the base block identifier.
00266  *
00267  * @retval     NRF_SUCCESS on success, otherwise an appropriate error code.
00268  * @retval     NRF_ERROR_INVALID_STATE is returned is API is called without module initialization.
00269  * @retval     NRF_ERROR_NULL if NULL parameter has been passed.
00270  * @retval     NRF_ERROR_INVALID_PARAM if invalid parameters are passed to the API.
00271  * @retval     NRF_ERROR_NO_MEM in case no more registrations can be supported.
00272  */
00273 uint32_t pstorage_raw_register(pstorage_module_param_t * p_module_param,
00274                                pstorage_handle_t *       p_block_id);
00275 
00276 /**@brief     Raw mode function for persistently storing data of length 'size' contained in 'p_src'
00277  *            address in storage module at 'p_dest' address; Equivalent to Storage Write.
00278  *
00279  * @param[in]  p_dest Destination address where data is to be stored persistently.
00280  * @param[in]  p_src  Source address containing data to be stored. API assumes this to be resident
00281  *                    memory and no intermediate copy of data is made by the API.
00282  * @param[in]  size   Size of data to be stored expressed in bytes. Should be word aligned.
00283  * @param[in]  offset Offset in bytes to be applied when writing to the block. 
00284  *                    For example, if within a block of 100 bytes, application wishes to
00285  *                    write 20 bytes at offset of 12, then this field should be set to 12.
00286  *                    Should be word aligned.
00287  *
00288  * @retval     NRF_SUCCESS on success, otherwise an appropriate error code.
00289  * @retval     NRF_ERROR_INVALID_STATE is returned is API is called without module initialization.
00290  * @retval     NRF_ERROR_NULL if NULL parameter has been passed.
00291  * @retval     NRF_ERROR_INVALID_PARAM if invalid parameters are passed to the API.
00292  * @retval     NRF_ERROR_INVALID_ADDR in case data address 'p_src' is not aligned.
00293  * @retval     NRF_ERROR_NO_MEM in case request cannot be processed.
00294  *
00295  * @warning    No copy of the data is made, and hence memory provided for data source to be written
00296  *             to flash cannot be freed or reused by the application until this procedure
00297  *             is complete. End of this procedure is notified to the application using the
00298  *             notification callback registered by the application.
00299  */
00300 uint32_t pstorage_raw_store(pstorage_handle_t * p_dest,
00301                             uint8_t *           p_src,
00302                             pstorage_size_t     size,
00303                             pstorage_size_t     offset);
00304 
00305 /**@brief      Function for clearing data in persistent memory in raw mode.
00306  *
00307  * @param[in]  p_base_id Base block identifier in persistent memory that needs to cleared;
00308  *                       Equivalent to an Erase Operation.
00309  *
00310  * @param[in]  size      Size of data to be cleared from persistent memory expressed in bytes.
00311  *                       This is currently unused. And a clear would mean clearing all blocks,
00312  *                       however, this parameter is to provision for clearing of certain blocks
00313  *                       of memory only and not all if need be.
00314  *
00315  * @retval     NRF_SUCCESS on success, otherwise an appropriate error code.
00316  * @retval     NRF_ERROR_INVALID_STATE is returned is API is called without module initialization.
00317  * @retval     NRF_ERROR_NULL if NULL parameter has been passed.
00318  * @retval     NRF_ERROR_INVALID_PARAM if invalid parameters are passed to the API.
00319  * @retval     NRF_ERROR_NO_MEM in case request cannot be processed.
00320  *
00321  * @note       Clear operations may take time. This API however, does not block until the clear
00322  *             procedure is complete. Application is notified of procedure completion using
00323  *             notification callback registered by the application. 'result' parameter of the
00324  *             callback suggests if the procedure was successful or not.
00325  */
00326 uint32_t pstorage_raw_clear(pstorage_handle_t * p_dest, pstorage_size_t size);
00327 
00328 #endif // PSTORAGE_RAW_MODE_ENABLE
00329 
00330 /**@} */
00331 /**@} */
00332 
00333 #endif // PSTORAGE_H__
00334