Ronak Kanabar | 1ae366f | 2023-06-07 01:21:56 +0530 | [diff] [blame^] | 1 | /** @file |
| 2 | Provides the services required to access a block I/O 2 device during PEI recovery |
| 3 | boot mode. |
| 4 | |
| 5 | Copyright (c) 2015, Intel Corporation. All rights reserved.<BR> |
| 6 | SPDX-License-Identifier: BSD-2-Clause-Patent |
| 7 | |
| 8 | @par Revision Reference: |
| 9 | This PPI is defined in UEFI Platform Initialization Specification 1.4 Volume 1: |
| 10 | Pre-EFI Initialization Core Interface. |
| 11 | |
| 12 | **/ |
| 13 | |
| 14 | #ifndef _PEI_BLOCK_IO2_H_ |
| 15 | #define _PEI_BLOCK_IO2_H_ |
| 16 | |
| 17 | #include <Ppi/BlockIo.h> |
| 18 | #include <Protocol/DevicePath.h> |
| 19 | |
| 20 | /// |
| 21 | /// Global ID for EFI_PEI_RECOVERY_BLOCK_IO2_PPI |
| 22 | /// |
| 23 | #define EFI_PEI_RECOVERY_BLOCK_IO2_PPI_GUID \ |
| 24 | { \ |
| 25 | 0x26cc0fad, 0xbeb3, 0x478a, { 0x91, 0xb2, 0xc, 0x18, 0x8f, 0x72, 0x61, 0x98 } \ |
| 26 | } |
| 27 | |
| 28 | /// |
| 29 | /// The forward declaration for EFI_PEI_RECOVERY_BLOCK_IO_PPI. |
| 30 | /// |
| 31 | typedef struct _EFI_PEI_RECOVERY_BLOCK_IO2_PPI EFI_PEI_RECOVERY_BLOCK_IO2_PPI; |
| 32 | |
| 33 | #define EFI_PEI_RECOVERY_BLOCK_IO2_PPI_REVISION 0x00010000 |
| 34 | |
| 35 | typedef struct { |
| 36 | /// |
| 37 | /// A type of interface that the device being referenced by DeviceIndex is |
| 38 | /// attached to. This field re-uses Messaging Device Path Node sub-type values |
| 39 | /// as defined by Section 9.3.5 Messaging Device Path of UEFI Specification. |
| 40 | /// When more than one sub-type is associated with the interface, sub-type with |
| 41 | /// the smallest number must be used. |
| 42 | /// |
| 43 | UINT8 InterfaceType; |
| 44 | /// |
| 45 | /// A flag that indicates if media is removable. |
| 46 | /// |
| 47 | BOOLEAN RemovableMedia; |
| 48 | /// |
| 49 | /// A flag that indicates if media is present. This flag is always set for |
| 50 | /// non-removable media devices. |
| 51 | /// |
| 52 | BOOLEAN MediaPresent; |
| 53 | /// |
| 54 | /// A flag that indicates if media is read-only. |
| 55 | /// |
| 56 | BOOLEAN ReadOnly; |
| 57 | /// |
| 58 | /// The size of a logical block in bytes. |
| 59 | /// |
| 60 | UINT32 BlockSize; |
| 61 | /// |
| 62 | /// The last logical block that the device supports. |
| 63 | /// |
| 64 | EFI_PEI_LBA LastBlock; |
| 65 | } EFI_PEI_BLOCK_IO2_MEDIA; |
| 66 | |
| 67 | /** |
| 68 | Gets the count of block I/O devices that one specific block driver detects. |
| 69 | |
| 70 | This function is used for getting the count of block I/O devices that one |
| 71 | specific block driver detects. To the PEI ATAPI driver, it returns the number |
| 72 | of all the detected ATAPI devices it detects during the enumeration process. |
| 73 | To the PEI legacy floppy driver, it returns the number of all the legacy |
| 74 | devices it finds during its enumeration process. If no device is detected, |
| 75 | then the function will return zero. |
| 76 | |
| 77 | @param[in] PeiServices General-purpose services that are available |
| 78 | to every PEIM. |
| 79 | @param[in] This Indicates the EFI_PEI_RECOVERY_BLOCK_IO2_PPI |
| 80 | instance. |
| 81 | @param[out] NumberBlockDevices The number of block I/O devices discovered. |
| 82 | |
| 83 | @retval EFI_SUCCESS The operation performed successfully. |
| 84 | |
| 85 | **/ |
| 86 | typedef |
| 87 | EFI_STATUS |
| 88 | (EFIAPI *EFI_PEI_GET_NUMBER_BLOCK_DEVICES2)( |
| 89 | IN EFI_PEI_SERVICES **PeiServices, |
| 90 | IN EFI_PEI_RECOVERY_BLOCK_IO2_PPI *This, |
| 91 | OUT UINTN *NumberBlockDevices |
| 92 | ); |
| 93 | |
| 94 | /** |
| 95 | Gets a block device's media information. |
| 96 | |
| 97 | This function will provide the caller with the specified block device's media |
| 98 | information. If the media changes, calling this function will update the media |
| 99 | information accordingly. |
| 100 | |
| 101 | @param[in] PeiServices General-purpose services that are available to every |
| 102 | PEIM |
| 103 | @param[in] This Indicates the EFI_PEI_RECOVERY_BLOCK_IO2_PPI instance. |
| 104 | @param[in] DeviceIndex Specifies the block device to which the function wants |
| 105 | to talk. Because the driver that implements Block I/O |
| 106 | PPIs will manage multiple block devices, the PPIs that |
| 107 | want to talk to a single device must specify the |
| 108 | device index that was assigned during the enumeration |
| 109 | process. This index is a number from one to |
| 110 | NumberBlockDevices. |
| 111 | @param[out] MediaInfo The media information of the specified block media. |
| 112 | The caller is responsible for the ownership of this |
| 113 | data structure. |
| 114 | |
| 115 | @par Note: |
| 116 | The MediaInfo structure describes an enumeration of possible block device |
| 117 | types. This enumeration exists because no device paths are actually passed |
| 118 | across interfaces that describe the type or class of hardware that is publishing |
| 119 | the block I/O interface. This enumeration will allow for policy decisions |
| 120 | in the Recovery PEIM, such as "Try to recover from legacy floppy first, |
| 121 | LS-120 second, CD-ROM third." If there are multiple partitions abstracted |
| 122 | by a given device type, they should be reported in ascending order; this |
| 123 | order also applies to nested partitions, such as legacy MBR, where the |
| 124 | outermost partitions would have precedence in the reporting order. The |
| 125 | same logic applies to systems such as IDE that have precedence relationships |
| 126 | like "Master/Slave" or "Primary/Secondary". The master device should be |
| 127 | reported first, the slave second. |
| 128 | |
| 129 | @retval EFI_SUCCESS Media information about the specified block device |
| 130 | was obtained successfully. |
| 131 | @retval EFI_DEVICE_ERROR Cannot get the media information due to a hardware |
| 132 | error. |
| 133 | |
| 134 | **/ |
| 135 | typedef |
| 136 | EFI_STATUS |
| 137 | (EFIAPI *EFI_PEI_GET_DEVICE_MEDIA_INFORMATION2)( |
| 138 | IN EFI_PEI_SERVICES **PeiServices, |
| 139 | IN EFI_PEI_RECOVERY_BLOCK_IO2_PPI *This, |
| 140 | IN UINTN DeviceIndex, |
| 141 | OUT EFI_PEI_BLOCK_IO2_MEDIA *MediaInfo |
| 142 | ); |
| 143 | |
| 144 | /** |
| 145 | Reads the requested number of blocks from the specified block device. |
| 146 | |
| 147 | The function reads the requested number of blocks from the device. All the |
| 148 | blocks are read, or an error is returned. If there is no media in the device, |
| 149 | the function returns EFI_NO_MEDIA. |
| 150 | |
| 151 | @param[in] PeiServices General-purpose services that are available to |
| 152 | every PEIM. |
| 153 | @param[in] This Indicates the EFI_PEI_RECOVERY_BLOCK_IO2_PPI instance. |
| 154 | @param[in] DeviceIndex Specifies the block device to which the function wants |
| 155 | to talk. Because the driver that implements Block I/O |
| 156 | PPIs will manage multiple block devices, PPIs that |
| 157 | want to talk to a single device must specify the device |
| 158 | index that was assigned during the enumeration process. |
| 159 | This index is a number from one to NumberBlockDevices. |
| 160 | @param[in] StartLBA The starting logical block address (LBA) to read from |
| 161 | on the device |
| 162 | @param[in] BufferSize The size of the Buffer in bytes. This number must be |
| 163 | a multiple of the intrinsic block size of the device. |
| 164 | @param[out] Buffer A pointer to the destination buffer for the data. |
| 165 | The caller is responsible for the ownership of the |
| 166 | buffer. |
| 167 | |
| 168 | @retval EFI_SUCCESS The data was read correctly from the device. |
| 169 | @retval EFI_DEVICE_ERROR The device reported an error while attempting |
| 170 | to perform the read operation. |
| 171 | @retval EFI_INVALID_PARAMETER The read request contains LBAs that are not |
| 172 | valid, or the buffer is not properly aligned. |
| 173 | @retval EFI_NO_MEDIA There is no media in the device. |
| 174 | @retval EFI_BAD_BUFFER_SIZE The BufferSize parameter is not a multiple of |
| 175 | the intrinsic block size of the device. |
| 176 | |
| 177 | **/ |
| 178 | typedef |
| 179 | EFI_STATUS |
| 180 | (EFIAPI *EFI_PEI_READ_BLOCKS2)( |
| 181 | IN EFI_PEI_SERVICES **PeiServices, |
| 182 | IN EFI_PEI_RECOVERY_BLOCK_IO2_PPI *This, |
| 183 | IN UINTN DeviceIndex, |
| 184 | IN EFI_PEI_LBA StartLBA, |
| 185 | IN UINTN BufferSize, |
| 186 | OUT VOID *Buffer |
| 187 | ); |
| 188 | |
| 189 | /// |
| 190 | /// EFI_PEI_RECOVERY_BLOCK_IO_PPI provides the services that are required |
| 191 | /// to access a block I/O device during PEI recovery boot mode. |
| 192 | /// |
| 193 | struct _EFI_PEI_RECOVERY_BLOCK_IO2_PPI { |
| 194 | /// |
| 195 | /// The revision to which the interface adheres. |
| 196 | /// All future revisions must be backwards compatible. |
| 197 | /// |
| 198 | UINT64 Revision; |
| 199 | /// |
| 200 | /// Gets the number of block I/O devices that the specific block driver manages. |
| 201 | /// |
| 202 | EFI_PEI_GET_NUMBER_BLOCK_DEVICES2 GetNumberOfBlockDevices; |
| 203 | |
| 204 | /// |
| 205 | /// Gets the specified media information. |
| 206 | /// |
| 207 | EFI_PEI_GET_DEVICE_MEDIA_INFORMATION2 GetBlockDeviceMediaInfo; |
| 208 | |
| 209 | /// |
| 210 | /// Reads the requested number of blocks from the specified block device. |
| 211 | /// |
| 212 | EFI_PEI_READ_BLOCKS2 ReadBlocks; |
| 213 | }; |
| 214 | |
| 215 | extern EFI_GUID gEfiPeiVirtualBlockIo2PpiGuid; |
| 216 | |
| 217 | #endif |