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

[mirror_edk2.git] / MdePkg / Include / Protocol / BlockIo.h

diff --git a/MdePkg/Include/Protocol/BlockIo.h b/MdePkg/Include/Protocol/BlockIo.h
index adbeedc2895c24949a03dcc92f79617009fe9d1a..ba3cae208201370e3df7de2ad9b0704bb1dde3f5 100644 (file)
--- a/MdePkg/Include/Protocol/BlockIo.h
+++ b/MdePkg/Include/Protocol/BlockIo.h
@@ -38,7 +38,7 @@ typedef EFI_BLOCK_IO_PROTOCOL   EFI_BLOCK_IO;
 /**\r
   Reset the Block Device.\r
 \r
-  @param  This                 Protocol instance pointer.\r
+  @param  This                 Indicates a pointer to the calling context.\r
   @param  ExtendedVerification Driver may perform diagnostics on reset.\r
 \r
   @retval EFI_SUCCESS          The device was reset.\r
@@ -56,19 +56,20 @@ EFI_STATUS
 /**\r
   Read BufferSize bytes from Lba into Buffer.\r
 \r
-  @param  This       Protocol instance pointer.\r
+  @param  This       Indicates a pointer to the calling context.\r
   @param  MediaId    Id of the media, changes every time the media is replaced.\r
   @param  Lba        The starting Logical Block Address to read from\r
   @param  BufferSize Size of Buffer, must be a multiple of device block size.\r
-  @param  Buffer     Buffer containing read data\r
+  @param  Buffer     A pointer to the destination buffer for the data. The caller is\r
+                     responsible for either having implicit or explicit ownership of the buffer.\r
 \r
   @retval EFI_SUCCESS           The data was read correctly from the device.\r
   @retval EFI_DEVICE_ERROR      The device reported an error while performing the read.\r
   @retval EFI_NO_MEDIA          There is no media in the device.\r
   @retval EFI_MEDIA_CHANGED     The MediaId does not matched the current device.\r
   @retval EFI_BAD_BUFFER_SIZE   The Buffer was not a multiple of the block size of the device.\r
-  @retval EFI_INVALID_PARAMETER The read request contains device addresses that are not\r
-                                valid for the device.\r
+  @retval EFI_INVALID_PARAMETER The read request contains LBAs that are not valid, \r
+                                or the buffer is not on proper alignment.\r
 \r
 **/\r
 typedef\r
@@ -84,11 +85,12 @@ EFI_STATUS
 /**\r
   Write BufferSize bytes from Lba into Buffer.\r
 \r
-  @param  This       Protocol instance pointer.\r
-  @param  MediaId    Id of the media, changes every time the media is replaced.\r
-  @param  Lba        The starting Logical Block Address to read from\r
+  @param  This       Indicates a pointer to the calling context.\r
+  @param  MediaId    The media ID that the write request is for.\r
+  @param  Lba        The starting logical block address to be written. The caller is\r
+                     responsible for writing to only legitimate locations.\r
   @param  BufferSize Size of Buffer, must be a multiple of device block size.\r
-  @param  Buffer     Buffer containing read data\r
+  @param  Buffer     A pointer to the source buffer for the data.\r
 \r
   @retval EFI_SUCCESS           The data was written correctly to the device.\r
   @retval EFI_WRITE_PROTECTED   The device can not be written to.\r
@@ -96,8 +98,8 @@ EFI_STATUS
   @retval EFI_NO_MEDIA          There is no media in the device.\r
   @retval EFI_MEDIA_CHNAGED     The MediaId does not matched the current device.\r
   @retval EFI_BAD_BUFFER_SIZE   The Buffer was not a multiple of the block size of the device.\r
-  @retval EFI_INVALID_PARAMETER The write request contains a LBA that is not\r
-                                valid for the device.\r
+  @retval EFI_INVALID_PARAMETER The write request contains LBAs that are not valid, \r
+                                or the buffer is not on proper alignment.\r
 \r
 **/\r
 typedef\r
@@ -113,7 +115,7 @@ EFI_STATUS
 /**\r
   Flush the Block Device.\r
 \r
-  @param  This              Protocol instance pointer.\r
+  @param  This              Indicates a pointer to the calling context.\r
 \r
   @retval EFI_SUCCESS       All outstanding data was written to the device\r
   @retval EFI_DEVICE_ERROR  The device reported an error while writting back the data\r