iPXE
BlockIo.h
Go to the documentation of this file.
00001 /** @file
00002   Block IO protocol as defined in the UEFI 2.0 specification.
00003 
00004   The Block IO protocol is used to abstract block devices like hard drives,
00005   DVD-ROMs and floppy drives.
00006 
00007   Copyright (c) 2006 - 2011, Intel Corporation. All rights reserved.<BR>
00008   This program and the accompanying materials
00009   are licensed and made available under the terms and conditions of the BSD License
00010   which accompanies this distribution.  The full text of the license may be found at
00011   http://opensource.org/licenses/bsd-license.php
00012 
00013   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
00014   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
00015 
00016 **/
00017 
00018 #ifndef __BLOCK_IO_H__
00019 #define __BLOCK_IO_H__
00020 
00021 FILE_LICENCE ( BSD3 );
00022 
00023 #define EFI_BLOCK_IO_PROTOCOL_GUID \
00024   { \
00025     0x964e5b21, 0x6459, 0x11d2, {0x8e, 0x39, 0x0, 0xa0, 0xc9, 0x69, 0x72, 0x3b } \
00026   }
00027 
00028 typedef struct _EFI_BLOCK_IO_PROTOCOL  EFI_BLOCK_IO_PROTOCOL;
00029 
00030 ///
00031 /// Protocol GUID name defined in EFI1.1.
00032 ///
00033 #define BLOCK_IO_PROTOCOL       EFI_BLOCK_IO_PROTOCOL_GUID
00034 
00035 ///
00036 /// Protocol defined in EFI1.1.
00037 ///
00038 typedef EFI_BLOCK_IO_PROTOCOL   EFI_BLOCK_IO;
00039 
00040 /**
00041   Reset the Block Device.
00042 
00043   @param  This                 Indicates a pointer to the calling context.
00044   @param  ExtendedVerification Driver may perform diagnostics on reset.
00045 
00046   @retval EFI_SUCCESS          The device was reset.
00047   @retval EFI_DEVICE_ERROR     The device is not functioning properly and could
00048                                not be reset.
00049 
00050 **/
00051 typedef
00052 EFI_STATUS
00053 (EFIAPI *EFI_BLOCK_RESET)(
00054   IN EFI_BLOCK_IO_PROTOCOL          *This,
00055   IN BOOLEAN                        ExtendedVerification
00056   );
00057 
00058 /**
00059   Read BufferSize bytes from Lba into Buffer.
00060 
00061   @param  This       Indicates a pointer to the calling context.
00062   @param  MediaId    Id of the media, changes every time the media is replaced.
00063   @param  Lba        The starting Logical Block Address to read from
00064   @param  BufferSize Size of Buffer, must be a multiple of device block size.
00065   @param  Buffer     A pointer to the destination buffer for the data. The caller is
00066                      responsible for either having implicit or explicit ownership of the buffer.
00067 
00068   @retval EFI_SUCCESS           The data was read correctly from the device.
00069   @retval EFI_DEVICE_ERROR      The device reported an error while performing the read.
00070   @retval EFI_NO_MEDIA          There is no media in the device.
00071   @retval EFI_MEDIA_CHANGED     The MediaId does not matched the current device.
00072   @retval EFI_BAD_BUFFER_SIZE   The Buffer was not a multiple of the block size of the device.
00073   @retval EFI_INVALID_PARAMETER The read request contains LBAs that are not valid,
00074                                 or the buffer is not on proper alignment.
00075 
00076 **/
00077 typedef
00078 EFI_STATUS
00079 (EFIAPI *EFI_BLOCK_READ)(
00080   IN EFI_BLOCK_IO_PROTOCOL          *This,
00081   IN UINT32                         MediaId,
00082   IN EFI_LBA                        Lba,
00083   IN UINTN                          BufferSize,
00084   OUT VOID                          *Buffer
00085   );
00086 
00087 /**
00088   Write BufferSize bytes from Lba into Buffer.
00089 
00090   @param  This       Indicates a pointer to the calling context.
00091   @param  MediaId    The media ID that the write request is for.
00092   @param  Lba        The starting logical block address to be written. The caller is
00093                      responsible for writing to only legitimate locations.
00094   @param  BufferSize Size of Buffer, must be a multiple of device block size.
00095   @param  Buffer     A pointer to the source buffer for the data.
00096 
00097   @retval EFI_SUCCESS           The data was written correctly to the device.
00098   @retval EFI_WRITE_PROTECTED   The device can not be written to.
00099   @retval EFI_DEVICE_ERROR      The device reported an error while performing the write.
00100   @retval EFI_NO_MEDIA          There is no media in the device.
00101   @retval EFI_MEDIA_CHNAGED     The MediaId does not matched the current device.
00102   @retval EFI_BAD_BUFFER_SIZE   The Buffer was not a multiple of the block size of the device.
00103   @retval EFI_INVALID_PARAMETER The write request contains LBAs that are not valid,
00104                                 or the buffer is not on proper alignment.
00105 
00106 **/
00107 typedef
00108 EFI_STATUS
00109 (EFIAPI *EFI_BLOCK_WRITE)(
00110   IN EFI_BLOCK_IO_PROTOCOL          *This,
00111   IN UINT32                         MediaId,
00112   IN EFI_LBA                        Lba,
00113   IN UINTN                          BufferSize,
00114   IN VOID                           *Buffer
00115   );
00116 
00117 /**
00118   Flush the Block Device.
00119 
00120   @param  This              Indicates a pointer to the calling context.
00121 
00122   @retval EFI_SUCCESS       All outstanding data was written to the device
00123   @retval EFI_DEVICE_ERROR  The device reported an error while writting back the data
00124   @retval EFI_NO_MEDIA      There is no media in the device.
00125 
00126 **/
00127 typedef
00128 EFI_STATUS
00129 (EFIAPI *EFI_BLOCK_FLUSH)(
00130   IN EFI_BLOCK_IO_PROTOCOL  *This
00131   );
00132 
00133 /**
00134   Block IO read only mode data and updated only via members of BlockIO
00135 **/
00136 typedef struct {
00137   ///
00138   /// The curent media Id. If the media changes, this value is changed.
00139   ///
00140   UINT32  MediaId;
00141 
00142   ///
00143   /// TRUE if the media is removable; otherwise, FALSE.
00144   ///
00145   BOOLEAN RemovableMedia;
00146 
00147   ///
00148   /// TRUE if there is a media currently present in the device;
00149   /// othersise, FALSE. THis field shows the media present status
00150   /// as of the most recent ReadBlocks() or WriteBlocks() call.
00151   ///
00152   BOOLEAN MediaPresent;
00153 
00154   ///
00155   /// TRUE if LBA 0 is the first block of a partition; otherwise
00156   /// FALSE. For media with only one partition this would be TRUE.
00157   ///
00158   BOOLEAN LogicalPartition;
00159 
00160   ///
00161   /// TRUE if the media is marked read-only otherwise, FALSE.
00162   /// This field shows the read-only status as of the most recent WriteBlocks () call.
00163   ///
00164   BOOLEAN ReadOnly;
00165 
00166   ///
00167   /// TRUE if the WriteBlock () function caches write data.
00168   ///
00169   BOOLEAN WriteCaching;
00170 
00171   ///
00172   /// The intrinsic block size of the device. If the media changes, then
00173   /// this field is updated.
00174   ///
00175   UINT32  BlockSize;
00176 
00177   ///
00178   /// Supplies the alignment requirement for any buffer to read or write block(s).
00179   ///
00180   UINT32  IoAlign;
00181 
00182   ///
00183   /// The last logical block address on the device.
00184   /// If the media changes, then this field is updated.
00185   ///
00186   EFI_LBA LastBlock;
00187 
00188   ///
00189   /// Only present if EFI_BLOCK_IO_PROTOCOL.Revision is greater than or equal to
00190   /// EFI_BLOCK_IO_PROTOCOL_REVISION2. Returns the first LBA is aligned to
00191   /// a physical block boundary.
00192   ///
00193   EFI_LBA LowestAlignedLba;
00194 
00195   ///
00196   /// Only present if EFI_BLOCK_IO_PROTOCOL.Revision is greater than or equal to
00197   /// EFI_BLOCK_IO_PROTOCOL_REVISION2. Returns the number of logical blocks
00198   /// per physical block.
00199   ///
00200   UINT32 LogicalBlocksPerPhysicalBlock;
00201 
00202   ///
00203   /// Only present if EFI_BLOCK_IO_PROTOCOL.Revision is greater than or equal to
00204   /// EFI_BLOCK_IO_PROTOCOL_REVISION3. Returns the optimal transfer length
00205   /// granularity as a number of logical blocks.
00206   ///
00207   UINT32 OptimalTransferLengthGranularity;
00208 } EFI_BLOCK_IO_MEDIA;
00209 
00210 #define EFI_BLOCK_IO_PROTOCOL_REVISION  0x00010000
00211 #define EFI_BLOCK_IO_PROTOCOL_REVISION2 0x00020001
00212 #define EFI_BLOCK_IO_PROTOCOL_REVISION3 0x00020031
00213 
00214 ///
00215 /// Revision defined in EFI1.1.
00216 ///
00217 #define EFI_BLOCK_IO_INTERFACE_REVISION   EFI_BLOCK_IO_PROTOCOL_REVISION
00218 
00219 ///
00220 ///  This protocol provides control over block devices.
00221 ///
00222 struct _EFI_BLOCK_IO_PROTOCOL {
00223   ///
00224   /// The revision to which the block IO interface adheres. All future
00225   /// revisions must be backwards compatible. If a future version is not
00226   /// back wards compatible, it is not the same GUID.
00227   ///
00228   UINT64              Revision;
00229   ///
00230   /// Pointer to the EFI_BLOCK_IO_MEDIA data for this device.
00231   ///
00232   EFI_BLOCK_IO_MEDIA  *Media;
00233 
00234   EFI_BLOCK_RESET     Reset;
00235   EFI_BLOCK_READ      ReadBlocks;
00236   EFI_BLOCK_WRITE     WriteBlocks;
00237   EFI_BLOCK_FLUSH     FlushBlocks;
00238 
00239 };
00240 
00241 extern EFI_GUID gEfiBlockIoProtocolGuid;
00242 
00243 #endif