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

["Ni, Ruiyu" <ruiyu.ni@intel.com>]

Reviewed-by: Ruiyu Ni <ruiyu.ni@intel.com>

Regards,
Ray

>-----Original Message-----
>From: Bi, Dandan
>Sent: Thursday, December 8, 2016 6:54 PM
>To: edk2-devel@lists.01.org
>Cc: Ni, Ruiyu <ruiyu.ni@intel.com>
>Subject: [patch 7/8] FatPkg\EnhancedFatDxe: Add comments for functions
>
>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