UEFI Drivers

UEFI / Framework Special Topic

Copyright 2007 Intel Corporation

UEFI / Framework Special Topic
Slide 1

UEFI Driver Model

Used for devices on industry standard buses
boot devices
Structured model of device/bus hierarchy
Device Drivers and Bus Drivers
Device Drivers are topology agnostic
Benefits
Simpler Device Drivers
Moves complexity into Bus Drivers and core services
Smaller driver footprint

Deterministic driver selection by the platform

Which driver controls which device

Describes complex bus hierarchies

Embedded, Desktop, Workstation, Server

Extensible to future bus types

Use
Useof
of multilayer
multilayer modularity
modularitymeans
means
UEFI
/
Framework
Special
more
morescenarios
scenariosjust
justwork
workTopicSlide 2

UEFI Drivers

UEFI Driver Model

Supports complex bus hierarchies
Follows the organization of physical/electrical architecture of
the machine

Driver Binding Protocol provides flexibility

Function to match drivers to devices
Driver version management
Hot-plug and unload support

Drivers not tied to FLASH

Can be loaded from UEFI System Partition

Extensible
Able to extend to future bus and device types
UEFI / Framework Special Topic
Slide 3

UEFI Driver Design

Modular chunks of code run in pre-boot
Manage devices or services
they are NOT OS-present drivers!

Drivers export protocol interfaces

Protocol = instance data + access methods

Like C++ classes but more code space efficient
Identified by GUID to avoid collisions
Version numbers and signatures provide means to
manage driver management policy

Drivers may consume protocol interfaces

Self-describing dependencies
E.g. Memory initialization may depend on SMBUS service

UEFI / Framework Special Topic

Slide 4

UEFI Drivers

Driver Design Steps

1.
2.
3.
4.
5.
6.

Determine Driver Type

Identify Consumed I/O Protocols
Identify Produced I/O Protocols
Identify UEFI Driver Model Protocols
Identify Additional Driver Features
Identify Target Platforms

x86
x64
Itanium Processor Family
EFI Byte Code (EBC)
UEFI / Framework Special Topic
Slide 5

UEFI Drivers

CPU

Complex System Example

IBA BUS

North
Bridge

CPU
PCI BUS

IBA-PCI
Bridge

PCI-IBA
Bridge

USB BUS

USB

KBD

VGA

PCI-ISA
Bridge

Mouse

Removable
Media
(floppy)

ISA BUS

Manageable by UEFI Driver Model

SCSI

PCI BUS
Hard
Drive
Hard
Drive
Hard
Drive
Hard
Drive

See 2.5 UEFI 2.1 Spec.

UEFI / Framework Special Topic

Slide 6

UEFI Drivers

What Type of Driver is Being Designed?

UEFI Images
Drivers
Service Drivers

UEFI Driver Model

Initializing Drivers
Root Bridge
Drivers

Device
BusBus Hybrid Device
Drivers Drivers Drivers
Drivers
Drivers

Applications
OS Loaders
UEFI / Framework Special Topic
Slide 7

Device Driver
Consumes Bus I/O Abstraction(s)
Initializes Device Controller
Produces Device Abstraction(s)
Block I/O Protocol
Simple Text Output Protocol
Simple Network Protocol

Does Not Create Any Child Handles

Can still be a Parent Controller
UEFI / Framework Special Topic
Slide 8

UEFI Drivers

Drivers
Service Drivers

UEFI Driver Model

Initializing Drivers
Root Bridge
Drivers

Bus
Drivers

Hybrid
Drivers

Device Drivers

Device
Drivers

Manages a Controller or Peripheral Device

Start() Does Not Create Any Child Handles
Start() Produces One or More I/O Protocols
Installed onto the Devices Controller Handle
Examples:
PCI Video Adapters
USB Host Controllers
USB Keyboards / USB Mice
PS/2 Keyboards / PS/2 Mice
UEFI / Framework Special Topic
Slide 9

Bus Driver

Consumes Parent Bus I/O Abstraction(s)

Initializes Bus Controller
Allocates Resources for Child Controllers
Creates Handles for Child Controllers
Loads drivers from Option ROMs if present
Child Controller Handle
EFI_DEVICE_PATH_PROTOCOL
EFI_XYZ_I/O_PROTOCOL

Optional

EFI_BUS_SPECIFIC_DRIVER_
OVERRIDE_PROTOCO

UEFI / Framework Special Topic

Slide 10

UEFI Drivers

Drivers
Service Drivers

UEFI Driver Model

Initializing Drivers
Root Bridge
Drivers

Bus
Drivers

Hybrid
Drivers

Bus Drivers

Device
Drivers

Manages and Enumerates a Bus Controller

Start() Creates One or More Child Handles
Start() Produces Bus Specific I/O Protocols
Installed onto the Buss Child Handles
Examples:
PCI Network Interface Controllers
Serial UART Controllers

UEFI / Framework Special Topic

Slide 11

UEFI Drivers
Drivers
Service Drivers

UEFI Driver Model

Hybrid Drivers

Initializing Drivers
Root Bridge
Drivers

Bus
Drivers

Hybrid
Drivers

Device
Drivers

Manages and Enumerates a Bus Controller

Start() Creates One or More Child Handles
Start() Produces Bus Specific I/O Protocols
Installed onto the Buss Controller Handle
Installed onto Buss Child Handles
Examples:
PCI SCSI Host Controllers
PCI Fiber Channel Controllers
UEFI / Framework Special Topic
Slide 12

UEFI Drivers

Drivers
Service Drivers

UEFI Driver Model

Initializing Drivers
Root Bridge
Drivers

Bus
Drivers

Hybrid
Drivers

Service Drivers

Device
Drivers

Does Not Manage Hardware

Provides Services to other Drivers
Does not support Driver Binding Protocol
Typically installs protocols in driver entry point
Creates One or More Service Handles
Produces Service Specific Protocols
Installed onto Service Handles

Examples:
UEFI Decompress Protocol
UEFI Byte Code Virtual Machine
Boot Integrity Services (BIS)
UEFI / Framework Special Topic
Slide 13

Driver Initialization
EFI Driver Handoff State
Not Allowed to Touch Hardware Resources
Installs Driver Binding on Driver Image Handle
Created by LoadImage()
Installed by LoadImage()
Installed in Driver Initialization
Implemented by Driver Writer

Driver Image Handle

EFI_LOADED_IMAGE
EFI_DRIVER_BINDING

Registers
RegistersDriver
Driverfor
forLater
LaterUse
Use
UEFI / Framework Special Topic
Slide 14

UEFI Drivers

Drivers
Service Drivers

UEFI Driver Model

Initializing Drivers
Root Bridge
Drivers

Bus
Drivers

Hybrid
Drivers

Initializing Drivers

Device
Drivers

Typically Touches Hardware

Performs One Time Initialization Operations
Does Not Create Any Handles
Does Not Produce Any Protocols
Unloaded When Finished
Examples: None
UEFI / Framework Special Topic
Slide 15

UEFI Drivers

Drivers
Service Drivers

UEFI Driver Model

Root Bridge Drivers

Initializing Drivers
Root Bridge
Drivers

Bus
Drivers

Hybrid
Drivers

Device
Drivers

Typically Manages Part of Core Chipset

Directly Touches Hardware
Creates One or More Root Bridge Handles
Produces Root Bridge I/O Protocols
Installed onto new Root a Bridge Handles
Examples: PCI Host Bridge

UEFI / Framework Special Topic

Slide 16

UEFI Drivers

What I/O Protocols are Consumed?

FLASH

PCI Adapters
PCI I/O Protocol
Device Path Protocol

USB Peripherals
USB I/O Protocol
Device Path Protocol

UEFI / Framework Special Topic

Slide 17

UEFI Drivers

What I/O Protocols are Produced?

FLASH

SCSI
SCSI RAID
Fiber Channel

SCSI Pass Thru Protocol

and
Block I/O Protocol
UEFI / Framework Special Topic
Slide 18

UEFI Drivers

What I/O Protocols are Produced?

FLASH

Network
Interface
Controller
(NIC)

Universal Network Driver Interface (UNDI)

and
Network Interface Identifier Protocol (NII)
UEFI / Framework Special Topic
Slide 19

UEFI Drivers

Responsibilities of Driver Writer

Driver Image Handle Required Protocols
Driver Image Handle
EFI_LOADED_IMAGE_PROTOCOL
Published by
Unload()
the driver
EFI_LOADED_IMAGE_PROTOCOL
EFI_DRIVER_BINDING_PROTOCOL
Supported()
Start()
Stop()
Version

Installed
by the
core
Installed
by the
driver

See 2.5.2 UEFI 2.1 Spec.

UEFI / Framework Special Topic

Slide 20

UEFI Drivers

More
Responsibilities of Driver Writer

Driver Image Handle Optional Protocols

Driver Image Handle
EFI_DRIVER_CONFIGURATION_PROTOCOL
SetOptions()
OptionValid()
ForceDefaults()
SupportedLanguages
EFI_DRIVER_DIAGNOSTICS_PROTOCOL
RunDiagnostics()
SupportedLanguages
EFI_COMPONENT_NAME_PROTOCOL
GetDriverName()
GetControllerName()
SupportedLanguages
UEFI / Framework Special Topic
Slide 21

UEFI Drivers

Driver Design Checklist

Driver Type

PCI
Video

PCI
RAID

PCI
NIC

Device

Hybrid

Bus
Bus

PCI I/O

PCI
PCII/O
I/O

I/O Protocols Consumed

PCI I/O

I/O Protocols Produced

Device Path

Device
DevicePath
Path

UGA Draw
UGA I/O

SCSI Pass Thru

Block I/O

UNDI,
UNDI,NII
NII

Driver Binding

Component Name

Driver Configuration

Driver Diagnostics

Unloadable

Exit Boot Services Event

Runtime

Set
SetVirtual
VirtualAddress
AddressMap
MapEvent
Event

UEFI / Framework Special Topic

Slide 22

UEFI Drivers

Running UEFI drivers

ConnectController()
Called from Boot Manager or during load
Precedence rules are applied

Context override
Platform override
Bus override
Version number

Order of which drivers are installed into handle

database is not deterministic

DisconnectController()
Must test and implement Stop()
UEFI / Framework Special Topic
Slide 23

UEFI Drivers

Implement, Test & Debug

See Backup Slides for Details
Required for IHVs
Optional for OEM/ODMs

Test Functions with EFI Shell Commands

Check for Leaks with EFI Shell Commands
Install UEFI Compliant Operating System
Boot UEFI Compliant Operating System
Debug Macros Identify Critical Failures
Use Same Techniques on all CPU Types
x86, x64, Itanium Processor Family, EBC
UEFI / Framework Special Topic
Slide 24

Driver Guidelines

Driver Guidelines

Dont touch hardware in Driver Entry

Keep Supported() small and simple
Move complex I/O into Start() and Stop()
Start() / Stop() mirror each other

InstallProtocolInterface() UninstallProtocolInterface()
OpenProtocol() CloseProtocol
AllocatePages() FreePages()
AllocatePool()
FreePool()

Driver Entry / Unload() mirror each other

UEFI / Framework Special Topic

Slide 25

Driver Guidelines

PCI Device Drivers

Always Call PciIo->Attributes()

Advertises Dual Address Cycle Capability
Save and Enable Attributes in Start()
Disable Attributes in Stop()

DMA Bus Master Write Operations

Must call PciIo->Flush()
DMA Setting Up with PciIo->Map()
Do Not Use Returned DeviceAddress
Not all chipsets have 1:1 bus/system mappings
UEFI / Framework Special Topic
Slide 26

Driver Guidelines

PCI Device Drivers Start()

Status = PciIo->Attributes(
PciIo,
EfiPciIoAttributeOperationGet,
0,
&ControllerContext->OriginalPciIoAttributes
);
if (EFI_ERROR (Status)) {
// Error Handling
}
Status = PciIo->Attributes(
PciIo,
EfiPciIoAttributeOperationEnable,
(EFI_PCI_IO_ATTRIBUTE_IO |
EFI_PCI_IO_ATTRIBUTE_MEMORY |
EFI_PCI_IO_ATTRIBUTE_BUS_MASTER |
EFI_PCI_IO_ATTRIBUTE_DUAL_ADDRESS_CYCLE),
0,
NULL
);
if (EFI_ERROR (Status)) {
// Error Handling
}

Save Original and Enable

UEFI / Framework Special Topic
Slide 27

Driver Guidelines

PCI Device Drivers Stop()

Status = PciIo->Attributes(
PciIo,
EfiPciIoAttributeOperationSet,
&ControllerContext->OriginalPciIoAttributes
NULL
);
if (EFI_ERROR (Status)) {
// Error Handling
}

Restore Original

UEFI / Framework Special Topic

Slide 28

Driver Guidelines

Preventing Alignment Faults

VOID
ScsiDeviceNodeInit (
IN OUT SCSI_DEVICE_PATH *ScsiDeviceNode,
IN
UINT16
Pun,
IN
UINT16
Lun
)
{
ScsiDeviceNode->Scsi.Header.Type
= MESSAGING_DEVICE_PATH;
ScsiDeviceNode->Scsi.Header.SubType
= MSG_SCSI_DP;
SetDevicePathNodeLength (&ScsiDeviceNode->Scsi.Header,
sizeof(SCSI_DEVICE_PATH));
ScsiDeviceNode->Scsi.Pun
= Pun;
ScsiDeviceNode->Scsi.Lun
= Lun;
}

BAD

ScsiDeviceNode may not be aligned

UEFI / Framework Special Topic
Slide 29

Driver Guidelines

Preventing Alignment Faults

VOID
ScsiDeviceNodeInit (
IN OUT SCSI_DEVICE_PATH *ScsiDeviceNode,
IN
UINT16
Pun,
IN
UINT16
Lun
)
{
SCSI_DEVICE_PATH MyDeviceNode;

GOOD

MyDeviceNode.Scsi.Header.Type
= MESSAGING_DEVICE_PATH;
MyDeviceNode.Scsi.Header.SubType
= MSG_SCSI_DP;
SetDevicePathNodeLength (&MyDeviceNode.Scsi.Header,
sizeof(SCSI_DEVICE_PATH));
MyDeviceNode.Scsi.Pun
= Pun;
MyDeviceNode.Scsi.Lun
= Lun;
gBS->CopyMem (ScsiDeviceNode,
&MyDeviceNode,
sizeof(SCSI_DEVICE_PATH));
}

gBS->CopyMem() handles all alignments

MyDeviceNode is aligned
UEFI / Framework Special Topic
Slide 30

Driver Guidelines

Use UEFI Driver Library Functions

CHILD_DEVICE

Child;

OK

Status = gBS->AllocatePool (
EfiBootServicesData,
sizeof (CHILD_DEVICE),
&Child
);
if (EFI_ERROR (Status)) {
return Status;
}
gBS->SetMem (Child, sizeof (CHILD_DEVICE), 0);
CHILD_DEVICE

Child;

GOOD

Child = EfiLibAllocateZeroPool (sizeof (CHILD_DEVICE));

if (Child == NULL) {
return EFI_OUT_OF_RESOURCES;
}

Library Functions Simplify Source Code

Library Functions May Reduce Size
UEFI / Framework Special Topic
Slide 31

Driver Guidelines

UEFI Device Paths

EFI_DRIVER_BINDING.Start()
Child->DevicePath = EfiAppendDevicePathNode

ControllerDevicePath,
ChildDevicePathNode
);
if (Child->DevicePath == NULL) {
return(EFI_OUT_OF_RESOURCES);
}

EFI_DRIVER_BINDING.Stop()
gBS->FreePool (Child->DevicePath);

Parent Device Path is Opaque

Not Parsed by Bus Drivers
UEFI / Framework Special Topic
Slide 32

Driver Guidelines

Bus Walk Tips

Use LocateHandleBuffer(Bus I/O Protocol)
Do not scan PCI configuration space

Implement support for RemainingDevicePath

Highly recommended for all bus drivers
(i.e. SCSI, Fibre Channel, etc.)

Allows bus driver to bypass full enumeration.

Reduces boot time

UEFI / Framework Special Topic

Slide 33

Driver Guidelines

Component Name Protocol

Limit Lengths of Names to 40 Unicode Characters

Include Driver Name and Version Number
UNDI Driver (Network Interface Controller)
Typically the Name of the PCI Controller

MAC Node Produced by an UNDI Driver

Identify Location of Physical Connector on NIC

PCI Slots
Identify Physical Location of PCI Slots in the System

SCSI / SCSI RAID / Fiber Channel

Controller - Typically name of the PCI Controller
Channel - Identify Physical Location of the SCSI Channel
Disk
- Use Results from INQUIRY Command

UEFI / Framework Special Topic

Slide 34

Driver Guidelines

Option ROM Size Reduction

Use UEFI Compression

Compile with EFI Byte Code Compiler

Single Binary for x86, x64 and Itanium

Smaller than Itanium Binaries
Comparable to x86 Binaries
Compresses Well ~ 50%

UEFI / Framework Special Topic

Slide 35

Driver Guidelines

1.
2.
3.
4.
5.
6.

How To Improve Portability

Do Not Assume Max Number of Children

Do Not Use Fixed Memory Addresses
Do Not Use Assembly
Do Not Use Floating Point Arithmetic
Some Minor EBC Porting Considerations
Bus Drivers Should Support Producing 1
Child at a time if possible (improves boot
performance)
Driver
DriverGuidelines
GuidelinesImprove
ImprovePortability
Portability

UEFI / Framework Special Topic

Slide 36

Driver Writers Guide

UEFI Driver Writers Guide

Captures Practical Experiences

Use as a Recipe Book
Must Read for all UEFI Driver Developers
Living Document
Content Based on Industry Feedback
Updated as Techniques are Refined
Updated as New Technologies are Introduced
EFI
EFI1.10
1.10
Driver
Writers
Guide
Driver Writers Guide
Draft
Draftfor
forReview
Review
Version 0.9
Version 0.9
July 20, 2004
July 20, 2004

UEFI / Framework Special Topic

Slide 37

Driver Writers Guide

General Topics
Overview of UEFI Concepts
UEFI Services
Commonly Used by UEFI Drivers
Rarely Used by UEFI Drivers
Should Not Be Used by UEFI Drivers

General Driver Design Guidelines

Classes of UEFI Drivers
Driver Entry Point
Private Context Data Structures
UEFI Driver Model Protocols
UEFI / Framework Special Topic
Slide 38

Driver Writers Guide

Platform Specific Topics

PCI Driver Guidelines

USB Driver Design Guidelines
SCSI Driver Design Guidelines
Size Optimizations
Speed Optimizations
Itanium Processor Family Considerations
EFI Byte Code Considerations
Building/Testing/Debugging UEFI Drivers
UEFI / Framework Special Topic
Slide 39

Driver Writers Guide

Benefits of following EFI

Driver Guidelines
Following EFI Driver Guidelines

Improves Portability, Quality, and Interoperability

Reduces Implementation Effort
May Increase Performance
May Reduce FLASH Overhead

EFI
EFI Driver
Driver Writers
WritersGuide
GuideHelps
Helps
Improve
ImproveEFI
EFI Drivers
Drivers
UEFI / Framework Special Topic
Slide 40

Summary

Good Designs Save Time and Money

Many Tools Available to Test and Debug
Using Driver Guidelines Improves Portability
Compile in EBC to have one driver image to
support x86, x64 and Itanium.

UEFI / Framework Special Topic

Slide 41