7.2 UEFI Driver Model

Drivers that follow the UEFI driver model are not allowed to touch any hardware in their driver entry point. In fact, these types of drivers do very little in their driver entry point.

They are required to register protocol interfaces in the Handle Database and may also choose to register HII packages in the HII Database, register an Unload() service in the UEFI Driver's Loaded Image Protocol, and create events that are signaled when an operating system calls ExitBootServices() or SetVirtualAddressMap(). This design allows these types of drivers to be loaded at any point in the system initialization sequence because their driver entry points depend only on a few of the UEFI boot services. The items registered in the driver entry point are used later in the boot sequence to initialize, configure, or diagnose devices required to boot an operating system.

All UEFI drivers following the UEFI driver model must install one or more instances of the Driver Binding Protocol onto handles in the handle database. The first Driver Binding Protocol is typically installed onto the ImageHandle passed into the UEFI Driver entry point. Additional instances of the Driver Binding Protocol must be installed onto new handles in the Handle Database.

The EDK II library UefiLib provides four functions that simplify the implementation of the driver entry point of a UEFI driver. The examples in this section make use of these driver initialization functions as shown in the following example.

Example 88-EDK II UefiLib driver initialization functions

EFI_STATUS
EFIAPI
EfiLibInstallDriverBinding (
  IN CONST EFI_HANDLE ImageHandle,
  IN CONST EFI_SYSTEM_TABLE       *SystemTable,
  IN EFI_DRIVER_BINDING_PROTOCOL  *DriverBinding,
  IN EFI_HANDLE DriverBindingHandle
  );

EFI_STATUS
EFIAPI
EfiLibInstallAllDriverProtocols (
  IN CONST EFI_HANDLE                                  ImageHandle,
  IN CONST EFI_SYSTEM_TABLE                            *SystemTable,
  IN EFI_DRIVER_BINDING_PROTOCOL                       *DriverBinding,
  IN EFI_HANDLE                                        DriverBindingHandle,
  IN CONST EFI_COMPONENT_NAME_PROTOCOL                 *ComponentName,
  OPTIONAL IN CONST EFI_DRIVER_CONFIGURATION_PROTOCOL  *DriverConfiguration, OPTIONAL
  IN CONST EFI_DRIVER_DIAGNOSTICS_PROTOCOL             *DriverDiagnostics OPTIONAL
  );

EFI_STATUS
EFIAPI
EfiLibInstallDriverBindingComponentName2 (
  IN CONST EFI_HANDLE                    ImageHandle,
  IN CONST EFI_SYSTEM_TABLE              *SystemTable,
  IN EFI_DRIVER_BINDING_PROTOCOL         *DriverBinding,
  IN EFI_HANDLE                          DriverBindingHandle,
  IN CONST EFI_COMPONENT_NAME_PROTOCOL   *ComponentName, OPTIONAL
  IN CONST EFI_COMPONENT_NAME2_PROTOCOL  *ComponentName2 OPTIONAL
  );

EFI_STATUS
EFIAPI
EfiLibInstallAllDriverProtocols2 (
  IN CONST EFI_HANDLE                          ImageHandle,
  IN CONST EFI_SYSTEM_TABLE                    *SystemTable,
  IN EFI_DRIVER_BINDING_PROTOCOL               *DriverBinding,
  IN EFI_HANDLE                                DriverBindingHandle,
  IN CONST EFI_COMPONENT_NAME_PROTOCOL         *ComponentName, OPTIONAL
  IN CONST EFI_COMPONENT_NAME2_PROTOCOL        *ComponentName2, OPTIONAL
  IN CONST EFI_DRIVER_CONFIGURATION_PROTOCOL   *DriverConfiguration, OPTIONAL
  IN CONST EFI_DRIVER_CONFIGURATION2_PROTOCOL  *DriverConfiguration2, OPTIONAL
  IN CONST EFI_DRIVER_DIAGNOSTICS_PROTOCOL     *DriverDiagnostics, OPTIONAL
  IN CONST EFI_DRIVER_DIAGNOSTICS2_PROTOCOL    *DriverDiagnostics2 OPTIONAL
  );

EfiLibInstallDriverBinding() installs the Driver Binding Protocol onto the handle specified by DriverBindingHandle. DriverBindingHandle is typically the same as ImageHandle, but if it is NULL, the Driver Binding Protocol is installed onto a newly created handle. This function is typically used by a UEFI Driver that does not implement any of the optional driver features.

EfiLibInstallAllDriverProtocols() installs the Driver Binding Protocol, and the driverrelated protocols from the older UEFI Specification (and EFI Specification), onto the handle specified by DriverBindingHandle. The optional driver-related protocols are defined as OPTIONAL because they can be NULL if a driver is not producing that specific optional protocol. Once again, the DriverBindingHandle is typically the same as ImageHandle, but if it is NULL, all driver-related protocols are installed onto a newly created handle. This function is typically used by a UEFI Driver required to be compatible with the EFI 1.10 Specification.

EfiLibInstallDriverBindingComponentName2() installs the Driver Binding Protocol and the Component Name Protocols onto the handle specified by DriverBindingHandle. The optional driver-related protocols are defined as OPTIONAL because they can be NULL if a driver is not producing that specific optional protocol. Once again, the DriverBindingHandle is typically the same as ImageHandle, but if it is NULL, all driverrelated protocols are installed onto a newly created handle. This function is typically used by a UEFI Driver that implements the Component Name Protocols that are strongly recommended.

EfiLibInstallAllDriverProtocols2() installs the Driver Binding Protocol, Component Name Protocols, Driver Configuration Protocols, and Driver Diagnostics Protocols onto the handle specified by DriverBindingHandle. The optional driver-related protocols are defined as OPTIONAL because they can be NULL if a driver is not producing that specific optional protocol. Once again, the DriverBindingHandle is typically the same as ImageHandle, but if it is NULL, all driver-related protocols are installed onto a newly created handle. This function is typically used by a UEFI Driver required to be compatible with all versions of the UEFI Specification and EFI Specification.