X-Git-Url: https://git.proxmox.com/?p=mirror_edk2.git;a=blobdiff_plain;f=MdePkg%2FInclude%2FProtocol%2FBlockIo.h;h=213c897e7497330cf095f4a7c3092a063287f8e1;hp=ecfd3a7551320ff44f5f7bd733b3cd08c2a8b6a2;hb=9095d37b8fe5bfc3d02adad6ba7fd7359ebc0107;hpb=4ca9b6c4e7dbbcf94f21b54f41f761cefc6b1086 diff --git a/MdePkg/Include/Protocol/BlockIo.h b/MdePkg/Include/Protocol/BlockIo.h index ecfd3a7551..213c897e74 100644 --- a/MdePkg/Include/Protocol/BlockIo.h +++ b/MdePkg/Include/Protocol/BlockIo.h @@ -4,14 +4,14 @@ The Block IO protocol is used to abstract block devices like hard drives, DVD-ROMs and floppy drives. - Copyright (c) 2006 - 2008, Intel Corporation - All rights reserved. This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php + Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.
+ This program and the accompanying materials + are licensed and made available under the terms and conditions of the BSD License + which accompanies this distribution. The full text of the license may be found at + http://opensource.org/licenses/bsd-license.php - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, + WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. **/ @@ -25,20 +25,20 @@ typedef struct _EFI_BLOCK_IO_PROTOCOL EFI_BLOCK_IO_PROTOCOL; -// -// Protocol GUID name defined in EFI1.1. -// +/// +/// Protocol GUID name defined in EFI1.1. +/// #define BLOCK_IO_PROTOCOL EFI_BLOCK_IO_PROTOCOL_GUID -// -// Protocol defined in EFI1.1. -// +/// +/// Protocol defined in EFI1.1. +/// 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. @@ -51,25 +51,25 @@ EFI_STATUS (EFIAPI *EFI_BLOCK_RESET)( IN EFI_BLOCK_IO_PROTOCOL *This, IN BOOLEAN ExtendedVerification - ) -; + ); /** 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 @@ -80,17 +80,17 @@ EFI_STATUS IN EFI_LBA Lba, IN UINTN BufferSize, OUT VOID *Buffer - ) -; + ); /** 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. @@ -98,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 @@ -110,13 +110,12 @@ EFI_STATUS IN EFI_LBA Lba, IN UINTN BufferSize, IN VOID *Buffer - ) -; + ); /** 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 @@ -127,92 +126,107 @@ typedef EFI_STATUS (EFIAPI *EFI_BLOCK_FLUSH)( IN EFI_BLOCK_IO_PROTOCOL *This - ) -; + ); /** Block IO read only mode data and updated only via members of BlockIO - - @param MediaId - The curent media Id. If the media changes, this value is changed. - - @param RemovableMedia - TRUE if the media is removable; otherwise, FALSE. - - @param MediaPresent - TRUE if there is a media currently present in the device; - othersise, FALSE. THis field shows the media present status - as of the most recent ReadBlocks() or WriteBlocks() call. - - @param LogicalPartition - TRUE if LBA 0 is the first block of a partition; otherwise - FALSE. For media with only one partition this would be TRUE. - - @param ReadOnly - TRUE if the media is marked read-only otherwise, FALSE. - This field shows the read-only status as of the most recent WriteBlocks () call. - - @param WriteCaching - TRUE if the WriteBlock () function caches write data. - - @param BlockSize - The intrinsic block size of the device. If the media changes, then - this field is updated. - - @param IoAlign - Supplies the alignment requirement for any buffer to read or write block(s). - - @param LastBlock - The last logical block address on the device. - If the media changes, then this field is updated. - **/ typedef struct { - UINT32 MediaId; + /// + /// The curent media Id. If the media changes, this value is changed. + /// + UINT32 MediaId; + + /// + /// TRUE if the media is removable; otherwise, FALSE. + /// BOOLEAN RemovableMedia; + + /// + /// TRUE if there is a media currently present in the device; + /// othersise, FALSE. THis field shows the media present status + /// as of the most recent ReadBlocks() or WriteBlocks() call. + /// BOOLEAN MediaPresent; + + /// + /// TRUE if LBA 0 is the first block of a partition; otherwise + /// FALSE. For media with only one partition this would be TRUE. + /// BOOLEAN LogicalPartition; + + /// + /// TRUE if the media is marked read-only otherwise, FALSE. + /// This field shows the read-only status as of the most recent WriteBlocks () call. + /// BOOLEAN ReadOnly; - BOOLEAN WriteCaching; - UINT32 BlockSize; - UINT32 IoAlign; - EFI_LBA LastBlock; + + /// + /// TRUE if the WriteBlock () function caches write data. + /// + BOOLEAN WriteCaching; + + /// + /// The intrinsic block size of the device. If the media changes, then + /// this field is updated. + /// + UINT32 BlockSize; + + /// + /// Supplies the alignment requirement for any buffer to read or write block(s). + /// + UINT32 IoAlign; + + /// + /// The last logical block address on the device. + /// If the media changes, then this field is updated. + /// + EFI_LBA LastBlock; + + /// + /// Only present if EFI_BLOCK_IO_PROTOCOL.Revision is greater than or equal to + /// EFI_BLOCK_IO_PROTOCOL_REVISION2. Returns the first LBA is aligned to + /// a physical block boundary. + /// + EFI_LBA LowestAlignedLba; + + /// + /// Only present if EFI_BLOCK_IO_PROTOCOL.Revision is greater than or equal to + /// EFI_BLOCK_IO_PROTOCOL_REVISION2. Returns the number of logical blocks + /// per physical block. + /// + UINT32 LogicalBlocksPerPhysicalBlock; + + /// + /// Only present if EFI_BLOCK_IO_PROTOCOL.Revision is greater than or equal to + /// EFI_BLOCK_IO_PROTOCOL_REVISION3. Returns the optimal transfer length + /// granularity as a number of logical blocks. + /// + UINT32 OptimalTransferLengthGranularity; } EFI_BLOCK_IO_MEDIA; #define EFI_BLOCK_IO_PROTOCOL_REVISION 0x00010000 -// -// Revision defined in EFI1.1. -// -#define EFI_BLOCK_IO_INTERFACE_REVISION EFI_BLOCK_IO_PROTOCOL_REVISION +#define EFI_BLOCK_IO_PROTOCOL_REVISION2 0x00020001 +#define EFI_BLOCK_IO_PROTOCOL_REVISION3 0x00020031 -/** - @par Protocol Description: - This protocol provides control over block devices. - - @param Revision - The revision to which the block IO interface adheres. All future - revisions must be backwards compatible. If a future version is not - back wards compatible, it is not the same GUID. - - @param Media - A pointer to the EFI_BLOCK_IO_MEDIA data for this device. - - @param Reset - Resets the block device hardware. - - @param ReadBlocks - Reads the requested number of blocks from the device. - - @param WriteBlocks - Writes the requested number of blocks to the device. +/// +/// Revision defined in EFI1.1. +/// +#define EFI_BLOCK_IO_INTERFACE_REVISION EFI_BLOCK_IO_PROTOCOL_REVISION - @param FlushBlocks - Flushes and cache blocks. This function is optional and only - needs to be supported on block devices that cache writes. -**/ +/// +/// This protocol provides control over block devices. +/// struct _EFI_BLOCK_IO_PROTOCOL { + /// + /// The revision to which the block IO interface adheres. All future + /// revisions must be backwards compatible. If a future version is not + /// back wards compatible, it is not the same GUID. + /// UINT64 Revision; - + /// + /// Pointer to the EFI_BLOCK_IO_MEDIA data for this device. + /// EFI_BLOCK_IO_MEDIA *Media; EFI_BLOCK_RESET Reset;