rt-thread/bsp/imx6sx/iMX6_Platform_SDK/sdk/common/filesystem/fsapi.h

/*
 * Copyright (c) 2012, Freescale Semiconductor, Inc.
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without modification,
 * are permitted provided that the following conditions are met:
 *
 * o Redistributions of source code must retain the above copyright notice, this list
 *   of conditions and the following disclaimer.
 *
 * o Redistributions in binary form must reproduce the above copyright notice, this
 *   list of conditions and the following disclaimer in the documentation and/or
 *   other materials provided with the distribution.
 *
 * o Neither the name of Freescale Semiconductor, Inc. nor the names of its
 *   contributors may be used to endorse or promote products derived from this
 *   software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
 * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
 * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
 * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */
////////////////////////////////////////////////////////////////////////////////
//! \addtogroup os_fat
//! @{
//!
//  Copyright (c) 2005-2008 SigmaTel, Inc.
//!
//! \file    fsapi.h
//! \brief   Contains the FAT file system public API. Supports FAT32 and FAT16.
//!
////////////////////////////////////////////////////////////////////////////////
#ifndef _FS_API_H
#define _FS_API_H

////////////////////////////////////////////////////////////////////////////////
// Includes
////////////////////////////////////////////////////////////////////////////////

#include "sdk.h"
#include "os_filesystem_errordefs.h"

////////////////////////////////////////////////////////////////////////////////
// Definitions
////////////////////////////////////////////////////////////////////////////////

#define FS_USE_MALLOC 1

#define SEEK_SET           	0
#define SEEK_CUR            1
#define SEEK_END            2

#define INVALID_FILESYSTEM	      (WORD)(3)

#ifndef MAX_FILENAME_LENGTH
#define MAX_FILENAME_LENGTH 256
#endif

#define ATTR_READ_ONLY      0x01
#define ATTR_HIDDEN         0x02
#define ATTR_SYSTEM         0x04
#define ATTR_VOLUME_ID      0x08
#define ATTR_DIRECTORY      0x10
#define ATTR_ARCHIVE        0x20
#define ATTR_LONG_NAME      (ATTR_READ_ONLY|ATTR_HIDDEN|ATTR_SYSTEM|ATTR_VOLUME_ID)
#define MAX_FILESNAME   13

typedef struct _FindData {
    uint8_t attrib;
    int32_t FileSize;
    uint8_t device;
    uint32_t startrecord;
    uint8_t name[MAX_FILESNAME];
    int64_t Key;
} FindData_t;

typedef struct {
    uint8_t Day;
    uint8_t Month;
    int16_t Year;
} DIR_DATE;

typedef struct {
    uint8_t Second;
    uint8_t Minute;
    uint8_t Hour;
} DIR_TIME;

// Use for 'crt_mod_date_time_para' parameter
#define CREATION_DATE       1
#define CREATION_TIME       2
#define MODIFICATION_DATE   3
#define MODIFICATION_TIME   4

// Use for 'dirattribute' parameter
#define READ_ONLY           0X01
#define HIDDEN              0X02
#define SYSTEM              0X04
#define VOLUME_ID           0X08
#define DIRECTORY           0X10
#define ARCHIVE             0X20

#define MAX_UNICODE_SIZE 512

////////////////////////////////////////////////////////////////////////////////
// Externs
////////////////////////////////////////////////////////////////////////////////

//! \brief Maximum number of drives supported by the file system. 
//! 
//! Typically, \c maxdevices is 2.
extern const int32_t maxdevices;

//! \brief Maximum number of handles available in the file system.
//! 
//! The number of handles available to the user is maxhandles - 2. 
//! Two handles are reserved by the file system for internal use only. 
//! The number of handles decides the number of files, which can 
//! simultaneously be open. Typically, \c maxhandles is 16.
extern const int32_t maxhandles;

//! \brief Total number of cache buffers. 
//! 
//! Increasing the number of cache buffers improves the performance of 
//! the file system when several threads are accessing the file system. 
//! Typically, \c maxcaches is 8.
extern const int32_t maxcaches;

//! \brief Assigns a drive letter to a drive.
//! 
//! For example, in the following sample code, \n
//!
//! \c A is assigned to drive 0,\n
//! \c B is assigned to drive 1, and \n
//! \c C is assigned to drive 2.
//! \code
//! int32_t DriveLetter[] = {'A','B','C'};
//! \endcode
extern const uint8_t DriveLetter[];

// The cache buffers are allocated in the X buffer.
//extern BYTE bufx[NUMCACHES*CACHEBUFSIZE];
#ifndef _WIN32
//#pragma alignvar(32)
__attribute__ ((aligned(32)))
#endif
//! \brief X memory buffer.
extern uint8_t bufx[];

#ifndef _WIN32
//#pragma alignvar(4)
__attribute__ ((aligned(4)))
#endif
//! \brief Y memory buffer.
extern uint8_t bufy[];

////////////////////////////////////////////////////////////////////////////////
// API
////////////////////////////////////////////////////////////////////////////////

#if defined(__cplusplus)
extern "C" {
#endif                          // __cplusplus

///////////////////////////////////////////////////////////////////////////////
//! \brief Redirects an Fclose request
//!                  
//! \fntype Function                  
//!                  
//! Redirects an Fclose request to the appropriate handler based on the
//! specified file handle.
//!                  
//! \param[in]  handleNumber Handle of the file to close
//!         
//! \return Value of the steering function or an error.
//! \retval ERROR_OS_FILESYSTEM_NO_STEERING_FUNCTION If there is no steering function defined for \c filehandle
//!
//! \internal
//! \see To view the function definition, see fs_steering.c.
///////////////////////////////////////////////////////////////////////////////
    RtStatus_t Fclose(int32_t handleNumber);

///////////////////////////////////////////////////////////////////////////////
//! \brief Redirects an Fread request
//!                  
//! \fntype Function                  
//!                  
//! Redirects an Fread request to the appropriate handler based on the
//! specified file handle.
//!                  
//! \param[in]  handleNumber   Handle of the file to read from
//! \param[out] pBuffer        Buffer in which the data to be read is placed
//! \param[in]  numBytesToRead Number of bytes to read from the file
//!                  
//! \return Number of bytes read if the steering function was successful or an RtStatus_t error.
//! \retval ERROR_OS_FILESYSTEM_NO_STEERING_FUNCTION If there is no steering function defined for \c filehandle
//!
//! \internal
//! \see To view the function definition, see fs_steering.c.
///////////////////////////////////////////////////////////////////////////////
    int32_t Fread(int32_t handleNumber, uint8_t * pBuffer, int32_t numBytesToRead);

///////////////////////////////////////////////////////////////////////////////
//! \brief Redirects an Fwrite request
//!                  
//! \fntype Function                  
//!                  
//! Redirects an Fwrite request to the appropriate handler based on the
//! specified file handle.
//!                  
//! \param[in]  handleNumber   Handle of the file to write to
//! \param[in]  pBuffer        Buffer holding the data to be written
//! \param[in]  numBytesToWrite Number of bytes to write to the file
//!                  
//! \return Number of bytes read if the steering function was successful or an RtStatus_t error.
//! \retval ERROR_OS_FILESYSTEM_NO_STEERING_FUNCTION If there is no steering function defined for \c filehandle
//!
//! \internal
//! \see To view the function definition, see fs_steering.c.
///////////////////////////////////////////////////////////////////////////////
    int32_t Fwrite(int32_t handleNumber, uint8_t * pBuffer, int32_t numBytesToWrite);

///////////////////////////////////////////////////////////////////////////////
//! \brief Redirects an Fseek request
//!                  
//! \fntype Function                  
//!                  
//! Redirects an Fseek request to the appropriate handler based on the
//! specified file handle.
//!                  
//! \param[in]  handleNumber   Handle of the file to seek
//! \param[in]  numBytesToSeek Relative number of bytes to seek
//! \param[in]  seekPosition   Value indicating where to seek from
//!                  
//! \retval ERROR_OS_FILESYSTEM_NO_STEERING_FUNCTION If there is no steering function defined for \c filehandle
//! \retval RtStatus_t The return value of the steering function
//! \internal
//! \see To view the function definition, see fs_steering.c.
///////////////////////////////////////////////////////////////////////////////
    RtStatus_t Fseek(int32_t handleNumber, int32_t numBytesToSeek, int32_t seekPosition);

////////////////////////////////////////////////////////////////////////////////
//!
//! \brief Fopen Opens a file for subsequent access.
//!
//! \param[in] filepath Pointer to a null-terminated ASCII string that contains the name of the file to open.
//!
//! \param[in] mode Null-terminated ASCII string that specifies how the file will be accessed. It must be one of the following:
//!
//!     -   "r"     =   open for reading only
//!     -   "r+"        =   same as "r", also allows writing
//!     -   "w"     =   open for writing only, file will be created if it does 
//!                     not exist, and will be overwritten if it does exist
//!     -   "w+"        =   same as "w", also allows reading
//!     -   "a"     =   open for appending to end of file, upon opening
//!                     file position is set to end-of-file
//!     -   "a+"        =   same as "a", also allows reading/writing
//!
//!
//!  \param[out] handle Returns an int32_t which uniquely identifies the file while it is open, and which must be
//!  used on all subsequent file system calls to access this file If this value is negative, then an error occurred.
//!
//!
//!  Long file name considerations
//!
//!    
//!  When creating a file (opening it with either "w" or "w+" modes) the
//!  FAT file system uses the following considerations to determine whether
//!  the file name will be stored on the media with a short name only (older
//!  style) or with both a short name and a long name.
//!
//! -   The file name is parsed into 2 parts, the part before the period (filespec) and the part after (extension)
//!
//! -   If more than one period is found during parsing, a long file name is created.
//!
//! -   If the filespec is more than 11 characters long a long file name is created.
//!
//! -   If the extension is more than 3 characters long a long file name is created
//!
//! -   If the filespec or the extension contains a space character or any one of +,;=[](plus-sign,comma,semi-colon,
//!     equal-sign,open-brace,close-brace) then a long file name is created.
//!
//! -   If a long file name is not used, the filepec and extension are converted 
//!     to upper case, and the resulting short file name is created.
//!
//!
//!  \internal
//!
//!   All of the checking listed above actually takes place in
//!   the function 'IsShortNameValid()' (which is in 'isshortnamevalid.c')
//!
///////////////////////////////////////////////////////////////////////////////
    RtStatus_t Fopen(uint8_t * filepath, uint8_t * mode);

///////////////////////////////////////////////////////////////////////////////
//!
//! \brief Fopenw Opens a file for subsequent access.
//!
//! \param[in] filepath Pointer to a null-terminated UNICODE string that contains the name of the file to open.
//!
//! \param[in] mode Null-terminated ASCII string that specifies how the file will be accessed. It must be one of the following:
//!
//!     -   "r"     =   open for reading only
//!     -   "r+"        =   same as "r", also allows writing
//!     -   "w"     =   open for writing only, file will be created if it does 
//!                     not exist, and will be overwritten if it does exist
//!     -   "w+"        =   same as "w", also allows reading
//!     -   "a"     =   open for appending to end of file, upon opening
//!                     file position is set to end-of-file
//!     -   "a+"        =   same as "a", also allows reading/writing
//!
//!
//!  \param[out] handle Returns an int32_t which uniquely identifies the file while it is open, and which must be
//!  used on all subsequent file system calls to access this file If this value is negative, then an error occurred.
//!
//!
//!  Long file name considerations
//!
//!  Since the input filepath is in UNICODE, this function ALWAYS creates a long file name
//!
    RtStatus_t Fopenw(uint8_t * filepath, uint8_t * mode);

    RtStatus_t Fclose_FAT(int32_t HandleNumber);
    RtStatus_t Fgetc(int32_t HandleNumber);
    RtStatus_t Fputc(int32_t HandleNumber, int32_t ByteToWrite);
    uint8_t *Fgets(int32_t HandleNumber, int32_t NumBytes, uint8_t * Buffer);
    uint8_t *Fputs(int32_t HandleNumber, uint8_t * Buffer);
    RtStatus_t Fread_FAT(int32_t HandleNumber, uint8_t * Buffer, int32_t NumBytesToRead);
    RtStatus_t Fwrite_FAT(int32_t HandleNumber, uint8_t * Buffer, int32_t NumBytesToWrite);
    int32_t Feof(int32_t HandleNumber);
    int32_t Ftell(int32_t HandleNumber);
    int32_t Ferror(int32_t HandleNumber);
    RtStatus_t Fseek_FAT(int32_t HandleNumber, int32_t NumBytesToSeek, int32_t SeekPosition);
    RtStatus_t Fflush(int32_t HandleNumber);
    RtStatus_t Fremove(const uint8_t * filepath);
    RtStatus_t Fremovew(uint8_t * filepath);

////////////////////////////////////////////////////////////////////////////////
// Miscellaneous File System Prototypes
////////////////////////////////////////////////////////////////////////////////

///////////////////////////////////////////////////////////////////////////////
//! \brief Initializes the file system.
//!
//! \param[in] bufx       Pointer to X buffer for allocation of cache buffers.
//! \param[in] bufy       Pointer to Y buffer for allocation of handles, descriptors, etc.
//! \param[in] maxdevices Max number of internal + external media supported.
//! \param[in] maxhandles Max handles supported.
//! \param[in] maxcaches  Max cache buffers supported.
//!
//! \return Status of the call.
//! \retval 0 If the call was successful.
///////////////////////////////////////////////////////////////////////////////
    RtStatus_t FSInit(uint8_t * bufx, uint8_t * bufy, int32_t maxdevices, int32_t maxhandles,
                      int32_t maxcaches);

    int32_t FSDriveInit(int32_t DeviceNumber);
    int32_t FSDriveShutdown(int32_t DeviceNumber);

///////////////////////////////////////////////////////////////////////////////
//! \brief Determines free space by reading the all records 
//!
//! \return Status of the call.
//! \retval 0 If successful.
///////////////////////////////////////////////////////////////////////////////
    RtStatus_t FSShutdown(void);

///////////////////////////////////////////////////////////////////////////////
//! \brief Determines total free clusters by first checking FAT type.
//!
//! \param[in] DeviceNumber Device number.
//!
//! \return Returns total number of free clusters.
///////////////////////////////////////////////////////////////////////////////
    int32_t Computefreecluster(int32_t DeviceNumber);

///////////////////////////////////////////////////////////////////////////////
//! \brief Gets the size of the file.
//!
//! \param[in] HandleNumber File handle.
//!
//! \return Status of the call.
//! \retval 0 If the call was successful.
//! \retval error If an error occurred.
///////////////////////////////////////////////////////////////////////////////
    RtStatus_t GetFileSize(int32_t HandleNumber);

///////////////////////////////////////////////////////////////////////////////
//! \brief Flushes only the dirty cache buffers that contain valid
//!        data to the disk, but invalidates all cache entries.
//!
//! \return Status of the call.
///////////////////////////////////////////////////////////////////////////////
    RtStatus_t FlushCache(void);

///////////////////////////////////////////////////////////////////////////////
//! \brief For device "deviceNumber", flushes only the dirty cache buffers that contain valid
//!        data to the disk, and invalidates their cache entries.
///////////////////////////////////////////////////////////////////////////////
    int32_t FSFlushDriveCache(int32_t deviceNumber);    //The real code calls for RtStatus_t

///////////////////////////////////////////////////////////////////////////////
//! \brief Returns FAT type.
//!
//! \param[in] DeviceNum
///////////////////////////////////////////////////////////////////////////////
    int32_t FSFATType(int32_t DeviceNum);

///////////////////////////////////////////////////////////////////////////////
//! \brief Returns a value that indicates whether the specified device is present.
//!
//! \param[in] DeviceNum Device number of the specified device.
//!
//! \return A value that indicates whether the device is present.
///////////////////////////////////////////////////////////////////////////////
    int32_t FSMediaPresent(int32_t DeviceNum);

    int32_t FSFreeClusters(int32_t Device);
    int64_t FSFreeSpace(int32_t Device);
    int64_t FSFreeSpaceFromHandle(int32_t HandleNumber);
    int32_t FSSize(int32_t DeviceNum);

////////////////////////////////////////////////////////////////////////////////
// Directory API
////////////////////////////////////////////////////////////////////////////////

///////////////////////////////////////////////////////////////////////////////
//! \brief Searches for the given directoy path and if the path is found 
//!        then changes the current working directoy to the given directory path.
//!
//! \param[in] filepath Pointer to file name.
//!
//! \return Status of the call.
//! \retval SUCCESS
//! \retval Error If error occurs.
///////////////////////////////////////////////////////////////////////////////
    RtStatus_t Chdir(uint8_t * filepath);

///////////////////////////////////////////////////////////////////////////////
//! \brief Searches for the given directoy path for UNICODE string and if the path is found 
//!        then changes the current working directoy to the given directory path.
//!
//! \param[in] filepath Pointer to the file name.
//!
//! \return Status of the call.
//! \retval SUCCESS
//! \retval Error If error occurs.
///////////////////////////////////////////////////////////////////////////////
    RtStatus_t Chdirw(uint8_t * filepath);

    RtStatus_t Mkdir(uint8_t * filepath);
    RtStatus_t Mkdirw(uint8_t * filepath);

///////////////////////////////////////////////////////////////////////////////
//! \brief Searches for the given directory, and if it is found, empties and 
//!        deletes the directory.
//!
//! \param[in] filepath Pointer to the file name.
//!
//! \return Status of the call.
//! \retval FS_SUCCESS If call was successful.
//! \retval Error      If error occurs.
///////////////////////////////////////////////////////////////////////////////
    RtStatus_t Rmdir(uint8_t * filepath);

///////////////////////////////////////////////////////////////////////////////
//! \brief Searches for the given directory, and if it is found, empties and 
//!        deletes the directory. 
//!
//! \param[in] filepath Pointer to the file name.
//!
//! \return Status of the call.
//! \retval FS_SUCCESS If call was successful.
//! \retval Error      If error occurs.
//!
//! \note This function considers the string to be Unicode.
///////////////////////////////////////////////////////////////////////////////
    RtStatus_t Rmdirw(uint8_t * filepath);

///////////////////////////////////////////////////////////////////////////////
//! \brief Deletes all the files and directories of the specified path.
//!
//! \param[in] Path Pointer to the directory path.
//!
//! \return Status of the call.
//! \retval 0     If the call was successful.
//! \retval Error If an error occurs.
///////////////////////////////////////////////////////////////////////////////
    int32_t DeleteTree(uint8_t * Path);

    int32_t Frename(uint8_t * oldFilename, uint8_t * newFilename);

///////////////////////////////////////////////////////////////////////////////
//! \brief Returns the pointer to the \c gCurrentWorkingdirectory string buffer.
//!
//! \return Pointer to current working directory buffer.
///////////////////////////////////////////////////////////////////////////////
    uint8_t *Getcwd(void);

///////////////////////////////////////////////////////////////////////////////
//! \brief TBD
//!
//! \param[in] DeviceNo Device number to set the cwd handle to root dir of
//!
//! \retval 0 If successful
///////////////////////////////////////////////////////////////////////////////
    int32_t SetCWDHandle(int32_t DeviceNo);

////////////////////////////////////////////////////////////////////////////////
// Find file API
////////////////////////////////////////////////////////////////////////////////

///////////////////////////////////////////////////////////////////////////////
//! \brief Provides base, file name, and extension of the file to the FindNext() function.
//!
//! \param[in] _finddata File specification
//! \param[in] FileName  Pointer to the file name.
//!
//! \return Status of the call.
//! \retval 0 If successful.
//! \retval Error 
//!
//! \note This function should not be called from multiple tasks.
///////////////////////////////////////////////////////////////////////////////
    RtStatus_t FindFirstLFN(FindData_t * _finddata, uint8_t * FileName, void *);

    RtStatus_t FindFirst(FindData_t * _finddata, uint8_t * FileName);
    RtStatus_t FindNextLFN(int32_t HandleNumber, FindData_t * _finddata, void *);
    RtStatus_t FindNext(int32_t HandleNumber, FindData_t * _finddata);
    RtStatus_t FindClose(int32_t HandleNumber);

////////////////////////////////////////////////////////////////////////////////
// File attribute API
////////////////////////////////////////////////////////////////////////////////

///////////////////////////////////////////////////////////////////////////////
//! \brief Finds the creation or modification date or time of 
//!                  the file referenced by the given handle number.
//!
//! \param[in] HandleNumber           Handle number.
//! \param[in] crt_mod_date_time_para Create-modify-date-time parameter.
//! \param[in] dirdate                Pointer to the DIR_DATE structure.
//! \param[in] dirtime                Pointer to the DIR_TIME structure.
//!
//! \return Status of the call.
//! \retval 0 If successful.
//! \retval ERROR If an error occurs.
///////////////////////////////////////////////////////////////////////////////
    RtStatus_t filegetdate(int32_t HandleNumber, int32_t crt_mod_date_time_para, DIR_DATE * dirdate,
                           DIR_TIME * dirtime);

///////////////////////////////////////////////////////////////////////////////
//! \brief Sets the creation or modification date or time of 
//!                  the file referenced by the given handle to the specified date or time.
//!
//! \param[in] FilePath               Pointer to the file path.
//! \param[in] crt_mod_date_time_para Create-modify-date-time parameter.
//! \param[in] dirdate                Pointer to the DIR_DATE structure.
//! \param[in] dirtime                Pointer to the DIR_TIME structure.
//!
//! \return Status of the call.
//! \retval 0 If successful.
//! \retval Error 
///////////////////////////////////////////////////////////////////////////////
    RtStatus_t filesetdate(uint8_t * FilePath, int32_t crt_mod_date_time_para, DIR_DATE * dirdate,
                           DIR_TIME * dirtime);

///////////////////////////////////////////////////////////////////////////////
//! \brief Gets directory attributes for a file based on the file handle.
//!
//! \param[in] HandleNumber File Handle.
//!
//! \return Returns directory attributes for a file or an error Code if an error occurs.
///////////////////////////////////////////////////////////////////////////////
    RtStatus_t filegetattribhandle(int32_t HandleNumber);

///////////////////////////////////////////////////////////////////////////////
//! \brief Gets directory attributes for a file.
//!
//! \param[in] FilePath Pointer to the file path.
//!
//! \return Returns directory attributes for a file or an error Code if an error occurs.
///////////////////////////////////////////////////////////////////////////////
    RtStatus_t filegetattrib(uint8_t * FilePath);

///////////////////////////////////////////////////////////////////////////////
//! \brief Sets directory attributes for a file.
//!
//! \param[in] HandleNumber TBD
//! \param[in] dirattribute TBD
//!
//! \return Status of the call.
//! \retval SUCCESS If call was successful.
//! \retval ERROR   If an error occurs.
///////////////////////////////////////////////////////////////////////////////
    RtStatus_t filesetattrib(int32_t HandleNumber, int32_t dirattribute);

///////////////////////////////////////////////////////////////////////////////
//! \brief Provides long file name.
//!
//! \param[in] HandleNumber TBD
//! \param[in] RecordNumber TBD
//! \param[in] LFNBuffer    Pointer to the file name buffer.
//!
//! \return Returns length of the long file name string.
///////////////////////////////////////////////////////////////////////////////
    int32_t ConstructLongFileName(int32_t HandleNumber, int32_t RecordNumber, int8_t * LFNBuffer);

#if defined(__cplusplus)
}                               // extern "C"
#endif                          // __cplusplus
#endif                          //_FS_API_H
///////////////////////////////////////////////////////////////////////////////// End of file/////////////////////////////////////////////////////////////////////////////////! @}