UEFI Drivers UEFI Framework Special Topic Copyright 2007

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 of multilayer modularity means UEFI scenarios / Framework Special more “just work”Topic Slide 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 – – x 86 x 64 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 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 Bus Hybrid Device 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 Service Drivers UEFI Driver Model Initializing Drivers Root Bridge Drivers Bus Drivers Hybrid 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 Device’s 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 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 Bus’s Child Handles Examples: PCI Network Interface Controllers Serial UART Controllers UEFI / Framework Special Topic Slide 11

UEFI 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 Bus’s Controller Handle – Installed onto Bus’s Child Handles Examples: PCI SCSI Host Controllers PCI Fiber Channel Controllers UEFI / Framework Special Topic Slide 12

UEFI 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 Load. Image() Installed in Driver Initialization Implemented by Driver Writer Driver Image Handle EFI_LOADED_IMAGE EFI_DRIVER_BINDING Registers Driver for Later Use UEFI / Framework Special Topic Slide 14

UEFI 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 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 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 Publishe d by the driver Installed by the core EFI_LOADED_IMAGE_PROTOCOL Unload() EFI_LOADED_IMAGE_PROTOCOL Installed by the driver EFI_DRIVER_BINDING_PROTOCOL Supported() Start() Stop() Version 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 Set. Options() Option. Valid() Force. Defaults() Supported. Languages EFI_DRIVER_DIAGNOSTICS_PROTOCOL Run. Diagnostics() Supported. Languages EFI_COMPONENT_NAME_PROTOCOL Get. Driver. Name() Get. Controller. Name() Supported. Languages UEFI / Framework Special Topic Slide 21

UEFI Drivers Driver Design Checklist Driver Type PCI Video Device I/O Protocols Consumed PCI I/O Protocols Produced Driver Binding Component Name Driver Configuration Driver Diagnostics Unloadable Exit Boot Services Event Runtime Set Virtual Address Map Event PCI RAID Hybrid PCI I/O PCI NIC Bus PCI I/O Device Path UGA Draw UGA I/O SCSI Pass Thru Block I/O UNDI, NII ü ü ü ü UEFI / Framework Special Topic Slide 22

UEFI Drivers Running UEFI drivers • Connect. Controller() – 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 • Disconnect. Controller() – 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 – x 86, x 64, Itanium Processor Family, EBC UEFI / Framework Special Topic Slide 24

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 – – Install. Protocol. Interface() Open. Protocol() Allocate. Pages() Allocate. Pool() Uninstall. Protocol. Interface() Close. Protocol Free. Pages() Free. Pool() • Driver Entry / Unload() mirror each other UEFI / Framework Special Topic Slide 25

Driver Guidelines PCI Device Drivers • Always Call Pci. Io->Attributes() – Advertises Dual Address Cycle Capability – Save and Enable Attributes in Start() – Disable Attributes in Stop() • DMA – Bus Master Write Operations – Must call Pci. Io->Flush() • DMA – Setting Up with Pci. Io->Map() – Do Not Use Returned Device. Address – Not all chipsets have 1: 1 bus/system mappings UEFI / Framework Special Topic Slide 26

Driver Guidelines PCI Device Drivers – Start() Status = Pci. Io->Attributes( Pci. Io, Efi. Pci. Io. Attribute. Operation. Get, 0, &Controller. Context->Original. Pci. Io. Attributes ); if (EFI_ERROR (Status)) { // Error Handling } Status = Pci. Io->Attributes( Pci. Io, Efi. Pci. Io. Attribute. Operation. Enable, (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 = Pci. Io->Attributes( Pci. Io, Efi. Pci. Io. Attribute. Operation. Set, &Controller. Context->Original. Pci. Io. Attributes NULL ); if (EFI_ERROR (Status)) { // Error Handling } Restore Original UEFI / Framework Special Topic Slide 28

Driver Guidelines Preventing Alignment Faults VOID Scsi. Device. Node. Init ( IN OUT SCSI_DEVICE_PATH *Scsi. Device. Node, IN UINT 16 Pun, IN UINT 16 Lun ) { Scsi. Device. Node->Scsi. Header. Type = MESSAGING_DEVICE_PATH; Scsi. Device. Node->Scsi. Header. Sub. Type = MSG_SCSI_DP; Set. Device. Path. Node. Length (&Scsi. Device. Node->Scsi. Header, sizeof(SCSI_DEVICE_PATH)); Scsi. Device. Node->Scsi. Pun = Pun; Scsi. Device. Node->Scsi. Lun = Lun; } BAD Scsi. Device. Node may not be aligned UEFI / Framework Special Topic Slide 29

Driver Guidelines Preventing Alignment Faults VOID Scsi. Device. Node. Init ( IN OUT SCSI_DEVICE_PATH *Scsi. Device. Node, IN UINT 16 Pun, IN UINT 16 Lun ) { SCSI_DEVICE_PATH My. Device. Node; GOOD My. Device. Node. Scsi. Header. Type = MESSAGING_DEVICE_PATH; My. Device. Node. Scsi. Header. Sub. Type = MSG_SCSI_DP; Set. Device. Path. Node. Length (&My. Device. Node. Scsi. Header, sizeof(SCSI_DEVICE_PATH)); My. Device. Node. Scsi. Pun = Pun; My. Device. Node. Scsi. Lun = Lun; g. BS->Copy. Mem (Scsi. Device. Node, &My. Device. Node, sizeof(SCSI_DEVICE_PATH)); } g. BS->Copy. Mem() handles all alignments My. Device. Node is aligned UEFI / Framework Special Topic Slide 30

Driver Guidelines Use UEFI Driver Library Functions CHILD_DEVICE Child; OK Status = g. BS->Allocate. Pool ( Efi. Boot. Services. Data, sizeof (CHILD_DEVICE), &Child ); if (EFI_ERROR (Status)) { return Status; } g. BS->Set. Mem (Child, sizeof (CHILD_DEVICE), 0); CHILD_DEVICE Child; GOOD Child = Efi. Lib. Allocate. Zero. Pool (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->Device. Path = Efi. Append. Device. Path. Node ( Controller. Device. Path, Child. Device. Path. Node ); if (Child->Device. Path == NULL) { return(EFI_OUT_OF_RESOURCES); } • EFI_DRIVER_BINDING. Stop() g. BS->Free. Pool (Child->Device. Path); Parent Device Path is Opaque Not Parsed by Bus Drivers UEFI / Framework Special Topic Slide 32

Driver Guidelines Bus Walk Tips • Use Locate. Handle. Buffer(Bus I/O Protocol) – Do not scan PCI configuration space • Implement support for Remaining. Device. Path – 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 x 86, x 64 and Itanium Smaller than Itanium Binaries Comparable to x 86 Binaries Compresses Well ~ 50% UEFI / Framework Special Topic Slide 35

Driver Guidelines How To Improve Portability 1. 2. 3. 4. 5. 6. 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 Guidelines Improve Portability UEFI / Framework Special Topic Slide 36

Driver Writer’s Guide 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 EFI 1. 10 Driver Writer’s Guide Draft for Review Version 0. 9 July 20, 2004 UEFI / Framework Special Topic Slide 37

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 UEFI / Framework Special Topic Slide 38

Driver Writer’s 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 Writer’s 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 Driver Writer’s Guide Helps Improve EFI 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 x 86, x 64 and Itanium. UEFI / Framework Special Topic Slide 41