| /* |
| * Copyright (c) 2015-2016, Texas Instruments Incorporated |
| * All rights reserved. |
| * |
| * Redistribution and use in source and binary forms, with or without |
| * modification, are permitted provided that the following conditions |
| * are met: |
| * |
| * * Redistributions of source code must retain the above copyright |
| * notice, this list of conditions and the following disclaimer. |
| * |
| * * Redistributions in binary form 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. |
| * |
| * * Neither the name of Texas Instruments Incorporated nor the names of |
| * its contributors may be used to endorse or promote products derived |
| * from this software without specific prior written permission. |
| * |
| * 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 OWNER 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. |
| */ |
| /** ========================================================================== |
| * @file NVS.h |
| * |
| * @brief <b>PRELIMINARY</b> Non-Volatile Storage Driver. |
| * |
| * <b>WARNING</b> These APIs are <b>PRELIMINARY</b>, and subject to |
| * change in the next few months. |
| * |
| * The NVS header file should be included in an application as follows: |
| * @code |
| * #include <ti/drivers/NVS.h> |
| * @endcode |
| * |
| * # Operation # |
| * |
| * The NVS module allows you to manage non-volatile memory. Using the |
| * NVS APIs, you can read and write data to persistant storage. Each NVS |
| * object manages a 'block' of non-volatile memory of a size specified in |
| * the NVS object's hardware attributes. A 'page' will refer to the |
| * smallest unit of non-volatile storage that can be erased at one time, |
| * and the page size is the size of this unit. This is hardware specific |
| * and may be meaningless for some persistant storage systems. However, |
| * in the case of flash memory, page size should be taken into account |
| * when deciding the block size for NVS to manage. For example on |
| * TM4C129x devices, a page size is 16KB. |
| * |
| * When page size is relevant (e.g. for flash memory), the size of an |
| * NVS block size must be less than or equal to the page size. The block |
| * size can be less than the page size, however, care must be taken not |
| * to use the area in the page outside of the block. When the block is |
| * erased, the entire page will be erased, clearing anything in the page |
| * that was written outside of the block. |
| * |
| * See the device specific NVS header file for configuration details. |
| * |
| * ========================================================================== |
| */ |
| |
| #ifndef ti_drivers_NVS__include |
| #define ti_drivers_NVS__include |
| |
| #include <stdint.h> |
| #include <stddef.h> |
| #include <stdbool.h> |
| |
| #if defined (__cplusplus) |
| extern "C" { |
| #endif |
| |
| /** |
| * @defgroup NVS_CONTROL NVS_control command and status codes |
| * These NVS macros are reservations for NVS.h |
| * @{ |
| */ |
| |
| /*! |
| * Common NVS_control command code reservation offset. |
| * NVS driver implementations should offset command codes with NVS_CMD_RESERVED |
| * growing positively |
| * |
| * Example implementation specific command codes: |
| * @code |
| * #define NVSXYZ_CMD_COMMAND0 NVS_CMD_RESERVED + 0 |
| * #define NVSXYZ_CMD_COMMAND1 NVS_CMD_RESERVED + 1 |
| * @endcode |
| */ |
| #define NVS_CMD_RESERVED 32 |
| |
| /*! |
| * Common NVS_control status code reservation offset. |
| * NVS driver implementations should offset status codes with |
| * NVS_STATUS_RESERVED growing negatively. |
| * |
| * Example implementation specific status codes: |
| * @code |
| * #define NVSXYZ_STATUS_ERROR0 NVS_STATUS_RESERVED - 0 |
| * #define NVSXYZ_STATUS_ERROR1 NVS_STATUS_RESERVED - 1 |
| * #define NVSXYZ_STATUS_ERROR2 NVS_STATUS_RESERVED - 2 |
| * @endcode |
| */ |
| #define NVS_STATUS_RESERVED -32 |
| |
| /** |
| * @defgroup NVS_STATUS Status Codes |
| * NVS_STATUS_* macros are general status codes returned by NVS_control() |
| * @{ |
| * @ingroup NVS_CONTROL |
| */ |
| |
| /*! |
| * @brief Successful status code returned by NVS_control(). |
| * |
| * NVS_control() returns NVS_STATUS_SUCCESS if the control code was executed |
| * successfully. |
| */ |
| #define NVS_STATUS_SUCCESS 0 |
| |
| /*! |
| * @brief Generic error status code returned by NVS_control(). |
| * |
| * NVS_control() returns NVS_STATUS_ERROR if the control code was not executed |
| * successfully. |
| */ |
| #define NVS_STATUS_ERROR -1 |
| |
| /*! |
| * @brief An error status code returned by NVS_control() for undefined |
| * command codes. |
| * |
| * NVS_control() returns NVS_STATUS_UNDEFINEDCMD if the control code is not |
| * recognized by the driver implementation. |
| */ |
| #define NVS_STATUS_UNDEFINEDCMD -2 |
| /** @}*/ |
| |
| /** |
| * @defgroup NVS_CMD Command Codes |
| * NVS_CMD_* macros are general command codes for NVS_control(). Not all NVS |
| * driver implementations support these command codes. |
| * @{ |
| * @ingroup NVS_CONTROL |
| */ |
| |
| /* Add NVS_CMD_<commands> here */ |
| |
| /** @}*/ |
| |
| /** @}*/ |
| |
| /*! |
| * @brief Success return code |
| */ |
| #define NVS_SOK (0) |
| |
| /*! |
| * @brief General failure return code |
| */ |
| #define NVS_EFAIL (-1) |
| #define NVS_EOFFSET (-3) |
| #define NVS_EALIGN (-4) |
| #define NVS_ENOTENOUGHBYTES (-5) |
| #define NVS_EALREADYWRITTEN (-6) |
| #define NVS_ECOPYBLOCK (-7) |
| |
| /*! |
| * @brief NVS write flags |
| * |
| * The following flags can be or'd together and passed as a bit mask |
| * to NVS_write. |
| */ |
| |
| /*! |
| * @brief Exclusive write flag |
| * |
| * Only write if the area has not already been written to since the last |
| * erase. In the case of flash memory on some devices, once data is written |
| * to a location, that location cannot be written to again without first |
| * erasing the entire flash page. If the NVS_WRITE_EXCLUSIVE flag is |
| * set in the flags passed to NVS_write(), the location where the data |
| * will be written to is first checked if it has been modified since the |
| * last time the NVS block was erarsed. If that is the case, NVS_write() |
| * will return an error. |
| */ |
| #define NVS_WRITE_EXCLUSIVE (0x1) |
| |
| /*! |
| * @brief Erase write flag. |
| * |
| * If NVS_WRITE_ERASE is set in the flags passed to NVS_write(), the entire |
| * NVS block will be erased before being written to. |
| */ |
| #define NVS_WRITE_ERASE (0x2) |
| |
| /*! |
| * @brief Validate write flag. |
| * |
| * If NVS_WRITE_VALIDATE is set in the flags passed to NVS_write(), the region |
| * in the NVS block that was written to will be validated (i.e., compared |
| * against the data buffer passed to NVS_write()). |
| */ |
| #define NVS_WRITE_VALIDATE (0x4) |
| |
| /*! |
| * @brief NVS Parameters |
| * |
| * NVS parameters are used with the NVS_open() call. Default values for |
| * these parameters are set using NVS_Params_init(). |
| * |
| * @sa NVS_Params_init() |
| */ |
| typedef struct NVS_Params { |
| bool eraseOnOpen; /*!< Erase block on open */ |
| } NVS_Params; |
| |
| /*! |
| * @brief NVS attributes |
| * |
| * The address of an NVS_Attrs structure can be passed to NVS_getAttrs() |
| * to fill in the fields. |
| * |
| * pageSize is the size of the smallest erase page. This is hardware |
| * specific. For example, all TM4C123x devices use 1KB pages, but |
| * TM4C129x devices use 16KB pages. Please consult the device datasheet |
| * to determine the pageSize to use. |
| * |
| * blockSize is the actual size of the NVS storage block that the |
| * application chooses to manage. |
| * If pageSize is greater than blockSize, care should be taken not to |
| * use the storage on the page that is outside of the block, since it |
| * may be erased when writing to the block. The block size must not be |
| * greater than the page size. |
| * |
| * @sa NVS_getAttrs() |
| */ |
| typedef struct NVS_Attrs { |
| size_t pageSize; /*! Hardware page size */ |
| size_t blockSize; /*! Size of the NVS block to manage */ |
| } NVS_Attrs; |
| |
| /*! |
| * @brief A handle that is returned from the NVS_open() call. |
| */ |
| typedef struct NVS_Config *NVS_Handle; |
| |
| /*! |
| * @brief A function pointer to a driver specific implementation of |
| * NVS_close(). |
| */ |
| typedef void (*NVS_CloseFxn) (NVS_Handle handle); |
| |
| /*! |
| * @brief A function pointer to a driver specific implementation of |
| * NVS_control(). |
| */ |
| typedef int (*NVS_ControlFxn) (NVS_Handle handle, unsigned int cmd, |
| uintptr_t arg); |
| |
| /*! |
| * @brief A function pointer to a driver specific implementation of |
| * NVS_exit(). |
| */ |
| typedef void (*NVS_ExitFxn) (NVS_Handle handle); |
| |
| /*! |
| * @brief A function pointer to a driver specific implementation of |
| * NVS_getAttrs(). |
| */ |
| typedef int (*NVS_GetAttrsFxn) (NVS_Handle handle, NVS_Attrs *attrs); |
| |
| /*! |
| * @brief A function pointer to a driver specific implementation of |
| * NVS_init(). |
| */ |
| typedef void (*NVS_InitFxn) (NVS_Handle handle); |
| |
| /*! |
| * @brief A function pointer to a driver specific implementation of |
| * NVS_open(). |
| */ |
| typedef NVS_Handle (*NVS_OpenFxn) (NVS_Handle handle, NVS_Params *params); |
| |
| /*! |
| * @brief A function pointer to a driver specific implementation of |
| * NVS_read(). |
| */ |
| typedef int (*NVS_ReadFxn) (NVS_Handle handle, size_t offset, |
| void *buffer, size_t bufferSize); |
| |
| /*! |
| * @brief A function pointer to a driver specific implementation of |
| * NVS_write(). |
| */ |
| typedef int (*NVS_WriteFxn) (NVS_Handle handle, size_t offset, |
| void *buffer, size_t bufferSize, |
| unsigned int flags); |
| |
| /*! |
| * @brief The definition of an NVS function table that contains the |
| * required set of functions to control a specific NVS driver |
| * implementation. |
| */ |
| typedef struct NVS_FxnTable { |
| /*! Function to close the specified NVS block */ |
| NVS_CloseFxn closeFxn; |
| |
| /*! Function to apply control command to the specified NVS block */ |
| NVS_ControlFxn controlFxn; |
| |
| /*! Function to de-initialize the NVS module */ |
| NVS_ExitFxn exitFxn; |
| |
| /*! Function to get the NVS device-specific attributes */ |
| NVS_GetAttrsFxn getAttrsFxn; |
| |
| /*! Function to initialize the NVS module */ |
| NVS_InitFxn initFxn; |
| |
| /*! Function to open an NVS block */ |
| NVS_OpenFxn openFxn; |
| |
| /*! Function to read from the specified NVS block */ |
| NVS_ReadFxn readFxn; |
| |
| /*! Function to write to the specified NVS block */ |
| NVS_WriteFxn writeFxn; |
| } NVS_FxnTable; |
| |
| /*! |
| * @brief NVS Global configuration |
| * |
| * The NVS_Config structure contains a set of pointers used to characterize |
| * the NVS driver implementation. |
| * |
| * This structure needs to be defined before calling NVS_init() and it must |
| * not be changed thereafter. |
| * |
| * @sa NVS_init() |
| */ |
| typedef struct NVS_Config { |
| /*! Pointer to a table of driver-specific implementations of NVS APIs */ |
| NVS_FxnTable const *fxnTablePtr; |
| |
| /*! Pointer to a driver specific data object */ |
| void *object; |
| |
| /*! Pointer to a driver specific hardware attributes structure */ |
| void const *hwAttrs; |
| } NVS_Config; |
| |
| /*! |
| * @brief Function to close an NVS handle |
| * |
| * @param handle A handle returned from NVS_open() |
| * |
| * @sa NVS_open() |
| */ |
| extern void NVS_close(NVS_Handle handle); |
| |
| /*! |
| * @brief Function performs implementation specific features on a given |
| * NVS_Handle. |
| * |
| * @pre NVS_open() must be called first. |
| * |
| * @param handle An NVS handle returned from NVS_open() |
| * |
| * @param cmd A command value defined by the driver specific |
| * implementation |
| * |
| * @param arg An optional R/W (read/write) argument that is |
| * accompanied with cmd |
| * |
| * @return Implementation specific return codes. Negative values indicate |
| * unsuccessful operations. |
| * |
| * @sa NVS_open() |
| */ |
| extern int NVS_control(NVS_Handle handle, unsigned int cmd, uintptr_t arg); |
| |
| /*! |
| * @brief Erase the block of storage reference by an NVS handle |
| * |
| * @param handle A handle returned from NVS_open() |
| * |
| * @return NVS_SOK Success. |
| * @return NVS_EFAIL An error occurred erasing the flash. |
| */ |
| extern int NVS_erase(NVS_Handle handle); |
| |
| /*! |
| * @brief Function to de-initialize the NVS module |
| * |
| * @pre NVS_init() was called. |
| */ |
| extern void NVS_exit(void); |
| |
| /*! |
| * @brief Function to get the NVS attributes |
| * |
| * @param handle A handle returned from NVS_open() |
| * |
| * @param attrs Location to store attributes. |
| */ |
| extern int NVS_getAttrs(NVS_Handle handle, NVS_Attrs *attrs); |
| |
| /*! |
| * @brief Function to initialize the NVS module |
| * |
| * @pre The NVS_config structure must exist and be persistent before this |
| * function can be called. This function must also be called before |
| * any other NVS APIs. |
| */ |
| extern void NVS_init(void); |
| |
| /*! |
| * @brief Get an NVS block for reading and writing. |
| * |
| * @pre NVS_init() was called. |
| * |
| * @param index Index in the NVS_config table of the block |
| * to manage. |
| * |
| * @param params Pointer to a parameter block. If NULL, default |
| * parameter values will be used. |
| */ |
| extern NVS_Handle NVS_open(int index, NVS_Params *params); |
| |
| /*! |
| * @brief Read data from an NVS block. |
| * |
| * @param handle A handle returned from NVS_open() |
| * |
| * @param offset The byte offset into the NVS block to start |
| * reading from. |
| * |
| * @param buffer A buffer to copy the data to. |
| * |
| * @param bufferSize The size of the buffer (number of bytes to read). |
| * |
| * @return NVS_SOK Success. |
| * @return NVS_EOFFSET The location and size to read from does not |
| * lie completely within the NVS block. |
| * |
| * @remark This call may block to ensure atomic access to the block. |
| */ |
| extern int NVS_read(NVS_Handle handle, size_t offset, void *buffer, |
| size_t bufferSize); |
| |
| /*! |
| * @brief Write data to an NVS block. |
| * |
| * @param handle A handle returned from NVS_open() |
| * |
| * @param offset The byte offset into the NVS block to start |
| * writing. offset must be 4-byte aligned. |
| * |
| * @param buffer A buffer conntaining data to write to |
| * the NVS block. If buffer is NULL, the block |
| * will be erased. A non-NULL buffer must be |
| * aligned on a 4-byte boundary. |
| * |
| * @param bufferSize The size of the buffer (number of bytes to write). |
| * bufferSize must be a multiple of 4 bytes. |
| * |
| * @param flags Write flags (NVS_WRITE_EXCLUSIVE, NVS_WRITE_ERASE, |
| * NVS_WRITE_VALIDATE). |
| * |
| * @return NVS_SOK Success. |
| * @return NVS_EOFFSET The location and size to write to does not |
| * lie completely within the NVS block. |
| * @return NVS_EALIGN The offset or bufferSize is not 4-byte aligned. |
| * @return NVS_ALREADYWRITTEN |
| * The region to write to (the bufferSize region |
| * starting at offset into the block) has already |
| * been written to since the last erase, and |
| * NVS_WRITE_EXCLUSIVE is set in the flags parameter. |
| * |
| * @remark This call may block to ensure atomic access to the block. |
| */ |
| extern int NVS_write(NVS_Handle handle, size_t offset, void *buffer, |
| size_t bufferSize, unsigned int flags); |
| |
| #if defined (__cplusplus) |
| } |
| #endif /* defined (__cplusplus) */ |
| |
| /*@}*/ |
| #endif /* ti_drivers_NVS__include */ |
