MdeModulePkg/Bus/Ata/AhciPei/AhciPei.h

   1 /** @file
   2   The AhciPei driver is used to manage ATA hard disk device working under AHCI
   3   mode at PEI phase.
   4
   5   Copyright (c) 2019, Intel Corporation. All rights reserved.<BR>
   6
   7   SPDX-License-Identifier: BSD-2-Clause-Patent
   8
   9 **/
  10
  11 #ifndef _AHCI_PEI_H_
  12 #define _AHCI_PEI_H_
  13
  14 #include <PiPei.h>
  15
  16 #include <IndustryStandard/Atapi.h>
  17
  18 #include <Ppi/AtaAhciController.h>
  19 #include <Ppi/IoMmu.h>
  20 #include <Ppi/EndOfPeiPhase.h>
  21 #include <Ppi/AtaPassThru.h>
  22 #include <Ppi/BlockIo2.h>
  23 #include <Ppi/StorageSecurityCommand.h>
  24
  25 #include <Library/DebugLib.h>
  26 #include <Library/PeiServicesLib.h>
  27 #include <Library/MemoryAllocationLib.h>
  28 #include <Library/BaseMemoryLib.h>
  29 #include <Library/IoLib.h>
  30 #include <Library/TimerLib.h>
  31
  32 //
  33 // Structure forward declarations
  34 //
  35 typedef struct _PEI_AHCI_CONTROLLER_PRIVATE_DATA  PEI_AHCI_CONTROLLER_PRIVATE_DATA;
  36
  37 #include "AhciPeiPassThru.h"
  38 #include "AhciPeiStorageSecurity.h"
  39
  40 //
  41 // ATA AHCI driver implementation related definitions
  42 //
  43 //
  44 // Refer SATA1.0a spec section 5.2, the Phy detection time should be less than 10ms.
  45 // The value is in millisecond units. Add a bit of margin for robustness.
  46 //
  47 #define AHCI_BUS_PHY_DETECT_TIMEOUT            15
  48 //
  49 // Refer SATA1.0a spec, the bus reset time should be less than 1s.
  50 // The value is in 100ns units.
  51 //
  52 #define AHCI_PEI_RESET_TIMEOUT                 10000000
  53 //
  54 // Time out Value for ATA pass through protocol, in 100ns units.
  55 //
  56 #define ATA_TIMEOUT                            30000000
  57 //
  58 // Maximal number of Physical Region Descriptor Table entries supported.
  59 //
  60 #define AHCI_MAX_PRDT_NUMBER                   8
  61
  62 #define AHCI_CAPABILITY_OFFSET                 0x0000
  63 #define   AHCI_CAP_SAM                         BIT18
  64 #define   AHCI_CAP_SSS                         BIT27
  65
  66 #define AHCI_GHC_OFFSET                        0x0004
  67 #define   AHCI_GHC_RESET                       BIT0
  68 #define   AHCI_GHC_ENABLE                      BIT31
  69
  70 #define AHCI_IS_OFFSET                         0x0008
  71 #define AHCI_PI_OFFSET                         0x000C
  72
  73 #define AHCI_MAX_PORTS                         32
  74
  75 typedef struct {
  76   UINT32  Lower32;
  77   UINT32  Upper32;
  78 } DATA_32;
  79
  80 typedef union {
  81   DATA_32   Uint32;
  82   UINT64    Uint64;
  83 } DATA_64;
  84
  85 #define AHCI_ATAPI_SIG_MASK                    0xFFFF0000
  86 #define AHCI_ATA_DEVICE_SIG                    0x00000000
  87
  88 //
  89 // Each PRDT entry can point to a memory block up to 4M byte
  90 //
  91 #define AHCI_MAX_DATA_PER_PRDT                 0x400000
  92
  93 #define AHCI_FIS_REGISTER_H2D                  0x27      //Register FIS - Host to Device
  94 #define   AHCI_FIS_REGISTER_H2D_LENGTH         20
  95 #define AHCI_FIS_REGISTER_D2H                  0x34      //Register FIS - Device to Host
  96 #define AHCI_FIS_PIO_SETUP                     0x5F      //PIO Setup FIS - Device to Host
  97
  98 #define AHCI_D2H_FIS_OFFSET                    0x40
  99 #define AHCI_PIO_FIS_OFFSET                    0x20
 100 #define AHCI_FIS_TYPE_MASK                     0xFF
 101
 102 //
 103 // Port register
 104 //
 105 #define AHCI_PORT_START                        0x0100
 106 #define AHCI_PORT_REG_WIDTH                    0x0080
 107 #define AHCI_PORT_CLB                          0x0000
 108 #define AHCI_PORT_CLBU                         0x0004
 109 #define AHCI_PORT_FB                           0x0008
 110 #define AHCI_PORT_FBU                          0x000C
 111 #define AHCI_PORT_IS                           0x0010
 112 #define AHCI_PORT_IE                           0x0014
 113 #define AHCI_PORT_CMD                          0x0018
 114 #define   AHCI_PORT_CMD_ST                     BIT0
 115 #define   AHCI_PORT_CMD_SUD                    BIT1
 116 #define   AHCI_PORT_CMD_POD                    BIT2
 117 #define   AHCI_PORT_CMD_CLO                    BIT3
 118 #define   AHCI_PORT_CMD_FRE                    BIT4
 119 #define   AHCI_PORT_CMD_FR                     BIT14
 120 #define   AHCI_PORT_CMD_CR                     BIT15
 121 #define   AHCI_PORT_CMD_CPD                    BIT20
 122 #define   AHCI_PORT_CMD_ATAPI                  BIT24
 123 #define   AHCI_PORT_CMD_DLAE                   BIT25
 124 #define   AHCI_PORT_CMD_ALPE                   BIT26
 125 #define   AHCI_PORT_CMD_ACTIVE                 (1 << 28)
 126 #define   AHCI_PORT_CMD_ICC_MASK               (BIT28 | BIT29 | BIT30 | BIT31)
 127
 128 #define AHCI_PORT_TFD                          0x0020
 129 #define   AHCI_PORT_TFD_ERR                    BIT0
 130 #define   AHCI_PORT_TFD_DRQ                    BIT3
 131 #define   AHCI_PORT_TFD_BSY                    BIT7
 132 #define   AHCI_PORT_TFD_MASK                   (BIT7 | BIT3 | BIT0)
 133
 134 #define AHCI_PORT_SIG                          0x0024
 135 #define AHCI_PORT_SSTS                         0x0028
 136 #define   AHCI_PORT_SSTS_DET_MASK              0x000F
 137 #define   AHCI_PORT_SSTS_DET                   0x0001
 138 #define   AHCI_PORT_SSTS_DET_PCE               0x0003
 139
 140 #define AHCI_PORT_SCTL                         0x002C
 141 #define   AHCI_PORT_SCTL_IPM_INIT              0x0300
 142
 143 #define AHCI_PORT_SERR                         0x0030
 144 #define AHCI_PORT_CI                           0x0038
 145
 146 #define IS_ALIGNED(addr, size)                 (((UINTN) (addr) & (size - 1)) == 0)
 147 #define TIMER_PERIOD_SECONDS(Seconds)          MultU64x32((UINT64)(Seconds), 10000000)
 148
 149 #pragma pack(1)
 150
 151 //
 152 // Received FIS structure
 153 //
 154 typedef struct {
 155   UINT8     AhciDmaSetupFis[0x1C];         // Dma Setup Fis: offset 0x00
 156   UINT8     AhciDmaSetupFisRsvd[0x04];
 157   UINT8     AhciPioSetupFis[0x14];         // Pio Setup Fis: offset 0x20
 158   UINT8     AhciPioSetupFisRsvd[0x0C];
 159   UINT8     AhciD2HRegisterFis[0x14];      // D2H Register Fis: offset 0x40
 160   UINT8     AhciD2HRegisterFisRsvd[0x04];
 161   UINT64    AhciSetDeviceBitsFis;          // Set Device Bits Fix: offset 0x58
 162   UINT8     AhciUnknownFis[0x40];          // Unkonwn Fis: offset 0x60
 163   UINT8     AhciUnknownFisRsvd[0x60];
 164 } EFI_AHCI_RECEIVED_FIS;
 165
 166 //
 167 // Command List structure includes total 32 entries.
 168 // The entry Data structure is listed at the following.
 169 //
 170 typedef struct {
 171   UINT32    AhciCmdCfl:5;      //Command FIS Length
 172   UINT32    AhciCmdA:1;        //ATAPI
 173   UINT32    AhciCmdW:1;        //Write
 174   UINT32    AhciCmdP:1;        //Prefetchable
 175   UINT32    AhciCmdR:1;        //Reset
 176   UINT32    AhciCmdB:1;        //BIST
 177   UINT32    AhciCmdC:1;        //Clear Busy upon R_OK
 178   UINT32    AhciCmdRsvd:1;
 179   UINT32    AhciCmdPmp:4;      //Port Multiplier Port
 180   UINT32    AhciCmdPrdtl:16;   //Physical Region Descriptor Table Length
 181   UINT32    AhciCmdPrdbc;      //Physical Region Descriptor Byte Count
 182   UINT32    AhciCmdCtba;       //Command Table Descriptor Base Address
 183   UINT32    AhciCmdCtbau;      //Command Table Descriptor Base Address Upper 32-BITs
 184   UINT32    AhciCmdRsvd1[4];
 185 } EFI_AHCI_COMMAND_LIST;
 186
 187 //
 188 // This is a software constructed FIS.
 189 // For Data transfer operations, this is the H2D Register FIS format as
 190 // specified in the Serial ATA Revision 2.6 specification.
 191 //
 192 typedef struct {
 193   UINT8     AhciCFisType;
 194   UINT8     AhciCFisPmNum:4;
 195   UINT8     AhciCFisRsvd:1;
 196   UINT8     AhciCFisRsvd1:1;
 197   UINT8     AhciCFisRsvd2:1;
 198   UINT8     AhciCFisCmdInd:1;
 199   UINT8     AhciCFisCmd;
 200   UINT8     AhciCFisFeature;
 201   UINT8     AhciCFisSecNum;
 202   UINT8     AhciCFisClyLow;
 203   UINT8     AhciCFisClyHigh;
 204   UINT8     AhciCFisDevHead;
 205   UINT8     AhciCFisSecNumExp;
 206   UINT8     AhciCFisClyLowExp;
 207   UINT8     AhciCFisClyHighExp;
 208   UINT8     AhciCFisFeatureExp;
 209   UINT8     AhciCFisSecCount;
 210   UINT8     AhciCFisSecCountExp;
 211   UINT8     AhciCFisRsvd3;
 212   UINT8     AhciCFisControl;
 213   UINT8     AhciCFisRsvd4[4];
 214   UINT8     AhciCFisRsvd5[44];
 215 } EFI_AHCI_COMMAND_FIS;
 216
 217 //
 218 // ACMD: ATAPI command (12 or 16 bytes)
 219 //
 220 typedef struct {
 221   UINT8    AtapiCmd[0x10];
 222 } EFI_AHCI_ATAPI_COMMAND;
 223
 224 //
 225 // Physical Region Descriptor Table includes up to 65535 entries
 226 // The entry data structure is listed at the following.
 227 // the actual entry number comes from the PRDTL field in the command
 228 // list entry for this command slot.
 229 //
 230 typedef struct {
 231   UINT32    AhciPrdtDba;       //Data Base Address
 232   UINT32    AhciPrdtDbau;      //Data Base Address Upper 32-BITs
 233   UINT32    AhciPrdtRsvd;
 234   UINT32    AhciPrdtDbc:22;    //Data Byte Count
 235   UINT32    AhciPrdtRsvd1:9;
 236   UINT32    AhciPrdtIoc:1;     //Interrupt on Completion
 237 } EFI_AHCI_COMMAND_PRDT;
 238
 239 //
 240 // Command table Data strucute which is pointed to by the entry in the command list
 241 //
 242 typedef struct {
 243   EFI_AHCI_COMMAND_FIS      CommandFis;       // A software constructed FIS.
 244   EFI_AHCI_ATAPI_COMMAND    AtapiCmd;         // 12 or 16 bytes ATAPI cmd.
 245   UINT8                     Reserved[0x30];
 246   //
 247   // The scatter/gather list for Data transfer.
 248   //
 249   EFI_AHCI_COMMAND_PRDT     PrdtTable[AHCI_MAX_PRDT_NUMBER];
 250 } EFI_AHCI_COMMAND_TABLE;
 251
 252 #pragma pack()
 253
 254 typedef struct {
 255   EFI_AHCI_RECEIVED_FIS     *AhciRFis;
 256   EFI_AHCI_COMMAND_LIST     *AhciCmdList;
 257   EFI_AHCI_COMMAND_TABLE    *AhciCmdTable;
 258   UINTN                     MaxRFisSize;
 259   UINTN                     MaxCmdListSize;
 260   UINTN                     MaxCmdTableSize;
 261   VOID                      *AhciRFisMap;
 262   VOID                      *AhciCmdListMap;
 263   VOID                      *AhciCmdTableMap;
 264 } EFI_AHCI_REGISTERS;
 265
 266 //
 267 // Unique signature for AHCI ATA device information structure.
 268 //
 269 #define AHCI_PEI_ATA_DEVICE_DATA_SIGNATURE    SIGNATURE_32 ('A', 'P', 'A', 'D')
 270
 271 //
 272 // AHCI mode device information structure.
 273 //
 274 typedef struct {
 275   UINT32                              Signature;
 276   LIST_ENTRY                          Link;
 277
 278   UINT16                              Port;
 279   UINT16                              PortMultiplier;
 280   UINT8                               FisIndex;
 281   UINTN                               DeviceIndex;
 282   ATA_IDENTIFY_DATA                   *IdentifyData;
 283
 284   BOOLEAN                             Lba48Bit;
 285   BOOLEAN                             TrustComputing;
 286   UINTN                               TrustComputingDeviceIndex;
 287   EFI_PEI_BLOCK_IO2_MEDIA             Media;
 288
 289   PEI_AHCI_CONTROLLER_PRIVATE_DATA    *Private;
 290 } PEI_AHCI_ATA_DEVICE_DATA;
 291
 292 #define AHCI_PEI_ATA_DEVICE_INFO_FROM_THIS(a)  \
 293   CR (a,                                       \
 294       PEI_AHCI_ATA_DEVICE_DATA,                \
 295       Link,                                    \
 296       AHCI_PEI_ATA_DEVICE_DATA_SIGNATURE       \
 297       );
 298
 299 //
 300 // Unique signature for private data structure.
 301 //
 302 #define AHCI_PEI_CONTROLLER_PRIVATE_DATA_SIGNATURE    SIGNATURE_32 ('A','P','C','P')
 303
 304 //
 305 // ATA AHCI controller private data structure.
 306 //
 307 struct _PEI_AHCI_CONTROLLER_PRIVATE_DATA {
 308   UINT32                                Signature;
 309   UINTN                                 MmioBase;
 310   UINTN                                 DevicePathLength;
 311   EFI_DEVICE_PATH_PROTOCOL              *DevicePath;
 312
 313   EFI_ATA_PASS_THRU_MODE                AtaPassThruMode;
 314   EDKII_PEI_ATA_PASS_THRU_PPI           AtaPassThruPpi;
 315   EDKII_PEI_STORAGE_SECURITY_CMD_PPI    StorageSecurityPpi;
 316   EFI_PEI_PPI_DESCRIPTOR                AtaPassThruPpiList;
 317   EFI_PEI_PPI_DESCRIPTOR                BlkIoPpiList;
 318   EFI_PEI_PPI_DESCRIPTOR                BlkIo2PpiList;
 319   EFI_PEI_PPI_DESCRIPTOR                StorageSecurityPpiList;
 320   EFI_PEI_NOTIFY_DESCRIPTOR             EndOfPeiNotifyList;
 321
 322   EFI_AHCI_REGISTERS                    AhciRegisters;
 323
 324   UINT32                                PortBitMap;
 325   UINT32                                ActiveDevices;
 326   UINT32                                TrustComputingDevices;
 327   LIST_ENTRY                            DeviceList;
 328
 329   UINT16                                PreviousPort;
 330   UINT16                                PreviousPortMultiplier;
 331 };
 332
 333 #define GET_AHCI_PEIM_HC_PRIVATE_DATA_FROM_THIS_PASS_THRU(a)           \
 334   CR (a, PEI_AHCI_CONTROLLER_PRIVATE_DATA, AtaPassThruPpi, AHCI_PEI_CONTROLLER_PRIVATE_DATA_SIGNATURE)
 335 #define GET_AHCI_PEIM_HC_PRIVATE_DATA_FROM_THIS_BLKIO(a)               \
 336   CR (a, PEI_AHCI_CONTROLLER_PRIVATE_DATA, BlkIoPpi, AHCI_PEI_CONTROLLER_PRIVATE_DATA_SIGNATURE)
 337 #define GET_AHCI_PEIM_HC_PRIVATE_DATA_FROM_THIS_BLKIO2(a)              \
 338   CR (a, PEI_AHCI_CONTROLLER_PRIVATE_DATA, BlkIo2Ppi, AHCI_PEI_CONTROLLER_PRIVATE_DATA_SIGNATURE)
 339 #define GET_AHCI_PEIM_HC_PRIVATE_DATA_FROM_THIS_STROAGE_SECURITY(a)    \
 340   CR (a, PEI_AHCI_CONTROLLER_PRIVATE_DATA, StorageSecurityPpi, AHCI_PEI_CONTROLLER_PRIVATE_DATA_SIGNATURE)
 341 #define GET_AHCI_PEIM_HC_PRIVATE_DATA_FROM_THIS_NOTIFY(a)              \
 342   CR (a, PEI_AHCI_CONTROLLER_PRIVATE_DATA, EndOfPeiNotifyList, AHCI_PEI_CONTROLLER_PRIVATE_DATA_SIGNATURE)
 343
 344 //
 345 // Global variables
 346 //
 347 extern UINT32    mMaxTransferBlockNumber[2];
 348
 349 //
 350 // Internal functions
 351 //
 352
 353 /**
 354   Allocates pages that are suitable for an OperationBusMasterCommonBuffer or
 355   OperationBusMasterCommonBuffer64 mapping.
 356
 357   @param  Pages                 The number of pages to allocate.
 358   @param  HostAddress           A pointer to store the base system memory address of the
 359                                 allocated range.
 360   @param  DeviceAddress         The resulting map address for the bus master PCI controller to use to
 361                                 access the hosts HostAddress.
 362   @param  Mapping               A resulting value to pass to Unmap().
 363
 364   @retval EFI_SUCCESS           The requested memory pages were allocated.
 365   @retval EFI_UNSUPPORTED       Attributes is unsupported. The only legal attribute bits are
 366                                 MEMORY_WRITE_COMBINE and MEMORY_CACHED.
 367   @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
 368   @retval EFI_OUT_OF_RESOURCES  The memory pages could not be allocated.
 369
 370 **/
 371 EFI_STATUS
 372 IoMmuAllocateBuffer (
 373   IN UINTN                  Pages,
 374   OUT VOID                  **HostAddress,
 375   OUT EFI_PHYSICAL_ADDRESS  *DeviceAddress,
 376   OUT VOID                  **Mapping
 377   );
 378
 379 /**
 380   Frees memory that was allocated with AllocateBuffer().
 381
 382   @param  Pages                 The number of pages to free.
 383   @param  HostAddress           The base system memory address of the allocated range.
 384   @param  Mapping               The mapping value returned from Map().
 385
 386   @retval EFI_SUCCESS           The requested memory pages were freed.
 387   @retval EFI_INVALID_PARAMETER The memory range specified by HostAddress and Pages
 388                                 was not allocated with AllocateBuffer().
 389
 390 **/
 391 EFI_STATUS
 392 IoMmuFreeBuffer (
 393   IN UINTN                  Pages,
 394   IN VOID                   *HostAddress,
 395   IN VOID                   *Mapping
 396   );
 397
 398 /**
 399   Provides the controller-specific addresses required to access system memory from a
 400   DMA bus master.
 401
 402   @param  Operation             Indicates if the bus master is going to read or write to system memory.
 403   @param  HostAddress           The system memory address to map to the PCI controller.
 404   @param  NumberOfBytes         On input the number of bytes to map. On output the number of bytes
 405                                 that were mapped.
 406   @param  DeviceAddress         The resulting map address for the bus master PCI controller to use to
 407                                 access the hosts HostAddress.
 408   @param  Mapping               A resulting value to pass to Unmap().
 409
 410   @retval EFI_SUCCESS           The range was mapped for the returned NumberOfBytes.
 411   @retval EFI_UNSUPPORTED       The HostAddress cannot be mapped as a common buffer.
 412   @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
 413   @retval EFI_OUT_OF_RESOURCES  The request could not be completed due to a lack of resources.
 414   @retval EFI_DEVICE_ERROR      The system hardware could not map the requested address.
 415
 416 **/
 417 EFI_STATUS
 418 IoMmuMap (
 419   IN  EDKII_IOMMU_OPERATION Operation,
 420   IN VOID                   *HostAddress,
 421   IN  OUT UINTN             *NumberOfBytes,
 422   OUT EFI_PHYSICAL_ADDRESS  *DeviceAddress,
 423   OUT VOID                  **Mapping
 424   );
 425
 426 /**
 427   Completes the Map() operation and releases any corresponding resources.
 428
 429   @param  Mapping               The mapping value returned from Map().
 430
 431   @retval EFI_SUCCESS           The range was unmapped.
 432   @retval EFI_INVALID_PARAMETER Mapping is not a value that was returned by Map().
 433   @retval EFI_DEVICE_ERROR      The data was not committed to the target system memory.
 434 **/
 435 EFI_STATUS
 436 IoMmuUnmap (
 437   IN VOID                  *Mapping
 438   );
 439
 440 /**
 441   One notified function to cleanup the allocated DMA buffers at EndOfPei.
 442
 443   @param[in] PeiServices         Pointer to PEI Services Table.
 444   @param[in] NotifyDescriptor    Pointer to the descriptor for the Notification
 445                                  event that caused this function to execute.
 446   @param[in] Ppi                 Pointer to the PPI data associated with this function.
 447
 448   @retval EFI_SUCCESS    The function completes successfully
 449
 450 **/
 451 EFI_STATUS
 452 EFIAPI
 453 AhciPeimEndOfPei (
 454   IN EFI_PEI_SERVICES           **PeiServices,
 455   IN EFI_PEI_NOTIFY_DESCRIPTOR  *NotifyDescriptor,
 456   IN VOID                       *Ppi
 457   );
 458
 459 /**
 460   Collect the number of bits set within a port bitmap.
 461
 462   @param[in]    PortBitMap    A 32-bit wide bit map of ATA AHCI ports.
 463
 464   @retval The number of bits set in the bitmap.
 465
 466 **/
 467 UINT8
 468 AhciGetNumberOfPortsFromMap (
 469   IN UINT32    PortBitMap
 470   );
 471
 472 /**
 473   Start a PIO Data transfer on specific port.
 474
 475   @param[in]     Private            The pointer to the PEI_AHCI_CONTROLLER_PRIVATE_DATA.
 476   @param[in]     Port               The number of port.
 477   @param[in]     PortMultiplier     The number of port multiplier.
 478   @param[in]     FisIndex           The offset index of the FIS base address.
 479   @param[in]     Read               The transfer direction.
 480   @param[in]     AtaCommandBlock    The EFI_ATA_COMMAND_BLOCK data.
 481   @param[in,out] AtaStatusBlock     The EFI_ATA_STATUS_BLOCK data.
 482   @param[in,out] MemoryAddr         The pointer to the data buffer.
 483   @param[in]     DataCount          The data count to be transferred.
 484   @param[in]     Timeout            The timeout value of PIO data transfer, uses
 485                                     100ns as a unit.
 486
 487   @retval EFI_DEVICE_ERROR        The PIO data transfer abort with error occurs.
 488   @retval EFI_TIMEOUT             The operation is time out.
 489   @retval EFI_UNSUPPORTED         The device is not ready for transfer.
 490   @retval EFI_OUT_OF_RESOURCES    The operation fails due to lack of resources.
 491   @retval EFI_SUCCESS             The PIO data transfer executes successfully.
 492
 493 **/
 494 EFI_STATUS
 495 AhciPioTransfer (
 496   IN     PEI_AHCI_CONTROLLER_PRIVATE_DATA    *Private,
 497   IN     UINT8                               Port,
 498   IN     UINT8                               PortMultiplier,
 499   IN     UINT8                               FisIndex,
 500   IN     BOOLEAN                             Read,
 501   IN     EFI_ATA_COMMAND_BLOCK               *AtaCommandBlock,
 502   IN OUT EFI_ATA_STATUS_BLOCK                *AtaStatusBlock,
 503   IN OUT VOID                                *MemoryAddr,
 504   IN     UINT32                              DataCount,
 505   IN     UINT64                              Timeout
 506   );
 507
 508 /**
 509   Start a non data transfer on specific port.
 510
 511   @param[in]     Private            The pointer to the PEI_AHCI_CONTROLLER_PRIVATE_DATA.
 512   @param[in]     Port               The number of port.
 513   @param[in]     PortMultiplier     The number of port multiplier.
 514   @param[in]     FisIndex           The offset index of the FIS base address.
 515   @param[in]     AtaCommandBlock    The EFI_ATA_COMMAND_BLOCK data.
 516   @param[in,out] AtaStatusBlock     The EFI_ATA_STATUS_BLOCK data.
 517   @param[in]     Timeout            The timeout value of non data transfer, uses
 518                                     100ns as a unit.
 519
 520   @retval EFI_DEVICE_ERROR        The non data transfer abort with error occurs.
 521   @retval EFI_TIMEOUT             The operation is time out.
 522   @retval EFI_UNSUPPORTED         The device is not ready for transfer.
 523   @retval EFI_SUCCESS             The non data transfer executes successfully.
 524
 525 **/
 526 EFI_STATUS
 527 AhciNonDataTransfer (
 528   IN     PEI_AHCI_CONTROLLER_PRIVATE_DATA    *Private,
 529   IN     UINT8                               Port,
 530   IN     UINT8                               PortMultiplier,
 531   IN     UINT8                               FisIndex,
 532   IN     EFI_ATA_COMMAND_BLOCK               *AtaCommandBlock,
 533   IN OUT EFI_ATA_STATUS_BLOCK                *AtaStatusBlock,
 534   IN     UINT64                              Timeout
 535   );
 536
 537 /**
 538   Initialize ATA host controller at AHCI mode.
 539
 540   The function is designed to initialize ATA host controller.
 541
 542   @param[in,out] Private    A pointer to the PEI_AHCI_CONTROLLER_PRIVATE_DATA instance.
 543
 544   @retval EFI_SUCCESS             The ATA AHCI controller is initialized successfully.
 545   @retval EFI_OUT_OF_RESOURCES    Not enough resource to complete while initializing
 546                                   the controller.
 547   @retval Others                  A device error occurred while initializing the
 548                                   controller.
 549
 550 **/
 551 EFI_STATUS
 552 AhciModeInitialization (
 553   IN OUT PEI_AHCI_CONTROLLER_PRIVATE_DATA    *Private
 554   );
 555
 556 /**
 557   Trust transfer data from/to ATA device.
 558
 559   This function performs one ATA pass through transaction to do a trust transfer
 560   from/to ATA device. It chooses the appropriate ATA command and protocol to invoke
 561   PassThru interface of ATA pass through.
 562
 563   @param[in]     DeviceData     Pointer to PEI_AHCI_ATA_DEVICE_DATA structure.
 564   @param[in,out] Buffer         The pointer to the current transaction buffer.
 565   @param[in]     SecurityProtocolId
 566                                 The value of the "Security Protocol" parameter
 567                                 of the security protocol command to be sent.
 568   @param[in]     SecurityProtocolSpecificData
 569                                 The value of the "Security Protocol Specific"
 570                                 parameter of the security protocol command to
 571                                 be sent.
 572   @param[in]     TransferLength The block number or sector count of the transfer.
 573   @param[in]     IsTrustSend    Indicates whether it is a trust send operation
 574                                 or not.
 575   @param[in]     Timeout        The timeout, in 100ns units, to use for the execution
 576                                 of the security protocol command. A Timeout value
 577                                 of 0 means that this function will wait indefinitely
 578                                 for the security protocol command to execute. If
 579                                 Timeout is greater than zero, then this function
 580                                 will return EFI_TIMEOUT if the time required to
 581                                 execute the receive data command is greater than
 582                                 Timeout.
 583   @param[out]    TransferLengthOut
 584                                 A pointer to a buffer to store the size in bytes
 585                                 of the data written to the buffer. Ignore it when
 586                                 IsTrustSend is TRUE.
 587
 588   @retval EFI_SUCCESS    The data transfer is complete successfully.
 589   @return others         Some error occurs when transferring data.
 590
 591 **/
 592 EFI_STATUS
 593 TrustTransferAtaDevice (
 594   IN     PEI_AHCI_ATA_DEVICE_DATA    *DeviceData,
 595   IN OUT VOID                        *Buffer,
 596   IN     UINT8                       SecurityProtocolId,
 597   IN     UINT16                      SecurityProtocolSpecificData,
 598   IN     UINTN                       TransferLength,
 599   IN     BOOLEAN                     IsTrustSend,
 600   IN     UINT64                      Timeout,
 601   OUT    UINTN                       *TransferLengthOut
 602   );
 603
 604 /**
 605   Returns a pointer to the next node in a device path.
 606
 607   If Node is NULL, then ASSERT().
 608
 609   @param  Node    A pointer to a device path node data structure.
 610
 611   @return a pointer to the device path node that follows the device path node
 612   specified by Node.
 613
 614 **/
 615 EFI_DEVICE_PATH_PROTOCOL *
 616 NextDevicePathNode (
 617   IN CONST VOID  *Node
 618   );
 619
 620 /**
 621   Get the size of the current device path instance.
 622
 623   @param[in]  DevicePath             A pointer to the EFI_DEVICE_PATH_PROTOCOL
 624                                      structure.
 625   @param[out] InstanceSize           The size of the current device path instance.
 626   @param[out] EntireDevicePathEnd    Indicate whether the instance is the last
 627                                      one in the device path strucure.
 628
 629   @retval EFI_SUCCESS    The size of the current device path instance is fetched.
 630   @retval Others         Fails to get the size of the current device path instance.
 631
 632 **/
 633 EFI_STATUS
 634 GetDevicePathInstanceSize (
 635   IN  EFI_DEVICE_PATH_PROTOCOL    *DevicePath,
 636   OUT UINTN                       *InstanceSize,
 637   OUT BOOLEAN                     *EntireDevicePathEnd
 638   );
 639
 640 /**
 641   Check the validity of the device path of a ATA AHCI host controller.
 642
 643   @param[in] DevicePath          A pointer to the EFI_DEVICE_PATH_PROTOCOL
 644                                  structure.
 645   @param[in] DevicePathLength    The length of the device path.
 646
 647   @retval EFI_SUCCESS              The device path is valid.
 648   @retval EFI_INVALID_PARAMETER    The device path is invalid.
 649
 650 **/
 651 EFI_STATUS
 652 AhciIsHcDevicePathValid (
 653   IN EFI_DEVICE_PATH_PROTOCOL    *DevicePath,
 654   IN UINTN                       DevicePathLength
 655   );
 656
 657 /**
 658   Build the device path for an ATA device with given port and port multiplier number.
 659
 660   @param[in]  Private               A pointer to the PEI_AHCI_CONTROLLER_PRIVATE_DATA
 661                                     data structure.
 662   @param[in]  Port                  The given port number.
 663   @param[in]  PortMultiplierPort    The given port multiplier number.
 664   @param[out] DevicePathLength      The length of the device path in bytes specified
 665                                     by DevicePath.
 666   @param[out] DevicePath            The device path of ATA device.
 667
 668   @retval EFI_SUCCESS               The operation succeeds.
 669   @retval EFI_INVALID_PARAMETER     The parameters are invalid.
 670   @retval EFI_OUT_OF_RESOURCES      The operation fails due to lack of resources.
 671
 672 **/
 673 EFI_STATUS
 674 AhciBuildDevicePath (
 675   IN  PEI_AHCI_CONTROLLER_PRIVATE_DATA    *Private,
 676   IN  UINT16                              Port,
 677   IN  UINT16                              PortMultiplierPort,
 678   OUT UINTN                               *DevicePathLength,
 679   OUT EFI_DEVICE_PATH_PROTOCOL            **DevicePath
 680   );
 681
 682 /**
 683   Collect the ports that need to be enumerated on a controller for S3 phase.
 684
 685   @param[in]  HcDevicePath          Device path of the controller.
 686   @param[in]  HcDevicePathLength    Length of the device path specified by
 687                                     HcDevicePath.
 688   @param[out] PortBitMap            Bitmap that indicates the ports that need
 689                                     to be enumerated on the controller.
 690
 691   @retval    The number of ports that need to be enumerated.
 692
 693 **/
 694 UINT8
 695 AhciS3GetEumeratePorts (
 696   IN  EFI_DEVICE_PATH_PROTOCOL    *HcDevicePath,
 697   IN  UINTN                       HcDevicePathLength,
 698   OUT UINT32                      *PortBitMap
 699   );
 700
 701 #endif