MdePkg/Include/Protocol/SdMmcPassThru.h

   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[in,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   IN 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