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