From cae7420b4bd015b78f915c4ba766dbee15da0468 Mon Sep 17 00:00:00 2001 From: Dandan Bi Date: Fri, 9 Dec 2016 10:07:49 +0800 Subject: [PATCH] FatPkg/EnhancedFatDxe: Make the comments align with EDKIIcoding style Cc: Ruiyu Ni Contributed-under: TianoCore Contribution Agreement 1.0 Signed-off-by: Dandan Bi Reviewed-by: Ruiyu Ni --- FatPkg/EnhancedFatDxe/ComponentName.c | 10 +- FatPkg/EnhancedFatDxe/Data.c | 16 +- FatPkg/EnhancedFatDxe/Debug.c | 38 +- FatPkg/EnhancedFatDxe/Delete.c | 41 +- FatPkg/EnhancedFatDxe/DirectoryCache.c | 124 ++-- FatPkg/EnhancedFatDxe/DirectoryManage.c | 744 +++++++++-------------- FatPkg/EnhancedFatDxe/DiskCache.c | 261 ++++---- FatPkg/EnhancedFatDxe/Fat.c | 169 ++--- FatPkg/EnhancedFatDxe/Fat.h | 470 ++++++-------- FatPkg/EnhancedFatDxe/FatFileSystem.h | 15 +- FatPkg/EnhancedFatDxe/FileName.c | 276 +++------ FatPkg/EnhancedFatDxe/FileSpace.c | 342 ++++------- FatPkg/EnhancedFatDxe/Flush.c | 258 +++----- FatPkg/EnhancedFatDxe/Hash.c | 164 ++--- FatPkg/EnhancedFatDxe/Info.c | 324 ++++------ FatPkg/EnhancedFatDxe/Init.c | 103 ++-- FatPkg/EnhancedFatDxe/Misc.c | 414 +++++-------- FatPkg/EnhancedFatDxe/Open.c | 180 +++--- FatPkg/EnhancedFatDxe/OpenVolume.c | 46 +- FatPkg/EnhancedFatDxe/ReadWrite.c | 410 +++++-------- FatPkg/EnhancedFatDxe/UnicodeCollation.c | 6 +- 21 files changed, 1664 insertions(+), 2747 deletions(-) diff --git a/FatPkg/EnhancedFatDxe/ComponentName.c b/FatPkg/EnhancedFatDxe/ComponentName.c index af3f9e61f1..ce1c975b5f 100644 --- a/FatPkg/EnhancedFatDxe/ComponentName.c +++ b/FatPkg/EnhancedFatDxe/ComponentName.c @@ -1,4 +1,4 @@ -/*++ +/** @file Copyright (c) 2005 - 2011, Intel Corporation. All rights reserved.
This program and the accompanying materials are licensed and made available @@ -10,13 +10,7 @@ THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. -Module Name: - - ComponentName.c - -Abstract: - ---*/ +**/ #include "Fat.h" diff --git a/FatPkg/EnhancedFatDxe/Data.c b/FatPkg/EnhancedFatDxe/Data.c index b20cc4592d..56a265e4f2 100644 --- a/FatPkg/EnhancedFatDxe/Data.c +++ b/FatPkg/EnhancedFatDxe/Data.c @@ -1,4 +1,5 @@ -/*++ +/** @file + Global data in the FAT Filesystem driver. Copyright (c) 2005 - 2013, Intel Corporation. All rights reserved.
This program and the accompanying materials are licensed and made available @@ -9,18 +10,7 @@ http://opensource.org/licenses/bsd-license.php THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. - -Module Name: - - Data.c - -Abstract: - - Global data in the FAT Filesystem driver - -Revision History - ---*/ +**/ #include "Fat.h" diff --git a/FatPkg/EnhancedFatDxe/Debug.c b/FatPkg/EnhancedFatDxe/Debug.c index 7c0dc20934..ad23786333 100644 --- a/FatPkg/EnhancedFatDxe/Debug.c +++ b/FatPkg/EnhancedFatDxe/Debug.c @@ -1,4 +1,5 @@ -/*++ +/** @file + Debug functions for fat driver Copyright (c) 2005, Intel Corporation. All rights reserved.
This program and the accompanying materials are licensed and made available @@ -9,40 +10,21 @@ http://opensource.org/licenses/bsd-license.php THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. - -Module Name: - - debug.c - -Abstract: - - Debug functions for fat driver - -Revision History - ---*/ +**/ #include "Fat.h" +/** + + Dump all the FAT Entry of the FAT table in the volume. + + @param Volume - The volume whose FAT info will be dumped + +**/ VOID FatDumpFatTable ( IN FAT_VOLUME *Volume ) -/*++ - -Routine Description: - - Dump all the FAT Entry of the FAT table in the volume - -Arguments: - - Volume - The volume whose FAT info will be dumped - -Returns: - - None - ---*/ { UINTN EntryValue; UINTN MaxIndex; diff --git a/FatPkg/EnhancedFatDxe/Delete.c b/FatPkg/EnhancedFatDxe/Delete.c index e5103a850c..9837565a8e 100644 --- a/FatPkg/EnhancedFatDxe/Delete.c +++ b/FatPkg/EnhancedFatDxe/Delete.c @@ -1,4 +1,5 @@ -/*++ +/** @file + Function that deletes a file. Copyright (c) 2005 - 2013, Intel Corporation. All rights reserved.
This program and the accompanying materials are licensed and made available @@ -10,41 +11,25 @@ THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. -Module Name: - - delete.c - -Abstract: - - Function that deletes a file - -Revision History - ---*/ +**/ #include "Fat.h" +/** + + Deletes the file & Closes the file handle. + + @param FHand - Handle to the file to delete. + + @retval EFI_SUCCESS - Delete the file successfully. + @retval EFI_WARN_DELETE_FAILURE - Fail to delete the file. + +**/ EFI_STATUS EFIAPI FatDelete ( IN EFI_FILE_PROTOCOL *FHand ) -/*++ - -Routine Description: - - Deletes the file & Closes the file handle. - -Arguments: - - FHand - Handle to the file to delete. - -Returns: - - EFI_SUCCESS - Delete the file successfully. - EFI_WARN_DELETE_FAILURE - Fail to delete the file. - ---*/ { FAT_IFILE *IFile; FAT_OFILE *OFile; diff --git a/FatPkg/EnhancedFatDxe/DirectoryCache.c b/FatPkg/EnhancedFatDxe/DirectoryCache.c index 568b29178b..30de86a996 100644 --- a/FatPkg/EnhancedFatDxe/DirectoryCache.c +++ b/FatPkg/EnhancedFatDxe/DirectoryCache.c @@ -1,4 +1,5 @@ -/*++ +/** @file + Functions for directory cache operation. Copyright (c) 2005, Intel Corporation. All rights reserved.
This program and the accompanying materials are licensed and made available @@ -10,40 +11,22 @@ THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. -Module Name: - - DirectoryCache.c - -Abstract: - - Functions for directory cache operation - -Revision History - ---*/ +**/ #include "Fat.h" +/** + + Free the directory structure and release the memory. + + @param ODir - The directory to be freed. + +**/ STATIC VOID FatFreeODir ( IN FAT_ODIR *ODir ) -/*++ - -Routine Description: - - Free the directory structure and release the memory. - -Arguments: - - ODir - The directory to be freed. - -Returns: - - None. - ---*/ { FAT_DIRENT *DirEnt; @@ -63,26 +46,18 @@ Returns: FreePool (ODir); } +/** + + Allocate the directory structure. + + @param OFile - The corresponding OFile. + +**/ STATIC FAT_ODIR * FatAllocateODir ( IN FAT_OFILE *OFile ) -/*++ - -Routine Description: - - Allocate the directory structure. - -Arguments: - - OFile - The corresponding OFile. - -Returns: - - None. - ---*/ { FAT_ODIR *ODir; @@ -99,26 +74,18 @@ Returns: return ODir; } -VOID -FatDiscardODir ( - IN FAT_OFILE *OFile - ) -/*++ - -Routine Description: +/** Discard the directory structure when an OFile will be freed. Volume will cache this directory if the OFile does not represent a deleted file. -Arguments: + @param OFile - The OFile whose directory structure is to be discarded. - OFile - The OFile whose directory structure is to be discarded. - -Returns: - - None. - ---*/ +**/ +VOID +FatDiscardODir ( + IN FAT_OFILE *OFile + ) { FAT_ODIR *ODir; FAT_VOLUME *Volume; @@ -154,27 +121,20 @@ Returns: } } -VOID -FatRequestODir ( - IN FAT_OFILE *OFile - ) -/*++ +/** -Routine Description: Request the directory structure when an OFile is newly generated. If the directory structure is cached by volume, then just return this directory; Otherwise, allocate a new one for OFile. -Arguments: + @param OFile - The OFile which requests directory structure. - OFile - The OFile which requests directory structure. - -Returns: - - None. - ---*/ +**/ +VOID +FatRequestODir ( + IN FAT_OFILE *OFile + ) { UINTN DirCacheTag; FAT_VOLUME *Volume; @@ -208,25 +168,17 @@ Returns: OFile->ODir = ODir; } +/** + + Clean up all the cached directory structures when the volume is going to be abandoned. + + @param Volume - FAT file system volume. + +**/ VOID FatCleanupODirCache ( IN FAT_VOLUME *Volume ) -/*++ - -Routine Description: - - Clean up all the cached directory structures when the volume is going to be abandoned. - -Arguments: - - Volume - FAT file system volume. - -Returns: - - None. - ---*/ { FAT_ODIR *ODir; while (Volume->DirCacheCount > 0) { diff --git a/FatPkg/EnhancedFatDxe/DirectoryManage.c b/FatPkg/EnhancedFatDxe/DirectoryManage.c index 149119dc2d..fe6fcc9d88 100644 --- a/FatPkg/EnhancedFatDxe/DirectoryManage.c +++ b/FatPkg/EnhancedFatDxe/DirectoryManage.c @@ -1,4 +1,5 @@ -/*++ +/** @file + Functions for performing directory entry io. Copyright (c) 2005 - 2015, Intel Corporation. All rights reserved.
This program and the accompanying materials are licensed and made available @@ -9,21 +10,23 @@ http://opensource.org/licenses/bsd-license.php THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. - -Module Name: - - DirectoryManage.c - -Abstract: - - Functions for performing directory entry io - -Revision History - ---*/ +**/ #include "Fat.h" +/** + + Get a directory entry from disk for the Ofile. + + @param Parent - The parent of the OFile which need to update. + @param IoMode - Indicate whether to read directory entry or write directroy entry. + @param EntryPos - The position of the directory entry to be accessed. + @param Entry - The directory entry read or written. + + @retval EFI_SUCCESS - Access the directory entry sucessfully. + @return other - An error occurred when reading the directory entry. + +**/ STATIC EFI_STATUS FatAccessEntry ( @@ -32,25 +35,6 @@ FatAccessEntry ( IN UINTN EntryPos, IN OUT VOID *Entry ) -/*++ - -Routine Description: - - Get a directory entry from disk for the Ofile. - -Arguments: - - Parent - The parent of the OFile which need to update. - IoMode - Indicate whether to read directory entry or write directroy entry. - EntryPos - The position of the directory entry to be accessed. - Entry - The directory entry read or written. - -Returns: - - EFI_SUCCESS - Access the directory entry sucessfully. - other - An error occurred when reading the directory entry. - ---*/ { UINTN Position; UINTN BufferSize; @@ -70,28 +54,22 @@ Returns: return FatAccessOFile (Parent, IoMode, Position, &BufferSize, Entry, NULL); } +/** + + Save the directory entry to disk. + + @param OFile - The parent OFile which needs to update. + @param DirEnt - The directory entry to be saved. + + @retval EFI_SUCCESS - Store the directory entry successfully. + @return other - An error occurred when writing the directory entry. + +**/ EFI_STATUS FatStoreDirEnt ( IN FAT_OFILE *OFile, IN FAT_DIRENT *DirEnt ) -/*++ - -Routine Description: - - Save the directory entry to disk. - -Arguments: - - OFile - The parent OFile which needs to update. - DirEnt - The directory entry to be saved. - -Returns: - - EFI_SUCCESS - Store the directory entry successfully. - other - An error occurred when writing the directory entry. - ---*/ { EFI_STATUS Status; FAT_DIRECTORY_LFN LfnEntry; @@ -157,26 +135,20 @@ Returns: return EFI_SUCCESS; } +/** + + Determine whether the directory entry is "." or ".." entry. + + @param DirEnt - The corresponding directory entry. + + @retval TRUE - The directory entry is "." or ".." directory entry + @retval FALSE - The directory entry is not "." or ".." directory entry + +**/ BOOLEAN FatIsDotDirEnt ( IN FAT_DIRENT *DirEnt ) -/*++ - -Routine Description: - - Determine whether the directory entry is "." or ".." entry. - -Arguments: - - DirEnt - The corresponding directory entry. - -Returns: - - TRUE - The directory entry is "." or ".." directory entry - FALSE - The directory entry is not "." or ".." directory entry - ---*/ { CHAR16 *FileString; FileString = DirEnt->FileString; @@ -187,26 +159,18 @@ Returns: return FALSE; } +/** + + Set the OFile's cluster info in its directory entry. + + @param OFile - The corresponding OFile. + +**/ STATIC VOID FatSetDirEntCluster ( IN FAT_OFILE *OFile ) -/*++ - -Routine Description: - - Set the OFile's cluster info in its directory entry. - -Arguments: - - OFile - The corresponding OFile. - -Returns: - - None. - ---*/ { UINTN Cluster; FAT_DIRENT *DirEnt; @@ -217,52 +181,36 @@ Returns: DirEnt->Entry.FileCluster = (UINT16) Cluster; } +/** + + Set the OFile's cluster and size info in its directory entry. + + @param OFile - The corresponding OFile. + +**/ VOID FatUpdateDirEntClusterSizeInfo ( IN FAT_OFILE *OFile ) -/*++ - -Routine Description: - - Set the OFile's cluster and size info in its directory entry. - -Arguments: - - OFile - The corresponding OFile. - -Returns: - - None. - ---*/ { ASSERT (OFile->ODir == NULL); OFile->DirEnt->Entry.FileSize = (UINT32) OFile->FileSize; FatSetDirEntCluster (OFile); } +/** + + Copy all the information of DirEnt2 to DirEnt1 except for 8.3 name. + + @param DirEnt1 - The destination directory entry. + @param DirEnt2 - The source directory entry. + +**/ VOID FatCloneDirEnt ( IN FAT_DIRENT *DirEnt1, IN FAT_DIRENT *DirEnt2 ) -/*++ - -Routine Description: - - Copy all the information of DirEnt2 to DirEnt1 except for 8.3 name. - -Arguments: - - DirEnt1 - The destination directory entry. - DirEnt2 - The source directory entry. - -Returns: - - None. - ---*/ { UINT8 *Entry1; UINT8 *Entry2; @@ -275,28 +223,20 @@ Returns: ); } +/** + + Get the LFN for the directory entry. + + @param Parent - The parent directory. + @param DirEnt - The directory entry to get LFN. + +**/ STATIC VOID FatLoadLongNameEntry ( IN FAT_OFILE *Parent, IN FAT_DIRENT *DirEnt ) -/*++ - -Routine Description: - - Get the LFN for the directory entry. - -Arguments: - - Parent - The parent directory. - DirEnt - The directory entry to get LFN. - -Returns: - - None. - ---*/ { CHAR16 LfnBuffer[MAX_LFN_ENTRIES * LFN_CHAR_TOTAL + 1]; CHAR16 *LfnBufferPointer; @@ -367,28 +307,20 @@ Returns: DirEnt->FileString = AllocateCopyPool (StrSize (LfnBuffer), LfnBuffer); } +/** + + Add this directory entry node to the list of directory entries and hash table. + + @param ODir - The parent OFile which needs to be updated. + @param DirEnt - The directory entry to be added. + +**/ STATIC VOID FatAddDirEnt ( IN FAT_ODIR *ODir, IN FAT_DIRENT *DirEnt ) -/*++ - -Routine Description: - - Add this directory entry node to the list of directory entries and hash table. - -Arguments: - - ODir - The parent OFile which needs to be updated. - DirEnt - The directory entry to be added. - -Returns: - - None. - ---*/ { if (DirEnt->Link.BackLink == NULL) { DirEnt->Link.BackLink = &ODir->ChildList; @@ -397,30 +329,24 @@ Returns: FatInsertToHashTable (ODir, DirEnt); } +/** + + Load from disk the next directory entry at current end of directory position. + + @param OFile - The parent OFile. + @param PtrDirEnt - The directory entry that is loaded. + + @retval EFI_SUCCESS - Load the directory entry successfully. + @retval EFI_OUT_OF_RESOURCES - Out of resource. + @return other - An error occurred when reading the directory entries. + +**/ STATIC EFI_STATUS FatLoadNextDirEnt ( IN FAT_OFILE *OFile, OUT FAT_DIRENT **PtrDirEnt ) -/*++ - -Routine Description: - - Load from disk the next directory entry at current end of directory position - -Arguments: - - OFile - The parent OFile. - PtrDirEnt - The directory entry that is loaded. - -Returns: - - EFI_SUCCESS - Load the directory entry successfully. - EFI_OUT_OF_RESOURCES - Out of resource. - other - An error occurred when reading the directory entries. - ---*/ { EFI_STATUS Status; FAT_DIRENT *DirEnt; @@ -505,6 +431,19 @@ Done: return Status; } +/** + + Get the directory entry's info into Buffer. + + @param Volume - FAT file system volume. + @param DirEnt - The corresponding directory entry. + @param BufferSize - Size of Buffer. + @param Buffer - Buffer containing file info. + + @retval EFI_SUCCESS - Get the file info successfully. + @retval EFI_BUFFER_TOO_SMALL - The buffer is too small. + +**/ EFI_STATUS FatGetDirEntInfo ( IN FAT_VOLUME *Volume, @@ -512,25 +451,6 @@ FatGetDirEntInfo ( IN OUT UINTN *BufferSize, OUT VOID *Buffer ) -/*++ - -Routine Description: - - Get the directory entry's info into Buffer. - -Arguments: - - Volume - FAT file system volume. - DirEnt - The corresponding directory entry. - BufferSize - Size of Buffer. - Buffer - Buffer containing file info. - -Returns: - - EFI_SUCCESS - Get the file info successfully. - EFI_BUFFER_TOO_SMALL - The buffer is too small. - ---*/ { UINTN Size; UINTN NameSize; @@ -575,6 +495,18 @@ Returns: return Status; } +/** + + Search the directory for the directory entry whose filename is FileNameString. + + @param OFile - The parent OFile whose directory is to be searched. + @param FileNameString - The filename to be searched. + @param PtrDirEnt - pointer to the directory entry if found. + + @retval EFI_SUCCESS - Find the directory entry or not found. + @return other - An error occurred when reading the directory entries. + +**/ STATIC EFI_STATUS FatSearchODir ( @@ -582,24 +514,6 @@ FatSearchODir ( IN CHAR16 *FileNameString, OUT FAT_DIRENT **PtrDirEnt ) -/*++ - -Routine Description: - - Search the directory for the directory entry whose filename is FileNameString. - -Arguments: - - OFile - The parent OFile whose directory is to be searched. - FileNameString - The filename to be searched. - PtrDirEnt - pointer to the directory entry if found. - -Returns: - - EFI_SUCCESS - Find the directory entry or not found. - other - An error occurred when reading the directory entries. - ---*/ { BOOLEAN PossibleShortName; CHAR8 File8Dot3Name[FAT_NAME_LEN]; @@ -647,25 +561,17 @@ Returns: return EFI_SUCCESS; } +/** + + Set the OFile's current directory cursor to the list head. + + @param OFile - The directory OFile whose directory cursor is reset. + +**/ VOID FatResetODirCursor ( IN FAT_OFILE *OFile ) -/*++ - -Routine Description: - - Set the OFile's current directory cursor to the list head. - -Arguments: - - OFile - The directory OFile whose directory cursor is reset. - -Returns: - - None. - ---*/ { FAT_ODIR *ODir; @@ -675,28 +581,22 @@ Returns: ODir->CurrentPos = 0; } +/** + + Set the directory's cursor to the next and get the next directory entry. + + @param OFile - The parent OFile. + @param PtrDirEnt - The next directory entry. + + @retval EFI_SUCCESS - We get the next directory entry successfully. + @return other - An error occurred when get next directory entry. + +**/ EFI_STATUS FatGetNextDirEnt ( IN FAT_OFILE *OFile, OUT FAT_DIRENT **PtrDirEnt ) -/*++ - -Routine Description: - - Set the directory's cursor to the next and get the next directory entry. - -Arguments: - - OFile - The parent OFile. - PtrDirEnt - The next directory entry. - -Returns: - - EFI_SUCCESS - We get the next directory entry successfully. - other - An error occurred when get next directory entry. - ---*/ { EFI_STATUS Status; FAT_DIRENT *DirEnt; @@ -735,28 +635,20 @@ Returns: return EFI_SUCCESS; } +/** + + Set the directory entry count according to the filename. + + @param OFile - The corresponding OFile. + @param DirEnt - The directory entry to be set. + +**/ STATIC VOID FatSetEntryCount ( IN FAT_OFILE *OFile, IN FAT_DIRENT *DirEnt ) -/*++ - -Routine Description: - - Set the directory entry count according to the filename. - -Arguments: - - OFile - The corresponding OFile. - DirEnt - The directory entry to be set. - -Returns: - - None. - ---*/ { CHAR16 *FileString; CHAR8 *File8Dot3Name; @@ -800,54 +692,42 @@ Returns: } } +/** + + Append a zero cluster to the current OFile. + + @param OFile - The directory OFile which needs to be updated. + + @retval EFI_SUCCESS - Append a zero cluster to the OFile successfully. + @return other - An error occurred when appending the zero cluster. + +**/ STATIC EFI_STATUS FatExpandODir ( IN FAT_OFILE *OFile ) -/*++ - -Routine Description: - - Append a zero cluster to the current OFile. - -Arguments: - - OFile - The directory OFile which needs to be updated. - -Returns: - - EFI_SUCCESS - Append a zero cluster to the OFile successfully. - other - An error occurred when appending the zero cluster. - ---*/ { return FatExpandOFile (OFile, OFile->FileSize + OFile->Volume->ClusterSize); } +/** + + Search the Root OFile for the possible volume label. + + @param Root - The Root OFile. + @param DirEnt - The returned directory entry of volume label. + + @retval EFI_SUCCESS - The search process is completed successfully. + @return other - An error occurred when searching volume label. + +**/ STATIC EFI_STATUS FatSeekVolumeId ( IN FAT_OFILE *Root, OUT FAT_DIRENT *DirEnt ) -/*++ - -Routine Description: - - Search the Root OFile for the possible volume label. - -Arguments: - - Root - The Root OFile. - DirEnt - The returned directory entry of volume label. - -Returns: - - EFI_SUCCESS - The search process is completed successfully. - other - An error occurred when searching volume label. - ---*/ { EFI_STATUS Status; UINTN EntryPos; @@ -874,33 +754,27 @@ Returns: return EFI_SUCCESS; } -STATIC -EFI_STATUS -FatFirstFitInsertDirEnt ( - IN FAT_OFILE *OFile, - IN FAT_DIRENT *DirEnt - ) -/*++ - -Routine Description: +/** Use First Fit Algorithm to insert directory entry. Only this function will erase "E5" entries in a directory. In view of safest recovery, this function will only be triggered when maximum directory entry number has reached. -Arguments: + @param OFile - The corresponding OFile. + @param DirEnt - The directory entry to be inserted. - OFile - The corresponding OFile. - DirEnt - The directory entry to be inserted. + @retval EFI_SUCCESS - The directory entry has been successfully inserted. + @retval EFI_VOLUME_FULL - The directory can not hold more directory entries. + @return Others - Some error occurred when inserting new directory entries. -Returns: - - EFI_SUCCESS - The directory entry has been successfully inserted. - EFI_VOLUME_FULL - The directory can not hold more directory entries. - Others - Some error occurred when inserting new directory entries. - ---*/ +**/ +STATIC +EFI_STATUS +FatFirstFitInsertDirEnt ( + IN FAT_OFILE *OFile, + IN FAT_DIRENT *DirEnt + ) { EFI_STATUS Status; FAT_ODIR *ODir; @@ -956,30 +830,24 @@ Done: return EFI_SUCCESS; } +/** + + Find the new directory entry position for the directory entry. + + @param OFile - The corresponding OFile. + @param DirEnt - The directory entry whose new position is to be set. + + @retval EFI_SUCCESS - The new directory entry position is successfully found. + @retval EFI_VOLUME_FULL - The directory has reach its maximum capacity. + @return other - An error occurred when reading the directory entry. + +**/ STATIC EFI_STATUS FatNewEntryPos ( IN FAT_OFILE *OFile, IN FAT_DIRENT *DirEnt ) -/*++ - -Routine Description: - - Find the new directory entry position for the directory entry. - -Arguments: - - OFile - The corresponding OFile. - DirEnt - The directory entry whose new position is to be set. - -Returns: - - EFI_SUCCESS - The new directory entry position is successfully found. - EFI_VOLUME_FULL - The directory has reach its maximum capacity. - other - An error occurred when reading the directory entry. - ---*/ { EFI_STATUS Status; FAT_ODIR *ODir; @@ -1027,28 +895,22 @@ Returns: return EFI_SUCCESS; } +/** + + Get the directory entry for the volume. + + @param Volume - FAT file system volume. + @param Name - The file name of the volume. + + @retval EFI_SUCCESS - Update the volume with the directory entry sucessfully. + @return others - An error occurred when getting volume label. + +**/ EFI_STATUS FatGetVolumeEntry ( IN FAT_VOLUME *Volume, IN CHAR16 *Name ) -/*++ - -Routine Description: - - Get the directory entry for the volume. - -Arguments: - - Volume - FAT file system volume. - Name - The file name of the volume. - -Returns: - - EFI_SUCCESS - Update the volume with the directory entry sucessfully. - others - An error occurred when getting volume label. - ---*/ { EFI_STATUS Status; FAT_DIRENT LabelDirEnt; @@ -1064,29 +926,23 @@ Returns: return Status; } +/** + + Set the relevant directory entry into disk for the volume. + + @param Volume - FAT file system volume. + @param Name - The new file name of the volume. + + @retval EFI_SUCCESS - Update the Volume sucessfully. + @retval EFI_UNSUPPORTED - The input label is not a valid volume label. + @return other - An error occurred when setting volume label. + +**/ EFI_STATUS FatSetVolumeEntry ( IN FAT_VOLUME *Volume, IN CHAR16 *Name ) -/*++ - -Routine Description: - - Set the relevant directory entry into disk for the volume. - -Arguments: - - Volume - FAT file system volume. - Name - The new file name of the volume. - -Returns: - - EFI_SUCCESS - Update the Volume sucessfully. - EFI_UNSUPPORTED - The input label is not a valid volume label. - other - An error occurred when setting volume label. - ---*/ { EFI_STATUS Status; FAT_DIRENT LabelDirEnt; @@ -1121,26 +977,20 @@ Returns: return FatStoreDirEnt (Root, &LabelDirEnt); } +/** + + Create "." and ".." directory entries in the newly-created parent OFile. + + @param OFile - The parent OFile. + + @retval EFI_SUCCESS - The dot directory entries are successfully created. + @return other - An error occurred when creating the directory entry. + +**/ EFI_STATUS FatCreateDotDirEnts ( IN FAT_OFILE *OFile ) -/*++ - -Routine Description: - - Create "." and ".." directory entries in the newly-created parent OFile. - -Arguments: - - OFile - The parent OFile. - -Returns: - - EFI_SUCCESS - The dot directory entries are successfully created. - other - An error occurred when creating the directory entry. - ---*/ { EFI_STATUS Status; FAT_DIRENT *DirEnt; @@ -1165,6 +1015,20 @@ Returns: return Status; } +/** + + Create a directory entry in the parent OFile. + + @param OFile - The parent OFile. + @param FileName - The filename of the newly-created directory entry. + @param Attributes - The attribute of the newly-created directory entry. + @param PtrDirEnt - The pointer to the newly-created directory entry. + + @retval EFI_SUCCESS - The directory entry is successfully created. + @retval EFI_OUT_OF_RESOURCES - Not enough memory to create the directory entry. + @return other - An error occurred when creating the directory entry. + +**/ EFI_STATUS FatCreateDirEnt ( IN FAT_OFILE *OFile, @@ -1172,26 +1036,6 @@ FatCreateDirEnt ( IN UINT8 Attributes, OUT FAT_DIRENT **PtrDirEnt ) -/*++ - -Routine Description: - - Create a directory entry in the parent OFile. - -Arguments: - - OFile - The parent OFile. - FileName - The filename of the newly-created directory entry. - Attributes - The attribute of the newly-created directory entry. - PtrDirEnt - The pointer to the newly-created directory entry. - -Returns: - - EFI_SUCCESS - The directory entry is successfully created. - EFI_OUT_OF_RESOURCES - Not enough memory to create the directory entry. - other - An error occurred when creating the directory entry. - ---*/ { FAT_DIRENT *DirEnt; FAT_ODIR *ODir; @@ -1234,28 +1078,22 @@ Done: return Status; } +/** + + Remove this directory entry node from the list of directory entries and hash table. + + @param OFile - The parent OFile. + @param DirEnt - The directory entry to be removed. + + @retval EFI_SUCCESS - The directory entry is successfully removed. + @return other - An error occurred when removing the directory entry. + +**/ EFI_STATUS FatRemoveDirEnt ( IN FAT_OFILE *OFile, IN FAT_DIRENT *DirEnt ) -/*++ - -Routine Description: - - Remove this directory entry node from the list of directory entries and hash table. - -Arguments: - - OFile - The parent OFile. - DirEnt - The directory entry to be removed. - -Returns: - - EFI_SUCCESS - The directory entry is successfully removed. - other - An error occurred when removing the directory entry. - ---*/ { FAT_ODIR *ODir; @@ -1279,29 +1117,23 @@ Returns: return FatStoreDirEnt (OFile, DirEnt); } +/** + + Open the directory entry to get the OFile. + + @param Parent - The parent OFile. + @param DirEnt - The directory entry to be opened. + + @retval EFI_SUCCESS - The directory entry is successfully opened. + @retval EFI_OUT_OF_RESOURCES - not enough memory to allocate a new OFile. + @return other - An error occurred when opening the directory entry. + +**/ EFI_STATUS FatOpenDirEnt ( IN FAT_OFILE *Parent, IN FAT_DIRENT *DirEnt ) -/*++ - -Routine Description: - - Open the directory entry to get the OFile. - -Arguments: - - OFile - The parent OFile. - DirEnt - The directory entry to be opened. - -Returns: - - EFI_SUCCESS - The directory entry is successfully opened. - EFI_OUT_OF_RESOURCES - not enough memory to allocate a new OFile. - other - An error occurred when opening the directory entry. - ---*/ { FAT_OFILE *OFile; FAT_VOLUME *Volume; @@ -1364,26 +1196,17 @@ Returns: return EFI_SUCCESS; } +/** + + Close the directory entry and free the OFile. + + @param DirEnt - The directory entry to be closed. + +**/ VOID FatCloseDirEnt ( IN FAT_DIRENT *DirEnt ) -/*++ - -Routine Description: - - Close the directory entry and free the OFile. - -Arguments: - - DirEnt - The directory entry to be closed. - -Returns: - - EFI_SUCCESS - The directory entry is successfully opened. - Other - An error occurred when opening the directory entry. - ---*/ { FAT_OFILE *OFile; FAT_VOLUME *Volume; @@ -1412,6 +1235,26 @@ Returns: } } +/** + + Traverse filename and open all OFiles that can be opened. + Update filename pointer to the component that can't be opened. + If more than one name component remains, returns an error; + otherwise, return the remaining name component so that the caller might choose to create it. + + @param PtrOFile - As input, the reference OFile; as output, the located OFile. + @param FileName - The file name relevant to the OFile. + @param Attributes - The attribute of the destination OFile. + @param NewFileName - The remaining file name. + + @retval EFI_NOT_FOUND - The file name can't be opened and there is more than one + components within the name left (this means the name can + not be created either). + @retval EFI_INVALID_PARAMETER - The parameter is not valid. + @retval EFI_SUCCESS - Open the file successfully. + @return other - An error occured when locating the OFile. + +**/ EFI_STATUS FatLocateOFile ( IN OUT FAT_OFILE **PtrOFile, @@ -1419,31 +1262,6 @@ FatLocateOFile ( IN UINT8 Attributes, OUT CHAR16 *NewFileName ) -/*++ - -Routine Description: - - Traverse filename and open all OFiles that can be opened. - Update filename pointer to the component that can't be opened. - If more than one name component remains, returns an error; - otherwise, return the remaining name component so that the caller might choose to create it. - -Arguments: - PtrOFile - As input, the reference OFile; as output, the located OFile. - FileName - The file name relevant to the OFile. - Attributes - The attribute of the destination OFile. - NewFileName - The remaining file name. - -Returns: - - EFI_NOT_FOUND - The file name can't be opened and there is more than one - components within the name left (this means the name can - not be created either). - EFI_INVALID_PARAMETER - The parameter is not valid. - EFI_SUCCESS - Open the file successfully. - other - An error occured when locating the OFile. - ---*/ { EFI_STATUS Status; FAT_VOLUME *Volume; diff --git a/FatPkg/EnhancedFatDxe/DiskCache.c b/FatPkg/EnhancedFatDxe/DiskCache.c index 7f1fcf48cb..63f9c007d6 100644 --- a/FatPkg/EnhancedFatDxe/DiskCache.c +++ b/FatPkg/EnhancedFatDxe/DiskCache.c @@ -1,4 +1,5 @@ -/*++ +/** @file + Cache implementation for EFI FAT File system driver. Copyright (c) 2005 - 2013, Intel Corporation. All rights reserved.
This program and the accompanying materials are licensed and made available @@ -9,33 +10,11 @@ http://opensource.org/licenses/bsd-license.php THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. - -Module Name: - - DiskCache.c - -Abstract: - - Cache implementation for EFI FAT File system driver - -Revision History - ---*/ +**/ #include "Fat.h" -STATIC -VOID -FatFlushDataCacheRange ( - IN FAT_VOLUME *Volume, - IN IO_MODE IoMode, - IN UINTN StartPageNo, - IN UINTN EndPageNo, - OUT UINT8 *Buffer - ) -/*++ - -Routine Description: +/** This function is used by the Data Cache. @@ -46,20 +25,23 @@ Routine Description: is dirty, it means that the relative info directly readed from media is older than than the info in the cache; So need to update the relative info in the Buffer. -Arguments: - - Volume - FAT file system volume. - IoMode - This function is called by read command or write command - StartPageNo - First PageNo to be checked in the cache. - EndPageNo - Last PageNo to be checked in the cache. - Buffer - The user buffer need to update. Only when doing the read command + @param Volume - FAT file system volume. + @param IoMode - This function is called by read command or write command + @param StartPageNo - First PageNo to be checked in the cache. + @param EndPageNo - Last PageNo to be checked in the cache. + @param Buffer - The user buffer need to update. Only when doing the read command and there is dirty cache in the cache range, this parameter will be used. -Returns: - - None. - ---*/ +**/ +STATIC +VOID +FatFlushDataCacheRange ( + IN FAT_VOLUME *Volume, + IN IO_MODE IoMode, + IN UINTN StartPageNo, + IN UINTN EndPageNo, + OUT UINT8 *Buffer + ) { UINTN PageNo; UINTN GroupNo; @@ -103,6 +85,20 @@ Returns: } } +/** + + Exchange the cache page with the image on the disk + + @param Volume - FAT file system volume. + @param DataType - Indicate the cache type. + @param IoMode - Indicate whether to load this page from disk or store this page to disk. + @param CacheTag - The Cache Tag for the current cache page. + @param Task point to task instance. + + @retval EFI_SUCCESS - Cache page exchanged successfully. + @return Others - An error occurred when exchanging cache page. + +**/ STATIC EFI_STATUS FatExchangeCachePage ( @@ -112,25 +108,6 @@ FatExchangeCachePage ( IN CACHE_TAG *CacheTag, IN FAT_TASK *Task ) -/*++ - -Routine Description: - - Exchange the cache page with the image on the disk - -Arguments: - - Volume - FAT file system volume. - DataType - Indicate the cache type. - IoMode - Indicate whether to load this page from disk or store this page to disk. - CacheTag - The Cache Tag for the current cache page. - -Returns: - - EFI_SUCCESS - Cache page exchanged successfully. - Others - An error occurred when exchanging cache page. - ---*/ { EFI_STATUS Status; UINTN GroupNo; @@ -181,6 +158,19 @@ Returns: return EFI_SUCCESS; } +/** + + Get one cache page by specified PageNo. + + @param Volume - FAT file system volume. + @param CacheDataType - The cache type: CACHE_FAT or CACHE_DATA. + @param PageNo - PageNo to match with the cache. + @param CacheTag - The Cache Tag for the current cache page. + + @retval EFI_SUCCESS - Get the cache page successfully. + @return other - An error occurred when accessing data. + +**/ STATIC EFI_STATUS FatGetCachePage ( @@ -189,25 +179,6 @@ FatGetCachePage ( IN UINTN PageNo, IN CACHE_TAG *CacheTag ) -/*++ - -Routine Description: - - Get one cache page by specified PageNo. - -Arguments: - - Volume - FAT file system volume. - CacheDataType - The cache type: CACHE_FAT or CACHE_DATA. - PageNo - PageNo to match with the cache. - CacheTag - The Cache Tag for the current cache page. - -Returns: - - EFI_SUCCESS - Get the cache page successfully. - other - An error occurred when accessing data. - ---*/ { EFI_STATUS Status; UINTN OldPageNo; @@ -238,6 +209,23 @@ Returns: return Status; } +/** + + Read Length bytes from the position of Offset into Buffer, or + write Length bytes from Buffer into the position of Offset. + + @param Volume - FAT file system volume. + @param CacheDataType - The type of cache: CACHE_DATA or CACHE_FAT. + @param IoMode - Indicate the type of disk access. + @param PageNo - The number of unaligned cache page. + @param Offset - The starting byte of cache page. + @param Length - The number of bytes that is read or written + @param Buffer - Buffer containing cache data. + + @retval EFI_SUCCESS - The data was accessed correctly. + @return Others - An error occurred when accessing unaligned cache page. + +**/ STATIC EFI_STATUS FatAccessUnalignedCachePage ( @@ -249,28 +237,6 @@ FatAccessUnalignedCachePage ( IN UINTN Length, IN OUT VOID *Buffer ) -/*++ -Routine Description: - - Read Length bytes from the position of Offset into Buffer, or - write Length bytes from Buffer into the position of Offset. - -Arguments: - - Volume - FAT file system volume. - CacheDataType - The type of cache: CACHE_DATA or CACHE_FAT. - IoMode - Indicate the type of disk access. - PageNo - The number of unaligned cache page. - Offset - The starting byte of cache page. - Length - The number of bytes that is read or written - Buffer - Buffer containing cache data. - -Returns: - - EFI_SUCCESS - The data was accessed correctly. - Others - An error occurred when accessing unaligned cache page. - ---*/ { EFI_STATUS Status; VOID *Source; @@ -299,18 +265,7 @@ Returns: return Status; } -EFI_STATUS -FatAccessCache ( - IN FAT_VOLUME *Volume, - IN CACHE_DATA_TYPE CacheDataType, - IN IO_MODE IoMode, - IN UINT64 Offset, - IN UINTN BufferSize, - IN OUT UINT8 *Buffer, - IN FAT_TASK *Task - ) -/*++ -Routine Description: +/** Read BufferSize bytes from the position of Offset into Buffer, or write BufferSize bytes from Buffer into the position of Offset. @@ -326,22 +281,29 @@ Routine Description: The UnderRun data and OverRun data will be accessed by the Data cache, but the Aligned data will be accessed with disk directly. -Arguments: + @param Volume - FAT file system volume. + @param CacheDataType - The type of cache: CACHE_DATA or CACHE_FAT. + @param IoMode - Indicate the type of disk access. + @param Offset - The starting byte offset to read from. + @param BufferSize - Size of Buffer. + @param Buffer - Buffer containing cache data. + @param Task point to task instance. - Volume - FAT file system volume. - CacheDataType - The type of cache: CACHE_DATA or CACHE_FAT. - IoMode - Indicate the type of disk access. - Offset - The starting byte offset to read from. - BufferSize - Size of Buffer. - Buffer - Buffer containing cache data. + @retval EFI_SUCCESS - The data was accessed correctly. + @retval EFI_MEDIA_CHANGED - The MediaId does not match the current device. + @return Others - An error occurred when accessing cache. -Returns: - - EFI_SUCCESS - The data was accessed correctly. - EFI_MEDIA_CHANGED - The MediaId does not match the current device. - Others - An error occurred when accessing cache. - ---*/ +**/ +EFI_STATUS +FatAccessCache ( + IN FAT_VOLUME *Volume, + IN CACHE_DATA_TYPE CacheDataType, + IN IO_MODE IoMode, + IN UINT64 Offset, + IN UINTN BufferSize, + IN OUT UINT8 *Buffer, + IN FAT_TASK *Task + ) { EFI_STATUS Status; UINTN PageSize; @@ -421,27 +383,22 @@ Returns: return Status; } +/** + + Flush all the dirty cache back, include the FAT cache and the Data cache. + + @param Volume - FAT file system volume. + @param Task point to task instance. + + @retval EFI_SUCCESS - Flush all the dirty cache back successfully + @return other - An error occurred when writing the data into the disk + +**/ EFI_STATUS FatVolumeFlushCache ( IN FAT_VOLUME *Volume, IN FAT_TASK *Task ) -/*++ - -Routine Description: - - Flush all the dirty cache back, include the FAT cache and the Data cache. - -Arguments: - - Volume - FAT file system volume. - -Returns: - - EFI_SUCCESS - Flush all the dirty cache back successfully - other - An error occurred when writing the data into the disk - ---*/ { EFI_STATUS Status; CACHE_DATA_TYPE CacheDataType; @@ -480,26 +437,20 @@ Returns: return Status; } +/** + + Initialize the disk cache according to Volume's FatType. + + @param Volume - FAT file system volume. + + @retval EFI_SUCCESS - The disk cache is successfully initialized. + @retval EFI_OUT_OF_RESOURCES - Not enough memory to allocate disk cache. + +**/ EFI_STATUS FatInitializeDiskCache ( IN FAT_VOLUME *Volume ) -/*++ - -Routine Description: - - Initialize the disk cache according to Volume's FatType. - -Arguments: - - Volume - FAT file system volume. - -Returns: - - EFI_SUCCESS - The disk cache is successfully initialized. - EFI_OUT_OF_RESOURCES - Not enough memory to allocate disk cache. - ---*/ { DISK_CACHE *DiskCache; UINTN FatCacheGroupCount; diff --git a/FatPkg/EnhancedFatDxe/Fat.c b/FatPkg/EnhancedFatDxe/Fat.c index 2080005adc..2e6c089650 100644 --- a/FatPkg/EnhancedFatDxe/Fat.c +++ b/FatPkg/EnhancedFatDxe/Fat.c @@ -1,4 +1,5 @@ -/*++ +/** @file + Fat File System driver routines that support EFI driver model. Copyright (c) 2005 - 2014, Intel Corporation. All rights reserved.
This program and the accompanying materials are licensed and made available @@ -9,16 +10,7 @@ http://opensource.org/licenses/bsd-license.php THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. - -Module Name: - - Fat.c - -Abstract: - - Fat File System driver routines that support EFI driver model - ---*/ +**/ #include "Fat.h" @@ -72,29 +64,23 @@ EFI_DRIVER_BINDING_PROTOCOL gFatDriverBinding = { NULL }; +/** + + Register Driver Binding protocol for this driver. + + @param ImageHandle - Handle for the image of this driver. + @param SystemTable - Pointer to the EFI System Table. + + @retval EFI_SUCCESS - Driver loaded. + @return other - Driver not loaded. + +**/ EFI_STATUS EFIAPI FatEntryPoint ( IN EFI_HANDLE ImageHandle, IN EFI_SYSTEM_TABLE *SystemTable ) -/*++ - -Routine Description: - - Register Driver Binding protocol for this driver. - -Arguments: - - ImageHandle - Handle for the image of this driver. - SystemTable - Pointer to the EFI System Table. - -Returns: - - EFI_SUCCESS - Driver loaded. - other - Driver not loaded. - ---*/ { EFI_STATUS Status; @@ -114,27 +100,21 @@ Returns: return Status; } +/** + + Unload function for this image. Uninstall DriverBinding protocol. + + @param ImageHandle - Handle for the image of this driver. + + @retval EFI_SUCCESS - Driver unloaded successfully. + @return other - Driver can not unloaded. + +**/ EFI_STATUS EFIAPI FatUnload ( IN EFI_HANDLE ImageHandle ) -/*++ - -Routine Description: - - Unload function for this image. Uninstall DriverBinding protocol. - -Arguments: - - ImageHandle - Handle for the image of this driver. - -Returns: - - EFI_SUCCESS - Driver unloaded successfully. - other - Driver can not unloaded. - ---*/ { EFI_STATUS Status; EFI_HANDLE *DeviceHandleBuffer; @@ -224,6 +204,20 @@ Returns: return Status; } +/** + + Test to see if this driver can add a file system to ControllerHandle. + ControllerHandle must support both Disk IO and Block IO protocols. + + @param This - Protocol instance pointer. + @param ControllerHandle - Handle of device to test. + @param RemainingDevicePath - Not used. + + @retval EFI_SUCCESS - This driver supports this device. + @retval EFI_ALREADY_STARTED - This driver is already running on this device. + @return other - This driver does not support this device. + +**/ EFI_STATUS EFIAPI FatDriverBindingSupported ( @@ -231,26 +225,6 @@ FatDriverBindingSupported ( IN EFI_HANDLE ControllerHandle, IN EFI_DEVICE_PATH_PROTOCOL *RemainingDevicePath ) -/*++ - -Routine Description: - - Test to see if this driver can add a file system to ControllerHandle. - ControllerHandle must support both Disk IO and Block IO protocols. - -Arguments: - - This - Protocol instance pointer. - ControllerHandle - Handle of device to test. - RemainingDevicePath - Not used. - -Returns: - - EFI_SUCCESS - This driver supports this device. - EFI_ALREADY_STARTED - This driver is already running on this device. - other - This driver does not support this device. - ---*/ { EFI_STATUS Status; EFI_DISK_IO_PROTOCOL *DiskIo; @@ -295,6 +269,22 @@ Returns: return Status; } +/** + + Start this driver on ControllerHandle by opening a Block IO and Disk IO + protocol, reading Device Path. Add a Simple File System protocol to + ControllerHandle if the media contains a valid file system. + + @param This - Protocol instance pointer. + @param ControllerHandle - Handle of device to bind driver to. + @param RemainingDevicePath - Not used. + + @retval EFI_SUCCESS - This driver is added to DeviceHandle. + @retval EFI_ALREADY_STARTED - This driver is already running on DeviceHandle. + @retval EFI_OUT_OF_RESOURCES - Can not allocate the memory. + @return other - This driver does not support this device. + +**/ EFI_STATUS EFIAPI FatDriverBindingStart ( @@ -302,28 +292,6 @@ FatDriverBindingStart ( IN EFI_HANDLE ControllerHandle, IN EFI_DEVICE_PATH_PROTOCOL *RemainingDevicePath ) -/*++ - -Routine Description: - - Start this driver on ControllerHandle by opening a Block IO and Disk IO - protocol, reading Device Path. Add a Simple File System protocol to - ControllerHandle if the media contains a valid file system. - -Arguments: - - This - Protocol instance pointer. - ControllerHandle - Handle of device to bind driver to. - RemainingDevicePath - Not used. - -Returns: - - EFI_SUCCESS - This driver is added to DeviceHandle. - EFI_ALREADY_STARTED - This driver is already running on DeviceHandle. - EFI_OUT_OF_RESOURCES - Can not allocate the memory. - other - This driver does not support this device. - ---*/ { EFI_STATUS Status; EFI_BLOCK_IO_PROTOCOL *BlockIo; @@ -430,6 +398,19 @@ Exit: return Status; } +/** + + Stop this driver on ControllerHandle. + + @param This - Protocol instance pointer. + @param ControllerHandle - Handle of device to stop driver on. + @param NumberOfChildren - Not used. + @param ChildHandleBuffer - Not used. + + @retval EFI_SUCCESS - This driver is removed DeviceHandle. + @return other - This driver was not removed from this device. + +**/ EFI_STATUS EFIAPI FatDriverBindingStop ( @@ -438,22 +419,6 @@ FatDriverBindingStop ( IN UINTN NumberOfChildren, IN EFI_HANDLE *ChildHandleBuffer ) -/*++ - -Routine Description: - Stop this driver on ControllerHandle. - -Arguments: - This - Protocol instance pointer. - ControllerHandle - Handle of device to stop driver on. - NumberOfChildren - Not used. - ChildHandleBuffer - Not used. - -Returns: - EFI_SUCCESS - This driver is removed DeviceHandle. - other - This driver was not removed from this device. - ---*/ { EFI_STATUS Status; EFI_SIMPLE_FILE_SYSTEM_PROTOCOL *FileSystem; diff --git a/FatPkg/EnhancedFatDxe/Fat.h b/FatPkg/EnhancedFatDxe/Fat.h index f49acee24e..9490868ea7 100644 --- a/FatPkg/EnhancedFatDxe/Fat.h +++ b/FatPkg/EnhancedFatDxe/Fat.h @@ -1,4 +1,5 @@ -/*++ +/** @file + Main header file for EFI FAT file system driver. Copyright (c) 2005 - 2013, Intel Corporation. All rights reserved.
This program and the accompanying materials are licensed and made available @@ -9,18 +10,7 @@ http://opensource.org/licenses/bsd-license.php THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. - -Module Name: - - Fat.h - -Abstract: - - Main header file for EFI FAT file system driver - -Revision History - ---*/ +**/ #ifndef _FAT_H_ #define _FAT_H_ @@ -396,6 +386,26 @@ struct _FAT_VOLUME { // // Function Prototypes // + +/** + + Implements Open() of Simple File System Protocol. + + @param FHand - File handle of the file serves as a starting reference point. + @param NewHandle - Handle of the file that is newly opened. + @param FileName - File name relative to FHand. + @param OpenMode - Open mode. + @param Attributes - Attributes to set if the file is created. + + + @retval EFI_INVALID_PARAMETER - The FileName is NULL or the file string is empty. + The OpenMode is not supported. + The Attributes is not the valid attributes. + @retval EFI_OUT_OF_RESOURCES - Can not allocate the memory for file string. + @retval EFI_SUCCESS - Open the file successfully. + @return Others - The status of open file. + +**/ EFI_STATUS EFIAPI FatOpen ( @@ -405,31 +415,27 @@ FatOpen ( IN UINT64 OpenMode, IN UINT64 Attributes ) -/*++ -Routine Description: - - Implements Open() of Simple File System Protocol. - -Arguments: - - FHand - File handle of the file serves as a starting reference point. - NewHandle - Handle of the file that is newly opened. - FileName - File name relative to FHand. - OpenMode - Open mode. - Attributes - Attributes to set if the file is created. - -Returns: - - EFI_INVALID_PARAMETER - The FileName is NULL or the file string is empty. - The OpenMode is not supported. - The Attributes is not the valid attributes. - EFI_OUT_OF_RESOURCES - Can not allocate the memory for file string. - EFI_SUCCESS - Open the file successfully. - Others - The status of open file. - ---*/ ; +/** + + Implements OpenEx() of Simple File System Protocol. + + @param FHand - File handle of the file serves as a starting reference point. + @param NewHandle - Handle of the file that is newly opened. + @param FileName - File name relative to FHand. + @param OpenMode - Open mode. + @param Attributes - Attributes to set if the file is created. + @param Token - A pointer to the token associated with the transaction. + + @retval EFI_INVALID_PARAMETER - The FileName is NULL or the file string is empty. + The OpenMode is not supported. + The Attributes is not the valid attributes. + @retval EFI_OUT_OF_RESOURCES - Can not allocate the memory for file string. + @retval EFI_SUCCESS - Open the file successfully. + @return Others - The status of open file. + +**/ EFI_STATUS EFIAPI FatOpenEx ( @@ -440,58 +446,41 @@ FatOpenEx ( IN UINT64 Attributes, IN OUT EFI_FILE_IO_TOKEN *Token ) -/*++ -Routine Description: - - Implements OpenEx() of Simple File System Protocol. - -Arguments: - - FHand - File handle of the file serves as a starting reference point. - NewHandle - Handle of the file that is newly opened. - FileName - File name relative to FHand. - OpenMode - Open mode. - Attributes - Attributes to set if the file is created. - Token - A pointer to the token associated with the transaction. - -Returns: - - EFI_INVALID_PARAMETER - The FileName is NULL or the file string is empty. - The OpenMode is not supported. - The Attributes is not the valid attributes. - EFI_OUT_OF_RESOURCES - Can not allocate the memory for file string. - EFI_SUCCESS - Open the file successfully. - Others - The status of open file. - ---*/ ; +/** + + Get the file's position of the file + + @param FHand - The handle of file. + @param Position - The file's position of the file. + + @retval EFI_SUCCESS - Get the info successfully. + @retval EFI_DEVICE_ERROR - Can not find the OFile for the file. + @retval EFI_UNSUPPORTED - The open file is not a file. + +**/ EFI_STATUS EFIAPI FatGetPosition ( IN EFI_FILE_PROTOCOL *FHand, OUT UINT64 *Position ) -/*++ - -Routine Description: - - Get the file's position of the file - -Arguments: - - FHand - The handle of file. - Position - The file's position of the file. - -Returns: - - EFI_SUCCESS - Get the info successfully. - EFI_DEVICE_ERROR - Can not find the OFile for the file. - EFI_UNSUPPORTED - The open file is not a file. - ---*/ ; +/** + + Get the some types info of the file into Buffer + + @param FHand - The handle of file. + @param Type - The type of the info. + @param BufferSize - Size of Buffer. + @param Buffer - Buffer containing volume info. + + @retval EFI_SUCCESS - Get the info successfully. + @retval EFI_DEVICE_ERROR - Can not find the OFile for the file. + +**/ EFI_STATUS EFIAPI FatGetInfo ( @@ -500,27 +489,21 @@ FatGetInfo ( IN OUT UINTN *BufferSize, OUT VOID *Buffer ) -/*++ - -Routine Description: - - Get the some types info of the file into Buffer - -Arguments: - - FHand - The handle of file. - Type - The type of the info. - BufferSize - Size of Buffer. - Buffer - Buffer containing volume info. - -Returns: - - EFI_SUCCESS - Get the info successfully. - EFI_DEVICE_ERROR - Can not find the OFile for the file. - ---*/ ; +/** + + Set the some types info of the file into Buffer. + + @param FHand - The handle of file. + @param Type - The type of the info. + @param BufferSize - Size of Buffer. + @param Buffer - Buffer containing volume info. + + @retval EFI_SUCCESS - Set the info successfully. + @retval EFI_DEVICE_ERROR - Can not find the OFile for the file. + +**/ EFI_STATUS EFIAPI FatSetInfo ( @@ -529,151 +512,116 @@ FatSetInfo ( IN UINTN BufferSize, IN VOID *Buffer ) -/*++ - -Routine Description: - - Set the some types info of the file into Buffer - -Arguments: - - FHand - The handle of file. - Type - The type of the info. - BufferSize - Size of Buffer. - Buffer - Buffer containing volume info. - -Returns: - - EFI_SUCCESS - Set the info successfully. - EFI_DEVICE_ERROR - Can not find the OFile for the file. - ---*/ ; +/** + + Flushes all data associated with the file handle. + + @param FHand - Handle to file to flush + + @retval EFI_SUCCESS - Flushed the file successfully + @retval EFI_WRITE_PROTECTED - The volume is read only + @retval EFI_ACCESS_DENIED - The volume is not read only + but the file is read only + @return Others - Flushing of the file is failed + +**/ EFI_STATUS EFIAPI FatFlush ( IN EFI_FILE_PROTOCOL *FHand ) -/*++ - -Routine Description: - - Flushes all data associated with the file handle - -Arguments: - - FHand - Handle to file to flush - -Returns: - - EFI_SUCCESS - Flushed the file successfully - EFI_WRITE_PROTECTED - The volume is read only - EFI_ACCESS_DENIED - The volume is not read only - but the file is read only - Others - Flushing of the file is failed - ---*/ ; +/** + + Flushes all data associated with the file handle. + + @param FHand - Handle to file to flush. + @param Token - A pointer to the token associated with the transaction. + + @retval EFI_SUCCESS - Flushed the file successfully. + @retval EFI_WRITE_PROTECTED - The volume is read only. + @retval EFI_ACCESS_DENIED - The file is read only. + @return Others - Flushing of the file failed. + +**/ EFI_STATUS EFIAPI FatFlushEx ( IN EFI_FILE_PROTOCOL *FHand, IN EFI_FILE_IO_TOKEN *Token ) -/*++ - -Routine Description: - - Flushes all data associated with the file handle. - -Arguments: - - FHand - Handle to file to flush. - Token - A pointer to the token associated with the transaction. - -Returns: - - EFI_SUCCESS - Flushed the file successfully. - EFI_WRITE_PROTECTED - The volume is read only. - EFI_ACCESS_DENIED - The file is read only. - Others - Flushing of the file failed. - ---*/ ; +/** + + Flushes & Closes the file handle. + + @param FHand - Handle to the file to delete. + + @retval EFI_SUCCESS - Closed the file successfully. + +**/ EFI_STATUS EFIAPI FatClose ( IN EFI_FILE_PROTOCOL *FHand ) -/*++ - -Routine Description: - - Flushes & Closes the file handle. - -Arguments: - - FHand - Handle to the file to delete. - -Returns: - - EFI_SUCCESS - Closed the file successfully. - ---*/ ; +/** + + Deletes the file & Closes the file handle. + + @param FHand - Handle to the file to delete. + + @retval EFI_SUCCESS - Delete the file successfully. + @retval EFI_WARN_DELETE_FAILURE - Fail to delete the file. + +**/ EFI_STATUS EFIAPI FatDelete ( IN EFI_FILE_PROTOCOL *FHand ) -/*++ - -Routine Description: - - Deletes the file & Closes the file handle. - -Arguments: - - FHand - Handle to the file to delete. - -Returns: - - EFI_SUCCESS - Delete the file successfully. - EFI_WARN_DELETE_FAILURE - Fail to delete the file. - ---*/ ; +/** + + Set the file's position of the file. + + @param FHand - The handle of file + @param Position - The file's position of the file + + @retval EFI_SUCCESS - Set the info successfully + @retval EFI_DEVICE_ERROR - Can not find the OFile for the file + @retval EFI_UNSUPPORTED - Set a directory with a not-zero position + +**/ EFI_STATUS EFIAPI FatSetPosition ( IN EFI_FILE_PROTOCOL *FHand, IN UINT64 Position ) -/*++ - -Routine Description: - - Set the file's position of the file - -Arguments: - - FHand - The handle of file - Position - The file's position of the file - -Returns: - - EFI_SUCCESS - Set the info successfully - EFI_DEVICE_ERROR - Can not find the OFile for the file - EFI_UNSUPPORTED - Set a directory with a not-zero position - ---*/ ; +/** + + Get the file info. + + @param FHand - The handle of the file. + @param BufferSize - Size of Buffer. + @param Buffer - Buffer containing read data. + + @retval EFI_SUCCESS - Get the file info successfully. + @retval EFI_DEVICE_ERROR - Can not find the OFile for the file. + @retval EFI_VOLUME_CORRUPTED - The file type of open file is error. + @return other - An error occurred when operation the disk. + +**/ EFI_STATUS EFIAPI FatRead ( @@ -681,55 +629,46 @@ FatRead ( IN OUT UINTN *BufferSize, OUT VOID *Buffer ) -/*++ +; -Routine Description: +/** Get the file info. -Arguments: + @param FHand - The handle of the file. + @param Token - A pointer to the token associated with the transaction. - FHand - The handle of the file. - BufferSize - Size of Buffer. - Buffer - Buffer containing read data. - -Returns: - - EFI_SUCCESS - Get the file info successfully. - EFI_DEVICE_ERROR - Can not find the OFile for the file. - EFI_VOLUME_CORRUPTED - The file type of open file is error. - other - An error occurred when operation the disk. - ---*/ -; + @retval EFI_SUCCESS - Get the file info successfully. + @retval EFI_DEVICE_ERROR - Can not find the OFile for the file. + @retval EFI_VOLUME_CORRUPTED - The file type of open file is error. + @return other - An error occurred when operation the disk. +**/ EFI_STATUS EFIAPI FatReadEx ( IN EFI_FILE_PROTOCOL *FHand, IN OUT EFI_FILE_IO_TOKEN *Token ) -/*++ - -Routine Description: - - Get the file info. - -Arguments: - - FHand - The handle of the file. - Token - A pointer to the token associated with the transaction. - -Returns: - - EFI_SUCCESS - Get the file info successfully. - EFI_DEVICE_ERROR - Can not find the OFile for the file. - EFI_VOLUME_CORRUPTED - The file type of open file is error. - other - An error occurred when operation the disk. - ---*/ ; +/** + + Set the file info. + + @param FHand - The handle of the file. + @param BufferSize - Size of Buffer. + @param Buffer - Buffer containing write data. + + @retval EFI_SUCCESS - Set the file info successfully. + @retval EFI_WRITE_PROTECTED - The disk is write protected. + @retval EFI_ACCESS_DENIED - The file is read-only. + @retval EFI_DEVICE_ERROR - The OFile is not valid. + @retval EFI_UNSUPPORTED - The open file is not a file. + - The writing file size is larger than 4GB. + @return other - An error occurred when operation the disk. + +**/ EFI_STATUS EFIAPI FatWrite ( @@ -737,56 +676,27 @@ FatWrite ( IN OUT UINTN *BufferSize, IN VOID *Buffer ) -/*++ - -Routine Description: - - Set the file info. - -Arguments: - - FHand - The handle of the file. - BufferSize - Size of Buffer. - Buffer - Buffer containing write data. - -Returns: - - EFI_SUCCESS - Set the file info successfully. - EFI_WRITE_PROTECTED - The disk is write protected. - EFI_ACCESS_DENIED - The file is read-only. - EFI_DEVICE_ERROR - The OFile is not valid. - EFI_UNSUPPORTED - The open file is not a file. - - The writing file size is larger than 4GB. - other - An error occurred when operation the disk. - ---*/ ; +/** + + Get the file info. + + @param FHand - The handle of the file. + @param Token - A pointer to the token associated with the transaction. + + @retval EFI_SUCCESS - Get the file info successfully. + @retval EFI_DEVICE_ERROR - Can not find the OFile for the file. + @retval EFI_VOLUME_CORRUPTED - The file type of open file is error. + @return other - An error occurred when operation the disk. + +**/ EFI_STATUS EFIAPI FatWriteEx ( IN EFI_FILE_PROTOCOL *FHand, IN OUT EFI_FILE_IO_TOKEN *Token ) -/*++ - -Routine Description: - - Get the file info. - -Arguments: - - FHand - The handle of the file. - Token - A pointer to the token associated with the transaction. - -Returns: - - EFI_SUCCESS - Get the file info successfully. - EFI_DEVICE_ERROR - Can not find the OFile for the file. - EFI_VOLUME_CORRUPTED - The file type of open file is error. - other - An error occurred when operation the disk. - ---*/ ; // diff --git a/FatPkg/EnhancedFatDxe/FatFileSystem.h b/FatPkg/EnhancedFatDxe/FatFileSystem.h index 3f89a3410a..a4d44054e1 100644 --- a/FatPkg/EnhancedFatDxe/FatFileSystem.h +++ b/FatPkg/EnhancedFatDxe/FatFileSystem.h @@ -1,4 +1,5 @@ -/*++ +/** @file + Definitions for on-disk FAT structures. Copyright (c) 2005, Intel Corporation. All rights reserved.
This program and the accompanying materials are licensed and made available @@ -10,17 +11,7 @@ THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. -Module Name: - - FatFileSystem.h - -Abstract: - - Definitions for on-disk FAT structures - -Revision History - ---*/ +**/ #ifndef _FATFILESYSTEM_H_ #define _FATFILESYSTEM_H_ diff --git a/FatPkg/EnhancedFatDxe/FileName.c b/FatPkg/EnhancedFatDxe/FileName.c index f393aa6357..8aa37456ab 100644 --- a/FatPkg/EnhancedFatDxe/FileName.c +++ b/FatPkg/EnhancedFatDxe/FileName.c @@ -1,4 +1,5 @@ -/*++ +/** @file + Functions for manipulating file names. Copyright (c) 2005 - 2015, Intel Corporation. All rights reserved.
This program and the accompanying materials are licensed and made available @@ -9,45 +10,28 @@ http://opensource.org/licenses/bsd-license.php THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. - -Module Name: - - FileName.c - -Abstract: - - Functions for manipulating file names - -Revision History - ---*/ +**/ #include "Fat.h" -BOOLEAN -FatCheckIs8Dot3Name ( - IN CHAR16 *FileName, - OUT CHAR8 *File8Dot3Name - ) -/*++ - -Routine Description: +/** This function checks whether the input FileName is a valid 8.3 short name. If the input FileName is a valid 8.3, the output is the 8.3 short name; otherwise, the output is the base tag of 8.3 short name. -Arguments: + @param FileName - The input unicode filename. + @param File8Dot3Name - The output ascii 8.3 short name or base tag of 8.3 short name. - FileName - The input unicode filename. - File8Dot3Name - The output ascii 8.3 short name or base tag of 8.3 short name. + @retval TRUE - The input unicode filename is a valid 8.3 short name. + @retval FALSE - The input unicode filename is not a valid 8.3 short name. -Returns: - - TRUE - The input unicode filename is a valid 8.3 short name. - FALSE - The input unicode filename is not a valid 8.3 short name. - ---*/ +**/ +BOOLEAN +FatCheckIs8Dot3Name ( + IN CHAR16 *FileName, + OUT CHAR8 *File8Dot3Name + ) { BOOLEAN PossibleShortName; CHAR16 *TempName; @@ -118,28 +102,22 @@ Returns: return PossibleShortName; } +/** + + Trim the trailing blanks of fat name. + + @param Name - The Char8 string needs to be trimed. + @param Len - The length of the fat name. + + The real length of the fat name after the trailing blanks are trimmed. + +**/ STATIC UINTN FatTrimAsciiTrailingBlanks ( IN CHAR8 *Name, IN UINTN Len ) -/*++ - -Routine Description: - - Trim the trailing blanks of fat name. - -Arguments: - - Name - The Char8 string needs to be trimed. - Len - The length of the fat name. - -Returns: - - The real length of the fat name after the trailing blanks are trimmed. - ---*/ { while (Len > 0 && Name[Len - 1] == ' ') { Len--; @@ -148,6 +126,17 @@ Returns: return Len; } +/** + + Convert the ascii fat name to the unicode string and strip trailing spaces, + and if necessary, convert the unicode string to lower case. + + @param FatName - The Char8 string needs to be converted. + @param Len - The length of the fat name. + @param LowerCase - Indicate whether to convert the string to lower case. + @param Str - The result of the convertion. + +**/ VOID FatNameToStr ( IN CHAR8 *FatName, @@ -155,25 +144,6 @@ FatNameToStr ( IN UINTN LowerCase, OUT CHAR16 *Str ) -/*++ - -Routine Description: - - Convert the ascii fat name to the unicode string and strip trailing spaces, - and if necessary, convert the unicode string to lower case. - -Arguments: - - FatName - The Char8 string needs to be converted. - Len - The length of the fat name. - LowerCase - Indicate whether to convert the string to lower case. - Str - The result of the convertion. - -Returns: - - None. - ---*/ { // // First, trim the trailing blanks @@ -192,27 +162,19 @@ Returns: } } +/** + + This function generates 8Dot3 name from user specified name for a newly created file. + + @param Parent - The parent directory. + @param DirEnt - The directory entry whose 8Dot3Name needs to be generated. + +**/ VOID FatCreate8Dot3Name ( IN FAT_OFILE *Parent, IN FAT_DIRENT *DirEnt ) -/*++ - -Routine Description: - - This function generates 8Dot3 name from user specified name for a newly created file. - -Arguments: - - Parent - The parent directory. - DirEnt - The directory entry whose 8Dot3Name needs to be generated. - -Returns: - - None. - ---*/ { CHAR8 *ShortName; CHAR8 *ShortNameChar; @@ -275,29 +237,23 @@ Returns: } } +/** + + Check the string is lower case or upper case + and it is used by fatname to dir entry count + + @param Str - The string which needs to be checked. + @param InCaseFlag - The input case flag which is returned when the string is lower case. + + @retval OutCaseFlag - The output case flag. + +**/ STATIC UINT8 FatCheckNameCase ( IN CHAR16 *Str, IN UINT8 InCaseFlag ) -/*++ - -Routine Description: - - Check the string is lower case or upper case - and it is used by fatname to dir entry count - -Arguments: - - Str - The string which needs to be checked. - InCaseFlag - The input case flag which is returned when the string is lower case. - -Returns: - - OutCaseFlag - The output case flag. - ---*/ { CHAR16 Buffer[FAT_MAIN_NAME_LEN + 1 + FAT_EXTEND_NAME_LEN + 1]; UINT8 OutCaseFlag; @@ -328,25 +284,17 @@ Returns: return OutCaseFlag; } +/** + + Set the caseflag value for the directory entry. + + @param DirEnt - The logical directory entry whose caseflag value is to be set. + +**/ VOID FatSetCaseFlag ( IN FAT_DIRENT *DirEnt ) -/*++ - -Routine Description: - - Set the caseflag value for the directory entry. - -Arguments: - - DirEnt - The logical directory entry whose caseflag value is to be set. - -Returns: - - None. - ---*/ { CHAR16 LfnBuffer[FAT_MAIN_NAME_LEN + 1 + FAT_EXTEND_NAME_LEN + 1]; CHAR16 *TempCharPtr; @@ -389,28 +337,21 @@ Returns: } } +/** + + Convert the 8.3 ASCII fat name to cased Unicode string according to case flag. + + @param DirEnt - The corresponding directory entry. + @param FileString - The output Unicode file name. + @param FileStringMax The max length of FileString. + +**/ VOID FatGetFileNameViaCaseFlag ( IN FAT_DIRENT *DirEnt, IN OUT CHAR16 *FileString, IN UINTN FileStringMax ) -/*++ - -Routine Description: - - Convert the 8.3 ASCII fat name to cased Unicode string according to case flag. - -Arguments: - - DirEnt - The corresponding directory entry. - FileString - The output Unicode file name. - -Returns: - - None. - ---*/ { UINT8 CaseFlag; CHAR8 *File8Dot3Name; @@ -429,25 +370,19 @@ Returns: } } +/** + + Get the Check sum for a short name. + + @param ShortNameString - The short name for a file. + + @retval Sum - UINT8 checksum. + +**/ UINT8 FatCheckSum ( IN CHAR8 *ShortNameString ) -/*++ - -Routine Description: - - Get the Check sum for a short name. - -Arguments: - - ShortNameString - The short name for a file. - -Returns: - - Sum - UINT8 checksum. - ---*/ { UINTN ShortNameLen; UINT8 Sum; @@ -459,29 +394,23 @@ Returns: return Sum; } -CHAR16 * -FatGetNextNameComponent ( - IN CHAR16 *Path, - OUT CHAR16 *Name - ) -/*++ - -Routine Description: +/** Takes Path as input, returns the next name component in Name, and returns the position after Name (e.g., the start of the next name component) -Arguments: - - Path - The path of one file. - Name - The next name component in Path. - -Returns: + @param Path - The path of one file. + @param Name - The next name component in Path. The position after Name in the Path ---*/ +**/ +CHAR16 * +FatGetNextNameComponent ( + IN CHAR16 *Path, + OUT CHAR16 *Name + ) { while (*Path != 0 && *Path != PATH_NAME_SEPARATOR) { *Name++ = *Path++; @@ -497,31 +426,24 @@ Returns: return Path; } -BOOLEAN -FatFileNameIsValid ( - IN CHAR16 *InputFileName, - OUT CHAR16 *OutputFileName - ) -/*++ - -Routine Description: +/** Check whether the IFileName is valid long file name. If the IFileName is a valid long file name, then we trim the possible leading blanks and leading/trailing dots. the trimmed filename is stored in OutputFileName -Arguments: + @param InputFileName - The input file name. + @param OutputFileName - The output file name. - InputFileName - The input file name. - OutputFileName - The output file name. + @retval TRUE - The InputFileName is a valid long file name. + @retval FALSE - The InputFileName is not a valid long file name. - -Returns: - - TRUE - The InputFileName is a valid long file name. - FALSE - The InputFileName is not a valid long file name. - ---*/ +**/ +BOOLEAN +FatFileNameIsValid ( + IN CHAR16 *InputFileName, + OUT CHAR16 *OutputFileName + ) { CHAR16 *TempNamePointer; CHAR16 TempChar; diff --git a/FatPkg/EnhancedFatDxe/FileSpace.c b/FatPkg/EnhancedFatDxe/FileSpace.c index db44a331a8..1254cd68b5 100644 --- a/FatPkg/EnhancedFatDxe/FileSpace.c +++ b/FatPkg/EnhancedFatDxe/FileSpace.c @@ -1,4 +1,5 @@ -/*++ +/** @file + Routines dealing with disk spaces and FAT table entries. Copyright (c) 2005 - 2013, Intel Corporation. All rights reserved.
This program and the accompanying materials are licensed and made available @@ -10,43 +11,28 @@ THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. -Module Name: - FileSpace.c - -Abstract: - - Routines dealing with disk spaces and FAT table entries - -Revision History - ---*/ +**/ #include "Fat.h" +/** + + Get the FAT entry of the volume, which is identified with the Index. + + @param Volume - FAT file system volume. + @param Index - The index of the FAT entry of the volume. + + @return The buffer of the FAT entry + +**/ STATIC VOID * FatLoadFatEntry ( IN FAT_VOLUME *Volume, IN UINTN Index ) -/*++ - -Routine Description: - - Get the FAT entry of the volume, which is identified with the Index. - -Arguments: - - Volume - FAT file system volume. - Index - The index of the FAT entry of the volume. - -Returns: - - The buffer of the FAT entry - ---*/ { UINTN Pos; EFI_STATUS Status; @@ -89,28 +75,22 @@ Returns: return &Volume->FatEntryBuffer; } +/** + + Get the FAT entry value of the volume, which is identified with the Index. + + @param Volume - FAT file system volume. + @param Index - The index of the FAT entry of the volume. + + @return The value of the FAT entry. + +**/ STATIC UINTN FatGetFatEntry ( IN FAT_VOLUME *Volume, IN UINTN Index ) -/*++ - -Routine Description: - - Get the FAT entry value of the volume, which is identified with the Index. - -Arguments: - - Volume - FAT file system volume. - Index - The index of the FAT entry of the volume. - -Returns: - - The value of the FAT entry. - ---*/ { VOID *Pos; UINT8 *En12; @@ -147,6 +127,19 @@ Returns: return Accum; } +/** + + Set the FAT entry value of the volume, which is identified with the Index. + + @param Volume - FAT file system volume. + @param Index - The index of the FAT entry of the volume. + @param Value - The new value of the FAT entry. + + @retval EFI_SUCCESS - Set the new FAT entry value sucessfully. + @retval EFI_VOLUME_CORRUPTED - The FAT type of the volume is error. + @return other - An error occurred when operation the FAT entries. + +**/ STATIC EFI_STATUS FatSetFatEntry ( @@ -154,25 +147,6 @@ FatSetFatEntry ( IN UINTN Index, IN UINTN Value ) -/*++ - -Routine Description: - - Set the FAT entry value of the volume, which is identified with the Index. - -Arguments: - - Volume - FAT file system volume. - Index - The index of the FAT entry of the volume. - Value - The new value of the FAT entry. - -Returns: - - EFI_SUCCESS - Set the new FAT entry value sucessfully. - EFI_VOLUME_CORRUPTED - The FAT type of the volume is error. - other - An error occurred when operation the FAT entries. - ---*/ { VOID *Pos; UINT8 *En12; @@ -253,29 +227,23 @@ Returns: return Status; } +/** + + Free the cluster clain. + + @param Volume - FAT file system volume. + @param Cluster - The first cluster of cluster chain. + + @retval EFI_SUCCESS - The cluster chain is freed successfully. + @retval EFI_VOLUME_CORRUPTED - There are errors in the file's clusters. + +**/ STATIC EFI_STATUS FatFreeClusters ( IN FAT_VOLUME *Volume, IN UINTN Cluster ) -/*++ - -Routine Description: - - Free the cluster clain. - -Arguments: - - Volume - FAT file system volume. - Cluster - The first cluster of cluster chain. - -Returns: - - EFI_SUCCESS - The cluster chain is freed successfully. - EFI_VOLUME_CORRUPTED - There are errors in the file's clusters. - ---*/ { UINTN LastCluster; @@ -294,26 +262,20 @@ Returns: return EFI_SUCCESS; } +/** + + Allocate a free cluster and return the cluster index. + + @param Volume - FAT file system volume. + + @return The index of the free cluster + +**/ STATIC UINTN FatAllocateCluster ( IN FAT_VOLUME *Volume ) -/*++ - -Routine Description: - - Allocate a free cluster and return the cluster index. - -Arguments: - - Volume - FAT file system volume. - -Returns: - - The index of the free cluster - ---*/ { UINTN Cluster; @@ -354,28 +316,22 @@ Returns: return Cluster; } +/** + + Count the number of clusters given a size. + + @param Volume - The file system volume. + @param Size - The size in bytes. + + @return The number of the clusters. + +**/ STATIC UINTN FatSizeToClusters ( IN FAT_VOLUME *Volume, IN UINTN Size ) -/*++ - -Routine Description: - - Count the number of clusters given a size - -Arguments: - - Volume - The file system volume. - Size - The size in bytes. - -Returns: - - The number of the clusters. - ---*/ { UINTN Clusters; @@ -387,26 +343,20 @@ Returns: return Clusters; } +/** + + Shrink the end of the open file base on the file size. + + @param OFile - The open file. + + @retval EFI_SUCCESS - Shrinked sucessfully. + @retval EFI_VOLUME_CORRUPTED - There are errors in the file's clusters. + +**/ EFI_STATUS FatShrinkEof ( IN FAT_OFILE *OFile ) -/*++ - -Routine Description: - - Shrink the end of the open file base on the file size. - -Arguments: - - OFile - The open file. - -Returns: - - EFI_SUCCESS - Shrinked sucessfully. - EFI_VOLUME_CORRUPTED - There are errors in the file's clusters. - ---*/ { FAT_VOLUME *Volume; UINTN NewSize; @@ -465,30 +415,24 @@ Returns: return FatFreeClusters (Volume, Cluster); } +/** + + Grow the end of the open file base on the NewSizeInBytes. + + @param OFile - The open file. + @param NewSizeInBytes - The new size in bytes of the open file. + + @retval EFI_SUCCESS - The file is grown sucessfully. + @retval EFI_UNSUPPORTED - The file size is larger than 4GB. + @retval EFI_VOLUME_CORRUPTED - There are errors in the files' clusters. + @retval EFI_VOLUME_FULL - The volume is full and can not grow the file. + +**/ EFI_STATUS FatGrowEof ( IN FAT_OFILE *OFile, IN UINT64 NewSizeInBytes ) -/*++ - -Routine Description: - - Grow the end of the open file base on the NewSizeInBytes. - -Arguments: - - OFile - The open file. - NewSizeInBytes - The new size in bytes of the open file. - -Returns: - - EFI_SUCCESS - The file is grown sucessfully. - EFI_UNSUPPORTED - The file size is larger than 4GB. - EFI_VOLUME_CORRUPTED - There are errors in the files' clusters. - EFI_VOLUME_FULL - The volume is full and can not grow the file. - ---*/ { FAT_VOLUME *Volume; EFI_STATUS Status; @@ -591,31 +535,25 @@ Done: return Status; } +/** + + Seek OFile to requested position, and calculate the number of + consecutive clusters from the position in the file + + @param OFile - The open file. + @param Position - The file's position which will be accessed. + @param PosLimit - The maximum length current reading/writing may access + + @retval EFI_SUCCESS - Set the info successfully. + @retval EFI_VOLUME_CORRUPTED - Cluster chain corrupt. + +**/ EFI_STATUS FatOFilePosition ( IN FAT_OFILE *OFile, IN UINTN Position, IN UINTN PosLimit ) -/*++ - -Routine Description: - - Seek OFile to requested position, and calculate the number of - consecutive clusters from the position in the file - -Arguments: - - OFile - The open file. - Position - The file's position which will be accessed. - PosLimit - The maximum length current reading/writing may access - -Returns: - - EFI_SUCCESS - Set the info successfully. - EFI_VOLUME_CORRUPTED - Cluster chain corrupt. - ---*/ { FAT_VOLUME *Volume; UINTN ClusterSize; @@ -691,28 +629,22 @@ Returns: return EFI_SUCCESS; } +/** + + Get the size of directory of the open file. + + @param Volume - The File System Volume. + @param Cluster - The Starting cluster. + + @return The physical size of the file starting at the input cluster, if there is error in the + cluster chain, the return value is 0. + +**/ UINTN FatPhysicalDirSize ( IN FAT_VOLUME *Volume, IN UINTN Cluster ) -/*++ - -Routine Description: - - Get the size of directory of the open file - -Arguments: - - Volume - The File System Volume. - Cluster - The Starting cluster. - -Returns: - - The physical size of the file starting at the input cluster, if there is error in the - cluster chain, the return value is 0. - ---*/ { UINTN Size; ASSERT_VOLUME_LOCKED (Volume); @@ -742,27 +674,21 @@ Returns: return Size; } +/** + + Get the physical size of a file on the disk. + + @param Volume - The file system volume. + @param RealSize - The real size of a file. + + @return The physical size of a file on the disk. + +**/ UINT64 FatPhysicalFileSize ( IN FAT_VOLUME *Volume, IN UINTN RealSize ) -/*++ - -Routine Description: - - Get the physical size of a file on the disk. - -Arguments: - - Volume - The file system volume. - RealSize - The real size of a file. - -Returns: - - The physical size of a file on the disk. - ---*/ { UINTN ClusterSizeMask; UINT64 PhysicalSize; @@ -771,25 +697,17 @@ Returns: return PhysicalSize; } +/** + + Update the free cluster info of FatInfoSector of the volume. + + @param Volume - FAT file system volume. + +**/ VOID FatComputeFreeInfo ( IN FAT_VOLUME *Volume ) -/*++ - -Routine Description: - - Update the free cluster info of FatInfoSector of the volume. - -Arguments: - - Volume - FAT file system volume. - -Returns: - - None. - ---*/ { UINTN Index; diff --git a/FatPkg/EnhancedFatDxe/Flush.c b/FatPkg/EnhancedFatDxe/Flush.c index 172f2023da..9cb0d9ac18 100644 --- a/FatPkg/EnhancedFatDxe/Flush.c +++ b/FatPkg/EnhancedFatDxe/Flush.c @@ -1,4 +1,5 @@ -/*++ +/** @file + Routines that check references and flush OFiles Copyright (c) 2005 - 2013, Intel Corporation. All rights reserved.
This program and the accompanying materials are licensed and made available @@ -10,45 +11,29 @@ THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. -Module Name: - - flush.c - -Abstract: - - Routines that check references and flush OFiles - -Revision History - ---*/ +**/ #include "Fat.h" +/** + + Flushes all data associated with the file handle. + + @param FHand - Handle to file to flush. + @param Token - A pointer to the token associated with the transaction. + + @retval EFI_SUCCESS - Flushed the file successfully. + @retval EFI_WRITE_PROTECTED - The volume is read only. + @retval EFI_ACCESS_DENIED - The file is read only. + @return Others - Flushing of the file failed. + +**/ EFI_STATUS EFIAPI FatFlushEx ( IN EFI_FILE_PROTOCOL *FHand, IN EFI_FILE_IO_TOKEN *Token ) -/*++ - -Routine Description: - - Flushes all data associated with the file handle. - -Arguments: - - FHand - Handle to file to flush. - Token - A pointer to the token associated with the transaction. - -Returns: - - EFI_SUCCESS - Flushed the file successfully. - EFI_WRITE_PROTECTED - The volume is read only. - EFI_ACCESS_DENIED - The file is read only. - Others - Flushing of the file failed. - ---*/ { FAT_IFILE *IFile; FAT_OFILE *OFile; @@ -113,53 +98,41 @@ Returns: return Status; } +/** + + Flushes all data associated with the file handle. + + @param FHand - Handle to file to flush. + + @retval EFI_SUCCESS - Flushed the file successfully. + @retval EFI_WRITE_PROTECTED - The volume is read only. + @retval EFI_ACCESS_DENIED - The file is read only. + @return Others - Flushing of the file failed. + +**/ EFI_STATUS EFIAPI FatFlush ( IN EFI_FILE_PROTOCOL *FHand ) -/*++ - -Routine Description: - - Flushes all data associated with the file handle. - -Arguments: - - FHand - Handle to file to flush. - -Returns: - - EFI_SUCCESS - Flushed the file successfully. - EFI_WRITE_PROTECTED - The volume is read only. - EFI_ACCESS_DENIED - The file is read only. - Others - Flushing of the file failed. - ---*/ { return FatFlushEx (FHand, NULL); } +/** + + Flushes & Closes the file handle. + + @param FHand - Handle to the file to delete. + + @retval EFI_SUCCESS - Closed the file successfully. + +**/ EFI_STATUS EFIAPI FatClose ( IN EFI_FILE_PROTOCOL *FHand ) -/*++ - -Routine Description: - - Flushes & Closes the file handle. - -Arguments: - - FHand - Handle to the file to delete. - -Returns: - - EFI_SUCCESS - Closed the file successfully. - ---*/ { FAT_IFILE *IFile; FAT_OFILE *OFile; @@ -191,25 +164,19 @@ Returns: return EFI_SUCCESS; } +/** + + Close the open file instance. + + @param IFile - Open file instance. + + @retval EFI_SUCCESS - Closed the file successfully. + +**/ EFI_STATUS FatIFileClose ( FAT_IFILE *IFile ) -/*++ - -Routine Description: - - Close the open file instance. - -Arguments: - - IFile - Open file instance. - -Returns: - - EFI_SUCCESS - Closed the file successfully. - ---*/ { FAT_OFILE *OFile; FAT_VOLUME *Volume; @@ -239,27 +206,21 @@ Returns: return EFI_SUCCESS; } -EFI_STATUS -FatOFileFlush ( - IN FAT_OFILE *OFile - ) -/*++ - -Routine Description: +/** Flush the data associated with an open file. In this implementation, only last Mod/Access time is updated. -Arguments: + @param OFile - The open file. - OFile - The open file. + @retval EFI_SUCCESS - The OFile is flushed successfully. + @return Others - An error occurred when flushing this OFile. -Returns: - - EFI_SUCCESS - The OFile is flushed successfully. - Others - An error occurred when flushing this OFile. - ---*/ +**/ +EFI_STATUS +FatOFileFlush ( + IN FAT_OFILE *OFile + ) { EFI_STATUS Status; FAT_OFILE *Parent; @@ -318,28 +279,22 @@ Returns: return EFI_SUCCESS; } -BOOLEAN -FatCheckOFileRef ( - IN FAT_OFILE *OFile - ) -/*++ - -Routine Description: +/** Check the references of the OFile. If the OFile (that is checked) is no longer referenced, then it is freed. -Arguments: + @param OFile - The OFile to be checked. - OFile - The OFile to be checked. + @retval TRUE - The OFile is not referenced and freed. + @retval FALSE - The OFile is kept. -Returns: - - TRUE - The OFile is not referenced and freed. - FALSE - The OFile is kept. - ---*/ +**/ +BOOLEAN +FatCheckOFileRef ( + IN FAT_OFILE *OFile + ) { // // If the OFile is on the check ref list, remove it @@ -366,29 +321,21 @@ Returns: return TRUE; } -STATIC -VOID -FatCheckVolumeRef ( - IN FAT_VOLUME *Volume - ) -/*++ - -Routine Description: +/** Check the references of all open files on the volume. Any open file (that is checked) that is no longer referenced, is freed - and it's parent open file is then referenced checked. -Arguments: + @param Volume - The volume to check the pending open file list. - Volume - The volume to check the pending open file list. - -Returns: - - None - ---*/ +**/ +STATIC +VOID +FatCheckVolumeRef ( + IN FAT_VOLUME *Volume + ) { FAT_OFILE *OFile; FAT_OFILE *Parent; @@ -414,6 +361,22 @@ Returns: } } +/** + + Set error status for a specific OFile, reference checking the volume. + If volume is already marked as invalid, and all resources are freed + after reference checking, the file system protocol is uninstalled and + the volume structure is freed. + + @param Volume - the Volume that is to be reference checked and unlocked. + @param OFile - the OFile whose permanent error code is to be set. + @param EfiStatus - error code to be set. + @param Task point to task instance. + + @retval EFI_SUCCESS - Clean up the volume successfully. + @return Others - Cleaning up of the volume is failed. + +**/ EFI_STATUS FatCleanupVolume ( IN FAT_VOLUME *Volume, @@ -421,27 +384,6 @@ FatCleanupVolume ( IN EFI_STATUS EfiStatus, IN FAT_TASK *Task ) -/*++ - -Routine Description: - - Set error status for a specific OFile, reference checking the volume. - If volume is already marked as invalid, and all resources are freed - after reference checking, the file system protocol is uninstalled and - the volume structure is freed. - -Arguments: - - Volume - the Volume that is to be reference checked and unlocked. - OFile - the OFile whose permanent error code is to be set. - EfiStatus - error code to be set. - -Returns: - - EFI_SUCCESS - Clean up the volume successfully. - Others - Cleaning up of the volume is failed. - ---*/ { EFI_STATUS Status; // @@ -499,27 +441,19 @@ Returns: return EfiStatus; } +/** + + Set the OFile and its child OFile with the error Status + + @param OFile - The OFile whose permanent error code is to be set. + @param Status - Error code to be set. + +**/ VOID FatSetVolumeError ( IN FAT_OFILE *OFile, IN EFI_STATUS Status ) -/*++ - -Routine Description: - - Set the OFile and its child OFile with the error Status - -Arguments: - - OFile - The OFile whose permanent error code is to be set. - Status - Error code to be set. - -Returns: - - None - ---*/ { LIST_ENTRY *Link; FAT_OFILE *ChildOFile; diff --git a/FatPkg/EnhancedFatDxe/Hash.c b/FatPkg/EnhancedFatDxe/Hash.c index f827368ef5..5a9bbda754 100644 --- a/FatPkg/EnhancedFatDxe/Hash.c +++ b/FatPkg/EnhancedFatDxe/Hash.c @@ -1,4 +1,5 @@ -/*++ +/** @file + Hash table operations. Copyright (c) 2005 - 2015, Intel Corporation. All rights reserved.
This program and the accompanying materials are licensed and made available @@ -9,41 +10,24 @@ http://opensource.org/licenses/bsd-license.php THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. - -Module Name: - - Hash.c - -Abstract: - - Hash table operations - -Revision History - ---*/ +**/ #include "Fat.h" +/** + + Get hash value for long name. + + @param LongNameString - The long name string to be hashed. + + @return HashValue. + +**/ STATIC UINT32 FatHashLongName ( IN CHAR16 *LongNameString ) -/*++ - -Routine Description: - - Get hash value for long name. - -Arguments: - - LongNameString - The long name string to be hashed. - -Returns: - - HashValue. - ---*/ { UINT32 HashValue; CHAR16 UpCasedLongFileName[EFI_PATH_STRING_LENGTH]; @@ -58,53 +42,41 @@ Returns: return (HashValue & HASH_TABLE_MASK); } +/** + + Get hash value for short name. + + @param ShortNameString - The short name string to be hashed. + + @return HashValue + +**/ STATIC UINT32 FatHashShortName ( IN CHAR8 *ShortNameString ) -/*++ - -Routine Description: - - Get hash value for short name. - -Arguments: - - ShortNameString - The short name string to be hashed. - -Returns: - - HashValue - ---*/ { UINT32 HashValue; gBS->CalculateCrc32 (ShortNameString, FAT_NAME_LEN, &HashValue); return (HashValue & HASH_TABLE_MASK); } +/** + + Search the long name hash table for the directory entry. + + @param ODir - The directory to be searched. + @param LongNameString - The long name string to search. + + @return The previous long name hash node of the directory entry. + +**/ FAT_DIRENT ** FatLongNameHashSearch ( IN FAT_ODIR *ODir, IN CHAR16 *LongNameString ) -/*++ - -Routine Description: - - Search the long name hash table for the directory entry. - -Arguments: - - ODir - The directory to be searched. - LongNameString - The long name string to search. - -Returns: - - The previous long name hash node of the directory entry. - ---*/ { FAT_DIRENT **PreviousHashNode; for (PreviousHashNode = &ODir->LongNameHashTable[FatHashLongName (LongNameString)]; @@ -119,27 +91,21 @@ Returns: return PreviousHashNode; } +/** + + Search the short name hash table for the directory entry. + + @param ODir - The directory to be searched. + @param ShortNameString - The short name string to search. + + @return The previous short name hash node of the directory entry. + +**/ FAT_DIRENT ** FatShortNameHashSearch ( IN FAT_ODIR *ODir, IN CHAR8 *ShortNameString ) -/*++ - -Routine Description: - - Search the short name hash table for the directory entry. - -Arguments: - - ODir - The directory to be searched. - ShortNameString - The short name string to search. - -Returns: - - The previous short name hash node of the directory entry. - ---*/ { FAT_DIRENT **PreviousHashNode; for (PreviousHashNode = &ODir->ShortNameHashTable[FatHashShortName (ShortNameString)]; @@ -154,27 +120,19 @@ Returns: return PreviousHashNode; } +/** + + Insert directory entry to hash table. + + @param ODir - The parent directory. + @param DirEnt - The directory entry node. + +**/ VOID FatInsertToHashTable ( IN FAT_ODIR *ODir, IN FAT_DIRENT *DirEnt ) -/*++ - -Routine Description: - - Insert directory entry to hash table. - -Arguments: - - ODir - The parent directory. - DirEnt - The directory entry node. - -Returns: - - None. - ---*/ { FAT_DIRENT **HashTable; UINT32 HashTableIndex; @@ -195,27 +153,19 @@ Returns: HashTable[HashTableIndex] = DirEnt; } +/** + + Delete directory entry from hash table. + + @param ODir - The parent directory. + @param DirEnt - The directory entry node. + +**/ VOID FatDeleteFromHashTable ( IN FAT_ODIR *ODir, IN FAT_DIRENT *DirEnt ) -/*++ - -Routine Description: - - Delete directory entry from hash table. - -Arguments: - - ODir - The parent directory. - DirEnt - The directory entry node. - -Returns: - - None. - ---*/ { *FatShortNameHashSearch (ODir, DirEnt->Entry.FileName) = DirEnt->ShortNameForwardLink; *FatLongNameHashSearch (ODir, DirEnt->FileString) = DirEnt->LongNameForwardLink; diff --git a/FatPkg/EnhancedFatDxe/Info.c b/FatPkg/EnhancedFatDxe/Info.c index aa1b0f245c..1a7f8280ba 100644 --- a/FatPkg/EnhancedFatDxe/Info.c +++ b/FatPkg/EnhancedFatDxe/Info.c @@ -1,4 +1,5 @@ -/*++ +/** @file + Routines dealing with setting/getting file/volume info Copyright (c) 2005 - 2015, Intel Corporation. All rights reserved.
This program and the accompanying materials are licensed and made available @@ -10,17 +11,8 @@ THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. -Module Name: - Info.c - -Abstract: - - Routines dealing with setting/getting file/volume info - -Revision History - ---*/ +**/ #include "Fat.h" @@ -47,58 +39,46 @@ FatSetOrGetInfo ( IN OUT VOID *Buffer ); +/** + + Get the open file's info into Buffer. + + @param OFile - The open file. + @param BufferSize - Size of Buffer. + @param Buffer - Buffer containing file info. + + @retval EFI_SUCCESS - Get the file info successfully. + @retval EFI_BUFFER_TOO_SMALL - The buffer is too small. + +**/ EFI_STATUS FatGetFileInfo ( IN FAT_OFILE *OFile, IN OUT UINTN *BufferSize, OUT VOID *Buffer ) -/*++ - -Routine Description: - - Get the open file's info into Buffer. - -Arguments: - - OFile - The open file. - BufferSize - Size of Buffer. - Buffer - Buffer containing file info. - -Returns: - - EFI_SUCCESS - Get the file info successfully. - EFI_BUFFER_TOO_SMALL - The buffer is too small. - ---*/ { return FatGetDirEntInfo (OFile->Volume, OFile->DirEnt, BufferSize, Buffer); } +/** + + Get the volume's info into Buffer. + + @param Volume - FAT file system volume. + @param BufferSize - Size of Buffer. + @param Buffer - Buffer containing volume info. + + @retval EFI_SUCCESS - Get the volume info successfully. + @retval EFI_BUFFER_TOO_SMALL - The buffer is too small. + +**/ EFI_STATUS FatGetVolumeInfo ( IN FAT_VOLUME *Volume, IN OUT UINTN *BufferSize, OUT VOID *Buffer ) -/*++ - -Routine Description: - - Get the volume's info into Buffer. - -Arguments: - - Volume - FAT file system volume. - BufferSize - Size of Buffer. - Buffer - Buffer containing volume info. - -Returns: - - EFI_SUCCESS - Get the volume info successfully. - EFI_BUFFER_TOO_SMALL - The buffer is too small. - ---*/ { UINTN Size; UINTN NameSize; @@ -141,30 +121,24 @@ Returns: return Status; } +/** + + Get the volume's label info into Buffer. + + @param Volume - FAT file system volume. + @param BufferSize - Size of Buffer. + @param Buffer - Buffer containing volume's label info. + + @retval EFI_SUCCESS - Get the volume's label info successfully. + @retval EFI_BUFFER_TOO_SMALL - The buffer is too small. + +**/ EFI_STATUS FatGetVolumeLabelInfo ( IN FAT_VOLUME *Volume, IN OUT UINTN *BufferSize, OUT VOID *Buffer ) -/*++ - -Routine Description: - - Get the volume's label info into Buffer. - -Arguments: - - Volume - FAT file system volume. - BufferSize - Size of Buffer. - Buffer - Buffer containing volume's label info. - -Returns: - - EFI_SUCCESS - Get the volume's label info successfully. - EFI_BUFFER_TOO_SMALL - The buffer is too small. - ---*/ { UINTN Size; UINTN NameSize; @@ -187,32 +161,26 @@ Returns: return Status; } +/** + + Set the volume's info. + + @param Volume - FAT file system volume. + @param BufferSize - Size of Buffer. + @param Buffer - Buffer containing the new volume info. + + @retval EFI_SUCCESS - Set the volume info successfully. + @retval EFI_BAD_BUFFER_SIZE - The buffer size is error. + @retval EFI_WRITE_PROTECTED - The volume is read only. + @return other - An error occurred when operation the disk. + +**/ EFI_STATUS FatSetVolumeInfo ( IN FAT_VOLUME *Volume, IN UINTN BufferSize, IN VOID *Buffer ) -/*++ - -Routine Description: - - Set the volume's info. - -Arguments: - - Volume - FAT file system volume. - BufferSize - Size of Buffer. - Buffer - Buffer containing the new volume info. - -Returns: - - EFI_SUCCESS - Set the volume info successfully. - EFI_BAD_BUFFER_SIZE - The buffer size is error. - EFI_WRITE_PROTECTED - The volume is read only. - other - An error occurred when operation the disk. - ---*/ { EFI_FILE_SYSTEM_INFO *Info; @@ -225,32 +193,26 @@ Returns: return FatSetVolumeEntry (Volume, Info->VolumeLabel); } +/** + + Set the volume's label info. + + @param Volume - FAT file system volume. + @param BufferSize - Size of Buffer. + @param Buffer - Buffer containing the new volume label info. + + @retval EFI_SUCCESS - Set the volume label info successfully. + @retval EFI_WRITE_PROTECTED - The disk is write protected. + @retval EFI_BAD_BUFFER_SIZE - The buffer size is error. + @return other - An error occurred when operation the disk. + +**/ EFI_STATUS FatSetVolumeLabelInfo ( IN FAT_VOLUME *Volume, IN UINTN BufferSize, IN VOID *Buffer ) -/*++ - -Routine Description: - - Set the volume's label info - -Arguments: - - Volume - FAT file system volume. - BufferSize - Size of Buffer. - Buffer - Buffer containing the new volume label info. - -Returns: - - EFI_SUCCESS - Set the volume label info successfully. - EFI_WRITE_PROTECTED - The disk is write protected. - EFI_BAD_BUFFER_SIZE - The buffer size is error. - other - An error occurred when operation the disk. - ---*/ { EFI_FILE_SYSTEM_VOLUME_LABEL *Info; @@ -263,6 +225,30 @@ Returns: return FatSetVolumeEntry (Volume, Info->VolumeLabel); } +/** + + Set the file info. + + @param Volume - FAT file system volume. + @param IFile - The instance of the open file. + @param OFile - The open file. + @param BufferSize - Size of Buffer. + @param Buffer - Buffer containing the new file info. + + @retval EFI_SUCCESS - Set the file info successfully. + @retval EFI_ACCESS_DENIED - It is the root directory + or the directory attribute bit can not change + or try to change a directory size + or something else. + @retval EFI_UNSUPPORTED - The new file size is larger than 4GB. + @retval EFI_WRITE_PROTECTED - The disk is write protected. + @retval EFI_BAD_BUFFER_SIZE - The buffer size is error. + @retval EFI_INVALID_PARAMETER - The time info or attributes info is error. + @retval EFI_OUT_OF_RESOURCES - Can not allocate new memory. + @retval EFI_VOLUME_CORRUPTED - The volume is corrupted. + @return other - An error occurred when operation the disk. + +**/ EFI_STATUS FatSetFileInfo ( IN FAT_VOLUME *Volume, @@ -271,36 +257,6 @@ FatSetFileInfo ( IN UINTN BufferSize, IN VOID *Buffer ) -/*++ - -Routine Description: - - Set the file info. - -Arguments: - - Volume - FAT file system volume. - IFile - The instance of the open file. - OFile - The open file. - BufferSize - Size of Buffer. - Buffer - Buffer containing the new file info. - -Returns: - - EFI_SUCCESS - Set the file info successfully. - EFI_ACCESS_DENIED - It is the root directory - or the directory attribute bit can not change - or try to change a directory size - or something else. - EFI_UNSUPPORTED - The new file size is larger than 4GB. - EFI_WRITE_PROTECTED - The disk is write protected. - EFI_BAD_BUFFER_SIZE - The buffer size is error. - EFI_INVALID_PARAMETER - The time info or attributes info is error. - EFI_OUT_OF_RESOURCES - Can not allocate new memory. - EFI_VOLUME_CORRUPTED - The volume is corrupted. - other - An error occurred when operation the disk. - ---*/ { EFI_STATUS Status; EFI_FILE_INFO *NewInfo; @@ -472,6 +428,20 @@ Returns: return FatOFileFlush (OFile); } +/** + + Set or Get the some types info of the file into Buffer. + + @param IsSet - TRUE:The access is set, else is get + @param FHand - The handle of file + @param Type - The type of the info + @param BufferSize - Size of Buffer + @param Buffer - Buffer containing volume info + + @retval EFI_SUCCESS - Get the info successfully + @retval EFI_DEVICE_ERROR - Can not find the OFile for the file + +**/ EFI_STATUS FatSetOrGetInfo ( IN BOOLEAN IsSet, @@ -480,26 +450,6 @@ FatSetOrGetInfo ( IN OUT UINTN *BufferSize, IN OUT VOID *Buffer ) -/*++ - -Routine Description: - - Set or Get the some types info of the file into Buffer - -Arguments: - - IsSet - TRUE:The access is set, else is get - FHand - The handle of file - Type - The type of the info - BufferSize - Size of Buffer - Buffer - Buffer containing volume info - -Returns: - - EFI_SUCCESS - Get the info successfully - EFI_DEVICE_ERROR - Can not find the OFile for the file - ---*/ { FAT_IFILE *IFile; FAT_OFILE *OFile; @@ -560,6 +510,19 @@ Returns: return Status; } +/** + + Get the some types info of the file into Buffer. + + @param FHand - The handle of file. + @param Type - The type of the info. + @param BufferSize - Size of Buffer. + @param Buffer - Buffer containing volume info. + + @retval EFI_SUCCESS - Get the info successfully. + @retval EFI_DEVICE_ERROR - Can not find the OFile for the file. + +**/ EFI_STATUS EFIAPI FatGetInfo ( @@ -568,29 +531,23 @@ FatGetInfo ( IN OUT UINTN *BufferSize, OUT VOID *Buffer ) -/*++ - -Routine Description: - - Get the some types info of the file into Buffer. - -Arguments: - - FHand - The handle of file. - Type - The type of the info. - BufferSize - Size of Buffer. - Buffer - Buffer containing volume info. - -Returns: - - EFI_SUCCESS - Get the info successfully. - EFI_DEVICE_ERROR - Can not find the OFile for the file. - ---*/ { return FatSetOrGetInfo (FALSE, FHand, Type, BufferSize, Buffer); } +/** + + Set the some types info of the file into Buffer. + + @param FHand - The handle of file. + @param Type - The type of the info. + @param BufferSize - Size of Buffer + @param Buffer - Buffer containing volume info. + + @retval EFI_SUCCESS - Set the info successfully. + @retval EFI_DEVICE_ERROR - Can not find the OFile for the file. + +**/ EFI_STATUS EFIAPI FatSetInfo ( @@ -599,25 +556,6 @@ FatSetInfo ( IN UINTN BufferSize, IN VOID *Buffer ) -/*++ - -Routine Description: - - Set the some types info of the file into Buffer. - -Arguments: - - FHand - The handle of file. - Type - The type of the info. - BufferSize - Size of Buffer - Buffer - Buffer containing volume info. - -Returns: - - EFI_SUCCESS - Set the info successfully. - EFI_DEVICE_ERROR - Can not find the OFile for the file. - ---*/ { return FatSetOrGetInfo (TRUE, FHand, Type, &BufferSize, Buffer); } diff --git a/FatPkg/EnhancedFatDxe/Init.c b/FatPkg/EnhancedFatDxe/Init.c index d7cfa823c8..6febffcddd 100644 --- a/FatPkg/EnhancedFatDxe/Init.c +++ b/FatPkg/EnhancedFatDxe/Init.c @@ -1,4 +1,5 @@ -/*++ +/** @file + Initialization routines. Copyright (c) 2005 - 2013, Intel Corporation. All rights reserved.
This program and the accompanying materials are licensed and made available @@ -9,19 +10,25 @@ http://opensource.org/licenses/bsd-license.php THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. - -Module Name: - - Init.c - -Abstract: - - Initialization routines - ---*/ +**/ #include "Fat.h" +/** + + Allocates volume structure, detects FAT file system, installs protocol, + and initialize cache. + + @param Handle - The handle of parent device. + @param DiskIo - The DiskIo of parent device. + @param DiskIo2 - The DiskIo2 of parent device. + @param BlockIo - The BlockIo of parent devicel + + @retval EFI_SUCCESS - Allocate a new volume successfully. + @retval EFI_OUT_OF_RESOURCES - Can not allocate the memory. + @return Others - Allocating a new volume failed. + +**/ EFI_STATUS FatAllocateVolume ( IN EFI_HANDLE Handle, @@ -29,26 +36,6 @@ FatAllocateVolume ( IN EFI_DISK_IO2_PROTOCOL *DiskIo2, IN EFI_BLOCK_IO_PROTOCOL *BlockIo ) -/*++ - -Routine Description: - - Allocates volume structure, detects FAT file system, installs protocol, - and initialize cache. - -Arguments: - - Handle - The handle of parent device. - DiskIo - The DiskIo of parent device. - BlockIo - The BlockIo of parent devicel - -Returns: - - EFI_SUCCESS - Allocate a new volume successfully. - EFI_OUT_OF_RESOURCES - Can not allocate the memory. - Others - Allocating a new volume failed. - ---*/ { EFI_STATUS Status; FAT_VOLUME *Volume; @@ -120,26 +107,20 @@ Done: return Status; } +/** + + Called by FatDriverBindingStop(), Abandon the volume. + + @param Volume - The volume to be abandoned. + + @retval EFI_SUCCESS - Abandoned the volume successfully. + @return Others - Can not uninstall the protocol interfaces. + +**/ EFI_STATUS FatAbandonVolume ( IN FAT_VOLUME *Volume ) -/*++ - -Routine Description: - - Called by FatDriverBindingStop(), Abandon the volume. - -Arguments: - - Volume - The volume to be abandoned. - -Returns: - - EFI_SUCCESS - Abandoned the volume successfully. - Others - Can not uninstall the protocol interfaces. - ---*/ { EFI_STATUS Status; BOOLEAN LockedByMe; @@ -202,27 +183,21 @@ Returns: return EFI_SUCCESS; } +/** + + Detects FAT file system on Disk and set relevant fields of Volume. + + @param Volume - The volume structure. + + @retval EFI_SUCCESS - The Fat File System is detected successfully + @retval EFI_UNSUPPORTED - The volume is not FAT file system. + @retval EFI_VOLUME_CORRUPTED - The volume is corrupted. + +**/ EFI_STATUS FatOpenDevice ( IN OUT FAT_VOLUME *Volume ) -/*++ - -Routine Description: - - Detects FAT file system on Disk and set relevant fields of Volume - -Arguments: - - Volume - The volume structure. - -Returns: - - EFI_SUCCESS - The Fat File System is detected successfully - EFI_UNSUPPORTED - The volume is not FAT file system. - EFI_VOLUME_CORRUPTED - The volume is corrupted. - ---*/ { EFI_STATUS Status; UINT32 BlockSize; diff --git a/FatPkg/EnhancedFatDxe/Misc.c b/FatPkg/EnhancedFatDxe/Misc.c index c5476e8ff8..c035670bf7 100644 --- a/FatPkg/EnhancedFatDxe/Misc.c +++ b/FatPkg/EnhancedFatDxe/Misc.c @@ -1,4 +1,5 @@ -/*++ +/** @file + Miscellaneous functions. Copyright (c) 2005 - 2013, Intel Corporation. All rights reserved.
This program and the accompanying materials are licensed and made available @@ -10,40 +11,26 @@ THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. -Module Name: - - Misc.c - -Abstract: - - Miscellaneous functions - -Revision History - ---*/ +**/ #include "Fat.h" UINT8 mMonthDays[] = { 31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31 }; +/** + + Create the task + + @param IFile - The instance of the open file. + @param Token - A pointer to the token associated with the transaction. + + @return FAT_TASK * - Return the task instance. + +**/ FAT_TASK * FatCreateTask ( FAT_IFILE *IFile, EFI_FILE_IO_TOKEN *Token ) -/*++ - -Routine Description: - - Create the task - -Arguments: - - IFile - The instance of the open file. - Token - A pointer to the token associated with the transaction. - -Return: - FAT_TASK * - Return the task instance. -**/ { FAT_TASK *Task; @@ -58,20 +45,17 @@ Return: return Task; } +/** + + Destroy the task. + + @param Task - The task to be destroyed. + +**/ VOID FatDestroyTask ( FAT_TASK *Task ) -/*++ - -Routine Description: - - Destroy the task - -Arguments: - - Task - The task to be destroyed. -**/ { LIST_ENTRY *Link; FAT_SUBTASK *Subtask; @@ -84,20 +68,17 @@ Arguments: FreePool (Task); } +/** + + Wait all non-blocking requests complete. + + @param IFile - The instance of the open file. + +**/ VOID FatWaitNonblockingTask ( FAT_IFILE *IFile ) -/*++ - -Routine Description: - - Wait all non-blocking requests complete. - -Arguments: - - IFile - The instance of the open file. -**/ { BOOLEAN TaskQueueEmpty; @@ -108,25 +89,19 @@ Arguments: } while (!TaskQueueEmpty); } +/** + + Remove the subtask from subtask list. + + @param Subtask - The subtask to be removed. + + @return LIST_ENTRY * - The next node in the list. + +**/ LIST_ENTRY * FatDestroySubtask ( FAT_SUBTASK *Subtask ) -/*++ - -Routine Description: - - Remove the subtask from subtask list. - -Arguments: - - Subtask - The subtask to be removed. - -Returns: - - LIST_ENTRY * - The next node in the list. - ---*/ { LIST_ENTRY *Link; @@ -138,28 +113,22 @@ Returns: return Link; } +/** + + Execute the task. + + @param IFile - The instance of the open file. + @param Task - The task to be executed. + + @retval EFI_SUCCESS - The task was executed sucessfully. + @return other - An error occurred when executing the task. + +**/ EFI_STATUS FatQueueTask ( IN FAT_IFILE *IFile, IN FAT_TASK *Task ) -/*++ - -Routine Description: - - Execute the task - -Arguments: - - IFile - The instance of the open file. - Task - The task to be executed. - -Returns: - - EFI_SUCCESS - The task was executed sucessfully. - other - An error occurred when executing the task. - ---*/ { EFI_STATUS Status; LIST_ENTRY *Link; @@ -239,30 +208,24 @@ Returns: return Status; } +/** + + Set the volume as dirty or not. + + @param Volume - FAT file system volume. + @param IoMode - The access mode. + @param DirtyValue - Set the volume as dirty or not. + + @retval EFI_SUCCESS - Set the new FAT entry value sucessfully. + @return other - An error occurred when operation the FAT entries. + +**/ EFI_STATUS FatAccessVolumeDirty ( IN FAT_VOLUME *Volume, IN IO_MODE IoMode, IN VOID *DirtyValue ) -/*++ - -Routine Description: - - Set the volume as dirty or not - -Arguments: - - Volume - FAT file system volume. - IoMode - The access mode. - DirtyValue - Set the volume as dirty or not. - -Returns: - - EFI_SUCCESS - Set the new FAT entry value sucessfully. - other - An error occurred when operation the FAT entries. - ---*/ { UINTN WriteCount; @@ -271,7 +234,7 @@ Returns: } /** - Invoke a notification event + Invoke a notification event. @param Event Event whose notification function is being invoked. @param Context The pointer to the notification function's context, @@ -284,22 +247,6 @@ FatOnAccessComplete ( IN EFI_EVENT Event, IN VOID *Context ) -/*++ - -Routine Description: - - Invoke a notification event - case #1. some subtasks are not completed when the FatOpenEx checks the Task->Subtasks - - sets Task->SubtaskCollected so callback to signal the event and free the task. - case #2. all subtasks are completed when the FatOpenEx checks the Task->Subtasks - - FatOpenEx signal the event and free the task. -Arguments: - - Event - Event whose notification function is being invoked. - Context - The pointer to the notification function's context, - which is implementation-dependent. - ---*/ { EFI_STATUS Status; FAT_SUBTASK *Subtask; @@ -342,6 +289,22 @@ Arguments: } } +/** + + General disk access function. + + @param Volume - FAT file system volume. + @param IoMode - The access mode (disk read/write or cache access). + @param Offset - The starting byte offset to read from. + @param BufferSize - Size of Buffer. + @param Buffer - Buffer containing read data. + @param Task point to task instance. + + @retval EFI_SUCCESS - The operation is performed successfully. + @retval EFI_VOLUME_CORRUPTED - The accesss is + @return Others - The status of read/write the disk + +**/ EFI_STATUS FatDiskIo ( IN FAT_VOLUME *Volume, @@ -351,27 +314,6 @@ FatDiskIo ( IN OUT VOID *Buffer, IN FAT_TASK *Task ) -/*++ - -Routine Description: - - General disk access function - -Arguments: - - Volume - FAT file system volume. - IoMode - The access mode (disk read/write or cache access). - Offset - The starting byte offset to read from. - BufferSize - Size of Buffer. - Buffer - Buffer containing read data. - -Returns: - - EFI_SUCCESS - The operation is performed successfully. - EFI_VOLUME_CORRUPTED - The accesss is - Others - The status of read/write the disk - ---*/ { EFI_STATUS Status; EFI_DISK_IO_PROTOCOL *DiskIo; @@ -438,97 +380,61 @@ Returns: return Status; } +/** + + Lock the volume. + +**/ VOID FatAcquireLock ( VOID ) -/*++ - -Routine Description: - - Lock the volume. - -Arguments: - - None. - -Returns: - - None. - ---*/ { EfiAcquireLock (&FatFsLock); } -EFI_STATUS -FatAcquireLockOrFail ( - VOID - ) -/*++ - -Routine Description: +/** Lock the volume. If the lock is already in the acquired state, then EFI_ACCESS_DENIED is returned. Otherwise, EFI_SUCCESS is returned. -Arguments: + @retval EFI_SUCCESS - The volume is locked. + @retval EFI_ACCESS_DENIED - The volume could not be locked because it is already locked. - None. - -Returns: - - EFI_SUCCESS - The volume is locked. - EFI_ACCESS_DENIED - The volume could not be locked because it is already locked. - ---*/ +**/ +EFI_STATUS +FatAcquireLockOrFail ( + VOID + ) { return EfiAcquireLockOrFail (&FatFsLock); } +/** + + Unlock the volume. + +**/ VOID FatReleaseLock ( VOID ) -/*++ - -Routine Description: - - Unlock the volume. - -Arguments: - - Null. - -Returns: - - None. - ---*/ { EfiReleaseLock (&FatFsLock); } +/** + + Free directory entry. + + @param DirEnt - The directory entry to be freed. + +**/ VOID FatFreeDirEnt ( IN FAT_DIRENT *DirEnt ) -/*++ - -Routine Description: - - Free directory entry. - -Arguments: - - DirEnt - The directory entry to be freed. - -Returns: - - None. - ---*/ { if (DirEnt->FileString != NULL) { FreePool (DirEnt->FileString); @@ -537,25 +443,17 @@ Returns: FreePool (DirEnt); } +/** + + Free volume structure (including the contents of directory cache and disk cache). + + @param Volume - The volume structure to be freed. + +**/ VOID FatFreeVolume ( IN FAT_VOLUME *Volume ) -/*++ - -Routine Description: - - Free volume structure (including the contents of directory cache and disk cache). - -Arguments: - - Volume - The volume structure to be freed. - -Returns: - - None. - ---*/ { // // Free disk cache @@ -570,27 +468,19 @@ Returns: FreePool (Volume); } +/** + + Translate EFI time to FAT time. + + @param ETime - The time of EFI_TIME. + @param FTime - The time of FAT_DATE_TIME. + +**/ VOID FatEfiTimeToFatTime ( IN EFI_TIME *ETime, OUT FAT_DATE_TIME *FTime ) -/*++ - -Routine Description: - - Translate EFI time to FAT time. - -Arguments: - - ETime - The time of EFI_TIME. - FTime - The time of FAT_DATE_TIME. - -Returns: - - None. - ---*/ { // // ignores timezone info in source ETime @@ -610,27 +500,19 @@ Returns: FTime->Time.DoubleSecond = (UINT16) (ETime->Second / 2); } +/** + + Translate Fat time to EFI time. + + @param FTime - The time of FAT_DATE_TIME. + @param ETime - The time of EFI_TIME.. + +**/ VOID FatFatTimeToEfiTime ( IN FAT_DATE_TIME *FTime, OUT EFI_TIME *ETime ) -/*++ - -Routine Description: - - Translate Fat time to EFI time. - -Arguments: - - FTime - The time of FAT_DATE_TIME. - ETime - The time of EFI_TIME. - -Returns: - - None. - ---*/ { ETime->Year = (UINT16) (FTime->Date.Year + 1980); ETime->Month = (UINT8) FTime->Date.Month; @@ -643,25 +525,17 @@ Returns: ETime->Daylight = 0; } +/** + + Get Current FAT time. + + @param FatNow - Current FAT time. + +**/ VOID FatGetCurrentFatTime ( OUT FAT_DATE_TIME *FatNow ) -/*++ - -Routine Description: - - Get Current FAT time. - -Arguments: - - FatNow - Current FAT time. - -Returns: - - None. - ---*/ { EFI_STATUS Status; EFI_TIME Now; @@ -678,26 +552,20 @@ Returns: } } +/** + + Check whether a time is valid. + + @param Time - The time of EFI_TIME. + + @retval TRUE - The time is valid. + @retval FALSE - The time is not valid. + +**/ BOOLEAN FatIsValidTime ( IN EFI_TIME *Time ) -/*++ - -Routine Description: - - Check whether a time is valid. - -Arguments: - - Time - The time of EFI_TIME. - -Returns: - - TRUE - The time is valid. - FALSE - The time is not valid. - ---*/ { UINTN Day; BOOLEAN ValidTime; diff --git a/FatPkg/EnhancedFatDxe/Open.c b/FatPkg/EnhancedFatDxe/Open.c index 1d864d1248..7b273fe1b1 100644 --- a/FatPkg/EnhancedFatDxe/Open.c +++ b/FatPkg/EnhancedFatDxe/Open.c @@ -1,4 +1,5 @@ -/*++ +/** @file + Routines dealing with file open. Copyright (c) 2005 - 2014, Intel Corporation. All rights reserved.
This program and the accompanying materials are licensed and made available @@ -9,44 +10,27 @@ http://opensource.org/licenses/bsd-license.php THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. - -Module Name: - - open.c - -Abstract: - - Routines dealing with file open - -Revision History - ---*/ +**/ #include "Fat.h" +/** + + Create an Open instance for the existing OFile. + The IFile of the newly opened file is passed out. + + @param OFile - The file that serves as a starting reference point. + @param PtrIFile - The newly generated IFile instance. + + @retval EFI_OUT_OF_RESOURCES - Can not allocate the memory for the IFile + @retval EFI_SUCCESS - Create the new IFile for the OFile successfully + +**/ EFI_STATUS FatAllocateIFile ( IN FAT_OFILE *OFile, OUT FAT_IFILE **PtrIFile ) -/*++ - -Routine Description: - - Create an Open instance for the existing OFile. - The IFile of the newly opened file is passed out. - -Arguments: - - OFile - The file that serves as a starting reference point. - PtrIFile - The newly generated IFile instance. - -Returns: - - EFI_OUT_OF_RESOURCES - Can not allocate the memory for the IFile - EFI_SUCCESS - Create the new IFile for the OFile successfully - ---*/ { FAT_IFILE *IFile; @@ -81,6 +65,28 @@ Returns: return EFI_SUCCESS; } +/** + + Open a file for a file name relative to an existing OFile. + The IFile of the newly opened file is passed out. + + @param OFile - The file that serves as a starting reference point. + @param NewIFile - The newly generated IFile instance. + @param FileName - The file name relative to the OFile. + @param OpenMode - Open mode. + @param Attributes - Attributes to set if the file is created. + + + @retval EFI_SUCCESS - Open the file successfully. + @retval EFI_INVALID_PARAMETER - The open mode is conflict with the attributes + or the file name is not valid. + @retval EFI_NOT_FOUND - Conficts between dir intention and attribute. + @retval EFI_WRITE_PROTECTED - Can't open for write if the volume is read only. + @retval EFI_ACCESS_DENIED - If the file's attribute is read only, and the + open is for read-write fail it. + @retval EFI_OUT_OF_RESOURCES - Can not allocate the memory. + +**/ EFI_STATUS FatOFileOpen ( IN FAT_OFILE *OFile, @@ -89,33 +95,6 @@ FatOFileOpen ( IN UINT64 OpenMode, IN UINT8 Attributes ) -/*++ - -Routine Description: - - Open a file for a file name relative to an existing OFile. - The IFile of the newly opened file is passed out. - -Arguments: - - OFile - The file that serves as a starting reference point. - NewIFile - The newly generated IFile instance. - FileName - The file name relative to the OFile. - OpenMode - Open mode. - Attributes - Attributes to set if the file is created. - -Returns: - - EFI_SUCCESS - Open the file successfully. - EFI_INVALID_PARAMETER - The open mode is conflict with the attributes - or the file name is not valid. - EFI_NOT_FOUND - Conficts between dir intention and attribute. - EFI_WRITE_PROTECTED - Can't open for write if the volume is read only. - EFI_ACCESS_DENIED - If the file's attribute is read only, and the - open is for read-write fail it. - EFI_OUT_OF_RESOURCES - Can not allocate the memory. - ---*/ { FAT_VOLUME *Volume; EFI_STATUS Status; @@ -199,6 +178,25 @@ Returns: return FatOFileFlush (OFile); } +/** + + Implements OpenEx() of Simple File System Protocol. + + @param FHand - File handle of the file serves as a starting reference point. + @param NewHandle - Handle of the file that is newly opened. + @param FileName - File name relative to FHand. + @param OpenMode - Open mode. + @param Attributes - Attributes to set if the file is created. + @param Token - A pointer to the token associated with the transaction.: + + @retval EFI_INVALID_PARAMETER - The FileName is NULL or the file string is empty. + The OpenMode is not supported. + The Attributes is not the valid attributes. + @retval EFI_OUT_OF_RESOURCES - Can not allocate the memory for file string. + @retval EFI_SUCCESS - Open the file successfully. + @return Others - The status of open file. + +**/ EFI_STATUS EFIAPI FatOpenEx ( @@ -209,30 +207,6 @@ FatOpenEx ( IN UINT64 Attributes, IN OUT EFI_FILE_IO_TOKEN *Token ) -/*++ -Routine Description: - - Implements OpenEx() of Simple File System Protocol. - -Arguments: - - FHand - File handle of the file serves as a starting reference point. - NewHandle - Handle of the file that is newly opened. - FileName - File name relative to FHand. - OpenMode - Open mode. - Attributes - Attributes to set if the file is created. - Token - A pointer to the token associated with the transaction. - -Returns: - - EFI_INVALID_PARAMETER - The FileName is NULL or the file string is empty. - The OpenMode is not supported. - The Attributes is not the valid attributes. - EFI_OUT_OF_RESOURCES - Can not allocate the memory for file string. - EFI_SUCCESS - Open the file successfully. - Others - The status of open file. - ---*/ { FAT_IFILE *IFile; FAT_IFILE *NewIFile; @@ -319,6 +293,25 @@ Returns: return Status; } +/** + + Implements Open() of Simple File System Protocol. + + + @param FHand - File handle of the file serves as a starting reference point. + @param NewHandle - Handle of the file that is newly opened. + @param FileName - File name relative to FHand. + @param OpenMode - Open mode. + @param Attributes - Attributes to set if the file is created. + + @retval EFI_INVALID_PARAMETER - The FileName is NULL or the file string is empty. + The OpenMode is not supported. + The Attributes is not the valid attributes. + @retval EFI_OUT_OF_RESOURCES - Can not allocate the memory for file string. + @retval EFI_SUCCESS - Open the file successfully. + @return Others - The status of open file. + +**/ EFI_STATUS EFIAPI FatOpen ( @@ -328,29 +321,6 @@ FatOpen ( IN UINT64 OpenMode, IN UINT64 Attributes ) -/*++ -Routine Description: - - Implements Open() of Simple File System Protocol. - -Arguments: - - FHand - File handle of the file serves as a starting reference point. - NewHandle - Handle of the file that is newly opened. - FileName - File name relative to FHand. - OpenMode - Open mode. - Attributes - Attributes to set if the file is created. - -Returns: - - EFI_INVALID_PARAMETER - The FileName is NULL or the file string is empty. - The OpenMode is not supported. - The Attributes is not the valid attributes. - EFI_OUT_OF_RESOURCES - Can not allocate the memory for file string. - EFI_SUCCESS - Open the file successfully. - Others - The status of open file. - ---*/ { return FatOpenEx (FHand, NewHandle, FileName, OpenMode, Attributes, NULL); } diff --git a/FatPkg/EnhancedFatDxe/OpenVolume.c b/FatPkg/EnhancedFatDxe/OpenVolume.c index 0f43ffae98..4e12db317e 100644 --- a/FatPkg/EnhancedFatDxe/OpenVolume.c +++ b/FatPkg/EnhancedFatDxe/OpenVolume.c @@ -1,4 +1,5 @@ -/*++ +/** @file + OpenVolume() function of Simple File System Protocol. Copyright (c) 2005 - 2013, Intel Corporation. All rights reserved.
This program and the accompanying materials are licensed and made available @@ -9,45 +10,28 @@ http://opensource.org/licenses/bsd-license.php THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. - -Module Name: - - OpenVolume.c - -Abstract: - - OpenVolume() function of Simple File System Protocol - -Revision History - ---*/ +**/ #include "Fat.h" +/** + + Implements Simple File System Protocol interface function OpenVolume(). + + @param This - Calling context. + @param File - the Root Directory of the volume. + + @retval EFI_OUT_OF_RESOURCES - Can not allocate the memory. + @retval EFI_VOLUME_CORRUPTED - The FAT type is error. + @retval EFI_SUCCESS - Open the volume successfully. + +**/ EFI_STATUS EFIAPI FatOpenVolume ( IN EFI_SIMPLE_FILE_SYSTEM_PROTOCOL *This, OUT EFI_FILE_PROTOCOL **File ) -/*++ - -Routine Description: - - Implements Simple File System Protocol interface function OpenVolume(). - -Arguments: - - This - Calling context. - File - the Root Directory of the volume. - -Returns: - - EFI_OUT_OF_RESOURCES - Can not allocate the memory. - EFI_VOLUME_CORRUPTED - The FAT type is error. - EFI_SUCCESS - Open the volume successfully. - ---*/ { EFI_STATUS Status; FAT_VOLUME *Volume; diff --git a/FatPkg/EnhancedFatDxe/ReadWrite.c b/FatPkg/EnhancedFatDxe/ReadWrite.c index 81676cd215..a6e0ec4c13 100644 --- a/FatPkg/EnhancedFatDxe/ReadWrite.c +++ b/FatPkg/EnhancedFatDxe/ReadWrite.c @@ -1,4 +1,5 @@ -/*++ +/** @file + Functions that perform file read/write. Copyright (c) 2005 - 2015, Intel Corporation. All rights reserved.
This program and the accompanying materials are licensed and made available @@ -10,44 +11,29 @@ THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. -Module Name: - - ReadWrite.c - -Abstract: - - Functions that perform file read/write - -Revision History - ---*/ +**/ #include "Fat.h" +/** + + Get the file's position of the file. + + + @param FHand - The handle of file. + @param Position - The file's position of the file. + + @retval EFI_SUCCESS - Get the info successfully. + @retval EFI_DEVICE_ERROR - Can not find the OFile for the file. + @retval EFI_UNSUPPORTED - The open file is not a file. + +**/ EFI_STATUS EFIAPI FatGetPosition ( IN EFI_FILE_PROTOCOL *FHand, OUT UINT64 *Position ) -/*++ - -Routine Description: - - Get the file's position of the file. - -Arguments: - - FHand - The handle of file. - Position - The file's position of the file. - -Returns: - - EFI_SUCCESS - Get the info successfully. - EFI_DEVICE_ERROR - Can not find the OFile for the file. - EFI_UNSUPPORTED - The open file is not a file. - ---*/ { FAT_IFILE *IFile; FAT_OFILE *OFile; @@ -67,30 +53,24 @@ Returns: return EFI_SUCCESS; } +/** + + Set the file's position of the file. + + @param FHand - The handle of file. + @param Position - The file's position of the file. + + @retval EFI_SUCCESS - Set the info successfully. + @retval EFI_DEVICE_ERROR - Can not find the OFile for the file. + @retval EFI_UNSUPPORTED - Set a directory with a not-zero position. + +**/ EFI_STATUS EFIAPI FatSetPosition ( IN EFI_FILE_PROTOCOL *FHand, IN UINT64 Position ) -/*++ - -Routine Description: - - Set the file's position of the file. - -Arguments: - - FHand - The handle of file. - Position - The file's position of the file. - -Returns: - - EFI_SUCCESS - Set the info successfully. - EFI_DEVICE_ERROR - Can not find the OFile for the file. - EFI_UNSUPPORTED - Set a directory with a not-zero position. - ---*/ { FAT_IFILE *IFile; FAT_OFILE *OFile; @@ -130,30 +110,24 @@ Returns: return EFI_SUCCESS; } +/** + + Get the file info from the open file of the IFile into Buffer. + + @param IFile - The instance of the open file. + @param BufferSize - Size of Buffer. + @param Buffer - Buffer containing read data. + + @retval EFI_SUCCESS - Get the file info successfully. + @retval other - An error occurred when operation the disk. + +**/ EFI_STATUS FatIFileReadDir ( IN FAT_IFILE *IFile, IN OUT UINTN *BufferSize, OUT VOID *Buffer ) -/*++ - -Routine Description: - - Get the file info from the open file of the IFile into Buffer. - -Arguments: - - IFile - The instance of the open file. - BufferSize - Size of Buffer. - Buffer - Buffer containing read data. - -Returns: - - EFI_SUCCESS - Get the file info successfully. - other - An error occurred when operation the disk. - ---*/ { EFI_STATUS Status; FAT_OFILE *OFile; @@ -205,6 +179,24 @@ Done: return Status; } +/** + + Get the file info from the open file of the IFile into Buffer. + + @param FHand - The file handle to access. + @param IoMode - Indicate whether the access mode is reading or writing. + @param BufferSize - Size of Buffer. + @param Buffer - Buffer containing read data. + @param Token - A pointer to the token associated with the transaction. + + @retval EFI_SUCCESS - Get the file info successfully. + @retval EFI_DEVICE_ERROR - Can not find the OFile for the file. + @retval EFI_VOLUME_CORRUPTED - The file type of open file is error. + @retval EFI_WRITE_PROTECTED - The disk is write protect. + @retval EFI_ACCESS_DENIED - The file is read-only. + @return other - An error occurred when operating on the disk. + +**/ EFI_STATUS FatIFileAccess ( IN EFI_FILE_PROTOCOL *FHand, @@ -213,30 +205,6 @@ FatIFileAccess ( IN OUT VOID *Buffer, IN EFI_FILE_IO_TOKEN *Token ) -/*++ - -Routine Description: - - Get the file info from the open file of the IFile into Buffer. - -Arguments: - - FHand - The file handle to access. - IoMode - Indicate whether the access mode is reading or writing. - BufferSize - Size of Buffer. - Buffer - Buffer containing read data. - Token - A pointer to the token associated with the transaction. - -Returns: - - EFI_SUCCESS - Get the file info successfully. - EFI_DEVICE_ERROR - Can not find the OFile for the file. - EFI_VOLUME_CORRUPTED - The file type of open file is error. - EFI_WRITE_PROTECTED - The disk is write protect. - EFI_ACCESS_DENIED - The file is read-only. - other - An error occurred when operating on the disk. - ---*/ { EFI_STATUS Status; FAT_IFILE *IFile; @@ -373,6 +341,21 @@ Done: return Status; } +/** + + Get the file info. + + @param FHand - The handle of the file. + @param BufferSize - Size of Buffer. + @param Buffer - Buffer containing read data. + + + @retval EFI_SUCCESS - Get the file info successfully. + @retval EFI_DEVICE_ERROR - Can not find the OFile for the file. + @retval EFI_VOLUME_CORRUPTED - The file type of open file is error. + @return other - An error occurred when operation the disk. + +**/ EFI_STATUS EFIAPI FatRead ( @@ -380,59 +363,50 @@ FatRead ( IN OUT UINTN *BufferSize, OUT VOID *Buffer ) -/*++ - -Routine Description: - - Get the file info. - -Arguments: - - FHand - The handle of the file. - BufferSize - Size of Buffer. - Buffer - Buffer containing read data. - -Returns: - - EFI_SUCCESS - Get the file info successfully. - EFI_DEVICE_ERROR - Can not find the OFile for the file. - EFI_VOLUME_CORRUPTED - The file type of open file is error. - other - An error occurred when operation the disk. - ---*/ { return FatIFileAccess (FHand, ReadData, BufferSize, Buffer, NULL); } +/** + + Get the file info. + + @param FHand - The handle of the file. + @param Token - A pointer to the token associated with the transaction. + + @retval EFI_SUCCESS - Get the file info successfully. + @retval EFI_DEVICE_ERROR - Can not find the OFile for the file. + @retval EFI_VOLUME_CORRUPTED - The file type of open file is error. + @return other - An error occurred when operation the disk. + +**/ EFI_STATUS EFIAPI FatReadEx ( IN EFI_FILE_PROTOCOL *FHand, IN OUT EFI_FILE_IO_TOKEN *Token ) -/*++ - -Routine Description: - - Get the file info. - -Arguments: - - FHand - The handle of the file. - Token - A pointer to the token associated with the transaction. - -Returns: - - EFI_SUCCESS - Get the file info successfully. - EFI_DEVICE_ERROR - Can not find the OFile for the file. - EFI_VOLUME_CORRUPTED - The file type of open file is error. - other - An error occurred when operation the disk. - ---*/ { return FatIFileAccess (FHand, ReadData, &Token->BufferSize, Token->Buffer, Token); } +/** + + Write the content of buffer into files. + + @param FHand - The handle of the file. + @param BufferSize - Size of Buffer. + @param Buffer - Buffer containing write data. + + @retval EFI_SUCCESS - Set the file info successfully. + @retval EFI_WRITE_PROTECTED - The disk is write protect. + @retval EFI_ACCESS_DENIED - The file is read-only. + @retval EFI_DEVICE_ERROR - The OFile is not valid. + @retval EFI_UNSUPPORTED - The open file is not a file. + - The writing file size is larger than 4GB. + @return other - An error occurred when operation the disk. + +**/ EFI_STATUS EFIAPI FatWrite ( @@ -440,62 +414,49 @@ FatWrite ( IN OUT UINTN *BufferSize, IN VOID *Buffer ) -/*++ - -Routine Description: - - Write the content of buffer into files. - -Arguments: - - FHand - The handle of the file. - BufferSize - Size of Buffer. - Buffer - Buffer containing write data. - -Returns: - - EFI_SUCCESS - Set the file info successfully. - EFI_WRITE_PROTECTED - The disk is write protect. - EFI_ACCESS_DENIED - The file is read-only. - EFI_DEVICE_ERROR - The OFile is not valid. - EFI_UNSUPPORTED - The open file is not a file. - - The writing file size is larger than 4GB. - other - An error occurred when operation the disk. - ---*/ { return FatIFileAccess (FHand, WriteData, BufferSize, Buffer, NULL); } +/** + + Get the file info. + + @param FHand - The handle of the file. + @param Token - A pointer to the token associated with the transaction. + + @retval EFI_SUCCESS - Get the file info successfully. + @retval EFI_DEVICE_ERROR - Can not find the OFile for the file. + @retval EFI_VOLUME_CORRUPTED - The file type of open file is error. + @return other - An error occurred when operation the disk. + +**/ EFI_STATUS EFIAPI FatWriteEx ( IN EFI_FILE_PROTOCOL *FHand, IN OUT EFI_FILE_IO_TOKEN *Token ) -/*++ - -Routine Description: - - Get the file info. - -Arguments: - - FHand - The handle of the file. - Token - A pointer to the token associated with the transaction. - -Returns: - - EFI_SUCCESS - Get the file info successfully. - EFI_DEVICE_ERROR - Can not find the OFile for the file. - EFI_VOLUME_CORRUPTED - The file type of open file is error. - other - An error occurred when operation the disk. - ---*/ { return FatIFileAccess (FHand, WriteData, &Token->BufferSize, Token->Buffer, Token); } +/** + + This function reads data from a file or writes data to a file. + It uses OFile->PosRem to determine how much data can be accessed in one time. + + @param OFile - The open file. + @param IoMode - Indicate whether the access mode is reading or writing. + @param Position - The position where data will be accessed. + @param DataBufferSize - Size of Buffer. + @param UserBuffer - Buffer containing data. + @param Task point to task instance. + + @retval EFI_SUCCESS - Access the data successfully. + @return other - An error occurred when operating on the disk. + +**/ EFI_STATUS FatAccessOFile ( IN FAT_OFILE *OFile, @@ -505,27 +466,6 @@ FatAccessOFile ( IN OUT UINT8 *UserBuffer, IN FAT_TASK *Task ) -/*++ - -Routine Description: - - This function reads data from a file or writes data to a file. - It uses OFile->PosRem to determine how much data can be accessed in one time. - -Arguments: - - OFile - The open file. - IoMode - Indicate whether the access mode is reading or writing. - Position - The position where data will be accessed. - DataBufferSize - Size of Buffer. - UserBuffer - Buffer containing data. - -Returns: - - EFI_SUCCESS - Access the data successfully. - other - An error occurred when operating on the disk. - ---*/ { FAT_VOLUME *Volume; UINTN Len; @@ -579,28 +519,22 @@ Returns: return Status; } +/** + + Expand OFile by appending zero bytes at the end of OFile. + + @param OFile - The open file. + @param ExpandedSize - The number of zero bytes appended at the end of the file. + + @retval EFI_SUCCESS - The file is expanded successfully. + @return other - An error occurred when expanding file. + +**/ EFI_STATUS FatExpandOFile ( IN FAT_OFILE *OFile, IN UINT64 ExpandedSize ) -/*++ - -Routine Description: - - Expand OFile by appending zero bytes at the end of OFile. - -Arguments: - - OFile - The open file. - ExpandedSize - The number of zero bytes appended at the end of the file. - -Returns: - - EFI_SUCCESS - The file is expanded successfully. - other - An error occurred when expanding file. - ---*/ { EFI_STATUS Status; UINTN WritePos; @@ -614,29 +548,23 @@ Returns: return Status; } +/** + + Write zero pool from the WritePos to the end of OFile. + + @param OFile - The open file to write zero pool. + @param WritePos - The number of zero bytes written. + + @retval EFI_SUCCESS - Write the zero pool successfully. + @retval EFI_OUT_OF_RESOURCES - Not enough memory to perform the operation. + @return other - An error occurred when writing disk. + +**/ EFI_STATUS FatWriteZeroPool ( IN FAT_OFILE *OFile, IN UINTN WritePos ) -/*++ - -Routine Description: - - Write zero pool from the WritePos to the end of OFile. - -Arguments: - - OFile - The open file to write zero pool. - WritePos - The number of zero bytes written. - -Returns: - - EFI_SUCCESS - Write the zero pool successfully. - EFI_OUT_OF_RESOURCES - Not enough memory to perform the operation. - other - An error occurred when writing disk. - ---*/ { EFI_STATUS Status; VOID *ZeroBuffer; @@ -676,28 +604,22 @@ Returns: return Status; } +/** + + Truncate the OFile to smaller file size. + + @param OFile - The open file. + @param TruncatedSize - The new file size. + + @retval EFI_SUCCESS - The file is truncated successfully. + @return other - An error occurred when truncating file. + +**/ EFI_STATUS FatTruncateOFile ( IN FAT_OFILE *OFile, IN UINTN TruncatedSize ) -/*++ - -Routine Description: - - Truncate the OFile to smaller file size. - -Arguments: - - OFile - The open file. - TruncatedSize - The new file size. - -Returns: - - EFI_SUCCESS - The file is truncated successfully. - other - An error occurred when truncating file. - ---*/ { OFile->FileSize = TruncatedSize; return FatShrinkEof (OFile); diff --git a/FatPkg/EnhancedFatDxe/UnicodeCollation.c b/FatPkg/EnhancedFatDxe/UnicodeCollation.c index 61b9aab4d9..b240a931ff 100644 --- a/FatPkg/EnhancedFatDxe/UnicodeCollation.c +++ b/FatPkg/EnhancedFatDxe/UnicodeCollation.c @@ -189,9 +189,8 @@ FatStriCmp ( /** Uppercase a string. - @param Str The string which will be upper-cased. + @param String The string which will be upper-cased. - @return None. **/ VOID @@ -209,9 +208,8 @@ FatStrUpr ( /** Lowercase a string - @param Str The string which will be lower-cased. + @param String The string which will be lower-cased. - @return None **/ VOID