EmulatorPkg/Include/Protocol/EmuBlockIo.h

   1 /** @file
   2   Emu Block IO2 protocol as defined in the UEFI 2.3.1 specification.
   3
   4   The Block IO2 protocol defines an extension to the Block IO protocol which
   5   enables the ability to read and write data at a block level in a non-blocking
   6   manner.
   7
   8   Copyright (c) 2011, Intel Corporation. All rights reserved.<BR>
   9   This program and the accompanying materials
  10   are licensed and made available under the terms and conditions of the BSD License
  11   which accompanies this distribution.  The full text of the license may be found at
  12   http://opensource.org/licenses/bsd-license.php
  13
  14   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  15   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  16
  17 **/
  18
  19 #ifndef __EMU_BLOCK_IO_H__
  20 #define __EMU_BLOCK_IO_H__
  21
  22 #include <Protocol/BlockIo.h>
  23 #include <Protocol/BlockIo2.h>
  24
  25 #define EMU_BLOCK_IO_PROTOCOL_GUID \
  26 { 0x6888A4AE, 0xAFCE, 0xE84B, { 0x91, 0x02, 0xF7, 0xB9, 0xDA, 0xE6, 0xA0, 0x30 } }
  27
  28 typedef struct _EMU_BLOCK_IO_PROTOCOL   EMU_BLOCK_IO_PROTOCOL;
  29
  30
  31
  32 /**
  33   Reset the block device hardware.
  34
  35   @param[in]  This                 Indicates a pointer to the calling context.
  36   @param[in]  ExtendedVerification Indicates that the driver may perform a more
  37                                    exhausive verfication operation of the device
  38                                    during reset.
  39
  40   @retval EFI_SUCCESS          The device was reset.
  41   @retval EFI_DEVICE_ERROR     The device is not functioning properly and could
  42                                not be reset.
  43
  44 **/
  45 typedef
  46 EFI_STATUS
  47 (EFIAPI *EMU_BLOCK_RESET) (
  48   IN EMU_BLOCK_IO_PROTOCOL   *This,
  49   IN BOOLEAN                 ExtendedVerification
  50   );
  51
  52 /**
  53   Read BufferSize bytes from Lba into Buffer.
  54
  55   This function reads the requested number of blocks from the device. All the
  56   blocks are read, or an error is returned.
  57   If EFI_DEVICE_ERROR, EFI_NO_MEDIA,_or EFI_MEDIA_CHANGED is returned and
  58   non-blocking I/O is being used, the Event associated with this request will
  59   not be signaled.
  60
  61   @param[in]       This       Indicates a pointer to the calling context.
  62   @param[in]       MediaId    Id of the media, changes every time the media is
  63                               replaced.
  64   @param[in]       Lba        The starting Logical Block Address to read from.
  65   @param[in, out]  Token            A pointer to the token associated with the transaction.
  66   @param[in]       BufferSize Size of Buffer, must be a multiple of device block size.
  67   @param[out]      Buffer     A pointer to the destination buffer for the data. The
  68                               caller is responsible for either having implicit or
  69                               explicit ownership of the buffer.
  70
  71   @retval EFI_SUCCESS           The read request was queued if Token->Event is
  72                                 not NULL.The data was read correctly from the
  73                                 device if the Token->Event is NULL.
  74   @retval EFI_DEVICE_ERROR      The device reported an error while performing
  75                                 the read.
  76   @retval EFI_NO_MEDIA          There is no media in the device.
  77   @retval EFI_MEDIA_CHANGED     The MediaId is not for the current media.
  78   @retval EFI_BAD_BUFFER_SIZE   The BufferSize parameter is not a multiple of the
  79                                 intrinsic block size of the device.
  80   @retval EFI_INVALID_PARAMETER The read request contains LBAs that are not valid,
  81                                 or the buffer is not on proper alignment.
  82   @retval EFI_OUT_OF_RESOURCES  The request could not be completed due to a lack
  83                                 of resources.
  84 **/
  85 typedef
  86 EFI_STATUS
  87 (EFIAPI *EMU_BLOCK_READ) (
  88   IN     EMU_BLOCK_IO_PROTOCOL  *This,
  89   IN     UINT32                 MediaId,
  90   IN     EFI_LBA                LBA,
  91   IN OUT EFI_BLOCK_IO2_TOKEN    *Token,
  92   IN     UINTN                  BufferSize,
  93      OUT VOID                   *Buffer
  94   );
  95
  96 /**
  97   Write BufferSize bytes from Lba into Buffer.
  98
  99   This function writes the requested number of blocks to the device. All blocks
 100   are written, or an error is returned.If EFI_DEVICE_ERROR, EFI_NO_MEDIA,
 101   EFI_WRITE_PROTECTED or EFI_MEDIA_CHANGED is returned and non-blocking I/O is
 102   being used, the Event associated with this request will not be signaled.
 103
 104   @param[in]       This       Indicates a pointer to the calling context.
 105   @param[in]       MediaId    The media ID that the write request is for.
 106   @param[in]       Lba        The starting logical block address to be written. The
 107                               caller is responsible for writing to only legitimate
 108                               locations.
 109   @param[in, out]  Token      A pointer to the token associated with the transaction.
 110   @param[in]       BufferSize Size of Buffer, must be a multiple of device block size.
 111   @param[in]       Buffer     A pointer to the source buffer for the data.
 112
 113   @retval EFI_SUCCESS           The write request was queued if Event is not NULL.
 114                                 The data was written correctly to the device if
 115                                 the Event is NULL.
 116   @retval EFI_WRITE_PROTECTED   The device can not be written to.
 117   @retval EFI_NO_MEDIA          There is no media in the device.
 118   @retval EFI_MEDIA_CHNAGED     The MediaId does not matched the current device.
 119   @retval EFI_DEVICE_ERROR      The device reported an error while performing the write.
 120   @retval EFI_BAD_BUFFER_SIZE   The Buffer was not a multiple of the block size of the device.
 121   @retval EFI_INVALID_PARAMETER The write request contains LBAs that are not valid,
 122                                 or the buffer is not on proper alignment.
 123   @retval EFI_OUT_OF_RESOURCES  The request could not be completed due to a lack
 124                                 of resources.
 125
 126 **/
 127 typedef
 128 EFI_STATUS
 129 (EFIAPI *EMU_BLOCK_WRITE) (
 130   IN     EMU_BLOCK_IO_PROTOCOL  *This,
 131   IN     UINT32                 MediaId,
 132   IN     EFI_LBA                LBA,
 133   IN OUT EFI_BLOCK_IO2_TOKEN    *Token,
 134   IN     UINTN                  BufferSize,
 135   IN     VOID                   *Buffer
 136   );
 137
 138 /**
 139   Flush the Block Device.
 140
 141   If EFI_DEVICE_ERROR, EFI_NO_MEDIA,_EFI_WRITE_PROTECTED or EFI_MEDIA_CHANGED
 142   is returned and non-blocking I/O is being used, the Event associated with
 143   this request will not be signaled.
 144
 145   @param[in]      This     Indicates a pointer to the calling context.
 146   @param[in,out]  Token    A pointer to the token associated with the transaction
 147
 148   @retval EFI_SUCCESS          The flush request was queued if Event is not NULL.
 149                                All outstanding data was written correctly to the
 150                                device if the Event is NULL.
 151   @retval EFI_DEVICE_ERROR     The device reported an error while writting back
 152                                the data.
 153   @retval EFI_WRITE_PROTECTED  The device cannot be written to.
 154   @retval EFI_NO_MEDIA         There is no media in the device.
 155   @retval EFI_MEDIA_CHANGED    The MediaId is not for the current media.
 156   @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack
 157                                of resources.
 158
 159 **/
 160 typedef
 161 EFI_STATUS
 162 (EFIAPI *EMU_BLOCK_FLUSH) (
 163   IN     EMU_BLOCK_IO_PROTOCOL    *This,
 164   IN OUT EFI_BLOCK_IO2_TOKEN      *Token
 165   );
 166
 167
 168 typedef
 169 EFI_STATUS
 170 (EFIAPI *EMU_BLOCK_CREATE_MAPPING) (
 171   IN     EMU_BLOCK_IO_PROTOCOL    *This,
 172   IN     EFI_BLOCK_IO_MEDIA       *Media
 173   );
 174
 175
 176 ///
 177 ///  The Block I/O2 protocol defines an extension to the Block I/O protocol which
 178 ///  enables the ability to read and write data at a block level in a non-blocking
 179 //   manner.
 180 ///
 181 struct _EMU_BLOCK_IO_PROTOCOL  {
 182   EMU_BLOCK_RESET           Reset;
 183   EMU_BLOCK_READ            ReadBlocks;
 184   EMU_BLOCK_WRITE           WriteBlocks;
 185   EMU_BLOCK_FLUSH           FlushBlocks;
 186   EMU_BLOCK_CREATE_MAPPING  CreateMapping;
 187 };
 188
 189 extern EFI_GUID gEmuBlockIoProtocolGuid;
 190
 191 #endif
 192