MdeModulePkg/Bus/Ufs/UfsPassThruDxe/UfsPassThru.h

   1 /** @file
   2
   3   Copyright (c) 2014 - 2019, Intel Corporation. All rights reserved.<BR>
   4   SPDX-License-Identifier: BSD-2-Clause-Patent
   5
   6 **/
   7
   8 #ifndef _UFS_PASS_THRU_H_
   9 #define _UFS_PASS_THRU_H_
  10
  11 #include <Uefi.h>
  12
  13 #include <Protocol/ScsiPassThruExt.h>
  14 #include <Protocol/UfsDeviceConfig.h>
  15 #include <Protocol/UfsHostController.h>
  16 #include <Protocol/UfsHostControllerPlatform.h>
  17
  18 #include <Library/DebugLib.h>
  19 #include <Library/UefiDriverEntryPoint.h>
  20 #include <Library/BaseLib.h>
  21 #include <Library/UefiLib.h>
  22 #include <Library/BaseMemoryLib.h>
  23 #include <Library/MemoryAllocationLib.h>
  24 #include <Library/UefiBootServicesTableLib.h>
  25 #include <Library/DevicePathLib.h>
  26 #include <Library/TimerLib.h>
  27
  28 #include "UfsPassThruHci.h"
  29
  30 #define UFS_PASS_THRU_SIG           SIGNATURE_32 ('U', 'F', 'S', 'P')
  31
  32 //
  33 // Lun 0~7 is for 8 common luns.
  34 // Lun 8~11 is for those 4 well known luns (Refer to UFS 2.0 spec Table 10.58 for details):
  35 //  Lun 8:  REPORT LUNS
  36 //  Lun 9:  UFS DEVICE
  37 //  Lun 10: BOOT
  38 //  Lun 11: RPMB
  39 //
  40 #define UFS_MAX_LUNS                12
  41 #define UFS_WLUN_PREFIX             0xC1
  42
  43 typedef struct {
  44   UINT8    Lun[UFS_MAX_LUNS];
  45   UINT16   BitMask:12;              // Bit 0~7 is 1/1 mapping to common luns. Bit 8~11 is 1/1 mapping to well-known luns.
  46   UINT16   Rsvd:4;
  47 } UFS_EXPOSED_LUNS;
  48
  49 //
  50 // Iterate through the double linked list. This is delete-safe.
  51 // Do not touch NextEntry
  52 //
  53 #define EFI_LIST_FOR_EACH_SAFE(Entry, NextEntry, ListHead)            \
  54   for(Entry = (ListHead)->ForwardLink, NextEntry = Entry->ForwardLink;\
  55       Entry != (ListHead); Entry = NextEntry, NextEntry = Entry->ForwardLink)
  56
  57 typedef struct _UFS_PASS_THRU_PRIVATE_DATA {
  58   UINT32                              Signature;
  59   EFI_HANDLE                          Handle;
  60   EFI_EXT_SCSI_PASS_THRU_MODE         ExtScsiPassThruMode;
  61   EFI_EXT_SCSI_PASS_THRU_PROTOCOL     ExtScsiPassThru;
  62   EFI_UFS_DEVICE_CONFIG_PROTOCOL      UfsDevConfig;
  63   EDKII_UFS_HOST_CONTROLLER_PROTOCOL  *UfsHostController;
  64   UINTN                               UfsHcBase;
  65   UINT32                              Capabilities;
  66
  67   UINT8                               TaskTag;
  68
  69   VOID                                *UtpTrlBase;
  70   UINT8                               Nutrs;
  71   VOID                                *TrlMapping;
  72   VOID                                *UtpTmrlBase;
  73   UINT8                               Nutmrs;
  74   VOID                                *TmrlMapping;
  75
  76   UFS_EXPOSED_LUNS                    Luns;
  77
  78   //
  79   // For Non-blocking operation.
  80   //
  81   EFI_EVENT                           TimerEvent;
  82   LIST_ENTRY                          Queue;
  83 } UFS_PASS_THRU_PRIVATE_DATA;
  84
  85 #define UFS_PASS_THRU_TRANS_REQ_SIG   SIGNATURE_32 ('U', 'F', 'S', 'T')
  86
  87 typedef struct {
  88   UINT32                                        Signature;
  89   LIST_ENTRY                                    TransferList;
  90
  91   UINT8                                         Slot;
  92   UTP_TRD                                       *Trd;
  93   UINT32                                        CmdDescSize;
  94   VOID                                          *CmdDescHost;
  95   VOID                                          *CmdDescMapping;
  96   VOID                                          *AlignedDataBuf;
  97   UINTN                                         AlignedDataBufSize;
  98   VOID                                          *DataBufMapping;
  99
 100   EFI_EXT_SCSI_PASS_THRU_SCSI_REQUEST_PACKET    *Packet;
 101   UINT64                                        TimeoutRemain;
 102   EFI_EVENT                                     CallerEvent;
 103 } UFS_PASS_THRU_TRANS_REQ;
 104
 105 #define UFS_PASS_THRU_TRANS_REQ_FROM_THIS(a) \
 106     CR(a, UFS_PASS_THRU_TRANS_REQ, TransferList, UFS_PASS_THRU_TRANS_REQ_SIG)
 107
 108 #define UFS_TIMEOUT                   EFI_TIMER_PERIOD_SECONDS(3)
 109 #define UFS_HC_ASYNC_TIMER            EFI_TIMER_PERIOD_MILLISECONDS(1)
 110
 111 #define ROUNDUP8(x) (((x) % 8 == 0) ? (x) : ((x) / 8 + 1) * 8)
 112
 113 #define IS_ALIGNED(addr, size)        (((UINTN) (addr) & (size - 1)) == 0)
 114
 115 #define UFS_PASS_THRU_PRIVATE_DATA_FROM_THIS(a) \
 116   CR (a, \
 117       UFS_PASS_THRU_PRIVATE_DATA, \
 118       ExtScsiPassThru, \
 119       UFS_PASS_THRU_SIG \
 120       )
 121
 122 #define UFS_PASS_THRU_PRIVATE_DATA_FROM_DEV_CONFIG(a) \
 123   CR (a, \
 124       UFS_PASS_THRU_PRIVATE_DATA, \
 125       UfsDevConfig, \
 126       UFS_PASS_THRU_SIG \
 127       )
 128
 129 typedef struct _UFS_DEVICE_MANAGEMENT_REQUEST_PACKET {
 130   UINT64           Timeout;
 131   VOID             *DataBuffer;
 132   UINT8            Opcode;
 133   UINT8            DescId;
 134   UINT8            Index;
 135   UINT8            Selector;
 136   UINT32           TransferLength;
 137   UINT8            DataDirection;
 138 } UFS_DEVICE_MANAGEMENT_REQUEST_PACKET;
 139
 140 //
 141 // function prototype
 142 //
 143 /**
 144   Tests to see if this driver supports a given controller. If a child device is provided,
 145   it further tests to see if this driver supports creating a handle for the specified child device.
 146
 147   This function checks to see if the driver specified by This supports the device specified by
 148   ControllerHandle. Drivers will typically use the device path attached to
 149   ControllerHandle and/or the services from the bus I/O abstraction attached to
 150   ControllerHandle to determine if the driver supports ControllerHandle. This function
 151   may be called many times during platform initialization. In order to reduce boot times, the tests
 152   performed by this function must be very small, and take as little time as possible to execute. This
 153   function must not change the state of any hardware devices, and this function must be aware that the
 154   device specified by ControllerHandle may already be managed by the same driver or a
 155   different driver. This function must match its calls to AllocatePages() with FreePages(),
 156   AllocatePool() with FreePool(), and OpenProtocol() with CloseProtocol().
 157   Since ControllerHandle may have been previously started by the same driver, if a protocol is
 158   already in the opened state, then it must not be closed with CloseProtocol(). This is required
 159   to guarantee the state of ControllerHandle is not modified by this function.
 160
 161   @param[in]  This                 A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance.
 162   @param[in]  ControllerHandle     The handle of the controller to test. This handle
 163                                    must support a protocol interface that supplies
 164                                    an I/O abstraction to the driver.
 165   @param[in]  RemainingDevicePath  A pointer to the remaining portion of a device path.  This
 166                                    parameter is ignored by device drivers, and is optional for bus
 167                                    drivers. For bus drivers, if this parameter is not NULL, then
 168                                    the bus driver must determine if the bus controller specified
 169                                    by ControllerHandle and the child controller specified
 170                                    by RemainingDevicePath are both supported by this
 171                                    bus driver.
 172
 173   @retval EFI_SUCCESS              The device specified by ControllerHandle and
 174                                    RemainingDevicePath is supported by the driver specified by This.
 175   @retval EFI_ALREADY_STARTED      The device specified by ControllerHandle and
 176                                    RemainingDevicePath is already being managed by the driver
 177                                    specified by This.
 178   @retval EFI_ACCESS_DENIED        The device specified by ControllerHandle and
 179                                    RemainingDevicePath is already being managed by a different
 180                                    driver or an application that requires exclusive access.
 181                                    Currently not implemented.
 182   @retval EFI_UNSUPPORTED          The device specified by ControllerHandle and
 183                                    RemainingDevicePath is not supported by the driver specified by This.
 184 **/
 185 EFI_STATUS
 186 EFIAPI
 187 UfsPassThruDriverBindingSupported (
 188   IN EFI_DRIVER_BINDING_PROTOCOL  *This,
 189   IN EFI_HANDLE                   Controller,
 190   IN EFI_DEVICE_PATH_PROTOCOL     *RemainingDevicePath
 191   );
 192
 193 /**
 194   Starts a device controller or a bus controller.
 195
 196   The Start() function is designed to be invoked from the EFI boot service ConnectController().
 197   As a result, much of the error checking on the parameters to Start() has been moved into this
 198   common boot service. It is legal to call Start() from other locations,
 199   but the following calling restrictions must be followed or the system behavior will not be deterministic.
 200   1. ControllerHandle must be a valid EFI_HANDLE.
 201   2. If RemainingDevicePath is not NULL, then it must be a pointer to a naturally aligned
 202      EFI_DEVICE_PATH_PROTOCOL.
 203   3. Prior to calling Start(), the Supported() function for the driver specified by This must
 204      have been called with the same calling parameters, and Supported() must have returned EFI_SUCCESS.
 205
 206   @param[in]  This                 A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance.
 207   @param[in]  ControllerHandle     The handle of the controller to start. This handle
 208                                    must support a protocol interface that supplies
 209                                    an I/O abstraction to the driver.
 210   @param[in]  RemainingDevicePath  A pointer to the remaining portion of a device path.  This
 211                                    parameter is ignored by device drivers, and is optional for bus
 212                                    drivers. For a bus driver, if this parameter is NULL, then handles
 213                                    for all the children of Controller are created by this driver.
 214                                    If this parameter is not NULL and the first Device Path Node is
 215                                    not the End of Device Path Node, then only the handle for the
 216                                    child device specified by the first Device Path Node of
 217                                    RemainingDevicePath is created by this driver.
 218                                    If the first Device Path Node of RemainingDevicePath is
 219                                    the End of Device Path Node, no child handle is created by this
 220                                    driver.
 221
 222   @retval EFI_SUCCESS              The device was started.
 223   @retval EFI_DEVICE_ERROR         The device could not be started due to a device error.Currently not implemented.
 224   @retval EFI_OUT_OF_RESOURCES     The request could not be completed due to a lack of resources.
 225   @retval Others                   The driver failded to start the device.
 226
 227 **/
 228 EFI_STATUS
 229 EFIAPI
 230 UfsPassThruDriverBindingStart (
 231   IN EFI_DRIVER_BINDING_PROTOCOL  *This,
 232   IN EFI_HANDLE                   Controller,
 233   IN EFI_DEVICE_PATH_PROTOCOL     *RemainingDevicePath
 234   );
 235
 236 /**
 237   Stops a device controller or a bus controller.
 238
 239   The Stop() function is designed to be invoked from the EFI boot service DisconnectController().
 240   As a result, much of the error checking on the parameters to Stop() has been moved
 241   into this common boot service. It is legal to call Stop() from other locations,
 242   but the following calling restrictions must be followed or the system behavior will not be deterministic.
 243   1. ControllerHandle must be a valid EFI_HANDLE that was used on a previous call to this
 244      same driver's Start() function.
 245   2. The first NumberOfChildren handles of ChildHandleBuffer must all be a valid
 246      EFI_HANDLE. In addition, all of these handles must have been created in this driver's
 247      Start() function, and the Start() function must have called OpenProtocol() on
 248      ControllerHandle with an Attribute of EFI_OPEN_PROTOCOL_BY_CHILD_CONTROLLER.
 249
 250   @param[in]  This              A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance.
 251   @param[in]  ControllerHandle  A handle to the device being stopped. The handle must
 252                                 support a bus specific I/O protocol for the driver
 253                                 to use to stop the device.
 254   @param[in]  NumberOfChildren  The number of child device handles in ChildHandleBuffer.
 255   @param[in]  ChildHandleBuffer An array of child handles to be freed. May be NULL
 256                                 if NumberOfChildren is 0.
 257
 258   @retval EFI_SUCCESS           The device was stopped.
 259   @retval EFI_DEVICE_ERROR      The device could not be stopped due to a device error.
 260
 261 **/
 262 EFI_STATUS
 263 EFIAPI
 264 UfsPassThruDriverBindingStop (
 265   IN  EFI_DRIVER_BINDING_PROTOCOL     *This,
 266   IN  EFI_HANDLE                      Controller,
 267   IN  UINTN                           NumberOfChildren,
 268   IN  EFI_HANDLE                      *ChildHandleBuffer
 269   );
 270
 271 //
 272 // EFI Component Name Functions
 273 //
 274 /**
 275   Retrieves a Unicode string that is the user readable name of the driver.
 276
 277   This function retrieves the user readable name of a driver in the form of a
 278   Unicode string. If the driver specified by This has a user readable name in
 279   the language specified by Language, then a pointer to the driver name is
 280   returned in DriverName, and EFI_SUCCESS is returned. If the driver specified
 281   by This does not support the language specified by Language,
 282   then EFI_UNSUPPORTED is returned.
 283
 284   @param  This[in]              A pointer to the EFI_COMPONENT_NAME2_PROTOCOL or
 285                                 EFI_COMPONENT_NAME_PROTOCOL instance.
 286
 287   @param  Language[in]          A pointer to a Null-terminated ASCII string
 288                                 array indicating the language. This is the
 289                                 language of the driver name that the caller is
 290                                 requesting, and it must match one of the
 291                                 languages specified in SupportedLanguages. The
 292                                 number of languages supported by a driver is up
 293                                 to the driver writer. Language is specified
 294                                 in RFC 4646 or ISO 639-2 language code format.
 295
 296   @param  DriverName[out]       A pointer to the Unicode string to return.
 297                                 This Unicode string is the name of the
 298                                 driver specified by This in the language
 299                                 specified by Language.
 300
 301   @retval EFI_SUCCESS           The Unicode string for the Driver specified by
 302                                 This and the language specified by Language was
 303                                 returned in DriverName.
 304
 305   @retval EFI_INVALID_PARAMETER Language is NULL.
 306
 307   @retval EFI_INVALID_PARAMETER DriverName is NULL.
 308
 309   @retval EFI_UNSUPPORTED       The driver specified by This does not support
 310                                 the language specified by Language.
 311
 312 **/
 313 EFI_STATUS
 314 EFIAPI
 315 UfsPassThruComponentNameGetDriverName (
 316   IN  EFI_COMPONENT_NAME_PROTOCOL  *This,
 317   IN  CHAR8                        *Language,
 318   OUT CHAR16                       **DriverName
 319   );
 320
 321
 322 /**
 323   Retrieves a Unicode string that is the user readable name of the controller
 324   that is being managed by a driver.
 325
 326   This function retrieves the user readable name of the controller specified by
 327   ControllerHandle and ChildHandle in the form of a Unicode string. If the
 328   driver specified by This has a user readable name in the language specified by
 329   Language, then a pointer to the controller name is returned in ControllerName,
 330   and EFI_SUCCESS is returned.  If the driver specified by This is not currently
 331   managing the controller specified by ControllerHandle and ChildHandle,
 332   then EFI_UNSUPPORTED is returned.  If the driver specified by This does not
 333   support the language specified by Language, then EFI_UNSUPPORTED is returned.
 334
 335   @param  This[in]              A pointer to the EFI_COMPONENT_NAME2_PROTOCOL or
 336                                 EFI_COMPONENT_NAME_PROTOCOL instance.
 337
 338   @param  ControllerHandle[in]  The handle of a controller that the driver
 339                                 specified by This is managing.  This handle
 340                                 specifies the controller whose name is to be
 341                                 returned.
 342
 343   @param  ChildHandle[in]       The handle of the child controller to retrieve
 344                                 the name of.  This is an optional parameter that
 345                                 may be NULL.  It will be NULL for device
 346                                 drivers.  It will also be NULL for a bus drivers
 347                                 that wish to retrieve the name of the bus
 348                                 controller.  It will not be NULL for a bus
 349                                 driver that wishes to retrieve the name of a
 350                                 child controller.
 351
 352   @param  Language[in]          A pointer to a Null-terminated ASCII string
 353                                 array indicating the language.  This is the
 354                                 language of the driver name that the caller is
 355                                 requesting, and it must match one of the
 356                                 languages specified in SupportedLanguages. The
 357                                 number of languages supported by a driver is up
 358                                 to the driver writer. Language is specified in
 359                                 RFC 4646 or ISO 639-2 language code format.
 360
 361   @param  ControllerName[out]   A pointer to the Unicode string to return.
 362                                 This Unicode string is the name of the
 363                                 controller specified by ControllerHandle and
 364                                 ChildHandle in the language specified by
 365                                 Language from the point of view of the driver
 366                                 specified by This.
 367
 368   @retval EFI_SUCCESS           The Unicode string for the user readable name in
 369                                 the language specified by Language for the
 370                                 driver specified by This was returned in
 371                                 DriverName.
 372
 373   @retval EFI_INVALID_PARAMETER ControllerHandle is NULL.
 374
 375   @retval EFI_INVALID_PARAMETER ChildHandle is not NULL and it is not a valid
 376                                 EFI_HANDLE.
 377
 378   @retval EFI_INVALID_PARAMETER Language is NULL.
 379
 380   @retval EFI_INVALID_PARAMETER ControllerName is NULL.
 381
 382   @retval EFI_UNSUPPORTED       The driver specified by This is not currently
 383                                 managing the controller specified by
 384                                 ControllerHandle and ChildHandle.
 385
 386   @retval EFI_UNSUPPORTED       The driver specified by This does not support
 387                                 the language specified by Language.
 388
 389 **/
 390 EFI_STATUS
 391 EFIAPI
 392 UfsPassThruComponentNameGetControllerName (
 393   IN  EFI_COMPONENT_NAME_PROTOCOL                     *This,
 394   IN  EFI_HANDLE                                      ControllerHandle,
 395   IN  EFI_HANDLE                                      ChildHandle        OPTIONAL,
 396   IN  CHAR8                                           *Language,
 397   OUT CHAR16                                          **ControllerName
 398   );
 399
 400 /**
 401   Sends a SCSI Request Packet to a SCSI device that is attached to the SCSI channel. This function
 402   supports both blocking I/O and nonblocking I/O. The blocking I/O functionality is required, and the
 403   nonblocking I/O functionality is optional.
 404
 405   @param  This    A pointer to the EFI_EXT_SCSI_PASS_THRU_PROTOCOL instance.
 406   @param  Target  The Target is an array of size TARGET_MAX_BYTES and it represents
 407                   the id of the SCSI device to send the SCSI Request Packet. Each
 408                   transport driver may choose to utilize a subset of this size to suit the needs
 409                   of transport target representation. For example, a Fibre Channel driver
 410                   may use only 8 bytes (WWN) to represent an FC target.
 411   @param  Lun     The LUN of the SCSI device to send the SCSI Request Packet.
 412   @param  Packet  A pointer to the SCSI Request Packet to send to the SCSI device
 413                   specified by Target and Lun.
 414   @param  Event   If nonblocking I/O is not supported then Event is ignored, and blocking
 415                   I/O is performed. If Event is NULL, then blocking I/O is performed. If
 416                   Event is not NULL and non blocking I/O is supported, then
 417                   nonblocking I/O is performed, and Event will be signaled when the
 418                   SCSI Request Packet completes.
 419
 420   @retval EFI_SUCCESS           The SCSI Request Packet was sent by the host. For bi-directional
 421                                 commands, InTransferLength bytes were transferred from
 422                                 InDataBuffer. For write and bi-directional commands,
 423                                 OutTransferLength bytes were transferred by
 424                                 OutDataBuffer.
 425   @retval EFI_BAD_BUFFER_SIZE   The SCSI Request Packet was not executed. The number of bytes that
 426                                 could be transferred is returned in InTransferLength. For write
 427                                 and bi-directional commands, OutTransferLength bytes were
 428                                 transferred by OutDataBuffer.
 429   @retval EFI_NOT_READY         The SCSI Request Packet could not be sent because there are too many
 430                                 SCSI Request Packets already queued. The caller may retry again later.
 431   @retval EFI_DEVICE_ERROR      A device error occurred while attempting to send the SCSI Request
 432                                 Packet.
 433   @retval EFI_INVALID_PARAMETER Target, Lun, or the contents of ScsiRequestPacket are invalid.
 434   @retval EFI_UNSUPPORTED       The command described by the SCSI Request Packet is not supported
 435                                 by the host adapter. This includes the case of Bi-directional SCSI
 436                                 commands not supported by the implementation. The SCSI Request
 437                                 Packet was not sent, so no additional status information is available.
 438   @retval EFI_TIMEOUT           A timeout occurred while waiting for the SCSI Request Packet to execute.
 439
 440 **/
 441 EFI_STATUS
 442 EFIAPI
 443 UfsPassThruPassThru (
 444   IN EFI_EXT_SCSI_PASS_THRU_PROTOCOL                    *This,
 445   IN UINT8                                              *Target,
 446   IN UINT64                                             Lun,
 447   IN OUT EFI_EXT_SCSI_PASS_THRU_SCSI_REQUEST_PACKET     *Packet,
 448   IN EFI_EVENT                                          Event OPTIONAL
 449   );
 450
 451 /**
 452   Used to retrieve the list of legal Target IDs and LUNs for SCSI devices on a SCSI channel. These
 453   can either be the list SCSI devices that are actually present on the SCSI channel, or the list of legal
 454   Target Ids and LUNs for the SCSI channel. Regardless, the caller of this function must probe the
 455   Target ID and LUN returned to see if a SCSI device is actually present at that location on the SCSI
 456   channel.
 457
 458   @param  This   A pointer to the EFI_EXT_SCSI_PASS_THRU_PROTOCOL instance.
 459   @param  Target On input, a pointer to the Target ID (an array of size
 460                  TARGET_MAX_BYTES) of a SCSI device present on the SCSI channel.
 461                  On output, a pointer to the Target ID (an array of
 462                  TARGET_MAX_BYTES) of the next SCSI device present on a SCSI
 463                  channel. An input value of 0xF(all bytes in the array are 0xF) in the
 464                  Target array retrieves the Target ID of the first SCSI device present on a
 465                  SCSI channel.
 466   @param  Lun    On input, a pointer to the LUN of a SCSI device present on the SCSI
 467                  channel. On output, a pointer to the LUN of the next SCSI device present
 468                  on a SCSI channel.
 469
 470   @retval EFI_SUCCESS           The Target ID and LUN of the next SCSI device on the SCSI
 471                                 channel was returned in Target and Lun.
 472   @retval EFI_INVALID_PARAMETER Target array is not all 0xF, and Target and Lun were
 473                                 not returned on a previous call to GetNextTargetLun().
 474   @retval EFI_NOT_FOUND         There are no more SCSI devices on this SCSI channel.
 475
 476 **/
 477 EFI_STATUS
 478 EFIAPI
 479 UfsPassThruGetNextTargetLun (
 480   IN  EFI_EXT_SCSI_PASS_THRU_PROTOCOL    *This,
 481   IN OUT UINT8                           **Target,
 482   IN OUT UINT64                          *Lun
 483   );
 484
 485 /**
 486   Used to allocate and build a device path node for a SCSI device on a SCSI channel.
 487
 488   @param  This       A pointer to the EFI_EXT_SCSI_PASS_THRU_PROTOCOL instance.
 489   @param  Target     The Target is an array of size TARGET_MAX_BYTES and it specifies the
 490                      Target ID of the SCSI device for which a device path node is to be
 491                      allocated and built. Transport drivers may chose to utilize a subset of
 492                      this size to suit the representation of targets. For example, a Fibre
 493                      Channel driver may use only 8 bytes (WWN) in the array to represent a
 494                      FC target.
 495   @param  Lun        The LUN of the SCSI device for which a device path node is to be
 496                      allocated and built.
 497   @param  DevicePath A pointer to a single device path node that describes the SCSI device
 498                      specified by Target and Lun. This function is responsible for
 499                      allocating the buffer DevicePath with the boot service
 500                      AllocatePool(). It is the caller's responsibility to free
 501                      DevicePath when the caller is finished with DevicePath.
 502
 503   @retval EFI_SUCCESS           The device path node that describes the SCSI device specified by
 504                                 Target and Lun was allocated and returned in
 505                                 DevicePath.
 506   @retval EFI_INVALID_PARAMETER DevicePath is NULL.
 507   @retval EFI_NOT_FOUND         The SCSI devices specified by Target and Lun does not exist
 508                                 on the SCSI channel.
 509   @retval EFI_OUT_OF_RESOURCES  There are not enough resources to allocate DevicePath.
 510
 511 **/
 512 EFI_STATUS
 513 EFIAPI
 514 UfsPassThruBuildDevicePath (
 515   IN     EFI_EXT_SCSI_PASS_THRU_PROTOCOL    *This,
 516   IN     UINT8                              *Target,
 517   IN     UINT64                             Lun,
 518   IN OUT EFI_DEVICE_PATH_PROTOCOL           **DevicePath
 519   );
 520
 521 /**
 522   Used to translate a device path node to a Target ID and LUN.
 523
 524   @param  This       A pointer to the EFI_EXT_SCSI_PASS_THRU_PROTOCOL instance.
 525   @param  DevicePath A pointer to a single device path node that describes the SCSI device
 526                      on the SCSI channel.
 527   @param  Target     A pointer to the Target Array which represents the ID of a SCSI device
 528                      on the SCSI channel.
 529   @param  Lun        A pointer to the LUN of a SCSI device on the SCSI channel.
 530
 531   @retval EFI_SUCCESS           DevicePath was successfully translated to a Target ID and
 532                                 LUN, and they were returned in Target and Lun.
 533   @retval EFI_INVALID_PARAMETER DevicePath or Target or Lun is NULL.
 534   @retval EFI_NOT_FOUND         A valid translation from DevicePath to a Target ID and LUN
 535                                 does not exist.
 536   @retval EFI_UNSUPPORTED       This driver does not support the device path node type in
 537                                  DevicePath.
 538
 539 **/
 540 EFI_STATUS
 541 EFIAPI
 542 UfsPassThruGetTargetLun (
 543   IN  EFI_EXT_SCSI_PASS_THRU_PROTOCOL    *This,
 544   IN  EFI_DEVICE_PATH_PROTOCOL           *DevicePath,
 545   OUT UINT8                              **Target,
 546   OUT UINT64                             *Lun
 547   );
 548
 549 /**
 550   Resets a SCSI channel. This operation resets all the SCSI devices connected to the SCSI channel.
 551
 552   @param  This A pointer to the EFI_EXT_SCSI_PASS_THRU_PROTOCOL instance.
 553
 554   @retval EFI_SUCCESS      The SCSI channel was reset.
 555   @retval EFI_DEVICE_ERROR A device error occurred while attempting to reset the SCSI channel.
 556   @retval EFI_TIMEOUT      A timeout occurred while attempting to reset the SCSI channel.
 557   @retval EFI_UNSUPPORTED  The SCSI channel does not support a channel reset operation.
 558
 559 **/
 560 EFI_STATUS
 561 EFIAPI
 562 UfsPassThruResetChannel (
 563   IN  EFI_EXT_SCSI_PASS_THRU_PROTOCOL   *This
 564   );
 565
 566 /**
 567   Resets a SCSI logical unit that is connected to a SCSI channel.
 568
 569   @param  This   A pointer to the EFI_EXT_SCSI_PASS_THRU_PROTOCOL instance.
 570   @param  Target The Target is an array of size TARGET_MAX_BYTE and it represents the
 571                  target port ID of the SCSI device containing the SCSI logical unit to
 572                  reset. Transport drivers may chose to utilize a subset of this array to suit
 573                  the representation of their targets.
 574   @param  Lun    The LUN of the SCSI device to reset.
 575
 576   @retval EFI_SUCCESS           The SCSI device specified by Target and Lun was reset.
 577   @retval EFI_INVALID_PARAMETER Target or Lun is NULL.
 578   @retval EFI_TIMEOUT           A timeout occurred while attempting to reset the SCSI device
 579                                 specified by Target and Lun.
 580   @retval EFI_UNSUPPORTED       The SCSI channel does not support a target reset operation.
 581   @retval EFI_DEVICE_ERROR      A device error occurred while attempting to reset the SCSI device
 582                                  specified by Target and Lun.
 583
 584 **/
 585 EFI_STATUS
 586 EFIAPI
 587 UfsPassThruResetTargetLun (
 588   IN EFI_EXT_SCSI_PASS_THRU_PROTOCOL    *This,
 589   IN UINT8                              *Target,
 590   IN UINT64                             Lun
 591   );
 592
 593 /**
 594   Used to retrieve the list of legal Target IDs for SCSI devices on a SCSI channel. These can either
 595   be the list SCSI devices that are actually present on the SCSI channel, or the list of legal Target IDs
 596   for the SCSI channel. Regardless, the caller of this function must probe the Target ID returned to
 597   see if a SCSI device is actually present at that location on the SCSI channel.
 598
 599   @param  This   A pointer to the EFI_EXT_SCSI_PASS_THRU_PROTOCOL instance.
 600   @param  Target (TARGET_MAX_BYTES) of a SCSI device present on the SCSI channel.
 601                  On output, a pointer to the Target ID (an array of
 602                  TARGET_MAX_BYTES) of the next SCSI device present on a SCSI
 603                  channel. An input value of 0xF(all bytes in the array are 0xF) in the
 604                  Target array retrieves the Target ID of the first SCSI device present on a
 605                  SCSI channel.
 606
 607   @retval EFI_SUCCESS           The Target ID of the next SCSI device on the SCSI
 608                                 channel was returned in Target.
 609   @retval EFI_INVALID_PARAMETER Target or Lun is NULL.
 610   @retval EFI_TIMEOUT           Target array is not all 0xF, and Target was not
 611                                 returned on a previous call to GetNextTarget().
 612   @retval EFI_NOT_FOUND         There are no more SCSI devices on this SCSI channel.
 613
 614 **/
 615 EFI_STATUS
 616 EFIAPI
 617 UfsPassThruGetNextTarget (
 618   IN  EFI_EXT_SCSI_PASS_THRU_PROTOCOL    *This,
 619   IN OUT UINT8                           **Target
 620   );
 621
 622 /**
 623   Sends a UFS-supported SCSI Request Packet to a UFS device that is attached to the UFS host controller.
 624
 625   @param[in]      Private       The pointer to the UFS_PASS_THRU_PRIVATE_DATA data structure.
 626   @param[in]      Lun           The LUN of the UFS device to send the SCSI Request Packet.
 627   @param[in, out] Packet        A pointer to the SCSI Request Packet to send to a specified Lun of the
 628                                 UFS device.
 629   @param[in]      Event         If nonblocking I/O is not supported then Event is ignored, and blocking
 630                                 I/O is performed. If Event is NULL, then blocking I/O is performed. If
 631                                 Event is not NULL and non blocking I/O is supported, then
 632                                 nonblocking I/O is performed, and Event will be signaled when the
 633                                 SCSI Request Packet completes.
 634
 635   @retval EFI_SUCCESS           The SCSI Request Packet was sent by the host. For bi-directional
 636                                 commands, InTransferLength bytes were transferred from
 637                                 InDataBuffer. For write and bi-directional commands,
 638                                 OutTransferLength bytes were transferred by
 639                                 OutDataBuffer.
 640   @retval EFI_DEVICE_ERROR      A device error occurred while attempting to send the SCSI Request
 641                                 Packet.
 642   @retval EFI_OUT_OF_RESOURCES  The resource for transfer is not available.
 643   @retval EFI_TIMEOUT           A timeout occurred while waiting for the SCSI Request Packet to execute.
 644
 645 **/
 646 EFI_STATUS
 647 UfsExecScsiCmds (
 648   IN     UFS_PASS_THRU_PRIVATE_DATA                  *Private,
 649   IN     UINT8                                       Lun,
 650   IN OUT EFI_EXT_SCSI_PASS_THRU_SCSI_REQUEST_PACKET  *Packet,
 651   IN     EFI_EVENT                                   Event    OPTIONAL
 652   );
 653
 654 /**
 655   Initialize the UFS host controller.
 656
 657   @param[in] Private                 The pointer to the NVME_CONTROLLER_PRIVATE_DATA data structure.
 658
 659   @retval EFI_SUCCESS                The NVM Express Controller is initialized successfully.
 660   @retval Others                     A device error occurred while initializing the controller.
 661
 662 **/
 663 EFI_STATUS
 664 UfsControllerInit (
 665   IN  UFS_PASS_THRU_PRIVATE_DATA     *Private
 666   );
 667
 668 /**
 669   Stop the UFS host controller.
 670
 671   @param[in] Private                 The pointer to the UFS_PASS_THRU_PRIVATE_DATA data structure.
 672
 673   @retval EFI_SUCCESS                The Ufs Host Controller is stopped successfully.
 674   @retval Others                     A device error occurred while stopping the controller.
 675
 676 **/
 677 EFI_STATUS
 678 UfsControllerStop (
 679   IN  UFS_PASS_THRU_PRIVATE_DATA     *Private
 680   );
 681
 682 /**
 683   Allocate common buffer for host and UFS bus master access simultaneously.
 684
 685   @param[in]  Private                The pointer to the UFS_PASS_THRU_PRIVATE_DATA data structure.
 686   @param[in]  Size                   The length of buffer to be allocated.
 687   @param[out] CmdDescHost            A pointer to store the base system memory address of the allocated range.
 688   @param[out] CmdDescPhyAddr         The resulting map address for the UFS bus master to use to access the hosts CmdDescHost.
 689   @param[out] CmdDescMapping         A resulting value to pass to Unmap().
 690
 691   @retval EFI_SUCCESS                The common buffer was allocated successfully.
 692   @retval EFI_DEVICE_ERROR           The allocation fails.
 693   @retval EFI_OUT_OF_RESOURCES       The memory resource is insufficient.
 694
 695 **/
 696 EFI_STATUS
 697 UfsAllocateAlignCommonBuffer (
 698   IN     UFS_PASS_THRU_PRIVATE_DATA    *Private,
 699   IN     UINTN                         Size,
 700      OUT VOID                          **CmdDescHost,
 701      OUT EFI_PHYSICAL_ADDRESS          *CmdDescPhyAddr,
 702      OUT VOID                          **CmdDescMapping
 703   );
 704
 705 /**
 706   Set specified flag to 1 on a UFS device.
 707
 708   @param[in]  Private           The pointer to the UFS_PASS_THRU_PRIVATE_DATA data structure.
 709   @param[in]  FlagId            The ID of flag to be set.
 710
 711   @retval EFI_SUCCESS           The flag was set successfully.
 712   @retval EFI_DEVICE_ERROR      A device error occurred while attempting to set the flag.
 713   @retval EFI_TIMEOUT           A timeout occurred while waiting for the completion of setting the flag.
 714
 715 **/
 716 EFI_STATUS
 717 UfsSetFlag (
 718   IN  UFS_PASS_THRU_PRIVATE_DATA   *Private,
 719   IN  UINT8                        FlagId
 720   );
 721
 722 /**
 723   Read specified flag from a UFS device.
 724
 725   @param[in]  Private           The pointer to the UFS_PASS_THRU_PRIVATE_DATA data structure.
 726   @param[in]  FlagId            The ID of flag to be read.
 727   @param[out] Value             The flag's value.
 728
 729   @retval EFI_SUCCESS           The flag was read successfully.
 730   @retval EFI_DEVICE_ERROR      A device error occurred while attempting to read the flag.
 731   @retval EFI_TIMEOUT           A timeout occurred while waiting for the completion of reading the flag.
 732
 733 **/
 734 EFI_STATUS
 735 UfsReadFlag (
 736   IN     UFS_PASS_THRU_PRIVATE_DATA   *Private,
 737   IN     UINT8                        FlagId,
 738      OUT UINT8                        *Value
 739   );
 740
 741 /**
 742   Read or write specified flag of a UFS device.
 743
 744   @param[in]      Private       The pointer to the UFS_PASS_THRU_PRIVATE_DATA data structure.
 745   @param[in]      Read          The boolean variable to show r/w direction.
 746   @param[in]      FlagId        The ID of flag to be read or written.
 747   @param[in, out] Value         The value to set or clear flag.
 748
 749   @retval EFI_SUCCESS           The flag was read/written successfully.
 750   @retval EFI_DEVICE_ERROR      A device error occurred while attempting to r/w the flag.
 751   @retval EFI_TIMEOUT           A timeout occurred while waiting for the completion of r/w the flag.
 752
 753 **/
 754 EFI_STATUS
 755 UfsRwFlags (
 756   IN     UFS_PASS_THRU_PRIVATE_DATA   *Private,
 757   IN     BOOLEAN                      Read,
 758   IN     UINT8                        FlagId,
 759   IN OUT UINT8                        *Value
 760   );
 761
 762 /**
 763   Read or write specified device descriptor of a UFS device.
 764
 765   @param[in]      Private       The pointer to the UFS_PASS_THRU_PRIVATE_DATA data structure.
 766   @param[in]      Read          The boolean variable to show r/w direction.
 767   @param[in]      DescId        The ID of device descriptor.
 768   @param[in]      Index         The Index of device descriptor.
 769   @param[in]      Selector      The Selector of device descriptor.
 770   @param[in, out] Descriptor    The buffer of device descriptor to be read or written.
 771   @param[in, out] DescSize      The size of device descriptor buffer. On input, the size, in bytes,
 772                                 of the data buffer specified by Descriptor. On output, the number
 773                                 of bytes that were actually transferred.
 774
 775   @retval EFI_SUCCESS           The device descriptor was read/written successfully.
 776   @retval EFI_DEVICE_ERROR      A device error occurred while attempting to r/w the device descriptor.
 777   @retval EFI_TIMEOUT           A timeout occurred while waiting for the completion of r/w the device descriptor.
 778
 779 **/
 780 EFI_STATUS
 781 UfsRwDeviceDesc (
 782   IN     UFS_PASS_THRU_PRIVATE_DATA   *Private,
 783   IN     BOOLEAN                      Read,
 784   IN     UINT8                        DescId,
 785   IN     UINT8                        Index,
 786   IN     UINT8                        Selector,
 787   IN OUT VOID                         *Descriptor,
 788   IN OUT UINT32                       *DescSize
 789   );
 790
 791 /**
 792   Read or write specified attribute of a UFS device.
 793
 794   @param[in]      Private       The pointer to the UFS_PASS_THRU_PRIVATE_DATA data structure.
 795   @param[in]      Read          The boolean variable to show r/w direction.
 796   @param[in]      AttrId        The ID of Attribute.
 797   @param[in]      Index         The Index of Attribute.
 798   @param[in]      Selector      The Selector of Attribute.
 799   @param[in, out] Attributes    The value of Attribute to be read or written.
 800
 801   @retval EFI_SUCCESS           The Attribute was read/written successfully.
 802   @retval EFI_DEVICE_ERROR      A device error occurred while attempting to r/w the Attribute.
 803   @retval EFI_TIMEOUT           A timeout occurred while waiting for the completion of r/w the Attribute.
 804
 805 **/
 806 EFI_STATUS
 807 UfsRwAttributes (
 808   IN     UFS_PASS_THRU_PRIVATE_DATA   *Private,
 809   IN     BOOLEAN                      Read,
 810   IN     UINT8                        AttrId,
 811   IN     UINT8                        Index,
 812   IN     UINT8                        Selector,
 813   IN OUT UINT32                       *Attributes
 814   );
 815
 816 /**
 817   Sends NOP IN cmd to a UFS device for initialization process request.
 818   For more details, please refer to UFS 2.0 spec Figure 13.3.
 819
 820   @param[in]  Private           The pointer to the UFS_PASS_THRU_PRIVATE_DATA data structure.
 821
 822   @retval EFI_SUCCESS           The NOP IN command was sent by the host. The NOP OUT response was
 823                                 received successfully.
 824   @retval EFI_DEVICE_ERROR      A device error occurred while attempting to execute NOP IN command.
 825   @retval EFI_OUT_OF_RESOURCES  The resource for transfer is not available.
 826   @retval EFI_TIMEOUT           A timeout occurred while waiting for the NOP IN command to execute.
 827
 828 **/
 829 EFI_STATUS
 830 UfsExecNopCmds (
 831   IN  UFS_PASS_THRU_PRIVATE_DATA       *Private
 832   );
 833
 834 /**
 835   Call back function when the timer event is signaled.
 836
 837   @param[in]  Event     The Event this notify function registered to.
 838   @param[in]  Context   Pointer to the context data registered to the Event.
 839
 840 **/
 841 VOID
 842 EFIAPI
 843 ProcessAsyncTaskList (
 844   IN EFI_EVENT          Event,
 845   IN VOID               *Context
 846   );
 847
 848 /**
 849   Internal helper function which will signal the caller event and clean up
 850   resources.
 851
 852   @param[in] Private   The pointer to the UFS_PASS_THRU_PRIVATE_DATA data
 853                        structure.
 854   @param[in] TransReq  The pointer to the UFS_PASS_THRU_TRANS_REQ data
 855                        structure.
 856
 857 **/
 858 VOID
 859 EFIAPI
 860 SignalCallerEvent (
 861   IN UFS_PASS_THRU_PRIVATE_DATA      *Private,
 862   IN UFS_PASS_THRU_TRANS_REQ         *TransReq
 863   );
 864
 865 /**
 866   Read or write specified device descriptor of a UFS device.
 867
 868   The function is used to read/write UFS device descriptors. The consumer of this API is
 869   responsible for allocating the data buffer pointed by Descriptor.
 870
 871   @param[in]      This          The pointer to the EFI_UFS_DEVICE_CONFIG_PROTOCOL instance.
 872   @param[in]      Read          The boolean variable to show r/w direction.
 873   @param[in]      DescId        The ID of device descriptor.
 874   @param[in]      Index         The Index of device descriptor.
 875   @param[in]      Selector      The Selector of device descriptor.
 876   @param[in, out] Descriptor    The buffer of device descriptor to be read or written.
 877   @param[in, out] DescSize      The size of device descriptor buffer. On input, the size, in bytes,
 878                                 of the data buffer specified by Descriptor. On output, the number
 879                                 of bytes that were actually transferred.
 880
 881   @retval EFI_SUCCESS           The device descriptor is read/written successfully.
 882   @retval EFI_INVALID_PARAMETER This is NULL or Descriptor is NULL or DescSize is NULL.
 883                                 DescId, Index and Selector are invalid combination to point to a
 884                                 type of UFS device descriptor.
 885   @retval EFI_DEVICE_ERROR      The device descriptor is not read/written successfully.
 886
 887 **/
 888 EFI_STATUS
 889 EFIAPI
 890 UfsRwUfsDescriptor (
 891   IN EFI_UFS_DEVICE_CONFIG_PROTOCOL    *This,
 892   IN BOOLEAN                           Read,
 893   IN UINT8                             DescId,
 894   IN UINT8                             Index,
 895   IN UINT8                             Selector,
 896   IN OUT UINT8                         *Descriptor,
 897   IN OUT UINT32                        *DescSize
 898   );
 899
 900 /**
 901   Read or write specified flag of a UFS device.
 902
 903   The function is used to read/write UFS flag descriptors. The consumer of this API is responsible
 904   for allocating the buffer pointed by Flag. The buffer size is 1 byte as UFS flag descriptor is
 905   just a single Boolean value that represents a TRUE or FALSE, '0' or '1', ON or OFF type of value.
 906
 907   @param[in]      This          The pointer to the EFI_UFS_DEVICE_CONFIG_PROTOCOL instance.
 908   @param[in]      Read          The boolean variable to show r/w direction.
 909   @param[in]      FlagId        The ID of flag to be read or written.
 910   @param[in, out] Flag          The buffer to set or clear flag.
 911
 912   @retval EFI_SUCCESS           The flag descriptor is set/clear successfully.
 913   @retval EFI_INVALID_PARAMETER This is NULL or Flag is NULL.
 914                                 FlagId is an invalid UFS flag ID.
 915   @retval EFI_DEVICE_ERROR      The flag is not set/clear successfully.
 916
 917 **/
 918 EFI_STATUS
 919 EFIAPI
 920 UfsRwUfsFlag (
 921   IN EFI_UFS_DEVICE_CONFIG_PROTOCOL    *This,
 922   IN BOOLEAN                           Read,
 923   IN UINT8                             FlagId,
 924   IN OUT UINT8                         *Flag
 925   );
 926
 927 /**
 928   Read or write specified attribute of a UFS device.
 929
 930   The function is used to read/write UFS attributes. The consumer of this API is responsible for
 931   allocating the data buffer pointed by Attribute.
 932
 933   @param[in]      This          The pointer to the EFI_UFS_DEVICE_CONFIG_PROTOCOL instance.
 934   @param[in]      Read          The boolean variable to show r/w direction.
 935   @param[in]      AttrId        The ID of Attribute.
 936   @param[in]      Index         The Index of Attribute.
 937   @param[in]      Selector      The Selector of Attribute.
 938   @param[in, out] Attribute     The buffer of Attribute to be read or written.
 939   @param[in, out] AttrSize      The size of Attribute buffer. On input, the size, in bytes, of the
 940                                 data buffer specified by Attribute. On output, the number of bytes
 941                                 that were actually transferred.
 942
 943   @retval EFI_SUCCESS           The attribute is read/written successfully.
 944   @retval EFI_INVALID_PARAMETER This is NULL or Attribute is NULL or AttrSize is NULL.
 945                                 AttrId, Index and Selector are invalid combination to point to a
 946                                 type of UFS attribute.
 947   @retval EFI_DEVICE_ERROR      The attribute is not read/written successfully.
 948
 949 **/
 950 EFI_STATUS
 951 EFIAPI
 952 UfsRwUfsAttribute (
 953   IN EFI_UFS_DEVICE_CONFIG_PROTOCOL    *This,
 954   IN BOOLEAN                           Read,
 955   IN UINT8                             AttrId,
 956   IN UINT8                             Index,
 957   IN UINT8                             Selector,
 958   IN OUT UINT8                         *Attribute,
 959   IN OUT UINT32                        *AttrSize
 960   );
 961
 962 extern EFI_COMPONENT_NAME_PROTOCOL  gUfsPassThruComponentName;
 963 extern EFI_COMPONENT_NAME2_PROTOCOL gUfsPassThruComponentName2;
 964 extern EFI_DRIVER_BINDING_PROTOCOL  gUfsPassThruDriverBinding;
 965
 966 #endif