From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mga02.intel.com (mga02.intel.com [134.134.136.20]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by ml01.01.org (Postfix) with ESMTPS id 73B1381FBC for ; Thu, 8 Dec 2016 17:10:15 -0800 (PST) Received: from fmsmga001.fm.intel.com ([10.253.24.23]) by orsmga101.jf.intel.com with ESMTP; 08 Dec 2016 17:10:13 -0800 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.33,322,1477983600"; d="scan'208";a="1079487032" Received: from fmsmsx104.amr.corp.intel.com ([10.18.124.202]) by fmsmga001.fm.intel.com with ESMTP; 08 Dec 2016 17:10:13 -0800 Received: from fmsmsx112.amr.corp.intel.com (10.18.116.6) by fmsmsx104.amr.corp.intel.com (10.18.124.202) with Microsoft SMTP Server (TLS) id 14.3.248.2; Thu, 8 Dec 2016 17:10:13 -0800 Received: from shsmsx101.ccr.corp.intel.com (10.239.4.153) by FMSMSX112.amr.corp.intel.com (10.18.116.6) with Microsoft SMTP Server (TLS) id 14.3.248.2; Thu, 8 Dec 2016 17:10:11 -0800 Received: from shsmsx104.ccr.corp.intel.com ([169.254.5.11]) by SHSMSX101.ccr.corp.intel.com ([169.254.1.206]) with mapi id 14.03.0248.002; Fri, 9 Dec 2016 09:10:09 +0800 From: "Ni, Ruiyu" To: "Bi, Dandan" , "edk2-devel@lists.01.org" Thread-Topic: [patch 6/8] FatPkg\EnhancedFatDxe: Make the comments align with EDKII coding style Thread-Index: AQHSUUGHzdcriTo4bUWwXMSQcDxAHKD+zzSQ Date: Fri, 9 Dec 2016 01:10:08 +0000 Deferred-Delivery: Fri, 9 Dec 2016 01:10:00 +0000 Message-ID: <734D49CCEBEEF84792F5B80ED585239D58EAFAF1@SHSMSX104.ccr.corp.intel.com> References: <1481194467-75920-1-git-send-email-dandan.bi@intel.com> <1481194467-75920-7-git-send-email-dandan.bi@intel.com> In-Reply-To: <1481194467-75920-7-git-send-email-dandan.bi@intel.com> Accept-Language: en-US, zh-CN X-MS-Has-Attach: X-MS-TNEF-Correlator: x-titus-metadata-40: eyJDYXRlZ29yeUxhYmVscyI6IiIsIk1ldGFkYXRhIjp7Im5zIjoiaHR0cDpcL1wvd3d3LnRpdHVzLmNvbVwvbnNcL0ludGVsMyIsImlkIjoiODU5ZThmMmUtODU4OC00Yzg2LWI5ZTctNmYzNzIxY2EyNGM1IiwicHJvcHMiOlt7Im4iOiJDVFBDbGFzc2lmaWNhdGlvbiIsInZhbHMiOlt7InZhbHVlIjoiQ1RQX1BVQkxJQyJ9XX1dfSwiU3ViamVjdExhYmVscyI6W10sIlRNQ1ZlcnNpb24iOiIxNS45LjYuNiIsIlRydXN0ZWRMYWJlbEhhc2giOiJ6R2swaWdoVGF6eUMxSm9NbXlzYjRwUFphVnFXMW90SGJHRHpuY2lpcWhBPSJ9 x-ctpclassification: CTP_PUBLIC x-originating-ip: [10.239.127.40] MIME-Version: 1.0 Subject: Re: [patch 6/8] FatPkg\EnhancedFatDxe: Make the comments align with EDKII coding style X-BeenThere: edk2-devel@lists.01.org X-Mailman-Version: 2.1.21 Precedence: list List-Id: EDK II Development List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Fri, 09 Dec 2016 01:10:15 -0000 Content-Language: en-US Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: quoted-printable Reviewed-by: Ruiyu Ni Regards, Ray >-----Original Message----- >From: Bi, Dandan >Sent: Thursday, December 8, 2016 6:54 PM >To: edk2-devel@lists.01.org >Cc: Ni, Ruiyu >Subject: [patch 6/8] FatPkg\EnhancedFatDxe: Make the comments align with E= DKII coding style > >Cc: Ruiyu Ni >Contributed-under: TianoCore Contribution Agreement 1.0 >Signed-off-by: Dandan Bi >--- > FatPkg/EnhancedFatDxe/ComponentName.c | 10 +- > FatPkg/EnhancedFatDxe/Data.c | 16 +- > FatPkg/EnhancedFatDxe/Debug.c | 34 +- > FatPkg/EnhancedFatDxe/Delete.c | 35 +- > FatPkg/EnhancedFatDxe/DirectoryCache.c | 120 ++--- > FatPkg/EnhancedFatDxe/DirectoryManage.c | 726 ++++++++++++--------------= ----- > FatPkg/EnhancedFatDxe/DiskCache.c | 257 +++++------ > FatPkg/EnhancedFatDxe/Fat.c | 169 +++---- > FatPkg/EnhancedFatDxe/Fat.h | 394 +++++++---------- > FatPkg/EnhancedFatDxe/FatFileSystem.h | 15 +- > FatPkg/EnhancedFatDxe/FileName.c | 272 +++++------- > FatPkg/EnhancedFatDxe/FileSpace.c | 334 ++++++-------- > FatPkg/EnhancedFatDxe/Flush.c | 246 ++++------- > FatPkg/EnhancedFatDxe/Hash.c | 158 +++---- > FatPkg/EnhancedFatDxe/Info.c | 320 ++++++-------- > FatPkg/EnhancedFatDxe/Init.c | 95 ++-- > FatPkg/EnhancedFatDxe/Misc.c | 402 ++++++----------- > FatPkg/EnhancedFatDxe/Open.c | 172 +++----- > FatPkg/EnhancedFatDxe/OpenVolume.c | 40 +- > FatPkg/EnhancedFatDxe/ReadWrite.c | 392 +++++++---------- > FatPkg/EnhancedFatDxe/UnicodeCollation.c | 6 +- > 21 files changed, 1565 insertions(+), 2648 deletions(-) > >diff --git a/FatPkg/EnhancedFatDxe/ComponentName.c b/FatPkg/EnhancedFatDxe= /ComponentName.c >index af3f9e6..ce1c975 100644 >--- a/FatPkg/EnhancedFatDxe/ComponentName.c >+++ b/FatPkg/EnhancedFatDxe/ComponentName.c >@@ -1,6 +1,6 @@ >-/*++ >+/** @file > > Copyright (c) 2005 - 2011, Intel Corporation. All rights reserved.
> This program and the accompanying materials are licensed and made availab= le > under the terms and conditions of the BSD License which accompanies this > distribution. The full text of the license may be found at >@@ -8,17 +8,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 IMPL= IED. > > >-Module Name: >- >- ComponentName.c >- >-Abstract: >- >---*/ >+**/ > > #include "Fat.h" > > // > // EFI Component Name Functions >diff --git a/FatPkg/EnhancedFatDxe/Data.c b/FatPkg/EnhancedFatDxe/Data.c >index b20cc45..56a265e 100644 >--- a/FatPkg/EnhancedFatDxe/Data.c >+++ b/FatPkg/EnhancedFatDxe/Data.c >@@ -1,28 +1,18 @@ >-/*++ >+/** @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 availab= le > under the terms and conditions of the BSD License which accompanies this > distribution. The full text of the license may be found at > 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 IMPL= IED. > >- >-Module Name: >- >- Data.c >- >-Abstract: >- >- Global data in the FAT Filesystem driver >- >-Revision History >- >---*/ >+**/ > > #include "Fat.h" > > // > // Globals >diff --git a/FatPkg/EnhancedFatDxe/Debug.c b/FatPkg/EnhancedFatDxe/Debug.c >index 7c0dc20..ad23786 100644 >--- a/FatPkg/EnhancedFatDxe/Debug.c >+++ b/FatPkg/EnhancedFatDxe/Debug.c >@@ -1,50 +1,32 @@ >-/*++ >+/** @file >+ Debug functions for fat driver > > Copyright (c) 2005, Intel Corporation. All rights reserved.
> This program and the accompanying materials are licensed and made availab= le > under the terms and conditions of the BSD License which accompanies this > distribution. The full text of the license may be found at > 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 IMPL= IED. > >+**/ > >-Module Name: >- >- debug.c >- >-Abstract: >- >- Debug functions for fat driver >+#include "Fat.h" > >-Revision History >+/** > >---*/ >+ Dump all the FAT Entry of the FAT table in the volume. > >-#include "Fat.h" >+ @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; > UINTN Index; > CHAR16 *Pointer; >diff --git a/FatPkg/EnhancedFatDxe/Delete.c b/FatPkg/EnhancedFatDxe/Delete= .c >index e5103a8..9837565 100644 >--- a/FatPkg/EnhancedFatDxe/Delete.c >+++ b/FatPkg/EnhancedFatDxe/Delete.c >@@ -1,6 +1,7 @@ >-/*++ >+/** @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 availab= le > under the terms and conditions of the BSD License which accompanies this > distribution. The full text of the license may be found at >@@ -8,45 +9,29 @@ 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 IMPL= IED. > > >-Module Name: >+**/ > >- delete.c >- >-Abstract: >+#include "Fat.h" > >- Function that deletes a file >+/** > >-Revision History >+ Deletes the file & Closes the file handle. > >---*/ >+ @param FHand - Handle to the file to delete. > >-#include "Fat.h" >+ @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; > FAT_DIRENT *DirEnt; > EFI_STATUS Status; >diff --git a/FatPkg/EnhancedFatDxe/DirectoryCache.c b/FatPkg/EnhancedFatDx= e/DirectoryCache.c >index 568b291..30de86a 100644 >--- a/FatPkg/EnhancedFatDxe/DirectoryCache.c >+++ b/FatPkg/EnhancedFatDxe/DirectoryCache.c >@@ -1,6 +1,7 @@ >-/*++ >+/** @file >+ Functions for directory cache operation. > > Copyright (c) 2005, Intel Corporation. All rights reserved.
> This program and the accompanying materials are licensed and made availab= le > under the terms and conditions of the BSD License which accompanies this > distribution. The full text of the license may be found at >@@ -8,44 +9,26 @@ 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 IMPL= IED. > > >-Module Name: >+**/ > >- DirectoryCache.c >- >-Abstract: >- >- Functions for directory cache operation >+#include "Fat.h" > >-Revision History >+/** > >---*/ >+ Free the directory structure and release the memory. > >-#include "Fat.h" >+ @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; > > // > // Release Directory Entry Nodes >@@ -61,30 +44,22 @@ 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; > > ODir =3D AllocateZeroPool (sizeof (FAT_ODIR)); > if (ODir !=3D NULL) { >@@ -97,30 +72,22 @@ 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 dele= ted file. > >-Arguments: >+ @param OFile - The OFile whose directory structure is = to be discarded. > >- OFile - The OFile whose directory structure is to be di= scarded. >- >-Returns: >- >- None. >- >---*/ >+**/ >+VOID >+FatDiscardODir ( >+ IN FAT_OFILE *OFile >+ ) > { > FAT_ODIR *ODir; > FAT_VOLUME *Volume; > > Volume =3D OFile->Volume; >@@ -152,31 +119,24 @@ Returns: > if (ODir !=3D NULL) { > FatFreeODir (ODir); > } > } > >-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 d= irectory; > Otherwise, allocate a new one for OFile. > >-Arguments: >- >- OFile - The OFile which requests directory structure. >+ @param OFile - The OFile which requests directory stru= cture. > >-Returns: >- >- None. >- >---*/ >+**/ >+VOID >+FatRequestODir ( >+ IN FAT_OFILE *OFile >+ ) > { > UINTN DirCacheTag; > FAT_VOLUME *Volume; > FAT_ODIR *ODir; > FAT_ODIR *CurrentODir; >@@ -206,29 +166,21 @@ Returns: > } > > OFile->ODir =3D ODir; > } > >-VOID >-FatCleanupODirCache ( >- IN FAT_VOLUME *Volume >- ) >-/*++ >- >-Routine Description: >+/** > > Clean up all the cached directory structures when the volume is going t= o be abandoned. > >-Arguments: >+ @param Volume - FAT file system volume. > >- Volume - FAT file system volume. >- >-Returns: >- >- None. >- >---*/ >+**/ >+VOID >+FatCleanupODirCache ( >+ IN FAT_VOLUME *Volume >+ ) > { > FAT_ODIR *ODir; > while (Volume->DirCacheCount > 0) { > ODir =3D ODIR_FROM_DIRCACHELINK (Volume->DirCacheList.BackLink); > RemoveEntryList (&ODir->DirCacheLink); >diff --git a/FatPkg/EnhancedFatDxe/DirectoryManage.c b/FatPkg/EnhancedFatD= xe/DirectoryManage.c >index 149119d..fe6fcc9 100644 >--- a/FatPkg/EnhancedFatDxe/DirectoryManage.c >+++ b/FatPkg/EnhancedFatDxe/DirectoryManage.c >@@ -1,58 +1,42 @@ >-/*++ >+/** @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 availab= le > under the terms and conditions of the BSD License which accompanies this > distribution. The full text of the license may be found at > 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 IMPL= IED. > >+**/ > >-Module Name: >- >- DirectoryManage.c >- >-Abstract: >+#include "Fat.h" > >- Functions for performing directory entry io >+/** > >-Revision History >+ Get a directory entry from disk for the Ofile. > >---*/ >+ @param Parent - The parent of the OFile which need to u= pdate. >+ @param IoMode - Indicate whether to read directory entr= y or write directroy entry. >+ @param EntryPos - The position of the directory entry to = be accessed. >+ @param Entry - The directory entry read or written. > >-#include "Fat.h" >+ @retval EFI_SUCCESS - Access the directory entry sucessfully. >+ @return other - An error occurred when reading the dire= ctory entry. > >+**/ > STATIC > EFI_STATUS > FatAccessEntry ( > IN FAT_OFILE *Parent, > IN IO_MODE IoMode, > 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 wri= te directroy entry. >- EntryPos - The position of the directory entry to be acces= sed. >- Entry - The directory entry read or written. >- >-Returns: >- >- EFI_SUCCESS - Access the directory entry sucessfully. >- other - An error occurred when reading the directory en= try. >- >---*/ > { > UINTN Position; > UINTN BufferSize; > > Position =3D EntryPos * sizeof (FAT_DIRECTORY_ENTRY); >@@ -68,32 +52,26 @@ Returns: > > BufferSize =3D sizeof (FAT_DIRECTORY_ENTRY); > return FatAccessOFile (Parent, IoMode, Position, &BufferSize, Entry, NU= LL); > } > >-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: >+ @param OFile - The parent OFile which needs to update. >+ @param DirEnt - The directory entry to be saved. > >- EFI_SUCCESS - Store the directory entry successfully. >- other - An error occurred when writing the directory en= try. >+ @retval EFI_SUCCESS - Store the directory entry successfully. >+ @return other - An error occurred when writing the dire= ctory entry. > >---*/ >+**/ >+EFI_STATUS >+FatStoreDirEnt ( >+ IN FAT_OFILE *OFile, >+ IN FAT_DIRENT *DirEnt >+ ) > { > EFI_STATUS Status; > FAT_DIRECTORY_LFN LfnEntry; > UINTN EntryPos; > CHAR16 *LfnBufferPointer; >@@ -155,116 +133,86 @@ Returns: > } > > return EFI_SUCCESS; > } > >-BOOLEAN >-FatIsDotDirEnt ( >- IN FAT_DIRENT *DirEnt >- ) >-/*++ >- >-Routine Description: >+/** > > Determine whether the directory entry is "." or ".." entry. > >-Arguments: >+ @param DirEnt - The corresponding directory entry. > >- DirEnt - The corresponding directory entry. >+ @retval TRUE - The directory entry is "." or ".." direc= tory entry >+ @retval FALSE - The directory entry is not "." or ".." d= irectory entry > >-Returns: >- >- TRUE - The directory entry is "." or ".." directory ent= ry >- FALSE - The directory entry is not "." or ".." directory= entry >- >---*/ >+**/ >+BOOLEAN >+FatIsDotDirEnt ( >+ IN FAT_DIRENT *DirEnt >+ ) > { > CHAR16 *FileString; > FileString =3D DirEnt->FileString; > if (StrCmp (FileString, L".") =3D=3D 0 || StrCmp (FileString, L"..") = =3D=3D 0) { > return TRUE; > } > > 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; > > DirEnt =3D OFile->DirEnt; > Cluster =3D OFile->FileCluster; > DirEnt->Entry.FileClusterHigh =3D (UINT16) (Cluster >> 16); > DirEnt->Entry.FileCluster =3D (UINT16) Cluster; > } > >-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. >+ @param OFile - The corresponding OFile. > >---*/ >+**/ >+VOID >+FatUpdateDirEntClusterSizeInfo ( >+ IN FAT_OFILE *OFile >+ ) > { > ASSERT (OFile->ODir =3D=3D NULL); > OFile->DirEnt->Entry.FileSize =3D (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; > Entry1 =3D (UINT8 *) &DirEnt1->Entry; > Entry2 =3D (UINT8 *) &DirEnt2->Entry; >@@ -273,32 +221,24 @@ Returns: > Entry2 + FAT_ENTRY_INFO_OFFSET, > sizeof (FAT_DIRECTORY_ENTRY) - FAT_ENTRY_INFO_OFFSET > ); > } > >+/** >+ >+ 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; > CHAR8 *File8Dot3Name; > UINTN EntryPos; >@@ -365,64 +305,50 @@ Returns: > } > > DirEnt->FileString =3D 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 upda= ted. >+ @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 =3D=3D NULL) { > DirEnt->Link.BackLink =3D &ODir->ChildList; > } > InsertTailList (DirEnt->Link.BackLink, &DirEnt->Link); > FatInsertToHashTable (ODir, DirEnt); > } > >+/** >+ >+ Load from disk the next directory entry at current end of directory pos= ition. >+ >+ @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 dire= ctory 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 pos= ition >- >-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 en= tries. >- >---*/ > { > EFI_STATUS Status; > FAT_DIRENT *DirEnt; > FAT_ODIR *ODir; > FAT_DIRECTORY_ENTRY Entry; >@@ -503,36 +429,30 @@ Returns: > Done: > FatFreeDirEnt (DirEnt); > 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, > IN FAT_DIRENT *DirEnt, > 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; > UINTN ResultSize; > UINTN Cluster; >@@ -573,35 +493,29 @@ Returns: > > *BufferSize =3D ResultSize; > return Status; > } > >+/** >+ >+ Search the directory for the directory entry whose filename is FileName= String. >+ >+ @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 dire= ctory entries. >+ >+**/ > STATIC > EFI_STATUS > FatSearchODir ( > IN FAT_OFILE *OFile, > IN CHAR16 *FileNameString, > OUT FAT_DIRENT **PtrDirEnt > ) >-/*++ >- >-Routine Description: >- >- Search the directory for the directory entry whose filename is FileName= String. >- >-Arguments: >- >- OFile - The parent OFile whose directory is to be searc= hed. >- 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 en= tries. >- >---*/ > { > BOOLEAN PossibleShortName; > CHAR8 File8Dot3Name[FAT_NAME_LEN]; > FAT_ODIR *ODir; > FAT_DIRENT *DirEnt; >@@ -645,60 +559,46 @@ Returns: > > *PtrDirEnt =3D DirEnt; > return EFI_SUCCESS; > } > >-VOID >-FatResetODirCursor ( >- IN FAT_OFILE *OFile >- ) >-/*++ >- >-Routine Description: >+/** > > Set the OFile's current directory cursor to the list head. > >-Arguments: >+ @param OFile - The directory OFile whose directory curs= or is reset. > >- OFile - The directory OFile whose directory cursor is r= eset. >- >-Returns: >- >- None. >- >---*/ >+**/ >+VOID >+FatResetODirCursor ( >+ IN FAT_OFILE *OFile >+ ) > { > FAT_ODIR *ODir; > > ODir =3D OFile->ODir; > ASSERT (ODir !=3D NULL); > ODir->CurrentCursor =3D &(ODir->ChildList); > ODir->CurrentPos =3D 0; > } > >-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: >+ @param OFile - The parent OFile. >+ @param PtrDirEnt - The next directory entry. > >- EFI_SUCCESS - We get the next directory entry successfully. >- other - An error occurred when get next directory entry= . >+ @retval EFI_SUCCESS - We get the next directory entry success= fully. >+ @return other - An error occurred when get next directo= ry entry. > >---*/ >+**/ >+EFI_STATUS >+FatGetNextDirEnt ( >+ IN FAT_OFILE *OFile, >+ OUT FAT_DIRENT **PtrDirEnt >+ ) > { > EFI_STATUS Status; > FAT_DIRENT *DirEnt; > FAT_ODIR *ODir; > >@@ -733,32 +633,24 @@ Returns: > > *PtrDirEnt =3D DirEnt; > 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; > > // >@@ -798,58 +690,46 @@ Returns: > DirEnt->EntryCount =3D (UINT8)(LFN_ENTRY_NUMBER (StrLen (FileString= )) + DirEnt->EntryCount); > } > } > } > >+/** >+ >+ 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 cluste= r. >+ >+**/ > STATIC > EFI_STATUS > FatExpandODir ( > IN FAT_OFILE *OFile > ) >-/*++ >- >-Routine Description: >- >- Append a zero cluster to the current OFile. >+{ >+ return FatExpandOFile (OFile, OFile->FileSize + OFile->Volume->ClusterS= ize); >+} > >-Arguments: >+/** > >- OFile - The directory OFile which needs to be updated. >+ Search the Root OFile for the possible volume label. > >-Returns: >+ @param Root - The Root OFile. >+ @param DirEnt - The returned directory entry of volume = label. > >- 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->ClusterS= ize); >-} >+ @retval EFI_SUCCESS - The search process is completed success= fully. >+ @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; > FAT_DIRECTORY_ENTRY *Entry; > >@@ -872,37 +752,31 @@ Returns: > EntryPos++; > } while (Entry->FileName[0] !=3D EMPTY_ENTRY_MARK); > 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: >- >- OFile - The corresponding OFile. >- DirEnt - The directory entry to be inserted. >+ @param OFile - The corresponding OFile. >+ @param DirEnt - The directory entry to be inserted. > >-Returns: >+ @retval EFI_SUCCESS - The directory entry has been successful= ly inserted. >+ @retval EFI_VOLUME_FULL - The directory can not hold more directo= ry entries. >+ @return Others - Some error occurred when inserting new = directory entries. > >- EFI_SUCCESS - The directory entry has been successfully inser= ted. >- EFI_VOLUME_FULL - The directory can not hold more directory entri= es. >- Others - Some error occurred when inserting new director= y entries. >- >---*/ >+**/ >+STATIC >+EFI_STATUS >+FatFirstFitInsertDirEnt ( >+ IN FAT_OFILE *OFile, >+ IN FAT_DIRENT *DirEnt >+ ) > { > EFI_STATUS Status; > FAT_ODIR *ODir; > LIST_ENTRY *CurrentEntry; > FAT_DIRENT *CurrentDirEnt; >@@ -954,34 +828,28 @@ Done: > DirEnt->EntryPos =3D (UINT16) NewEntryPos; > DirEnt->Link.BackLink =3D CurrentEntry; > 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 suc= cessfully found. >+ @retval EFI_VOLUME_FULL - The directory has reach its maximum cap= acity. >+ @return other - An error occurred when reading the dire= ctory 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 successfull= y found. >- EFI_VOLUME_FULL - The directory has reach its maximum capacity. >- other - An error occurred when reading the directory en= try. >- >---*/ > { > EFI_STATUS Status; > FAT_ODIR *ODir; > FAT_DIRENT *TempDirEnt; > UINT32 NewEndPos; >@@ -1025,32 +893,26 @@ Returns: > ODir->CurrentEndPos =3D NewEndPos; > DirEnt->EntryPos =3D (UINT16) (ODir->CurrentEndPos - 1); > return EFI_SUCCESS; > } > >-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: >+ @param Volume - FAT file system volume. >+ @param Name - The file name of the volume. > >- EFI_SUCCESS - Update the volume with the directory entry suce= ssfully. >- others - An error occurred when getting volume label. >+ @retval EFI_SUCCESS - Update the volume with the directory en= try sucessfully. >+ @return others - An error occurred when getting volume l= abel. > >---*/ >+**/ >+EFI_STATUS >+FatGetVolumeEntry ( >+ IN FAT_VOLUME *Volume, >+ IN CHAR16 *Name >+ ) > { > EFI_STATUS Status; > FAT_DIRENT LabelDirEnt; > > *Name =3D 0; >@@ -1062,33 +924,27 @@ Returns: > } > > return Status; > } > >-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: >+ @param Volume - FAT file system volume. >+ @param Name - The new file name of the volume. > >- 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. >+ @retval EFI_SUCCESS - Update the Volume sucessfully. >+ @retval EFI_UNSUPPORTED - The input label is not a valid volume lab= el. >+ @return other - An error occurred when setting volume lab= el. > >---*/ >+**/ >+EFI_STATUS >+FatSetVolumeEntry ( >+ IN FAT_VOLUME *Volume, >+ IN CHAR16 *Name >+ ) > { > EFI_STATUS Status; > FAT_DIRENT LabelDirEnt; > FAT_OFILE *Root; > >@@ -1119,30 +975,24 @@ Returns: > > FatGetCurrentFatTime (&LabelDirEnt.Entry.FileModificationTime); > return FatStoreDirEnt (Root, &LabelDirEnt); > } > >-EFI_STATUS >-FatCreateDotDirEnts ( >- IN FAT_OFILE *OFile >- ) >-/*++ >- >-Routine Description: >+/** > > Create "." and ".." directory entries in the newly-created parent OFile= . > >-Arguments: >- >- OFile - The parent OFile. >+ @param OFile - The parent OFile. > >-Returns: >+ @retval EFI_SUCCESS - The dot directory entries are successfu= lly created. >+ @return other - An error occurred when creating the dir= ectory entry. > >- EFI_SUCCESS - The dot directory entries are successfully crea= ted. >- other - An error occurred when creating the directory e= ntry. >- >---*/ >+**/ >+EFI_STATUS >+FatCreateDotDirEnts ( >+ IN FAT_OFILE *OFile >+ ) > { > EFI_STATUS Status; > FAT_DIRENT *DirEnt; > > Status =3D FatExpandODir (OFile); >@@ -1163,37 +1013,31 @@ Returns: > // > Status =3D FatCreateDirEnt (OFile, L"..", FAT_ATTRIBUTE_DIRECTORY, &Dir= Ent); > return Status; > } > >+/** >+ >+ Create a directory entry in the parent OFile. >+ >+ @param OFile - The parent OFile. >+ @param FileName - The filename of the newly-created direc= tory entry. >+ @param Attributes - The attribute of the newly-created dire= ctory entry. >+ @param PtrDirEnt - The pointer to the newly-created direct= ory entry. >+ >+ @retval EFI_SUCCESS - The directory entry is successfully cre= ated. >+ @retval EFI_OUT_OF_RESOURCES - Not enough memory to create the directo= ry entry. >+ @return other - An error occurred when creating the dir= ectory entry. >+ >+**/ > EFI_STATUS > FatCreateDirEnt ( > IN FAT_OFILE *OFile, > IN CHAR16 *FileName, > 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 ent= ry. >- Attributes - The attribute of the newly-created directory en= try. >- PtrDirEnt - The pointer to the newly-created directory entr= y. >- >-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 e= ntry. >- >---*/ > { > FAT_DIRENT *DirEnt; > FAT_ODIR *ODir; > EFI_STATUS Status; > >@@ -1232,32 +1076,26 @@ Returns: > Done: > FatFreeDirEnt (DirEnt); > return Status; > } > >-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. >+ @param OFile - The parent OFile. >+ @param DirEnt - The directory entry to be removed. > >-Returns: >+ @retval EFI_SUCCESS - The directory entry is successfully remo= ved. >+ @return other - An error occurred when removing the dire= ctory entry. > >- EFI_SUCCESS - The directory entry is successfully removed. >- other - An error occurred when removing the directory en= try. >- >---*/ >+**/ >+EFI_STATUS >+FatRemoveDirEnt ( >+ IN FAT_OFILE *OFile, >+ IN FAT_DIRENT *DirEnt >+ ) > { > FAT_ODIR *ODir; > > ODir =3D OFile->ODir; > if (ODir->CurrentCursor =3D=3D &DirEnt->Link) { >@@ -1277,33 +1115,27 @@ Returns: > DirEnt->Entry.FileName[0] =3D DELETE_ENTRY_MARK; > DirEnt->Invalid =3D TRUE; > return FatStoreDirEnt (OFile, DirEnt); > } > >-EFI_STATUS >-FatOpenDirEnt ( >- IN FAT_OFILE *Parent, >- IN FAT_DIRENT *DirEnt >- ) >-/*++ >- >-Routine Description: >+/** > > Open the directory entry to get the OFile. > >-Arguments: >+ @param Parent - The parent OFile. >+ @param DirEnt - The directory entry to be opened. > >- OFile - The parent OFile. >- DirEnt - The directory entry to be opened. >+ @retval EFI_SUCCESS - The directory entry is successfully ope= ned. >+ @retval EFI_OUT_OF_RESOURCES - not enough memory to allocate a new OFi= le. >+ @return other - An error occurred when opening the dire= ctory entry. > >-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 en= try. >- >---*/ >+**/ >+EFI_STATUS >+FatOpenDirEnt ( >+ IN FAT_OFILE *Parent, >+ IN FAT_DIRENT *DirEnt >+ ) > { > FAT_OFILE *OFile; > FAT_VOLUME *Volume; > > if (DirEnt->OFile =3D=3D NULL) { >@@ -1362,30 +1194,21 @@ Returns: > } > > return EFI_SUCCESS; > } > >-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 ent= ry. >+ @param DirEnt - The directory entry to be closed. > >---*/ >+**/ >+VOID >+FatCloseDirEnt ( >+ IN FAT_DIRENT *DirEnt >+ ) > { > FAT_OFILE *OFile; > FAT_VOLUME *Volume; > > OFile =3D DirEnt->OFile; >@@ -1410,42 +1233,37 @@ Returns: > // > FatFreeDirEnt (DirEnt); > } > } > >-EFI_STATUS >-FatLocateOFile ( >- IN OUT FAT_OFILE **PtrOFile, >- IN CHAR16 *FileName, >- 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 l= ocated OFile. >- FileName - The file name relevant to the OFile. >- Attributes - The attribute of the destination OFile. >- NewFileName - The remaining file name. >- >-Returns: >+ @param PtrOFile - As input, the reference OFile; as outpu= t, 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. > >- EFI_NOT_FOUND - The file name can't be opened and there is more= than one >+ @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). >- EFI_INVALID_PARAMETER - The parameter is not valid. >- EFI_SUCCESS - Open the file successfully. >- other - An error occured when locating the OFile. >+ @retval EFI_INVALID_PARAMETER - The parameter is not valid. >+ @retval EFI_SUCCESS - Open the file successfully. >+ @return other - An error occured when locating the OFil= e. > >---*/ >+**/ >+EFI_STATUS >+FatLocateOFile ( >+ IN OUT FAT_OFILE **PtrOFile, >+ IN CHAR16 *FileName, >+ IN UINT8 Attributes, >+ OUT CHAR16 *NewFileName >+ ) > { > EFI_STATUS Status; > FAT_VOLUME *Volume; > CHAR16 ComponentName[EFI_PATH_STRING_LENGTH]; > UINTN FileNameLen; >diff --git a/FatPkg/EnhancedFatDxe/DiskCache.c b/FatPkg/EnhancedFatDxe/Dis= kCache.c >index 7f1fcf4..63f9c00 100644 >--- a/FatPkg/EnhancedFatDxe/DiskCache.c >+++ b/FatPkg/EnhancedFatDxe/DiskCache.c >@@ -1,67 +1,49 @@ >-/*++ >+/** @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 availab= le > under the terms and conditions of the BSD License which accompanies this > distribution. The full text of the license may be found at > 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 IMPL= IED. > >+**/ > >-Module Name: >- >- DiskCache.c >+#include "Fat.h" > >-Abstract: >+/** > >- Cache implementation for EFI FAT File system driver >+ This function is used by the Data Cache. > >-Revision History >+ When this function is called by write command, all entries in this rang= e >+ are older than the contents in disk, so they are invalid; just mark the= m invalid. > >---*/ >+ When this function is called by read command, if any entry in this rang= e >+ 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. > >-#include "Fat.h" >+ @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 wh= en doing the read command >+ and there is dirty cache in the cache range, th= is parameter will be used. > >+**/ > 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. >- >- When this function is called by write command, all entries in this rang= e >- are older than the contents in disk, so they are invalid; just mark the= m invalid. >- >- When this function is called by read command, if any entry in this rang= e >- 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 writ= e 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 >- and there is dirty cache in the cache range, th= is parameter will be used. >- >-Returns: >- >- None. >- >---*/ > { > UINTN PageNo; > UINTN GroupNo; > UINTN GroupMask; > UINTN PageSize; >@@ -101,38 +83,33 @@ 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 pag= e. >+ @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 ( > IN FAT_VOLUME *Volume, > IN CACHE_DATA_TYPE DataType, > IN IO_MODE IoMode, > 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; > UINTN PageNo; > UINTN WriteCount; >@@ -179,37 +156,31 @@ Returns: > CacheTag->Dirty =3D FALSE; > CacheTag->RealSize =3D RealSize; > 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 pag= e. >+ >+ @retval EFI_SUCCESS - Get the cache page successfully. >+ @return other - An error occurred when accessing data. >+ >+**/ > STATIC > EFI_STATUS > FatGetCachePage ( > IN FAT_VOLUME *Volume, > IN CACHE_DATA_TYPE CacheDataType, > 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; > > OldPageNo =3D CacheTag->PageNo; >@@ -236,10 +207,27 @@ Returns: > Status =3D FatExchangeCachePage (Volume, CacheDataType, Read= Disk, CacheTag, NULL); > > 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 wri= tten >+ @param Buffer - Buffer containing cache data. >+ >+ @retval EFI_SUCCESS - The data was accessed correctly. >+ @return Others - An error occurred when accessing unalig= ned cache page. >+ >+**/ > STATIC > EFI_STATUS > FatAccessUnalignedCachePage ( > IN FAT_VOLUME *Volume, > IN CACHE_DATA_TYPE CacheDataType, >@@ -247,32 +235,10 @@ FatAccessUnalignedCachePage ( > IN UINTN PageNo, > IN UINTN Offset, > 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 cach= e page. >- >---*/ > { > EFI_STATUS Status; > VOID *Source; > VOID *Destination; > DISK_CACHE *DiskCache; >@@ -297,22 +263,11 @@ 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. > > Base on the parameter of CACHE_DATA_TYPE, the data access will be divid= ed into >@@ -324,26 +279,33 @@ Routine Description: > 2. Access of Data cache (CACHE_DATA): > The access data will be divided into UnderRun data, Aligned data and= OverRun data; > The UnderRun data and OverRun data will be accessed by the Data cach= e, > but the Aligned data will be accessed with disk directly. > >-Arguments: >- >- 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. >+ @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. > >-Returns: >+ @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. > >- 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; > UINTN UnderRun; > UINTN OverRun; >@@ -419,31 +381,26 @@ Returns: > } > > return Status; > } > >-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 cach= e. > >-Arguments: >- >- Volume - FAT file system volume. >+ @param Volume - FAT file system volume. >+ @param Task point to task instance. > >-Returns: >+ @retval EFI_SUCCESS - Flush all the dirty cache back successf= ully >+ @return other - An error occurred when writing the data= into the disk > >- EFI_SUCCESS - Flush all the dirty cache back successfully >- other - An error occurred when writing the data into th= e disk >- >---*/ >+**/ >+EFI_STATUS >+FatVolumeFlushCache ( >+ IN FAT_VOLUME *Volume, >+ IN FAT_TASK *Task >+ ) > { > EFI_STATUS Status; > CACHE_DATA_TYPE CacheDataType; > UINTN GroupIndex; > UINTN GroupMask; >@@ -478,30 +435,24 @@ Returns: > // > Status =3D Volume->BlockIo->FlushBlocks (Volume->BlockIo); > return Status; > } > >-EFI_STATUS >-FatInitializeDiskCache ( >- IN FAT_VOLUME *Volume >- ) >-/*++ >- >-Routine Description: >+/** > > Initialize the disk cache according to Volume's FatType. > >-Arguments: >- >- Volume - FAT file system volume. >+ @param Volume - FAT file system volume. > >-Returns: >+ @retval EFI_SUCCESS - The disk cache is successfully initiali= zed. >+ @retval EFI_OUT_OF_RESOURCES - Not enough memory to allocate disk cach= e. > >- EFI_SUCCESS - The disk cache is successfully initialized. >- EFI_OUT_OF_RESOURCES - Not enough memory to allocate disk cache. >- >---*/ >+**/ >+EFI_STATUS >+FatInitializeDiskCache ( >+ IN FAT_VOLUME *Volume >+ ) > { > DISK_CACHE *DiskCache; > UINTN FatCacheGroupCount; > UINTN DataCacheSize; > UINTN FatCacheSize; >diff --git a/FatPkg/EnhancedFatDxe/Fat.c b/FatPkg/EnhancedFatDxe/Fat.c >index 2080005..2e6c089 100644 >--- a/FatPkg/EnhancedFatDxe/Fat.c >+++ b/FatPkg/EnhancedFatDxe/Fat.c >@@ -1,26 +1,18 @@ >-/*++ >+/** @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 availab= le > under the terms and conditions of the BSD License which accompanies this > distribution. The full text of the license may be found at > 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 IMPL= IED. > >- >-Module Name: >- >- Fat.c >- >-Abstract: >- >- Fat File System driver routines that support EFI driver model >- >---*/ >+**/ > > #include "Fat.h" > > EFI_STATUS > EFIAPI >@@ -70,33 +62,27 @@ EFI_DRIVER_BINDING_PROTOCOL gFatDriverBinding =3D { > 0xa, > NULL, > 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; > > // > // Initialize the EFI Driver Library >@@ -112,31 +98,25 @@ Returns: > ASSERT_EFI_ERROR (Status); > > return Status; > } > >-EFI_STATUS >-EFIAPI >-FatUnload ( >- IN EFI_HANDLE ImageHandle >- ) >-/*++ >- >-Routine Description: >+/** > > Unload function for this image. Uninstall DriverBinding protocol. > >-Arguments: >+ @param ImageHandle - Handle for the image of this driver. > >- ImageHandle - Handle for the image of this driver. >+ @retval EFI_SUCCESS - Driver unloaded successfully. >+ @return other - Driver can not unloaded. > >-Returns: >- >- EFI_SUCCESS - Driver unloaded successfully. >- other - Driver can not unloaded. >- >---*/ >+**/ >+EFI_STATUS >+EFIAPI >+FatUnload ( >+ IN EFI_HANDLE ImageHandle >+ ) > { > EFI_STATUS Status; > EFI_HANDLE *DeviceHandleBuffer; > UINTN DeviceHandleCount; > UINTN Index; >@@ -222,37 +202,31 @@ 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 devic= e. >+ >+**/ > EFI_STATUS > EFIAPI > FatDriverBindingSupported ( > IN EFI_DRIVER_BINDING_PROTOCOL *This, > 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; > > // >@@ -293,39 +267,33 @@ Returns: > ); > > return Status; > } > >-EFI_STATUS >-EFIAPI >-FatDriverBindingStart ( >- IN EFI_DRIVER_BINDING_PROTOCOL *This, >- 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. >+ @param This - Protocol instance pointer. >+ @param ControllerHandle - Handle of device to bind driver to. >+ @param RemainingDevicePath - Not used. > >-Returns: >+ @retval EFI_SUCCESS - This driver is added to DeviceHandle. >+ @retval EFI_ALREADY_STARTED - This driver is already running on Devic= eHandle. >+ @retval EFI_OUT_OF_RESOURCES - Can not allocate the memory. >+ @return other - This driver does not support this devic= e. > >- 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 >+EFIAPI >+FatDriverBindingStart ( >+ IN EFI_DRIVER_BINDING_PROTOCOL *This, >+ IN EFI_HANDLE ControllerHandle, >+ IN EFI_DEVICE_PATH_PROTOCOL *RemainingDevicePath >+ ) > { > EFI_STATUS Status; > EFI_BLOCK_IO_PROTOCOL *BlockIo; > EFI_DISK_IO_PROTOCOL *DiskIo; > EFI_DISK_IO2_PROTOCOL *DiskIo2; >@@ -428,34 +396,31 @@ Exit: > FatReleaseLock (); > } > 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 d= evice. >+ >+**/ > EFI_STATUS > EFIAPI > FatDriverBindingStop ( > IN EFI_DRIVER_BINDING_PROTOCOL *This, > IN EFI_HANDLE ControllerHandle, > 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; > FAT_VOLUME *Volume; > EFI_DISK_IO2_PROTOCOL *DiskIo2; >diff --git a/FatPkg/EnhancedFatDxe/Fat.h b/FatPkg/EnhancedFatDxe/Fat.h >index f49acee..9490868 100644 >--- a/FatPkg/EnhancedFatDxe/Fat.h >+++ b/FatPkg/EnhancedFatDxe/Fat.h >@@ -1,28 +1,18 @@ >-/*++ >+/** @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 availab= le > under the terms and conditions of the BSD License which accompanies this > distribution. The full text of the license may be found at > 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 IMPL= IED. > >- >-Module Name: >- >- Fat.h >- >-Abstract: >- >- Main header file for EFI FAT file system driver >- >-Revision History >- >---*/ >+**/ > > #ifndef _FAT_H_ > #define _FAT_H_ > > #include >@@ -394,401 +384,321 @@ struct _FAT_VOLUME { > }; > > // > // Function Prototypes > // >+ >+/** >+ >+ Implements Open() of Simple File System Protocol. >+ >+ @param FHand - File handle of the file serves as a sta= rting 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 create= d. >+ >+ >+ @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 st= ring. >+ @retval EFI_SUCCESS - Open the file successfully. >+ @return Others - The status of open file. >+ >+**/ > EFI_STATUS > EFIAPI > FatOpen ( > IN EFI_FILE_PROTOCOL *FHand, > OUT EFI_FILE_PROTOCOL **NewHandle, > IN CHAR16 *FileName, > 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 re= ference 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. >+ Implements OpenEx() of Simple File System Protocol. > >-Returns: >+ @param FHand - File handle of the file serves as a sta= rting 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 create= d. >+ @param Token - A pointer to the token associated with = the transaction. > >- EFI_INVALID_PARAMETER - The FileName is NULL or the file string is empt= y. >+ @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. >- EFI_OUT_OF_RESOURCES - Can not allocate the memory for file string. >- EFI_SUCCESS - Open the file successfully. >- Others - The status of open file. >- >---*/ >-; >+ @retval EFI_OUT_OF_RESOURCES - Can not allocate the memory for file st= ring. >+ @retval EFI_SUCCESS - Open the file successfully. >+ @return Others - The status of open file. > >+**/ > EFI_STATUS > EFIAPI > FatOpenEx ( > IN EFI_FILE_PROTOCOL *FHand, > OUT EFI_FILE_PROTOCOL **NewHandle, > IN CHAR16 *FileName, > IN UINT64 OpenMode, > 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 re= ference 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 tran= saction. >+/** > >-Returns: >+ Get the file's position of the file > >- EFI_INVALID_PARAMETER - The FileName is NULL or the file string is empt= y. >- 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. >+ @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: >+ Get the some types info of the file into Buffer > >- 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. >+ @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 ( > IN EFI_FILE_PROTOCOL *FHand, > IN EFI_GUID *Type, > 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: >+ Set the some types info of the file into Buffer. > >- EFI_SUCCESS - Get the info successfully. >- EFI_DEVICE_ERROR - Can not find the OFile for the file. >+ @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 ( > IN EFI_FILE_PROTOCOL *FHand, > IN EFI_GUID *Type, > 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: >+ Flushes all data associated with the file handle. > >- EFI_SUCCESS - Set the info successfully. >- EFI_DEVICE_ERROR - Can not find the OFile for the file. >+ @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: >+ Flushes all data associated with the file handle. > >- 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 >+ @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 tran= saction. >+/** > >-Returns: >+ Flushes & Closes the file handle. > >- 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. >+ @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: >+ Deletes the file & Closes the file handle. > >- EFI_SUCCESS - Closed the file successfully. >+ @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: >+ Set the file's position of the file. > >- EFI_SUCCESS - Delete the file successfully. >- EFI_WARN_DELETE_FAILURE - Fail to delete 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 positio= n > >+**/ > 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 >+ Get the file info. > >-Returns: >+ @param FHand - The handle of the file. >+ @param BufferSize - Size of Buffer. >+ @param Buffer - Buffer containing read data. > >- 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 >- >---*/ >-; >+ @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 di= sk. > >+**/ > EFI_STATUS > EFIAPI > FatRead ( > IN EFI_FILE_PROTOCOL *FHand, > 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. >+ @param FHand - The handle of the file. >+ @param Token - A pointer to the token associated with t= he 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. >- >---*/ >-; >+ @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 di= sk. > >+**/ > 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 tran= saction. >+/** > >-Returns: >+ Set the file info. > >- 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. >+ @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 di= sk. > >+**/ > EFI_STATUS > EFIAPI > FatWrite ( > IN EFI_FILE_PROTOCOL *FHand, > 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. >+ Get the file info. > >-Returns: >+ @param FHand - The handle of the file. >+ @param Token - A pointer to the token associated with = the transaction. > >- 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. >- >---*/ >-; >+ @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 di= sk. > >+**/ > 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 tran= saction. >- >-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. >- >---*/ > ; > > // > // DiskCache.c > // >diff --git a/FatPkg/EnhancedFatDxe/FatFileSystem.h b/FatPkg/EnhancedFatDxe= /FatFileSystem.h >index 3f89a34..a4d4405 100644 >--- a/FatPkg/EnhancedFatDxe/FatFileSystem.h >+++ b/FatPkg/EnhancedFatDxe/FatFileSystem.h >@@ -1,6 +1,7 @@ >-/*++ >+/** @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 availab= le > under the terms and conditions of the BSD License which accompanies this > distribution. The full text of the license may be found at >@@ -8,21 +9,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 IMPL= IED. > > >-Module Name: >- >- FatFileSystem.h >- >-Abstract: >- >- Definitions for on-disk FAT structures >- >-Revision History >- >---*/ >+**/ > > #ifndef _FATFILESYSTEM_H_ > #define _FATFILESYSTEM_H_ > > #pragma pack(1) >diff --git a/FatPkg/EnhancedFatDxe/FileName.c b/FatPkg/EnhancedFatDxe/File= Name.c >index f393aa6..8aa3745 100644 >--- a/FatPkg/EnhancedFatDxe/FileName.c >+++ b/FatPkg/EnhancedFatDxe/FileName.c >@@ -1,55 +1,39 @@ >-/*++ >+/** @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 availab= le > under the terms and conditions of the BSD License which accompanies this > distribution. The full text of the license may be found at > 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 IMPL= IED. > >+**/ > >-Module Name: >- >- FileName.c >- >-Abstract: >+#include "Fat.h" > >- Functions for manipulating file names >+/** > >-Revision History >+ This function checks whether the input FileName is a valid 8.3 short na= me. >+ 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. > >---*/ >+ @param FileName - The input unicode filename. >+ @param File8Dot3Name - The output ascii 8.3 short name or base= tag of 8.3 short name. > >-#include "Fat.h" >+ @retval TRUE - The input unicode filename is a valid 8= .3 short name. >+ @retval FALSE - The input unicode filename is not a val= id 8.3 short name. > >+**/ > BOOLEAN > FatCheckIs8Dot3Name ( > IN CHAR16 *FileName, > OUT CHAR8 *File8Dot3Name > ) >-/*++ >- >-Routine Description: >- >- This function checks whether the input FileName is a valid 8.3 short na= me. >- 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: >- >- FileName - The input unicode filename. >- File8Dot3Name - The output ascii 8.3 short name or base tag of = 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 s= hort name. >- >---*/ > { > BOOLEAN PossibleShortName; > CHAR16 *TempName; > CHAR16 *ExtendName; > CHAR16 *SeparateDot; >@@ -116,66 +100,52 @@ Returns: > } > > return PossibleShortName; > } > >-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: >+ @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 >+ ) > { > while (Len > 0 && Name[Len - 1] =3D=3D ' ') { > Len--; > } > > return Len; > } > >+/** >+ >+ Convert the ascii fat name to the unicode string and strip trailing spa= ces, >+ 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, > IN UINTN Len, > IN UINTN LowerCase, > OUT CHAR16 *Str > ) >-/*++ >- >-Routine Description: >- >- Convert the ascii fat name to the unicode string and strip trailing spa= ces, >- 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 > // > Len =3D FatTrimAsciiTrailingBlanks (FatName, Len); >@@ -190,31 +160,23 @@ Returns: > if (LowerCase !=3D 0) { > FatStrLwr (Str); > } > } > >+/** >+ >+ 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 nee= ds 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; > UINTN BaseTagLen; > UINTN Index; >@@ -273,33 +235,27 @@ Returns: > *ShortNameChar =3D '1'; > } > } > } > >-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. >+ @param Str - The string which needs to be checked. >+ @param InCaseFlag - The input case flag which is returned wh= en the string is lower case. > >-Returns: >+ @retval OutCaseFlag - The output case flag. > >- OutCaseFlag - The output case flag. >- >---*/ >+**/ >+STATIC >+UINT8 >+FatCheckNameCase ( >+ IN CHAR16 *Str, >+ IN UINT8 InCaseFlag >+ ) > { > CHAR16 Buffer[FAT_MAIN_NAME_LEN + 1 + FAT_EXTEND_NAME_LEN + 1]; > UINT8 OutCaseFlag; > > // >@@ -326,29 +282,21 @@ Returns: > } > > return OutCaseFlag; > } > >-VOID >-FatSetCaseFlag ( >- IN FAT_DIRENT *DirEnt >- ) >-/*++ >- >-Routine Description: >+/** > > Set the caseflag value for the directory entry. > >-Arguments: >- >- DirEnt - The logical directory entry whose caseflag valu= e is to be set. >- >-Returns: >- >- None. >+ @param DirEnt - The logical directory entry whose casefl= ag value is to be set. > >---*/ >+**/ >+VOID >+FatSetCaseFlag ( >+ IN FAT_DIRENT *DirEnt >+ ) > { > CHAR16 LfnBuffer[FAT_MAIN_NAME_LEN + 1 + FAT_EXTEND_NAME_LEN + 1]; > CHAR16 *TempCharPtr; > CHAR16 *ExtendName; > CHAR16 *FileNameCharPtr; >@@ -387,32 +335,25 @@ Returns: > DirEnt->Entry.CaseFlag =3D 0; > DirEnt->EntryCount++; > } > } > >+/** >+ >+ Convert the 8.3 ASCII fat name to cased Unicode string according to cas= e 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 cas= e flag. >- >-Arguments: >- >- DirEnt - The corresponding directory entry. >- FileString - The output Unicode file name. >- >-Returns: >- >- None. >- >---*/ > { > UINT8 CaseFlag; > CHAR8 *File8Dot3Name; > CHAR16 TempExt[1 + FAT_EXTEND_NAME_LEN + 1]; > // >@@ -427,29 +368,23 @@ Returns: > TempExt[0] =3D L'.'; > StrCatS (FileString, FileStringMax, TempExt); > } > } > >-UINT8 >-FatCheckSum ( >- IN CHAR8 *ShortNameString >- ) >-/*++ >- >-Routine Description: >+/** > > Get the Check sum for a short name. > >-Arguments: >+ @param ShortNameString - The short name for a file. > >- ShortNameString - The short name for a file. >+ @retval Sum - UINT8 checksum. > >-Returns: >- >- Sum - UINT8 checksum. >- >---*/ >+**/ >+UINT8 >+FatCheckSum ( >+ IN CHAR8 *ShortNameString >+ ) > { > UINTN ShortNameLen; > UINT8 Sum; > Sum =3D 0; > for (ShortNameLen =3D FAT_NAME_LEN; ShortNameLen !=3D 0; ShortNameLen--= ) { >@@ -457,33 +392,27 @@ 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 !=3D 0 && *Path !=3D PATH_NAME_SEPARATOR) { > *Name++ =3D *Path++; > } > *Name =3D 0; >@@ -495,35 +424,28 @@ 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 i= s a valid > long file name, then we trim the possible leading blanks and leading/tr= ailing 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 f= ile 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; > // > // Trim Leading blanks >diff --git a/FatPkg/EnhancedFatDxe/FileSpace.c b/FatPkg/EnhancedFatDxe/Fil= eSpace.c >index db44a33..1254cd6 100644 >--- a/FatPkg/EnhancedFatDxe/FileSpace.c >+++ b/FatPkg/EnhancedFatDxe/FileSpace.c >@@ -1,6 +1,7 @@ >-/*++ >+/** @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 availab= le > under the terms and conditions of the BSD License which accompanies this > distribution. The full text of the license may be found at >@@ -8,47 +9,32 @@ 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 IMPL= IED. > > >-Module Name: > >- FileSpace.c >+**/ > >-Abstract: >+#include "Fat.h" > >- Routines dealing with disk spaces and FAT table entries > >-Revision History >+/** > >---*/ >+ Get the FAT entry of the volume, which is identified with the Index. > >-#include "Fat.h" >+ @param Volume - FAT file system volume. >+ @param Index - The index of the FAT entry of the volum= e. > >+ @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; > > if (Index > (Volume->MaxCluster + 1)) { >@@ -87,32 +73,26 @@ Returns: > } > > return &Volume->FatEntryBuffer; > } > >+/** >+ >+ Get the FAT entry value of the volume, which is identified with the Ind= ex. >+ >+ @param Volume - FAT file system volume. >+ @param Index - The index of the FAT entry of the volum= e. >+ >+ @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 Ind= ex. >- >-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; > UINT16 *En16; > UINT32 *En32; >@@ -145,36 +125,30 @@ Returns: > } > > return Accum; > } > >+/** >+ >+ Set the FAT entry value of the volume, which is identified with the Ind= ex. >+ >+ @param Volume - FAT file system volume. >+ @param Index - The index of the FAT entry of the volum= e. >+ @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 FA= T entries. >+ >+**/ > STATIC > EFI_STATUS > FatSetFatEntry ( > IN FAT_VOLUME *Volume, > IN UINTN Index, > IN UINTN Value > ) >-/*++ >- >-Routine Description: >- >- Set the FAT entry value of the volume, which is identified with the Ind= ex. >- >-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 entrie= s. >- >---*/ > { > VOID *Pos; > UINT8 *En12; > UINT16 *En16; > UINT32 *En32; >@@ -251,33 +225,27 @@ Returns: > NULL > ); > 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; > > while (!FAT_END_OF_FAT_CHAIN (Cluster)) { > if (Cluster =3D=3D FAT_CLUSTER_FREE || Cluster >=3D FAT_CLUSTER_SPECI= AL) { >@@ -292,30 +260,24 @@ Returns: > } > > return EFI_SUCCESS; > } > >-STATIC >-UINTN >-FatAllocateCluster ( >- IN FAT_VOLUME *Volume >- ) >-/*++ >- >-Routine Description: >+/** > > Allocate a free cluster and return the cluster index. > >-Arguments: >- >- Volume - FAT file system volume. >+ @param Volume - FAT file system volume. > >-Returns: >+ @return The index of the free cluster > >- The index of the free cluster >- >---*/ >+**/ >+STATIC >+UINTN >+FatAllocateCluster ( >+ IN FAT_VOLUME *Volume >+ ) > { > UINTN Cluster; > > // > // Start looking at FatFreePos for the next unallocated cluster >@@ -352,32 +314,26 @@ Returns: > Cluster =3D Volume->FatInfoSector.FreeInfo.NextCluster; > Volume->FatInfoSector.FreeInfo.NextCluster +=3D 1; > 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; > > Clusters =3D Size >> Volume->ClusterAlignment; > if ((Size & (Volume->ClusterSize - 1)) > 0) { >@@ -385,30 +341,24 @@ Returns: > } > > return 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. >+ @param OFile - The open file. > >-Returns: >+ @retval EFI_SUCCESS - Shrinked sucessfully. >+ @retval EFI_VOLUME_CORRUPTED - There are errors in the file's clusters= . > >- EFI_SUCCESS - Shrinked sucessfully. >- EFI_VOLUME_CORRUPTED - There are errors in the file's clusters. >- >---*/ >+**/ >+EFI_STATUS >+FatShrinkEof ( >+ IN FAT_OFILE *OFile >+ ) > { > FAT_VOLUME *Volume; > UINTN NewSize; > UINTN CurSize; > UINTN Cluster; >@@ -463,34 +413,28 @@ Returns: > // Free the remaining cluster chain > // > return FatFreeClusters (Volume, Cluster); > } > >-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. >+ @param OFile - The open file. >+ @param NewSizeInBytes - The new size in bytes of the open file. > >-Returns: >+ @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_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. >- >---*/ >+**/ >+EFI_STATUS >+FatGrowEof ( >+ IN FAT_OFILE *OFile, >+ IN UINT64 NewSizeInBytes >+ ) > { > FAT_VOLUME *Volume; > EFI_STATUS Status; > UINTN Cluster; > UINTN CurSize; >@@ -589,35 +533,29 @@ Returns: > Done: > FatShrinkEof (OFile); > return Status; > } > >-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 >+ @param OFile - The open file. >+ @param Position - The file's position which will be acces= sed. >+ @param PosLimit - The maximum length current reading/writ= ing may access > >-Returns: >+ @retval EFI_SUCCESS - Set the info successfully. >+ @retval EFI_VOLUME_CORRUPTED - Cluster chain corrupt. > >- EFI_SUCCESS - Set the info successfully. >- EFI_VOLUME_CORRUPTED - Cluster chain corrupt. >- >---*/ >+**/ >+EFI_STATUS >+FatOFilePosition ( >+ IN FAT_OFILE *OFile, >+ IN UINTN Position, >+ IN UINTN PosLimit >+ ) > { > FAT_VOLUME *Volume; > UINTN ClusterSize; > UINTN Cluster; > UINTN StartPos; >@@ -689,32 +627,26 @@ Returns: > > OFile->PosRem =3D Run; > return EFI_SUCCESS; > } > >-UINTN >-FatPhysicalDirSize ( >- IN FAT_VOLUME *Volume, >- IN UINTN Cluster >- ) >-/*++ >- >-Routine Description: >- >- Get the size of directory of the open file >+/** > >-Arguments: >+ Get the size of directory of the open file. > >- Volume - The File System Volume. >- Cluster - The Starting cluster. >+ @param Volume - The File System Volume. >+ @param Cluster - The Starting cluster. > >-Returns: >- >- The physical size of the file starting at the input cluster, if there i= s error in the >+ @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 >+ ) > { > UINTN Size; > ASSERT_VOLUME_LOCKED (Volume); > // > // Run the cluster chain for the OFile >@@ -740,58 +672,44 @@ 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; > ClusterSizeMask =3D Volume->ClusterSize - 1; > PhysicalSize =3D (RealSize + ClusterSizeMask) & (~((UINT64) ClusterS= izeMask)); > return PhysicalSize; > } > >-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. >+ @param Volume - FAT file system volume. > >---*/ >+**/ >+VOID >+FatComputeFreeInfo ( >+ IN FAT_VOLUME *Volume >+ ) > { > UINTN Index; > > // > // If we don't have valid info, compute it now >diff --git a/FatPkg/EnhancedFatDxe/Flush.c b/FatPkg/EnhancedFatDxe/Flush.c >index 172f202..9cb0d9a 100644 >--- a/FatPkg/EnhancedFatDxe/Flush.c >+++ b/FatPkg/EnhancedFatDxe/Flush.c >@@ -1,6 +1,7 @@ >-/*++ >+/** @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 availab= le > under the terms and conditions of the BSD License which accompanies this > distribution. The full text of the license may be found at >@@ -8,49 +9,33 @@ 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 IMPL= IED. > > >-Module Name: >- >- flush.c >+**/ > >-Abstract: >+#include "Fat.h" > >- Routines that check references and flush OFiles >+/** > >-Revision History >+ 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. > >-#include "Fat.h" >+ @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 tran= saction. >- >-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; > FAT_VOLUME *Volume; > EFI_STATUS Status; >@@ -111,57 +96,45 @@ Returns: > } > > return Status; > } > >-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: >+ @param FHand - Handle to file to flush. > >- 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); >-} >+ @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 >-FatClose ( >+FatFlush ( > IN EFI_FILE_PROTOCOL *FHand > ) >-/*++ >+{ >+ return FatFlushEx (FHand, NULL); >+} > >-Routine Description: >+/** > > Flushes & Closes the file handle. > >-Arguments: >- >- FHand - Handle to the file to delete. >- >-Returns: >+ @param FHand - Handle to the file to delete. > >- EFI_SUCCESS - Closed the file successfully. >+ @retval EFI_SUCCESS - Closed the file successfully. > >---*/ >+**/ >+EFI_STATUS >+EFIAPI >+FatClose ( >+ IN EFI_FILE_PROTOCOL *FHand >+ ) > { > FAT_IFILE *IFile; > FAT_OFILE *OFile; > FAT_VOLUME *Volume; > >@@ -189,29 +162,23 @@ Returns: > // Close always succeed > // > return EFI_SUCCESS; > } > >-EFI_STATUS >-FatIFileClose ( >- FAT_IFILE *IFile >- ) >-/*++ >- >-Routine Description: >+/** > > Close the open file instance. > >-Arguments: >+ @param IFile - Open file instance. > >- IFile - Open file instance. >+ @retval EFI_SUCCESS - Closed the file successfully. > >-Returns: >- >- EFI_SUCCESS - Closed the file successfully. >- >---*/ >+**/ >+EFI_STATUS >+FatIFileClose ( >+ FAT_IFILE *IFile >+ ) > { > FAT_OFILE *OFile; > FAT_VOLUME *Volume; > > OFile =3D IFile->OFile; >@@ -237,31 +204,25 @@ Returns: > // > FreePool (IFile); > 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 OF= ile. > >-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; > FAT_DIRENT *DirEnt; > FAT_DATE_TIME FatNow; >@@ -316,32 +277,26 @@ Returns: > OFile =3D Parent; > } while (OFile !=3D NULL); > 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 > // > if (OFile->CheckLink.ForwardLink !=3D NULL) { >@@ -364,33 +319,25 @@ Returns: > // > FatCloseDirEnt (OFile->DirEnt); > 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: >- >- Volume - The volume to check the pending open file list. >- >-Returns: >+ @param Volume - The volume to check the pending open fi= le list. > >- None >- >---*/ >+**/ >+STATIC >+VOID >+FatCheckVolumeRef ( >+ IN FAT_VOLUME *Volume >+ ) > { > FAT_OFILE *OFile; > FAT_OFILE *Parent; > > // >@@ -412,38 +359,33 @@ Returns: > } > } > } > } > >-EFI_STATUS >-FatCleanupVolume ( >- IN FAT_VOLUME *Volume, >- IN FAT_OFILE *OFile, >- 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: >+ @param Volume - the Volume that is to be reference chec= ked 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. > >- Volume - the Volume that is to be reference checked and = unlocked. >- OFile - the OFile whose permanent error code is to be s= et. >- EfiStatus - error code to be set. >+ @retval EFI_SUCCESS - Clean up the volume successfully. >+ @return Others - Cleaning up of the volume is failed. > >-Returns: >- >- EFI_SUCCESS - Clean up the volume successfully. >- Others - Cleaning up of the volume is failed. >- >---*/ >+**/ >+EFI_STATUS >+FatCleanupVolume ( >+ IN FAT_VOLUME *Volume, >+ IN FAT_OFILE *OFile, >+ IN EFI_STATUS EfiStatus, >+ IN FAT_TASK *Task >+ ) > { > EFI_STATUS Status; > // > // Flag the OFile > // >@@ -497,31 +439,23 @@ 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 s= et. >- 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 f827368..5a9bbda 100644 >--- a/FatPkg/EnhancedFatDxe/Hash.c >+++ b/FatPkg/EnhancedFatDxe/Hash.c >@@ -1,51 +1,35 @@ >-/*++ >+/** @file >+ Hash table operations. > > Copyright (c) 2005 - 2015, Intel Corporation. All rights reserved.
> This program and the accompanying materials are licensed and made availab= le > under the terms and conditions of the BSD License which accompanies this > distribution. The full text of the license may be found at > 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 IMPL= IED. > >+**/ > >-Module Name: >- >- Hash.c >- >-Abstract: >+#include "Fat.h" > >- Hash table operations >+/** > >-Revision History >+ Get hash value for long name. > >---*/ >+ @param LongNameString - The long name string to be hashed. > >-#include "Fat.h" >+ @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]; > StrnCpyS ( > UpCasedLongFileName, >@@ -56,57 +40,45 @@ Returns: > FatStrUpr (UpCasedLongFileName); > gBS->CalculateCrc32 (UpCasedLongFileName, StrSize (UpCasedLongFileName)= , &HashValue); > return (HashValue & HASH_TABLE_MASK); > } > >-STATIC >-UINT32 >-FatHashShortName ( >- IN CHAR8 *ShortNameString >- ) >-/*++ >- >-Routine Description: >+/** > > Get hash value for short name. > >-Arguments: >+ @param ShortNameString - The short name string to be hashed. > >- ShortNameString - The short name string to be hashed. >+ @return HashValue > >-Returns: >- >- HashValue >- >---*/ >+**/ >+STATIC >+UINT32 >+FatHashShortName ( >+ IN CHAR8 *ShortNameString >+ ) > { > UINT32 HashValue; > gBS->CalculateCrc32 (ShortNameString, FAT_NAME_LEN, &HashValue); > return (HashValue & HASH_TABLE_MASK); > } > >-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: >+ @param ODir - The directory to be searched. >+ @param LongNameString - The long name string to search. > >- The previous long name hash node of the directory entry. >+ @return The previous long name hash node of the directory entry. > >---*/ >+**/ >+FAT_DIRENT ** >+FatLongNameHashSearch ( >+ IN FAT_ODIR *ODir, >+ IN CHAR16 *LongNameString >+ ) > { > FAT_DIRENT **PreviousHashNode; > for (PreviousHashNode =3D &ODir->LongNameHashTable[FatHashLongName (L= ongNameString)]; > *PreviousHashNode !=3D NULL; > PreviousHashNode =3D &(*PreviousHashNode)->LongNameForwardLink >@@ -117,31 +89,25 @@ Returns: > } > > return PreviousHashNode; > } > >-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. >+ @param ODir - The directory to be searched. >+ @param ShortNameString - The short name string to search. > >-Returns: >+ @return The previous short name hash node of the directory entry. > >- The previous short name hash node of the directory entry. >- >---*/ >+**/ >+FAT_DIRENT ** >+FatShortNameHashSearch ( >+ IN FAT_ODIR *ODir, >+ IN CHAR8 *ShortNameString >+ ) > { > FAT_DIRENT **PreviousHashNode; > for (PreviousHashNode =3D &ODir->ShortNameHashTable[FatHashShortName = (ShortNameString)]; > *PreviousHashNode !=3D NULL; > PreviousHashNode =3D &(*PreviousHashNode)->ShortNameForwardLink >@@ -152,31 +118,23 @@ 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; > > // >@@ -193,30 +151,22 @@ Returns: > HashTable =3D ODir->LongNameHashTable; > DirEnt->LongNameForwardLink =3D HashTable[HashTableIndex]; > HashTable[HashTableIndex] =3D 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) =3D DirEnt->Shor= tNameForwardLink; > *FatLongNameHashSearch (ODir, DirEnt->FileString) =3D DirEnt->Long= NameForwardLink; > } >diff --git a/FatPkg/EnhancedFatDxe/Info.c b/FatPkg/EnhancedFatDxe/Info.c >index aa1b0f2..1a7f828 100644 >--- a/FatPkg/EnhancedFatDxe/Info.c >+++ b/FatPkg/EnhancedFatDxe/Info.c >@@ -1,6 +1,7 @@ >-/*++ >+/** @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 availab= le > under the terms and conditions of the BSD License which accompanies this > distribution. The full text of the license may be found at >@@ -8,21 +9,12 @@ 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 IMPL= IED. > > >-Module Name: >- >- Info.c >- >-Abstract: >- >- Routines dealing with setting/getting file/volume info >- >-Revision History > >---*/ >+**/ > > #include "Fat.h" > > EFI_STATUS > FatGetVolumeInfo ( >@@ -45,62 +37,50 @@ FatSetOrGetInfo ( > IN EFI_GUID *Type, > IN OUT UINTN *BufferSize, > 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: >+{ >+ return FatGetDirEntInfo (OFile->Volume, OFile->DirEnt, BufferSize, Buff= er); >+} > >- OFile - The open file. >- BufferSize - Size of Buffer. >- Buffer - Buffer containing file info. >+/** > >-Returns: >+ Get the volume's info into Buffer. > >- EFI_SUCCESS - Get the file info successfully. >- EFI_BUFFER_TOO_SMALL - The buffer is too small. >+ @param Volume - FAT file system volume. >+ @param BufferSize - Size of Buffer. >+ @param Buffer - Buffer containing volume info. > >---*/ >-{ >- return FatGetDirEntInfo (OFile->Volume, OFile->DirEnt, BufferSize, Buff= er); >-} >+ @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; > UINTN ResultSize; > CHAR16 Name[FAT_NAME_LEN + 1]; >@@ -139,34 +119,28 @@ Returns: > > *BufferSize =3D ResultSize; > 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 successfull= y. >+ @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; > UINTN ResultSize; > CHAR16 Name[FAT_NAME_LEN + 1]; >@@ -185,36 +159,30 @@ Returns: > > *BufferSize =3D ResultSize; > 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 di= sk. >+ >+**/ > 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; > > Info =3D (EFI_FILE_SYSTEM_INFO *) Buffer; > >@@ -223,36 +191,30 @@ 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 di= sk. >+ >+**/ > 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; > > Info =3D (EFI_FILE_SYSTEM_VOLUME_LABEL *) Buffer; > >@@ -261,48 +223,42 @@ 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 err= or. >+ @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 di= sk. >+ >+**/ > EFI_STATUS > FatSetFileInfo ( > IN FAT_VOLUME *Volume, > IN FAT_IFILE *IFile, > IN FAT_OFILE *OFile, > 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; > FAT_OFILE *DotOFile; > FAT_OFILE *Parent; >@@ -470,38 +426,32 @@ Returns: > > OFile->Dirty =3D TRUE; > 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, > IN EFI_FILE_PROTOCOL *FHand, > IN EFI_GUID *Type, > 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; > FAT_VOLUME *Volume; > EFI_STATUS Status; >@@ -558,66 +508,54 @@ Returns: > > FatReleaseLock (); > 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 ( > IN EFI_FILE_PROTOCOL *FHand, > IN EFI_GUID *Type, > IN OUT UINTN *BufferSize, > OUT VOID *Buffer > ) >-/*++ >- >-Routine Description: >- >- Get the some types info of the file into Buffer. >- >-Arguments: >+{ >+ return FatSetOrGetInfo (FALSE, FHand, Type, BufferSize, Buffer); >+} > >- FHand - The handle of file. >- Type - The type of the info. >- BufferSize - Size of Buffer. >- Buffer - Buffer containing volume info. >+/** > >-Returns: >+ Set the some types info of the file into Buffer. > >- EFI_SUCCESS - Get the info successfully. >- EFI_DEVICE_ERROR - Can not find the OFile for the file. >+ @param FHand - The handle of file. >+ @param Type - The type of the info. >+ @param BufferSize - Size of Buffer >+ @param Buffer - Buffer containing volume info. > >---*/ >-{ >- return FatSetOrGetInfo (FALSE, FHand, Type, BufferSize, Buffer); >-} >+ @retval EFI_SUCCESS - Set the info successfully. >+ @retval EFI_DEVICE_ERROR - Can not find the OFile for the file. > >+**/ > EFI_STATUS > EFIAPI > FatSetInfo ( > IN EFI_FILE_PROTOCOL *FHand, > IN EFI_GUID *Type, > 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 d7cfa82..6febffc 100644 >--- a/FatPkg/EnhancedFatDxe/Init.c >+++ b/FatPkg/EnhancedFatDxe/Init.c >@@ -1,56 +1,43 @@ >-/*++ >+/** @file >+ Initialization routines. > > Copyright (c) 2005 - 2013, Intel Corporation. All rights reserved.
> This program and the accompanying materials are licensed and made availab= le > under the terms and conditions of the BSD License which accompanies this > distribution. The full text of the license may be found at > 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 IMPL= IED. > >+**/ > >-Module Name: >- >- Init.c >+#include "Fat.h" > >-Abstract: >+/** > >- Initialization routines >+ 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 > >-#include "Fat.h" >+ @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, > IN EFI_DISK_IO_PROTOCOL *DiskIo, > 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; > > // >@@ -118,30 +105,24 @@ Done: > } > > return Status; > } > >-EFI_STATUS >-FatAbandonVolume ( >- IN FAT_VOLUME *Volume >- ) >-/*++ >- >-Routine Description: >+/** > > Called by FatDriverBindingStop(), Abandon the volume. > >-Arguments: >- >- Volume - The volume to be abandoned. >- >-Returns: >+ @param Volume - The volume to be abandoned. > >- EFI_SUCCESS - Abandoned the volume successfully. >- Others - Can not uninstall the protocol interfaces. >+ @retval EFI_SUCCESS - Abandoned the volume successfully. >+ @return Others - Can not uninstall the protocol interfac= es. > >---*/ >+**/ >+EFI_STATUS >+FatAbandonVolume ( >+ IN FAT_VOLUME *Volume >+ ) > { > EFI_STATUS Status; > BOOLEAN LockedByMe; > > // >@@ -200,31 +181,25 @@ Returns: > } > > return EFI_SUCCESS; > } > >-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. >+ Detects FAT file system on Disk and set relevant fields of Volume. > >-Returns: >+ @param Volume - The volume structure. > >- 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. >+ @retval EFI_SUCCESS - The Fat File System is detected success= fully >+ @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 >+ ) > { > EFI_STATUS Status; > UINT32 BlockSize; > UINT32 DirtyMask; > EFI_DISK_IO_PROTOCOL *DiskIo; >diff --git a/FatPkg/EnhancedFatDxe/Misc.c b/FatPkg/EnhancedFatDxe/Misc.c >index 48c99f9..c36bdb8 100644 >--- a/FatPkg/EnhancedFatDxe/Misc.c >+++ b/FatPkg/EnhancedFatDxe/Misc.c >@@ -1,6 +1,7 @@ >-/*++ >+/** @file >+ Miscellaneous functions. > > Copyright (c) 2005 - 2013, Intel Corporation. All rights reserved.
> This program and the accompanying materials are licensed and made availab= le > under the terms and conditions of the BSD License which accompanies this > distribution. The full text of the license may be found at >@@ -8,43 +9,29 @@ 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 IMPL= IED. > > >-Module Name: >- >- Misc.c >+**/ > >-Abstract: >+#include "Fat.h" > >- Miscellaneous functions >+/** > >-Revision History >+ Create the task > >---*/ >+ @param IFile - The instance of the open file. >+ @param Token - A pointer to the token associated with = the transaction. > >-#include "Fat.h" >+ @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 tran= saction. >- >-Return: >- FAT_TASK * - Return the task instance. >-**/ > { > FAT_TASK *Task; > > Task =3D AllocateZeroPool (sizeof (*Task)); > if (Task !=3D NULL) { >@@ -55,24 +42,21 @@ Return: > InitializeListHead (&Task->Link); > } > return Task; > } > >-VOID >-FatDestroyTask ( >- FAT_TASK *Task >- ) >-/*++ >- >-Routine Description: >+/** > >- Destroy the task >+ Destroy the task. > >-Arguments: >+ @param Task - The task to be destroyed. > >- Task - The task to be destroyed. > **/ >+VOID >+FatDestroyTask ( >+ FAT_TASK *Task >+ ) > { > LIST_ENTRY *Link; > FAT_SUBTASK *Subtask; > > Link =3D GetFirstNode (&Task->Subtasks); >@@ -81,53 +65,44 @@ Arguments: > Link =3D FatDestroySubtask (Subtask); > } > FreePool (Task); > } > >-VOID >-FatWaitNonblockingTask ( >- FAT_IFILE *IFile >- ) >-/*++ >- >-Routine Description: >+/** > > Wait all non-blocking requests complete. > >-Arguments: >+ @param IFile - The instance of the open file. > >- IFile - The instance of the open file. > **/ >+VOID >+FatWaitNonblockingTask ( >+ FAT_IFILE *IFile >+ ) > { > BOOLEAN TaskQueueEmpty; > > do { > EfiAcquireLock (&FatTaskLock); > TaskQueueEmpty =3D IsListEmpty (&IFile->Tasks); > EfiReleaseLock (&FatTaskLock); > } while (!TaskQueueEmpty); > } > >-LIST_ENTRY * >-FatDestroySubtask ( >- FAT_SUBTASK *Subtask >- ) >-/*++ >- >-Routine Description: >+/** > > Remove the subtask from subtask list. > >-Arguments: >- >- Subtask - The subtask to be removed. >+ @param Subtask - The subtask to be removed. > >-Returns: >+ @return LIST_ENTRY * - The next node in the list. > >- LIST_ENTRY * - The next node in the list. >- >---*/ >+**/ >+LIST_ENTRY * >+FatDestroySubtask ( >+ FAT_SUBTASK *Subtask >+ ) > { > LIST_ENTRY *Link; > > gBS->CloseEvent (Subtask->DiskIo2Token.Event); > >@@ -135,32 +110,26 @@ Returns: > FreePool (Subtask); > > 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 ta= sk. >+ >+**/ > 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; > FAT_SUBTASK *Subtask; > >@@ -236,43 +205,37 @@ 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 FA= T 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 entrie= s. >- >---*/ > { > UINTN WriteCount; > > WriteCount =3D Volume->FatEntrySize; > return FatDiskIo (Volume, IoMode, Volume->FatPos + WriteCount, WriteCou= nt, DirtyValue, NULL); > } > > /** >- Invoke a notification event >+ Invoke a notification event. > > @param Event Event whose notification function is bein= g invoked. > @param Context The pointer to the notification function'= s context, > which is implementation-dependent. > >@@ -281,26 +244,10 @@ VOID > EFIAPI > 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 invo= ked. >- Context - The pointer to the notification function's cont= ext, >- which is implementation-dependent. >- >---*/ > { > EFI_STATUS Status; > FAT_SUBTASK *Subtask; > FAT_TASK *Task; > >@@ -339,40 +286,35 @@ Arguments: > RemoveEntryList (&Task->Link); > FreePool (Task); > } > } > >+/** >+ >+ General disk access function. >+ >+ @param Volume - FAT file system volume. >+ @param IoMode - The access mode (disk read/write or cac= he 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, > IN IO_MODE IoMode, > IN UINT64 Offset, > IN UINTN BufferSize, > 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 acces= s). >- 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; > EFI_DISK_READ IoFunction; > FAT_SUBTASK *Subtask; >@@ -435,128 +377,84 @@ 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: >- >- None. >- >-Returns: >+ @retval EFI_SUCCESS - The volume is locked. >+ @retval EFI_ACCESS_DENIED - The volume could not be locked because = it is already locked. > >- EFI_SUCCESS - The volume is locked. >- EFI_ACCESS_DENIED - The volume could not be locked because it is al= ready 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); > } > >-VOID >-FatFreeDirEnt ( >- IN FAT_DIRENT *DirEnt >- ) >-/*++ >- >-Routine Description: >+/** > > Free directory entry. > >-Arguments: >- >- DirEnt - The directory entry to be freed. >- >-Returns: >+ @param DirEnt - The directory entry to be freed. > >- None. >- >---*/ >+**/ >+VOID >+FatFreeDirEnt ( >+ IN FAT_DIRENT *DirEnt >+ ) > { > if (DirEnt->FileString !=3D NULL) { > FreePool (DirEnt->FileString); > } > > FreePool (DirEnt); > } > >-VOID >-FatFreeVolume ( >- IN FAT_VOLUME *Volume >- ) >-/*++ >- >-Routine Description: >+/** > > Free volume structure (including the contents of directory cache and di= sk cache). > >-Arguments: >- >- Volume - The volume structure to be freed. >+ @param Volume - The volume structure to be freed. > >-Returns: >- >- None. >- >---*/ >+**/ >+VOID >+FatFreeVolume ( >+ IN FAT_VOLUME *Volume >+ ) > { > // > // Free disk cache > // > if (Volume->CacheBuffer !=3D NULL) { >@@ -567,31 +465,23 @@ Returns: > // > FatCleanupODirCache (Volume); > 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 > // > if (ETime->Year > 1980) { >@@ -607,31 +497,23 @@ Returns: > FTime->Time.Hour =3D ETime->Hour; > FTime->Time.Minute =3D ETime->Minute; > FTime->Time.DoubleSecond =3D (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 =3D (UINT16) (FTime->Date.Year + 1980); > ETime->Month =3D (UINT8) FTime->Date.Month; > ETime->Day =3D (UINT8) FTime->Date.Day; > ETime->Hour =3D (UINT8) FTime->Time.Hour; >@@ -640,29 +522,21 @@ Returns: > ETime->Nanosecond =3D 0; > ETime->TimeZone =3D EFI_UNSPECIFIED_TIMEZONE; > ETime->Daylight =3D 0; > } > >-VOID >-FatGetCurrentFatTime ( >- OUT FAT_DATE_TIME *FatNow >- ) >-/*++ >- >-Routine Description: >+/** > > Get Current FAT time. > >-Arguments: >- >- FatNow - Current FAT time. >- >-Returns: >+ @param FatNow - Current FAT time. > >- None. >- >---*/ >+**/ >+VOID >+FatGetCurrentFatTime ( >+ OUT FAT_DATE_TIME *FatNow >+ ) > { > EFI_STATUS Status; > EFI_TIME Now; > > Status =3D gRT->GetTime (&Now, NULL); >@@ -675,30 +549,24 @@ Returns: > Now.Day =3D 1; > FatEfiTimeToFatTime (&Now, FatNow); > } > } > >-BOOLEAN >-FatIsValidTime ( >- IN EFI_TIME *Time >- ) >-/*++ >- >-Routine Description: >+/** > > Check whether a time is valid. > >-Arguments: >- >- Time - The time of EFI_TIME. >+ @param Time - The time of EFI_TIME. > >-Returns: >+ @retval TRUE - The time is valid. >+ @retval FALSE - The time is not valid. > >- TRUE - The time is valid. >- FALSE - The time is not valid. >- >---*/ >+**/ >+BOOLEAN >+FatIsValidTime ( >+ IN EFI_TIME *Time >+ ) > { > STATIC UINT8 MonthDays[12]; > UINTN Day; > BOOLEAN ValidTime; > >diff --git a/FatPkg/EnhancedFatDxe/Open.c b/FatPkg/EnhancedFatDxe/Open.c >index 1d864d1..7b273fe 100644 >--- a/FatPkg/EnhancedFatDxe/Open.c >+++ b/FatPkg/EnhancedFatDxe/Open.c >@@ -1,54 +1,38 @@ >-/*++ >+/** @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 availab= le > under the terms and conditions of the BSD License which accompanies this > distribution. The full text of the license may be found at > 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 IMPL= IED. > >+**/ > >-Module Name: >- >- open.c >+#include "Fat.h" > >-Abstract: >+/** > >- Routines dealing with file open >+ Create an Open instance for the existing OFile. >+ The IFile of the newly opened file is passed out. > >-Revision History >+ @param OFile - The file that serves as a starting refe= rence point. >+ @param PtrIFile - The newly generated IFile instance. > >---*/ >- >-#include "Fat.h" >+ @retval EFI_OUT_OF_RESOURCES - Can not allocate the memory for the IFi= le >+ @retval EFI_SUCCESS - Create the new IFile for the OFile succ= essfully > >+**/ > 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 po= int. >- 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; > > ASSERT_VOLUME_LOCKED (OFile->Volume); > >@@ -79,45 +63,40 @@ Returns: > > *PtrIFile =3D IFile; > return EFI_SUCCESS; > } > >-EFI_STATUS >-FatOFileOpen ( >- IN FAT_OFILE *OFile, >- OUT FAT_IFILE **NewIFile, >- IN CHAR16 *FileName, >- 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 po= int. >- 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. >+ @param OFile - The file that serves as a starting refe= rence 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 create= d. > >-Returns: > >- EFI_SUCCESS - Open the file successfully. >- EFI_INVALID_PARAMETER - The open mode is conflict with the attributes >+ @retval EFI_SUCCESS - Open the file successfully. >+ @retval EFI_INVALID_PARAMETER - The open mode is conflict with the attr= ibutes > 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 >+ @retval EFI_NOT_FOUND - Conficts between dir intention and attr= ibute. >+ @retval EFI_WRITE_PROTECTED - Can't open for write if the volume is r= ead only. >+ @retval EFI_ACCESS_DENIED - If the file's attribute is read only, a= nd the > open is for read-write fail it. >- EFI_OUT_OF_RESOURCES - Can not allocate the memory. >+ @retval EFI_OUT_OF_RESOURCES - Can not allocate the memory. > >---*/ >+**/ >+EFI_STATUS >+FatOFileOpen ( >+ IN FAT_OFILE *OFile, >+ OUT FAT_IFILE **NewIFile, >+ IN CHAR16 *FileName, >+ IN UINT64 OpenMode, >+ IN UINT8 Attributes >+ ) > { > FAT_VOLUME *Volume; > EFI_STATUS Status; > CHAR16 NewFileName[EFI_PATH_STRING_LENGTH]; > FAT_DIRENT *DirEnt; >@@ -197,44 +176,39 @@ Returns: > > DEBUG ((EFI_D_INFO, "FSOpen: Open '%S' %r\n", FileName, Status)); > return FatOFileFlush (OFile); > } > >+/** >+ >+ Implements OpenEx() of Simple File System Protocol. >+ >+ @param FHand - File handle of the file serves as a sta= rting 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 create= d. >+ @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 st= ring. >+ @retval EFI_SUCCESS - Open the file successfully. >+ @return Others - The status of open file. >+ >+**/ > EFI_STATUS > EFIAPI > FatOpenEx ( > IN EFI_FILE_PROTOCOL *FHand, > OUT EFI_FILE_PROTOCOL **NewHandle, > IN CHAR16 *FileName, > IN UINT64 OpenMode, > 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 re= ference 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 tran= saction. >- >-Returns: >- >- EFI_INVALID_PARAMETER - The FileName is NULL or the file string is empt= y. >- 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; > FAT_OFILE *OFile; > EFI_STATUS Status; >@@ -317,40 +291,36 @@ Returns: > } > > return Status; > } > >+/** >+ >+ Implements Open() of Simple File System Protocol. >+ >+ >+ @param FHand - File handle of the file serves as a st= arting reference point. >+ @param NewHandle - Handle of the file that is newly opene= d. >+ @param FileName - File name relative to FHand. >+ @param OpenMode - Open mode. >+ @param Attributes - Attributes to set if the file is creat= ed. >+ >+ @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 st= ring. >+ @retval EFI_SUCCESS - Open the file successfully. >+ @return Others - The status of open file. >+ >+**/ > EFI_STATUS > EFIAPI > FatOpen ( > IN EFI_FILE_PROTOCOL *FHand, > OUT EFI_FILE_PROTOCOL **NewHandle, > IN CHAR16 *FileName, > 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 re= ference 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 empt= y. >- 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, NUL= L); > } >diff --git a/FatPkg/EnhancedFatDxe/OpenVolume.c b/FatPkg/EnhancedFatDxe/Op= enVolume.c >index 0f43ffa..4e12db3 100644 >--- a/FatPkg/EnhancedFatDxe/OpenVolume.c >+++ b/FatPkg/EnhancedFatDxe/OpenVolume.c >@@ -1,55 +1,39 @@ >-/*++ >+/** @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 availab= le > under the terms and conditions of the BSD License which accompanies this > distribution. The full text of the license may be found at > 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 IMPL= IED. > >+**/ > >-Module Name: >- >- OpenVolume.c >+#include "Fat.h" > >-Abstract: >+/** > >- OpenVolume() function of Simple File System Protocol >+ Implements Simple File System Protocol interface function OpenVolume(). > >-Revision History >+ @param This - Calling context. >+ @param File - the Root Directory of the volume. > >---*/ >- >-#include "Fat.h" >+ @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; > FAT_IFILE *IFile; > >diff --git a/FatPkg/EnhancedFatDxe/ReadWrite.c b/FatPkg/EnhancedFatDxe/Rea= dWrite.c >index 81676cd..a6e0ec4 100644 >--- a/FatPkg/EnhancedFatDxe/ReadWrite.c >+++ b/FatPkg/EnhancedFatDxe/ReadWrite.c >@@ -1,6 +1,7 @@ >-/*++ >+/** @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 availab= le > under the terms and conditions of the BSD License which accompanies this > distribution. The full text of the license may be found at >@@ -8,48 +9,33 @@ 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 IMPL= IED. > > >-Module Name: >+**/ > >- ReadWrite.c >+#include "Fat.h" > >-Abstract: >+/** > >- Functions that perform file read/write >+ Get the file's position of the file. > >-Revision History > >---*/ >+ @param FHand - The handle of file. >+ @param Position - The file's position of the file. > >-#include "Fat.h" >+ @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; > > IFile =3D IFILE_FROM_FHAND (FHand); >@@ -65,34 +51,28 @@ Returns: > > *Position =3D IFile->Position; > 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 positio= n. >+ >+**/ > 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; > > IFile =3D IFILE_FROM_FHAND (FHand); >@@ -128,34 +108,28 @@ Returns: > // > IFile->Position =3D Position; > 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 di= sk. >+ >+**/ > 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; > FAT_ODIR *ODir; > FAT_DIRENT *DirEnt; >@@ -203,42 +177,36 @@ 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 rea= ding 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, > IN IO_MODE IoMode, > IN OUT UINTN *BufferSize, > 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 tran= saction. >- >-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; > FAT_OFILE *OFile; > FAT_VOLUME *Volume; >@@ -371,163 +339,135 @@ Done: > > FatReleaseLock (); > 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 di= sk. >+ >+**/ > EFI_STATUS > EFIAPI > FatRead ( > IN EFI_FILE_PROTOCOL *FHand, > IN OUT UINTN *BufferSize, > OUT VOID *Buffer > ) >-/*++ >+{ >+ return FatIFileAccess (FHand, ReadData, BufferSize, Buffer, NULL); >+} > >-Routine Description: >+/** > > Get the file info. > >-Arguments: >- >- FHand - The handle of the file. >- BufferSize - Size of Buffer. >- Buffer - Buffer containing read data. >+ @param FHand - The handle of the file. >+ @param 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, BufferSize, Buffer, NULL); >-} >+ @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 di= sk. > >+**/ > EFI_STATUS > EFIAPI > FatReadEx ( > IN EFI_FILE_PROTOCOL *FHand, > IN OUT EFI_FILE_IO_TOKEN *Token > ) >-/*++ >- >-Routine Description: >- >- Get the file info. >- >-Arguments: >+{ >+ return FatIFileAccess (FHand, ReadData, &Token->BufferSize, Token->Buff= er, Token); >+} > >- FHand - The handle of the file. >- Token - A pointer to the token associated with the tran= saction. >+/** > >-Returns: >+ Write the content of buffer into files. > >- 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. >+ @param FHand - The handle of the file. >+ @param BufferSize - Size of Buffer. >+ @param Buffer - Buffer containing write data. > >---*/ >-{ >- return FatIFileAccess (FHand, ReadData, &Token->BufferSize, Token->Buff= er, Token); >-} >+ @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 di= sk. > >+**/ > EFI_STATUS > EFIAPI > FatWrite ( > IN EFI_FILE_PROTOCOL *FHand, > IN OUT UINTN *BufferSize, > IN VOID *Buffer > ) >-/*++ >- >-Routine Description: >- >- Write the content of buffer into files. >+{ >+ return FatIFileAccess (FHand, WriteData, BufferSize, Buffer, NULL); >+} > >-Arguments: >+/** > >- FHand - The handle of the file. >- BufferSize - Size of Buffer. >- Buffer - Buffer containing write data. >+ Get the file info. > >-Returns: >+ @param FHand - The handle of the file. >+ @param Token - A pointer to the token associated with = the transaction. > >- 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); >-} >+ @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 di= sk. > >+**/ > EFI_STATUS > EFIAPI > FatWriteEx ( > IN EFI_FILE_PROTOCOL *FHand, > IN OUT EFI_FILE_IO_TOKEN *Token > ) >-/*++ >- >-Routine Description: >- >- Get the file info. >- >-Arguments: >+{ >+ return FatIFileAccess (FHand, WriteData, &Token->BufferSize, Token->Buf= fer, Token); >+} > >- FHand - The handle of the file. >- Token - A pointer to the token associated with the tran= saction. >+/** > >-Returns: >+ 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. > >- 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. >+ @param OFile - The open file. >+ @param IoMode - Indicate whether the access mode is rea= ding or writing. >+ @param Position - The position where data will be accesse= d. >+ @param DataBufferSize - Size of Buffer. >+ @param UserBuffer - Buffer containing data. >+ @param Task point to task instance. > >---*/ >-{ >- return FatIFileAccess (FHand, WriteData, &Token->BufferSize, Token->Buf= fer, Token); >-} >+ @retval EFI_SUCCESS - Access the data successfully. >+ @return other - An error occurred when operating on the= disk. > >+**/ > EFI_STATUS > FatAccessOFile ( > IN FAT_OFILE *OFile, > IN IO_MODE IoMode, > IN UINTN Position, > IN OUT UINTN *DataBufferSize, > 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; > EFI_STATUS Status; > UINTN BufferSize; >@@ -577,32 +517,26 @@ Returns: > // > *DataBufferSize -=3D BufferSize; > return Status; > } > >-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. >+ @param OFile - The open file. >+ @param ExpandedSize - The number of zero bytes appended at th= e end of the file. > >-Returns: >+ @retval EFI_SUCCESS - The file is expanded successfully. >+ @return other - An error occurred when expanding file. > >- EFI_SUCCESS - The file is expanded successfully. >- other - An error occurred when expanding file. >- >---*/ >+**/ >+EFI_STATUS >+FatExpandOFile ( >+ IN FAT_OFILE *OFile, >+ IN UINT64 ExpandedSize >+ ) > { > EFI_STATUS Status; > UINTN WritePos; > > WritePos =3D OFile->FileSize; >@@ -612,33 +546,27 @@ Returns: > } > > return Status; > } > >-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: >+ @param OFile - The open file to write zero pool. >+ @param WritePos - The number of zero bytes written. > >- 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. >+ @retval EFI_SUCCESS - Write the zero pool successfully. >+ @retval EFI_OUT_OF_RESOURCES - Not enough memory to perform the operat= ion. >+ @return other - An error occurred when writing disk. > >---*/ >+**/ >+EFI_STATUS >+FatWriteZeroPool ( >+ IN FAT_OFILE *OFile, >+ IN UINTN WritePos >+ ) > { > EFI_STATUS Status; > VOID *ZeroBuffer; > UINTN AppendedSize; > UINTN BufferSize; >@@ -674,31 +602,25 @@ Returns: > > FreePool (ZeroBuffer); > return Status; > } > >-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. >+ @param OFile - The open file. >+ @param TruncatedSize - The new file size. > >-Returns: >+ @retval EFI_SUCCESS - The file is truncated successfully. >+ @return other - An error occurred when truncating file. > >- EFI_SUCCESS - The file is truncated successfully. >- other - An error occurred when truncating file. >- >---*/ >+**/ >+EFI_STATUS >+FatTruncateOFile ( >+ IN FAT_OFILE *OFile, >+ IN UINTN TruncatedSize >+ ) > { > OFile->FileSize =3D TruncatedSize; > return FatShrinkEof (OFile); > } >diff --git a/FatPkg/EnhancedFatDxe/UnicodeCollation.c b/FatPkg/EnhancedFat= Dxe/UnicodeCollation.c >index 61b9aab..b240a93 100644 >--- a/FatPkg/EnhancedFatDxe/UnicodeCollation.c >+++ b/FatPkg/EnhancedFatDxe/UnicodeCollation.c >@@ -187,13 +187,12 @@ 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 > FatStrUpr ( > IN OUT CHAR16 *String >@@ -207,13 +206,12 @@ 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 > FatStrLwr ( > IN OUT CHAR16 *String >-- >1.9.5.msysgit.1