MdeModulePkg/Bus/Ufs/UfsPassThruDxe/UfsPassThru.h

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