1 /** @file 2 The EFI_SD_MMC_PASS_THRU_PROTOCOL provides the ability to send SD/MMC Commands 3 to any SD/MMC device attached to the SD compatible pci host controller. 4 5 Copyright (c) 2015, Intel Corporation. All rights reserved.<BR> 6 SPDX-License-Identifier: BSD-2-Clause-Patent 7 8 **/ 9 10 #ifndef __SD_MMC_PASS_THRU_H__ 11 #define __SD_MMC_PASS_THRU_H__ 12 13 #define EFI_SD_MMC_PASS_THRU_PROTOCOL_GUID \ 14 { \ 15 0x716ef0d9, 0xff83, 0x4f69, {0x81, 0xe9, 0x51, 0x8b, 0xd3, 0x9a, 0x8e, 0x70 } \ 16 } 17 18 typedef struct _EFI_SD_MMC_PASS_THRU_PROTOCOL EFI_SD_MMC_PASS_THRU_PROTOCOL; 19 20 typedef enum { 21 SdMmcCommandTypeBc, // Broadcast commands, no response 22 SdMmcCommandTypeBcr, // Broadcast commands with response 23 SdMmcCommandTypeAc, // Addressed(point-to-point) commands 24 SdMmcCommandTypeAdtc // Addressed(point-to-point) data transfer commands 25 } EFI_SD_MMC_COMMAND_TYPE; 26 27 typedef enum { 28 SdMmcResponseTypeR1, 29 SdMmcResponseTypeR1b, 30 SdMmcResponseTypeR2, 31 SdMmcResponseTypeR3, 32 SdMmcResponseTypeR4, 33 SdMmcResponseTypeR5, 34 SdMmcResponseTypeR5b, 35 SdMmcResponseTypeR6, 36 SdMmcResponseTypeR7 37 } EFI_SD_MMC_RESPONSE_TYPE; 38 39 typedef struct _EFI_SD_MMC_COMMAND_BLOCK { 40 UINT16 CommandIndex; 41 UINT32 CommandArgument; 42 UINT32 CommandType; // One of the EFI_SD_MMC_COMMAND_TYPE values 43 UINT32 ResponseType; // One of the EFI_SD_MMC_RESPONSE_TYPE values 44 } EFI_SD_MMC_COMMAND_BLOCK; 45 46 typedef struct _EFI_SD_MMC_STATUS_BLOCK { 47 UINT32 Resp0; 48 UINT32 Resp1; 49 UINT32 Resp2; 50 UINT32 Resp3; 51 } EFI_SD_MMC_STATUS_BLOCK; 52 53 typedef struct _EFI_SD_MMC_PASS_THRU_COMMAND_PACKET { 54 UINT64 Timeout; 55 EFI_SD_MMC_COMMAND_BLOCK *SdMmcCmdBlk; 56 EFI_SD_MMC_STATUS_BLOCK *SdMmcStatusBlk; 57 VOID *InDataBuffer; 58 VOID *OutDataBuffer; 59 UINT32 InTransferLength; 60 UINT32 OutTransferLength; 61 EFI_STATUS TransactionStatus; 62 } EFI_SD_MMC_PASS_THRU_COMMAND_PACKET; 63 64 /** 65 Sends SD command to an SD card that is attached to the SD controller. 66 67 The PassThru() function sends the SD command specified by Packet to the SD card 68 specified by Slot. 69 70 If Packet is successfully sent to the SD card, then EFI_SUCCESS is returned. 71 72 If a device error occurs while sending the Packet, then EFI_DEVICE_ERROR is returned. 73 74 If Slot is not in a valid range for the SD controller, then EFI_INVALID_PARAMETER 75 is returned. 76 77 If Packet defines a data command but both InDataBuffer and OutDataBuffer are NULL, 78 EFI_INVALID_PARAMETER is returned. 79 80 @param[in] This A pointer to the EFI_SD_MMC_PASS_THRU_PROTOCOL instance. 81 @param[in] Slot The slot number of the SD card to send the command to. 82 @param[in,out] Packet A pointer to the SD command data structure. 83 @param[in] Event If Event is NULL, blocking I/O is performed. If Event is 84 not NULL, then nonblocking I/O is performed, and Event 85 will be signaled when the Packet completes. 86 87 @retval EFI_SUCCESS The SD Command Packet was sent by the host. 88 @retval EFI_DEVICE_ERROR A device error occurred while attempting to send the SD 89 command Packet. 90 @retval EFI_INVALID_PARAMETER Packet, Slot, or the contents of the Packet is invalid. 91 @retval EFI_INVALID_PARAMETER Packet defines a data command but both InDataBuffer and 92 OutDataBuffer are NULL. 93 @retval EFI_NO_MEDIA SD Device not present in the Slot. 94 @retval EFI_UNSUPPORTED The command described by the SD Command Packet is not 95 supported by the host controller. 96 @retval EFI_BAD_BUFFER_SIZE The InTransferLength or OutTransferLength exceeds the 97 limit supported by SD card ( i.e. if the number of bytes 98 exceed the Last LBA). 99 100 **/ 101 typedef 102 EFI_STATUS 103 (EFIAPI *EFI_SD_MMC_PASS_THRU_PASSTHRU) ( 104 IN EFI_SD_MMC_PASS_THRU_PROTOCOL *This, 105 IN UINT8 Slot, 106 IN OUT EFI_SD_MMC_PASS_THRU_COMMAND_PACKET *Packet, 107 IN EFI_EVENT Event OPTIONAL 108 ); 109 110 /** 111 Used to retrieve next slot numbers supported by the SD controller. The function 112 returns information about all available slots (populated or not-populated). 113 114 The GetNextSlot() function retrieves the next slot number on an SD controller. 115 If on input Slot is 0xFF, then the slot number of the first slot on the SD controller 116 is returned. 117 118 If Slot is a slot number that was returned on a previous call to GetNextSlot(), then 119 the slot number of the next slot on the SD controller is returned. 120 121 If Slot is not 0xFF and Slot was not returned on a previous call to GetNextSlot(), 122 EFI_INVALID_PARAMETER is returned. 123 124 If Slot is the slot number of the last slot on the SD controller, then EFI_NOT_FOUND 125 is returned. 126 127 @param[in] This A pointer to the EFI_SD_MMMC_PASS_THRU_PROTOCOL instance. 128 @param[in,out] Slot On input, a pointer to a slot number on the SD controller. 129 On output, a pointer to the next slot number on the SD controller. 130 An input value of 0xFF retrieves the first slot number on the SD 131 controller. 132 133 @retval EFI_SUCCESS The next slot number on the SD controller was returned in Slot. 134 @retval EFI_NOT_FOUND There are no more slots on this SD controller. 135 @retval EFI_INVALID_PARAMETER Slot is not 0xFF and Slot was not returned on a previous call 136 to GetNextSlot(). 137 138 **/ 139 typedef 140 EFI_STATUS 141 (EFIAPI *EFI_SD_MMC_PASS_THRU_GET_NEXT_SLOT) ( 142 IN EFI_SD_MMC_PASS_THRU_PROTOCOL *This, 143 IN OUT UINT8 *Slot 144 ); 145 146 /** 147 Used to allocate and build a device path node for an SD card on the SD controller. 148 149 The BuildDevicePath() function allocates and builds a single device node for the SD 150 card specified by Slot. 151 152 If the SD card specified by Slot is not present on the SD controller, then EFI_NOT_FOUND 153 is returned. 154 155 If DevicePath is NULL, then EFI_INVALID_PARAMETER is returned. 156 157 If there are not enough resources to allocate the device path node, then EFI_OUT_OF_RESOURCES 158 is returned. 159 160 Otherwise, DevicePath is allocated with the boot service AllocatePool(), the contents of 161 DevicePath are initialized to describe the SD card specified by Slot, and EFI_SUCCESS is 162 returned. 163 164 @param[in] This A pointer to the EFI_SD_MMMC_PASS_THRU_PROTOCOL instance. 165 @param[in] Slot Specifies the slot number of the SD card for which a device 166 path node is to be allocated and built. 167 @param[out] DevicePath A pointer to a single device path node that describes the SD 168 card specified by Slot. This function is responsible for 169 allocating the buffer DevicePath with the boot service 170 AllocatePool(). It is the caller's responsibility to free 171 DevicePath when the caller is finished with DevicePath. 172 173 @retval EFI_SUCCESS The device path node that describes the SD card specified by 174 Slot was allocated and returned in DevicePath. 175 @retval EFI_NOT_FOUND The SD card specified by Slot does not exist on the SD controller. 176 @retval EFI_INVALID_PARAMETER DevicePath is NULL. 177 @retval EFI_OUT_OF_RESOURCES There are not enough resources to allocate DevicePath. 178 179 **/ 180 typedef 181 EFI_STATUS 182 (EFIAPI *EFI_SD_MMC_PASS_THRU_BUILD_DEVICE_PATH) ( 183 IN EFI_SD_MMC_PASS_THRU_PROTOCOL *This, 184 IN UINT8 Slot, 185 OUT EFI_DEVICE_PATH_PROTOCOL **DevicePath 186 ); 187 188 /** 189 This function retrieves an SD card slot number based on the input device path. 190 191 The GetSlotNumber() function retrieves slot number for the SD card specified by 192 the DevicePath node. If DevicePath is NULL, EFI_INVALID_PARAMETER is returned. 193 194 If DevicePath is not a device path node type that the SD Pass Thru driver supports, 195 EFI_UNSUPPORTED is returned. 196 197 @param[in] This A pointer to the EFI_SD_MMC_PASS_THRU_PROTOCOL instance. 198 @param[in] DevicePath A pointer to the device path node that describes a SD 199 card on the SD controller. 200 @param[out] Slot On return, points to the slot number of an SD card on 201 the SD controller. 202 203 @retval EFI_SUCCESS SD card slot number is returned in Slot. 204 @retval EFI_INVALID_PARAMETER Slot or DevicePath is NULL. 205 @retval EFI_UNSUPPORTED DevicePath is not a device path node type that the SD 206 Pass Thru driver supports. 207 208 **/ 209 typedef 210 EFI_STATUS 211 (EFIAPI *EFI_SD_MMC_PASS_THRU_GET_SLOT_NUMBER) ( 212 IN EFI_SD_MMC_PASS_THRU_PROTOCOL *This, 213 IN EFI_DEVICE_PATH_PROTOCOL *DevicePath, 214 OUT UINT8 *Slot 215 ); 216 217 /** 218 Resets an SD card that is connected to the SD controller. 219 220 The ResetDevice() function resets the SD card specified by Slot. 221 222 If this SD controller does not support a device reset operation, EFI_UNSUPPORTED is 223 returned. 224 225 If Slot is not in a valid slot number for this SD controller, EFI_INVALID_PARAMETER 226 is returned. 227 228 If the device reset operation is completed, EFI_SUCCESS is returned. 229 230 @param[in] This A pointer to the EFI_SD_MMC_PASS_THRU_PROTOCOL instance. 231 @param[in] Slot Specifies the slot number of the SD card to be reset. 232 233 @retval EFI_SUCCESS The SD card specified by Slot was reset. 234 @retval EFI_UNSUPPORTED The SD controller does not support a device reset operation. 235 @retval EFI_INVALID_PARAMETER Slot number is invalid. 236 @retval EFI_NO_MEDIA SD Device not present in the Slot. 237 @retval EFI_DEVICE_ERROR The reset command failed due to a device error 238 239 **/ 240 typedef 241 EFI_STATUS 242 (EFIAPI *EFI_SD_MMC_PASS_THRU_RESET_DEVICE) ( 243 IN EFI_SD_MMC_PASS_THRU_PROTOCOL *This, 244 IN UINT8 Slot 245 ); 246 247 struct _EFI_SD_MMC_PASS_THRU_PROTOCOL { 248 UINT32 IoAlign; 249 EFI_SD_MMC_PASS_THRU_PASSTHRU PassThru; 250 EFI_SD_MMC_PASS_THRU_GET_NEXT_SLOT GetNextSlot; 251 EFI_SD_MMC_PASS_THRU_BUILD_DEVICE_PATH BuildDevicePath; 252 EFI_SD_MMC_PASS_THRU_GET_SLOT_NUMBER GetSlotNumber; 253 EFI_SD_MMC_PASS_THRU_RESET_DEVICE ResetDevice; 254 }; 255 256 extern EFI_GUID gEfiSdMmcPassThruProtocolGuid; 257 258 #endif 259