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