Diff: targets/TARGET_NORDIC/TARGET_NRF5/sdk/libraries/fstorage/fstorage.h

Revision:

149:156823d33999

Parent:

144:ef7eb2e8f9f7

diff -r 21d94c44109e -r 156823d33999 targets/TARGET_NORDIC/TARGET_NRF5/sdk/libraries/fstorage/fstorage.h
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/targets/TARGET_NORDIC/TARGET_NRF5/sdk/libraries/fstorage/fstorage.h	Fri Oct 28 11:17:30 2016 +0100
@@ -0,0 +1,262 @@
+/* 
+ * Copyright (c) 2015 Nordic Semiconductor ASA
+ * All rights reserved.
+ * 
+ * Redistribution and use in source and binary forms, with or without modification,
+ * are permitted provided that the following conditions are met:
+ * 
+ *   1. Redistributions of source code must retain the above copyright notice, this list 
+ *      of conditions and the following disclaimer.
+ *
+ *   2. Redistributions in binary form, except as embedded into a Nordic Semiconductor ASA 
+ *      integrated circuit in a product or a software update for such product, must reproduce 
+ *      the above copyright notice, this list of conditions and the following disclaimer in 
+ *      the documentation and/or other materials provided with the distribution.
+ *
+ *   3. Neither the name of Nordic Semiconductor ASA nor the names of its contributors may be 
+ *      used to endorse or promote products derived from this software without specific prior 
+ *      written permission.
+ *
+ *   4. This software, with or without modification, must only be used with a 
+ *      Nordic Semiconductor ASA integrated circuit.
+ *
+ *   5. Any software provided in binary or object form under this license must not be reverse 
+ *      engineered, decompiled, modified and/or disassembled. 
+ * 
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+ * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+ * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
+ * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+ * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+ * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+ * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+ * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ * 
+ */
+
+
+#ifndef FSTORAGE_H__
+#define FSTORAGE_H__
+
+/**
+ * @defgroup fstorage fstorage
+ * @ingroup app_common
+ * @{
+ *
+ * @brief   Module which provides functionality to store data to flash and erase flash pages.
+ */
+
+#include <stdint.h>
+#include "section_vars.h"
+
+
+/**@brief   fstorage return values. */
+typedef enum
+{
+    FS_SUCCESS,
+    FS_ERR_NOT_INITIALIZED,     //!< Error. The module is not initialized.
+    FS_ERR_INVALID_CFG,         //!< Error. Invalid fstorage configuration.
+    FS_ERR_NULL_ARG,            //!< Error. Argument is NULL.
+    FS_ERR_INVALID_ARG,         //!< Error. Argument contains invalid data.
+    FS_ERR_INVALID_ADDR,        //!< Error. Address out of bounds.
+    FS_ERR_UNALIGNED_ADDR,      //!< Error. Unaligned address.
+    FS_ERR_QUEUE_FULL,          //!< Error. Queue is full.
+    FS_ERR_OPERATION_TIMEOUT,   //!< Error. The operation has timed out.
+    FS_ERR_INTERNAL,            //!< Error. Internal error.
+} fs_ret_t;
+
+
+/**@brief   fstorage event IDs. */
+typedef enum
+{
+    FS_EVT_STORE,   //!< Event for @ref fs_store.
+    FS_EVT_ERASE    //!< Event for @ref fs_erase.
+} fs_evt_id_t;
+
+
+#if defined(__CC_ARM)
+  #pragma push
+  #pragma anon_unions
+#elif defined(__ICCARM__)
+  #pragma language=extended
+#elif defined(__GNUC__)
+  /* anonymous unions are enabled by default */
+#endif
+
+/**@brief   An fstorage event. */
+typedef struct
+{
+    fs_evt_id_t id;                         //!< The event ID.
+    union
+    {
+        struct
+        {
+            uint32_t const * p_data;        //!< Pointer to the data stored in flash.
+            uint16_t         length_words;  //!< Length of the data, in 4-byte words.
+        } store;
+        struct
+        {
+            uint16_t first_page;            //!< First page erased.
+            uint16_t last_page;             //!< Last page erased.
+        } erase;
+    };
+} fs_evt_t;
+
+#if defined(__CC_ARM)
+  #pragma pop
+#elif defined(__ICCARM__)
+  /* leave anonymous unions enabled */
+#elif defined(__GNUC__)
+  /* anonymous unions are enabled by default */
+#endif
+
+
+/**@brief   fstorage event handler function prototype.
+ *
+ * @param[in]   evt     The event.
+ * @param[in]   result  The result of the operation.
+ */
+typedef void (*fs_cb_t)(fs_evt_t const * const evt, fs_ret_t result);
+
+
+/**@brief   fstorage application-specific configuration.
+ *
+ * @details Specifies the callback to invoke when an operation completes, the number of flash pages
+ *          requested by the application and the priority with which these are to be assigned, with
+ *          respect to other applications. Additionally, the configuration specifies the boundaries
+ *          of the flash space assigned to an application. The configuration must be provided as an
+ *          argument when invoking @ref fs_store and @ref fs_erase.
+ *
+ * @note    The fields @p p_start_addr and @p p_end_address are set by @ref fs_init, based on the
+ *          value of the field @p priority.
+ */
+typedef struct
+{
+    /**@brief   The beginning of the flash space assigned to the application which registered this
+     *          configuration. This field is set by @ref fs_init.
+     */
+    uint32_t const * p_start_addr;
+
+    /**@brief   The end of the flash space assigned to the application which registered this
+     *          configuration. This field is set by @ref fs_init.
+     */
+    uint32_t const * p_end_addr;
+
+    fs_cb_t  const   callback;    //!< Callback to run when a flash operation has completed.
+    uint8_t  const   num_pages;   //!< The number of flash pages requested.
+
+    /**@brief   The priority with which fstorage should assign flash pages to this application,
+     *          with respect to other applications. Applications with higher priority will be
+     *          assigned flash pages with a higher memory address. The highest priority is
+     *          reserved. Must be unique among configurations.
+     */
+    uint8_t  const   priority;
+} fs_config_t;
+
+
+/**@brief   Macro for registering with an fstorage configuration.
+ *          Applications which use fstorage must register with the module using this macro.
+ *          Registering involves defining a variable which holds the configuration of fstorage
+ *          specific to the application which invokes the macro.
+ *
+ * @details This macro places the configuration variable in a section named "fs_data" that
+ *          fstorage uses during initialization and regular operation.
+ *
+ * @param[in]   cfg_var     A @e definition of a @ref fs_config_t variable.
+ */
+#define FS_REGISTER_CFG(cfg_var) NRF_SECTION_VARS_ADD(fs_data, cfg_var)
+
+
+/**@brief   Function for initializing the module.
+ *
+ * @details This functions assigns pages in flash according to all registered configurations.
+ *
+ * @retval  FS_SUCCESS    If the module was successfully initialized.
+ */
+fs_ret_t fs_init(void);
+
+
+/**@brief   Function for storing data in flash.
+ *
+ * @details Copies @p length_words words from @p p_src to the location pointed by @p p_dest.
+ *          If the length of the data exceeds @ref FS_MAX_WRITE_SIZE_WORDS, the data will be
+ *          written down in several chunks, as necessary. Only one event will be sent to the
+ *          application upon completion. Both the source and the destination of the data must be
+ *          word aligned. This function is asynchronous, completion is reported via an event sent
+ *          the the callback function specified in the supplied configuration.
+ *
+ * @warning The data to be written to flash has to be kept in memory until the operation has
+ *          terminated, i.e., an event is received.
+ *
+ * @param[in]   p_config        fstorage configuration registered by the application.
+ * @param[in]   p_dest          The address in flash memory where to store the data.
+ * @param[in]   p_src           Pointer to the data to store in flash.
+ * @param[in]   length_words    Length of the data to store, in words.
+ *
+ * @retval  FS_SUCCESS              If the operation was queued successfully.
+ * @retval  FS_ERR_NOT_INITIALIZED  If the module is not initialized.
+ * @retval  FS_ERR_INVALID_CFG      If @p p_config is NULL or contains invalid data.
+ * @retval  FS_ERR_NULL_ARG         If @p p_dest or @p p_src are NULL.
+ * @retval  FS_ERR_INVALID_ARG      If @p length_words is zero.
+ * @retval  FS_ERR_INVALID_ADDR     If @p p_dest or @p p_src are outside of the flash memory
+ *                                  boundaries specified in @p p_config.
+ * @retval  FS_ERR_UNALIGNED_ADDR   If @p p_dest or @p p_src are not aligned to a word boundary.
+ * @retval  FS_ERR_QUEUE_FULL       If the internal operation queue is full.
+ */
+fs_ret_t fs_store(fs_config_t const * const p_config,
+                  uint32_t    const * const p_dest,
+                  uint32_t    const * const p_src,
+                  uint16_t                  length_words);
+
+
+/**@brief   Function for erasing flash pages.
+ *
+ * @details Starting from the page at @p p_page_addr, erases @p num_pages flash pages.
+ *          @p p_page_addr must be aligned to a page boundary. All pages to be erased must be
+ *          within the bounds specified in the supplied fstorage configuration.
+ *          This function is asynchronous. Completion is reported via an event.
+ *
+ * @param[in]   p_config        fstorage configuration registered by the application.
+ * @param[in]   p_page_addr     Address of the page to erase. Must be aligned to a page boundary.
+ * @param[in]   num_pages       Number of pages to erase. May not be zero.
+ *
+ * @retval  FS_SUCCESS              If the operation was queued successfully.
+ * @retval  FS_ERR_NOT_INITIALIZED  If the module is not initialized.
+ * @retval  FS_ERR_INVALID_CFG      If @p p_config is NULL or contains invalid data.
+ * @retval  FS_ERR_NULL_ARG         If @p p_page_addr is NULL.
+ * @retval  FS_ERR_INVALID_ARG      If @p num_pages is zero.
+ * @retval  FS_ERR_INVALID_ADDR     If the operation would go beyond the flash memory boundaries
+ *                                  specified in @p p_config.
+ * @retval  FS_ERR_UNALIGNED_ADDR   If @p p_page_addr is not aligned to a page boundary.
+ * @retval  FS_ERR_QUEUE_FULL       If the internal operation queue is full.
+ */
+fs_ret_t fs_erase(fs_config_t const * const p_config,
+                  uint32_t    const * const p_page_addr,
+                  uint16_t                  num_pages);
+
+
+/**@brief Function for retrieving the number of queued flash operations.
+ *
+ * @param[out]  p_op_count    The number of queued flash operations.
+ *
+ * @retval  FS_SUCCESS          If the number of queued operations was retrieved successfully.
+ * @retval  FS_ERR_NULL_ARG     If @p p_op_count is NULL.
+ */
+fs_ret_t fs_queued_op_count_get(uint32_t * const p_op_count);
+
+
+/**@brief   Function for handling system events from the SoftDevice.
+ *
+ * @details If any of the modules used by the application rely on fstorage, the application should
+ *          dispatch system events to fstorage using this function.
+ *
+ * @param[in]   sys_evt     System event from the SoftDevice.
+ */
+void fs_sys_event_handler(uint32_t sys_evt);
+
+
+/** @} */
+
+#endif // FSTORAGE_H__