OvmfPkg/SataControllerDxe/SataController.c

   1 /** @file
   2   This driver module produces IDE_CONTROLLER_INIT protocol for Sata Controllers.
   3
   4   Copyright (c) 2011, Intel Corporation. All rights reserved.<BR>
   5   SPDX-License-Identifier: BSD-2-Clause-Patent
   6
   7 **/
   8
   9 #include "SataController.h"
  10
  11 ///
  12 /// EFI_DRIVER_BINDING_PROTOCOL instance
  13 ///
  14 EFI_DRIVER_BINDING_PROTOCOL  gSataControllerDriverBinding = {
  15   SataControllerSupported,
  16   SataControllerStart,
  17   SataControllerStop,
  18   0xa,
  19   NULL,
  20   NULL
  21 };
  22
  23 /**
  24   Read AHCI Operation register.
  25
  26   @param PciIo      The PCI IO protocol instance.
  27   @param Offset     The operation register offset.
  28
  29   @return The register content read.
  30
  31 **/
  32 UINT32
  33 EFIAPI
  34 AhciReadReg (
  35   IN EFI_PCI_IO_PROTOCOL  *PciIo,
  36   IN UINT32               Offset
  37   )
  38 {
  39   UINT32  Data;
  40
  41   ASSERT (PciIo != NULL);
  42
  43   Data = 0;
  44
  45   PciIo->Mem.Read (
  46                PciIo,
  47                EfiPciIoWidthUint32,
  48                AHCI_BAR_INDEX,
  49                (UINT64)Offset,
  50                1,
  51                &Data
  52                );
  53
  54   return Data;
  55 }
  56
  57 /**
  58   Write AHCI Operation register.
  59
  60   @param PciIo      The PCI IO protocol instance.
  61   @param Offset     The operation register offset.
  62   @param Data       The data used to write down.
  63
  64 **/
  65 VOID
  66 EFIAPI
  67 AhciWriteReg (
  68   IN EFI_PCI_IO_PROTOCOL  *PciIo,
  69   IN UINT32               Offset,
  70   IN UINT32               Data
  71   )
  72 {
  73   ASSERT (PciIo != NULL);
  74
  75   PciIo->Mem.Write (
  76                PciIo,
  77                EfiPciIoWidthUint32,
  78                AHCI_BAR_INDEX,
  79                (UINT64)Offset,
  80                1,
  81                &Data
  82                );
  83
  84   return;
  85 }
  86
  87 /**
  88   This function is used to calculate the best PIO mode supported by specific IDE device
  89
  90   @param IdentifyData   The identify data of specific IDE device.
  91   @param DisPioMode     Disqualified PIO modes collection.
  92   @param SelectedMode   Available PIO modes collection.
  93
  94   @retval EFI_SUCCESS       Best PIO modes are returned.
  95   @retval EFI_UNSUPPORTED   The device doesn't support PIO mode,
  96                             or all supported modes have been disqualified.
  97 **/
  98 EFI_STATUS
  99 CalculateBestPioMode (
 100   IN EFI_IDENTIFY_DATA  *IdentifyData,
 101   IN UINT16             *DisPioMode OPTIONAL,
 102   OUT UINT16            *SelectedMode
 103   )
 104 {
 105   UINT16  PioMode;
 106   UINT16  AdvancedPioMode;
 107   UINT16  Temp;
 108   UINT16  Index;
 109   UINT16  MinimumPioCycleTime;
 110
 111   Temp = 0xff;
 112
 113   PioMode = (UINT8)(((ATA5_IDENTIFY_DATA *)(&(IdentifyData->AtaData)))->pio_cycle_timing >> 8);
 114
 115   //
 116   // See whether Identify Data word 64 - 70 are valid
 117   //
 118   if ((IdentifyData->AtaData.field_validity & 0x02) == 0x02) {
 119     AdvancedPioMode = IdentifyData->AtaData.advanced_pio_modes;
 120     DEBUG ((DEBUG_INFO, "CalculateBestPioMode: AdvancedPioMode = %x\n", AdvancedPioMode));
 121
 122     for (Index = 0; Index < 8; Index++) {
 123       if ((AdvancedPioMode & 0x01) != 0) {
 124         Temp = Index;
 125       }
 126
 127       AdvancedPioMode >>= 1;
 128     }
 129
 130     //
 131     // If Temp is modified, mean the advanced_pio_modes is not zero;
 132     // if Temp is not modified, mean there is no advanced PIO mode supported,
 133     // the best PIO Mode is the value in pio_cycle_timing.
 134     //
 135     if (Temp != 0xff) {
 136       AdvancedPioMode = (UINT16)(Temp + 3);
 137     } else {
 138       AdvancedPioMode = PioMode;
 139     }
 140
 141     //
 142     // Limit the PIO mode to at most PIO4.
 143     //
 144     PioMode = (UINT16)MIN (AdvancedPioMode, 4);
 145
 146     MinimumPioCycleTime = IdentifyData->AtaData.min_pio_cycle_time_with_flow_control;
 147
 148     if (MinimumPioCycleTime <= 120) {
 149       PioMode = (UINT16)MIN (4, PioMode);
 150     } else if (MinimumPioCycleTime <= 180) {
 151       PioMode = (UINT16)MIN (3, PioMode);
 152     } else if (MinimumPioCycleTime <= 240) {
 153       PioMode = (UINT16)MIN (2, PioMode);
 154     } else {
 155       PioMode = 0;
 156     }
 157
 158     //
 159     // Degrade the PIO mode if the mode has been disqualified
 160     //
 161     if (DisPioMode != NULL) {
 162       if (*DisPioMode < 2) {
 163         return EFI_UNSUPPORTED; // no mode below ATA_PIO_MODE_BELOW_2
 164       }
 165
 166       if (PioMode >= *DisPioMode) {
 167         PioMode = (UINT16)(*DisPioMode - 1);
 168       }
 169     }
 170
 171     if (PioMode < 2) {
 172       *SelectedMode = 1;        // ATA_PIO_MODE_BELOW_2;
 173     } else {
 174       *SelectedMode = PioMode;  // ATA_PIO_MODE_2 to ATA_PIO_MODE_4;
 175     }
 176   } else {
 177     //
 178     // Identify Data word 64 - 70 are not valid
 179     // Degrade the PIO mode if the mode has been disqualified
 180     //
 181     if (DisPioMode != NULL) {
 182       if (*DisPioMode < 2) {
 183         return EFI_UNSUPPORTED; // no mode below ATA_PIO_MODE_BELOW_2
 184       }
 185
 186       if (PioMode == *DisPioMode) {
 187         PioMode--;
 188       }
 189     }
 190
 191     if (PioMode < 2) {
 192       *SelectedMode = 1;        // ATA_PIO_MODE_BELOW_2;
 193     } else {
 194       *SelectedMode = 2;        // ATA_PIO_MODE_2;
 195     }
 196   }
 197
 198   return EFI_SUCCESS;
 199 }
 200
 201 /**
 202   This function is used to calculate the best UDMA mode supported by specific IDE device
 203
 204   @param IdentifyData   The identify data of specific IDE device.
 205   @param DisUDmaMode     Disqualified UDMA modes collection.
 206   @param SelectedMode   Available UDMA modes collection.
 207
 208   @retval EFI_SUCCESS       Best UDMA modes are returned.
 209   @retval EFI_UNSUPPORTED   The device doesn't support UDMA mode,
 210                             or all supported modes have been disqualified.
 211 **/
 212 EFI_STATUS
 213 CalculateBestUdmaMode (
 214   IN EFI_IDENTIFY_DATA  *IdentifyData,
 215   IN UINT16             *DisUDmaMode OPTIONAL,
 216   OUT UINT16            *SelectedMode
 217   )
 218 {
 219   UINT16  TempMode;
 220   UINT16  DeviceUDmaMode;
 221
 222   DeviceUDmaMode = 0;
 223
 224   //
 225   // Check whether the WORD 88 (supported UltraDMA by drive) is valid
 226   //
 227   if ((IdentifyData->AtaData.field_validity & 0x04) == 0x00) {
 228     return EFI_UNSUPPORTED;
 229   }
 230
 231   DeviceUDmaMode = IdentifyData->AtaData.ultra_dma_mode;
 232   DEBUG ((DEBUG_INFO, "CalculateBestUdmaMode: DeviceUDmaMode = %x\n", DeviceUDmaMode));
 233   DeviceUDmaMode &= 0x3f;
 234   TempMode        = 0;          // initialize it to UDMA-0
 235
 236   while ((DeviceUDmaMode >>= 1) != 0) {
 237     TempMode++;
 238   }
 239
 240   //
 241   // Degrade the UDMA mode if the mode has been disqualified
 242   //
 243   if (DisUDmaMode != NULL) {
 244     if (*DisUDmaMode == 0) {
 245       *SelectedMode = 0;
 246       return EFI_UNSUPPORTED;   // no mode below ATA_UDMA_MODE_0
 247     }
 248
 249     if (TempMode >= *DisUDmaMode) {
 250       TempMode = (UINT16)(*DisUDmaMode - 1);
 251     }
 252   }
 253
 254   //
 255   // Possible returned mode is between ATA_UDMA_MODE_0 and ATA_UDMA_MODE_5
 256   //
 257   *SelectedMode = TempMode;
 258
 259   return EFI_SUCCESS;
 260 }
 261
 262 /**
 263   The Entry Point of module. It follows the standard UEFI driver model.
 264
 265   @param[in] ImageHandle    The firmware allocated handle for the EFI image.
 266   @param[in] SystemTable    A pointer to the EFI System Table.
 267
 268   @retval EFI_SUCCESS   The entry point is executed successfully.
 269   @retval other         Some error occurs when executing this entry point.
 270
 271 **/
 272 EFI_STATUS
 273 EFIAPI
 274 InitializeSataControllerDriver (
 275   IN EFI_HANDLE        ImageHandle,
 276   IN EFI_SYSTEM_TABLE  *SystemTable
 277   )
 278 {
 279   EFI_STATUS  Status;
 280
 281   //
 282   // Install driver model protocol(s).
 283   //
 284   Status = EfiLibInstallDriverBindingComponentName2 (
 285              ImageHandle,
 286              SystemTable,
 287              &gSataControllerDriverBinding,
 288              ImageHandle,
 289              &gSataControllerComponentName,
 290              &gSataControllerComponentName2
 291              );
 292   ASSERT_EFI_ERROR (Status);
 293
 294   return Status;
 295 }
 296
 297 /**
 298   Supported function of Driver Binding protocol for this driver.
 299   Test to see if this driver supports ControllerHandle.
 300
 301   @param This                   Protocol instance pointer.
 302   @param Controller             Handle of device to test.
 303   @param RemainingDevicePath    A pointer to the device path.
 304                                 it should be ignored by device driver.
 305
 306   @retval EFI_SUCCESS           This driver supports this device.
 307   @retval EFI_ALREADY_STARTED   This driver is already running on this device.
 308   @retval other                 This driver does not support this device.
 309
 310 **/
 311 EFI_STATUS
 312 EFIAPI
 313 SataControllerSupported (
 314   IN EFI_DRIVER_BINDING_PROTOCOL  *This,
 315   IN EFI_HANDLE                   Controller,
 316   IN EFI_DEVICE_PATH_PROTOCOL     *RemainingDevicePath
 317   )
 318 {
 319   EFI_STATUS           Status;
 320   EFI_PCI_IO_PROTOCOL  *PciIo;
 321   PCI_TYPE00           PciData;
 322
 323   //
 324   // Attempt to open PCI I/O Protocol
 325   //
 326   Status = gBS->OpenProtocol (
 327                   Controller,
 328                   &gEfiPciIoProtocolGuid,
 329                   (VOID **)&PciIo,
 330                   This->DriverBindingHandle,
 331                   Controller,
 332                   EFI_OPEN_PROTOCOL_GET_PROTOCOL
 333                   );
 334   if (EFI_ERROR (Status)) {
 335     return Status;
 336   }
 337
 338   //
 339   // Now further check the PCI header: Base Class (offset 0x0B) and
 340   // Sub Class (offset 0x0A). This controller should be an SATA controller
 341   //
 342   Status = PciIo->Pci.Read (
 343                         PciIo,
 344                         EfiPciIoWidthUint8,
 345                         PCI_CLASSCODE_OFFSET,
 346                         sizeof (PciData.Hdr.ClassCode),
 347                         PciData.Hdr.ClassCode
 348                         );
 349   if (EFI_ERROR (Status)) {
 350     return EFI_UNSUPPORTED;
 351   }
 352
 353   if (IS_PCI_IDE (&PciData) || IS_PCI_SATADPA (&PciData)) {
 354     return EFI_SUCCESS;
 355   }
 356
 357   return EFI_UNSUPPORTED;
 358 }
 359
 360 /**
 361   This routine is called right after the .Supported() called and
 362   Start this driver on ControllerHandle.
 363
 364   @param This                   Protocol instance pointer.
 365   @param Controller             Handle of device to bind driver to.
 366   @param RemainingDevicePath    A pointer to the device path.
 367                                 it should be ignored by device driver.
 368
 369   @retval EFI_SUCCESS           This driver is added to this device.
 370   @retval EFI_ALREADY_STARTED   This driver is already running on this device.
 371   @retval other                 Some error occurs when binding this driver to this device.
 372
 373 **/
 374 EFI_STATUS
 375 EFIAPI
 376 SataControllerStart (
 377   IN EFI_DRIVER_BINDING_PROTOCOL  *This,
 378   IN EFI_HANDLE                   Controller,
 379   IN EFI_DEVICE_PATH_PROTOCOL     *RemainingDevicePath
 380   )
 381 {
 382   UINTN                             BailLogMask;
 383   EFI_STATUS                        Status;
 384   EFI_PCI_IO_PROTOCOL               *PciIo;
 385   UINT64                            OriginalPciAttributes;
 386   PCI_TYPE00                        PciData;
 387   EFI_SATA_CONTROLLER_PRIVATE_DATA  *SataPrivateData;
 388   UINT32                            Data32;
 389   UINTN                             ChannelDeviceCount;
 390
 391   DEBUG ((DEBUG_INFO, "SataControllerStart START\n"));
 392
 393   BailLogMask     = DEBUG_ERROR;
 394   SataPrivateData = NULL;
 395
 396   //
 397   // Now test and open PCI I/O Protocol
 398   //
 399   Status = gBS->OpenProtocol (
 400                   Controller,
 401                   &gEfiPciIoProtocolGuid,
 402                   (VOID **)&PciIo,
 403                   This->DriverBindingHandle,
 404                   Controller,
 405                   EFI_OPEN_PROTOCOL_BY_DRIVER
 406                   );
 407   if (EFI_ERROR (Status)) {
 408     if (Status == EFI_ALREADY_STARTED) {
 409       //
 410       // This is an expected condition for OpenProtocol() / BY_DRIVER, in a
 411       // DriverBindingStart() member function; degrade the log mask to
 412       // DEBUG_INFO.
 413       //
 414       BailLogMask = DEBUG_INFO;
 415     }
 416
 417     goto Bail;
 418   }
 419
 420   //
 421   // Save original PCI attributes, and enable IO space access, memory space
 422   // access, and Bus Master (DMA).
 423   //
 424   Status = PciIo->Attributes (
 425                     PciIo,
 426                     EfiPciIoAttributeOperationGet,
 427                     0,
 428                     &OriginalPciAttributes
 429                     );
 430   if (EFI_ERROR (Status)) {
 431     goto ClosePciIo;
 432   }
 433
 434   Status = PciIo->Attributes (
 435                     PciIo,
 436                     EfiPciIoAttributeOperationEnable,
 437                     EFI_PCI_DEVICE_ENABLE,
 438                     NULL
 439                     );
 440   if (EFI_ERROR (Status)) {
 441     goto ClosePciIo;
 442   }
 443
 444   //
 445   // Allocate Sata Private Data structure
 446   //
 447   SataPrivateData = AllocateZeroPool (sizeof (EFI_SATA_CONTROLLER_PRIVATE_DATA));
 448   if (SataPrivateData == NULL) {
 449     Status = EFI_OUT_OF_RESOURCES;
 450     goto RestorePciAttributes;
 451   }
 452
 453   //
 454   // Initialize Sata Private Data
 455   //
 456   SataPrivateData->Signature              = SATA_CONTROLLER_SIGNATURE;
 457   SataPrivateData->PciIo                  = PciIo;
 458   SataPrivateData->OriginalPciAttributes  = OriginalPciAttributes;
 459   SataPrivateData->IdeInit.GetChannelInfo = IdeInitGetChannelInfo;
 460   SataPrivateData->IdeInit.NotifyPhase    = IdeInitNotifyPhase;
 461   SataPrivateData->IdeInit.SubmitData     = IdeInitSubmitData;
 462   SataPrivateData->IdeInit.DisqualifyMode = IdeInitDisqualifyMode;
 463   SataPrivateData->IdeInit.CalculateMode  = IdeInitCalculateMode;
 464   SataPrivateData->IdeInit.SetTiming      = IdeInitSetTiming;
 465   SataPrivateData->IdeInit.EnumAll        = SATA_ENUMER_ALL;
 466
 467   Status = PciIo->Pci.Read (
 468                         PciIo,
 469                         EfiPciIoWidthUint8,
 470                         PCI_CLASSCODE_OFFSET,
 471                         sizeof (PciData.Hdr.ClassCode),
 472                         PciData.Hdr.ClassCode
 473                         );
 474   if (EFI_ERROR (Status)) {
 475     goto FreeSataPrivateData;
 476   }
 477
 478   if (IS_PCI_IDE (&PciData)) {
 479     SataPrivateData->IdeInit.ChannelCount = IDE_MAX_CHANNEL;
 480     SataPrivateData->DeviceCount          = IDE_MAX_DEVICES;
 481   } else if (IS_PCI_SATADPA (&PciData)) {
 482     //
 483     // Read Host Capability Register(CAP) to get Number of Ports(NPS) and Supports Port Multiplier(SPM)
 484     //   NPS is 0's based value indicating the maximum number of ports supported by the HBA silicon.
 485     //   A maximum of 32 ports can be supported. A value of '0h', indicating one port, is the minimum requirement.
 486     //
 487     Data32                                = AhciReadReg (PciIo, R_AHCI_CAP);
 488     SataPrivateData->IdeInit.ChannelCount = (UINT8)((Data32 & B_AHCI_CAP_NPS) + 1);
 489     SataPrivateData->DeviceCount          = AHCI_MAX_DEVICES;
 490     if ((Data32 & B_AHCI_CAP_SPM) == B_AHCI_CAP_SPM) {
 491       SataPrivateData->DeviceCount = AHCI_MULTI_MAX_DEVICES;
 492     }
 493   }
 494
 495   ChannelDeviceCount                 = (UINTN)(SataPrivateData->IdeInit.ChannelCount) * (UINTN)(SataPrivateData->DeviceCount);
 496   SataPrivateData->DisqualifiedModes = AllocateZeroPool ((sizeof (EFI_ATA_COLLECTIVE_MODE)) * ChannelDeviceCount);
 497   if (SataPrivateData->DisqualifiedModes == NULL) {
 498     Status = EFI_OUT_OF_RESOURCES;
 499     goto FreeSataPrivateData;
 500   }
 501
 502   SataPrivateData->IdentifyData = AllocateZeroPool ((sizeof (EFI_IDENTIFY_DATA)) * ChannelDeviceCount);
 503   if (SataPrivateData->IdentifyData == NULL) {
 504     Status = EFI_OUT_OF_RESOURCES;
 505     goto FreeDisqualifiedModes;
 506   }
 507
 508   SataPrivateData->IdentifyValid = AllocateZeroPool ((sizeof (BOOLEAN)) * ChannelDeviceCount);
 509   if (SataPrivateData->IdentifyValid == NULL) {
 510     Status = EFI_OUT_OF_RESOURCES;
 511     goto FreeIdentifyData;
 512   }
 513
 514   //
 515   // Install IDE Controller Init Protocol to this instance
 516   //
 517   Status = gBS->InstallMultipleProtocolInterfaces (
 518                   &Controller,
 519                   &gEfiIdeControllerInitProtocolGuid,
 520                   &(SataPrivateData->IdeInit),
 521                   NULL
 522                   );
 523
 524   if (EFI_ERROR (Status)) {
 525     goto FreeIdentifyValid;
 526   }
 527
 528   DEBUG ((DEBUG_INFO, "SataControllerStart END status = %r\n", Status));
 529   return Status;
 530
 531 FreeIdentifyValid:
 532   FreePool (SataPrivateData->IdentifyValid);
 533
 534 FreeIdentifyData:
 535   FreePool (SataPrivateData->IdentifyData);
 536
 537 FreeDisqualifiedModes:
 538   FreePool (SataPrivateData->DisqualifiedModes);
 539
 540 FreeSataPrivateData:
 541   FreePool (SataPrivateData);
 542
 543 RestorePciAttributes:
 544   PciIo->Attributes (
 545            PciIo,
 546            EfiPciIoAttributeOperationSet,
 547            OriginalPciAttributes,
 548            NULL
 549            );
 550
 551 ClosePciIo:
 552   gBS->CloseProtocol (
 553          Controller,
 554          &gEfiPciIoProtocolGuid,
 555          This->DriverBindingHandle,
 556          Controller
 557          );
 558
 559 Bail:
 560   DEBUG ((
 561     BailLogMask,
 562     "SataControllerStart error return status = %r\n",
 563     Status
 564     ));
 565   return Status;
 566 }
 567
 568 /**
 569   Stop this driver on ControllerHandle.
 570
 571   @param This               Protocol instance pointer.
 572   @param Controller         Handle of device to stop driver on.
 573   @param NumberOfChildren   Not used.
 574   @param ChildHandleBuffer  Not used.
 575
 576   @retval EFI_SUCCESS   This driver is removed from this device.
 577   @retval other         Some error occurs when removing this driver from this device.
 578
 579 **/
 580 EFI_STATUS
 581 EFIAPI
 582 SataControllerStop (
 583   IN EFI_DRIVER_BINDING_PROTOCOL  *This,
 584   IN EFI_HANDLE                   Controller,
 585   IN UINTN                        NumberOfChildren,
 586   IN EFI_HANDLE                   *ChildHandleBuffer
 587   )
 588 {
 589   EFI_STATUS                        Status;
 590   EFI_IDE_CONTROLLER_INIT_PROTOCOL  *IdeInit;
 591   EFI_SATA_CONTROLLER_PRIVATE_DATA  *SataPrivateData;
 592   EFI_PCI_IO_PROTOCOL               *PciIo;
 593   UINT64                            OriginalPciAttributes;
 594
 595   //
 596   // Open the produced protocol
 597   //
 598   Status = gBS->OpenProtocol (
 599                   Controller,
 600                   &gEfiIdeControllerInitProtocolGuid,
 601                   (VOID **)&IdeInit,
 602                   This->DriverBindingHandle,
 603                   Controller,
 604                   EFI_OPEN_PROTOCOL_GET_PROTOCOL
 605                   );
 606   if (EFI_ERROR (Status)) {
 607     return EFI_UNSUPPORTED;
 608   }
 609
 610   SataPrivateData = SATA_CONTROLLER_PRIVATE_DATA_FROM_THIS (IdeInit);
 611   ASSERT (SataPrivateData != NULL);
 612
 613   PciIo                 = SataPrivateData->PciIo;
 614   OriginalPciAttributes = SataPrivateData->OriginalPciAttributes;
 615
 616   //
 617   // Uninstall the IDE Controller Init Protocol from this instance
 618   //
 619   Status = gBS->UninstallMultipleProtocolInterfaces (
 620                   Controller,
 621                   &gEfiIdeControllerInitProtocolGuid,
 622                   &(SataPrivateData->IdeInit),
 623                   NULL
 624                   );
 625   if (EFI_ERROR (Status)) {
 626     return Status;
 627   }
 628
 629   if (SataPrivateData->DisqualifiedModes != NULL) {
 630     FreePool (SataPrivateData->DisqualifiedModes);
 631   }
 632
 633   if (SataPrivateData->IdentifyData != NULL) {
 634     FreePool (SataPrivateData->IdentifyData);
 635   }
 636
 637   if (SataPrivateData->IdentifyValid != NULL) {
 638     FreePool (SataPrivateData->IdentifyValid);
 639   }
 640
 641   FreePool (SataPrivateData);
 642
 643   //
 644   // Restore original PCI attributes
 645   //
 646   PciIo->Attributes (
 647            PciIo,
 648            EfiPciIoAttributeOperationSet,
 649            OriginalPciAttributes,
 650            NULL
 651            );
 652
 653   //
 654   // Close protocols opened by Sata Controller driver
 655   //
 656   return gBS->CloseProtocol (
 657                 Controller,
 658                 &gEfiPciIoProtocolGuid,
 659                 This->DriverBindingHandle,
 660                 Controller
 661                 );
 662 }
 663
 664 /**
 665   Calculate the flat array subscript of a (Channel, Device) pair.
 666
 667   @param[in] SataPrivateData  The private data structure corresponding to the
 668                               SATA controller that attaches the device for
 669                               which the flat array subscript is being
 670                               calculated.
 671
 672   @param[in] Channel          The channel (ie. port) number on the SATA
 673                               controller that the device is attached to.
 674
 675   @param[in] Device           The device number on the channel.
 676
 677   @return  The flat array subscript suitable for indexing DisqualifiedModes,
 678            IdentifyData, and IdentifyValid.
 679 **/
 680 STATIC
 681 UINTN
 682 FlatDeviceIndex (
 683   IN CONST EFI_SATA_CONTROLLER_PRIVATE_DATA  *SataPrivateData,
 684   IN UINTN                                   Channel,
 685   IN UINTN                                   Device
 686   )
 687 {
 688   ASSERT (SataPrivateData != NULL);
 689   ASSERT (Channel < SataPrivateData->IdeInit.ChannelCount);
 690   ASSERT (Device < SataPrivateData->DeviceCount);
 691
 692   return Channel * SataPrivateData->DeviceCount + Device;
 693 }
 694
 695 //
 696 // Interface functions of IDE_CONTROLLER_INIT protocol
 697 //
 698
 699 /**
 700   Returns the information about the specified IDE channel.
 701
 702   This function can be used to obtain information about a particular IDE channel.
 703   The driver entity uses this information during the enumeration process.
 704
 705   If Enabled is set to FALSE, the driver entity will not scan the channel. Note
 706   that it will not prevent an operating system driver from scanning the channel.
 707
 708   For most of today's controllers, MaxDevices will either be 1 or 2. For SATA
 709   controllers, this value will always be 1. SATA configurations can contain SATA
 710   port multipliers. SATA port multipliers behave like SATA bridges and can support
 711   up to 16 devices on the other side. If a SATA port out of the IDE controller
 712   is connected to a port multiplier, MaxDevices will be set to the number of SATA
 713   devices that the port multiplier supports. Because today's port multipliers
 714   support up to fifteen SATA devices, this number can be as large as fifteen. The IDE
 715   bus driver is required to scan for the presence of port multipliers behind an SATA
 716   controller and enumerate up to MaxDevices number of devices behind the port
 717   multiplier.
 718
 719   In this context, the devices behind a port multiplier constitute a channel.
 720
 721   @param[in]  This         The pointer to the EFI_IDE_CONTROLLER_INIT_PROTOCOL instance.
 722   @param[in]  Channel      Zero-based channel number.
 723   @param[out] Enabled      TRUE if this channel is enabled.  Disabled channels
 724                            are not scanned to see if any devices are present.
 725   @param[out] MaxDevices   The maximum number of IDE devices that the bus driver
 726                            can expect on this channel.  For the ATA/ATAPI
 727                            specification, version 6, this number will either be
 728                            one or two. For Serial ATA (SATA) configurations with a
 729                            port multiplier, this number can be as large as fifteen.
 730
 731   @retval EFI_SUCCESS             Information was returned without any errors.
 732   @retval EFI_INVALID_PARAMETER   Channel is invalid (Channel >= ChannelCount).
 733
 734 **/
 735 EFI_STATUS
 736 EFIAPI
 737 IdeInitGetChannelInfo (
 738   IN EFI_IDE_CONTROLLER_INIT_PROTOCOL  *This,
 739   IN UINT8                             Channel,
 740   OUT BOOLEAN                          *Enabled,
 741   OUT UINT8                            *MaxDevices
 742   )
 743 {
 744   EFI_SATA_CONTROLLER_PRIVATE_DATA  *SataPrivateData;
 745
 746   SataPrivateData = SATA_CONTROLLER_PRIVATE_DATA_FROM_THIS (This);
 747   ASSERT (SataPrivateData != NULL);
 748
 749   if (Channel < This->ChannelCount) {
 750     *Enabled    = TRUE;
 751     *MaxDevices = SataPrivateData->DeviceCount;
 752     return EFI_SUCCESS;
 753   }
 754
 755   *Enabled = FALSE;
 756   return EFI_INVALID_PARAMETER;
 757 }
 758
 759 /**
 760   The notifications from the driver entity that it is about to enter a certain
 761   phase of the IDE channel enumeration process.
 762
 763   This function can be used to notify the IDE controller driver to perform
 764   specific actions, including any chipset-specific initialization, so that the
 765   chipset is ready to enter the next phase. Seven notification points are defined
 766   at this time.
 767
 768   More synchronization points may be added as required in the future.
 769
 770   @param[in] This      The pointer to the EFI_IDE_CONTROLLER_INIT_PROTOCOL instance.
 771   @param[in] Phase     The phase during enumeration.
 772   @param[in] Channel   Zero-based channel number.
 773
 774   @retval EFI_SUCCESS             The notification was accepted without any errors.
 775   @retval EFI_UNSUPPORTED         Phase is not supported.
 776   @retval EFI_INVALID_PARAMETER   Channel is invalid (Channel >= ChannelCount).
 777   @retval EFI_NOT_READY           This phase cannot be entered at this time; for
 778                                   example, an attempt was made to enter a Phase
 779                                   without having entered one or more previous
 780                                   Phase.
 781
 782 **/
 783 EFI_STATUS
 784 EFIAPI
 785 IdeInitNotifyPhase (
 786   IN EFI_IDE_CONTROLLER_INIT_PROTOCOL  *This,
 787   IN EFI_IDE_CONTROLLER_ENUM_PHASE     Phase,
 788   IN UINT8                             Channel
 789   )
 790 {
 791   return EFI_SUCCESS;
 792 }
 793
 794 /**
 795   Submits the device information to the IDE controller driver.
 796
 797   This function is used by the driver entity to pass detailed information about
 798   a particular device to the IDE controller driver. The driver entity obtains
 799   this information by issuing an ATA or ATAPI IDENTIFY_DEVICE command. IdentifyData
 800   is the pointer to the response data buffer. The IdentifyData buffer is owned
 801   by the driver entity, and the IDE controller driver must make a local copy
 802   of the entire buffer or parts of the buffer as needed. The original IdentifyData
 803   buffer pointer may not be valid when
 804
 805     - EFI_IDE_CONTROLLER_INIT_PROTOCOL.CalculateMode() or
 806     - EFI_IDE_CONTROLLER_INIT_PROTOCOL.DisqualifyMode() is called at a later point.
 807
 808   The IDE controller driver may consult various fields of EFI_IDENTIFY_DATA to
 809   compute the optimum mode for the device. These fields are not limited to the
 810   timing information. For example, an implementation of the IDE controller driver
 811   may examine the vendor and type/mode field to match known bad drives.
 812
 813   The driver entity may submit drive information in any order, as long as it
 814   submits information for all the devices belonging to the enumeration group
 815   before EFI_IDE_CONTROLLER_INIT_PROTOCOL.CalculateMode() is called for any device
 816   in that enumeration group. If a device is absent, EFI_IDE_CONTROLLER_INIT_PROTOCOL.SubmitData()
 817   should be called with IdentifyData set to NULL.  The IDE controller driver may
 818   not have any other mechanism to know whether a device is present or not. Therefore,
 819   setting IdentifyData to NULL does not constitute an error condition.
 820   EFI_IDE_CONTROLLER_INIT_PROTOCOL.SubmitData() can be called only once for a
 821   given (Channel, Device) pair.
 822
 823   @param[in] This           A pointer to the EFI_IDE_CONTROLLER_INIT_PROTOCOL instance.
 824   @param[in] Channel        Zero-based channel number.
 825   @param[in] Device         Zero-based device number on the Channel.
 826   @param[in] IdentifyData   The device's response to the ATA IDENTIFY_DEVICE command.
 827
 828   @retval EFI_SUCCESS             The information was accepted without any errors.
 829   @retval EFI_INVALID_PARAMETER   Channel is invalid (Channel >= ChannelCount).
 830   @retval EFI_INVALID_PARAMETER   Device is invalid.
 831
 832 **/
 833 EFI_STATUS
 834 EFIAPI
 835 IdeInitSubmitData (
 836   IN EFI_IDE_CONTROLLER_INIT_PROTOCOL  *This,
 837   IN UINT8                             Channel,
 838   IN UINT8                             Device,
 839   IN EFI_IDENTIFY_DATA                 *IdentifyData
 840   )
 841 {
 842   EFI_SATA_CONTROLLER_PRIVATE_DATA  *SataPrivateData;
 843   UINTN                             DeviceIndex;
 844
 845   SataPrivateData = SATA_CONTROLLER_PRIVATE_DATA_FROM_THIS (This);
 846   ASSERT (SataPrivateData != NULL);
 847
 848   if ((Channel >= This->ChannelCount) || (Device >= SataPrivateData->DeviceCount)) {
 849     return EFI_INVALID_PARAMETER;
 850   }
 851
 852   DeviceIndex = FlatDeviceIndex (SataPrivateData, Channel, Device);
 853
 854   //
 855   // Make a local copy of device's IdentifyData and mark the valid flag
 856   //
 857   if (IdentifyData != NULL) {
 858     CopyMem (
 859       &(SataPrivateData->IdentifyData[DeviceIndex]),
 860       IdentifyData,
 861       sizeof (EFI_IDENTIFY_DATA)
 862       );
 863
 864     SataPrivateData->IdentifyValid[DeviceIndex] = TRUE;
 865   } else {
 866     SataPrivateData->IdentifyValid[DeviceIndex] = FALSE;
 867   }
 868
 869   return EFI_SUCCESS;
 870 }
 871
 872 /**
 873   Disqualifies specific modes for an IDE device.
 874
 875   This function allows the driver entity or other drivers (such as platform
 876   drivers) to reject certain timing modes and request the IDE controller driver
 877   to recalculate modes. This function allows the driver entity and the IDE
 878   controller driver to negotiate the timings on a per-device basis. This function
 879   is useful in the case of drives that lie about their capabilities. An example
 880   is when the IDE device fails to accept the timing modes that are calculated
 881   by the IDE controller driver based on the response to the Identify Drive command.
 882
 883   If the driver entity does not want to limit the ATA timing modes and leave that
 884   decision to the IDE controller driver, it can either not call this function for
 885   the given device or call this function and set the Valid flag to FALSE for all
 886   modes that are listed in EFI_ATA_COLLECTIVE_MODE.
 887
 888   The driver entity may disqualify modes for a device in any order and any number
 889   of times.
 890
 891   This function can be called multiple times to invalidate multiple modes of the
 892   same type (e.g., Programmed Input/Output [PIO] modes 3 and 4). See the ATA/ATAPI
 893   specification for more information on PIO modes.
 894
 895   For Serial ATA (SATA) controllers, this member function can be used to disqualify
 896   a higher transfer rate mode on a given channel. For example, a platform driver
 897   may inform the IDE controller driver to not use second-generation (Gen2) speeds
 898   for a certain SATA drive.
 899
 900   @param[in] This       The pointer to the EFI_IDE_CONTROLLER_INIT_PROTOCOL instance.
 901   @param[in] Channel    The zero-based channel number.
 902   @param[in] Device     The zero-based device number on the Channel.
 903   @param[in] BadModes   The modes that the device does not support and that
 904                         should be disqualified.
 905
 906   @retval EFI_SUCCESS             The modes were accepted without any errors.
 907   @retval EFI_INVALID_PARAMETER   Channel is invalid (Channel >= ChannelCount).
 908   @retval EFI_INVALID_PARAMETER   Device is invalid.
 909   @retval EFI_INVALID_PARAMETER   IdentifyData is NULL.
 910
 911 **/
 912 EFI_STATUS
 913 EFIAPI
 914 IdeInitDisqualifyMode (
 915   IN EFI_IDE_CONTROLLER_INIT_PROTOCOL  *This,
 916   IN UINT8                             Channel,
 917   IN UINT8                             Device,
 918   IN EFI_ATA_COLLECTIVE_MODE           *BadModes
 919   )
 920 {
 921   EFI_SATA_CONTROLLER_PRIVATE_DATA  *SataPrivateData;
 922   UINTN                             DeviceIndex;
 923
 924   SataPrivateData = SATA_CONTROLLER_PRIVATE_DATA_FROM_THIS (This);
 925   ASSERT (SataPrivateData != NULL);
 926
 927   if ((Channel >= This->ChannelCount) || (BadModes == NULL) || (Device >= SataPrivateData->DeviceCount)) {
 928     return EFI_INVALID_PARAMETER;
 929   }
 930
 931   DeviceIndex = FlatDeviceIndex (SataPrivateData, Channel, Device);
 932
 933   //
 934   // Record the disqualified modes per channel per device. From ATA/ATAPI spec,
 935   // if a mode is not supported, the modes higher than it is also not supported.
 936   //
 937   CopyMem (
 938     &(SataPrivateData->DisqualifiedModes[DeviceIndex]),
 939     BadModes,
 940     sizeof (EFI_ATA_COLLECTIVE_MODE)
 941     );
 942
 943   return EFI_SUCCESS;
 944 }
 945
 946 /**
 947   Returns the information about the optimum modes for the specified IDE device.
 948
 949   This function is used by the driver entity to obtain the optimum ATA modes for
 950   a specific device.  The IDE controller driver takes into account the following
 951   while calculating the mode:
 952     - The IdentifyData inputs to EFI_IDE_CONTROLLER_INIT_PROTOCOL.SubmitData()
 953     - The BadModes inputs to EFI_IDE_CONTROLLER_INIT_PROTOCOL.DisqualifyMode()
 954
 955   The driver entity is required to call EFI_IDE_CONTROLLER_INIT_PROTOCOL.SubmitData()
 956   for all the devices that belong to an enumeration group before calling
 957   EFI_IDE_CONTROLLER_INIT_PROTOCOL.CalculateMode() for any device in the same group.
 958
 959   The IDE controller driver will use controller- and possibly platform-specific
 960   algorithms to arrive at SupportedModes.  The IDE controller may base its
 961   decision on user preferences and other considerations as well. This function
 962   may be called multiple times because the driver entity may renegotiate the mode
 963   with the IDE controller driver using EFI_IDE_CONTROLLER_INIT_PROTOCOL.DisqualifyMode().
 964
 965   The driver entity may collect timing information for various devices in any
 966   order. The driver entity is responsible for making sure that all the dependencies
 967   are satisfied. For example, the SupportedModes information for device A that
 968   was previously returned may become stale after a call to
 969   EFI_IDE_CONTROLLER_INIT_PROTOCOL.DisqualifyMode() for device B.
 970
 971   The buffer SupportedModes is allocated by the callee because the caller does
 972   not necessarily know the size of the buffer. The type EFI_ATA_COLLECTIVE_MODE
 973   is defined in a way that allows for future extensibility and can be of variable
 974   length. This memory pool should be deallocated by the caller when it is no
 975   longer necessary.
 976
 977   The IDE controller driver for a Serial ATA (SATA) controller can use this
 978   member function to force a lower speed (first-generation [Gen1] speeds on a
 979   second-generation [Gen2]-capable hardware).  The IDE controller driver can
 980   also allow the driver entity to stay with the speed that has been negotiated
 981   by the physical layer.
 982
 983   @param[in]  This             The pointer to the EFI_IDE_CONTROLLER_INIT_PROTOCOL instance.
 984   @param[in]  Channel          A zero-based channel number.
 985   @param[in]  Device           A zero-based device number on the Channel.
 986   @param[out] SupportedModes   The optimum modes for the device.
 987
 988   @retval EFI_SUCCESS             SupportedModes was returned.
 989   @retval EFI_INVALID_PARAMETER   Channel is invalid (Channel >= ChannelCount).
 990   @retval EFI_INVALID_PARAMETER   Device is invalid.
 991   @retval EFI_INVALID_PARAMETER   SupportedModes is NULL.
 992   @retval EFI_NOT_READY           Modes cannot be calculated due to a lack of
 993                                   data.  This error may happen if
 994                                   EFI_IDE_CONTROLLER_INIT_PROTOCOL.SubmitData()
 995                                   and EFI_IDE_CONTROLLER_INIT_PROTOCOL.DisqualifyData()
 996                                   were not called for at least one drive in the
 997                                   same enumeration group.
 998
 999 **/
1000 EFI_STATUS
1001 EFIAPI
1002 IdeInitCalculateMode (
1003   IN EFI_IDE_CONTROLLER_INIT_PROTOCOL  *This,
1004   IN UINT8                             Channel,
1005   IN UINT8                             Device,
1006   OUT EFI_ATA_COLLECTIVE_MODE          **SupportedModes
1007   )
1008 {
1009   EFI_SATA_CONTROLLER_PRIVATE_DATA  *SataPrivateData;
1010   EFI_IDENTIFY_DATA                 *IdentifyData;
1011   BOOLEAN                           IdentifyValid;
1012   EFI_ATA_COLLECTIVE_MODE           *DisqualifiedModes;
1013   UINT16                            SelectedMode;
1014   EFI_STATUS                        Status;
1015   UINTN                             DeviceIndex;
1016
1017   SataPrivateData = SATA_CONTROLLER_PRIVATE_DATA_FROM_THIS (This);
1018   ASSERT (SataPrivateData != NULL);
1019
1020   if ((Channel >= This->ChannelCount) || (SupportedModes == NULL) || (Device >= SataPrivateData->DeviceCount)) {
1021     return EFI_INVALID_PARAMETER;
1022   }
1023
1024   *SupportedModes = AllocateZeroPool (sizeof (EFI_ATA_COLLECTIVE_MODE));
1025   if (*SupportedModes == NULL) {
1026     ASSERT (*SupportedModes != NULL);
1027     return EFI_OUT_OF_RESOURCES;
1028   }
1029
1030   DeviceIndex = FlatDeviceIndex (SataPrivateData, Channel, Device);
1031
1032   IdentifyData      = &(SataPrivateData->IdentifyData[DeviceIndex]);
1033   IdentifyValid     = SataPrivateData->IdentifyValid[DeviceIndex];
1034   DisqualifiedModes = &(SataPrivateData->DisqualifiedModes[DeviceIndex]);
1035
1036   //
1037   // Make sure we've got the valid identify data of the device from SubmitData()
1038   //
1039   if (!IdentifyValid) {
1040     FreePool (*SupportedModes);
1041     return EFI_NOT_READY;
1042   }
1043
1044   Status = CalculateBestPioMode (
1045              IdentifyData,
1046              (DisqualifiedModes->PioMode.Valid ? ((UINT16 *)&(DisqualifiedModes->PioMode.Mode)) : NULL),
1047              &SelectedMode
1048              );
1049   if (!EFI_ERROR (Status)) {
1050     (*SupportedModes)->PioMode.Valid = TRUE;
1051     (*SupportedModes)->PioMode.Mode  = SelectedMode;
1052   } else {
1053     (*SupportedModes)->PioMode.Valid = FALSE;
1054   }
1055
1056   DEBUG ((DEBUG_INFO, "IdeInitCalculateMode: PioMode = %x\n", (*SupportedModes)->PioMode.Mode));
1057
1058   Status = CalculateBestUdmaMode (
1059              IdentifyData,
1060              (DisqualifiedModes->UdmaMode.Valid ? ((UINT16 *)&(DisqualifiedModes->UdmaMode.Mode)) : NULL),
1061              &SelectedMode
1062              );
1063
1064   if (!EFI_ERROR (Status)) {
1065     (*SupportedModes)->UdmaMode.Valid = TRUE;
1066     (*SupportedModes)->UdmaMode.Mode  = SelectedMode;
1067   } else {
1068     (*SupportedModes)->UdmaMode.Valid = FALSE;
1069   }
1070
1071   DEBUG ((DEBUG_INFO, "IdeInitCalculateMode: UdmaMode = %x\n", (*SupportedModes)->UdmaMode.Mode));
1072
1073   //
1074   // The modes other than PIO and UDMA are not supported
1075   //
1076   return EFI_SUCCESS;
1077 }
1078
1079 /**
1080   Commands the IDE controller driver to program the IDE controller hardware
1081   so that the specified device can operate at the specified mode.
1082
1083   This function is used by the driver entity to instruct the IDE controller
1084   driver to program the IDE controller hardware to the specified modes. This
1085   function can be called only once for a particular device. For a Serial ATA
1086   (SATA) Advanced Host Controller Interface (AHCI) controller, no controller-
1087   specific programming may be required.
1088
1089   @param[in] This      Pointer to the EFI_IDE_CONTROLLER_INIT_PROTOCOL instance.
1090   @param[in] Channel   Zero-based channel number.
1091   @param[in] Device    Zero-based device number on the Channel.
1092   @param[in] Modes     The modes to set.
1093
1094   @retval EFI_SUCCESS             The command was accepted without any errors.
1095   @retval EFI_INVALID_PARAMETER   Channel is invalid (Channel >= ChannelCount).
1096   @retval EFI_INVALID_PARAMETER   Device is invalid.
1097   @retval EFI_NOT_READY           Modes cannot be set at this time due to lack of data.
1098   @retval EFI_DEVICE_ERROR        Modes cannot be set due to hardware failure.
1099                                   The driver entity should not use this device.
1100
1101 **/
1102 EFI_STATUS
1103 EFIAPI
1104 IdeInitSetTiming (
1105   IN EFI_IDE_CONTROLLER_INIT_PROTOCOL  *This,
1106   IN UINT8                             Channel,
1107   IN UINT8                             Device,
1108   IN EFI_ATA_COLLECTIVE_MODE           *Modes
1109   )
1110 {
1111   return EFI_SUCCESS;
1112 }