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