FileSystem

Provides file system capabilities to TI's CC31XX that can be used by both the CC31XX device and the user. More...

Functions
_i32	sl_FsOpen (const _u8 *pFileName, const _u32 AccessModeAndMaxSize, _u32 *pToken)
	open file for read or write from/to storage device More...
_i16	sl_FsClose (const _i32 FileHdl, const _u8 *pCeritificateFileName, const _u8 *pSignature, const _u32 SignatureLen)
	Close file in storage device. More...
_i32	sl_FsRead (const _i32 FileHdl, _u32 Offset, _u8 *pData, _u32 Len)
	Read block of data from a file in storage device. More...
_i32	sl_FsWrite (const _i32 FileHdl, _u32 Offset, _u8 *pData, _u32 Len)
	Write block of data to a file in storage device. More...
_i16	sl_FsGetInfo (const _u8 *pFileName, const _u32 Token, SlFsFileInfo_t *pFsFileInfo)
	Get information of a file. More...
_i16	sl_FsDel (const _u8 *pFileName, const _u32 Token)
	Delete specific file from a storage or all files from a storage (format) More...
_i32	sl_FsCtl (SlFsCtl_e Command, _u32 Token, _u8 *pFileName, const _u8 *pData, _u16 DataLen, _u8 *pOutputData, _u16 OutputDataLen, _u32 *pNewToken)
	Controls various file system operations. More...
_i32	sl_FsProgram (const _u8 *pData, _u16 Len, const _u8 *pKey, _u32 Flags)
	Enables to format and configure the device with pre-prepared configuration. More...
_i32	sl_FsGetFileList (_i32 *pIndex, _u8 Count, _u8 MaxEntryLen, _u8 *pBuff, SlFileListFlags_t Flags)
	The list of file names, the files are retrieve in chunks. More...

Enumerations
enum	SlFsTokenId_e {   SL_FS_TOKEN_MASTER = 0,   SL_FS_TOKEN_WRITE_READ = 1,   SL_FS_TOKEN_WRITE_ONLY = 2,   SL_FS_TOKEN_READ_ONLY = 3 }
enum	SlFsCtl_e {   SL_FS_CTL_RESTORE = 0,   SL_FS_CTL_ROLLBACK = 1,   SL_FS_CTL_COMMIT = 2,   SL_FS_CTL_RENAME = 3,   SL_FS_CTL_GET_STORAGE_INFO = 5,   SL_FS_CTL_BUNDLE_ROLLBACK = 6,   SL_FS_CTL_BUNDLE_COMMIT = 7 }
enum	SlFsBundleState_e {   SL_FS_BUNDLE_STATE_STOPPED = 0,   SL_FS_BUNDLE_STATE_STARTED = 1,   SL_FS_BUNDLE_STATE_PENDING_COMMIT = 3 }
enum	SlFsRetToFactoryOper_e {   SL_FS_FACTORY_RET_TO_IMAGE = 0,   SL_FS_FACTORY_RET_TO_DEFAULT = 2 }
enum	SlFileListFlags_t { SL_FS_GET_FILE_ATTRIBUTES = 0x1 }

Detailed Description

Provides file system capabilities to TI's CC31XX that can be used by both the CC31XX device and the user.

Function Documentation

_i16 sl_FsClose	(	const _i32	FileHdl,
		const _u8 *	pCeritificateFileName,
		const _u8 *	pSignature,
		const _u32	SignatureLen
	)

Close file in storage device.

Parameters

[in]	FileHdl	Pointer to the file (assigned from sl_FsOpen)
[in]	pCeritificateFileName	Certificate file, or NULL if irrelevant.
[in]	pSignature	The signature is SHA-1, the certificate chain may include SHA-256
[in]	SignatureLen	The signature actual length

Returns

Zero on success, or a negative value if an error occurred

See also

sl_FsRead sl_FsWrite sl_FsOpen

Note

Call the fs_Close with signature = 'A' signature len = 1 for activating an abort action
Creating signature : OpenSSL> dgst -binary -sha1 -sign <file-location><private_key>.pem -out <file-location><output>.sig <file-location><input>.txt

Warning

Examples

• Closing file:

  _i16 RetVal;
  RetVal = sl_FsClose(FileHandle,0,0,0);

  
  
• Aborting file:

  _u8  Signature;
  Signature = 'A';
  sl_FsClose(FileHandle,0,&Signature, 1);

Note

In case the file was opened as not secure file or as secure-not signed, any certificate or signature provided are ignored, those fields should be set to NULL.

Definition at line 247 of file fs.c.

{
    _SlFsCloseMsg_u    Msg;
    _SlCmdExt_t        ExtCtrl;

    _SlDrvMemZero(&Msg, (_u16)sizeof(SlFsCloseCommand_t));

    /* verify that this api is allowed. if not allowed then
    ignore the API execution and return immediately with an error */
    VERIFY_API_ALLOWED(SL_OPCODE_SILO_FS);


    Msg.Cmd.FileHandle             = (_u32)FileHdl;
    if( pCeritificateFileName != NULL )
    {
        Msg.Cmd.CertificFileNameLength = (_u32)((_SlFsStrlen(pCeritificateFileName)+4) & (~3)); /* add 4: 1 for NULL and the 3 for align */
    }
    Msg.Cmd.SignatureLen           = SignatureLen;

    _SlDrvMemZero(&ExtCtrl, (_u16)sizeof(_SlCmdExt_t));

    ExtCtrl.TxPayload1Len = (_u16)(((SignatureLen+3) & (~3))); /* align */
    ExtCtrl.pTxPayload1   = (_u8*)pSignature;
    ExtCtrl.RxPayloadLen = (_i16)Msg.Cmd.CertificFileNameLength;
    ExtCtrl.pRxPayload   = (_u8*)pCeritificateFileName; /* Add signature */

    if(ExtCtrl.pRxPayload != NULL &&  ExtCtrl.RxPayloadLen != 0)
    {
       ExtCtrl.RxPayloadLen = ExtCtrl.RxPayloadLen * (-1);
    }

    VERIFY_RET_OK(_SlDrvCmdOp((_SlCmdCtrl_t *)&_SlFsCloseCmdCtrl, &Msg, &ExtCtrl));

    return (_i16)((_i16)Msg.Rsp.status);
}

_i32 sl_FsCtl	(	SlFsCtl_e	Command,
		_u32	Token,
		_u8 *	pFileName,
		const _u8 *	pData,
		_u16	DataLen,
		_u8 *	pOutputData,
		_u16	OutputDataLen,
		_u32 *	pNewToken
	)

Controls various file system operations.

Parameters

[in]

Command,the

command to execute,

See also

SlFsCtl_e SL_FS_CTL_RESTORE , Return to factory default, return to factory image , see fs programming SL_FS_CTL_ROLLBACK , Roll-back file which was created with 'SL_FS_WRITE_MUST_COMMIT' SL_FS_CTL_COMMIT,Commit file which was created with 'SL_FS_WRITE_MUST_COMMIT' SL_FS_CTL_RENAME, Rename file SL_FS_CTL_GET_STORAGE_INFO, Total size of storage , available size of storage SL_FS_CTL_BUNDLE_ROLLBACK, Rollback bundle files SL_FS_CTL_BUNDLE_COMMIT, Commit Bundle files

Parameters

[in]	Token	Set to NULL if not relevant to the command
[in]	pFileName	Set to NULL if not relevant to the command
[in]	pData	The data according the command.
[in]	DataLen	Length of data buffer
[out]	pOutputData	Buffer for the output data
[out]	OutputDataLen	Length of the output data buffer
[out]	pNewToken	The new valid file token, if irrelevant can be set to NULL.

Returns

• Zero on success, or a negative value if an error occurred
• For SL_FS_CTL_BUNDLE_ROLLBACK, On success bundle the new bundle state is returned (see SlFsBundleState_e) else negative error number
• For SL_FS_CTL_BUNDLE_COMMIT, On success the new bundle state is returned (see SlFsBundleState_e) else negative error number

See also

Note

belongs to ext_api

Warning

Examples

• SL_FS_CTL_ROLLBACK:

  FsControl.IncludeFilters = 0;
  slRetVal = sl_FsCtl( (SlFsCtl_e)SL_FS_CTL_FILE_ROLLBACK, Token, NWPfileName ,(_u8 *)&FsControl, sizeof(SlFsControl_t), NULL, 0 , pNewToken);

  
  
• SL_FS_CTL_COMMIT:

  FsControl.IncludeFilters = 0;
  slRetVal = sl_FsCtl(SL_FS_CTL_COMMIT, Token, NWPfileName ,(_u8 *)&FsControl, sizeof(SlFsControl_t), NULL, 0, pNewToken );

  
  
• SL_FS_CTL_RENAME:

  slRetVal = sl_FsCtl(SL_FS_CTL_RENAME, Token, NWPfileName, NewFileName, 0, NULL, 0, NULL );

  
  
• SL_FS_CTL_GET_STORAGE_INFO:

  _i32  GetStorageInfo( SlFsControlGetStorageInfoResponse_t* pSlFsControlGetStorageInfoResponse )
  {
      _i32 slRetVal;
  
      slRetVal = sl_FsCtl( ( SlFsCtl_e)SL_FS_CTL_GET_STORAGE_INFO, 0, NULL , NULL , 0, (_u8 *)pSlFsControlGetStorageInfoResponse, sizeof(SlFsControlGetStorageInfoResponse_t), NULL );
      return slRetVal;
  
  }

  
  
• SL_FS_CTL_RESTORE:

  //Return 0 for OK, else Error
  _i32 ProgramRetToImage( )
  {
      _i32 slRetVal;
      SlFsRetToFactoryCommand_t RetToFactoryCommand;
      _i32 RetVal, ExtendedError;
  
          RetToFactoryCommand.Operation = SL_FS_FACTORY_RET_TO_IMAGE;
      slRetVal = sl_FsCtl( (SlFsCtl_e)SL_FS_CTL_RESTORE, 0, NULL , (_u8 *)&RetToFactoryCommand , sizeof(SlFsRetToFactoryCommand_t), NULL, 0 , NULL );
          if ((_i32)slRetVal < 0)
          {
              //Pay attention, for this function the slRetVal is composed from Signed RetVal & extended error
              RetVal = (_i16)slRetVal>> 16;
              ExtendedError = (_u16)slRetVal& 0xFFFF;
              printf("\tError SL_FS_FACTORY_RET_TO_IMAGE, 5d, %d\n", RetVal, ExtendedError);
              return slRetVal;
      }
      //Reset
      sl_Stop(0);
      Sleep(1000);
      sl_Start(NULL, NULL, NULL);
  
      return slRetVal;
  }

  
  
• SL_FS_CTL_BUNDLE_ROLLBACK:

  //return 0 for O.K else negative
  _i32 BundleRollback()
  {
      _i32 slRetVal = 0;
          SlFsControl_t FsControl;
          FsControl.IncludeFilters = 0; //Use default behaviour
          slRetVal = sl_FsCtl( (SlFsCtl_e)SL_FS_CTL_BUNDLE_ROLLBACK, 0, NULL ,(_u8 *)&FsControl, sizeof(SlFsControl_t), NULL, 0 , NULL);
          return slRetVal;
  }

  
  
• SL_FS_CTL_BUNDLE_COMMIT:

  //return 0 for O.K else negative
  _i32 BundleCommit()
  {
      _i32 slRetVal = 0;
          SlFsControl_t FsControl;
          FsControl.IncludeFilters = 0; //Use default behaviour
          slRetVal = sl_FsCtl( (SlFsCtl_e)SL_FS_CTL_BUNDLE_COMMIT, 0, NULL ,(_u8 *)&FsControl, sizeof(SlFsControl_t), NULL, 0 , NULL);
          return slRetVal;
  }

Definition at line 597 of file fs.c.

{
    _SlFsFileSysControlMsg_u     Msg;
    _SlCmdExt_t                  CmdExt;

    /* verify that this api is allowed. if not allowed then
    ignore the API execution and return immediately with an error */
    VERIFY_API_ALLOWED(SL_OPCODE_SILO_FS);

    Msg.Cmd.Token = Token;
    Msg.Cmd.Operation = (_u8)Command;

    _SlDrvMemZero(&CmdExt, (_u16)sizeof(_SlCmdExt_t));

    if ((SL_FS_CTL_ROLLBACK == Command) || (SL_FS_CTL_COMMIT == Command ))
    {
        Msg.Cmd.FileNameLength = _SlFsStrlen(pFileName) + 1 ;

        if ( _SlFsStrlen(pFileName) >= SL_FS_MAX_FILE_NAME_LENGTH )
        {
            return SL_ERROR_FS_WRONG_FILE_NAME;
        }


        /*the data is aligned*/
        CmdExt.RxPayloadLen = DataLen;
        CmdExt.pRxPayload = (_u8 *)(pData);

        CmdExt.TxPayload1Len = (_SlFsStrlen(pFileName) + 4) & (~3);
        CmdExt.pTxPayload1   = pFileName;

        Msg.Cmd.BufferLength =  CmdExt.RxPayloadLen + CmdExt.TxPayload1Len;

       if(CmdExt.pRxPayload != NULL &&  CmdExt.RxPayloadLen != 0)
       {
           CmdExt.RxPayloadLen = CmdExt.RxPayloadLen * (-1);
       }


    }
    else if( SL_FS_CTL_RENAME == Command )
    {
        if ( _SlFsStrlen(pFileName) >= SL_FS_MAX_FILE_NAME_LENGTH )
        {
            return SL_ERROR_FS_WRONG_FILE_NAME;
        }

      Msg.Cmd.FileNameLength = (_SlFsStrlen(pFileName) + 4) & (~3);

        /*current file name*/
        CmdExt.RxPayloadLen = (_u16)Msg.Cmd.FileNameLength;
        CmdExt.pRxPayload   = pFileName;


      /*New file name*/
        CmdExt.TxPayload1Len = (_SlFsStrlen(pData) + 4) & (~3);;
        CmdExt.pTxPayload1 = (_u8 *)(pData);

        Msg.Cmd.BufferLength =  CmdExt.RxPayloadLen + CmdExt.TxPayload1Len;

       if(CmdExt.pRxPayload != NULL &&  CmdExt.RxPayloadLen != 0)
       {
           CmdExt.RxPayloadLen = CmdExt.RxPayloadLen * (-1);
       }

    }
    else
    {
    Msg.Cmd.FileNameLength = 0;

    CmdExt.TxPayload1Len = (DataLen + 3) & (~3);
    CmdExt.pTxPayload1 = (_u8 *)(pData);

    CmdExt.RxPayloadLen = OutputDataLen;
    CmdExt.pRxPayload = pOutputData;

    Msg.Cmd.BufferLength =  CmdExt.TxPayload1Len;
    }



    VERIFY_RET_OK(_SlDrvCmdOp((_SlCmdCtrl_t *)&_SlFsFileSysControlCmdCtrl, &Msg, &CmdExt));

  if( pNewToken != NULL )
  {
      *pNewToken = Msg.Rsp.Token;
  }

    return  (_i32)((_i32)Msg.Rsp.Status);
}

_i16 sl_FsDel	(	const _u8 *	pFileName,
		const _u32	Token
	)

Delete specific file from a storage or all files from a storage (format)

Parameters

[in]	pFileName	File Name
[in]	Token	File token. if irrelevant set to 0

Returns

Zero on success, or a negative value if an error occurred

See also

Note

belongs to basic_api

Warning

Example

• Deleting file:

  Status = sl_FsDel("FileName.html",Token);

Definition at line 549 of file fs.c.

{
    _SlFsDeleteMsg_u Msg;
    _SlCmdExt_t          CmdExt;


    /* verify that this api is allowed. if not allowed then
    ignore the API execution and return immediately with an error */
    VERIFY_API_ALLOWED(SL_OPCODE_SILO_FS);

    if ( _SlFsStrlen(pFileName) >= SL_FS_MAX_FILE_NAME_LENGTH )
    {
        return SL_ERROR_FS_WRONG_FILE_NAME;
    }


    _SlDrvMemZero(&CmdExt, (_u16)sizeof(_SlCmdExt_t));

    CmdExt.TxPayload1Len = (_u16)((_SlFsStrlen(pFileName)+4) & (~3)); /* add 4: 1 for NULL and the 3 for align */
    CmdExt.pTxPayload1   = (_u8*)pFileName;
    Msg.Cmd.Token       = Token;


    VERIFY_RET_OK(_SlDrvCmdOp((_SlCmdCtrl_t *)&_SlFsDeleteCmdCtrl, &Msg, &CmdExt));

    return  (_i16)((_i16)Msg.Rsp.status);
}

_i32 sl_FsGetFileList	(	_i32 *	pIndex,
		_u8	Count,
		_u8	MaxEntryLen,
		_u8 *	pBuff,
		SlFileListFlags_t	Flags
	)

The list of file names, the files are retrieve in chunks.

Parameters

[in,out]	pIndex	The first chunk should start with value of -1, afterwards the Index from the previous call should be set as input Returns current chunk intex, start the next chunk from that number
[in]	Count	Number of entries to retrieve
[in]	MaxEntryLen	The total size of the buffer is Count * MaxEntryLen
[out]	pBuff	The buffer contains list of SlFileAttributes_t + file name
[in]	Flags	Is to retrieve file attributes see SlFileAttributes_t.

Returns

The actual number of entries which are contained in the buffer. On error negative number which contains the error number.

See also

Note

belongs to ext_api

Warning

Example

• Getting file list

  typedef struct
  {
      SlFileAttributes_t attribute;
      char fileName[SL_FS_MAX_FILE_NAME_LENGTH];
  }slGetfileList_t;
  
  #define COUNT 5
  
  void PrintFileListProperty(_u16 prop);
  
  INT32 GetFileList()
  {
      _i32 NumOfEntriesOrError = 1;
      _i32 Index = -1;
      slGetfileList_t File[COUNT];
      _i32  i;
         _i32 RetVal = 0;
  
         printf("%\n");
      while( NumOfEntriesOrError > 0 )
      {
             NumOfEntriesOrError = sl_FsGetFileList( &Index, COUNT, (_u8)(SL_FS_MAX_FILE_NAME_LENGTH + sizeof(SlFileAttributes_t)), (unsigned char*)File, SL_FS_GET_FILE_ATTRIBUTES);
             if (NumOfEntriesOrError < 0)
                   {
                             RetVal = NumOfEntriesOrError;//error
                    break;
                   }
             for (i = 0; i < NumOfEntriesOrError; i++)
             {
                    printf("Name: %s\n", File[i].fileName);
                    printf("AllocatedBlocks: %5d ",File[i].attribute.FileAllocatedBlocks);
                               printf("MaxSize(byte): %5d \n", File[i].attribute.FileMaxSize);
                               PrintFileListProperty((_u16)File[i].attribute.Properties);
                               printf("%\n\n");
             }
      }
         printf("%\n");
         return RetVal;//0 means O.K
  }
  
  void PrintFileListProperty(_u16 prop)
  {
         printf("Flags : ");
         if (prop & SL_FS_INFO_MUST_COMMIT)
                printf("Open file commit,");
         if (prop & SL_FS_INFO_BUNDLE_FILE)
                printf("Open bundle commit,");
         if (prop & SL_FS_INFO_PENDING_COMMIT)
                printf("Pending file commit,");
         if (prop & SL_FS_INFO_PENDING_BUNDLE_COMMIT)
                printf("Pending bundle commit,");
         if (prop & SL_FS_INFO_SECURE)
                printf("Secure,");
         if (prop & SL_FS_INFO_NOT_FAILSAFE)
                printf("File safe,");
         if (prop & SL_FS_INFO_SYS_FILE)
                printf("System,");
         if (prop & SL_FS_INFO_NOT_VALID)
                printf("No valid copy,");
         if (prop & SL_FS_INFO_PUBLIC_WRITE)
                printf("Public write,");
         if (prop & SL_FS_INFO_PUBLIC_READ)
                printf("Public read,");
  }

Definition at line 814 of file fs.c.

{
  _SlFsGetFileListMsg_u     Msg;
    _SlCmdExt_t                CmdExt;
    _u16                       OutputBufferSize;


    /* verify that this api is allowed. if not allowed then
    ignore the API execution and return immediately with an error */
    VERIFY_API_ALLOWED(SL_OPCODE_SILO_FS);

    _SlDrvResetCmdExt(&CmdExt);

    Msg.Cmd.Index = *pIndex;
    Msg.Cmd.MaxEntryLen = MaxEntryLen  & (~3); /* round to modulu 4 */
    Msg.Cmd.Count = Count;
    Msg.Cmd.Flags = (_u8)Flags;

    OutputBufferSize = Msg.Cmd.Count * Msg.Cmd.MaxEntryLen;
    if( OutputBufferSize > MAX_NVMEM_CHUNK_SIZE )
    {
      return SL_ERROR_FS_WRONG_INPUT_SIZE;
    }

    CmdExt.RxPayloadLen = OutputBufferSize;
    CmdExt.pRxPayload   = pBuff;

    VERIFY_RET_OK(_SlDrvCmdOp((_SlCmdCtrl_t *)&_SlFsGetFileListCmdCtrl, &Msg, &CmdExt));


    *pIndex = Msg.Rsp.Index;

    return  (_i32)((_i32)Msg.Rsp.NumOfEntriesOrError);
}

_i16 sl_FsGetInfo	(	const _u8 *	pFileName,
		const _u32	Token,
		SlFsFileInfo_t *	pFsFileInfo
	)

Get information of a file.

Parameters

[in]	pFileName	File name
[in]	Token	File token. if irrelevant set to 0.
[out]	pFsFileInfo	Returns the File's Information (SlFsFileInfo_t) Flags File size Allocated size Tokens

Returns

Zero on success, negative error code on failure
When file not exists : SL_ERROR_FS_FILE_NOT_EXISTS

Note

• If the return value is SL_ERROR_FS_FILE_HAS_NOT_BEEN_CLOSE_CORRECTLY or SL_ERROR_FS_FILE_IS_ALREADY_OPENED information about the file is valid.
• Belongs to basic_api

See also

sl_FsOpen

Warning

Example

• Getting file info:

  Status = sl_FsGetInfo("FileName.html",Token,&FsFileInfo);

Definition at line 482 of file fs.c.

{
    _SlFsGetInfoMsg_u    Msg;
    _SlCmdExt_t          CmdExt;
    _u16                 BitNum;

    /* verify that this api is allowed. if not allowed then
    ignore the API execution and return immediately with an error */
    VERIFY_API_ALLOWED(SL_OPCODE_SILO_FS);

    _SlDrvMemZero(&CmdExt, (_u16)sizeof(_SlCmdExt_t));

    if ( _SlFsStrlen(pFileName) >= SL_FS_MAX_FILE_NAME_LENGTH )
    {
        return SL_ERROR_FS_WRONG_FILE_NAME;
    }


    CmdExt.TxPayload1Len = (_u16)((_SlFsStrlen(pFileName)+4) & (~3)); /* add 4: 1 for NULL and the 3 for align  */
    CmdExt.pTxPayload1   = (_u8*)pFileName;

    Msg.Cmd.Token       = Token;

    VERIFY_RET_OK(_SlDrvCmdOp((_SlCmdCtrl_t *)&_SlFsGetInfoCmdCtrl, &Msg, &CmdExt));


    /* convert flags */
    pFsFileInfo->Flags = 0;
    for (BitNum = 0; BitNum < 16; BitNum++ )
    {
        if (( Msg.Rsp.Flags >> BitNum) & 0x1 )
        {
            pFsFileInfo->Flags |= FlagsTranslate[BitNum];
        }
    }

    pFsFileInfo->Len          = Msg.Rsp.FileLen;
    pFsFileInfo->MaxSize      = Msg.Rsp.AllocatedLen;
    pFsFileInfo->Token[0]     = Msg.Rsp.Token[0];
    pFsFileInfo->Token[1]     = Msg.Rsp.Token[1];
    pFsFileInfo->Token[2]     = Msg.Rsp.Token[2];
    pFsFileInfo->Token[3]     = Msg.Rsp.Token[3];
    pFsFileInfo->StorageSize  = Msg.Rsp.FileStorageSize;
    pFsFileInfo->WriteCounter = Msg.Rsp.FileWriteCounter;
    return  (_i16)((_i16)Msg.Rsp.Status);
}

_i32 sl_FsOpen	(	const _u8 *	pFileName,
		const _u32	AccessModeAndMaxSize,
		_u32 *	pToken
	)

open file for read or write from/to storage device

Parameters

[in]	pFileName	File Name buffer pointer
[in]	AccessModeAndMaxSize	Options: As described below
[in]	pToken	input Token for read, output Token for write

AccessModeAndMaxSize possible input
SL_FS_READ - Read a file
SL_FS_WRITE - Open for write for an existing file (whole file content needs to be rewritten)
SL_FS_CREATE|maxSizeInBytes,accessModeFlags SL_FS_CREATE|SL_FS_OVERWRITE|maxSizeInBytes,accessModeFlags - Open for creating a new file. Max file size is defined in bytes.
For optimal FS size, use max size in 4K-512 bytes steps (e.g. 3584,7680,117760)
Several access modes bits can be combined together from SlFileOpenFlags_e enum

Returns

File handle on success. Negative error code on fail

See also

sl_FsRead sl_FsWrite sl_FsClose

Note

belongs to basic_api

Warning

Example

• Creating file and writing data to it

  char*           DeviceFileName = "MyFile.txt";
  unsigned long   MaxSize = 63 * 1024; //62.5K is max file size
  long            DeviceFileHandle = -1;
  _i32            RetVal;        //negative retval is an error
  unsigned long   Offset = 0;
  unsigned char   InputBuffer[100];
  _u32 MasterToken = 0;
  
  // Create a file and write data. The file in this example is secured, without signature and with a fail safe commit
  
  //create a secure file if not exists and open it for write.
  DeviceFileHandle =  sl_FsOpen(unsigned char *)DeviceFileName,
                       SL_FS_CREATE|SL_FS_OVERWRITE | SL_FS_CREATE_SECURE | SL_FS_CREATE_NOSIGNATURE | SL_FS_CREATE_MAX_SIZE( MaxSize ),
                       &MasterToken);
  
  Offset = 0;
  //Preferred in secure file that the Offset and the length will be aligned to 16 bytes.
  RetVal = sl_FsWrite( DeviceFileHandle, Offset, (unsigned char *)"HelloWorld", strlen("HelloWorld"));
  
  RetVal = sl_FsClose(DeviceFileHandle, NULL, NULL , 0);
  
  // open the same file for read, using the Token we got from the creation procedure above
  DeviceFileHandle =  sl_FsOpen(unsigned char *)DeviceFileName,
                                   SL_FS_READ,
                                   &MasterToken);
  
  Offset = 0;
  RetVal = sl_FsRead( DeviceFileHandle, Offset, (unsigned char *)InputBuffer, strlen("HelloWorld"));
  
  RetVal = sl_FsClose(DeviceFileHandle, NULL, NULL , 0);

  
  

  • Create a non secure file if not already exists and open it for write

    DeviceFileHandle = sl_FsOpen((unsigned char *)DeviceFileName,
                                     SL_FS_CREATE|SL_FS_OVERWRITE| SL_FS_CREATE_MAX_SIZE( MaxSize ),
                                      NULL);

  Note

  Some of the flags are creation flags and can only be set when the file is created. When opening the file for write the creation flags are ignored. For more information, refer to chapter 8 in the user manual.

Definition at line 149 of file fs.c.

{

    _SlFsOpenMsg_u        Msg;
    _SlCmdExt_t           CmdExt;
    _i32                  FileHandle;
    _u32                  MaxSizeInBytes;
    _u32                  OpenMode;
    _u8                   CreateMode;


    /* verify that this api is allowed. if not allowed then
    ignore the API execution and return immediately with an error */
    VERIFY_API_ALLOWED(SL_OPCODE_SILO_FS);

    _SlDrvMemZero(&CmdExt, (_u16)sizeof(_SlCmdExt_t));

    if ( _SlFsStrlen(pFileName) >= SL_FS_MAX_FILE_NAME_LENGTH )
    {
        return SL_ERROR_FS_WRONG_FILE_NAME;
    }

    CmdExt.TxPayload1Len = (_u16)((_SlFsStrlen(pFileName)+4) & (~3)); /* add 4: 1 for NULL and the 3 for align */
    CmdExt.pTxPayload1 = (_u8*)pFileName;

    OpenMode = ModeAndMaxSize & SL_FS_OPEN_MODE_BIT_MASK;

    /*convert from the interface flags to the device flags*/
    if( OpenMode == SL_FS_READ )
    {
        Msg.Cmd.Mode = FS_MODE(FS_MODE_OPEN_READ, 0, 0, 0);
    }
    else if (( OpenMode == SL_FS_WRITE ) ||( OpenMode == SL_FS_OVERWRITE))
    {
        Msg.Cmd.Mode = FS_MODE(FS_MODE_OPEN_WRITE, 0, 0, FS_CONVERT_FLAGS ( ModeAndMaxSize));
    }
    /* one of the creation mode */
    else if ( ( OpenMode == (SL_FS_CREATE | SL_FS_OVERWRITE )) || ( OpenMode == SL_FS_CREATE) ||(OpenMode == (SL_FS_CREATE | SL_FS_WRITE )))
    {
       /* test that the size is correct */
       MaxSizeInBytes = (ModeAndMaxSize & SL_FS_OPEN_MAXSIZE_BIT_MASK) * 256;
       if (MaxSizeInBytes > 0xFF0000 )
       {
           return SL_ERROR_FS_FILE_MAX_SIZE_EXCEEDED;
       }

       CreateMode = ((OpenMode == (SL_FS_CREATE | SL_FS_OVERWRITE )) ? FS_MODE_OPEN_WRITE_CREATE_IF_NOT_EXIST : FS_MODE_OPEN_CREATE  );

        Msg.Cmd.Mode = FsGetCreateFsMode( CreateMode ,MaxSizeInBytes, FS_CONVERT_FLAGS ( ModeAndMaxSize)  );
    }
    else
    {
        return SL_ERROR_FS_UNVALID_FILE_MODE;
    }




    if(pToken != NULL)
    {
        Msg.Cmd.Token         = *pToken;
    }
    else
    {
        Msg.Cmd.Token         = 0;
    }

    _SlDrvCmdOp((_SlCmdCtrl_t *)&_SlFsOpenCmdCtrl, &Msg, &CmdExt);
    FileHandle = (_i32)Msg.Rsp.FileHandle;
    if (pToken != NULL)
    {
        *pToken =      Msg.Rsp.Token;
    }

    /* in case of an error, return the erros file handler as an error code */
    return FileHandle;
}

_i32 sl_FsProgram	(	const _u8 *	pData,
		_u16	Len,
		const _u8 *	pKey,
		_u32	Flags
	)

Enables to format and configure the device with pre-prepared configuration.

Parameters

[in]	Flags	For future use
[in]	pKey	In case the ucf is encrypted the encryption key, otherwise NULL
[in]	pData	The file is download in data chunks, the chunk size should be aligned to 16 bytes, if no data Set to NULL
[in]	Len	The length of pData in bytes

Returns

The return value is:

• On error < 0 , contains the error number and extended error number
• On success > 0, represent the number of bytes received
• On successful end == 0 , when all file chunks are download

See also

Note

belongs to ext_api

Warning

Example

• FS programming:

  //Return 0 for OK, else Error
  _i32 ProgramImage( char* UcfFileName, char * KeyFileName )
  {
  #define PROGRAMMING_CHUNK_SIZE 4096
      _i32 slRetVal = 0;
      SlFsKey_t Key;
      FILE *hostFileHandle = NULL;
      _u16 bytesRead;
      _u8 DataBuf[PROGRAMMING_CHUNK_SIZE];
      FILE *KeyFileHandle = NULL;
      short ErrorNum;
      unsigned short ExtendedErrorNum;
      time_t start,end;
      double dif;
      _u8* pKey = NULL;
      errno_t err;
  
  
  
      if (KeyFileName != "")
      {
          //Read key
          err   = fopen_s( &KeyFileHandle, KeyFileName, "rb");
          if (err != 0)
          {
              return __LINE__;//error
          }
          fread((_u8*)&Key, 1, sizeof(SlFsKey_t), KeyFileHandle);
          fclose(KeyFileHandle);
          pKey = (_u8*)&Key;
      }
  
      // Downlaoding the Data with the key, the key can be set only in the first chunk,no need to download it with each chunk
      if (UcfFileName != "")
      {
          //Read data
           err   = fopen_s( &hostFileHandle, UcfFileName, "rb");
          if (err != 0)
          {
              return __LINE__;//error
          }
  
  
         time (&start);
  
          bytesRead = fread(DataBuf, 1, PROGRAMMING_CHUNK_SIZE, hostFileHandle);
  
          while ( bytesRead  )
          {
              slRetVal =  sl_FsProgram( DataBuf , bytesRead , (_u8*)pKey,  0 );
              if(slRetVal ==  SL_API_ABORTED)//timeout
              {
                  return( slRetVal );
              }
              else if (slRetVal < 0 )//error
              {
                  ErrorNum = (long)slRetVal >> 16;
                  ExtendedErrorNum = (_u16)(slRetVal & 0xFFFF);
                  printf("\tError sl_FsProgram = %d , %d \n", ErrorNum, ExtendedErrorNum);
                  fclose(hostFileHandle);
                  return( ErrorNum );
              }
              if(slRetVal == 0)//finished succesfully
                  break;
              pKey = NULL;//no need to download the key with each chunk;
              bytesRead = fread(DataBuf, 1, PROGRAMMING_CHUNK_SIZE, hostFileHandle);
          }
  
  
            time (&end);
            dif = difftime (end,start);
      #ifdef PRINT
            printf ("\tProgramming took %.2lf seconds to run.\n", dif );
      #endif
            //The file was downloaded but it was not detected by the programming as the EOF.
            if((bytesRead == 0 ) && (slRetVal > 0 ))
            {
                return __LINE__;//error
            }
  
  
          fclose(hostFileHandle);
      }//if (UcfFileName != "")
  
      //this scenario is in case the image was already "burned" to the SFLASH by external tool and only the key is downloaded
      else if (KeyFileName != "")
      {
          slRetVal =  sl_FsProgram(NULL , 0 , (_u8*)pKey,  0 );
          if (slRetVal < 0)//error
          {
              ErrorNum = (long)slRetVal >> 16;
              ExtendedErrorNum = (_u16)slRetVal && 0xFF;;
              printf("\tError sl_FsProgram = %d , %d \n", ErrorNum, ExtendedErrorNum);
              fclose(hostFileHandle);
              return( ErrorNum );
          }
      }
  
      if( slRetVal == 0 )
      {
          //Reset the nWP
          sl_Stop(100);
          Sleep(1000);
          sl_Start(NULL, NULL, NULL);
          Sleep(2000);
       }
  
      return slRetVal;
  
  }

Definition at line 709 of file fs.c.

{
    _SlFsProgrammingMsg_u     Msg;
    _SlCmdExt_t                CmdExt;
    _u16                       ChunkLen;

    VERIFY_API_ALLOWED(SL_OPCODE_SILO_FS);

    Msg.Cmd.Flags = (_u32)Flags;

   _SlDrvResetCmdExt(&CmdExt);

    /* no data and no key, called only for extracting the image */
    if( (DataLen == 0) && (pKey == NULL) )
    {
        Msg.Cmd.ChunkLen = 0;
        Msg.Cmd.KeyLen = 0;
        Msg.Cmd.Flags = Flags;
        VERIFY_RET_OK(_SlDrvCmdOp((_SlCmdCtrl_t *)&_SlFsProgrammingCmdCtrl, &Msg, &CmdExt));
    }
    else if( (DataLen> 0)  && ( pData == NULL))
    {
       return( ((_i32)SL_ERROR_FS_WRONG_INPUT_SIZE) << 16 );
    }
    else if( (DataLen == 0) && (pKey != NULL) )
    {
        Msg.Cmd.ChunkLen = 0;
        Msg.Cmd.KeyLen = sizeof(SlFsKey_t);;
        Msg.Cmd.Flags = Flags;
        CmdExt.pTxPayload1 = (_u8*)pKey;
        CmdExt.TxPayload1Len  = sizeof(SlFsKey_t);
        VERIFY_RET_OK(_SlDrvCmdOp((_SlCmdCtrl_t *)&_SlFsProgrammingCmdCtrl, &Msg, &CmdExt));
    }
    else /* DataLen > 0 */
   {
        if( (DataLen & 0xF) > 0)
        {
            return( ((_i32)SL_ERROR_FS_NOT_16_ALIGNED) << 16 );
        }
        Msg.Cmd.Flags = Flags;

        CmdExt.pTxPayload1   = (_u8 *)pData;
        ChunkLen = (_u16)sl_min(MAX_NVMEM_CHUNK_SIZE, DataLen);

        while(ChunkLen > 0)
        {
            Msg.Cmd.ChunkLen  = ChunkLen;
            CmdExt.TxPayload1Len = ChunkLen;
            if( pKey != NULL )
            {
                Msg.Cmd.KeyLen = sizeof(SlFsKey_t);
                CmdExt.RxPayloadLen = sizeof(SlFsKey_t);
                CmdExt.pRxPayload   = (_u8 *)pKey;

                if(CmdExt.pRxPayload != NULL &&  CmdExt.RxPayloadLen != 0)
                {
                   CmdExt.RxPayloadLen = CmdExt.RxPayloadLen * (-1);
                }
            }
            else /* No key */
            {
                Msg.Cmd.KeyLen = 0;
                CmdExt.RxPayloadLen = 0;
                CmdExt.pRxPayload   = NULL;
            }

            VERIFY_RET_OK( _SlDrvCmdOp((_SlCmdCtrl_t *)&_SlFsProgrammingCmdCtrl, &Msg, &CmdExt));

            if( Msg.Rsp.Status <= 0 ) /* Error or finished */
            {
                return (_i32)(Msg.Rsp.Status);
            }

            DataLen -= ChunkLen;
            CmdExt.pTxPayload1 += ChunkLen;

            ChunkLen = (_u16)sl_min(MAX_NVMEM_CHUNK_SIZE, DataLen);
        }
    }
    return  (_i32)(Msg.Rsp.Status);
}

_i32 sl_FsRead	(	const _i32	FileHdl,
		_u32	Offset,
		_u8 *	pData,
		_u32	Len
	)

Read block of data from a file in storage device.

Parameters

[in]	FileHdl	Pointer to the file (assigned from sl_FsOpen)
[in]	Offset	Offset to specific read block
[out]	pData	Pointer for the received data
[in]	Len	Length of the received data

Returns

Number of read bytes on success, negative error code on failure

See also

sl_FsClose sl_FsWrite sl_FsOpen

Note

belongs to basic_api

Warning

Example

• Reading File:

  Status = sl_FsRead(FileHandle, 0, &readBuff[0], readSize);

Definition at line 304 of file fs.c.

{
    _SlFsReadMsg_u      Msg;
    _SlCmdExt_t         ExtCtrl;
    _u16      ChunkLen;
    _SlReturnVal_t      RetVal =0;
    _i32                RetCount = 0;

    /* verify that this api is allowed. if not allowed then
    ignore the API execution and return immediately with an error */
    VERIFY_API_ALLOWED(SL_OPCODE_SILO_FS);

    _SlDrvMemZero(&ExtCtrl, (_u16)sizeof(_SlCmdExt_t));

    ChunkLen = (_u16)sl_min(MAX_NVMEM_CHUNK_SIZE,Len);
    ExtCtrl.RxPayloadLen = (_i16)ChunkLen;
    ExtCtrl.pRxPayload   = (_u8 *)(pData);
    Msg.Cmd.Offset       = Offset;
    Msg.Cmd.Len          = ChunkLen;
    Msg.Cmd.FileHandle   = (_u32)FileHdl;
    do
    {
        RetVal = _SlDrvCmdOp((_SlCmdCtrl_t *)&_SlFsReadCmdCtrl, &Msg, &ExtCtrl);
        if(SL_OS_RET_CODE_OK == RetVal)
        {
            if( Msg.Rsp.status < 0)
            {
                if( RetCount > 0)
                {
                   return RetCount;
                }
                else
                {
                   return Msg.Rsp.status;
                }
            }
            RetCount += (_i32)Msg.Rsp.status;
            Len -= ChunkLen;
            Offset += ChunkLen;
            Msg.Cmd.Offset      = Offset;
            ExtCtrl.pRxPayload   += ChunkLen;
            ChunkLen = (_u16)sl_min(MAX_NVMEM_CHUNK_SIZE,Len);
            ExtCtrl.RxPayloadLen  = (_i16)ChunkLen;
            Msg.Cmd.Len           = ChunkLen;
            Msg.Cmd.FileHandle  = (_u32)FileHdl;
        }
        else
        {
            return RetVal;
        }
    }while(ChunkLen > 0);

    return (_i32)RetCount;
}

_i32 sl_FsWrite	(	const _i32	FileHdl,
		_u32	Offset,
		_u8 *	pData,
		_u32	Len
	)

Write block of data to a file in storage device.

Parameters

[in]	FileHdl	Pointer to the file (assigned from sl_FsOpen)
[in]	Offset	Offset to specific block to be written
[in]	pData	Pointer the transmitted data to the storage device
[in]	Len	Length of the transmitted data

Returns

Number of wireted bytes on success, negative error code on failure

See also

Note

belongs to basic_api

Warning

Example

• Writing file:

  Status = sl_FsWrite(FileHandle, 0, &buff[0], readSize);

Definition at line 379 of file fs.c.

{
    _SlFsWriteMsg_u     Msg;
    _SlCmdExt_t         ExtCtrl;
    _u16      ChunkLen;
    _SlReturnVal_t      RetVal;
    _i32                RetCount = 0;

    /* verify that this api is allowed. if not allowed then
    ignore the API execution and return immediately with an error */
    VERIFY_API_ALLOWED(SL_OPCODE_SILO_FS);

    _SlDrvMemZero(&ExtCtrl, (_u16)sizeof(_SlCmdExt_t));

    ChunkLen = (_u16)sl_min(MAX_NVMEM_CHUNK_SIZE,Len);
    ExtCtrl.TxPayload1Len = ChunkLen;
    ExtCtrl.pTxPayload1   = (_u8 *)(pData);
    Msg.Cmd.Offset      = Offset;
    Msg.Cmd.Len          = ChunkLen;
    Msg.Cmd.FileHandle  = (_u32)FileHdl;

    do
    {

        RetVal = _SlDrvCmdOp((_SlCmdCtrl_t *)&_SlFsWriteCmdCtrl, &Msg, &ExtCtrl);
        if(SL_OS_RET_CODE_OK == RetVal)
        {
            if( Msg.Rsp.status < 0)
            {
                if( RetCount > 0)
                {
                   return RetCount;
                }
                else
                {
                   return Msg.Rsp.status;
                }
            }

            RetCount += (_i32)Msg.Rsp.status;
            Len -= ChunkLen;
            Offset += ChunkLen;
            Msg.Cmd.Offset        = Offset;
            ExtCtrl.pTxPayload1   += ChunkLen;
            ChunkLen = (_u16)sl_min(MAX_NVMEM_CHUNK_SIZE,Len);
            ExtCtrl.TxPayload1Len  = ChunkLen;
            Msg.Cmd.Len           = ChunkLen;
            Msg.Cmd.FileHandle  = (_u32)FileHdl;
        }
        else
        {
            return RetVal;
        }
    }while(ChunkLen > 0);

    return (_i32)RetCount;
}

---

Data Structure Documentation

struct SlFsFileInfo_t

Definition at line 80 of file fs.h.

Data Fields
_u16	Flags
_u32	Len
_u32	MaxSize
_u32	StorageSize
_u32	Token[4]
_u32	WriteCounter

struct SlFsKey_t

Definition at line 170 of file fs.h.

Data Fields
_u32	Key[4]

struct SlFsFileNameIndex_t

Definition at line 177 of file fs.h.

Data Fields
_u8	Index

union SlFsFileNameIndexOrError_t

Definition at line 182 of file fs.h.

Data Fields
_i32	ErrorNumber
SlFsFileNameIndex_t	Index

struct SlFsRetToFactoryCommand_t

Definition at line 199 of file fs.h.

Data Fields
_u32	Operation

struct SlFsControl_t

Definition at line 212 of file fs.h.

Data Fields
_u32	IncludeFilters

struct SlFsControlDeviceUsage_t

Definition at line 220 of file fs.h.

Data Fields
_u16	DeviceBlocksCapacity
_u16	DeviceBlockSize
_u16	LargestAllocatedGapInBlocks
_u16	NumOfAllocatedBlocks
_u16	NumOfAvailableBlocksForUserFiles
_u16	NumOfReservedBlocks
_u16	NumOfReservedBlocksForSystemfiles
_u8	Padding[2]

struct SlFsControlFilesUsage_t

Definition at line 232 of file fs.h.

Data Fields
_u8	ActualNumOfSysFiles
_u8	ActualNumOfUserFiles
_u8	Bundlestate
_u16	FATWriteCounter
_u8	IsDevlopmentFormatType
_u8	MaxFsFiles
_u8	MaxFsFilesReservedForSysFiles
_u32	NumOfAlerts
_u32	NumOfAlertsThreshold
_u8	Padding
_u16	Padding2
_u8	Reserved

struct SlFsControlGetStorageInfoResponse_t

Definition at line 252 of file fs.h.

Data Fields
SlFsControlDeviceUsage_t	DeviceUsage
SlFsControlFilesUsage_t	FilesUsage

struct SlFsControlGetCountersResponse_t

Definition at line 259 of file fs.h.

Data Fields
_u8	ClosedFilesCnt
_u8	ClosedFilesCntWithValidFailSafeImage
_u32	IncludeFilters
_u8	OpenedForWriteCnt
_u8	OpenedForWriteCntWithValidFailSafeImage
_u8	OpeneForReadCnt
_u8	OpeneForReadCntWithValidFailSafeImage
_u8	padding[2]

struct SlFileAttributes_t

Definition at line 285 of file fs.h.

Data Fields
_u32	FileAllocatedBlocks
_u32	FileMaxSize
_u32	Properties