Add doxygen style comments for functions in Partition & Disk IO modules.

git-svn-id: https://edk2.svn.sourceforge.net/svnroot/edk2/trunk/edk2@5182 6f19259b-4bc3-4df7-8a09-765794883524

5 files changed, 312 insertions, 45 deletions

diff --git a/MdeModulePkg/Universal/Disk/DiskIoDxe/DiskIo.h b/MdeModulePkg/Universal/Disk/DiskIoDxe/DiskIo.h
index 57a0584..5223ae7 100644
--- a/MdeModulePkg/Universal/Disk/DiskIoDxe/DiskIo.h
+++ b/MdeModulePkg/Universal/Disk/DiskIoDxe/DiskIo.h
@@ -53,6 +53,19 @@ extern EFI_COMPONENT_NAME2_PROTOCOL  gDiskIoComponentName2;
 // Prototypes

 // Driver model protocol interface

 //

+/**

+  Test to see if this driver supports ControllerHandle. 

+

+  @param  This                Protocol instance pointer.

+  @param  ControllerHandle    Handle of device to test

+  @param  RemainingDevicePath Optional parameter use to pick a specific child

+                              device to start.

+

+  @retval EFI_SUCCESS         This driver supports this device

+  @retval EFI_ALREADY_STARTED This driver is already running on this device

+  @retval other               This driver does not support this device

+

+**/

 EFI_STATUS

 EFIAPI

 DiskIoDriverBindingSupported (

@@ -61,6 +74,20 @@ DiskIoDriverBindingSupported (
   IN EFI_DEVICE_PATH_PROTOCOL       *RemainingDevicePath

   );

 

+/**

+  Start this driver on ControllerHandle by opening a Block IO protocol and

+  installing a Disk IO protocol on ControllerHandle.

+

+  @param  This                 Protocol instance pointer.

+  @param  ControllerHandle     Handle of device to bind driver to

+  @param  RemainingDevicePath  Optional parameter use to pick a specific child

+                               device to start.

+

+  @retval EFI_SUCCESS          This driver is added to ControllerHandle

+  @retval EFI_ALREADY_STARTED  This driver is already running on ControllerHandle

+  @retval other                This driver does not support this device

+

+**/

 EFI_STATUS

 EFIAPI

 DiskIoDriverBindingStart (

@@ -69,6 +96,20 @@ DiskIoDriverBindingStart (
   IN EFI_DEVICE_PATH_PROTOCOL       *RemainingDevicePath

   );

 

+/**

+  Stop this driver on ControllerHandle by removing Disk IO protocol and closing

+  the Block IO protocol on ControllerHandle.

+

+  @param  This              Protocol instance pointer.

+  @param  ControllerHandle  Handle of device to stop driver on

+  @param  NumberOfChildren  Number of Handles in ChildHandleBuffer. If number of

+                            children is zero stop the entire bus driver.

+  @param  ChildHandleBuffer List of Child Handles to Stop.

+

+  @retval EFI_SUCCESS       This driver is removed ControllerHandle

+  @retval other             This driver was not removed from this device

+

+**/

 EFI_STATUS

 EFIAPI

 DiskIoDriverBindingStop (

@@ -81,6 +122,29 @@ DiskIoDriverBindingStop (
 //

 // Disk I/O Protocol Interface

 //

+/**

+  Read BufferSize bytes from Offset into Buffer.

+  Reads may support reads that are not aligned on

+  sector boundaries. There are three cases:

+    UnderRun - The first byte is not on a sector boundary or the read request is

+               less than a sector in length.

+    Aligned  - A read of N contiguous sectors.

+    OverRun  - The last byte is not on a sector boundary.

+

+  @param  This                  Protocol instance pointer.

+  @param  MediaId               Id of the media, changes every time the media is replaced.

+  @param  Offset                The starting byte offset to read from

+  @param  BufferSize            Size of Buffer

+  @param  Buffer                Buffer containing read data

+

+  @retval EFI_SUCCESS           The data was read correctly from the device.

+  @retval EFI_DEVICE_ERROR      The device reported an error while performing the read.

+  @retval EFI_NO_MEDIA          There is no media in the device.

+  @retval EFI_MEDIA_CHNAGED     The MediaId does not matched the current device.

+  @retval EFI_INVALID_PARAMETER The read request contains device addresses that are not

+                                valid for the device.

+

+**/

 EFI_STATUS

 EFIAPI

 DiskIoReadDisk (

@@ -91,6 +155,31 @@ DiskIoReadDisk (
   OUT VOID                 *Buffer

   );

 

+/**

+  Read BufferSize bytes from Offset into Buffer.

+  Writes may require a read modify write to support writes that are not

+  aligned on sector boundaries. There are three cases:

+    UnderRun - The first byte is not on a sector boundary or the write request

+               is less than a sector in length. Read modify write is required.

+    Aligned  - A write of N contiguous sectors.

+    OverRun  - The last byte is not on a sector boundary. Read modified write

+               required.

+

+  @param  This       Protocol instance pointer.

+  @param  MediaId    Id of the media, changes every time the media is replaced.

+  @param  Offset     The starting byte offset to read from

+  @param  BufferSize Size of Buffer

+  @param  Buffer     Buffer containing read data

+

+  @retval EFI_SUCCESS           The data was written correctly to the device.

+  @retval EFI_WRITE_PROTECTED   The device can not be written to.

+  @retval EFI_DEVICE_ERROR      The device reported an error while performing the write.

+  @retval EFI_NO_MEDIA          There is no media in the device.

+  @retval EFI_MEDIA_CHNAGED     The MediaId does not matched the current device.

+  @retval EFI_INVALID_PARAMETER The write request contains device addresses that are not

+                                 valid for the device.

+

+**/

 EFI_STATUS

 EFIAPI

 DiskIoWriteDisk (

diff --git a/MdeModulePkg/Universal/Disk/PartitionDxe/Gpt.c b/MdeModulePkg/Universal/Disk/PartitionDxe/Gpt.c
index 56245ec..ef3c766 100644
--- a/MdeModulePkg/Universal/Disk/PartitionDxe/Gpt.c
+++ b/MdeModulePkg/Universal/Disk/PartitionDxe/Gpt.c
@@ -17,6 +17,18 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
 #include "Partition.h"

 

 

+/**

+  Install child handles if the Handle supports GPT partition structure.

+

+  @param[in]  BlockIo     Parent BlockIo interface

+  @param[in]  DiskIo      Disk Io protocol.

+  @param[in]  Lba         The starting Lba of the Partition Table

+  @param[out] PartHeader  Stores the partition table that is read

+

+  @retval TRUE      The partition table is valid

+  @retval FALSE     The partition table is not valid

+

+**/

 BOOLEAN

 PartitionValidGptTable (

   IN  EFI_BLOCK_IO_PROTOCOL       *BlockIo,

@@ -26,6 +38,18 @@ PartitionValidGptTable (
   );

 

 

+/**

+  Check if the CRC field in the Partition table header is valid

+  for Partition entry array.

+

+  @param[in]  BlockIo     Parent BlockIo interface

+  @param[in]  DiskIo      Disk Io Protocol.

+  @param[in]  PartHeader  Partition table header structure

+

+  @retval TRUE      the CRC is valid

+  @retval FALSE     the CRC is invalid

+

+**/

 BOOLEAN

 PartitionCheckGptEntryArrayCRC (

   IN  EFI_BLOCK_IO_PROTOCOL       *BlockIo,

@@ -34,6 +58,18 @@ PartitionCheckGptEntryArrayCRC (
   );

 

 

+/**

+  Restore Partition Table to its alternate place

+  (Primary -> Backup or Backup -> Primary)

+

+  @param[in]  BlockIo     Parent BlockIo interface

+  @param[in]  DiskIo      Disk Io Protocol.

+  @param[in]  PartHeader  Partition table header structure

+

+  @retval TRUE      Restoring succeeds

+  @retval FALSE     Restoring failed

+

+**/

 BOOLEAN

 PartitionRestoreGptTable (

   IN  EFI_BLOCK_IO_PROTOCOL       *BlockIo,

@@ -42,6 +78,16 @@ PartitionRestoreGptTable (
   );

 

 

+/**

+  Restore Partition Table to its alternate place

+  (Primary -> Backup or Backup -> Primary)

+

+  @param[in]    PartHeader    Partition table header structure

+  @param[in]    PartEntry     The partition entry array

+  @param[out]   PEntryStatus  the partition entry status array 

+                              recording the status of each partition

+

+**/

 VOID

 PartitionCheckGptEntry (

   IN  EFI_PARTITION_TABLE_HEADER  *PartHeader,

@@ -50,6 +96,17 @@ PartitionCheckGptEntry (
   );

 

 

+/**

+  Checks the CRC32 value in the table header

+

+  @param  MaxSize   Max Size limit

+  @param  Size      The size of the table

+  @param  Hdr       Table to check

+

+  @return TRUE    CRC Valid

+  @return FALSE   CRC Invalid

+

+**/

 BOOLEAN

 PartitionCheckCrcAltSize (

   IN UINTN                 MaxSize,

@@ -58,6 +115,16 @@ PartitionCheckCrcAltSize (
   );

 

 

+/**

+  Checks the CRC32 value in the table header

+

+  @param  MaxSize   Max Size limit

+  @param  Hdr       Table to check

+

+  @return TRUE      CRC Valid

+  @return FALSE     CRC Invalid

+

+**/

 BOOLEAN

 PartitionCheckCrc (

   IN UINTN                 MaxSize,

@@ -65,6 +132,13 @@ PartitionCheckCrc (
   );

 

 

+/**

+  Updates the CRC32 value in the table header

+

+  @param  Size   The size of the table

+  @param  Hdr    Table to update

+

+**/

 VOID

 PartitionSetCrcAltSize (

   IN UINTN                 Size,

@@ -72,6 +146,12 @@ PartitionSetCrcAltSize (
   );

 

 

+/**

+  Updates the CRC32 value in the table header

+

+  @param  Hdr    Table to update

+

+**/

 VOID

 PartitionSetCrc (

   IN OUT EFI_TABLE_HEADER *Hdr

@@ -325,7 +405,7 @@ Done:
   @param[in]  BlockIo     Parent BlockIo interface

   @param[in]  DiskIo      Disk Io protocol.

   @param[in]  Lba         The starting Lba of the Partition Table

-  @param[in]  PartHeader  Stores the partition table that is read

+  @param[out] PartHeader  Stores the partition table that is read

 

   @retval TRUE      The partition table is valid

   @retval FALSE     The partition table is not valid

@@ -546,6 +626,7 @@ Done:
   @param[in]    PartEntry     The partition entry array

   @param[out]   PEntryStatus  the partition entry status array 

                               recording the status of each partition

+

 **/

 VOID

 PartitionCheckGptEntry (

@@ -602,7 +683,7 @@ PartitionCheckGptEntry (
 /**

   Updates the CRC32 value in the table header

 

-  @param[in,out]  Hdr    Table to update

+  @param  Hdr    Table to update

 

 **/

 VOID

@@ -617,8 +698,8 @@ PartitionSetCrc (
 /**

   Updates the CRC32 value in the table header

 

-  @param[in]      Size   The size of the table

-  @param[in,out]  Hdr    Table to update

+  @param  Size   The size of the table

+  @param  Hdr    Table to update

 

 **/

 VOID

@@ -639,11 +720,11 @@ PartitionSetCrcAltSize (
 /**

   Checks the CRC32 value in the table header

 

-  @param[in]      MaxSize   Max Size limit

-  @param[in,out]  Hdr       Table to check

+  @param  MaxSize   Max Size limit

+  @param  Hdr       Table to check

 

-  @return TRUE    CRC Valid

-  @return FALSE   CRC Invalid

+  @return TRUE      CRC Valid

+  @return FALSE     CRC Invalid

 

 **/

 BOOLEAN

@@ -659,9 +740,9 @@ PartitionCheckCrc (
 /**

   Checks the CRC32 value in the table header

 

-  @param[in]      MaxSize   Max Size limit

-  @param[in]      Size      The size of the table

-  @param[in,out]  Hdr       Table to check

+  @param  MaxSize   Max Size limit

+  @param  Size      The size of the table

+  @param  Hdr       Table to check

 

   @return TRUE    CRC Valid

   @return FALSE   CRC Invalid

diff --git a/MdeModulePkg/Universal/Disk/PartitionDxe/Mbr.c b/MdeModulePkg/Universal/Disk/PartitionDxe/Mbr.c
index be63a7e..c95a866 100644
--- a/MdeModulePkg/Universal/Disk/PartitionDxe/Mbr.c
+++ b/MdeModulePkg/Universal/Disk/PartitionDxe/Mbr.c
@@ -24,26 +24,22 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
 

 #include "Partition.h"

 

+/**

+  Test to see if the Mbr buffer is a valid MBR.

+

+  @param  Mbr         Parent Handle.

+  @param  LastLba     Last Lba address on the device.

+   

+  @retval TRUE        Mbr is a Valid MBR.

+  @retval FALSE       Mbr is not a Valid MBR.

+

+**/

 STATIC

 BOOLEAN

 PartitionValidMbr (

   IN  MASTER_BOOT_RECORD      *Mbr,

   IN  EFI_LBA                 LastLba

   )

-/*++

-

-Routine Description:

-  Test to see if the Mbr buffer is a valid MBR

-

-Arguments:       

-  Mbr     - Parent Handle 

-  LastLba - Last Lba address on the device.

-

-Returns:

-  TRUE  - Mbr is a Valid MBR

-  FALSE - Mbr is not a Valid MBR

-

---*/

 {

   UINT32  StartingLBA;

   UINT32  EndingLBA;

@@ -102,6 +98,21 @@ Returns:
   return MbrValid;

 }

 

+

+/**

+  Install child handles if the Handle supports MBR format.

+

+  @param  This              Calling context.

+  @param  Handle            Parent Handle.

+  @param  DiskIo            Parent DiskIo interface.

+  @param  BlockIo           Parent BlockIo interface.

+  @param  DevicePath        Parent Device Path.

+   

+  @retval EFI_SUCCESS       A child handle was added.

+  @retval EFI_MEDIA_CHANGED Media change was detected.

+  @retval Others            MBR partition was not found.

+

+**/

 EFI_STATUS

 PartitionInstallMbrChildHandles (

   IN  EFI_DRIVER_BINDING_PROTOCOL  *This,

@@ -110,24 +121,6 @@ PartitionInstallMbrChildHandles (
   IN  EFI_BLOCK_IO_PROTOCOL        *BlockIo,

   IN  EFI_DEVICE_PATH_PROTOCOL     *DevicePath

   )

-/*++

-

-Routine Description:

-  Install child handles if the Handle supports MBR format.

-

-Arguments:       

-  This       - Calling context.

-  Handle     - Parent Handle 

-  DiskIo     - Parent DiskIo interface

-  BlockIo    - Parent BlockIo interface

-  DevicePath - Parent Device Path

-

-Returns:

-  EFI_SUCCESS       - If a child handle was added

-  EFI_MEDIA_CHANGED - Media changed Detected

-	!EFI_SUCCESS      - Not found MBR partition.

-

---*/

 {

   EFI_STATUS                Status;

   MASTER_BOOT_RECORD        *Mbr;

diff --git a/MdeModulePkg/Universal/Disk/PartitionDxe/Partition.c b/MdeModulePkg/Universal/Disk/PartitionDxe/Partition.c
index 4ece475..66fa950 100644
--- a/MdeModulePkg/Universal/Disk/PartitionDxe/Partition.c
+++ b/MdeModulePkg/Universal/Disk/PartitionDxe/Partition.c
@@ -555,8 +555,7 @@ PartitionFlushBlocks (
   Create a child handle for a logical block device that represents the

   bytes Start to End of the Parent Block IO device.

 

-  @param[in]  This              Protocol instance pointer.

-  @param[in]  This              Calling context.

+  @param[in]  This              Protocol instance pointer

   @param[in]  ParentHandle      Parent Handle for new child

   @param[in]  ParentDiskIo      Parent DiskIo interface

   @param[in]  ParentBlockIo     Parent BlockIo interface

diff --git a/MdeModulePkg/Universal/Disk/PartitionDxe/Partition.h b/MdeModulePkg/Universal/Disk/PartitionDxe/Partition.h
index 4130762..9d6477c 100644
--- a/MdeModulePkg/Universal/Disk/PartitionDxe/Partition.h
+++ b/MdeModulePkg/Universal/Disk/PartitionDxe/Partition.h
@@ -88,6 +88,20 @@ extern EFI_COMPONENT_NAME2_PROTOCOL  gPartitionComponentName2;
 //

 // Function Prototypes

 //

+/**

+  Test to see if this driver supports ControllerHandle. Any ControllerHandle

+  than contains a BlockIo and DiskIo protocol can be supported.

+

+  @param  This                Protocol instance pointer.

+  @param  ControllerHandle    Handle of device to test

+  @param  RemainingDevicePath Optional parameter use to pick a specific child

+                              device to start.

+

+  @retval EFI_SUCCESS         This driver supports this device

+  @retval EFI_ALREADY_STARTED This driver is already running on this device

+  @retval other               This driver does not support this device

+

+**/

 EFI_STATUS

 EFIAPI

 PartitionDriverBindingSupported (

@@ -96,6 +110,21 @@ PartitionDriverBindingSupported (
   IN EFI_DEVICE_PATH_PROTOCOL     *RemainingDevicePath

   );

 

+/**

+  Start this driver on ControllerHandle by opening a Block IO and Disk IO

+  protocol, reading Device Path, and creating a child handle with a

+  Disk IO and device path protocol.

+

+  @param  This                 Protocol instance pointer.

+  @param  ControllerHandle     Handle of device to bind driver to

+  @param  RemainingDevicePath  Optional parameter use to pick a specific child

+                               device to start.

+

+  @retval EFI_SUCCESS          This driver is added to ControllerHandle

+  @retval EFI_ALREADY_STARTED  This driver is already running on ControllerHandle

+  @retval other                This driver does not support this device

+

+**/

 EFI_STATUS

 EFIAPI

 PartitionDriverBindingStart (

@@ -104,6 +133,20 @@ PartitionDriverBindingStart (
   IN EFI_DEVICE_PATH_PROTOCOL     *RemainingDevicePath

   );

 

+/**

+  Stop this driver on ControllerHandle. Support stoping any child handles

+  created by this driver.

+

+  @param  This              Protocol instance pointer.

+  @param  ControllerHandle  Handle of device to stop driver on

+  @param  NumberOfChildren  Number of Handles in ChildHandleBuffer. If number of

+                            children is zero stop the entire bus driver.

+  @param  ChildHandleBuffer List of Child Handles to Stop.

+

+  @retval EFI_SUCCESS       This driver is removed ControllerHandle

+  @retval other             This driver was not removed from this device

+

+**/

 EFI_STATUS

 EFIAPI

 PartitionDriverBindingStop (

@@ -243,6 +286,25 @@ PartitionComponentNameGetControllerName (
   );

 

 

+/**

+  Create a child handle for a logical block device that represents the

+  bytes Start to End of the Parent Block IO device.

+

+  @param[in]  This              Protocol instance pointer

+  @param[in]  ParentHandle      Parent Handle for new child

+  @param[in]  ParentDiskIo      Parent DiskIo interface

+  @param[in]  ParentBlockIo     Parent BlockIo interface

+  @param[in]  ParentDevicePath  Parent Device Path

+  @param[in]  DevicePathNode    Child Device Path node

+  @param[in]  Start             Start Block

+  @param[in]  End               End Block

+  @param[in]  BlockSize         Child block size

+  @param[in]  InstallEspGuid    Flag to install EFI System Partition GUID on handle

+

+  @retval EFI_SUCCESS       A child handle was added

+  @retval other             A child handle was not added

+

+**/

 EFI_STATUS

 PartitionInstallChildHandle (

   IN  EFI_DRIVER_BINDING_PROTOCOL  *This,

@@ -258,6 +320,20 @@ PartitionInstallChildHandle (
   )

 ;

 

+/**

+  Install child handles if the Handle supports GPT partition structure.

+

+  @param[in]  This       - Calling context.

+  @param[in]  Handle     - Parent Handle

+  @param[in]  DiskIo     - Parent DiskIo interface

+  @param[in]  BlockIo    - Parent BlockIo interface

+  @param[in]  DevicePath - Parent Device Path

+

+  @retval EFI_SUCCESS         Valid GPT disk

+  @retval EFI_MEDIA_CHANGED   Media changed Detected

+  @retval other               Not a valid GPT disk

+

+**/

 EFI_STATUS

 PartitionInstallGptChildHandles (

   IN  EFI_DRIVER_BINDING_PROTOCOL  *This,

@@ -268,6 +344,21 @@ PartitionInstallGptChildHandles (
   )

 ;

 

+/**

+  Install child handles if the Handle supports El Torito format.

+

+  @param[in]  This        Calling context.

+  @param[in]  Handle      Parent Handle

+  @param[in]  DiskIo      Parent DiskIo interface

+  @param[in]  BlockIo     Parent BlockIo interface

+  @param[in]  DevicePath  Parent Device Path

+

+

+  @retval EFI_SUCCESS         Child handle(s) was added

+  @retval EFI_MEDIA_CHANGED   Media changed Detected

+  @retval other               no child handle was added

+

+**/

 EFI_STATUS

 PartitionInstallElToritoChildHandles (

   IN  EFI_DRIVER_BINDING_PROTOCOL  *This,

@@ -278,6 +369,20 @@ PartitionInstallElToritoChildHandles (
   )

 ;

 

+/**

+  Install child handles if the Handle supports MBR format.

+

+  @param  This              Calling context.

+  @param  Handle            Parent Handle.

+  @param  DiskIo            Parent DiskIo interface.

+  @param  BlockIo           Parent BlockIo interface.

+  @param  DevicePath        Parent Device Path.

+   

+  @retval EFI_SUCCESS       A child handle was added.

+  @retval EFI_MEDIA_CHANGED Media change was detected.

+  @retval Others            MBR partition was not found.

+

+**/

 EFI_STATUS

 PartitionInstallMbrChildHandles (

   IN  EFI_DRIVER_BINDING_PROTOCOL  *This,