MdeModulePkg/Bus/Ata/AhciPei/AhciPeiBlockIo.h

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