1 /* 2 * fs.h - CC31xx/CC32xx Host Driver Implementation 3 * 4 * Copyright (C) 2014 Texas Instruments Incorporated - http://www.ti.com/ 5 * 6 * 7 * Redistribution and use in source and binary forms, with or without 8 * modification, are permitted provided that the following conditions 9 * are met: 10 * 11 * Redistributions of source code must retain the above copyright 12 * notice, this list of conditions and the following disclaimer. 13 * 14 * Redistributions in binary form must reproduce the above copyright 15 * notice, this list of conditions and the following disclaimer in the 16 * documentation and/or other materials provided with the 17 * distribution. 18 * 19 * Neither the name of Texas Instruments Incorporated nor the names of 20 * its contributors may be used to endorse or promote products derived 21 * from this software without specific prior written permission. 22 * 23 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 24 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 25 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 26 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 27 * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 28 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 29 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 30 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 31 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 32 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 33 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 34 * 35 */ 36 37 /*****************************************************************************/ 38 /* Include files */ 39 /*****************************************************************************/ 40 41 #include "simplelink.h" 42 43 #ifndef __FS_H__ 44 #define __FS_H__ 45 46 47 48 #ifdef __cplusplus 49 extern "C" { 50 #endif 51 52 /*! 53 54 \addtogroup FileSystem 55 @{ 56 57 */ 58 59 /*****************************************************************************/ 60 /* Macro declarations */ 61 /*****************************************************************************/ 62 63 /* FS error codes */ 64 #define SL_FS_OK (0) 65 #define SL_FS_ERR_EMPTY_SFLASH (-67) 66 #define SL_FS_ERR_FILE_IS_NOT_SECURE_AND_SIGN (-66) 67 #define SL_FS_ERASING_FLASH (-65) 68 #define SL_FS_FILE_HAS_NOT_BEEN_CLOSE_CORRECTLY (-64) 69 #define SL_FS_WRONG_SIGNATURE (-63) 70 #define SL_FS_WRONG_SIGNATURE_OR_CERTIFIC_NAME_LENGTH (-62) 71 #define SL_FS_NOT_16_ALIGNED (-61) 72 #define SL_FS_CERT_CHAIN_ERROR (-60) 73 #define SL_FS_FILE_NAME_EXIST (-59) 74 #define SL_FS_SECURITY_BUF_ALREADY_ALLOC (-58) 75 #define SL_FS_SECURE_FILE_MUST_BE_COMMIT (-57) 76 #define SL_FS_ERR_INCORRECT_OFFSET_ALIGNMENT (-56) 77 #define SL_FS_ERR_FAILED_READ_NVMEM_HEADER (-55) 78 #define SL_FS_WRONG_FILE_NAME (-54) 79 #define SL_FS_FILE_SYSTEM_IS_LOCKED (-53) 80 #define SL_FS_SECURITY_ALLERT (-52) 81 #define SL_FS_FILE_UNVALID_FILE_SIZE (-51) 82 #define SL_FS_ERR_TOKEN_IS_NOT_VALID (-50) 83 #define SL_FS_NO_DEVICE_IS_LOADED (-49) 84 #define SL_FS_DATA_ADDRESS_SHOUD_BE_IN_DATA_RAM (-48) 85 #define SL_FS_DATA_IS_NOT_ALIGNED (-47) 86 #define SL_FS_ERR_OVERLAP_DETECTION_THRESHHOLD (-46) 87 #define SL_FS_FILE_HAS_RESERVED_NV_INDEX (-45) 88 #define SL_FS_ERR_MAX_FS_FILES_IS_LARGER (-44) 89 #define SL_FS_ERR_MAX_FS_FILES_IS_SMALLER (-43) 90 #define SL_FS_FILE_MAX_SIZE_EXCEEDED (-42) 91 #define SL_FS_INVALID_BUFFER_FOR_READ (-41) 92 #define SL_FS_INVALID_BUFFER_FOR_WRITE (-40) 93 #define SL_FS_ERR_FILE_IMAGE_IS_CORRUPTED (-39) 94 #define SL_FS_ERR_SIZE_OF_FILE_EXT_EXCEEDED (-38) 95 #define SL_FS_WARNING_FILE_NAME_NOT_KEPT (-37) 96 #define SL_FS_ERR_DEVICE_IS_NOT_FORMATTED (-36) 97 #define SL_FS_ERR_FAILED_WRITE_NVMEM_HEADER (-35) 98 #define SL_FS_ERR_NO_AVAILABLE_NV_INDEX (-34) 99 #define SL_FS_ERR_FAILED_TO_ALLOCATE_MEM (-33) 100 #define SL_FS_ERR_FAILED_TO_READ_INTEGRITY_HEADER_2 (-32) 101 #define SL_FS_ERR_FAILED_TO_READ_INTEGRITY_HEADER_1 (-31) 102 #define SL_FS_ERR_NO_AVAILABLE_BLOCKS (-30) 103 #define SL_FS_ERR_FILE_MAX_SIZE_BIGGER_THAN_EXISTING_FILE (-29) 104 #define SL_FS_ERR_FILE_EXISTS_ON_DIFFERENT_DEVICE_ID (-28) 105 #define SL_FS_ERR_INVALID_ACCESS_TYPE (-27) 106 #define SL_FS_ERR_FILE_ALREADY_EXISTS (-26) 107 #define SL_FS_ERR_PROGRAM (-25) 108 #define SL_FS_ERR_NO_ENTRIES_AVAILABLE (-24) 109 #define SL_FS_ERR_FILE_ACCESS_IS_DIFFERENT (-23) 110 #define SL_FS_ERR_BAD_FILE_MODE (-22) 111 #define SL_FS_ERR_FAILED_READ_NVFILE (-21) 112 #define SL_FS_ERR_FAILED_INIT_STORAGE (-20) 113 #define SL_FS_ERR_CONTINUE_WRITE_MUST_BE_MOD_4 (-19) 114 #define SL_FS_ERR_FAILED_LOAD_FILE (-18) 115 #define SL_FS_ERR_INVALID_HANDLE (-17) 116 #define SL_FS_ERR_FAILED_TO_WRITE (-16) 117 #define SL_FS_ERR_OFFSET_OUT_OF_RANGE (-15) 118 #define SL_FS_ERR_ALLOC (-14) 119 #define SL_FS_ERR_READ_DATA_LENGTH (-13) 120 #define SL_FS_ERR_INVALID_FILE_ID (-12) 121 #define SL_FS_ERR_FILE_NOT_EXISTS (-11) 122 #define SL_FS_ERR_EMPTY_ERROR (-10) 123 #define SL_FS_ERR_INVALID_ARGS (-9) 124 #define SL_FS_ERR_FAILED_TO_CREATE_FILE (-8) 125 #define SL_FS_ERR_FS_ALREADY_LOADED (-7) 126 #define SL_FS_ERR_UNKNOWN (-6) 127 #define SL_FS_ERR_FAILED_TO_CREATE_LOCK_OBJ (-5) 128 #define SL_FS_ERR_DEVICE_NOT_LOADED (-4) 129 #define SL_FS_ERR_INVALID_MAGIC_NUM (-3) 130 #define SL_FS_ERR_FAILED_TO_READ (-2) 131 #define SL_FS_ERR_NOT_SUPPORTED (-1) 132 /* end of error codes */ 133 134 #define _FS_MODE_ACCESS_RESERVED_OFFSET (24) 135 #define _FS_MODE_ACCESS_RESERVED_MASK (0xFF) 136 #define _FS_MODE_ACCESS_FLAGS_OFFSET (16) 137 #define _FS_MODE_ACCESS_FLAGS_MASK (0xFF) 138 #define _FS_MODE_ACCESS_OFFSET (12) 139 #define _FS_MODE_ACCESS_MASK (0xF) 140 #define _FS_MODE_OPEN_SIZE_GRAN_OFFSET (8) 141 #define _FS_MODE_OPEN_SIZE_GRAN_MASK (0xF) 142 #define _FS_MODE_OPEN_SIZE_OFFSET (0) 143 #define _FS_MODE_OPEN_SIZE_MASK (0xFF) 144 #define MAX_MODE_SIZE (0xFF) 145 #define _FS_MODE(Access, SizeGran, Size,Flags) (_u32)(((_u32)((Access) & _FS_MODE_ACCESS_MASK)<<_FS_MODE_ACCESS_OFFSET) | \ 146 ((_u32)((SizeGran) & _FS_MODE_OPEN_SIZE_GRAN_MASK)<<_FS_MODE_OPEN_SIZE_GRAN_OFFSET) | \ 147 ((_u32)((Size) & _FS_MODE_OPEN_SIZE_MASK)<<_FS_MODE_OPEN_SIZE_OFFSET) | \ 148 ((_u32)((Flags) & _FS_MODE_ACCESS_FLAGS_MASK)<<_FS_MODE_ACCESS_FLAGS_OFFSET)) 149 150 151 /* sl_FsOpen options */ 152 /* Open for Read */ 153 #define FS_MODE_OPEN_READ _FS_MODE(_FS_MODE_OPEN_READ,0,0,0) 154 /* Open for Write (in case file exist) */ 155 #define FS_MODE_OPEN_WRITE _FS_MODE(_FS_MODE_OPEN_WRITE,0,0,0) 156 /* Open for Creating a new file */ 157 #define FS_MODE_OPEN_CREATE(maxSizeInBytes,accessModeFlags) _sl_GetCreateFsMode(maxSizeInBytes,accessModeFlags) 158 159 /*****************************************************************************/ 160 /* Structure/Enum declarations */ 161 /*****************************************************************************/ 162 typedef struct 163 { 164 _u16 flags; 165 _u32 FileLen; 166 _u32 AllocatedLen; 167 _u32 Token[4]; 168 }SlFsFileInfo_t; 169 170 typedef enum 171 { 172 _FS_MODE_OPEN_READ = 0, 173 _FS_MODE_OPEN_WRITE, 174 _FS_MODE_OPEN_CREATE, 175 _FS_MODE_OPEN_WRITE_CREATE_IF_NOT_EXIST 176 }SlFsFileOpenAccessType_e; 177 178 typedef enum 179 { 180 _FS_FILE_OPEN_FLAG_COMMIT = 0x1, /* MIRROR - for fail safe */ 181 _FS_FILE_OPEN_FLAG_SECURE = 0x2, /* SECURE */ 182 _FS_FILE_OPEN_FLAG_NO_SIGNATURE_TEST = 0x4, /* Relevant to secure file only */ 183 _FS_FILE_OPEN_FLAG_STATIC = 0x8, /* Relevant to secure file only */ 184 _FS_FILE_OPEN_FLAG_VENDOR = 0x10, /* Relevant to secure file only */ 185 _FS_FILE_PUBLIC_WRITE= 0x20, /* Relevant to secure file only, the file can be opened for write without Token */ 186 _FS_FILE_PUBLIC_READ = 0x40 /* Relevant to secure file only, the file can be opened for read without Token */ 187 }SlFileOpenFlags_e; 188 189 typedef enum 190 { 191 _FS_MODE_SIZE_GRAN_256B = 0, /* MAX_SIZE = 64K */ 192 _FS_MODE_SIZE_GRAN_1KB, /* MAX_SIZE = 256K */ 193 _FS_MODE_SIZE_GRAN_4KB, /* MAX_SZIE = 1M */ 194 _FS_MODE_SIZE_GRAN_16KB, /* MAX_SIZE = 4M */ 195 _FS_MODE_SIZE_GRAN_64KB, /* MAX_SIZE = 16M */ 196 _FS_MAX_MODE_SIZE_GRAN 197 }_SlFsFileOpenMaxSizeGran_e; 198 199 /*****************************************************************************/ 200 /* Internal Function prototypes */ 201 /*****************************************************************************/ 202 _u32 _sl_GetCreateFsMode(_u32 maxSizeInBytes,_u32 accessFlags); 203 204 /*****************************************************************************/ 205 /* Function prototypes */ 206 /*****************************************************************************/ 207 208 /*! 209 \brief open file for read or write from/to storage device 210 211 \param[in] pFileName File Name buffer pointer 212 \param[in] AccessModeAndMaxSize Options: As described below 213 \param[in] pToken Reserved for future use. Use NULL for this field 214 \param[out] pFileHandle Pointing on the file and used for read and write commands to the file 215 216 AccessModeAndMaxSize possible input \n 217 FS_MODE_OPEN_READ - Read a file \n 218 FS_MODE_OPEN_WRITE - Open for write for an existing file \n 219 FS_MODE_OPEN_CREATE(maxSizeInBytes,accessModeFlags) - Open for creating a new file. Max file size is defined in bytes. \n 220 For optimal FS size, use max size in 4K-512 bytes steps (e.g. 3584,7680,117760) \n 221 Several access modes bits can be combined together from SlFileOpenFlags_e enum 222 223 \return On success, zero is returned. On error, an error code is returned 224 225 \sa sl_FsRead sl_FsWrite sl_FsClose 226 \note belongs to \ref basic_api 227 \warning 228 \par Example: 229 \code 230 char* DeviceFileName = "MyFile.txt"; 231 unsigned long MaxSize = 63 * 1024; //62.5K is max file size 232 long DeviceFileHandle = -1; 233 long RetVal; //negative retval is an error 234 unsigned long Offset = 0; 235 unsigned char InputBuffer[100]; 236 237 // Create a file and write data. The file in this example is secured, without signature and with a fail safe commit 238 RetVal = sl_FsOpen((unsigned char *)DeviceFileName, 239 FS_MODE_OPEN_CREATE(MaxSize , _FS_FILE_OPEN_FLAG_NO_SIGNATURE_TEST | _FS_FILE_OPEN_FLAG_COMMIT ), 240 NULL, &DeviceFileHandle); 241 242 Offset = 0; 243 //Preferred in secure file that the Offset and the length will be aligned to 16 bytes. 244 RetVal = sl_FsWrite( DeviceFileHandle, Offset, (unsigned char *)"HelloWorld", strlen("HelloWorld")); 245 246 RetVal = sl_FsClose(DeviceFileHandle, NULL, NULL , 0); 247 248 // open the same file for read, using the Token we got from the creation procedure above 249 RetVal = sl_FsOpen((unsigned char *)DeviceFileName, 250 FS_MODE_OPEN_READ, 251 NULL, &DeviceFileHandle); 252 253 Offset = 0; 254 RetVal = sl_FsRead( DeviceFileHandle, Offset, (unsigned char *)InputBuffer, strlen("HelloWorld")); 255 256 RetVal = sl_FsClose(DeviceFileHandle, NULL, NULL , 0); 257 258 \endcode 259 */ 260 #if _SL_INCLUDE_FUNC(sl_FsOpen) 261 _i32 sl_FsOpen(const _u8 *pFileName,const _u32 AccessModeAndMaxSize,_u32 *pToken,_i32 *pFileHandle); 262 #endif 263 264 /*! 265 \brief close file in storage device 266 267 \param[in] FileHdl Pointer to the file (assigned from sl_FsOpen) 268 \param[in] pCeritificateFileName Reserved for future use. Use NULL. 269 \param[in] pSignature Reserved for future use. Use NULL. 270 \param[in] SignatureLen Reserved for future use. Use 0. 271 272 273 \return On success, zero is returned. On error, an error code is returned 274 275 \sa sl_FsRead sl_FsWrite sl_FsOpen 276 \note Call the fs_Close with signature = 'A' signature len = 1 for activating an abort action 277 \warning 278 \par Example: 279 \code 280 sl_FsClose(FileHandle,0,0,0); 281 \endcode 282 */ 283 #if _SL_INCLUDE_FUNC(sl_FsClose) 284 _i16 sl_FsClose(const _i32 FileHdl,const _u8* pCeritificateFileName,const _u8* pSignature,const _u32 SignatureLen); 285 #endif 286 287 /*! 288 \brief Read block of data from a file in storage device 289 290 \param[in] FileHdl Pointer to the file (assigned from sl_FsOpen) 291 \param[in] Offset Offset to specific read block 292 \param[out] pData Pointer for the received data 293 \param[in] Len Length of the received data 294 295 \return On success, returns the number of read bytes. On error, negative number is returned 296 297 \sa sl_FsClose sl_FsWrite sl_FsOpen 298 \note belongs to \ref basic_api 299 \warning 300 \par Example: 301 \code 302 Status = sl_FsRead(FileHandle, 0, &readBuff[0], readSize); 303 \endcode 304 */ 305 #if _SL_INCLUDE_FUNC(sl_FsRead) 306 _i32 sl_FsRead(const _i32 FileHdl,_u32 Offset ,_u8* pData,_u32 Len); 307 #endif 308 309 /*! 310 \brief write block of data to a file in storage device 311 312 \param[in] FileHdl Pointer to the file (assigned from sl_FsOpen) 313 \param[in] Offset Offset to specific block to be written 314 \param[in] pData Pointer the transmitted data to the storage device 315 \param[in] Len Length of the transmitted data 316 317 \return On success, returns the number of written bytes. On error, an error code is returned 318 319 \sa 320 \note belongs to \ref basic_api 321 \warning 322 \par Example: 323 \code 324 Status = sl_FsWrite(FileHandle, 0, &buff[0], readSize); 325 \endcode 326 */ 327 #if _SL_INCLUDE_FUNC(sl_FsWrite) 328 _i32 sl_FsWrite(const _i32 FileHdl,_u32 Offset,_u8* pData,_u32 Len); 329 #endif 330 331 /*! 332 \brief get info on a file 333 334 \param[in] pFileName File name 335 \param[in] Token Reserved for future use. Use 0 336 \param[out] pFsFileInfo Returns the File's Information: flags,file size, allocated size and Tokens 337 338 \return On success, zero is returned. On error, an error code is returned 339 340 \sa sl_FsOpen 341 \note belongs to \ref basic_api 342 \warning 343 \par Example: 344 \code 345 Status = sl_FsGetInfo("FileName.html",0,&FsFileInfo); 346 \endcode 347 */ 348 #if _SL_INCLUDE_FUNC(sl_FsGetInfo) 349 _i16 sl_FsGetInfo(const _u8 *pFileName,const _u32 Token,SlFsFileInfo_t* pFsFileInfo); 350 #endif 351 352 /*! 353 \brief Delete specific file from a storage or all files from a storage (format) 354 355 \param[in] pFileName File Name 356 \param[in] Token Reserved for future use. Use 0 357 \return On success, zero is returned. On error, an error code is returned 358 359 \sa 360 \note belongs to \ref basic_api 361 \warning 362 \par Example: 363 \code 364 Status = sl_FsDel("FileName.html",0); 365 \endcode 366 */ 367 #if _SL_INCLUDE_FUNC(sl_FsDel) 368 _i16 sl_FsDel(const _u8 *pFileName,const _u32 Token); 369 #endif 370 /*! 371 372 Close the Doxygen group. 373 @} 374 375 */ 376 377 #ifdef __cplusplus 378 } 379 #endif /* __cplusplus */ 380 381 #endif /* __FS_H__ */ 382 383