NVS.h

Go to the documentation of this file.

/*
 * Copyright (c) 2015-2018, 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      Non-Volatile Storage driver interface
 *
 *  To use the NVS driver, ensure that the correct driver library for your
 *  device is linked in and include this header file as follows:
 *  @code
 *  #include <ti/drivers/NVS.h>
 *  @endcode
 *
 *  This module serves as the main interface for applications. Its purpose
 *  is to redirect the NVS APIs to specific driver implementations
 *  which are specified using a pointer to a #NVS_FxnTable.
 *
 *  # Overview #
 *
 *  The NVS module allows you to manage non-volatile memory.  Using the
 *  NVS APIs, you can read and write data from and to persistent storage.
 *
 *  Each NVS object manages a region of non-volatile memory. The size is
 *  specified in the device specific driver's hardware attributes. A sector
 *  is the smallest unit of non-volatile storage that can be erased at
 *  one time. The size of the sector, or sector size, is hardware specific and
 *  may be meaningless for some non-volatile storage hardware. For flash
 *  memory devices, the region must be aligned with the sector size. That is,
 *  the region must start on a sector boundary. Additionally, the overall size
 *  of the region must be an integer multiple of the sector size.
 *
 *  # Thread Safety #
 *
 *  All NVS APIs are globally thread safe. Consequently, only one write,
 *  erase, or read in the case of SPI flash operation is allowed to be
 *  performed at a time, even for distinct NVS regions. Threads initiating
 *  new NVS writes or erases will block until any current operation completes.
 *
 *  # Interrupt Latency During Flash Operations #
 *
 *  When writing to or erasing internal flash, interrupts must be disabled
 *  to avoid executing code in flash while the flash is being reprogrammed.
 *  This constraint is met internally by the driver. User code does not need
 *  to safeguard against this.
 *
 *  Care must be taken by the user to not perform flash write or erase
 *  operations during latency critical phases of an application. See the
 *  NVS_lock() and NVS_unlock() API descriptions for more information.
 *
 *  # Usage #
 *
 *  The NVS driver interface provides device independent APIs, data types,
 *  and macros.  The following code example opens an NVS region instance,
 *  writes a string into it, then prints the string after reading it back
 *  into a local buffer, and also prints the string from its directly
 *  addressable location in flash memory.
 *
 *  @code
 *    NVS_Handle rHandle;
 *    NVS_Attrs regionAttrs;
 *    NVS_Params nvsParams;
 *    uint_fast16_t status;
 *    char buf[32];
 *
 *    // Initialize the NVS driver
 *    NVS_init();
 *
 *    //
 *    // Open the NVS region specified by the 0 element in the NVS_config[]
 *    // array defined in Board.c.
 *    // Use default NVS_Params to open this memory region, hence NULL
 *    //
 *    rHandle = NVS_open(Board_NVSINTERNAL, NULL);
 *
 *    // confirm that the NVS region opened properly
 *    if (rHandle == NULL) {
 *        // Error opening NVS driver
 *        while (1);
 *    }
 *
 *    // fetch the generic NVS region attributes
 *    NVS_getAttrs(rHandle, &regionAttrs);
 *
 *    // erase the first sector of the NVS region
 *    status = NVS_erase(rHandle, 0, regionAttrs.sectorSize);
 *    if (status != NVS_STATUS_SUCCESS) {
 *        // Error handling code
 *    }
 *
 *    // write "Hello" to the base address of region 0, verify after write
 *    status = NVS_write(rHandle, 0, "Hello", strlen("Hello")+1, NVS_POST_VERIFY);
 *    if (status != NVS_STATUS_SUCCESS) {
 *        // Error handling code
 *    }
 *
 *    // copy "Hello" from region0 into local 'buf'
 *    status = NVS_read(rHandle, 0, buf, strlen("Hello")+1);
 *    if (status != NVS_STATUS_SUCCESS) {
 *        // Error handling code
 *    }
 *
 *    // print string from fetched NVS storage
 *    System_printf("%s\n", buf);
 *
 *    // print string using direct address reference if valid
 *    if (regionAttrs.regionBase != NVS_REGION_NOT_ADDRESSABLE) {
 *       System_printf("%s\n", regionAttrs.regionBase);
 *    }
 *
 *    // close the region
 *    NVS_close(rHandle);
 *
 *  @endcode
 *
 *  Details for the example code above are described in the following
 *  subsections.
 *
 *  ### NVS Driver Configuration #
 *
 *  In order to use the NVS APIs, the application is required
 *  to provide device-specific NVS configuration in the Board.c file.
 *  The NVS driver interface defines a configuration data structure,
 *  #NVS_Config.
 *
 *  The application must declare an array of #NVS_Config elements, named
 *  \p NVS_config[].  Each element of \p NVS_config[] is populated with
 *  pointers to a device specific NVS driver implementation's function
 *  table, driver object, and hardware attributes.  The hardware attributes
 *  define properties such as the NVS region's base address and size,
 *  Each element in \p NVS_config[] corresponds to a NVS instance, and none
 *  of the elements should have NULL pointers.
 *
 *  You will need to check the device-specific NVS driver implementation's
 *  header file for example configuration.  Please also refer to the
 *  Board.c file of any of the provided examples to see the NVS configuration.
 *
 *  ### Initializing the NVS Driver #
 *
 *  NVS_init() must be called before any other NVS APIs.  This function
 *  calls the device implementation's NVS initialization function, for each
 *  element of \p NVS_config[].
 *
 *  ### Opening the NVS Driver #
 *
 *  Opening a NVS requires four steps:
 *  1.  Optionally create and initialize a #NVS_Params structure.
 *  2.  Fill in the desired parameters.
 *  3.  Call NVS_open(), passing the index of the NVS region in the #NVS_Config
 *      structure, and the address of the #NVS_Params structure.
 *  4.  Check that the #NVS_Handle returned by NVS_open() is non-NULL,
 *      and save it.  The handle will be used to read and write to the
 *      NVS you just opened.
 *
 *  \note Each NVS index can only be opened exclusively. Calling NVS_open()
 *  multiple times with the same index will result in an error. The index can
 *  be re-used if NVS_close() is called first.
 *
 *****************************************************************************
 */

#ifndef ti_drivers_NVS__include
#define ti_drivers_NVS__include

#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>

#if defined (__cplusplus)
extern "C" {
#endif

#define NVS_CMD_RESERVED            (32)

#define NVS_STATUS_RESERVED         (-32)

#define NVS_STATUS_SUCCESS          (0)

#define NVS_STATUS_ERROR            (-1)

#define NVS_STATUS_UNDEFINEDCMD     (-2)

#define NVS_STATUS_TIMEOUT          (-3)

#define NVS_STATUS_INV_OFFSET       (-4)

#define NVS_STATUS_INV_ALIGNMENT    (-5)

#define NVS_STATUS_INV_SIZE         (-6)

#define NVS_STATUS_INV_WRITE        (-7)

/* Add NVS_CMD_<commands> here */

#define NVS_WRITE_ERASE             (0x1)

#define NVS_WRITE_PRE_VERIFY        (0x2)

#define NVS_WRITE_POST_VERIFY       (0x4)

#define NVS_LOCK_WAIT_FOREVER       (~(0U))

#define NVS_LOCK_NO_WAIT            (0U)

#define NVS_REGION_NOT_ADDRESSABLE  ((void *)(~(0U)))

typedef struct NVS_Params {
    void *custom;    
} NVS_Params;

typedef struct NVS_Attrs {
    void   *regionBase;   
    size_t  regionSize;   
    size_t  sectorSize;   
} NVS_Attrs;

typedef struct NVS_Config_ *NVS_Handle;

typedef void (*NVS_CloseFxn) (NVS_Handle handle);

typedef int_fast16_t (*NVS_ControlFxn) (NVS_Handle handle, uint_fast16_t cmd,
                                        uintptr_t arg);

typedef int_fast16_t (*NVS_EraseFxn) (NVS_Handle handle, size_t offset,
                                      size_t size);

typedef void (*NVS_GetAttrsFxn) (NVS_Handle handle, NVS_Attrs *attrs);

typedef void (*NVS_InitFxn) (void);

typedef NVS_Handle (*NVS_OpenFxn) (uint_least8_t index, NVS_Params *params);

typedef int_fast16_t (*NVS_ReadFxn) (NVS_Handle handle, size_t offset,
                                     void *buffer, size_t bufferSize);

typedef int_fast16_t (*NVS_WriteFxn) (NVS_Handle handle, size_t offset,
                                      void *buffer, size_t bufferSize,
                                      uint_fast16_t flags);

typedef int_fast16_t (*NVS_LockFxn) (NVS_Handle handle, uint32_t timeout);

typedef void (*NVS_UnlockFxn) (NVS_Handle handle);

typedef struct NVS_FxnTable {
    NVS_CloseFxn        closeFxn;

    NVS_ControlFxn      controlFxn;

    NVS_EraseFxn        eraseFxn;

    NVS_GetAttrsFxn     getAttrsFxn;

    NVS_InitFxn         initFxn;

    NVS_LockFxn         lockFxn;

    NVS_OpenFxn         openFxn;

    NVS_ReadFxn         readFxn;

    NVS_UnlockFxn       unlockFxn;

    NVS_WriteFxn        writeFxn;
} NVS_FxnTable;

typedef struct NVS_Config_ {
    NVS_FxnTable  const *fxnTablePtr;

    void                *object;

    void          const *hwAttrs;
} NVS_Config;

extern void NVS_close(NVS_Handle handle);

extern int_fast16_t NVS_control(NVS_Handle handle, uint_fast16_t cmd, uintptr_t arg);

extern int_fast16_t NVS_erase(NVS_Handle handle, size_t offset, size_t size);

extern void NVS_getAttrs(NVS_Handle handle, NVS_Attrs *attrs);

extern void NVS_init(void);

extern int_fast16_t NVS_lock(NVS_Handle handle, uint32_t timeout);

extern NVS_Handle NVS_open(uint_least8_t index, NVS_Params *params);

extern void NVS_Params_init(NVS_Params *params);

extern int_fast16_t NVS_read(NVS_Handle handle, size_t offset, void *buffer,
                    size_t bufferSize);

extern void NVS_unlock(NVS_Handle handle);

extern int_fast16_t NVS_write(NVS_Handle handle, size_t offset, void *buffer,
                     size_t bufferSize, uint_fast16_t flags);

#if defined (__cplusplus)
}
#endif /* defined (__cplusplus) */

#endif /* ti_drivers_NVS__include */