MdeModulePkg/Bus/Ufs/UfsPassThruDxe/UfsPassThru.h

   1 /** @file
   2
   3   Copyright (c) 2014, Intel Corporation. All rights reserved.<BR>
   4   This program and the accompanying materials
   5   are licensed and made available under the terms and conditions of the BSD License
   6   which accompanies this distribution.  The full text of the license may be found at
   7   http://opensource.org/licenses/bsd-license.php
   8
   9   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  10   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  11
  12 **/
  13
  14 #ifndef _UFS_PASS_THRU_H_
  15 #define _UFS_PASS_THRU_H_
  16
  17 #include <Uefi.h>
  18
  19 #include <Protocol/ScsiPassThruExt.h>
  20 #include <Protocol/UfsHostController.h>
  21
  22 #include <Library/DebugLib.h>
  23 #include <Library/UefiDriverEntryPoint.h>
  24 #include <Library/BaseLib.h>
  25 #include <Library/UefiLib.h>
  26 #include <Library/BaseMemoryLib.h>
  27 #include <Library/MemoryAllocationLib.h>
  28 #include <Library/UefiBootServicesTableLib.h>
  29 #include <Library/DevicePathLib.h>
  30 #include <Library/IoLib.h>
  31 #include <Library/TimerLib.h>
  32
  33 #include "UfsPassThruHci.h"
  34
  35 #define UFS_PASS_THRU_SIG           SIGNATURE_32 ('U', 'F', 'S', 'P')
  36
  37 //
  38 // Lun 0~7 is for 8 common luns.
  39 // Lun 8~11 is for those 4 well known luns (Refer to UFS 2.0 spec Table 10.58 for details):
  40 //  Lun 8:  REPORT LUNS
  41 //  Lun 9:  UFS DEVICE
  42 //  Lun 10: BOOT
  43 //  Lun 11: RPMB
  44 //
  45 #define UFS_MAX_LUNS                12
  46 #define UFS_WLUN_PREFIX             0xC1
  47
  48 typedef struct {
  49   UINT8    Lun[UFS_MAX_LUNS];
  50   UINT16   BitMask:12;              // Bit 0~7 is 1/1 mapping to common luns. Bit 8~11 is 1/1 mapping to well-known luns.
  51   UINT16   Rsvd:4;
  52 } UFS_EXPOSED_LUNS;
  53
  54 typedef struct _UFS_PASS_THRU_PRIVATE_DATA {
  55   UINT32                              Signature;
  56   EFI_HANDLE                          Handle;
  57   EFI_EXT_SCSI_PASS_THRU_MODE         ExtScsiPassThruMode;
  58   EFI_EXT_SCSI_PASS_THRU_PROTOCOL     ExtScsiPassThru;
  59   EDKII_UFS_HOST_CONTROLLER_PROTOCOL  *UfsHostController;
  60   UINTN                               UfsHcBase;
  61   UINT32                              Capabilities;
  62
  63   UINT8                               TaskTag;
  64
  65   VOID                                *UtpTrlBase;
  66   UINT8                               Nutrs;
  67   VOID                                *TrlMapping;
  68   VOID                                *UtpTmrlBase;
  69   UINT8                               Nutmrs;
  70   VOID                                *TmrlMapping;
  71
  72   UFS_EXPOSED_LUNS                    Luns;
  73 } UFS_PASS_THRU_PRIVATE_DATA;
  74
  75 #define UFS_TIMEOUT                   EFI_TIMER_PERIOD_SECONDS(3)
  76
  77 #define ROUNDUP8(x) (((x) % 8 == 0) ? (x) : ((x) / 8 + 1) * 8)
  78
  79 #define IS_ALIGNED(addr, size)        (((UINTN) (addr) & (size - 1)) == 0)
  80
  81 #define UFS_PASS_THRU_PRIVATE_DATA_FROM_THIS(a) \
  82   CR (a, \
  83       UFS_PASS_THRU_PRIVATE_DATA, \
  84       ExtScsiPassThru, \
  85       UFS_PASS_THRU_SIG \
  86       )
  87
  88 typedef struct _UFS_DEVICE_MANAGEMENT_REQUEST_PACKET {
  89   UINT64           Timeout;
  90   VOID             *InDataBuffer;
  91   VOID             *OutDataBuffer;
  92   UINT8            Opcode;
  93   UINT8            DescId;
  94   UINT8            Index;
  95   UINT8            Selector;
  96   UINT32           InTransferLength;
  97   UINT32           OutTransferLength;
  98   UINT8            DataDirection;
  99   UINT8            Ocs;
 100 } UFS_DEVICE_MANAGEMENT_REQUEST_PACKET;
 101
 102 //
 103 // function prototype
 104 //
 105 /**
 106   Tests to see if this driver supports a given controller. If a child device is provided,
 107   it further tests to see if this driver supports creating a handle for the specified child device.
 108
 109   This function checks to see if the driver specified by This supports the device specified by
 110   ControllerHandle. Drivers will typically use the device path attached to
 111   ControllerHandle and/or the services from the bus I/O abstraction attached to
 112   ControllerHandle to determine if the driver supports ControllerHandle. This function
 113   may be called many times during platform initialization. In order to reduce boot times, the tests
 114   performed by this function must be very small, and take as little time as possible to execute. This
 115   function must not change the state of any hardware devices, and this function must be aware that the
 116   device specified by ControllerHandle may already be managed by the same driver or a
 117   different driver. This function must match its calls to AllocatePages() with FreePages(),
 118   AllocatePool() with FreePool(), and OpenProtocol() with CloseProtocol().
 119   Since ControllerHandle may have been previously started by the same driver, if a protocol is
 120   already in the opened state, then it must not be closed with CloseProtocol(). This is required
 121   to guarantee the state of ControllerHandle is not modified by this function.
 122
 123   @param[in]  This                 A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance.
 124   @param[in]  ControllerHandle     The handle of the controller to test. This handle
 125                                    must support a protocol interface that supplies
 126                                    an I/O abstraction to the driver.
 127   @param[in]  RemainingDevicePath  A pointer to the remaining portion of a device path.  This
 128                                    parameter is ignored by device drivers, and is optional for bus
 129                                    drivers. For bus drivers, if this parameter is not NULL, then
 130                                    the bus driver must determine if the bus controller specified
 131                                    by ControllerHandle and the child controller specified
 132                                    by RemainingDevicePath are both supported by this
 133                                    bus driver.
 134
 135   @retval EFI_SUCCESS              The device specified by ControllerHandle and
 136                                    RemainingDevicePath is supported by the driver specified by This.
 137   @retval EFI_ALREADY_STARTED      The device specified by ControllerHandle and
 138                                    RemainingDevicePath is already being managed by the driver
 139                                    specified by This.
 140   @retval EFI_ACCESS_DENIED        The device specified by ControllerHandle and
 141                                    RemainingDevicePath is already being managed by a different
 142                                    driver or an application that requires exclusive access.
 143                                    Currently not implemented.
 144   @retval EFI_UNSUPPORTED          The device specified by ControllerHandle and
 145                                    RemainingDevicePath is not supported by the driver specified by This.
 146 **/
 147 EFI_STATUS
 148 EFIAPI
 149 UfsPassThruDriverBindingSupported (
 150   IN EFI_DRIVER_BINDING_PROTOCOL  *This,
 151   IN EFI_HANDLE                   Controller,
 152   IN EFI_DEVICE_PATH_PROTOCOL     *RemainingDevicePath
 153   );
 154
 155 /**
 156   Starts a device controller or a bus controller.
 157
 158   The Start() function is designed to be invoked from the EFI boot service ConnectController().
 159   As a result, much of the error checking on the parameters to Start() has been moved into this
 160   common boot service. It is legal to call Start() from other locations,
 161   but the following calling restrictions must be followed or the system behavior will not be deterministic.
 162   1. ControllerHandle must be a valid EFI_HANDLE.
 163   2. If RemainingDevicePath is not NULL, then it must be a pointer to a naturally aligned
 164      EFI_DEVICE_PATH_PROTOCOL.
 165   3. Prior to calling Start(), the Supported() function for the driver specified by This must
 166      have been called with the same calling parameters, and Supported() must have returned EFI_SUCCESS.
 167
 168   @param[in]  This                 A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance.
 169   @param[in]  ControllerHandle     The handle of the controller to start. This handle
 170                                    must support a protocol interface that supplies
 171                                    an I/O abstraction to the driver.
 172   @param[in]  RemainingDevicePath  A pointer to the remaining portion of a device path.  This
 173                                    parameter is ignored by device drivers, and is optional for bus
 174                                    drivers. For a bus driver, if this parameter is NULL, then handles
 175                                    for all the children of Controller are created by this driver.
 176                                    If this parameter is not NULL and the first Device Path Node is
 177                                    not the End of Device Path Node, then only the handle for the
 178                                    child device specified by the first Device Path Node of
 179                                    RemainingDevicePath is created by this driver.
 180                                    If the first Device Path Node of RemainingDevicePath is
 181                                    the End of Device Path Node, no child handle is created by this
 182                                    driver.
 183
 184   @retval EFI_SUCCESS              The device was started.
 185   @retval EFI_DEVICE_ERROR         The device could not be started due to a device error.Currently not implemented.
 186   @retval EFI_OUT_OF_RESOURCES     The request could not be completed due to a lack of resources.
 187   @retval Others                   The driver failded to start the device.
 188
 189 **/
 190 EFI_STATUS
 191 EFIAPI
 192 UfsPassThruDriverBindingStart (
 193   IN EFI_DRIVER_BINDING_PROTOCOL  *This,
 194   IN EFI_HANDLE                   Controller,
 195   IN EFI_DEVICE_PATH_PROTOCOL     *RemainingDevicePath
 196   );
 197
 198 /**
 199   Stops a device controller or a bus controller.
 200
 201   The Stop() function is designed to be invoked from the EFI boot service DisconnectController().
 202   As a result, much of the error checking on the parameters to Stop() has been moved
 203   into this common boot service. It is legal to call Stop() from other locations,
 204   but the following calling restrictions must be followed or the system behavior will not be deterministic.
 205   1. ControllerHandle must be a valid EFI_HANDLE that was used on a previous call to this
 206      same driver's Start() function.
 207   2. The first NumberOfChildren handles of ChildHandleBuffer must all be a valid
 208      EFI_HANDLE. In addition, all of these handles must have been created in this driver's
 209      Start() function, and the Start() function must have called OpenProtocol() on
 210      ControllerHandle with an Attribute of EFI_OPEN_PROTOCOL_BY_CHILD_CONTROLLER.
 211
 212   @param[in]  This              A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance.
 213   @param[in]  ControllerHandle  A handle to the device being stopped. The handle must
 214                                 support a bus specific I/O protocol for the driver
 215                                 to use to stop the device.
 216   @param[in]  NumberOfChildren  The number of child device handles in ChildHandleBuffer.
 217   @param[in]  ChildHandleBuffer An array of child handles to be freed. May be NULL
 218                                 if NumberOfChildren is 0.
 219
 220   @retval EFI_SUCCESS           The device was stopped.
 221   @retval EFI_DEVICE_ERROR      The device could not be stopped due to a device error.
 222
 223 **/
 224 EFI_STATUS
 225 EFIAPI
 226 UfsPassThruDriverBindingStop (
 227   IN  EFI_DRIVER_BINDING_PROTOCOL     *This,
 228   IN  EFI_HANDLE                      Controller,
 229   IN  UINTN                           NumberOfChildren,
 230   IN  EFI_HANDLE                      *ChildHandleBuffer
 231   );
 232
 233 //
 234 // EFI Component Name Functions
 235 //
 236 /**
 237   Retrieves a Unicode string that is the user readable name of the driver.
 238
 239   This function retrieves the user readable name of a driver in the form of a
 240   Unicode string. If the driver specified by This has a user readable name in
 241   the language specified by Language, then a pointer to the driver name is
 242   returned in DriverName, and EFI_SUCCESS is returned. If the driver specified
 243   by This does not support the language specified by Language,
 244   then EFI_UNSUPPORTED is returned.
 245
 246   @param  This[in]              A pointer to the EFI_COMPONENT_NAME2_PROTOCOL or
 247                                 EFI_COMPONENT_NAME_PROTOCOL instance.
 248
 249   @param  Language[in]          A pointer to a Null-terminated ASCII string
 250                                 array indicating the language. This is the
 251                                 language of the driver name that the caller is
 252                                 requesting, and it must match one of the
 253                                 languages specified in SupportedLanguages. The
 254                                 number of languages supported by a driver is up
 255                                 to the driver writer. Language is specified
 256                                 in RFC 4646 or ISO 639-2 language code format.
 257
 258   @param  DriverName[out]       A pointer to the Unicode string to return.
 259                                 This Unicode string is the name of the
 260                                 driver specified by This in the language
 261                                 specified by Language.
 262
 263   @retval EFI_SUCCESS           The Unicode string for the Driver specified by
 264                                 This and the language specified by Language was
 265                                 returned in DriverName.
 266
 267   @retval EFI_INVALID_PARAMETER Language is NULL.
 268
 269   @retval EFI_INVALID_PARAMETER DriverName is NULL.
 270
 271   @retval EFI_UNSUPPORTED       The driver specified by This does not support
 272                                 the language specified by Language.
 273
 274 **/
 275 EFI_STATUS
 276 EFIAPI
 277 UfsPassThruComponentNameGetDriverName (
 278   IN  EFI_COMPONENT_NAME_PROTOCOL  *This,
 279   IN  CHAR8                        *Language,
 280   OUT CHAR16                       **DriverName
 281   );
 282
 283
 284 /**
 285   Retrieves a Unicode string that is the user readable name of the controller
 286   that is being managed by a driver.
 287
 288   This function retrieves the user readable name of the controller specified by
 289   ControllerHandle and ChildHandle in the form of a Unicode string. If the
 290   driver specified by This has a user readable name in the language specified by
 291   Language, then a pointer to the controller name is returned in ControllerName,
 292   and EFI_SUCCESS is returned.  If the driver specified by This is not currently
 293   managing the controller specified by ControllerHandle and ChildHandle,
 294   then EFI_UNSUPPORTED is returned.  If the driver specified by This does not
 295   support the language specified by Language, then EFI_UNSUPPORTED is returned.
 296
 297   @param  This[in]              A pointer to the EFI_COMPONENT_NAME2_PROTOCOL or
 298                                 EFI_COMPONENT_NAME_PROTOCOL instance.
 299
 300   @param  ControllerHandle[in]  The handle of a controller that the driver
 301                                 specified by This is managing.  This handle
 302                                 specifies the controller whose name is to be
 303                                 returned.
 304
 305   @param  ChildHandle[in]       The handle of the child controller to retrieve
 306                                 the name of.  This is an optional parameter that
 307                                 may be NULL.  It will be NULL for device
 308                                 drivers.  It will also be NULL for a bus drivers
 309                                 that wish to retrieve the name of the bus
 310                                 controller.  It will not be NULL for a bus
 311                                 driver that wishes to retrieve the name of a
 312                                 child controller.
 313
 314   @param  Language[in]          A pointer to a Null-terminated ASCII string
 315                                 array indicating the language.  This is the
 316                                 language of the driver name that the caller is
 317                                 requesting, and it must match one of the
 318                                 languages specified in SupportedLanguages. The
 319                                 number of languages supported by a driver is up
 320                                 to the driver writer. Language is specified in
 321                                 RFC 4646 or ISO 639-2 language code format.
 322
 323   @param  ControllerName[out]   A pointer to the Unicode string to return.
 324                                 This Unicode string is the name of the
 325                                 controller specified by ControllerHandle and
 326                                 ChildHandle in the language specified by
 327                                 Language from the point of view of the driver
 328                                 specified by This.
 329
 330   @retval EFI_SUCCESS           The Unicode string for the user readable name in
 331                                 the language specified by Language for the
 332                                 driver specified by This was returned in
 333                                 DriverName.
 334
 335   @retval EFI_INVALID_PARAMETER ControllerHandle is NULL.
 336
 337   @retval EFI_INVALID_PARAMETER ChildHandle is not NULL and it is not a valid
 338                                 EFI_HANDLE.
 339
 340   @retval EFI_INVALID_PARAMETER Language is NULL.
 341
 342   @retval EFI_INVALID_PARAMETER ControllerName is NULL.
 343
 344   @retval EFI_UNSUPPORTED       The driver specified by This is not currently
 345                                 managing the controller specified by
 346                                 ControllerHandle and ChildHandle.
 347
 348   @retval EFI_UNSUPPORTED       The driver specified by This does not support
 349                                 the language specified by Language.
 350
 351 **/
 352 EFI_STATUS
 353 EFIAPI
 354 UfsPassThruComponentNameGetControllerName (
 355   IN  EFI_COMPONENT_NAME_PROTOCOL                     *This,
 356   IN  EFI_HANDLE                                      ControllerHandle,
 357   IN  EFI_HANDLE                                      ChildHandle        OPTIONAL,
 358   IN  CHAR8                                           *Language,
 359   OUT CHAR16                                          **ControllerName
 360   );
 361
 362 /**
 363   Sends a SCSI Request Packet to a SCSI device that is attached to the SCSI channel. This function
 364   supports both blocking I/O and nonblocking I/O. The blocking I/O functionality is required, and the
 365   nonblocking I/O functionality is optional.
 366
 367   @param  This    A pointer to the EFI_EXT_SCSI_PASS_THRU_PROTOCOL instance.
 368   @param  Target  The Target is an array of size TARGET_MAX_BYTES and it represents
 369                   the id of the SCSI device to send the SCSI Request Packet. Each
 370                   transport driver may choose to utilize a subset of this size to suit the needs
 371                   of transport target representation. For example, a Fibre Channel driver
 372                   may use only 8 bytes (WWN) to represent an FC target.
 373   @param  Lun     The LUN of the SCSI device to send the SCSI Request Packet.
 374   @param  Packet  A pointer to the SCSI Request Packet to send to the SCSI device
 375                   specified by Target and Lun.
 376   @param  Event   If nonblocking I/O is not supported then Event is ignored, and blocking
 377                   I/O is performed. If Event is NULL, then blocking I/O is performed. If
 378                   Event is not NULL and non blocking I/O is supported, then
 379                   nonblocking I/O is performed, and Event will be signaled when the
 380                   SCSI Request Packet completes.
 381
 382   @retval EFI_SUCCESS           The SCSI Request Packet was sent by the host. For bi-directional
 383                                 commands, InTransferLength bytes were transferred from
 384                                 InDataBuffer. For write and bi-directional commands,
 385                                 OutTransferLength bytes were transferred by
 386                                 OutDataBuffer.
 387   @retval EFI_BAD_BUFFER_SIZE   The SCSI Request Packet was not executed. The number of bytes that
 388                                 could be transferred is returned in InTransferLength. For write
 389                                 and bi-directional commands, OutTransferLength bytes were
 390                                 transferred by OutDataBuffer.
 391   @retval EFI_NOT_READY         The SCSI Request Packet could not be sent because there are too many
 392                                 SCSI Request Packets already queued. The caller may retry again later.
 393   @retval EFI_DEVICE_ERROR      A device error occurred while attempting to send the SCSI Request
 394                                 Packet.
 395   @retval EFI_INVALID_PARAMETER Target, Lun, or the contents of ScsiRequestPacket are invalid.
 396   @retval EFI_UNSUPPORTED       The command described by the SCSI Request Packet is not supported
 397                                 by the host adapter. This includes the case of Bi-directional SCSI
 398                                 commands not supported by the implementation. The SCSI Request
 399                                 Packet was not sent, so no additional status information is available.
 400   @retval EFI_TIMEOUT           A timeout occurred while waiting for the SCSI Request Packet to execute.
 401
 402 **/
 403 EFI_STATUS
 404 EFIAPI
 405 UfsPassThruPassThru (
 406   IN EFI_EXT_SCSI_PASS_THRU_PROTOCOL                    *This,
 407   IN UINT8                                              *Target,
 408   IN UINT64                                             Lun,
 409   IN OUT EFI_EXT_SCSI_PASS_THRU_SCSI_REQUEST_PACKET     *Packet,
 410   IN EFI_EVENT                                          Event OPTIONAL
 411   );
 412
 413 /**
 414   Used to retrieve the list of legal Target IDs and LUNs for SCSI devices on a SCSI channel. These
 415   can either be the list SCSI devices that are actually present on the SCSI channel, or the list of legal
 416   Target Ids and LUNs for the SCSI channel. Regardless, the caller of this function must probe the
 417   Target ID and LUN returned to see if a SCSI device is actually present at that location on the SCSI
 418   channel.
 419
 420   @param  This   A pointer to the EFI_EXT_SCSI_PASS_THRU_PROTOCOL instance.
 421   @param  Target On input, a pointer to the Target ID (an array of size
 422                  TARGET_MAX_BYTES) of a SCSI device present on the SCSI channel.
 423                  On output, a pointer to the Target ID (an array of
 424                  TARGET_MAX_BYTES) of the next SCSI device present on a SCSI
 425                  channel. An input value of 0xF(all bytes in the array are 0xF) in the
 426                  Target array retrieves the Target ID of the first SCSI device present on a
 427                  SCSI channel.
 428   @param  Lun    On input, a pointer to the LUN of a SCSI device present on the SCSI
 429                  channel. On output, a pointer to the LUN of the next SCSI device present
 430                  on a SCSI channel.
 431
 432   @retval EFI_SUCCESS           The Target ID and LUN of the next SCSI device on the SCSI
 433                                 channel was returned in Target and Lun.
 434   @retval EFI_INVALID_PARAMETER Target array is not all 0xF, and Target and Lun were
 435                                 not returned on a previous call to GetNextTargetLun().
 436   @retval EFI_NOT_FOUND         There are no more SCSI devices on this SCSI channel.
 437
 438 **/
 439 EFI_STATUS
 440 EFIAPI
 441 UfsPassThruGetNextTargetLun (
 442   IN  EFI_EXT_SCSI_PASS_THRU_PROTOCOL    *This,
 443   IN OUT UINT8                           **Target,
 444   IN OUT UINT64                          *Lun
 445   );
 446
 447 /**
 448   Used to allocate and build a device path node for a SCSI device on a SCSI channel.
 449
 450   @param  This       A pointer to the EFI_EXT_SCSI_PASS_THRU_PROTOCOL instance.
 451   @param  Target     The Target is an array of size TARGET_MAX_BYTES and it specifies the
 452                      Target ID of the SCSI device for which a device path node is to be
 453                      allocated and built. Transport drivers may chose to utilize a subset of
 454                      this size to suit the representation of targets. For example, a Fibre
 455                      Channel driver may use only 8 bytes (WWN) in the array to represent a
 456                      FC target.
 457   @param  Lun        The LUN of the SCSI device for which a device path node is to be
 458                      allocated and built.
 459   @param  DevicePath A pointer to a single device path node that describes the SCSI device
 460                      specified by Target and Lun. This function is responsible for
 461                      allocating the buffer DevicePath with the boot service
 462                      AllocatePool(). It is the caller's responsibility to free
 463                      DevicePath when the caller is finished with DevicePath.
 464
 465   @retval EFI_SUCCESS           The device path node that describes the SCSI device specified by
 466                                 Target and Lun was allocated and returned in
 467                                 DevicePath.
 468   @retval EFI_INVALID_PARAMETER DevicePath is NULL.
 469   @retval EFI_NOT_FOUND         The SCSI devices specified by Target and Lun does not exist
 470                                 on the SCSI channel.
 471   @retval EFI_OUT_OF_RESOURCES  There are not enough resources to allocate DevicePath.
 472
 473 **/
 474 EFI_STATUS
 475 EFIAPI
 476 UfsPassThruBuildDevicePath (
 477   IN     EFI_EXT_SCSI_PASS_THRU_PROTOCOL    *This,
 478   IN     UINT8                              *Target,
 479   IN     UINT64                             Lun,
 480   IN OUT EFI_DEVICE_PATH_PROTOCOL           **DevicePath
 481   );
 482
 483 /**
 484   Used to translate a device path node to a Target ID and LUN.
 485
 486   @param  This       A pointer to the EFI_EXT_SCSI_PASS_THRU_PROTOCOL instance.
 487   @param  DevicePath A pointer to a single device path node that describes the SCSI device
 488                      on the SCSI channel.
 489   @param  Target     A pointer to the Target Array which represents the ID of a SCSI device
 490                      on the SCSI channel.
 491   @param  Lun        A pointer to the LUN of a SCSI device on the SCSI channel.
 492
 493   @retval EFI_SUCCESS           DevicePath was successfully translated to a Target ID and
 494                                 LUN, and they were returned in Target and Lun.
 495   @retval EFI_INVALID_PARAMETER DevicePath or Target or Lun is NULL.
 496   @retval EFI_NOT_FOUND         A valid translation from DevicePath to a Target ID and LUN
 497                                 does not exist.
 498   @retval EFI_UNSUPPORTED       This driver does not support the device path node type in
 499                                  DevicePath.
 500
 501 **/
 502 EFI_STATUS
 503 EFIAPI
 504 UfsPassThruGetTargetLun (
 505   IN  EFI_EXT_SCSI_PASS_THRU_PROTOCOL    *This,
 506   IN  EFI_DEVICE_PATH_PROTOCOL           *DevicePath,
 507   OUT UINT8                              **Target,
 508   OUT UINT64                             *Lun
 509   );
 510
 511 /**
 512   Resets a SCSI channel. This operation resets all the SCSI devices connected to the SCSI channel.
 513
 514   @param  This A pointer to the EFI_EXT_SCSI_PASS_THRU_PROTOCOL instance.
 515
 516   @retval EFI_SUCCESS      The SCSI channel was reset.
 517   @retval EFI_DEVICE_ERROR A device error occurred while attempting to reset the SCSI channel.
 518   @retval EFI_TIMEOUT      A timeout occurred while attempting to reset the SCSI channel.
 519   @retval EFI_UNSUPPORTED  The SCSI channel does not support a channel reset operation.
 520
 521 **/
 522 EFI_STATUS
 523 EFIAPI
 524 UfsPassThruResetChannel (
 525   IN  EFI_EXT_SCSI_PASS_THRU_PROTOCOL   *This
 526   );
 527
 528 /**
 529   Resets a SCSI logical unit that is connected to a SCSI channel.
 530
 531   @param  This   A pointer to the EFI_EXT_SCSI_PASS_THRU_PROTOCOL instance.
 532   @param  Target The Target is an array of size TARGET_MAX_BYTE and it represents the
 533                  target port ID of the SCSI device containing the SCSI logical unit to
 534                  reset. Transport drivers may chose to utilize a subset of this array to suit
 535                  the representation of their targets.
 536   @param  Lun    The LUN of the SCSI device to reset.
 537
 538   @retval EFI_SUCCESS           The SCSI device specified by Target and Lun was reset.
 539   @retval EFI_INVALID_PARAMETER Target or Lun is NULL.
 540   @retval EFI_TIMEOUT           A timeout occurred while attempting to reset the SCSI device
 541                                 specified by Target and Lun.
 542   @retval EFI_UNSUPPORTED       The SCSI channel does not support a target reset operation.
 543   @retval EFI_DEVICE_ERROR      A device error occurred while attempting to reset the SCSI device
 544                                  specified by Target and Lun.
 545
 546 **/
 547 EFI_STATUS
 548 EFIAPI
 549 UfsPassThruResetTargetLun (
 550   IN EFI_EXT_SCSI_PASS_THRU_PROTOCOL    *This,
 551   IN UINT8                              *Target,
 552   IN UINT64                             Lun
 553   );
 554
 555 /**
 556   Used to retrieve the list of legal Target IDs for SCSI devices on a SCSI channel. These can either
 557   be the list SCSI devices that are actually present on the SCSI channel, or the list of legal Target IDs
 558   for the SCSI channel. Regardless, the caller of this function must probe the Target ID returned to
 559   see if a SCSI device is actually present at that location on the SCSI channel.
 560
 561   @param  This   A pointer to the EFI_EXT_SCSI_PASS_THRU_PROTOCOL instance.
 562   @param  Target (TARGET_MAX_BYTES) of a SCSI device present on the SCSI channel.
 563                  On output, a pointer to the Target ID (an array of
 564                  TARGET_MAX_BYTES) of the next SCSI device present on a SCSI
 565                  channel. An input value of 0xF(all bytes in the array are 0xF) in the
 566                  Target array retrieves the Target ID of the first SCSI device present on a
 567                  SCSI channel.
 568
 569   @retval EFI_SUCCESS           The Target ID of the next SCSI device on the SCSI
 570                                 channel was returned in Target.
 571   @retval EFI_INVALID_PARAMETER Target or Lun is NULL.
 572   @retval EFI_TIMEOUT           Target array is not all 0xF, and Target was not
 573                                 returned on a previous call to GetNextTarget().
 574   @retval EFI_NOT_FOUND         There are no more SCSI devices on this SCSI channel.
 575
 576 **/
 577 EFI_STATUS
 578 EFIAPI
 579 UfsPassThruGetNextTarget (
 580   IN  EFI_EXT_SCSI_PASS_THRU_PROTOCOL    *This,
 581   IN OUT UINT8                           **Target
 582   );
 583
 584 /**
 585   Sends a UFS-supported SCSI Request Packet to a UFS device that is attached to the UFS host controller.
 586
 587   @param[in]      Private       The pointer to the UFS_PASS_THRU_PRIVATE_DATA data structure.
 588   @param[in]      Lun           The LUN of the UFS device to send the SCSI Request Packet.
 589   @param[in, out] Packet        A pointer to the SCSI Request Packet to send to a specified Lun of the
 590                                 UFS device.
 591
 592   @retval EFI_SUCCESS           The SCSI Request Packet was sent by the host. For bi-directional
 593                                 commands, InTransferLength bytes were transferred from
 594                                 InDataBuffer. For write and bi-directional commands,
 595                                 OutTransferLength bytes were transferred by
 596                                 OutDataBuffer.
 597   @retval EFI_DEVICE_ERROR      A device error occurred while attempting to send the SCSI Request
 598                                 Packet.
 599   @retval EFI_OUT_OF_RESOURCES  The resource for transfer is not available.
 600   @retval EFI_TIMEOUT           A timeout occurred while waiting for the SCSI Request Packet to execute.
 601
 602 **/
 603 EFI_STATUS
 604 UfsExecScsiCmds (
 605   IN     UFS_PASS_THRU_PRIVATE_DATA                  *Private,
 606   IN     UINT8                                       Lun,
 607   IN OUT EFI_EXT_SCSI_PASS_THRU_SCSI_REQUEST_PACKET  *Packet
 608   );
 609
 610 /**
 611   Initialize the UFS host controller.
 612
 613   @param[in] Private                 The pointer to the NVME_CONTROLLER_PRIVATE_DATA data structure.
 614
 615   @retval EFI_SUCCESS                The NVM Express Controller is initialized successfully.
 616   @retval Others                     A device error occurred while initializing the controller.
 617
 618 **/
 619 EFI_STATUS
 620 UfsControllerInit (
 621   IN  UFS_PASS_THRU_PRIVATE_DATA     *Private
 622   );
 623
 624 /**
 625   Stop the UFS host controller.
 626
 627   @param[in] Private                 The pointer to the UFS_PASS_THRU_PRIVATE_DATA data structure.
 628
 629   @retval EFI_SUCCESS                The Ufs Host Controller is stopped successfully.
 630   @retval Others                     A device error occurred while stopping the controller.
 631
 632 **/
 633 EFI_STATUS
 634 UfsControllerStop (
 635   IN  UFS_PASS_THRU_PRIVATE_DATA     *Private
 636   );
 637
 638 /**
 639   Allocate common buffer for host and UFS bus master access simultaneously.
 640
 641   @param[in]  Private                The pointer to the UFS_PASS_THRU_PRIVATE_DATA data structure.
 642   @param[in]  Size                   The length of buffer to be allocated.
 643   @param[out] CmdDescHost            A pointer to store the base system memory address of the allocated range.
 644   @param[out] CmdDescPhyAddr         The resulting map address for the UFS bus master to use to access the hosts CmdDescHost.
 645   @param[out] CmdDescMapping         A resulting value to pass to Unmap().
 646
 647   @retval EFI_SUCCESS                The common buffer was allocated successfully.
 648   @retval EFI_DEVICE_ERROR           The allocation fails.
 649   @retval EFI_OUT_OF_RESOURCES       The memory resource is insufficient.
 650
 651 **/
 652 EFI_STATUS
 653 UfsAllocateAlignCommonBuffer (
 654   IN     UFS_PASS_THRU_PRIVATE_DATA    *Private,
 655   IN     UINTN                         Size,
 656      OUT VOID                          **CmdDescHost,
 657      OUT EFI_PHYSICAL_ADDRESS          *CmdDescPhyAddr,
 658      OUT VOID                          **CmdDescMapping
 659   );
 660
 661 /**
 662   Set specified flag to 1 on a UFS device.
 663
 664   @param[in]  Private           The pointer to the UFS_PASS_THRU_PRIVATE_DATA data structure.
 665   @param[in]  FlagId            The ID of flag to be set.
 666
 667   @retval EFI_SUCCESS           The flag was set successfully.
 668   @retval EFI_DEVICE_ERROR      A device error occurred while attempting to set the flag.
 669   @retval EFI_TIMEOUT           A timeout occurred while waiting for the completion of setting the flag.
 670
 671 **/
 672 EFI_STATUS
 673 UfsSetFlag (
 674   IN  UFS_PASS_THRU_PRIVATE_DATA   *Private,
 675   IN  UINT8                        FlagId
 676   );
 677
 678 /**
 679   Read or write specified device descriptor of a UFS device.
 680
 681   @param[in]      Private       The pointer to the UFS_PASS_THRU_PRIVATE_DATA data structure.
 682   @param[in]      Read          The boolean variable to show r/w direction.
 683   @param[in]      DescId        The ID of device descriptor.
 684   @param[in]      Index         The Index of device descriptor.
 685   @param[in]      Selector      The Selector of device descriptor.
 686   @param[in, out] Descriptor    The buffer of device descriptor to be read or written.
 687   @param[in]      DescSize      The size of device descriptor buffer.
 688
 689   @retval EFI_SUCCESS           The device descriptor was read/written successfully.
 690   @retval EFI_DEVICE_ERROR      A device error occurred while attempting to r/w the device descriptor.
 691   @retval EFI_TIMEOUT           A timeout occurred while waiting for the completion of r/w the device descriptor.
 692
 693 **/
 694 EFI_STATUS
 695 UfsRwDeviceDesc (
 696   IN     UFS_PASS_THRU_PRIVATE_DATA   *Private,
 697   IN     BOOLEAN                      Read,
 698   IN     UINT8                        DescId,
 699   IN     UINT8                        Index,
 700   IN     UINT8                        Selector,
 701   IN OUT VOID                         *Descriptor,
 702   IN     UINT32                       DescSize
 703   );
 704
 705 /**
 706   Sends NOP IN cmd to a UFS device for initialization process request.
 707   For more details, please refer to UFS 2.0 spec Figure 13.3.
 708
 709   @param[in]  Private           The pointer to the UFS_PASS_THRU_PRIVATE_DATA data structure.
 710
 711   @retval EFI_SUCCESS           The NOP IN command was sent by the host. The NOP OUT response was
 712                                 received successfully.
 713   @retval EFI_DEVICE_ERROR      A device error occurred while attempting to execute NOP IN command.
 714   @retval EFI_OUT_OF_RESOURCES  The resource for transfer is not available.
 715   @retval EFI_TIMEOUT           A timeout occurred while waiting for the NOP IN command to execute.
 716
 717 **/
 718 EFI_STATUS
 719 UfsExecNopCmds (
 720   IN  UFS_PASS_THRU_PRIVATE_DATA       *Private
 721   );
 722
 723 extern GLOBAL_REMOVE_IF_UNREFERENCED EFI_COMPONENT_NAME_PROTOCOL  gUfsPassThruComponentName;
 724 extern GLOBAL_REMOVE_IF_UNREFERENCED EFI_COMPONENT_NAME2_PROTOCOL gUfsPassThruComponentName2;
 725 extern EFI_DRIVER_BINDING_PROTOCOL   gUfsPassThruDriverBinding;
 726
 727 #endif