Mouse code for the MacroRat
mbed-dev/targets/TARGET_NORDIC/TARGET_NRF5/sdk/libraries/fstorage/fstorage.h
- Committer:
- sahilmgandhi
- Date:
- 2017-06-03
- Revision:
- 46:b156ef445742
- Parent:
- 18:6a4db94011d3
File content as of revision 46:b156ef445742:
/* * 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__