git.sur5r.net Git - freertos/blob - FreeRTOS/Demo/CORTEX_M4_SimpleLink_CC3220SF_CCS/ti/drivers/NVS.h

   1 /*
   2  * Copyright (c) 2015-2016, Texas Instruments Incorporated
   3  * All rights reserved.
   4  *
   5  * Redistribution and use in source and binary forms, with or without
   6  * modification, are permitted provided that the following conditions
   7  * are met:
   8  *
   9  * *  Redistributions of source code must retain the above copyright
  10  *    notice, this list of conditions and the following disclaimer.
  11  *
  12  * *  Redistributions in binary form must reproduce the above copyright
  13  *    notice, this list of conditions and the following disclaimer in the
  14  *    documentation and/or other materials provided with the distribution.
  15  *
  16  * *  Neither the name of Texas Instruments Incorporated nor the names of
  17  *    its contributors may be used to endorse or promote products derived
  18  *    from this software without specific prior written permission.
  19  *
  20  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
  21  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
  22  * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  23  * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
  24  * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
  25  * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
  26  * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
  27  * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
  28  * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
  29  * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
  30  * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  31  */
  32 /** ==========================================================================
  33  *  @file       NVS.h
  34  *
  35  *  @brief      <b>PRELIMINARY</b> Non-Volatile Storage Driver.
  36  *
  37  *  <b>WARNING</b> These APIs are <b>PRELIMINARY</b>, and subject to
  38  *  change in the next few months.
  39  *
  40  *  The NVS header file should be included in an application as follows:
  41  *  @code
  42  *  #include <ti/drivers/NVS.h>
  43  *  @endcode
  44  *
  45  *  # Operation #
  46  *
  47  *  The NVS module allows you to manage non-volatile memory.  Using the
  48  *  NVS APIs, you can read and write data to persistant storage.  Each NVS
  49  *  object manages a 'block' of non-volatile memory of a size specified in
  50  *  the NVS object's hardware attributes.  A 'page' will refer to the
  51  *  smallest unit of non-volatile storage that can be erased at one time,
  52  *  and the page size is the size of this unit.  This is hardware specific
  53  *  and may be meaningless for some persistant storage systems.  However,
  54  *  in the case of flash memory, page size should be taken into account
  55  *  when deciding the block size for NVS to manage.  For example on
  56  *  TM4C129x devices, a page size is 16KB.
  57  *
  58  *  When page size is relevant (e.g. for flash memory), the size of an
  59  *  NVS block size must be less than or equal to the page size.  The block
  60  *  size can be less than the page size, however, care must be taken not
  61  *  to use the area in the page outside of the block.  When the block is
  62  *  erased, the entire page will be erased, clearing anything in the page
  63  *  that was written outside of the block.
  64  *
  65  *  See the device specific NVS header file for configuration details.
  66  *
  67  *  ==========================================================================
  68  */
  69
  70 #ifndef ti_drivers_NVS__include
  71 #define ti_drivers_NVS__include
  72
  73 #include <stdint.h>
  74 #include <stddef.h>
  75 #include <stdbool.h>
  76
  77 #if defined (__cplusplus)
  78 extern "C" {
  79 #endif
  80
  81 /**
  82  *  @defgroup NVS_CONTROL NVS_control command and status codes
  83  *  These NVS macros are reservations for NVS.h
  84  *  @{
  85  */
  86
  87 /*!
  88  * Common NVS_control command code reservation offset.
  89  * NVS driver implementations should offset command codes with NVS_CMD_RESERVED
  90  * growing positively
  91  *
  92  * Example implementation specific command codes:
  93  * @code
  94  * #define NVSXYZ_CMD_COMMAND0     NVS_CMD_RESERVED + 0
  95  * #define NVSXYZ_CMD_COMMAND1     NVS_CMD_RESERVED + 1
  96  * @endcode
  97  */
  98 #define NVS_CMD_RESERVED            32
  99
 100 /*!
 101  * Common NVS_control status code reservation offset.
 102  * NVS driver implementations should offset status codes with
 103  * NVS_STATUS_RESERVED growing negatively.
 104  *
 105  * Example implementation specific status codes:
 106  * @code
 107  * #define NVSXYZ_STATUS_ERROR0    NVS_STATUS_RESERVED - 0
 108  * #define NVSXYZ_STATUS_ERROR1    NVS_STATUS_RESERVED - 1
 109  * #define NVSXYZ_STATUS_ERROR2    NVS_STATUS_RESERVED - 2
 110  * @endcode
 111  */
 112 #define NVS_STATUS_RESERVED        -32
 113
 114 /**
 115  *  @defgroup NVS_STATUS Status Codes
 116  *  NVS_STATUS_* macros are general status codes returned by NVS_control()
 117  *  @{
 118  *  @ingroup NVS_CONTROL
 119  */
 120
 121 /*!
 122  * @brief   Successful status code returned by NVS_control().
 123  *
 124  * NVS_control() returns NVS_STATUS_SUCCESS if the control code was executed
 125  * successfully.
 126  */
 127 #define NVS_STATUS_SUCCESS         0
 128
 129 /*!
 130  * @brief   Generic error status code returned by NVS_control().
 131  *
 132  * NVS_control() returns NVS_STATUS_ERROR if the control code was not executed
 133  * successfully.
 134  */
 135 #define NVS_STATUS_ERROR          -1
 136
 137 /*!
 138  * @brief   An error status code returned by NVS_control() for undefined
 139  * command codes.
 140  *
 141  * NVS_control() returns NVS_STATUS_UNDEFINEDCMD if the control code is not
 142  * recognized by the driver implementation.
 143  */
 144 #define NVS_STATUS_UNDEFINEDCMD   -2
 145 /** @}*/
 146
 147 /**
 148  *  @defgroup NVS_CMD Command Codes
 149  *  NVS_CMD_* macros are general command codes for NVS_control(). Not all NVS
 150  *  driver implementations support these command codes.
 151  *  @{
 152  *  @ingroup NVS_CONTROL
 153  */
 154
 155 /* Add NVS_CMD_<commands> here */
 156
 157 /** @}*/
 158
 159 /** @}*/
 160
 161 /*!
 162  *  @brief Success return code
 163  */
 164 #define NVS_SOK (0)
 165
 166 /*!
 167  *  @brief General failure return code
 168  */
 169 #define NVS_EFAIL               (-1)
 170 #define NVS_EOFFSET             (-3)
 171 #define NVS_EALIGN              (-4)
 172 #define NVS_ENOTENOUGHBYTES     (-5)
 173 #define NVS_EALREADYWRITTEN     (-6)
 174 #define NVS_ECOPYBLOCK          (-7)
 175
 176 /*!
 177  *  @brief NVS write flags
 178  *
 179  *  The following flags can be or'd together and passed as a bit mask
 180  *  to NVS_write.
 181  */
 182
 183 /*!
 184  *  @brief Exclusive write flag
 185  *
 186  *  Only write if the area has not already been written to since the last
 187  *  erase.  In the case of flash memory on some devices, once data is written
 188  *  to a location, that location cannot be written to again without first
 189  *  erasing the entire flash page.  If the NVS_WRITE_EXCLUSIVE flag is
 190  *  set in the flags passed to NVS_write(), the location where the data
 191  *  will be written to is first checked if it has been modified since the
 192  *  last time the NVS block was erarsed.  If that is the case, NVS_write()
 193  *  will return an error.
 194  */
 195 #define NVS_WRITE_EXCLUSIVE           (0x1)
 196
 197 /*!
 198  *  @brief Erase write flag.
 199  *
 200  *  If NVS_WRITE_ERASE is set in the flags passed to NVS_write(), the entire
 201  *  NVS block will be erased before being written to.
 202  */
 203 #define NVS_WRITE_ERASE               (0x2)
 204
 205 /*!
 206  *  @brief Validate write flag.
 207  *
 208  *  If NVS_WRITE_VALIDATE is set in the flags passed to NVS_write(), the region
 209  *  in the NVS block that was written to will be validated (i.e., compared
 210  *  against the data buffer passed to NVS_write()).
 211  */
 212 #define NVS_WRITE_VALIDATE            (0x4)
 213
 214 /*!
 215  *  @brief    NVS Parameters
 216  *
 217  *  NVS parameters are used with the NVS_open() call. Default values for
 218  *  these parameters are set using NVS_Params_init().
 219  *
 220  *  @sa       NVS_Params_init()
 221  */
 222 typedef struct NVS_Params {
 223     bool    eraseOnOpen;    /*!< Erase block on open */
 224 } NVS_Params;
 225
 226 /*!
 227  *  @brief      NVS attributes
 228  *
 229  *  The address of an NVS_Attrs structure can be passed to NVS_getAttrs()
 230  *  to fill in the fields.
 231  *
 232  *  pageSize is the size of the smallest erase page.  This is hardware
 233  *  specific.  For example, all TM4C123x devices use 1KB pages, but
 234  *  TM4C129x devices use 16KB pages. Please consult the device datasheet
 235  *  to determine the pageSize to use.
 236  *
 237  *  blockSize is the actual size of the NVS storage block that the
 238  *  application chooses to manage.
 239  *  If pageSize is greater than blockSize, care should be taken not to
 240  *  use the storage on the page that is outside of the block, since it
 241  *  may be erased when writing to the block.  The block size must not be
 242  *  greater than the page size.
 243  *
 244  *  @sa     NVS_getAttrs()
 245  */
 246 typedef struct NVS_Attrs {
 247     size_t  pageSize;    /*! Hardware page size */
 248     size_t  blockSize;   /*! Size of the NVS block to manage */
 249 } NVS_Attrs;
 250
 251 /*!
 252  *  @brief      A handle that is returned from the NVS_open() call.
 253  */
 254 typedef struct NVS_Config      *NVS_Handle;
 255
 256 /*!
 257  *  @brief      A function pointer to a driver specific implementation of
 258  *              NVS_close().
 259  */
 260 typedef void        (*NVS_CloseFxn)    (NVS_Handle handle);
 261
 262 /*!
 263  *  @brief      A function pointer to a driver specific implementation of
 264  *              NVS_control().
 265  */
 266 typedef int         (*NVS_ControlFxn)  (NVS_Handle handle, unsigned int cmd,
 267                                         uintptr_t arg);
 268
 269 /*!
 270  *  @brief      A function pointer to a driver specific implementation of
 271  *              NVS_exit().
 272  */
 273 typedef void        (*NVS_ExitFxn)     (NVS_Handle handle);
 274
 275 /*!
 276  *  @brief      A function pointer to a driver specific implementation of
 277  *              NVS_getAttrs().
 278  */
 279 typedef int         (*NVS_GetAttrsFxn) (NVS_Handle handle, NVS_Attrs *attrs);
 280
 281 /*!
 282  *  @brief      A function pointer to a driver specific implementation of
 283  *              NVS_init().
 284  */
 285 typedef void        (*NVS_InitFxn)     (NVS_Handle handle);
 286
 287 /*!
 288  *  @brief      A function pointer to a driver specific implementation of
 289  *              NVS_open().
 290  */
 291 typedef NVS_Handle  (*NVS_OpenFxn)     (NVS_Handle handle, NVS_Params *params);
 292
 293 /*!
 294  *  @brief      A function pointer to a driver specific implementation of
 295  *              NVS_read().
 296  */
 297 typedef int         (*NVS_ReadFxn)     (NVS_Handle handle, size_t offset,
 298                                         void *buffer, size_t bufferSize);
 299
 300 /*!
 301  *  @brief      A function pointer to a driver specific implementation of
 302  *              NVS_write().
 303  */
 304 typedef int         (*NVS_WriteFxn)    (NVS_Handle handle, size_t offset,
 305                                         void *buffer, size_t bufferSize,
 306                                         unsigned int flags);
 307
 308 /*!
 309  *  @brief      The definition of an NVS function table that contains the
 310  *              required set of functions to control a specific NVS driver
 311  *              implementation.
 312  */
 313 typedef struct NVS_FxnTable {
 314     /*! Function to close the specified NVS block */
 315     NVS_CloseFxn        closeFxn;
 316
 317     /*! Function to apply control command to the specified NVS block */
 318     NVS_ControlFxn      controlFxn;
 319
 320     /*! Function to de-initialize the NVS module */
 321     NVS_ExitFxn         exitFxn;
 322
 323     /*! Function to get the NVS device-specific attributes */
 324     NVS_GetAttrsFxn     getAttrsFxn;
 325
 326     /*! Function to initialize the NVS module */
 327     NVS_InitFxn         initFxn;
 328
 329     /*! Function to open an NVS block */
 330     NVS_OpenFxn         openFxn;
 331
 332     /*! Function to read from the specified NVS block */
 333     NVS_ReadFxn         readFxn;
 334
 335     /*! Function to write to the specified NVS block */
 336     NVS_WriteFxn        writeFxn;
 337 } NVS_FxnTable;
 338
 339 /*!
 340  *  @brief  NVS Global configuration
 341  *
 342  *  The NVS_Config structure contains a set of pointers used to characterize
 343  *  the NVS driver implementation.
 344  *
 345  *  This structure needs to be defined before calling NVS_init() and it must
 346  *  not be changed thereafter.
 347  *
 348  *  @sa     NVS_init()
 349  */
 350 typedef struct NVS_Config {
 351     /*! Pointer to a table of driver-specific implementations of NVS APIs */
 352     NVS_FxnTable const *fxnTablePtr;
 353
 354     /*! Pointer to a driver specific data object */
 355     void               *object;
 356
 357     /*! Pointer to a driver specific hardware attributes structure */
 358     void         const *hwAttrs;
 359 } NVS_Config;
 360
 361 /*!
 362  *  @brief  Function to close an NVS handle
 363  *
 364  *  @param  handle      A handle returned from NVS_open()
 365  *
 366  *  @sa     NVS_open()
 367  */
 368 extern void NVS_close(NVS_Handle handle);
 369
 370 /*!
 371  *  @brief  Function performs implementation specific features on a given
 372  *          NVS_Handle.
 373  *
 374  *  @pre    NVS_open() must be called first.
 375  *
 376  *  @param  handle      An NVS handle returned from NVS_open()
 377  *
 378  *  @param  cmd         A command value defined by the driver specific
 379  *                      implementation
 380  *
 381  *  @param  arg         An optional R/W (read/write) argument that is
 382  *                      accompanied with cmd
 383  *
 384  *  @return Implementation specific return codes. Negative values indicate
 385  *          unsuccessful operations.
 386  *
 387  *  @sa     NVS_open()
 388  */
 389 extern int NVS_control(NVS_Handle handle, unsigned int cmd, uintptr_t arg);
 390
 391 /*!
 392  *  @brief  Erase the block of storage reference by an NVS handle
 393  *
 394  *  @param  handle      A handle returned from NVS_open()
 395  *
 396  *  @return  NVS_SOK    Success.
 397  *  @return  NVS_EFAIL  An error occurred erasing the flash.
 398  */
 399 extern int NVS_erase(NVS_Handle handle);
 400
 401 /*!
 402  *  @brief  Function to de-initialize the NVS module
 403  *
 404  *  @pre    NVS_init() was called.
 405  */
 406 extern void NVS_exit(void);
 407
 408 /*!
 409  *  @brief  Function to get the NVS attributes
 410  *
 411  *  @param  handle      A handle returned from NVS_open()
 412  *
 413  *  @param  attrs       Location to store attributes.
 414  */
 415 extern int NVS_getAttrs(NVS_Handle handle, NVS_Attrs *attrs);
 416
 417 /*!
 418  *  @brief  Function to initialize the NVS module
 419  *
 420  *  @pre    The NVS_config structure must exist and be persistent before this
 421  *          function can be called. This function must also be called before
 422  *          any other NVS APIs.
 423  */
 424 extern void NVS_init(void);
 425
 426 /*!
 427  *  @brief  Get an NVS block for reading and writing.
 428  *
 429  *  @pre    NVS_init() was called.
 430  *
 431  *  @param  index         Index in the NVS_config table of the block
 432  *                        to manage.
 433  *
 434  *  @param  params        Pointer to a parameter block.  If NULL, default
 435  *                        parameter values will be used.
 436  */
 437 extern NVS_Handle NVS_open(int index, NVS_Params *params);
 438
 439 /*!
 440  *  @brief   Read data from an NVS block.
 441  *
 442  *  @param   handle     A handle returned from NVS_open()
 443  *
 444  *  @param   offset     The byte offset into the NVS block to start
 445  *                      reading from.
 446  *
 447  *  @param   buffer     A buffer to copy the data to.
 448  *
 449  *  @param   bufferSize The size of the buffer (number of bytes to read).
 450  *
 451  *  @return  NVS_SOK      Success.
 452  *  @return  NVS_EOFFSET  The location and size to read from does not
 453  *                        lie completely within the NVS block.
 454  *
 455  *  @remark  This call may block to ensure atomic access to the block.
 456  */
 457 extern int NVS_read(NVS_Handle handle, size_t offset, void *buffer,
 458                     size_t bufferSize);
 459
 460 /*!
 461  *  @brief   Write data to an NVS block.
 462  *
 463  *  @param   handle     A handle returned from NVS_open()
 464  *
 465  *  @param   offset     The byte offset into the NVS block to start
 466  *                      writing.  offset must be 4-byte aligned.
 467  *
 468  *  @param   buffer     A buffer conntaining data to write to
 469  *                      the NVS block.  If buffer is NULL, the block
 470  *                      will be erased.  A non-NULL buffer must be
 471  *                      aligned on a 4-byte boundary.
 472  *
 473  *  @param   bufferSize The size of the buffer (number of bytes to write).
 474  *                      bufferSize must be a multiple of 4 bytes.
 475  *
 476  *  @param   flags      Write flags (NVS_WRITE_EXCLUSIVE, NVS_WRITE_ERASE,
 477  *                      NVS_WRITE_VALIDATE).
 478  *
 479  *  @return  NVS_SOK      Success.
 480  *  @return  NVS_EOFFSET  The location and size to write to does not
 481  *                        lie completely within the NVS block.
 482  *  @return  NVS_EALIGN   The offset or bufferSize is not 4-byte aligned.
 483  *  @return  NVS_ALREADYWRITTEN
 484  *                        The region to write to (the bufferSize region
 485  *                        starting at offset into the block) has already
 486  *                        been written to since the last erase, and
 487  *                        NVS_WRITE_EXCLUSIVE is set in the flags parameter.
 488  *
 489  *  @remark  This call may block to ensure atomic access to the block.
 490  */
 491 extern int NVS_write(NVS_Handle handle, size_t offset, void *buffer,
 492                      size_t bufferSize, unsigned int flags);
 493
 494 #if defined (__cplusplus)
 495 }
 496 #endif /* defined (__cplusplus) */
 497
 498 /*@}*/
 499 #endif /* ti_drivers_NVS__include */