[patch 7/8] FatPkg\EnhancedFatDxe: Add comments for functions

[Dandan Bi <dandan.bi@intel.com>]

Cc: Ruiyu Ni <ruiyu.ni@intel.com>
Contributed-under: TianoCore Contribution Agreement 1.0
Signed-off-by: Dandan Bi <dandan.bi@intel.com>
---
 FatPkg/EnhancedFatDxe/Fat.c  |  64 ++++
 FatPkg/EnhancedFatDxe/Fat.h  | 804 +++++++++++++++++++++++++++++++++++++++++++
 FatPkg/EnhancedFatDxe/Info.c |  40 +++
 3 files changed, 908 insertions(+)

diff --git a/FatPkg/EnhancedFatDxe/Fat.c b/FatPkg/EnhancedFatDxe/Fat.c
index 2e6c089..e29c64c 100644
--- a/FatPkg/EnhancedFatDxe/Fat.c
+++ b/FatPkg/EnhancedFatDxe/Fat.c
@@ -12,39 +12,103 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
 
 **/
 
 #include "Fat.h"
 
+/**
+
+  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
   );
 
+/**
+
+  Unload function for this image. Uninstall DriverBinding protocol.
+
+  @param ImageHandle           - Handle for the image of this driver.
+
+  @retval EFI_SUCCESS           - Driver unloaded successfully.
+  @return other                 - Driver can not unloaded.
+
+**/
 EFI_STATUS
 EFIAPI
 FatUnload (
   IN EFI_HANDLE         ImageHandle
   );
 
+/**
+
+  Test to see if this driver can add a file system to ControllerHandle.
+  ControllerHandle must support both Disk IO and Block IO protocols.
+
+  @param  This                  - Protocol instance pointer.
+  @param  ControllerHandle      - Handle of device to test.
+  @param  RemainingDevicePath   - Not used.
+
+  @retval EFI_SUCCESS           - This driver supports this device.
+  @retval EFI_ALREADY_STARTED   - This driver is already running on this device.
+  @return other                 - This driver does not support this device.
+
+**/
 EFI_STATUS
 EFIAPI
 FatDriverBindingSupported (
   IN EFI_DRIVER_BINDING_PROTOCOL  *This,
   IN EFI_HANDLE                   Controller,
   IN EFI_DEVICE_PATH_PROTOCOL     *RemainingDevicePath
   );
 
+/**
+
+  Start this driver on ControllerHandle by opening a Block IO and Disk IO
+  protocol, reading Device Path. Add a Simple File System protocol to
+  ControllerHandle if the media contains a valid file system.
+
+  @param  This                  - Protocol instance pointer.
+  @param  ControllerHandle      - Handle of device to bind driver to.
+  @param  RemainingDevicePath   - Not used.
+
+  @retval EFI_SUCCESS           - This driver is added to DeviceHandle.
+  @retval EFI_ALREADY_STARTED   - This driver is already running on DeviceHandle.
+  @retval EFI_OUT_OF_RESOURCES  - Can not allocate the memory.
+  @return other                 - This driver does not support this device.
+
+**/
 EFI_STATUS
 EFIAPI
 FatDriverBindingStart (
   IN EFI_DRIVER_BINDING_PROTOCOL  *This,
   IN EFI_HANDLE                   Controller,
   IN EFI_DEVICE_PATH_PROTOCOL     *RemainingDevicePath
   );
 
+/**
+
+  Stop this driver on ControllerHandle.
+
+  @param  This                  - Protocol instance pointer.
+  @param  ControllerHandle      - Handle of device to stop driver on.
+  @param  NumberOfChildren      - Not used.
+  @param  ChildHandleBuffer     - Not used.
+
+  @retval EFI_SUCCESS           - This driver is removed DeviceHandle.
+  @return other                 - This driver was not removed from this device.
+
+**/
 EFI_STATUS
 EFIAPI
 FatDriverBindingStop (
   IN  EFI_DRIVER_BINDING_PROTOCOL  *This,
   IN  EFI_HANDLE                   Controller,
diff --git a/FatPkg/EnhancedFatDxe/Fat.h b/FatPkg/EnhancedFatDxe/Fat.h
index 9490868..8355261 100644
--- a/FatPkg/EnhancedFatDxe/Fat.h
+++ b/FatPkg/EnhancedFatDxe/Fat.h
@@ -700,15 +700,54 @@ FatWriteEx (
 ;
 
 //
 // DiskCache.c
 //
+/**
+
+  Initialize the disk cache according to Volume's FatType.
+
+  @param  Volume                - FAT file system volume.
+
+  @retval EFI_SUCCESS           - The disk cache is successfully initialized.
+  @retval EFI_OUT_OF_RESOURCES  - Not enough memory to allocate disk cache.
+
+**/
 EFI_STATUS
 FatInitializeDiskCache (
   IN FAT_VOLUME              *Volume
   );
 
+/**
+
+  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 divided into
+  the access of FAT cache (CACHE_FAT) and the access of Data cache (CACHE_DATA):
+
+  1. Access of FAT cache (CACHE_FAT): Access the data in the FAT cache, if there is cache
+     page hit, just return the cache page; else update the related cache page and return
+     the right cache page.
+  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 cache,
+     but the Aligned data will be accessed with disk directly.
+
+  @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.
+
+  @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_STATUS
 FatAccessCache (
   IN     FAT_VOLUME          *Volume,
   IN     CACHE_DATA_TYPE     CacheDataType,
   IN     IO_MODE             IoMode,
@@ -716,40 +755,107 @@ FatAccessCache (
   IN     UINTN               BufferSize,
   IN OUT UINT8               *Buffer,
   IN     FAT_TASK            *Task
   );
 
+/**
+
+  Flush all the dirty cache back, include the FAT cache and the Data cache.
+
+  @param  Volume                - FAT file system volume.
+  @param  Task                    point to task instance.
+
+  @retval EFI_SUCCESS           - Flush all the dirty cache back successfully
+  @return other                 - An error occurred when writing the data into the disk
+
+**/
 EFI_STATUS
 FatVolumeFlushCache (
   IN FAT_VOLUME              *Volume,
   IN FAT_TASK                *Task
   );
 
 //
 // Flush.c
 //
+/**
+
+  Flush the data associated with an open file.
+  In this implementation, only last Mod/Access time is updated.
+
+  @param  OFile                 - The open file.
+
+  @retval EFI_SUCCESS           - The OFile is flushed successfully.
+  @return Others                - An error occurred when flushing this OFile.
+
+**/
 EFI_STATUS
 FatOFileFlush (
   IN FAT_OFILE          *OFile
   );
 
+/**
+
+  Check the references of the OFile.
+  If the OFile (that is checked) is no longer
+  referenced, then it is freed.
+
+  @param  OFile                 - The OFile to be checked.
+
+  @retval TRUE                  - The OFile is not referenced and freed.
+  @retval FALSE                 - The OFile is kept.
+
+**/
 BOOLEAN
 FatCheckOFileRef (
   IN FAT_OFILE          *OFile
   );
 
+/**
+
+  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
   );
 
+/**
+
+  Close the open file instance.
+
+  @param  IFile                 - Open file instance.
+
+  @retval EFI_SUCCESS           - Closed the file successfully.
+
+**/
 EFI_STATUS
 FatIFileClose (
   FAT_IFILE             *IFile
   );
 
+/**
+
+  Set error status for a specific OFile, reference checking the volume.
+  If volume is already marked as invalid, and all resources are freed
+  after reference checking, the file system protocol is uninstalled and
+  the volume structure is freed.
+
+  @param  Volume                - the Volume that is to be reference checked and unlocked.
+  @param  OFile                 - the OFile whose permanent error code is to be set.
+  @param  EfiStatus             - error code to be set.
+  @param  Task                    point to task instance.
+
+  @retval EFI_SUCCESS           - Clean up the volume successfully.
+  @return Others                - Cleaning up of the volume is failed.
+
+**/
 EFI_STATUS
 FatCleanupVolume (
   IN FAT_VOLUME         *Volume,
   IN FAT_OFILE          *OFile,
   IN EFI_STATUS         EfiStatus,
@@ -757,443 +863,1141 @@ FatCleanupVolume (
   );
 
 //
 // FileSpace.c
 //
+/**
+
+  Shrink the end of the open file base on the file size.
+
+  @param  OFile                 - The open file.
+
+  @retval EFI_SUCCESS           - Shrinked sucessfully.
+  @retval EFI_VOLUME_CORRUPTED  - There are errors in the file's clusters.
+
+**/
 EFI_STATUS
 FatShrinkEof (
   IN FAT_OFILE          *OFile
   );
 
+/**
+
+  Grow the end of the open file base on the NewSizeInBytes.
+
+  @param  OFile                 - The open file.
+  @param  NewSizeInBytes        - The new size in bytes of the open file.
+
+  @retval EFI_SUCCESS           - The file is grown sucessfully.
+  @retval EFI_UNSUPPORTED       - The file size is larger than 4GB.
+  @retval EFI_VOLUME_CORRUPTED  - There are errors in the files' clusters.
+  @retval EFI_VOLUME_FULL       - The volume is full and can not grow the file.
+
+**/
 EFI_STATUS
 FatGrowEof (
   IN FAT_OFILE          *OFile,
   IN UINT64             NewSizeInBytes
   );
 
+/**
+
+  Get the size of directory of the open file.
+
+  @param  Volume                - The File System Volume.
+  @param  Cluster               - The Starting cluster.
+
+  @return The physical size of the file starting at the input cluster, if there is error in the
+  cluster chain, the return value is 0.
+
+**/
 UINTN
 FatPhysicalDirSize (
   IN FAT_VOLUME         *Volume,
   IN UINTN              Cluster
   );
 
+/**
+
+  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
   );
 
+/**
+
+  Seek OFile to requested position, and calculate the number of
+  consecutive clusters from the position in the file
+
+  @param  OFile                 - The open file.
+  @param  Position              - The file's position which will be accessed.
+  @param  PosLimit              - The maximum length current reading/writing may access
+
+  @retval EFI_SUCCESS           - Set the info successfully.
+  @retval EFI_VOLUME_CORRUPTED  - Cluster chain corrupt.
+
+**/
 EFI_STATUS
 FatOFilePosition (
   IN FAT_OFILE            *OFile,
   IN UINTN                Position,
   IN UINTN                PosLimit
   );
 
+/**
+
+  Update the free cluster info of FatInfoSector of the volume.
+
+  @param  Volume                - FAT file system volume.
+
+**/
 VOID
 FatComputeFreeInfo (
   IN FAT_VOLUME         *Volume
   );
 
 //
 // Init.c
 //
+/**
+
+  Allocates volume structure, detects FAT file system, installs protocol,
+  and initialize cache.
+
+  @param  Handle                - The handle of parent device.
+  @param  DiskIo                - The DiskIo of parent device.
+  @param  DiskIo2               - The DiskIo2 of parent device.
+  @param  BlockIo               - The BlockIo of parent devicel
+
+  @retval EFI_SUCCESS           - Allocate a new volume successfully.
+  @retval EFI_OUT_OF_RESOURCES  - Can not allocate the memory.
+  @return Others                - Allocating a new volume failed.
+
+**/
 EFI_STATUS
 FatAllocateVolume (
   IN  EFI_HANDLE                     Handle,
   IN  EFI_DISK_IO_PROTOCOL           *DiskIo,
   IN  EFI_DISK_IO2_PROTOCOL          *DiskIo2,
   IN  EFI_BLOCK_IO_PROTOCOL          *BlockIo
   );
 
+/**
+
+  Detects FAT file system on Disk and set relevant fields of Volume.
+
+  @param Volume                - The volume structure.
+
+  @retval EFI_SUCCESS           - The Fat File System is detected successfully
+  @retval EFI_UNSUPPORTED       - The volume is not FAT file system.
+  @retval EFI_VOLUME_CORRUPTED  - The volume is corrupted.
+
+**/
 EFI_STATUS
 FatOpenDevice (
   IN OUT FAT_VOLUME     *Volume
   );
 
+/**
+
+  Called by FatDriverBindingStop(), Abandon the volume.
+
+  @param  Volume                - The volume to be abandoned.
+
+  @retval EFI_SUCCESS           - Abandoned the volume successfully.
+  @return Others                - Can not uninstall the protocol interfaces.
+
+**/
 EFI_STATUS
 FatAbandonVolume (
   IN FAT_VOLUME         *Volume
   );
 
 //
 // Misc.c
 //
+/**
+
+  Create the task
+
+  @param  IFile                 - The instance of the open file.
+  @param  Token                 - A pointer to the token associated with the transaction.
+
+  @return FAT_TASK *            - Return the task instance.
+
+**/
 FAT_TASK *
 FatCreateTask (
   FAT_IFILE           *IFile,
   EFI_FILE_IO_TOKEN   *Token
   );
 
+/**
+
+  Destroy the task.
+
+  @param  Task                  - The task to be destroyed.
+
+**/
 VOID
 FatDestroyTask (
   FAT_TASK            *Task
   );
 
+/**
+
+  Wait all non-blocking requests complete.
+
+  @param  IFile                 - The instance of the open file.
+
+**/
 VOID
 FatWaitNonblockingTask (
   FAT_IFILE           *IFile
   );
 
+/**
+
+  Remove the subtask from subtask list.
+
+  @param  Subtask               - The subtask to be removed.
+
+  @return LIST_ENTRY *          - The next node in the list.
+
+**/
 LIST_ENTRY *
 FatDestroySubtask (
   FAT_SUBTASK         *Subtask
   );
 
+/**
+
+  Execute the task.
+
+  @param  IFile                 - The instance of the open file.
+  @param  Task                  - The task to be executed.
+
+  @retval EFI_SUCCESS           - The task was executed sucessfully.
+  @return other                 - An error occurred when executing the task.
+
+**/
 EFI_STATUS
 FatQueueTask (
   IN FAT_IFILE        *IFile,
   IN FAT_TASK         *Task
   );
 
+/**
+
+  Set the volume as dirty or not.
+
+  @param  Volume                - FAT file system volume.
+  @param  IoMode                - The access mode.
+  @param  DirtyValue            - Set the volume as dirty or not.
+
+  @retval EFI_SUCCESS           - Set the new FAT entry value sucessfully.
+  @return other                 - An error occurred when operation the FAT entries.
+
+**/
 EFI_STATUS
 FatAccessVolumeDirty (
   IN FAT_VOLUME         *Volume,
   IN IO_MODE            IoMode,
   IN VOID               *DirtyValue
   );
 
+/**
+
+  General disk access function.
+
+  @param  Volume                - FAT file system volume.
+  @param  IoMode                - The access mode (disk read/write or cache access).
+  @param  Offset                - The starting byte offset to read from.
+  @param  BufferSize            - Size of Buffer.
+  @param  Buffer                - Buffer containing read data.
+  @param  Task                    point to task instance.
+
+  @retval EFI_SUCCESS           - The operation is performed successfully.
+  @retval EFI_VOLUME_CORRUPTED  - The accesss is
+  @return Others                - The status of read/write the disk
+
+**/
 EFI_STATUS
 FatDiskIo (
   IN FAT_VOLUME         *Volume,
   IN IO_MODE            IoMode,
   IN UINT64             Offset,
   IN UINTN              BufferSize,
   IN OUT VOID           *Buffer,
   IN FAT_TASK           *Task
   );
 
+/**
+
+  Lock the volume.
+
+**/
 VOID
 FatAcquireLock (
   VOID
   );
 
+/**
+
+  Unlock the volume.
+
+**/
 VOID
 FatReleaseLock (
   VOID
   );
 
+/**
+
+  Lock the volume.
+  If the lock is already in the acquired state, then EFI_ACCESS_DENIED is returned.
+  Otherwise, EFI_SUCCESS is returned.
+
+  @retval EFI_SUCCESS           - The volume is locked.
+  @retval EFI_ACCESS_DENIED     - The volume could not be locked because it is already locked.
+
+**/
 EFI_STATUS
 FatAcquireLockOrFail (
   VOID
   );
 
+/**
+
+  Free directory entry.
+
+  @param  DirEnt                - The directory entry to be freed.
+
+**/
 VOID
 FatFreeDirEnt (
   IN FAT_DIRENT         *DirEnt
   );
 
+/**
+
+  Free volume structure (including the contents of directory cache and disk cache).
+
+  @param  Volume                - The volume structure to be freed.
+
+**/
 VOID
 FatFreeVolume (
   IN FAT_VOLUME         *Volume
   );
 
+/**
+
+  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
   );
 
+/**
+
+  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
   );
 
+/**
+
+  Get Current FAT time.
+
+  @param  FatTime               - Current FAT time.
+
+**/
 VOID
 FatGetCurrentFatTime (
   OUT FAT_DATE_TIME     *FatTime
   );
 
+/**
+
+  Check whether a time is valid.
+
+  @param  Time                  - The time of EFI_TIME.
+
+  @retval TRUE                  - The time is valid.
+  @retval FALSE                 - The time is not valid.
+
+**/
 BOOLEAN
 FatIsValidTime (
   IN EFI_TIME           *Time
   );
 
 //
 // UnicodeCollation.c
 //
+/**
+  Initialize Unicode Collation support.
+
+  It tries to locate Unicode Collation 2 protocol and matches it with current
+  platform language code. If for any reason the first attempt fails, it then tries to
+  use Unicode Collation Protocol.
+
+  @param  AgentHandle          The handle used to open Unicode Collation (2) protocol.
+
+  @retval EFI_SUCCESS          The Unicode Collation (2) protocol has been successfully located.
+  @retval Others               The Unicode Collation (2) protocol has not been located.
+
+**/
 EFI_STATUS
 InitializeUnicodeCollationSupport (
   IN EFI_HANDLE    AgentHandle
   );
 
+/**
+  Convert FAT string to unicode string.
+
+  @param  FatSize               The size of FAT string.
+  @param  Fat                   The FAT string.
+  @param  String                The unicode string.
+
+  @return None.
+
+**/
 VOID
 FatFatToStr (
   IN UINTN              FatSize,
   IN CHAR8              *Fat,
   OUT CHAR16            *String
   );
 
+/**
+  Convert unicode string to Fat string.
+
+  @param  String                The unicode string.
+  @param  FatSize               The size of the FAT string.
+  @param  Fat                   The FAT string.
+
+  @retval TRUE                  Convert successfully.
+  @retval FALSE                 Convert error.
+
+**/
 BOOLEAN
 FatStrToFat (
   IN  CHAR16            *String,
   IN  UINTN             FatSize,
   OUT CHAR8             *Fat
   );
 
+/**
+  Lowercase a string
+
+  @param  Str                   The string which will be lower-cased.
+
+**/
 VOID
 FatStrLwr (
   IN CHAR16             *Str
   );
 
+/**
+  Uppercase a string.
+
+  @param  Str                   The string which will be upper-cased.
+
+**/
 VOID
 FatStrUpr (
   IN CHAR16             *Str
   );
 
+/**
+  Performs a case-insensitive comparison of two Null-terminated Unicode strings.
+
+  @param  Str1                   A pointer to a Null-terminated Unicode string.
+  @param  Str2                   A pointer to a Null-terminated Unicode string.
+
+  @retval 0                    S1 is equivalent to S2.
+  @retval >0                   S1 is lexically greater than S2.
+  @retval <0                   S1 is lexically less than S2.
+**/
 INTN
 FatStriCmp (
   IN CHAR16             *Str1,
   IN CHAR16             *Str2
   );
 
 //
 // Open.c
 //
+
+/**
+
+  Open a file for a file name relative to an existing OFile.
+  The IFile of the newly opened file is passed out.
+
+  @param  OFile                 - The file that serves as a starting reference point.
+  @param  NewIFile              - The newly generated IFile instance.
+  @param  FileName              - The file name relative to the OFile.
+  @param  OpenMode              - Open mode.
+  @param  Attributes            - Attributes to set if the file is created.
+
+
+  @retval EFI_SUCCESS           - Open the file successfully.
+  @retval EFI_INVALID_PARAMETER - The open mode is conflict with the attributes
+                          or the file name is not valid.
+  @retval EFI_NOT_FOUND         - Conficts between dir intention and attribute.
+  @retval EFI_WRITE_PROTECTED   - Can't open for write if the volume is read only.
+  @retval EFI_ACCESS_DENIED     - If the file's attribute is read only, and the
+                          open is for read-write fail it.
+  @retval EFI_OUT_OF_RESOURCES  - Can not allocate the memory.
+
+**/
 EFI_STATUS
 FatOFileOpen (
   IN FAT_OFILE          *OFile,
   OUT FAT_IFILE         **NewIFile,
   IN CHAR16             *FileName,
   IN UINT64             OpenMode,
   IN UINT8              Attributes
   );
 
+/**
+
+  Create an Open instance for the existing OFile.
+  The IFile of the newly opened file is passed out.
+
+  @param  OFile                 - The file that serves as a starting reference point.
+  @param  PtrIFile              - The newly generated IFile instance.
+
+  @retval EFI_OUT_OF_RESOURCES  - Can not allocate the memory for the IFile
+  @retval EFI_SUCCESS           - Create the new IFile for the OFile successfully
+
+**/
 EFI_STATUS
 FatAllocateIFile (
   IN FAT_OFILE          *OFile,
   OUT FAT_IFILE         **PtrIFile
   );
 
 //
 // OpenVolume.c
 //
+/**
+
+  Implements Simple File System Protocol interface function OpenVolume().
+
+  @param  This                  - Calling context.
+  @param  File                  - the Root Directory of the volume.
+
+  @retval EFI_OUT_OF_RESOURCES  - Can not allocate the memory.
+  @retval EFI_VOLUME_CORRUPTED  - The FAT type is error.
+  @retval EFI_SUCCESS           - Open the volume successfully.
+
+**/
 EFI_STATUS
 EFIAPI
 FatOpenVolume (
   IN  EFI_SIMPLE_FILE_SYSTEM_PROTOCOL *This,
   OUT EFI_FILE_PROTOCOL               **File
   );
 
 //
 // ReadWrite.c
 //
+/**
+
+  This function reads data from a file or writes data to a file.
+  It uses OFile->PosRem to determine how much data can be accessed in one time.
+
+  @param  OFile                 - The open file.
+  @param  IoMode                - Indicate whether the access mode is reading or writing.
+  @param  Position              - The position where data will be accessed.
+  @param  DataBufferSize        - Size of Buffer.
+  @param  UserBuffer            - Buffer containing data.
+  @param  Task                    point to task instance.
+
+  @retval EFI_SUCCESS           - Access the data successfully.
+  @return other                 - An error occurred when operating on the disk.
+
+**/
 EFI_STATUS
 FatAccessOFile (
   IN FAT_OFILE          *OFile,
   IN IO_MODE            IoMode,
   IN UINTN              Position,
   IN UINTN              *DataBufferSize,
   IN UINT8              *UserBuffer,
   IN FAT_TASK           *Task
   );
 
+/**
+
+  Expand OFile by appending zero bytes at the end of OFile.
+
+  @param  OFile                 - The open file.
+  @param  ExpandedSize          - The number of zero bytes appended at the end of the file.
+
+  @retval EFI_SUCCESS           - The file is expanded successfully.
+  @return other                 - An error occurred when expanding file.
+
+**/
 EFI_STATUS
 FatExpandOFile (
   IN FAT_OFILE          *OFile,
   IN UINT64             ExpandedSize
   );
 
+/**
+
+  Write zero pool from the WritePos to the end of OFile.
+
+  @param  OFile                 - The open file to write zero pool.
+  @param  WritePos              - The number of zero bytes written.
+
+  @retval EFI_SUCCESS           - Write the zero pool successfully.
+  @retval EFI_OUT_OF_RESOURCES  - Not enough memory to perform the operation.
+  @return other                 - An error occurred when writing disk.
+
+**/
 EFI_STATUS
 FatWriteZeroPool (
   IN FAT_OFILE          *OFile,
   IN UINTN              WritePos
   );
 
+/**
+
+  Truncate the OFile to smaller file size.
+
+  @param  OFile                 - The open file.
+  @param  TruncatedSize         - The new file size.
+
+  @retval EFI_SUCCESS           - The file is truncated successfully.
+  @return other                 - An error occurred when truncating file.
+
+**/
 EFI_STATUS
 FatTruncateOFile (
   IN FAT_OFILE          *OFile,
   IN UINTN              TruncatedSize
   );
 
 //
 // DirectoryManage.c
 //
+/**
+
+  Set the OFile's current directory cursor to the list head.
+
+  @param OFile                 - The directory OFile whose directory cursor is reset.
+
+**/
 VOID
 FatResetODirCursor (
   IN FAT_OFILE          *OFile
   );
 
+/**
+
+  Set the directory's cursor to the next and get the next directory entry.
+
+  @param  OFile                 - The parent OFile.
+  @param PtrDirEnt             - The next directory entry.
+
+  @retval EFI_SUCCESS           - We get the next directory entry successfully.
+  @return other                 - An error occurred when get next directory entry.
+
+**/
 EFI_STATUS
 FatGetNextDirEnt (
   IN  FAT_OFILE         *OFile,
   OUT FAT_DIRENT        **PtrDirEnt
   );
 
+/**
+
+  Remove this directory entry node from the list of directory entries and hash table.
+
+  @param  OFile                - The parent OFile.
+  @param  DirEnt               - The directory entry to be removed.
+
+  @retval EFI_SUCCESS          - The directory entry is successfully removed.
+  @return other                - An error occurred when removing the directory entry.
+
+**/
 EFI_STATUS
 FatRemoveDirEnt (
   IN FAT_OFILE          *OFile,
   IN FAT_DIRENT         *DirEnt
   );
 
+/**
+
+  Save the directory entry to disk.
+
+  @param  OFile                 - The parent OFile which needs to update.
+  @param  DirEnt                - The directory entry to be saved.
+
+  @retval EFI_SUCCESS           - Store the directory entry successfully.
+  @return other                 - An error occurred when writing the directory entry.
+
+**/
 EFI_STATUS
 FatStoreDirEnt (
   IN FAT_OFILE          *OFile,
   IN FAT_DIRENT         *DirEnt
   );
 
+/**
+
+  Create a directory entry in the parent OFile.
+
+  @param  OFile                 - The parent OFile.
+  @param  FileName              - The filename of the newly-created directory entry.
+  @param  Attributes            - The attribute of the newly-created directory entry.
+  @param  PtrDirEnt             - The pointer to the newly-created directory entry.
+
+  @retval EFI_SUCCESS           - The directory entry is successfully created.
+  @retval EFI_OUT_OF_RESOURCES  - Not enough memory to create the directory entry.
+  @return other                 - An error occurred when creating the directory entry.
+
+**/
 EFI_STATUS
 FatCreateDirEnt (
   IN  FAT_OFILE         *OFile,
   IN  CHAR16            *FileName,
   IN  UINT8             Attributes,
   OUT FAT_DIRENT        **PtrDirEnt
   );
 
+/**
+
+  Determine whether the directory entry is "." or ".." entry.
+
+  @param  DirEnt               - The corresponding directory entry.
+
+  @retval TRUE                 - The directory entry is "." or ".." directory entry
+  @retval FALSE                - The directory entry is not "." or ".." directory entry
+
+**/
 BOOLEAN
 FatIsDotDirEnt (
   IN FAT_DIRENT         *DirEnt
   );
 
+/**
+
+  Set the OFile's cluster and size info in its directory entry.
+
+  @param  OFile                 - The corresponding OFile.
+
+**/
 VOID
 FatUpdateDirEntClusterSizeInfo (
   IN FAT_OFILE          *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
   );
 
+/**
+
+  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
   );
 
+/**
+
+  Open the directory entry to get the OFile.
+
+  @param  Parent                - The parent OFile.
+  @param  DirEnt                - The directory entry to be opened.
+
+  @retval EFI_SUCCESS           - The directory entry is successfully opened.
+  @retval EFI_OUT_OF_RESOURCES  - not enough memory to allocate a new OFile.
+  @return other                 - An error occurred when opening the directory entry.
+
+**/
 EFI_STATUS
 FatOpenDirEnt (
   IN FAT_OFILE          *OFile,
   IN FAT_DIRENT         *DirEnt
   );
 
+/**
+
+  Create "." and ".." directory entries in the newly-created parent OFile.
+
+  @param  OFile                 - The parent OFile.
+
+  @retval EFI_SUCCESS           - The dot directory entries are successfully created.
+  @return other                 - An error occurred when creating the directory entry.
+
+**/
 EFI_STATUS
 FatCreateDotDirEnts (
   IN FAT_OFILE          *OFile
   );
 
+/**
+
+  Close the directory entry and free the OFile.
+
+  @param  DirEnt               - The directory entry to be closed.
+
+**/
 VOID
 FatCloseDirEnt (
   IN FAT_DIRENT         *DirEnt
   );
 
+/**
+
+  Traverse filename and open all OFiles that can be opened.
+  Update filename pointer to the component that can't be opened.
+  If more than one name component remains, returns an error;
+  otherwise, return the remaining name component so that the caller might choose to create it.
+
+  @param  PtrOFile              - As input, the reference OFile; as output, the located OFile.
+  @param  FileName              - The file name relevant to the OFile.
+  @param  Attributes            - The attribute of the destination OFile.
+  @param  NewFileName           - The remaining file name.
+
+  @retval EFI_NOT_FOUND         - The file name can't be opened and there is more than one
+                          components within the name left (this means the name can
+                          not be created either).
+  @retval EFI_INVALID_PARAMETER - The parameter is not valid.
+  @retval EFI_SUCCESS           - Open the file successfully.
+  @return other                 - An error occured when locating the OFile.
+
+**/
 EFI_STATUS
 FatLocateOFile (
   IN OUT FAT_OFILE      **PtrOFile,
   IN     CHAR16         *FileName,
   IN     UINT8          Attributes,
      OUT CHAR16         *NewFileName
   );
 
+/**
+
+  Get the directory entry for the volume.
+
+  @param  Volume                - FAT file system volume.
+  @param  Name                  - The file name of the volume.
+
+  @retval EFI_SUCCESS           - Update the volume with the directory entry sucessfully.
+  @return others                - An error occurred when getting volume label.
+
+**/
 EFI_STATUS
 FatGetVolumeEntry (
   IN FAT_VOLUME         *Volume,
   IN CHAR16             *Name
   );
 
+/**
+
+  Set the relevant directory entry into disk for the volume.
+
+  @param  Volume              - FAT file system volume.
+  @param  Name                - The new file name of the volume.
+
+  @retval EFI_SUCCESS         - Update the Volume sucessfully.
+  @retval EFI_UNSUPPORTED     - The input label is not a valid volume label.
+  @return other               - An error occurred when setting volume label.
+
+**/
 EFI_STATUS
 FatSetVolumeEntry (
   IN FAT_VOLUME         *Volume,
   IN CHAR16             *Name
   );
 
 //
 // Hash.c
 //
+/**
+
+  Search the long name hash table for the directory entry.
+
+  @param  ODir                  - The directory to be searched.
+  @param  LongNameString        - The long name string to search.
+
+  @return The previous long name hash node of the directory entry.
+
+**/
 FAT_DIRENT **
 FatLongNameHashSearch (
   IN FAT_ODIR           *ODir,
   IN CHAR16             *LongNameString
   );
 
+/**
+
+  Search the short name hash table for the directory entry.
+
+  @param  ODir                  - The directory to be searched.
+  @param  ShortNameString       - The short name string to search.
+
+  @return The previous short name hash node of the directory entry.
+
+**/
 FAT_DIRENT **
 FatShortNameHashSearch (
   IN FAT_ODIR           *ODir,
   IN CHAR8              *ShortNameString
   );
 
+/**
+
+  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
   );
 
+/**
+
+  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
   );
 
 //
 // FileName.c
 //
+/**
+
+  This function checks whether the input FileName is a valid 8.3 short name.
+  If the input FileName is a valid 8.3, the output is the 8.3 short name;
+  otherwise, the output is the base tag of 8.3 short name.
+
+  @param  FileName              - The input unicode filename.
+  @param  File8Dot3Name         - The output ascii 8.3 short name or base tag of 8.3 short name.
+
+  @retval TRUE                  - The input unicode filename is a valid 8.3 short name.
+  @retval FALSE                 - The input unicode filename is not a valid 8.3 short name.
+
+**/
 BOOLEAN
 FatCheckIs8Dot3Name (
   IN CHAR16             *FileName,
   OUT CHAR8             *File8Dot3Name
   );
 
+/**
+
+  This function generates 8Dot3 name from user specified name for a newly created file.
+
+  @param  Parent                - The parent directory.
+  @param  DirEnt                - The directory entry whose 8Dot3Name needs to be generated.
+
+**/
 VOID
 FatCreate8Dot3Name (
   IN FAT_OFILE          *Parent,
   IN FAT_DIRENT         *DirEnt
   );
 
+/**
+
+  Convert the ascii fat name to the unicode string and strip trailing spaces,
+  and if necessary, convert the unicode string to lower case.
+
+  @param  FatName               - The Char8 string needs to be converted.
+  @param  Len                   - The length of the fat name.
+  @param  LowerCase             - Indicate whether to convert the string to lower case.
+  @param  Str                   - The result of the convertion.
+
+**/
 VOID
 FatNameToStr (
   IN CHAR8              *FatName,
   IN UINTN              Len,
   IN UINTN              LowerCase,
   IN CHAR16             *Str
   );
 
+/**
+
+  Set the caseflag value for the directory entry.
+
+  @param DirEnt                - The logical directory entry whose caseflag value is to be set.
+
+**/
 VOID
 FatSetCaseFlag (
   IN FAT_DIRENT         *DirEnt
   );
 
+/**
+
+  Convert the 8.3 ASCII fat name to cased Unicode string according to case flag.
+
+  @param  DirEnt                - The corresponding directory entry.
+  @param  FileString            - The output Unicode file name.
+  @param  FileStringMax           The max length of FileString.
+
+**/
 VOID
 FatGetFileNameViaCaseFlag (
   IN     FAT_DIRENT     *DirEnt,
   IN OUT CHAR16         *FileString,
   IN     UINTN          FileStringMax
   );
 
+/**
+
+  Get the Check sum for a short name.
+
+  @param  ShortNameString       - The short name for a file.
+
+  @retval Sum                   - UINT8 checksum.
+
+**/
 UINT8
 FatCheckSum (
   IN CHAR8              *ShortNameString
   );
 
+/**
+
+  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)
+
+  @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
   );
 
+/**
+
+  Check whether the IFileName is valid long file name. If the IFileName is a valid
+  long file name, then we trim the possible leading blanks and leading/trailing dots.
+  the trimmed filename is stored in OutputFileName
+
+  @param  InputFileName         - The input file name.
+  @param  OutputFileName        - The output file name.
+
+  @retval TRUE                  - The InputFileName is a valid long file name.
+  @retval FALSE                 - The InputFileName is not a valid long file name.
+
+**/
 BOOLEAN
 FatFileNameIsValid (
   IN  CHAR16  *InputFileName,
   OUT CHAR16  *OutputFileName
   );
 
 //
 // DirectoryCache.c
 //
+/**
+
+  Discard the directory structure when an OFile will be freed.
+  Volume will cache this directory if the OFile does not represent a deleted file.
+
+  @param  OFile                 - The OFile whose directory structure is to be discarded.
+
+**/
 VOID
 FatDiscardODir (
   IN FAT_OFILE    *OFile
   );
 
+/**
+
+  Request the directory structure when an OFile is newly generated.
+  If the directory structure is cached by volume, then just return this directory;
+  Otherwise, allocate a new one for OFile.
+
+  @param  OFile                 - The OFile which requests directory structure.
+
+**/
 VOID
 FatRequestODir (
   IN FAT_OFILE    *OFile
   );
 
+/**
+
+  Clean up all the cached directory structures when the volume is going to be abandoned.
+
+  @param  Volume                - FAT file system volume.
+
+**/
 VOID
 FatCleanupODirCache (
   IN FAT_VOLUME   *Volume
   );
 
diff --git a/FatPkg/EnhancedFatDxe/Info.c b/FatPkg/EnhancedFatDxe/Info.c
index 1a7f828..50b840b 100644
--- a/FatPkg/EnhancedFatDxe/Info.c
+++ b/FatPkg/EnhancedFatDxe/Info.c
@@ -14,24 +14,64 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
 
 **/
 
 #include "Fat.h"
 
+/**
+
+  Get the volume's info into Buffer.
+
+  @param  Volume                - FAT file system volume.
+  @param  BufferSize            - Size of Buffer.
+  @param  Buffer                - Buffer containing volume info.
+
+  @retval EFI_SUCCESS           - Get the volume info successfully.
+  @retval EFI_BUFFER_TOO_SMALL  - The buffer is too small.
+
+**/
 EFI_STATUS
 FatGetVolumeInfo (
   IN FAT_VOLUME       *Volume,
   IN OUT UINTN        *BufferSize,
   OUT VOID            *Buffer
   );
 
+/**
+
+  Set the volume's info.
+
+  @param  Volume                - FAT file system volume.
+  @param  BufferSize            - Size of Buffer.
+  @param  Buffer                - Buffer containing the new volume info.
+
+  @retval EFI_SUCCESS           - Set the volume info successfully.
+  @retval EFI_BAD_BUFFER_SIZE   - The buffer size is error.
+  @retval EFI_WRITE_PROTECTED   - The volume is read only.
+  @return other                 - An error occurred when operation the disk.
+
+**/
 EFI_STATUS
 FatSetVolumeInfo (
   IN FAT_VOLUME       *Volume,
   IN UINTN            BufferSize,
   IN VOID            *Buffer
   );
 
+/**
+
+  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,
-- 
1.9.5.msysgit.1