From a8d0c20e7aa01e4f676003650b3b1c7cb40028ba Mon Sep 17 00:00:00 2001 From: qhuang8 Date: Thu, 8 May 2008 04:17:44 +0000 Subject: [PATCH] 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 --- .../Universal/Disk/DiskIoDxe/DiskIo.h | 89 +++++++++++++++ .../Universal/Disk/PartitionDxe/Gpt.c | 103 +++++++++++++++-- .../Universal/Disk/PartitionDxe/Mbr.c | 57 +++++----- .../Universal/Disk/PartitionDxe/Partition.c | 3 +- .../Universal/Disk/PartitionDxe/Partition.h | 105 ++++++++++++++++++ 5 files changed, 312 insertions(+), 45 deletions(-) diff --git a/MdeModulePkg/Universal/Disk/DiskIoDxe/DiskIo.h b/MdeModulePkg/Universal/Disk/DiskIoDxe/DiskIo.h index 57a0584782..5223ae7b90 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 56245ec7ae..ef3c766e53 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 be63a7e234..c95a866e75 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 4ece475d98..66fa9507f3 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 41307629a8..9d6477cc3a 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, -- 2.39.2