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