1 /* 2 * Copyright (c) 2017-2019, 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 NVSRAM.h 34 * 35 * @brief RAM implementation of the NVS driver 36 * 37 * This NVS driver implementation makes use of RAM instead of FLASH memory. 38 * It can be used for developing code which relies the NVS driver without 39 * wearing down FLASH memory. 40 * 41 * The NVS header file should be included in an application as follows: 42 * @code 43 * #include <ti/drivers/NVS.h> 44 * #include <ti/drivers/nvs/NVSRAM.h> 45 * @endcode 46 * 47 * ============================================================================ 48 */ 49 50 #ifndef ti_drivers_nvs_NVSRAM__include 51 #define ti_drivers_nvs_NVSRAM__include 52 53 #include <stdint.h> 54 #include <stdbool.h> 55 56 #if defined (__cplusplus) 57 extern "C" { 58 #endif 59 60 /*! 61 * @internal @brief NVS function pointer table 62 * 63 * 'NVSRAM_fxnTable' is a fully populated function pointer table 64 * that can be referenced in the NVS_config[] array entries. 65 * 66 * Users can minimize their application code size by providing their 67 * own custom NVS function pointer table that contains only those APIs 68 * used by the application. 69 * 70 * An example of a custom NVS function table is shown below: 71 * @code 72 * // 73 * // Since the application does not use the 74 * // NVS_control(), NVS_lock(), and NVS_unlock() APIs, 75 * // these APIs are removed from the function 76 * // pointer table and replaced with NULL 77 * // 78 * const NVS_FxnTable myNVS_fxnTable = { 79 * NVSRAM_close, 80 * NULL, // remove NVSRAM_control(), 81 * NVSRAM_erase, 82 * NVSRAM_getAttrs, 83 * NVSRAM_init, 84 * NULL, // remove NVSRAM_lock(), 85 * NVSRAM_open, 86 * NVSRAM_read, 87 * NULL, // remove NVSRAM_unlock(), 88 * NVSRAM_write 89 * }; 90 * @endcode 91 */ 92 extern const NVS_FxnTable NVSRAM_fxnTable; 93 94 /*! 95 * @brief NVSRAM Hardware Attributes 96 * 97 * The 'sectorSize' is the minimal amount of data to that is cleared on an 98 * erase operation. Devices which feature internal FLASH memory usually 99 * have a 4096 byte sector size (refer to device specific documentation). It 100 * is recommended that the 'sectorSize' used match the FLASH memory sector 101 * size. 102 * 103 * The 'regionBase' field must point to the base address of the region 104 * to be managed. It is also required that the region be aligned on a 105 * sectorSize boundary (example below to demonstrate how to do this). 106 * 107 * The 'regionSize' must be an integer multiple of the 'sectorSize'. 108 * 109 * Defining and reserving RAM memory regions can be done entirely within the 110 * ti_drivers_config.c file. 111 * 112 * The example below defines a char array, 'ramBuf' and uses compiler 113 * pragmas to place 'ramBuf' at an aligned address within RAM. 114 * 115 * @code 116 * #define SECTORSIZE (4096) 117 * 118 * static char ramBuf[SECTORSIZE * 4] __attribute__ ((aligned (4096))); 119 * 120 * NVSRAM_HWAttrs NVSRAMHWAttrs[1] = { 121 * { 122 * .regionBase = (void *) ramBuf, 123 * .regionSize = SECTORSIZE * 4, 124 * .sectorSize = SECTORSIZE 125 * } 126 * }; 127 * 128 * 129 * @endcode 130 */ 131 typedef struct 132 { 133 void *regionBase; /*!< Base address of RAM region */ 134 size_t regionSize; /*!< The size of the region in bytes */ 135 size_t sectorSize; /*!< Sector size in bytes */ 136 } NVSRAM_HWAttrs; 137 138 /* 139 * @brief NVSRAM Object 140 * 141 * The application must not access any member variables of this structure! 142 */ 143 typedef struct 144 { 145 size_t sectorBaseMask; 146 bool isOpen; 147 } NVSRAM_Object; 148 149 /* 150 * @cond NODOC 151 * NVSRAM driver public APIs 152 */ 153 154 extern void NVSRAM_close(NVS_Handle handle); 155 extern int_fast16_t NVSRAM_control(NVS_Handle handle, uint_fast16_t cmd, 156 uintptr_t arg); 157 extern int_fast16_t NVSRAM_erase(NVS_Handle handle, size_t offset, 158 size_t size); 159 extern void NVSRAM_getAttrs(NVS_Handle handle, NVS_Attrs *attrs); 160 extern void NVSRAM_init(); 161 extern int_fast16_t NVSRAM_lock(NVS_Handle handle, uint32_t timeout); 162 extern NVS_Handle NVSRAM_open(uint_least8_t index, NVS_Params *params); 163 extern int_fast16_t NVSRAM_read(NVS_Handle handle, size_t offset, 164 void *buffer, size_t bufferSize); 165 extern void NVSRAM_unlock(NVS_Handle handle); 166 extern int_fast16_t NVSRAM_write(NVS_Handle handle, size_t offset, 167 void *buffer, size_t bufferSize, uint_fast16_t flags); 168 169 /*! @endcond */ 170 171 #if defined (__cplusplus) 172 } 173 #endif /* defined (__cplusplus) */ 174 175 /*@}*/ 176 #endif /* ti_drivers_nvs_NVSRAM__include */ 177
