MdeModulePkg/Bus/Pci/NvmExpressPei/NvmExpressPeiBlockIo.h

   1 /** @file
   2   The NvmExpressPei driver is used to manage non-volatile memory subsystem
   3   which follows NVM Express specification at PEI phase.
   4
   5   Copyright (c) 2018, Intel Corporation. All rights reserved.<BR>
   6
   7   This program and the accompanying materials
   8   are licensed and made available under the terms and conditions
   9   of the BSD License which accompanies this distribution.  The
  10   full text of the license may be found at
  11   http://opensource.org/licenses/bsd-license.php
  12
  13   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  14   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  15
  16 **/
  17
  18 #ifndef _NVM_EXPRESS_PEI_BLOCKIO_H_
  19 #define _NVM_EXPRESS_PEI_BLOCKIO_H_
  20
  21 //
  22 // Nvme device for EFI_PEI_BLOCK_DEVICE_TYPE
  23 //
  24 #define EDKII_PEI_BLOCK_DEVICE_TYPE_NVME    7
  25
  26 #define NVME_READ_MAX_RETRY                 3
  27
  28 /**
  29   Gets the count of block I/O devices that one specific block driver detects.
  30
  31   This function is used for getting the count of block I/O devices that one
  32   specific block driver detects. If no device is detected, then the function
  33   will return zero.
  34
  35   @param[in]  PeiServices          General-purpose services that are available
  36                                    to every PEIM.
  37   @param[in]  This                 Indicates the EFI_PEI_RECOVERY_BLOCK_IO_PPI
  38                                    instance.
  39   @param[out] NumberBlockDevices   The number of block I/O devices discovered.
  40
  41   @retval     EFI_SUCCESS          The operation performed successfully.
  42
  43 **/
  44 EFI_STATUS
  45 EFIAPI
  46 NvmeBlockIoPeimGetDeviceNo (
  47   IN  EFI_PEI_SERVICES               **PeiServices,
  48   IN  EFI_PEI_RECOVERY_BLOCK_IO_PPI  *This,
  49   OUT UINTN                          *NumberBlockDevices
  50   );
  51
  52 /**
  53   Gets a block device's media information.
  54
  55   This function will provide the caller with the specified block device's media
  56   information. If the media changes, calling this function will update the media
  57   information accordingly.
  58
  59   @param[in]  PeiServices   General-purpose services that are available to every
  60                             PEIM
  61   @param[in]  This          Indicates the EFI_PEI_RECOVERY_BLOCK_IO_PPI instance.
  62   @param[in]  DeviceIndex   Specifies the block device to which the function wants
  63                             to talk. Because the driver that implements Block I/O
  64                             PPIs will manage multiple block devices, the PPIs that
  65                             want to talk to a single device must specify the
  66                             device index that was assigned during the enumeration
  67                             process. This index is a number from one to
  68                             NumberBlockDevices.
  69   @param[out] MediaInfo     The media information of the specified block media.
  70                             The caller is responsible for the ownership of this
  71                             data structure.
  72
  73   @par Note:
  74       The MediaInfo structure describes an enumeration of possible block device
  75       types.  This enumeration exists because no device paths are actually passed
  76       across interfaces that describe the type or class of hardware that is publishing
  77       the block I/O interface. This enumeration will allow for policy decisions
  78       in the Recovery PEIM, such as "Try to recover from legacy floppy first,
  79       LS-120 second, CD-ROM third." If there are multiple partitions abstracted
  80       by a given device type, they should be reported in ascending order; this
  81       order also applies to nested partitions, such as legacy MBR, where the
  82       outermost partitions would have precedence in the reporting order. The
  83       same logic applies to systems such as IDE that have precedence relationships
  84       like "Master/Slave" or "Primary/Secondary". The master device should be
  85       reported first, the slave second.
  86
  87   @retval EFI_SUCCESS        Media information about the specified block device
  88                              was obtained successfully.
  89   @retval EFI_DEVICE_ERROR   Cannot get the media information due to a hardware
  90                              error.
  91
  92 **/
  93 EFI_STATUS
  94 EFIAPI
  95 NvmeBlockIoPeimGetMediaInfo (
  96   IN  EFI_PEI_SERVICES               **PeiServices,
  97   IN  EFI_PEI_RECOVERY_BLOCK_IO_PPI  *This,
  98   IN  UINTN                          DeviceIndex,
  99   OUT EFI_PEI_BLOCK_IO_MEDIA         *MediaInfo
 100   );
 101
 102 /**
 103   Reads the requested number of blocks from the specified block device.
 104
 105   The function reads the requested number of blocks from the device. All the
 106   blocks are read, or an error is returned. If there is no media in the device,
 107   the function returns EFI_NO_MEDIA.
 108
 109   @param[in]  PeiServices   General-purpose services that are available to
 110                             every PEIM.
 111   @param[in]  This          Indicates the EFI_PEI_RECOVERY_BLOCK_IO_PPI instance.
 112   @param[in]  DeviceIndex   Specifies the block device to which the function wants
 113                             to talk. Because the driver that implements Block I/O
 114                             PPIs will manage multiple block devices, PPIs that
 115                             want to talk to a single device must specify the device
 116                             index that was assigned during the enumeration process.
 117                             This index is a number from one to NumberBlockDevices.
 118   @param[in]  StartLBA      The starting logical block address (LBA) to read from
 119                             on the device
 120   @param[in]  BufferSize    The size of the Buffer in bytes. This number must be
 121                             a multiple of the intrinsic block size of the device.
 122   @param[out] Buffer        A pointer to the destination buffer for the data.
 123                             The caller is responsible for the ownership of the
 124                             buffer.
 125
 126   @retval EFI_SUCCESS             The data was read correctly from the device.
 127   @retval EFI_DEVICE_ERROR        The device reported an error while attempting
 128                                   to perform the read operation.
 129   @retval EFI_INVALID_PARAMETER   The read request contains LBAs that are not
 130                                   valid, or the buffer is not properly aligned.
 131   @retval EFI_NO_MEDIA            There is no media in the device.
 132   @retval EFI_BAD_BUFFER_SIZE     The BufferSize parameter is not a multiple of
 133                                   the intrinsic block size of the device.
 134
 135 **/
 136 EFI_STATUS
 137 EFIAPI
 138 NvmeBlockIoPeimReadBlocks (
 139   IN  EFI_PEI_SERVICES               **PeiServices,
 140   IN  EFI_PEI_RECOVERY_BLOCK_IO_PPI  *This,
 141   IN  UINTN                          DeviceIndex,
 142   IN  EFI_PEI_LBA                    StartLBA,
 143   IN  UINTN                          BufferSize,
 144   OUT VOID                           *Buffer
 145   );
 146
 147 /**
 148   Gets the count of block I/O devices that one specific block driver detects.
 149
 150   This function is used for getting the count of block I/O devices that one
 151   specific block driver detects. If no device is detected, then the function
 152   will return zero.
 153
 154   @param[in]  PeiServices          General-purpose services that are available
 155                                    to every PEIM.
 156   @param[in]  This                 Indicates the EFI_PEI_RECOVERY_BLOCK_IO2_PPI
 157                                    instance.
 158   @param[out] NumberBlockDevices   The number of block I/O devices discovered.
 159
 160   @retval     EFI_SUCCESS          The operation performed successfully.
 161
 162 **/
 163 EFI_STATUS
 164 EFIAPI
 165 NvmeBlockIoPeimGetDeviceNo2 (
 166   IN  EFI_PEI_SERVICES                **PeiServices,
 167   IN  EFI_PEI_RECOVERY_BLOCK_IO2_PPI  *This,
 168   OUT UINTN                           *NumberBlockDevices
 169   );
 170
 171 /**
 172   Gets a block device's media information.
 173
 174   This function will provide the caller with the specified block device's media
 175   information. If the media changes, calling this function will update the media
 176   information accordingly.
 177
 178   @param[in]  PeiServices   General-purpose services that are available to every
 179                             PEIM
 180   @param[in]  This          Indicates the EFI_PEI_RECOVERY_BLOCK_IO2_PPI instance.
 181   @param[in]  DeviceIndex   Specifies the block device to which the function wants
 182                             to talk. Because the driver that implements Block I/O
 183                             PPIs will manage multiple block devices, the PPIs that
 184                             want to talk to a single device must specify the
 185                             device index that was assigned during the enumeration
 186                             process. This index is a number from one to
 187                             NumberBlockDevices.
 188   @param[out] MediaInfo     The media information of the specified block media.
 189                             The caller is responsible for the ownership of this
 190                             data structure.
 191
 192   @par Note:
 193       The MediaInfo structure describes an enumeration of possible block device
 194       types.  This enumeration exists because no device paths are actually passed
 195       across interfaces that describe the type or class of hardware that is publishing
 196       the block I/O interface. This enumeration will allow for policy decisions
 197       in the Recovery PEIM, such as "Try to recover from legacy floppy first,
 198       LS-120 second, CD-ROM third." If there are multiple partitions abstracted
 199       by a given device type, they should be reported in ascending order; this
 200       order also applies to nested partitions, such as legacy MBR, where the
 201       outermost partitions would have precedence in the reporting order. The
 202       same logic applies to systems such as IDE that have precedence relationships
 203       like "Master/Slave" or "Primary/Secondary". The master device should be
 204       reported first, the slave second.
 205
 206   @retval EFI_SUCCESS        Media information about the specified block device
 207                              was obtained successfully.
 208   @retval EFI_DEVICE_ERROR   Cannot get the media information due to a hardware
 209                              error.
 210
 211 **/
 212 EFI_STATUS
 213 EFIAPI
 214 NvmeBlockIoPeimGetMediaInfo2 (
 215   IN  EFI_PEI_SERVICES                **PeiServices,
 216   IN  EFI_PEI_RECOVERY_BLOCK_IO2_PPI  *This,
 217   IN  UINTN                           DeviceIndex,
 218   OUT EFI_PEI_BLOCK_IO2_MEDIA         *MediaInfo
 219   );
 220
 221 /**
 222   Reads the requested number of blocks from the specified block device.
 223
 224   The function reads the requested number of blocks from the device. All the
 225   blocks are read, or an error is returned. If there is no media in the device,
 226   the function returns EFI_NO_MEDIA.
 227
 228   @param[in]  PeiServices   General-purpose services that are available to
 229                             every PEIM.
 230   @param[in]  This          Indicates the EFI_PEI_RECOVERY_BLOCK_IO2_PPI instance.
 231   @param[in]  DeviceIndex   Specifies the block device to which the function wants
 232                             to talk. Because the driver that implements Block I/O
 233                             PPIs will manage multiple block devices, PPIs that
 234                             want to talk to a single device must specify the device
 235                             index that was assigned during the enumeration process.
 236                             This index is a number from one to NumberBlockDevices.
 237   @param[in]  StartLBA      The starting logical block address (LBA) to read from
 238                             on the device
 239   @param[in]  BufferSize    The size of the Buffer in bytes. This number must be
 240                             a multiple of the intrinsic block size of the device.
 241   @param[out] Buffer        A pointer to the destination buffer for the data.
 242                             The caller is responsible for the ownership of the
 243                             buffer.
 244
 245   @retval EFI_SUCCESS             The data was read correctly from the device.
 246   @retval EFI_DEVICE_ERROR        The device reported an error while attempting
 247                                   to perform the read operation.
 248   @retval EFI_INVALID_PARAMETER   The read request contains LBAs that are not
 249                                   valid, or the buffer is not properly aligned.
 250   @retval EFI_NO_MEDIA            There is no media in the device.
 251   @retval EFI_BAD_BUFFER_SIZE     The BufferSize parameter is not a multiple of
 252                                   the intrinsic block size of the device.
 253
 254 **/
 255 EFI_STATUS
 256 EFIAPI
 257 NvmeBlockIoPeimReadBlocks2 (
 258   IN  EFI_PEI_SERVICES                **PeiServices,
 259   IN  EFI_PEI_RECOVERY_BLOCK_IO2_PPI  *This,
 260   IN  UINTN                           DeviceIndex,
 261   IN  EFI_PEI_LBA                     StartLBA,
 262   IN  UINTN                           BufferSize,
 263   OUT VOID                            *Buffer
 264   );
 265
 266 #endif