iPXE
BlockIo2.h
Go to the documentation of this file.
00001 /** @file
00002   Block IO2 protocol as defined in the UEFI 2.3.1 specification.
00003 
00004   The Block IO2 protocol defines an extension to the Block IO protocol which
00005   enables the ability to read and write data at a block level in a non-blocking
00006   manner.
00007 
00008   Copyright (c) 2011, Intel Corporation. All rights reserved.<BR>
00009   This program and the accompanying materials
00010   are licensed and made available under the terms and conditions of the BSD License
00011   which accompanies this distribution.  The full text of the license may be found at
00012   http://opensource.org/licenses/bsd-license.php
00013 
00014   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
00015   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
00016 
00017 **/
00018 
00019 #ifndef __BLOCK_IO2_H__
00020 #define __BLOCK_IO2_H__
00021 
00022 FILE_LICENCE ( BSD3 );
00023 
00024 #include <ipxe/efi/Protocol/BlockIo.h>
00025 
00026 #define EFI_BLOCK_IO2_PROTOCOL_GUID \
00027   { \
00028     0xa77b2472, 0xe282, 0x4e9f, {0xa2, 0x45, 0xc2, 0xc0, 0xe2, 0x7b, 0xbc, 0xc1} \
00029   }
00030 
00031 typedef struct _EFI_BLOCK_IO2_PROTOCOL  EFI_BLOCK_IO2_PROTOCOL;
00032 
00033 /**
00034   The struct of Block IO2 Token.
00035 **/
00036 typedef struct {
00037 
00038   ///
00039   /// If Event is NULL, then blocking I/O is performed.If Event is not NULL and
00040   /// non-blocking I/O is supported, then non-blocking I/O is performed, and
00041   /// Event will be signaled when the read request is completed.
00042   ///
00043   EFI_EVENT               Event;
00044 
00045   ///
00046   /// Defines whether or not the signaled event encountered an error.
00047   ///
00048   EFI_STATUS              TransactionStatus;
00049 } EFI_BLOCK_IO2_TOKEN;
00050 
00051 
00052 /**
00053   Reset the block device hardware.
00054 
00055   @param[in]  This                 Indicates a pointer to the calling context.
00056   @param[in]  ExtendedVerification Indicates that the driver may perform a more
00057                                    exhausive verification operation of the device
00058                                    during reset.
00059 
00060   @retval EFI_SUCCESS          The device was reset.
00061   @retval EFI_DEVICE_ERROR     The device is not functioning properly and could
00062                                not be reset.
00063 
00064 **/
00065 typedef
00066 EFI_STATUS
00067 (EFIAPI *EFI_BLOCK_RESET_EX) (
00068   IN EFI_BLOCK_IO2_PROTOCOL  *This,
00069   IN BOOLEAN                 ExtendedVerification
00070   );
00071 
00072 /**
00073   Read BufferSize bytes from Lba into Buffer.
00074 
00075   This function reads the requested number of blocks from the device. All the
00076   blocks are read, or an error is returned.
00077   If EFI_DEVICE_ERROR, EFI_NO_MEDIA,_or EFI_MEDIA_CHANGED is returned and
00078   non-blocking I/O is being used, the Event associated with this request will
00079   not be signaled.
00080 
00081   @param[in]       This       Indicates a pointer to the calling context.
00082   @param[in]       MediaId    Id of the media, changes every time the media is
00083                               replaced.
00084   @param[in]       Lba        The starting Logical Block Address to read from.
00085   @param[in, out]  Token            A pointer to the token associated with the transaction.
00086   @param[in]       BufferSize Size of Buffer, must be a multiple of device block size.
00087   @param[out]      Buffer     A pointer to the destination buffer for the data. The
00088                               caller is responsible for either having implicit or
00089                               explicit ownership of the buffer.
00090 
00091   @retval EFI_SUCCESS           The read request was queued if Token->Event is
00092                                 not NULL.The data was read correctly from the
00093                                 device if the Token->Event is NULL.
00094   @retval EFI_DEVICE_ERROR      The device reported an error while performing
00095                                 the read.
00096   @retval EFI_NO_MEDIA          There is no media in the device.
00097   @retval EFI_MEDIA_CHANGED     The MediaId is not for the current media.
00098   @retval EFI_BAD_BUFFER_SIZE   The BufferSize parameter is not a multiple of the
00099                                 intrinsic block size of the device.
00100   @retval EFI_INVALID_PARAMETER The read request contains LBAs that are not valid,
00101                                 or the buffer is not on proper alignment.
00102   @retval EFI_OUT_OF_RESOURCES  The request could not be completed due to a lack
00103                                 of resources.
00104 **/
00105 typedef
00106 EFI_STATUS
00107 (EFIAPI *EFI_BLOCK_READ_EX) (
00108   IN     EFI_BLOCK_IO2_PROTOCOL *This,
00109   IN     UINT32                 MediaId,
00110   IN     EFI_LBA                LBA,
00111   IN OUT EFI_BLOCK_IO2_TOKEN    *Token,
00112   IN     UINTN                  BufferSize,
00113      OUT VOID                  *Buffer
00114   );
00115 
00116 /**
00117   Write BufferSize bytes from Lba into Buffer.
00118 
00119   This function writes the requested number of blocks to the device. All blocks
00120   are written, or an error is returned.If EFI_DEVICE_ERROR, EFI_NO_MEDIA,
00121   EFI_WRITE_PROTECTED or EFI_MEDIA_CHANGED is returned and non-blocking I/O is
00122   being used, the Event associated with this request will not be signaled.
00123 
00124   @param[in]       This       Indicates a pointer to the calling context.
00125   @param[in]       MediaId    The media ID that the write request is for.
00126   @param[in]       Lba        The starting logical block address to be written. The
00127                               caller is responsible for writing to only legitimate
00128                               locations.
00129   @param[in, out]  Token      A pointer to the token associated with the transaction.
00130   @param[in]       BufferSize Size of Buffer, must be a multiple of device block size.
00131   @param[in]       Buffer     A pointer to the source buffer for the data.
00132 
00133   @retval EFI_SUCCESS           The write request was queued if Event is not NULL.
00134                                 The data was written correctly to the device if
00135                                 the Event is NULL.
00136   @retval EFI_WRITE_PROTECTED   The device can not be written to.
00137   @retval EFI_NO_MEDIA          There is no media in the device.
00138   @retval EFI_MEDIA_CHNAGED     The MediaId does not matched the current device.
00139   @retval EFI_DEVICE_ERROR      The device reported an error while performing the write.
00140   @retval EFI_BAD_BUFFER_SIZE   The Buffer was not a multiple of the block size of the device.
00141   @retval EFI_INVALID_PARAMETER The write request contains LBAs that are not valid,
00142                                 or the buffer is not on proper alignment.
00143   @retval EFI_OUT_OF_RESOURCES  The request could not be completed due to a lack
00144                                 of resources.
00145 
00146 **/
00147 typedef
00148 EFI_STATUS
00149 (EFIAPI *EFI_BLOCK_WRITE_EX) (
00150   IN     EFI_BLOCK_IO2_PROTOCOL  *This,
00151   IN     UINT32                 MediaId,
00152   IN     EFI_LBA                LBA,
00153   IN OUT EFI_BLOCK_IO2_TOKEN    *Token,
00154   IN     UINTN                  BufferSize,
00155   IN     VOID                   *Buffer
00156   );
00157 
00158 /**
00159   Flush the Block Device.
00160 
00161   If EFI_DEVICE_ERROR, EFI_NO_MEDIA,_EFI_WRITE_PROTECTED or EFI_MEDIA_CHANGED
00162   is returned and non-blocking I/O is being used, the Event associated with
00163   this request will not be signaled.
00164 
00165   @param[in]      This     Indicates a pointer to the calling context.
00166   @param[in,out]  Token    A pointer to the token associated with the transaction
00167 
00168   @retval EFI_SUCCESS          The flush request was queued if Event is not NULL.
00169                                All outstanding data was written correctly to the
00170                                device if the Event is NULL.
00171   @retval EFI_DEVICE_ERROR     The device reported an error while writting back
00172                                the data.
00173   @retval EFI_WRITE_PROTECTED  The device cannot be written to.
00174   @retval EFI_NO_MEDIA         There is no media in the device.
00175   @retval EFI_MEDIA_CHANGED    The MediaId is not for the current media.
00176   @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack
00177                                of resources.
00178 
00179 **/
00180 typedef
00181 EFI_STATUS
00182 (EFIAPI *EFI_BLOCK_FLUSH_EX) (
00183   IN     EFI_BLOCK_IO2_PROTOCOL   *This,
00184   IN OUT EFI_BLOCK_IO2_TOKEN      *Token
00185   );
00186 
00187 ///
00188 ///  The Block I/O2 protocol defines an extension to the Block I/O protocol which
00189 ///  enables the ability to read and write data at a block level in a non-blocking
00190 //   manner.
00191 ///
00192 struct _EFI_BLOCK_IO2_PROTOCOL {
00193   ///
00194   /// A pointer to the EFI_BLOCK_IO_MEDIA data for this device.
00195   /// Type EFI_BLOCK_IO_MEDIA is defined in BlockIo.h.
00196   ///
00197   EFI_BLOCK_IO_MEDIA      *Media;
00198 
00199   EFI_BLOCK_RESET_EX      Reset;
00200   EFI_BLOCK_READ_EX       ReadBlocksEx;
00201   EFI_BLOCK_WRITE_EX      WriteBlocksEx;
00202   EFI_BLOCK_FLUSH_EX      FlushBlocksEx;
00203 };
00204 
00205 extern EFI_GUID gEfiBlockIo2ProtocolGuid;
00206 
00207 #endif
00208