MdeModulePkg/Bus/Pci/SataControllerDxe/SataController.c

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