NVS.h

Go to the documentation of this file.

/*
 * Copyright (c) 2015-2019, 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
 *
 *  @anchor ti_drivers_NVS_Overview
 *  # 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 is used to manage a region of non-volatile memory.
 *  The size of the region 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.
 *
 *  <hr>
 *  @anchor ti_drivers_NVS_Usage
 *  # Usage
 *
 *  This section provides a basic @ref ti_drivers_NVS_Synopsis
 *  "usage summary" and a set of @ref ti_drivers_NVS_Examples "examples"
 *  in the form of commented code fragments. Detailed descriptions of the
 *  APIs are provided in subsequent sections.

 *  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.
 *
 *  @anchor ti_drivers_NVS_Synopsis
 *  ## Synopsis
 *  @anchor ti_drivers_NVS_Synopsis_Code
 *  @code
 *  // Import NVS Driver definitions
 *  #include <ti/drivers/NVS.h>
 *
 *  // One time init of NVS driver
 *  NVS_init();
 *
 *  // Initialize optional NVS parameters
 *  NVS_Params_init(&nvsParams);
 *
 *  // Open NVS driver instance
 *  nvsRegion = NVS_open(config_NVS0, &nvsParams);
 *
 *  // write "Hello" to the base address of region 0, verify after write
 *  status = NVS_write(nvsRegion, 0, "Hello", strlen("Hello")+1, NVS_POST_VERIFY);
 *
 *  // Close NVS region
 *  NVS_close(nvsRegion);
 *
 *  @endcode
 *
 *  <hr>
 *  @anchor ti_drivers_NVS_Examples
 *  # Examples
 *
 *  @li @ref ti_drivers_NVS_Examples_open "Opening an NVS region instance"
 *  @li @ref ti_drivers_NVS_Examples_typical "Typical NVS region operations"
 *
 *  @anchor ti_drivers_NVS_Examples_open
 *  ## Opening an NVS region instance
 *
 *  @code
 *      NVS_Handle nvsRegion;
 *      NVS_Params nvsParams;
 *
 *      NVS_Params_init(&nvsParams);
 *      nvsRegion = NVS_open(CONFIG_NVS0, &nvsParams);
 *  @endcode
 *
 *  @anchor ti_drivers_NVS_Examples_typical
 *  ## Erasing, writing, reading an NVS region
 *
 *  The following code example opens an NVS region instance, erases the first
 *  sector of that region, writes a string into it, then prints the string
 *  after reading it back into a local buffer. If the string is directly CPU
 *  addressable (i.e. not in SPI flash), the string is printed from
 *  its location in flash memory.
 *
 *  @code
 *
 *      // Import NVS Driver definitions
 *      #include <ti/drivers/NVS.h>
 *
 *      NVS_Handle nvsRegion;
 *      NVS_Attrs regionAttrs;
 *
 *      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 defined in ti_drivers_config.c.
 *      //
 *      // Use default NVS_Params to open this memory region, hence 'NULL'
 *      //
 *      nvsRegion = NVS_open(CONFIG_NVS0, NULL);
 *
 *      // Confirm that the NVS region opened properly
 *      if (nvsRegion == NULL) {
 *          // Error handling code
 *      }
 *
 *      // Fetch the generic NVS region attributes for nvsRegion
 *      NVS_getAttrs(nvsRegion, &regionAttrs);
 *
 *      // Erase the first sector of nvsRegion
 *      status = NVS_erase(nvsRegion, 0, regionAttrs.sectorSize);
 *      if (status != NVS_STATUS_SUCCESS) {
 *          // Error handling code
 *      }
 *
 *      // Write "Hello" to the base address of nvsRegion, verify after write
 *      status = NVS_write(nvsRegion, 0, "Hello", strlen("Hello")+1, NVS_POST_VERIFY);
 *      if (status != NVS_STATUS_SUCCESS) {
 *          // Error handling code
 *      }
 *
 *      // Copy "Hello" from nvsRegion into local 'buf'
 *      status = NVS_read(nvsRegion, 0, buf, strlen("Hello")+1);
 *      if (status != NVS_STATUS_SUCCESS) {
 *          // Error handling code
 *      }
 *
 *      // Print the string from fetched NVS storage
 *      System_printf("%s\n", buf);
 *
 *      //
 *      // Print the string using direct flash address reference if valid
 *      //
 *      // When the NVS driver is managing SPI flash non volatile
 *      // storage, the regionBase attribute will be `NVS_REGION_NOT_ADDRESSABLE`
 *      //
 *      if (regionAttrs.regionBase != NVS_REGION_NOT_ADDRESSABLE) {
 *         System_printf("%s\n", regionAttrs.regionBase);
 *      }
 *
 *      // close the region
 *      NVS_close(nvsRegion);
 *
 *  @endcode
 *
 *  <hr>
 *  @anchor ti_drivers_NVS_Configuration
 *  # Configuration
 *
 *  Refer to the @ref driver_configuration "Driver's Configuration" section
 *  for driver configuration information.
 *  <hr>
 *
 *  # Example discussion
 *
 *  Details for the @ref ti_drivers_NVS_Examples_typical "Typical NVS region operations"
 *  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 ti_drivers_config.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
 *  ti_drivers_config.c file of any of the 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.
 *
 *  <hr>
 *  # 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.
 *
 *****************************************************************************
 */

#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
{
    void *custom;    
} NVS_Params;

typedef struct
{
    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_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 */