The Block IO protocol is used to abstract block devices like hard drives,\r
DVD-ROMs and floppy drives.\r
\r
- Copyright (c) 2006, Intel Corporation \r
- All rights reserved. This program and the accompanying materials \r
- are licensed and made available under the terms and conditions of the BSD License \r
- which accompanies this distribution. The full text of the license may be found at \r
- http://opensource.org/licenses/bsd-license.php \r
-\r
- THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, \r
- WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. \r
+ Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR>\r
+ SPDX-License-Identifier: BSD-2-Clause-Patent\r
\r
**/\r
\r
0x964e5b21, 0x6459, 0x11d2, {0x8e, 0x39, 0x0, 0xa0, 0xc9, 0x69, 0x72, 0x3b } \\r
}\r
\r
-typedef struct _EFI_BLOCK_IO_PROTOCOL EFI_BLOCK_IO_PROTOCOL;\r
+typedef struct _EFI_BLOCK_IO_PROTOCOL EFI_BLOCK_IO_PROTOCOL;\r
\r
-//\r
-// Protocol GUID name defined in EFI1.1.\r
-// \r
-#define BLOCK_IO_PROTOCOL EFI_BLOCK_IO_PROTOCOL_GUID\r
+///\r
+/// Protocol GUID name defined in EFI1.1.\r
+///\r
+#define BLOCK_IO_PROTOCOL EFI_BLOCK_IO_PROTOCOL_GUID\r
\r
-//\r
-// Protocol defined in EFI1.1.\r
-// \r
-typedef EFI_BLOCK_IO_PROTOCOL EFI_BLOCK_IO;\r
+///\r
+/// Protocol defined in EFI1.1.\r
+///\r
+typedef EFI_BLOCK_IO_PROTOCOL EFI_BLOCK_IO;\r
\r
/**\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
(EFIAPI *EFI_BLOCK_RESET)(\r
IN EFI_BLOCK_IO_PROTOCOL *This,\r
IN BOOLEAN ExtendedVerification\r
- )\r
-;\r
+ );\r
\r
/**\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
IN EFI_LBA Lba,\r
IN UINTN BufferSize,\r
OUT VOID *Buffer\r
- )\r
-;\r
+ );\r
\r
/**\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
@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
IN EFI_LBA Lba,\r
IN UINTN BufferSize,\r
IN VOID *Buffer\r
- )\r
-;\r
+ );\r
\r
/**\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
EFI_STATUS\r
(EFIAPI *EFI_BLOCK_FLUSH)(\r
IN EFI_BLOCK_IO_PROTOCOL *This\r
- )\r
-;\r
+ );\r
\r
/**\r
Block IO read only mode data and updated only via members of BlockIO\r
-\r
**/\r
typedef struct {\r
- UINT32 MediaId; ///< The curent media Id. If the media changes, this value is changed.\r
- BOOLEAN RemovableMedia; ///< TRUE if the media is removable; otherwise, FALSE.\r
- BOOLEAN MediaPresent; /**< TRUE if there is a media currently present in the device;\r
- othersise, FALSE. THis field shows the media present status\r
- as of the most recent ReadBlocks() or WriteBlocks() call.\r
- **/\r
- BOOLEAN LogicalPartition; /**< TRUE if LBA 0 is the first block of a partition; otherwise\r
- FALSE. For media with only one partition this would be TRUE.\r
- **/\r
- BOOLEAN ReadOnly; /**< TRUE if the media is marked read-only otherwise, FALSE.\r
- This field shows the read-only status as of the most recent WriteBlocks () call.\r
- **/\r
- BOOLEAN WriteCaching; ///< TRUE if the WriteBlock () function caches write data.\r
-\r
- UINT32 BlockSize; /**< The intrinsic block size of the device. If the media changes, then\r
- this field is updated.\r
- **/\r
- UINT32 IoAlign; ///< Supplies the alignment requirement for any buffer to read or write block(s).\r
-\r
- EFI_LBA LastBlock; /**< The last logical block address on the device.\r
- If the media changes, then this field is updated.\r
- **/\r
+ ///\r
+ /// The curent media Id. If the media changes, this value is changed.\r
+ ///\r
+ UINT32 MediaId;\r
+\r
+ ///\r
+ /// TRUE if the media is removable; otherwise, FALSE.\r
+ ///\r
+ BOOLEAN RemovableMedia;\r
+\r
+ ///\r
+ /// TRUE if there is a media currently present in the device;\r
+ /// othersise, FALSE. THis field shows the media present status\r
+ /// as of the most recent ReadBlocks() or WriteBlocks() call.\r
+ ///\r
+ BOOLEAN MediaPresent;\r
+\r
+ ///\r
+ /// TRUE if LBA 0 is the first block of a partition; otherwise\r
+ /// FALSE. For media with only one partition this would be TRUE.\r
+ ///\r
+ BOOLEAN LogicalPartition;\r
+\r
+ ///\r
+ /// TRUE if the media is marked read-only otherwise, FALSE.\r
+ /// This field shows the read-only status as of the most recent WriteBlocks () call.\r
+ ///\r
+ BOOLEAN ReadOnly;\r
+\r
+ ///\r
+ /// TRUE if the WriteBlock () function caches write data.\r
+ ///\r
+ BOOLEAN WriteCaching;\r
+\r
+ ///\r
+ /// The intrinsic block size of the device. If the media changes, then\r
+ /// this field is updated.\r
+ ///\r
+ UINT32 BlockSize;\r
+\r
+ ///\r
+ /// Supplies the alignment requirement for any buffer to read or write block(s).\r
+ ///\r
+ UINT32 IoAlign;\r
+\r
+ ///\r
+ /// The last logical block address on the device.\r
+ /// If the media changes, then this field is updated.\r
+ ///\r
+ EFI_LBA LastBlock;\r
+\r
+ ///\r
+ /// Only present if EFI_BLOCK_IO_PROTOCOL.Revision is greater than or equal to\r
+ /// EFI_BLOCK_IO_PROTOCOL_REVISION2. Returns the first LBA is aligned to\r
+ /// a physical block boundary.\r
+ ///\r
+ EFI_LBA LowestAlignedLba;\r
+\r
+ ///\r
+ /// Only present if EFI_BLOCK_IO_PROTOCOL.Revision is greater than or equal to\r
+ /// EFI_BLOCK_IO_PROTOCOL_REVISION2. Returns the number of logical blocks\r
+ /// per physical block.\r
+ ///\r
+ UINT32 LogicalBlocksPerPhysicalBlock;\r
+\r
+ ///\r
+ /// Only present if EFI_BLOCK_IO_PROTOCOL.Revision is greater than or equal to\r
+ /// EFI_BLOCK_IO_PROTOCOL_REVISION3. Returns the optimal transfer length\r
+ /// granularity as a number of logical blocks.\r
+ ///\r
+ UINT32 OptimalTransferLengthGranularity;\r
} EFI_BLOCK_IO_MEDIA;\r
\r
-#define EFI_BLOCK_IO_PROTOCOL_REVISION 0x00010000\r
-//\r
-// Revision defined in EFI1.1.\r
-// \r
-#define EFI_BLOCK_IO_INTERFACE_REVISION EFI_BLOCK_IO_PROTOCOL_REVISION\r
+#define EFI_BLOCK_IO_PROTOCOL_REVISION 0x00010000\r
+#define EFI_BLOCK_IO_PROTOCOL_REVISION2 0x00020001\r
+#define EFI_BLOCK_IO_PROTOCOL_REVISION3 0x0002001F\r
\r
-struct _EFI_BLOCK_IO_PROTOCOL {\r
- UINT64 Revision;\r
-\r
- EFI_BLOCK_IO_MEDIA *Media;\r
-\r
- EFI_BLOCK_RESET Reset;\r
- EFI_BLOCK_READ ReadBlocks;\r
- EFI_BLOCK_WRITE WriteBlocks;\r
- EFI_BLOCK_FLUSH FlushBlocks;\r
+///\r
+/// Revision defined in EFI1.1.\r
+///\r
+#define EFI_BLOCK_IO_INTERFACE_REVISION EFI_BLOCK_IO_PROTOCOL_REVISION\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
+ /// revisions must be backwards compatible. If a future version is not\r
+ /// back wards compatible, it is not the same GUID.\r
+ ///\r
+ UINT64 Revision;\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
+ EFI_BLOCK_READ ReadBlocks;\r
+ EFI_BLOCK_WRITE WriteBlocks;\r
+ EFI_BLOCK_FLUSH FlushBlocks;\r
};\r
\r
-extern EFI_GUID gEfiBlockIoProtocolGuid;\r
+extern EFI_GUID gEfiBlockIoProtocolGuid;\r
\r
#endif\r