fs.h

00001 /*
00002  * fs.h - CC31xx/CC32xx Host Driver Implementation
00003  *
00004  * Copyright (C) 2015 Texas Instruments Incorporated - http://www.ti.com/ 
00005  * 
00006  * 
00007  *  Redistribution and use in source and binary forms, with or without 
00008  *  modification, are permitted provided that the following conditions 
00009  *  are met:
00010  *
00011  *    Redistributions of source code must retain the above copyright 
00012  *    notice, this list of conditions and the following disclaimer.
00013  *
00014  *    Redistributions in binary form must reproduce the above copyright
00015  *    notice, this list of conditions and the following disclaimer in the 
00016  *    documentation and/or other materials provided with the   
00017  *    distribution.
00018  *
00019  *    Neither the name of Texas Instruments Incorporated nor the names of
00020  *    its contributors may be used to endorse or promote products derived
00021  *    from this software without specific prior written permission.
00022  *
00023  *  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 
00024  *  "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 
00025  *  LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
00026  *  A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 
00027  *  OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 
00028  *  SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 
00029  *  LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
00030  *  DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
00031  *  THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 
00032  *  (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 
00033  *  OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
00034  *
00035 */
00036 
00037 /*****************************************************************************/
00038 /* Include files                                                             */
00039 /*****************************************************************************/
00040 
00041 #include "simplelink.h"
00042     
00043 #ifndef __FS_H__
00044 #define __FS_H__
00045 
00046 
00047 
00048 #ifdef __cplusplus
00049 extern "C" {
00050 #endif
00051 
00052 /*!
00053 
00054     \addtogroup FileSystem
00055     @{
00056 
00057 */
00058 
00059 /*****************************************************************************/
00060 /* Macro declarations                                                        */
00061 /*****************************************************************************/
00062 
00063 /* FS error codes */
00064 #define SL_FS_OK                                              (0)
00065 #define SL_FS_ERR_EMPTY_SFLASH                                (-67)
00066 #define SL_FS_ERR_FILE_IS_NOT_SECURE_AND_SIGN                 (-66)
00067 #define SL_FS_ERASING_FLASH                                   (-65)
00068 #define SL_FS_FILE_HAS_NOT_BEEN_CLOSE_CORRECTLY               (-64)
00069 #define SL_FS_WRONG_SIGNATURE                                 (-63)
00070 #define SL_FS_WRONG_SIGNATURE_OR_CERTIFIC_NAME_LENGTH         (-62)
00071 #define SL_FS_NOT_16_ALIGNED                                  (-61)
00072 #define SL_FS_CERT_CHAIN_ERROR                                (-60)
00073 #define SL_FS_FILE_NAME_EXIST                                 (-59)
00074 #define SL_FS_SECURITY_BUF_ALREADY_ALLOC                      (-58)
00075 #define SL_FS_SECURE_FILE_MUST_BE_COMMIT                      (-57)
00076 #define SL_FS_ERR_INCORRECT_OFFSET_ALIGNMENT                  (-56)
00077 #define SL_FS_ERR_FAILED_READ_NVMEM_HEADER                    (-55)
00078 #define SL_FS_WRONG_FILE_NAME                                 (-54)
00079 #define SL_FS_FILE_SYSTEM_IS_LOCKED                           (-53)
00080 #define SL_FS_SECURITY_ALLERT                                 (-52)
00081 #define SL_FS_FILE_UNVALID_FILE_SIZE                          (-51)
00082 #define SL_FS_ERR_TOKEN_IS_NOT_VALID                          (-50)
00083 #define SL_FS_NO_DEVICE_IS_LOADED                             (-49)
00084 #define SL_FS_DATA_ADDRESS_SHOUD_BE_IN_DATA_RAM               (-48)
00085 #define SL_FS_DATA_IS_NOT_ALIGNED                             (-47)
00086 #define SL_FS_ERR_OVERLAP_DETECTION_THRESHHOLD                (-46)
00087 #define SL_FS_FILE_HAS_RESERVED_NV_INDEX                      (-45)
00088 #define SL_FS_ERR_MAX_FS_FILES_IS_LARGER                      (-44)
00089 #define SL_FS_ERR_MAX_FS_FILES_IS_SMALLER                     (-43)
00090 #define SL_FS_FILE_MAX_SIZE_EXCEEDED                          (-42)
00091 #define SL_FS_INVALID_BUFFER_FOR_READ                         (-41)
00092 #define SL_FS_INVALID_BUFFER_FOR_WRITE                        (-40)
00093 #define SL_FS_ERR_FILE_IMAGE_IS_CORRUPTED                     (-39)
00094 #define SL_FS_ERR_SIZE_OF_FILE_EXT_EXCEEDED                   (-38)
00095 #define SL_FS_WARNING_FILE_NAME_NOT_KEPT                      (-37)
00096 #define SL_FS_ERR_DEVICE_IS_NOT_FORMATTED                     (-36)
00097 #define SL_FS_ERR_FAILED_WRITE_NVMEM_HEADER                   (-35)
00098 #define SL_FS_ERR_NO_AVAILABLE_NV_INDEX                       (-34)
00099 #define SL_FS_ERR_FAILED_TO_ALLOCATE_MEM                      (-33)
00100 #define SL_FS_ERR_FAILED_TO_READ_INTEGRITY_HEADER_2           (-32)
00101 #define SL_FS_ERR_FAILED_TO_READ_INTEGRITY_HEADER_1           (-31)
00102 #define SL_FS_ERR_NO_AVAILABLE_BLOCKS                         (-30)
00103 #define SL_FS_ERR_FILE_MAX_SIZE_BIGGER_THAN_EXISTING_FILE     (-29)
00104 #define SL_FS_ERR_FILE_EXISTS_ON_DIFFERENT_DEVICE_ID          (-28)
00105 #define SL_FS_ERR_INVALID_ACCESS_TYPE                         (-27)
00106 #define SL_FS_ERR_FILE_ALREADY_EXISTS                         (-26)
00107 #define SL_FS_ERR_PROGRAM                                     (-25)
00108 #define SL_FS_ERR_NO_ENTRIES_AVAILABLE                        (-24)
00109 #define SL_FS_ERR_FILE_ACCESS_IS_DIFFERENT                    (-23)
00110 #define SL_FS_ERR_BAD_FILE_MODE                               (-22)
00111 #define SL_FS_ERR_FAILED_READ_NVFILE                          (-21)
00112 #define SL_FS_ERR_FAILED_INIT_STORAGE                         (-20)
00113 #define SL_FS_ERR_CONTINUE_WRITE_MUST_BE_MOD_4                (-19)
00114 #define SL_FS_ERR_FAILED_LOAD_FILE                            (-18)
00115 #define SL_FS_ERR_INVALID_HANDLE                              (-17)
00116 #define SL_FS_ERR_FAILED_TO_WRITE                             (-16)
00117 #define SL_FS_ERR_OFFSET_OUT_OF_RANGE                         (-15)
00118 #define SL_FS_ERR_ALLOC                                       (-14)
00119 #define SL_FS_ERR_READ_DATA_LENGTH                            (-13)
00120 #define SL_FS_ERR_INVALID_FILE_ID                             (-12)
00121 #define SL_FS_ERR_FILE_NOT_EXISTS                             (-11)
00122 #define SL_FS_ERR_EMPTY_ERROR                                 (-10)
00123 #define SL_FS_ERR_INVALID_ARGS                                (-9)
00124 #define SL_FS_ERR_FAILED_TO_CREATE_FILE                       (-8)
00125 #define SL_FS_ERR_FS_ALREADY_LOADED                           (-7)
00126 #define SL_FS_ERR_UNKNOWN                                     (-6)
00127 #define SL_FS_ERR_FAILED_TO_CREATE_LOCK_OBJ                   (-5)
00128 #define SL_FS_ERR_DEVICE_NOT_LOADED                           (-4)
00129 #define SL_FS_ERR_INVALID_MAGIC_NUM                           (-3)
00130 #define SL_FS_ERR_FAILED_TO_READ                              (-2)
00131 #define SL_FS_ERR_NOT_SUPPORTED                               (-1)
00132 /* end of error codes */
00133 
00134 #define _FS_MODE_ACCESS_RESERVED_OFFSET                       (24)
00135 #define _FS_MODE_ACCESS_RESERVED_MASK                         (0xFF)
00136 #define _FS_MODE_ACCESS_FLAGS_OFFSET                          (16)
00137 #define _FS_MODE_ACCESS_FLAGS_MASK                            (0xFF)
00138 #define _FS_MODE_ACCESS_OFFSET                                (12)
00139 #define _FS_MODE_ACCESS_MASK                                  (0xF)
00140 #define _FS_MODE_OPEN_SIZE_GRAN_OFFSET                        (8)
00141 #define _FS_MODE_OPEN_SIZE_GRAN_MASK                          (0xF)
00142 #define _FS_MODE_OPEN_SIZE_OFFSET                             (0)
00143 #define _FS_MODE_OPEN_SIZE_MASK                               (0xFF)
00144 #define MAX_MODE_SIZE                                         (0xFF)
00145 #define _FS_MODE(Access, SizeGran, Size,Flags)        (_u32)(((_u32)((Access) & _FS_MODE_ACCESS_MASK)<<_FS_MODE_ACCESS_OFFSET) |  \
00146                                                             ((_u32)((SizeGran) & _FS_MODE_OPEN_SIZE_GRAN_MASK)<<_FS_MODE_OPEN_SIZE_GRAN_OFFSET) | \
00147                                                             ((_u32)((Size) & _FS_MODE_OPEN_SIZE_MASK)<<_FS_MODE_OPEN_SIZE_OFFSET) | \
00148                                                             ((_u32)((Flags) & _FS_MODE_ACCESS_FLAGS_MASK)<<_FS_MODE_ACCESS_FLAGS_OFFSET))
00149 
00150 
00151 /*  sl_FsOpen options */
00152 /*  Open for Read */
00153 #define FS_MODE_OPEN_READ                                     _FS_MODE(_FS_MODE_OPEN_READ,0,0,0)
00154 /*  Open for Write (in case file exist) */
00155 #define FS_MODE_OPEN_WRITE                                    _FS_MODE(_FS_MODE_OPEN_WRITE,0,0,0)
00156 /* Open for Creating a new file */
00157 #define FS_MODE_OPEN_CREATE(maxSizeInBytes,accessModeFlags)   _sl_GetCreateFsMode(maxSizeInBytes,accessModeFlags)        
00158 
00159 /*****************************************************************************/
00160 /* Structure/Enum declarations                                               */
00161 /*****************************************************************************/
00162 typedef struct
00163 {
00164     _u16 flags;
00165     _u32  FileLen;
00166     _u32  AllocatedLen;
00167     _u32  Token[4];
00168 }SlFsFileInfo_t;
00169 
00170 typedef enum
00171 {
00172        _FS_MODE_OPEN_READ            = 0,
00173        _FS_MODE_OPEN_WRITE,
00174        _FS_MODE_OPEN_CREATE,
00175        _FS_MODE_OPEN_WRITE_CREATE_IF_NOT_EXIST
00176 }SlFsFileOpenAccessType_e;
00177 
00178 typedef enum
00179 {
00180    _FS_FILE_OPEN_FLAG_COMMIT  =  0x1,           /* MIRROR - for fail safe */
00181    _FS_FILE_OPEN_FLAG_SECURE  =  0x2,           /* SECURE */
00182    _FS_FILE_OPEN_FLAG_NO_SIGNATURE_TEST = 0x4,  /* Relevant to secure file only  */
00183    _FS_FILE_OPEN_FLAG_STATIC  =           0x8,  /*  Relevant to secure file only */
00184    _FS_FILE_OPEN_FLAG_VENDOR  =           0x10, /*  Relevant to secure file only */
00185    _FS_FILE_PUBLIC_WRITE=                 0x20, /* Relevant to secure file only, the file can be opened for write without Token */
00186    _FS_FILE_PUBLIC_READ =                 0x40  /* Relevant to secure file only, the file can be opened for read without Token  */
00187 }SlFileOpenFlags_e;
00188 
00189 typedef enum
00190 {
00191        _FS_MODE_SIZE_GRAN_256B    = 0,   /*  MAX_SIZE = 64K  */
00192        _FS_MODE_SIZE_GRAN_1KB,           /*  MAX_SIZE = 256K */
00193        _FS_MODE_SIZE_GRAN_4KB,           /*  MAX_SZIE = 1M   */
00194        _FS_MODE_SIZE_GRAN_16KB,          /*  MAX_SIZE = 4M   */
00195        _FS_MODE_SIZE_GRAN_64KB,          /*  MAX_SIZE = 16M  */
00196        _FS_MAX_MODE_SIZE_GRAN
00197 }_SlFsFileOpenMaxSizeGran_e;
00198 
00199 /*****************************************************************************/
00200 /* Internal Function prototypes                                              */
00201 /*****************************************************************************/
00202 _u32 _sl_GetCreateFsMode(_u32 maxSizeInBytes,_u32 accessFlags);
00203 
00204 /*****************************************************************************/
00205 /* Function prototypes                                                       */
00206 /*****************************************************************************/
00207 
00208 /*!
00209     \brief open file for read or write from/to storage device
00210     
00211     \param[in]      pFileName                  File Name buffer pointer  
00212     \param[in]      AccessModeAndMaxSize       Options: As described below
00213     \param[in]      pToken                     Reserved for future use. Use NULL for this field
00214     \param[out]     pFileHandle      Pointing on the file and used for read and write commands to the file     
00215      
00216      AccessModeAndMaxSize possible input                                                                        \n
00217      FS_MODE_OPEN_READ                                        - Read a file                                                                  \n
00218      FS_MODE_OPEN_WRITE                                       - Open for write for an existing file                                          \n
00219      FS_MODE_OPEN_CREATE(maxSizeInBytes,accessModeFlags)      - Open for creating a new file. Max file size is defined in bytes.             \n
00220                                                                 For optimal FS size, use max size in 4K-512 bytes steps (e.g. 3584,7680,117760)  \n
00221                                                                 Several access modes bits can be combined together from SlFileOpenFlags_e enum
00222 
00223     \return         On success, zero is returned. On error, an error code is returned    
00224     
00225     \sa             sl_FsRead sl_FsWrite sl_FsClose       
00226     \note           belongs to \ref basic_api       
00227     \warning        
00228     \par            Example:
00229     \code
00230        char*           DeviceFileName = "MyFile.txt";
00231        unsigned long   MaxSize = 63 * 1024; //62.5K is max file size
00232        long            DeviceFileHandle = -1;
00233        long            RetVal;        //negative retval is an error
00234        unsigned long   Offset = 0;
00235        unsigned char   InputBuffer[100];
00236 
00237        // Create a file and write data. The file in this example is secured, without signature and with a fail safe commit
00238        RetVal = sl_FsOpen((unsigned char *)DeviceFileName,
00239                                         FS_MODE_OPEN_CREATE(MaxSize , _FS_FILE_OPEN_FLAG_NO_SIGNATURE_TEST | _FS_FILE_OPEN_FLAG_COMMIT ),
00240                                         NULL, &DeviceFileHandle);
00241 
00242        Offset = 0;
00243        //Preferred in secure file that the Offset and the length will be aligned to 16 bytes.
00244        RetVal = sl_FsWrite( DeviceFileHandle, Offset, (unsigned char *)"HelloWorld", strlen("HelloWorld"));
00245 
00246        RetVal = sl_FsClose(DeviceFileHandle, NULL, NULL , 0);
00247 
00248        // open the same file for read, using the Token we got from the creation procedure above
00249        RetVal = sl_FsOpen((unsigned char *)DeviceFileName,
00250                                         FS_MODE_OPEN_READ,
00251                                         NULL, &DeviceFileHandle);
00252 
00253        Offset = 0;
00254        RetVal = sl_FsRead( DeviceFileHandle, Offset, (unsigned char *)InputBuffer, strlen("HelloWorld"));
00255 
00256        RetVal = sl_FsClose(DeviceFileHandle, NULL, NULL , 0);
00257 
00258      \endcode
00259 */
00260 #if _SL_INCLUDE_FUNC(sl_FsOpen)
00261 _i32 sl_FsOpen(const _u8 *pFileName,const _u32 AccessModeAndMaxSize,_u32 *pToken,_i32 *pFileHandle);
00262 #endif
00263 
00264 /*!
00265     \brief close file in storage device
00266     
00267     \param[in]      FileHdl                 Pointer to the file (assigned from sl_FsOpen) 
00268     \param[in]      pCeritificateFileName   Reserved for future use. Use NULL.
00269     \param[in]      pSignature              Reserved for future use. Use NULL.
00270     \param[in]      SignatureLen            Reserved for future use. Use 0.
00271                     
00272 
00273     \return         On success, zero is returned.  On error, an error code is returned   
00274     
00275     \sa             sl_FsRead sl_FsWrite sl_FsOpen        
00276     \note           Call the fs_Close  with signature = 'A' signature len = 1 for activating an abort action
00277     \warning
00278     \par            Example:
00279     \code            
00280     sl_FsClose(FileHandle,0,0,0);
00281     \endcode
00282 */
00283 #if _SL_INCLUDE_FUNC(sl_FsClose)
00284 _i16 sl_FsClose(const _i32 FileHdl,const _u8* pCeritificateFileName,const _u8* pSignature,const _u32 SignatureLen);
00285 #endif
00286 
00287 /*!
00288     \brief Read block of data from a file in storage device
00289     
00290     \param[in]      FileHdl Pointer to the file (assigned from sl_FsOpen)    
00291     \param[in]      Offset  Offset to specific read block
00292     \param[out]     pData   Pointer for the received data
00293     \param[in]      Len     Length of the received data
00294      
00295     \return         On success, returns the number of read bytes. On error, negative number is returned    
00296     
00297     \sa             sl_FsClose sl_FsWrite sl_FsOpen        
00298     \note           belongs to \ref basic_api       
00299     \warning     
00300     \par            Example:
00301     \code    
00302     Status = sl_FsRead(FileHandle, 0, &readBuff[0], readSize);
00303     \endcode
00304 */
00305 #if _SL_INCLUDE_FUNC(sl_FsRead)
00306 _i32 sl_FsRead(const _i32 FileHdl,_u32 Offset ,_u8*  pData,_u32 Len);
00307 #endif
00308 
00309 /*!
00310     \brief write block of data to a file in storage device
00311     
00312     \param[in]      FileHdl  Pointer to the file (assigned from sl_FsOpen)  
00313     \param[in]      Offset   Offset to specific block to be written
00314     \param[in]      pData    Pointer the transmitted data to the storage device
00315     \param[in]      Len      Length of the transmitted data
00316      
00317     \return         On success, returns the number of written bytes.  On error, an error code is returned
00318     
00319     \sa                     
00320     \note           belongs to \ref basic_api       
00321     \warning     
00322     \par            Example:
00323     \code    
00324     Status = sl_FsWrite(FileHandle, 0, &buff[0], readSize);
00325     \endcode
00326 */
00327 #if _SL_INCLUDE_FUNC(sl_FsWrite)
00328 _i32 sl_FsWrite(const _i32 FileHdl,_u32 Offset,_u8*  pData,_u32 Len);
00329 #endif
00330 
00331 /*!
00332     \brief get info on a file
00333     
00334     \param[in]      pFileName    File name
00335     \param[in]      Token        Reserved for future use. Use 0
00336     \param[out]     pFsFileInfo Returns the File's Information: flags,file size, allocated size and Tokens 
00337      
00338     \return         On success, zero is returned.   On error, an error code is returned    
00339     
00340     \sa             sl_FsOpen        
00341     \note           belongs to \ref basic_api       
00342     \warning        
00343     \par            Example:
00344     \code    
00345     Status = sl_FsGetInfo("FileName.html",0,&FsFileInfo);
00346     \endcode
00347 */
00348 #if _SL_INCLUDE_FUNC(sl_FsGetInfo)
00349 _i16 sl_FsGetInfo(const _u8 *pFileName,const _u32 Token,SlFsFileInfo_t* pFsFileInfo);
00350 #endif
00351 
00352 /*!
00353     \brief Delete specific file from a storage or all files from a storage (format)
00354     
00355     \param[in]      pFileName    File Name 
00356     \param[in]      Token        Reserved for future use. Use 0
00357     \return         On success, zero is returned.  On error, an error code is returned    
00358     
00359     \sa                     
00360     \note           belongs to \ref basic_api       
00361     \warning     
00362     \par            Example:
00363     \code    
00364     Status = sl_FsDel("FileName.html",0);
00365     \endcode
00366 */
00367 #if _SL_INCLUDE_FUNC(sl_FsDel)
00368 _i16 sl_FsDel(const _u8 *pFileName,const _u32 Token);
00369 #endif
00370 /*!
00371 
00372  Close the Doxygen group.
00373  @}
00374 
00375  */
00376 
00377 #ifdef  __cplusplus
00378 }
00379 #endif /*  __cplusplus */
00380 
00381 #endif /*  __FS_H__ */
00382