18.3.2 Start() and Stop()

The Start() service of the Driver Binding Protocol for a PCI driver also opens the PCI I/O Protocol with an attribute of EFI_OPEN_PROTOCOL_BY_DRIVER. If the PCI driver is a bus or hybrid driver, the Device Path Protocol opens using the attribute EFI_OPEN_PROTOCOL_BY_DRIVER. A device driver is not required to open the Device Path Protocol. In addition, all PCI drivers are required to call the Attributes() service of the PCI I/O Protocol to enable the I/O, memory, and bus master bits in the Command register of the PCI configuration header. By default, the PCI bus driver is not required to enable the Command register of the PCI controllers. Instead, it is the responsibility of the Start() service to enable these bits and that of the Stop() service to restore these bits. In order for the Stop() service to restore the attributes, a PCI Driver typically stores the original attributes in a UINT64 field of the private context data structure.

There is one additional attribute that must be specified in this call to the Attributes() service. If the PCI controller is a bus master and capable of generating 64-bit DMA addresses, the EFI_PCI_IO_ATTRIBUTE_DUAL_ADDRESS_CYCLE attribute must also be enabled. Unfortunately, there is no standard method for detecting if a PCI controller supports 32-bit or 64-bit DMA addresses. As a result, it is the PCI driver's responsibility to inform the PCI bus driver that the PCI controller is capable of producing 64-bit DMA addresses.

The PCI bus driver assumes that all PCI controllers are only capable of generating 32-bit DMA addresses unless the PCI driver enables the dual address cycle attribute.

The PCI bus driver uses this information along with the services of the PCI Root Bridge I/O Protocol to perform PCI DMA transactions. If a PCI bus master that is capable of 32-bit DMA addresses is present in a platform supporting more than 4 GB of system memory, the DMA transactions may have to be double buffered. Double buffering can reduce the performance of a driver. It is also possible for some platforms to only support system memory above 4 GB. For these reasons, a PCI driver must always accurately describe the DMA capabilities of the PCI controller from the Start() service of the Driver Binding Protocol.

The example below shows the code fragment from the Start()services of a PCI driver for a PCI controller supporting 64-bit DMA transactions. The example opens the PCI I/O Protocol attribute of EFI_OPEN_PROTOCOL_BY_DRIVER. It then retrieves the current set of PCI I/O Protocol attributes and saves them in the private context data structure field called ABC_PRIVATE_DATA. It then determines what attribute the PCI I/O Protocol supports and enables the I/O decode, MMIO decode, and Bus Master, and Dual Address Cycle capabilities. If a PCI Controller does not support DAC, the only change is the removal of EFI_PCI_IO_ATTRIBUTE_DUAL_ADDRESS_CYCLE from the last call to the Attributes() service of the PCI I/O Protocol.

Example 171-Start() for a 64-bit DMA-capable PCI controller

#include <Uefi.h>
#include <Protocol/DriverBinding.h>
#include <Protocol/PciIo.h>
#include <Library/UefiBootServicesTableLib.h>

typedef struct {
  UINTN Signature;
  //
  // . .
  //
  UINT64 OriginalPciAttributes;
} ABC_PRIVATE_DATA;

EFI_STATUS Status;
EFI_DRIVER_BINDING_PROTOCOL *This;
EFI_HANDLE ControllerHandle;
ABC_PRIVATE_DATA *Private;
EFI_PCI_IO_PROTOCOL *PciIo;
UINT64 PciSupports;

//
// Open the PCI I/O Protocol
//
Status = gBS->OpenProtocol (
                ControllerHandle,
                &gEfiPciIoProtocolGuid,
                (VOID **)&PciIo,
                This->DriverBindingHandle,
                ControllerHandle,
                EFI_OPEN_PROTOCOL_BY_DRIVER
                );
if (EFI_ERROR (Status)) {
  goto Done;
}

//
// Retrieve original PCI attributes and save them in the private context data
// structure.
//
Status = PciIo->Attributes (
                  PciIo,
                  EfiPciIoAttributeOperationGet,
                  0,
                  &Private->OriginalPciAttributes
                  );
if (EFI_ERROR (Status)) {
  goto Done;
}

//
// Retrieve attributes that the PCI Controller supports
//
Status = PciIo->Attributes (
                  PciIo,
                  EfiPciIoAttributeOperationSupported,
                  0,
                  &PciSupports
                  );
if (EFI_ERROR (Status)) {
  goto Done;
}

//
// Enable Command register and Dual Address Cycle
//
Status = PciIo->Attributes (
                  PciIo,
                  EfiPciIoAttributeOperationEnable,
                  (PciSupports & EFI_PCI_DEVICE_ENABLE) |
                  EFI_PCI_IO_ATTRIBUTE_DUAL_ADDRESS_CYCLE,
                  NULL
                  );
if (EFI_ERROR (Status)) {
  goto Done;
}

This example shows the code fragment from the Stop()services of a PCI driver. This example restores the PCI I/O Protocol attributes from a field of the private context data structure called ABC_PRIVATE_DATA.

Example 172-Restore PCI Attributes in Stop()

#include <Uefi.h>
#include <Protocol/PciIo.h>
#include <Library/UefiBootServicesTableLib.h>

EFI_STATUS Status;
EFI_PCI_IO_PROTOCOL *PciIo;
ABC_PRIVATE_DATA *Private;
//
// Restore original PCI attributes
//
PciIo->Attributes (
         PciIo,
         EfiPciIoAttributeOperationSet,
         Private->OriginalPciAttributes,
         NULL
         );
//
// Close the PCI I/O Protocol
//
gBS->CloseProtocol (
       ControllerHandle,
       &gEfiPciIoProtocolGuid,
       This->DriverBindingHandle,
       ControllerHandle
       );

The following table lists the #define statements compatible with the Attributes() service. A PCI driver must use the Attributes() service to enable the decodes on the PCI controller, accurately describe the PCI controller DMA capabilities, and request that specific I/O cycles are forwarded to the device. The call to Attributes() fails if the request cannot be satisfied. If this failure occurs, the Start() function must return an error.

Once again, any attributes enabled in the Start() service must be restored in the Stop() service.

Table 26-PCI Attributes

The table below, lists #define statements not part of the UEFI Specification, but which are included in EDK II to simplify PCI driver implementations. These attributes cover the typical classes of hardware capabilities and provide a names for common combinations of attributes described in the PCI Bus Support chapter of the UEFI Specification.

TIP: For code readability, the Enable attributes included in EDK II should be used.

Table 27-EDK II attributes #defines

This table lists the #define statements that to use with the GetBarAttributes() and SetBarAttributes() services to adjust the attributes of a memory-mapped I/O region described by a Base Address Register (BAR) of a PCI controller. The support of these attributes is optional, but in general, a PCI driver uses these attributes to provide hints that may be used to improve the performance of a PCI driver. Improved performance is especially important for PCI drivers managing graphics controllers. Do note that any BAR attributes set in the Start() service must be restored in the Stop() service.

Table 28-PCI BAR attributes

Sometimes there may be different logic paths in a UEFI Driver between a PCI add-in card and a PCI controller integrated into a platform. The PCI I/O Protocol provides attributes that help a UEFI Driver determine if a specific PCI Controller and its associated PCI Option ROM image are from a PCI add-in card in a PCI slot or if they are integrated into a platform. The attributes shown in the following table list the #define statements for these attributes. These attributes are read-only and the values are established by the PCI Bus Driver when a PCI Controller is discovered and the PCI I/O Protocol is produced. A PCI driver may retrieve the attributes of a PCI controller with the Attributes() service of the PCI I/O Protocol, but a PCI Driver is not allowed to modify these attributes.

Table 29-PCI Embedded Device Attributes