UEFI Drivers Intel Corporation Software and Solutions Group Copyright © 2006-2008 Intel...

UEFI DriversUEFI Drivers

Intel CorporationSoftware and Solutions Group

Copyright © 2006-2008 Intel Corporation

® UEFI / Framework Training 2008UEFI / Framework Training 2008UEFI / Framework Training 2008UEFI / Framework Training 2008 Slide 2Copyright © 2006-2008 Intel Corporation

•Other trademarks and brands are the property of their respective owners

Agenda

• Driver Introduction• UEFI Protocols• Driver Design Steps• Driver Writer Guidelines• Driver Writer’s Guide Publication



What do UEFI Drivers do?

• UEFI Drivers extend firmware– Add support for new hardware– No HW dependence– No OS dependence

• Portable across platforms – IA32, IA64, Intel-64, XScale

• Enables rapid development

UEFI Driver Intro



General Driver Execution (entry)

UEFI Loader Entry Point

Establish Protocols:Supported,

Start, Stop

Exit Driver

UEFI Driver Intro



General Driver Execution (Supported)

Supported

Return

Is Device supported Testing ID

True: Status = Supported

False: Status = Unsupported

ProtocolConsumer

UEFI Driver Intro



What is an UEFI Driver?

• An UEFI Loadable Image– Loaded by UEFI loader– May produce protocols– May consume protocols– Typically system driven

• Can be used for – Supporting specific hardware– Overriding an existing driver

UEFI Driver Intro



Driver vs. Application

Driver Application

Loaded by: EFI Loader EFI Loader

Interfaces available: ALL ALL

Consume protocols? YES YES

Produce protocols? YES NO

Typically driven by? System User

Typical use Support HW Any

UEFI Driver Intro



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 Driver Intro



Agenda




What is a protocol?

• An interface• Must be Produced by a driver• May be Consumed by anyone• A set of related functions and their associated

data

• Examples:– Device Path, PCI I/O, Disk I/O, GOP, UNDI



PCI IO Protocol - Example GUID

#define EFI_PCI_IO_PROTOCOL_GUID \{0x4cf5b200,0x68b8,0x4ca5,0x9e,0xec,0xb2,0x3e,0x3f,0x50,0x2,0x9a}Protocol Interface Structuretypedef struct _EFI_PCI_IO_PROTOCOL {

EFI_PCI_IO_PROTOCOL_POLL_IO_MEM PollMem;EFI_PCI_IO_PROTOCOL_POLL_IO_MEM PollIo;EFI_PCI_IO_PROTOCOL_ACCESS Mem;EFI_PCI_IO_PROTOCOL_ACCESS Io;EFI_PCI_IO_PROTOCOL_CONFIG_ACCESS Pci;EFI_PCI_IO_PROTOCOL_COPY_MEM CopyMem;EFI_PCI_IO_PROTOCOL_MAP Map;EFI_PCI_IO_PROTOCOL_UNMAP Unmap;EFI_PCI_IO_PROTOCOL_ALLOCATE_BUFFER AllocateBuffer;EFI_PCI_IO_PROTOCOL_FREE_BUFFER FreeBuffer;EFI_PCI_IO_PROTOCOL_FLUSH Flush;EFI_PCI_IO_PROTOCOL_GET_LOCATION GetLocation;EFI_PCI_IO_PROTOCOL_ATTRIBUTES Attributes;EFI_PCI_IO_PROTOCOL_GET_BAR_ATTRIBUTES GetBarAttributes;EFI_PCI_IO_PROTOCOL_SET_BAR_ATTRIBUTES SetBarAttributes;UINT64 RomSize;VOID *RomImage;

} EFI_PCI_IO_PROTOCOLSee § 13.4 UEFI 2.1 Spec.



Disk IO Protocol - Example

GUID#define EFI_DISK_IO_PROTOCOL_GUID \

{0xCE345171,0xBA0B,0x11d2,0x8e,0x4F,0x00,0xa0,0xc9,0x69,0x72,

0x3b}

Revision Number

#define EFI_DISK_IO_PROTOCOL_REVISION 0x00010000

Protocol Interface Structure

typedef struct _EFI_DISK_IO_PROTOCOL {

UINT64 Revision;

EFI_DISK_READ ReadDisk;

EFI_DISK_WRITE WriteDisk;

} EFI_DISK_IO_PROTOCOL; See § 12.6 UEFI 2.1 Spec.



Device Path Protocol - Example

GUID#define EFI_DEVICE_PATH_PROTOCOL_GUID \

{0x09576e91,0x6d3f,0x11d2,0x8e,0x39,0x00,0xa0,0xc9,0x69,0x72,

0x3b}

Protocol Interface Structuretypedef struct _EFI_DEVICE_PATH_PROTOCOL {

UINT8 Type;

UINT8 SubType;

UINT8 Length[2];

} EFI_DEVICE_PATH_PROTOCOL;

• The device path describes the location of the device the handle is for• A UEFI driver may access only a physical device for which it provides

functionality.

See § 9.2 UEFI 2.1 Spec.



UEFI boot services

UEFI application

Simple File System

ExtendedSCSI Passthrough

(PCI OpRom driver)

Protocol example Application Consumes I/O protocol

firmware Produces protocol(exposed through BS)

Firmware uses correct lower level protocolsConsumes Extended SCSI Passthrough protocol

SCSI card driver Produces Extended SCSI Passthrough protocol

SCSI card driver will talk directly to the SCSI drive

The Application has to

determine which top level handle to call

into

Disk I/O driver

Block I/O

SCSI I/O



Protocol vs. C++ class

• An UEFI protocol is logically similar to a C++ class– With lower memory overhead

• No virtual function table

– Has private member variables– Has exposed functions– Has private functions– Has a ‘This’ pointer

– Look/feel very different



Agenda




Driver Design Steps

1. Determine Driver Type2. Identify Consumed I/O Protocols3. Identify Produced I/O Protocols4. Identify UEFI Driver Model Protocols5. Identify Additional Driver Features6. Identify Target Platforms

– x86– x64– Itanium Processor Family– EFI Byte Code (EBC)

Design Steps



What Type of Driver is Being Designed?

UEFI Images

Applications

DriversService Drivers

OS Loaders

Initializing Drivers

Root Bridge Drivers

UEFI Driver Model

BusDrivers

Device Drivers

Device Drivers

Bus Drivers

Hybrid Drivers

Design Steps



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 Device’s Controller HandleExamples:Examples:

PCI Video AdaptersPCI Video AdaptersUSB Host ControllersUSB Host ControllersUSB Keyboards / USB MiceUSB Keyboards / USB MicePS/2 Keyboards / PS/2 MicePS/2 Keyboards / PS/2 Mice



Root Bridge Drivers

UEFI Driver Model

Device Drivers

Bus Drivers

Hybrid Drivers

Design Steps



Bus Drivers

• Manages and Enumerates a Bus Controller• Start() Creates One or More Child Handles• Start() Produces Bus Specific I/O Protocols

– Installed onto the Bus’s Child Handles

Examples:Examples:PCI Network Interface ControllersPCI Network Interface ControllersSerial UART ControllersSerial UART Controllers



Root Bridge Drivers

UEFI Driver Model

Device Drivers

Bus Drivers

Hybrid Drivers

Design Steps



Hybrid Drivers

• Manages and Enumerates a Bus Controller• Start() Creates One or More Child Handles• Start() Produces Bus Specific I/O Protocols

– Installed onto the Bus’s Controller Handle– Installed onto Bus’s Child Handles

Examples:Examples:PCI SCSI Host ControllersPCI SCSI Host ControllersPCI Fiber Channel ControllersPCI Fiber Channel Controllers



Root Bridge Drivers

UEFI Driver Model

Device Drivers

Bus Drivers

Hybrid Drivers

Design Steps



Service 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 HandlesExamples:Examples:

UEFI Decompress ProtocolUEFI Decompress ProtocolUEFI Byte Code Virtual MachineUEFI Byte Code Virtual MachineBoot Integrity Services (BIS)Boot Integrity Services (BIS)



Root Bridge Drivers

UEFI Driver Model

Device Drivers

Bus Drivers

Hybrid Drivers

Design Steps




• Typically Touches Hardware• Performs One Time Initialization Operations• Does Not Create Any Handles• Does Not Produce Any Protocols• Unloaded When Finished

Examples: NoneExamples: None



Root Bridge Drivers

UEFI Driver Model

Device Drivers

Bus Drivers

Hybrid Drivers

Design Steps



Root Bridge 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 Bridge Handles

Examples: PCI Host BridgeExamples: PCI Host Bridge



Root Bridge Drivers

UEFI Driver Model

Device Drivers

Bus Drivers

Hybrid Drivers

Design Steps



What I/O Protocols are Consumed?

• PCI Adapters– PCI I/O Protocol– Device Path Protocol

• USB Peripherals– USB I/O Protocol– Device Path Protocol

FLASH

Design Steps



What I/O Protocols are Produced?

SCSISCSI RAIDFiber Channel

• SCSI Pass Thru Protocol

and• Block I/O Protocol

FLASH

Design Steps



What I/O Protocols are Produced?

Network Interface Controller (NIC)

• Universal Network Driver Interface (UNDI)

and• Network Interface Identifier Protocol (NII)

FLASH

Design Steps



Driver Image HandleEFI_LOADED_IMAGE_PROTOCOL

Responsibilities of Driver Writer

EFI_DRIVER_BINDING_PROTOCOLSupported()Start()Stop()Version

• Driver Image Handle Required Protocols

Installed by the core

Installed by the driver

Unload()Published by the driver

EFI_LOADED_IMAGE_PROTOCOL

See § 2.5.2 UEFI 2.1 Spec.

Design Steps



MoreResponsibilities of Driver Writer

Driver Image Handle

EFI_PLATFORM_TO_DRIVER_CONFIGURATION_PROTOCOL

Query()Response()

EFI_DRIVER_DIAGNOSTICS_PROTOCOLRunDiagnostics()SupportedLanguages

• Driver Image Handle Optional Protocols

EFI_COMPONENT_NAME_PROTOCOLGetDriverName()GetControllerName()SupportedLanguages

Design Steps



Driver Design Checklist

Driver Type

I/O Protocols Consumed

I/O Protocols Produced

Driver Binding

Component Name

Driver Configuration

Driver Diagnostics

Unloadable

Exit Boot Services Event

Runtime

Set Virtual Address Map EventSet Virtual Address Map Event

GOP SCSI Pass Thru

Block I/O

PCI I/OPCI I/O

Device Path

BusBusDevice Hybrid

PCI

NIC

PCI

Video

PCI

RAID

PCI I/ODevice Path

PCI I/ODevice Path

UNDI, NIIUNDI, NII

Design Steps



• 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()

Running UEFI driversDesign Steps



Agenda




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

Driver Guidelines



Driver Guidelines

• Don’t 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

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

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 EnableSave Original and Enable

Driver Guidelines



PCI Device Drivers – Stop()

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

Restore OriginalRestore Original

Driver Guidelines



Preventing Alignment Faults

VOIDScsiDeviceNodeInit ( 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 alignedScsiDeviceNode may not be aligned

Driver Guidelines



Preventing Alignment Faults

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

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));}

GOOD

gBS->CopyMem() handles all alignmentsgBS->CopyMem() handles all alignmentsMyDeviceNode is alignedMyDeviceNode is aligned

Driver Guidelines



Use UEFI Driver Library Functions

CHILD_DEVICE Child;

Child = EfiLibAllocateZeroPool (sizeof (CHILD_DEVICE));if (Child == NULL) { return EFI_OUT_OF_RESOURCES;}

Library Functions Simplify Source CodeLibrary Functions Simplify Source CodeLibrary Functions May Reduce SizeLibrary Functions May Reduce Size

CHILD_DEVICE Child;

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

OK

GOOD

Driver Guidelines



UEFI Device Paths

• EFI_DRIVER_BINDING.Start()

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

gBS->FreePool (Child->DevicePath);

• EFI_DRIVER_BINDING.Stop()

Parent Device Path is OpaqueParent Device Path is OpaqueNot Parsed by Bus DriversNot Parsed by Bus Drivers

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

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

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%

Driver Guidelines



How To Improve Portability

1. Do Not Assume Max Number of Children

2. Do Not Use Fixed Memory Addresses

3. Do Not Use Assembly

4. Do Not Use Floating Point Arithmetic

5. Some Minor EBC Porting Considerations

6. Bus Drivers Should Support Producing 1 Child at a time if possible (improves boot performance)

Driver Guidelines Improve PortabilityDriver Guidelines Improve PortabilityDriver Guidelines Improve PortabilityDriver Guidelines Improve Portability

Driver Guidelines



Agenda




UEFI Driver Writer’s 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

Driver Writer’s Guide for UEFI 2.0

Draft for Review

April 28, 2008Revision 0.96

Driver Writer’s Guide for UEFI 2.0

Draft for Review

April 28, 2008Revision 0.96

Driver Writer’s 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




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




Benefits of following EFIDriver Guidelines

• Following EFI Driver Guidelines– Improves Portability, Quality, and Interoperability– Reduces Implementation Effort– May Increase Performance– May Reduce FLASH Overhead

UEFI Driver Writer’s Guide Helps UEFI Driver Writer’s Guide Helps Improve EFI DriversImprove EFI Drivers

UEFI Driver Writer’s Guide Helps UEFI Driver Writer’s Guide Helps Improve EFI DriversImprove EFI Drivers




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.



Further Information

• http://www.intel.com/technology/EFI– EFI Web site for information, IDF presentations

and EFI Driver Writer’s Guide

• http://www.uefi.org– Website for Unified EFI Forum, UEFI

Specifications

• https://www.TianoCore.org– Website for UEFI open source resources

• EFI Developer Kit (EDK) and (EDK II)• UEFI Driver Writer’s Guide 2.0



Q & A



Back up• Required Materials for IHVs• Optional Materials for OEMs

See Backup Presentation “UEFI-Drivers-Backup Only”



Network UEFI 2.1



Protocol Diagram

Red (solid) lines are new network protocol APIs that can be accessed by multiple applications and drivers at the same time.

Green (broken) lines are existing network protocol APIs that can only be accessed by one application or driver at a time.

PXEBC

UDP TCP

IP (ICMP, IGMP, ARP)

SNP

UNDI

TFTP DHCP

Network



Internet Protocol (IP)

• One IP instance per SNP instance.• Can be used by multiple applications and

drivers at the same time.• Implements a subset of IP (RFC 791).

– No support for IP options in alpha code.– Minimal support for ICMP

• ping works• errors can be routed up to applications and drivers

– Just enough to make UDP and TCP layers work

Network



User Datagram Protocol (UDP)

• One UDP instance per IP instance.• Can be used by multiple applications and drivers

at the same time.• Implements all of UDP (RFC 768).

Network



Transmission Control Protocol (TCP)

• One TCP instance per IP instance.• Can be used by multiple applications and drivers at the

same time.• Implements a subset of TCP (RFC 793).

– No application control of window or segment sizes.– Minimal data returned for socket status.– Just enough to make implementing a Berkeley Socket interface

possible.

Network



Multicast Trivial File Transfer Protocol (Mtftp)

• One MTFTP instance per UDP/IP instance.• Can be used by multiple applications and drivers

at the same time.• Implements all of TFTP (RFC 1350) + Options

(RFCs 2347, 2348, 2349) + Internet-Drafts covering BIG extensions.

Network



Dynamic Host Configuration Protocol (DHCP)

• One DHCP instance per UDP/IP instance.• Can be used by multiple applications and drivers at the

same time.• Only provides network configuration information.

– Does not manage network connections.– If DHCP data changes, application must update network

connection accordingly.

• Implements all of DHCP (RFC 2131 and 2132)

Network



SNP

UNDI

ARP Service Binding

IPv4 Service Binding

UDPv4 Service Binding

MNP Service Binding

MTFTPv4 Service Binding

TCPv4 Service Binding

DHCPv4 Service Binding

iSCSI

UEFI PXE Base Code

Primarily External Interfaces

Primarily Internal Interfaces

PXEBC

SNP

UNDI

TCP/IPStack

APP APP

Current Network Stack Layout

APPAPP

Notice the concurrentusage in new solution set. SNP is used exclusively by MNP, and MNP acts as a multiplex for incoming use of the SNP.

UEFI Drivers Intel Corporation Software and Solutions Group Copyright © 2006-2008 Intel...

Documents

Transcript of UEFI Drivers Intel Corporation Software and Solutions Group Copyright © 2006-2008 Intel...