MdeModulePkg/Bus/Ufs/UfsPassThruDxe/UfsPassThru.h

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