450 lines
16 KiB
C
450 lines
16 KiB
C
/*************************************************************************************************/
|
|
/*!
|
|
* \file wsf_efs.h
|
|
*
|
|
* \brief Embedded File System service.
|
|
*
|
|
* $Date: 2017-03-09 12:18:38 -0600 (Thu, 09 Mar 2017) $
|
|
* $Revision: 11460 $
|
|
*
|
|
* Copyright (c) 2014-2017 ARM Ltd., all rights reserved.
|
|
* ARM Ltd. confidential and proprietary.
|
|
*
|
|
* IMPORTANT. Your use of this file is governed by a Software License Agreement
|
|
* ("Agreement") that must be accepted in order to download or otherwise receive a
|
|
* copy of this file. You may not use or copy this file for any purpose other than
|
|
* as described in the Agreement. If you do not agree to all of the terms of the
|
|
* Agreement do not use this file and delete all copies in your possession or control;
|
|
* if you do not have a copy of the Agreement, you must contact ARM Ltd. prior
|
|
* to any use, copying or further distribution of this software.
|
|
*/
|
|
/*************************************************************************************************/
|
|
|
|
#ifndef WSF_EFS_H
|
|
#define WSF_EFS_H
|
|
|
|
#ifdef __cplusplus
|
|
extern "C" {
|
|
#endif
|
|
|
|
/**************************************************************************************************
|
|
Macros
|
|
**************************************************************************************************/
|
|
|
|
/* Max Number of Files and Media */
|
|
#ifndef WSF_EFS_MAX_FILES
|
|
#define WSF_EFS_MAX_FILES 6
|
|
#endif
|
|
|
|
/* Max Number of Media */
|
|
#ifndef WSF_EFS_MAX_MEDIA
|
|
#define WSF_EFS_MAX_MEDIA 4
|
|
#endif
|
|
|
|
/* Status codes */
|
|
#define WSF_EFS_SUCCESS 0 /*! Success */
|
|
#define WSF_EFS_FAILURE 1 /*! Failure */
|
|
#define WSF_EFS_GET_FAILED 0xFFFF /*! Get operation failure */
|
|
#define WSF_EFS_PUT_FAILED 0xFFFF /*! PUT operation failure */
|
|
|
|
/* Invalid parameter Identifiers */
|
|
#define WSF_EFS_INVALID_HANDLE 0xFFFF /*! Invalid Handle */
|
|
#define WSF_EFS_INVALID_OFFSET 0xFFFFFFFF /*! Invalid Offset */
|
|
#define WSF_EFS_INVALID_SIZE 0xFFFFFFFF /*! Invalid Size */
|
|
#define WSF_EFS_INVALID_MEDIA 0xFF /*! Invalid Media */
|
|
|
|
/* File Types */
|
|
#define WSF_EFS_FILE_TYPE_BULK 0 /*! Bulk File Type */
|
|
#define WSF_EFS_FILE_TYPE_STREAM 1 /*! Stream File Type */
|
|
|
|
/* Offset to WsfEfsAddFile indicating any file offset can be used */
|
|
#define WSF_EFS_FILE_OFFSET_ANY 0xFFFFFFFF
|
|
|
|
/* File Permissions */
|
|
#define WSF_EFS_REMOTE_PERMISSIONS_MASK 0xFF /*! Remote Permissions */
|
|
#define WSF_EFS_REMOTE_GET_PERMITTED 0x01 /*! Remote Get Permitted */
|
|
#define WSF_EFS_REMOTE_PUT_PERMITTED 0x02 /*! Remote Put Permitted */
|
|
#define WSF_EFS_REMOTE_ERASE_PERMITTED 0x04 /*! Remote Erase Permitted */
|
|
#define WSF_EFS_REMOTE_VERIFY_PERMITTED 0x08 /*! Remote Verify Permitted */
|
|
#define WSF_EFS_LOCAL_GET_PERMITTED 0x0100 /*! Local Get Permitted */
|
|
#define WSF_EFS_LOCAL_PUT_PERMITTED 0x0200 /*! Local Put Permitted */
|
|
#define WSF_EFS_LOCAL_ERASE_PERMITTED 0x0400 /*! Local Erase Permitted */
|
|
#define WSF_EFS_REMOTE_VISIBLE 0x0800 /*! File Visible via Remote WDXS */
|
|
|
|
/* File name length in bytes */
|
|
#define WSF_EFS_NAME_LEN 16
|
|
|
|
/* File version length in bytes */
|
|
#define WSF_EFS_VERSION_LEN 16
|
|
|
|
/* Standard Media Specific Command Identifiers */
|
|
#define WSF_EFS_WDXS_PUT_COMPLETE_CMD 0x00 /*! Put Complete */
|
|
#define WSF_EFS_VALIDATE_CMD 0x01 /*! Validate Req for the file */
|
|
|
|
/* Media Specific Command Identifiers reserved for applications begin at 0x80 */
|
|
#define WSF_EFS_USER_CMD 0x80
|
|
|
|
/**************************************************************************************************
|
|
Data Types
|
|
**************************************************************************************************/
|
|
|
|
/* File handle data type */
|
|
typedef uint16_t wsfEfsHandle_t;
|
|
|
|
/* File attributes data type */
|
|
typedef struct
|
|
{
|
|
char name[WSF_EFS_NAME_LEN];
|
|
char version[WSF_EFS_VERSION_LEN];
|
|
uint16_t permissions;
|
|
uint8_t type;
|
|
} wsfEsfAttributes_t;
|
|
|
|
/* File control block data type */
|
|
typedef struct
|
|
{
|
|
uint32_t maxSize;
|
|
uint32_t address;
|
|
uint8_t media;
|
|
uint32_t size;
|
|
wsfEsfAttributes_t attributes;
|
|
} wsfEfsControl_t;
|
|
|
|
/* File Listing Information */
|
|
typedef struct
|
|
{
|
|
wsfEfsHandle_t handle;
|
|
uint32_t size;
|
|
wsfEsfAttributes_t attributes;
|
|
} wsfEfsFileInfo_t;
|
|
|
|
/*************************************************************************************************/
|
|
/*!
|
|
* \fn wsfMediaInitFunc_t
|
|
*
|
|
* \brief Media Init function, called when media is registered.
|
|
*
|
|
* \param none.
|
|
*
|
|
* \return Status of the operation.
|
|
*/
|
|
/*************************************************************************************************/
|
|
typedef uint8_t wsfMediaInitFunc_t(void);
|
|
|
|
/*************************************************************************************************/
|
|
/*!
|
|
* \fn wsfMediaEraseFunc_t
|
|
*
|
|
* \brief Media Erase function.
|
|
*
|
|
* \param address Address in media to start erasing.
|
|
* \param size Number of bytes to erase.
|
|
*
|
|
* \return Status of the operation.
|
|
*/
|
|
/*************************************************************************************************/
|
|
typedef uint8_t wsfMediaEraseFunc_t(uint32_t address, uint32_t size);
|
|
|
|
/*************************************************************************************************/
|
|
/*!
|
|
* \fn wsfMediaReadFunc_t
|
|
*
|
|
* \brief Media Read function.
|
|
*
|
|
* \param pBuf Buffer to hold data.
|
|
* \param address Address in media to read from.
|
|
* \param size Size of pBuf in bytes.
|
|
*
|
|
* \return Status of the operation.
|
|
*/
|
|
/*************************************************************************************************/
|
|
typedef uint8_t wsfMediaReadFunc_t(uint8_t *pBuf, uint32_t address, uint32_t size);
|
|
|
|
/*************************************************************************************************/
|
|
/*!
|
|
* \fn wsfMediaWriteFunc_t
|
|
*
|
|
* \brief Media Write function.
|
|
*
|
|
* \param pBuf Buffer with data to be written.
|
|
* \param address Address in media to write to.
|
|
* \param size Size of pBuf in bytes.
|
|
*
|
|
* \return Status of the operation.
|
|
*/
|
|
/*************************************************************************************************/
|
|
typedef uint8_t wsfMediaWriteFunc_t(const uint8_t *pBuf, uint32_t address, uint32_t size);
|
|
|
|
/*************************************************************************************************/
|
|
/*!
|
|
* \fn wsfMediaHandleCmdFunc_t
|
|
*
|
|
* \brief Media Specific Command handler.
|
|
*
|
|
* \param cmd Identifier of the media specific command.
|
|
* \param param Optional Parameter to the command.
|
|
*
|
|
* \return Status of the operation.
|
|
*/
|
|
/*************************************************************************************************/
|
|
typedef uint8_t wsfMediaHandleCmdFunc_t(uint8_t cmd, uint32_t param);
|
|
|
|
/* Media Control data type */
|
|
typedef struct
|
|
{
|
|
uint32_t startAddress;
|
|
uint32_t endAddress;
|
|
uint32_t pageSize;
|
|
wsfMediaInitFunc_t *init;
|
|
wsfMediaEraseFunc_t *erase;
|
|
wsfMediaReadFunc_t *read;
|
|
wsfMediaWriteFunc_t *write;
|
|
wsfMediaHandleCmdFunc_t *handleCmd;
|
|
} wsfEfsMedia_t;
|
|
|
|
/* Pointer to Media Control data type */
|
|
typedef const wsfEfsMedia_t *pWsfEfsMedia_t;
|
|
|
|
/**************************************************************************************************
|
|
Function Declarations
|
|
**************************************************************************************************/
|
|
|
|
/*************************************************************************************************/
|
|
/*!
|
|
* \fn WsfEfsInit
|
|
*
|
|
* \brief Initialise the embedded file system.
|
|
*
|
|
* \return none.
|
|
*/
|
|
/*************************************************************************************************/
|
|
void WsfEfsInit(void);
|
|
|
|
/*************************************************************************************************/
|
|
/*!
|
|
* \fn WsfEfsAddFile
|
|
*
|
|
* \brief Create a file in the embedded file system.
|
|
*
|
|
* \param maxSize Max length in bytes of of the file.
|
|
* \param media Identifier of the media where the file is stored.
|
|
* \param pAttr Attributes of the file
|
|
* \param offset Offset address of the file in the memory space.
|
|
*
|
|
* \return File Handle, or WSF_EFS_INVALID_HANDLE.
|
|
*/
|
|
/*************************************************************************************************/
|
|
wsfEfsHandle_t WsfEfsAddFile(uint32_t maxSize, uint8_t media, wsfEsfAttributes_t *pAttr, uint32_t offset);
|
|
|
|
/*************************************************************************************************/
|
|
/*!
|
|
* \fn WsfEfsRemoveFile
|
|
*
|
|
* \brief Deletes a file in the embedded file system.
|
|
*
|
|
* \param handle Handle identifying the file.
|
|
*
|
|
* \return WSF_EFS_SUCCESS or WSF_EFS_FAILURE.
|
|
*/
|
|
/*************************************************************************************************/
|
|
uint8_t WsfEfsRemoveFile(wsfEfsHandle_t handle);
|
|
|
|
/*************************************************************************************************/
|
|
/*!
|
|
* \fn WsfEfsErase
|
|
*
|
|
* \brief Clears the contents of a file without deleting the file.
|
|
*
|
|
* \param handle Handle identifying the file.
|
|
*
|
|
* \return WSF_EFS_SUCCESS or WSF_EFS_FAILURE.
|
|
*/
|
|
/*************************************************************************************************/
|
|
uint8_t WsfEfsErase(wsfEfsHandle_t handle);
|
|
|
|
/*************************************************************************************************/
|
|
/*!
|
|
* \fn WsfEfsGetAttributes
|
|
*
|
|
* \brief Gets the attributes of a file.
|
|
*
|
|
* \param handle Handle identifying the file.
|
|
* \param pAttr Pointer to memory to store the attributes.
|
|
*
|
|
* \return WSF_EFS_SUCCESS or WSF_EFS_FAILURE.
|
|
*/
|
|
/*************************************************************************************************/
|
|
uint8_t WsfEfsGetAttributes(wsfEfsHandle_t handle, wsfEsfAttributes_t *pAttr);
|
|
|
|
/*************************************************************************************************/
|
|
/*!
|
|
* \fn WsfEfsSetAttributes
|
|
*
|
|
* \brief Updates the attributes of a file.
|
|
*
|
|
* \param handle Handle identifying the file.
|
|
* \param pAttr Pointer to memory to with the updated attributes.
|
|
*
|
|
* \return WSF_EFS_SUCCESS or WSF_EFS_FAILURE.
|
|
*/
|
|
/*************************************************************************************************/
|
|
uint8_t WsfEfsSetAttributes(wsfEfsHandle_t handle, wsfEsfAttributes_t *pInfo);
|
|
|
|
/*************************************************************************************************/
|
|
/*!
|
|
* \fn WsfEfsGet
|
|
*
|
|
* \brief Copies data from a file.
|
|
*
|
|
* \param handle Handle identifying the file.
|
|
* \param offset Offset into the file to begin copying from.
|
|
* \param pBuffer Location to copy the data to.
|
|
* \param len Number of bytes to copy into pBuffer.
|
|
*
|
|
* \return The number of bytes read from the file
|
|
*/
|
|
/*************************************************************************************************/
|
|
uint16_t WsfEfsGet(wsfEfsHandle_t handle, uint32_t offset, uint8_t *pBuffer, uint16_t len);
|
|
|
|
/*************************************************************************************************/
|
|
/*!
|
|
* \fn WsfEfsPut
|
|
*
|
|
* \brief Writes data to a file.
|
|
*
|
|
* \param handle Handle identifying the file.
|
|
* \param offset Offset into the file to begin writing to.
|
|
* \param pBuffer Data to write to the file.
|
|
* \param len Number of bytes to write to the file.
|
|
*
|
|
* \return The number of bytes written to the file
|
|
*/
|
|
/*************************************************************************************************/
|
|
uint16_t WsfEfsPut(wsfEfsHandle_t handle, uint32_t offset, const uint8_t *pBuffer, uint16_t len);
|
|
|
|
/*************************************************************************************************/
|
|
/*!
|
|
* \fn WsfEfsRegisterMedia
|
|
*
|
|
* \brief Registers a File Storage Medium with the Embedded File System.
|
|
*
|
|
* \param pMedia Pointer to the media control structure.
|
|
* \param mediaID User specified identifier of the media.
|
|
*
|
|
* \return WSF_EFS_SUCCESS or WSF_EFS_FAILURE.
|
|
*/
|
|
/*************************************************************************************************/
|
|
uint8_t WsfEfsRegisterMedia(const wsfEfsMedia_t *pMediaCtrl, uint8_t mediaID);
|
|
|
|
/*************************************************************************************************/
|
|
/*!
|
|
* \fn wsfEfsGetFileByHandle
|
|
*
|
|
* \brief Returns the file control block for the given handle.
|
|
*
|
|
* \param handle Handle of the file
|
|
*
|
|
* \return File control block, or NULL.
|
|
*/
|
|
/*************************************************************************************************/
|
|
wsfEfsControl_t *WsfEfsGetFileByHandle(wsfEfsHandle_t handle);
|
|
|
|
/*************************************************************************************************/
|
|
/*!
|
|
* \fn WsfEfsGetFileName
|
|
*
|
|
* \brief Get the name of a file.
|
|
*
|
|
* \param handle File Handle.
|
|
*
|
|
* \return Filename string of a file.
|
|
*/
|
|
/*************************************************************************************************/
|
|
char *WsfEfsGetFileName(wsfEfsHandle_t handle);
|
|
|
|
/*************************************************************************************************/
|
|
/*!
|
|
* \fn WsfEfsGetFileVersion
|
|
*
|
|
* \brief Get the version of a file.
|
|
*
|
|
* \param handle File Handle.
|
|
*
|
|
* \return Version string of a file.
|
|
*/
|
|
/*************************************************************************************************/
|
|
char *WsfEfsGetFileVersion(wsfEfsHandle_t handle);
|
|
|
|
/*************************************************************************************************/
|
|
/*!
|
|
* \fn WsfEfsGetFileSize
|
|
*
|
|
* \brief Get the size of a file.
|
|
*
|
|
* \param handle File Handle.
|
|
*
|
|
* \return Size of the file.
|
|
*/
|
|
/*************************************************************************************************/
|
|
uint32_t WsfEfsGetFileSize(wsfEfsHandle_t handle);
|
|
|
|
/*************************************************************************************************/
|
|
/*!
|
|
* \fn WsfEfsGetFileMaxSize
|
|
*
|
|
* \brief Get the number of bytes of memory reserved for use by a file.
|
|
*
|
|
* \param handle File Handle.
|
|
*
|
|
* \return Max size of the file.
|
|
*/
|
|
/*************************************************************************************************/
|
|
uint32_t WsfEfsGetFileMaxSize(wsfEfsHandle_t handle);
|
|
|
|
/*************************************************************************************************/
|
|
/*!
|
|
* \fn WsfEfsGetFileType
|
|
*
|
|
* \brief Get the type of a file.
|
|
*
|
|
* \param handle File Handle.
|
|
*
|
|
* \return Type of file (bulk or stream).
|
|
*/
|
|
/*************************************************************************************************/
|
|
uint8_t WsfEfsGetFileType(wsfEfsHandle_t handle);
|
|
|
|
/*************************************************************************************************/
|
|
/*!
|
|
* \fn WsfEfsGetFilePermissions
|
|
*
|
|
* \brief Get the permissions of a file.
|
|
*
|
|
* \param handle File Handle.
|
|
*
|
|
* \return Permissions of the file.
|
|
*/
|
|
/*************************************************************************************************/
|
|
uint16_t WsfEfsGetFilePermissions(wsfEfsHandle_t handle);
|
|
|
|
/*************************************************************************************************/
|
|
/*!
|
|
* \fn WsfEfsMediaSpecificCommand
|
|
*
|
|
* \brief Execute a media specific command on a file.
|
|
*
|
|
* \param handle File Handle.
|
|
* \param cmd Media specific command identifier.
|
|
* \param param Command specific parameter.
|
|
*
|
|
* \return Status of the operation.
|
|
*/
|
|
/*************************************************************************************************/
|
|
uint8_t WsfEfsMediaSpecificCommand(wsfEfsHandle_t handle, uint8_t cmd, uint32_t param);
|
|
|
|
#ifdef __cplusplus
|
|
}
|
|
#endif
|
|
|
|
#endif /* WSF_EFS_H */
|