Update comments for Protocol definitions to match UEFI spec. And add the missing comments for the data structure.

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

1 files changed, 14 insertions, 12 deletions

diff --git a/MdePkg/Include/Protocol/BlockIo.h b/MdePkg/Include/Protocol/BlockIo.h
index adbeedc289..ba3cae2082 100644
--- a/MdePkg/Include/Protocol/BlockIo.h
+++ b/MdePkg/Include/Protocol/BlockIo.h
@@ -38,7 +38,7 @@ typedef EFI_BLOCK_IO_PROTOCOL   EFI_BLOCK_IO;
 /**

   Reset the Block Device.

 

-  @param  This                 Protocol instance pointer.

+  @param  This                 Indicates a pointer to the calling context.

   @param  ExtendedVerification Driver may perform diagnostics on reset.

 

   @retval EFI_SUCCESS          The device was reset.

@@ -56,19 +56,20 @@ EFI_STATUS
 /**

   Read BufferSize bytes from Lba into Buffer.

 

-  @param  This       Protocol instance pointer.

+  @param  This       Indicates a pointer to the calling context.

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

   @param  Lba        The starting Logical Block Address to read from

   @param  BufferSize Size of Buffer, must be a multiple of device block size.

-  @param  Buffer     Buffer containing read data

+  @param  Buffer     A pointer to the destination buffer for the data. The caller is

+                     responsible for either having implicit or explicit ownership of the buffer.

 

   @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_CHANGED     The MediaId does not matched the current device.

   @retval EFI_BAD_BUFFER_SIZE   The Buffer was not a multiple of the block size of the device.

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

-                                valid for the device.

+  @retval EFI_INVALID_PARAMETER The read request contains LBAs that are not valid, 

+                                or the buffer is not on proper alignment.

 

 **/

 typedef

@@ -84,11 +85,12 @@ EFI_STATUS
 /**

   Write BufferSize bytes from Lba into Buffer.

 

-  @param  This       Protocol instance pointer.

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

-  @param  Lba        The starting Logical Block Address to read from

+  @param  This       Indicates a pointer to the calling context.

+  @param  MediaId    The media ID that the write request is for.

+  @param  Lba        The starting logical block address to be written. The caller is

+                     responsible for writing to only legitimate locations.

   @param  BufferSize Size of Buffer, must be a multiple of device block size.

-  @param  Buffer     Buffer containing read data

+  @param  Buffer     A pointer to the source buffer for the data.

 

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

   @retval EFI_WRITE_PROTECTED   The device can not be written to.

@@ -96,8 +98,8 @@ EFI_STATUS
   @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_BAD_BUFFER_SIZE   The Buffer was not a multiple of the block size of the device.

-  @retval EFI_INVALID_PARAMETER The write request contains a LBA that is not

-                                valid for the device.

+  @retval EFI_INVALID_PARAMETER The write request contains LBAs that are not valid, 

+                                or the buffer is not on proper alignment.

 

 **/

 typedef

@@ -113,7 +115,7 @@ EFI_STATUS
 /**

   Flush the Block Device.

 

-  @param  This              Protocol instance pointer.

+  @param  This              Indicates a pointer to the calling context.

 

   @retval EFI_SUCCESS       All outstanding data was written to the device

   @retval EFI_DEVICE_ERROR  The device reported an error while writting back the data