MdePkg: Replace BSD License with BSD+Patent License

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

/** @file\r
  Block IO protocol as defined in the UEFI 2.0 specification.\r
\r
  The Block IO protocol is used to abstract block devices like hard drives,\r
  DVD-ROMs and floppy drives.\r
\r
  Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR>\r
  SPDX-License-Identifier: BSD-2-Clause-Patent\r
\r
**/\r
\r
#ifndef __BLOCK_IO_H__\r
#define __BLOCK_IO_H__\r
\r
#define EFI_BLOCK_IO_PROTOCOL_GUID \\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
\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
/**\r
  Reset the Block Device.\r
\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
  @retval EFI_DEVICE_ERROR     The device is not functioning properly and could\r
                               not be reset.\r
\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *EFI_BLOCK_RESET)(\r
  IN EFI_BLOCK_IO_PROTOCOL          *This,\r
  IN BOOLEAN                        ExtendedVerification\r
  );\r
\r
/**\r
  Read BufferSize bytes from Lba into Buffer.\r
\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     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 LBAs that are not valid,\r
                                or the buffer is not on proper alignment.\r
\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *EFI_BLOCK_READ)(\r
  IN EFI_BLOCK_IO_PROTOCOL          *This,\r
  IN UINT32                         MediaId,\r
  IN EFI_LBA                        Lba,\r
  IN UINTN                          BufferSize,\r
  OUT VOID                          *Buffer\r
  );\r
\r
/**\r
  Write BufferSize bytes from Lba into Buffer.\r
\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     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_DEVICE_ERROR      The device reported an error while performing the write.\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 LBAs that are not valid,\r
                                or the buffer is not on proper alignment.\r
\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *EFI_BLOCK_WRITE)(\r
  IN EFI_BLOCK_IO_PROTOCOL          *This,\r
  IN UINT32                         MediaId,\r
  IN EFI_LBA                        Lba,\r
  IN UINTN                          BufferSize,\r
  IN VOID                           *Buffer\r
  );\r
\r
/**\r
  Flush the Block Device.\r
\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
  @retval EFI_NO_MEDIA      There is no media in the device.\r
\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *EFI_BLOCK_FLUSH)(\r
  IN EFI_BLOCK_IO_PROTOCOL  *This\r
  );\r
\r
/**\r
  Block IO read only mode data and updated only via members of BlockIO\r
**/\r
typedef struct {\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
#define EFI_BLOCK_IO_PROTOCOL_REVISION2 0x00020001\r
#define EFI_BLOCK_IO_PROTOCOL_REVISION3 0x00020031\r
\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
\r
extern EFI_GUID gEfiBlockIoProtocolGuid;\r
\r
#endif\r