code scrub ArpDxe

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

diff --git a/MdePkg/Include/Protocol/BlockIo.h b/MdePkg/Include/Protocol/BlockIo.h
index dd3d9c1a1503ed18c8b206a47c9cbf2ef2763583..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
@@ -189,10 +191,9 @@ typedef struct {
 /// \r
 #define EFI_BLOCK_IO_INTERFACE_REVISION   EFI_BLOCK_IO_PROTOCOL_REVISION\r
 \r
-/**\r
-  @par Protocol Description:\r
-  This protocol provides control over block devices.\r
-**/\r
+///\r
+///  This protocol provides control over block devices.\r
+///\r
 struct _EFI_BLOCK_IO_PROTOCOL {\r
   ///\r
   /// The revision to which the block IO interface adheres. All future\r
@@ -200,7 +201,9 @@ struct _EFI_BLOCK_IO_PROTOCOL {
   /// back wards compatible, it is not the same GUID.\r
   ///\r
   UINT64              Revision;\r
-\r
+  ///\r
+  /// Pointer to the EFI_BLOCK_IO_MEDIA data for this device.\r
+  ///\r
   EFI_BLOCK_IO_MEDIA  *Media;\r
 \r
   EFI_BLOCK_RESET     Reset;\r