NVS.h

Go to the documentation of this file.

/*
 * Copyright (c) 2015-2017, 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 of a size
 *  specified in the NVS object's hardware attributes.  A 'sector' refers to
 *  the smallest unit of non-volatile storage that can be erased at one time,
 *  and the 'sectorSize' is the size of this unit. Flash sector size is
 *  hardware specific and may be meaningless for some persistent storage
 *  systems.  However, in the case of flash memory devices, the size
 *  of a managed 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 0th element in the NVS_config[] array
 *    // in Board.c
 *    //
 *    rHandle = NVS_open(0, NULL); // use default NVS_Params to open this flash region
 *
 *    // confirm that the NVS region opened properly
 *    if (rHandle == NULL) {
 *        ...
 *    }
 *
 *    // 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) {
 *        ...
 *    }
 *
 *    // 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) {
 *        ...
 *    }
 *
 *    // copy "Hello" from region0 into local 'buf'
 *    status = NVS_read(rHandle, 0, buf, strlen("Hello")+1);
 *    if (status != NVS_STATUS_SUCCESS) {
 *        ...
 *    }
 *
 *    // 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:
 *
 *  @code
 *  typedef struct NVS_Config_ {
 *      NVS_FxnTable const    *fxnTablePtr;
 *      void                  *object;
 *      void                  *hwAttrs;
 *  } NVS_Config;
 *  @endcode
 *
 *  The application must declare an array of NVS_Config elements, named
 *  NVS_config[].  Each element of 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 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 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.
 *
 *  Only one NVS index can be used at a time; calling NVS_open() a second
 *  time with the same index previously passed to NVS_open() will result in
 *  an error.  You can, though, re-use the index if the instance is closed
 *  via NVS_close().
 *
 *****************************************************************************
 */

#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 */