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