uefi / framework special topic slide 1 uefi drivers uefi / framework special topic copyright © 2007...
DESCRIPTION
UEFI / Framework Special Topic Slide 3 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 DriversTRANSCRIPT
UEFI / Framework Special TopicUEFI / Framework Special Topic Slide 1
UEFI Drivers
UEFI / Framework Special Topic
Copyright © 2007 Intel Corporation
UEFI / Framework Special TopicUEFI / Framework Special Topic Slide 2
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 meansUse of multilayer modularity meansmore scenarios “just work”more scenarios “just work”
UEFI / Framework Special TopicUEFI / Framework Special Topic Slide 3
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 Drivers
UEFI / Framework Special TopicUEFI / Framework Special Topic Slide 4
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 TopicUEFI / Framework Special Topic Slide 5
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)
UEFI Drivers
UEFI / Framework Special TopicUEFI / Framework Special Topic Slide 6
Complex System Example
• Manageable by UEFI Driver Model
CPUCPU
NorthNorthBridgeBridge
CPUCPU
PCI-IBAPCI-IBABridgeBridge
USBUSB
VGAVGA
PCI-ISAPCI-ISABridgeBridge
IBA-PCIIBA-PCIBridgeBridge
KBDKBD
MouseMouse
RemovableRemovableMediaMedia
(floppy)(floppy)
SCSISCSI
Hard Hard DriveDrive
Hard Hard DriveDrive
Hard Hard DriveDrive
Hard Hard DriveDrive
PCI BUSPCI BUS
IBA BUSIBA BUSPCI BUSPCI BUS
USB BUSUSB BUS
ISA BUSISA BUS
UEFI Drivers
See § 2.5 UEFI 2.1 Spec.
UEFI / Framework Special TopicUEFI / Framework Special Topic Slide 7
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
UEFI Drivers
Device DriversBus
DriversHybrid Drivers
UEFI / Framework Special TopicUEFI / Framework Special Topic Slide 8
• 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
Device Driver
UEFI / Framework Special TopicUEFI / Framework Special Topic Slide 9
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
UEFI DriversDrivers
Service Drivers
Initializing Drivers
Root Bridge Drivers
UEFI Driver Model
Device Drivers
Bus Drivers
Hybrid Drivers
UEFI / Framework Special TopicUEFI / Framework Special Topic Slide 10
• 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 HandleEFI_DEVICE_PATH_PROTOCOL
EFI_XYZ_I/O_PROTOCOL
Bus Driver
EFI_BUS_SPECIFIC_DRIVER_OVERRIDE_PROTOCO
Optional
UEFI / Framework Special TopicUEFI / Framework Special Topic Slide 11
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 HandlesExamples:Examples:
PCI Network Interface ControllersPCI Network Interface ControllersSerial UART ControllersSerial UART Controllers
DriversService Drivers
Initializing Drivers
Root Bridge Drivers
UEFI Driver Model
Device Drivers
Bus Drivers
Hybrid Drivers
UEFI Drivers
UEFI / Framework Special TopicUEFI / Framework Special Topic Slide 12
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
DriversService Drivers
Initializing Drivers
Root Bridge Drivers
UEFI Driver Model
Device Drivers
Bus Drivers
Hybrid Drivers
UEFI Drivers
UEFI / Framework Special TopicUEFI / Framework Special Topic Slide 13
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)
DriversService Drivers
Initializing Drivers
Root Bridge Drivers
UEFI Driver Model
Device Drivers
Bus Drivers
Hybrid Drivers
UEFI Drivers
UEFI / Framework Special TopicUEFI / Framework Special Topic Slide 14
Driver Initialization
• EFI Driver Handoff State• Not Allowed to Touch Hardware Resources• Installs Driver Binding on Driver Image Handle
Installed by LoadImage()
Installed in Driver InitializationImplemented by Driver Writer
Created by LoadImage() Driver Image HandleEFI_LOADED_IMAGE
EFI_DRIVER_BINDING
Registers Driver for Later UseRegisters Driver for Later Use
UEFI / Framework Special TopicUEFI / Framework Special Topic Slide 15
Initializing Drivers
• Typically Touches Hardware• Performs One Time Initialization Operations• Does Not Create Any Handles• Does Not Produce Any Protocols• Unloaded When Finished
Examples: NoneExamples: None
DriversService Drivers
Initializing Drivers
Root Bridge Drivers
UEFI Driver Model
Device Drivers
Bus Drivers
Hybrid Drivers
UEFI Drivers
UEFI / Framework Special TopicUEFI / Framework Special Topic Slide 16
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 a Bridge Handles
Examples: PCI Host BridgeExamples: PCI Host Bridge
DriversService Drivers
Initializing Drivers
Root Bridge Drivers
UEFI Driver Model
Device Drivers
Bus Drivers
Hybrid Drivers
UEFI Drivers
UEFI / Framework Special TopicUEFI / Framework Special Topic Slide 17
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
UEFI Drivers
UEFI / Framework Special TopicUEFI / Framework Special Topic Slide 18
What I/O Protocols are Produced?
SCSISCSI RAIDFiber Channel
• SCSI Pass Thru Protocoland
• Block I/O Protocol
FLASH
UEFI Drivers
UEFI / Framework Special TopicUEFI / Framework Special Topic Slide 19
What I/O Protocols are Produced?
Network Interface Controller (NIC)
• Universal Network Driver Interface (UNDI)and
• Network Interface Identifier Protocol (NII)
FLASH
UEFI Drivers
UEFI / Framework Special TopicUEFI / Framework Special Topic Slide 20
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
UEFI Drivers
EFI_LOADED_IMAGE_PROTOCOL
See § 2.5.2 UEFI 2.1 Spec.
UEFI / Framework Special TopicUEFI / Framework Special Topic Slide 21
MoreResponsibilities of Driver Writer
Driver Image HandleEFI_DRIVER_CONFIGURATION_PROTOCOL
SetOptions()OptionValid()ForceDefaults()SupportedLanguages
EFI_DRIVER_DIAGNOSTICS_PROTOCOLRunDiagnostics()SupportedLanguages
• Driver Image Handle Optional Protocols
EFI_COMPONENT_NAME_PROTOCOLGetDriverName()GetControllerName()SupportedLanguages
UEFI Drivers
UEFI / Framework Special TopicUEFI / Framework Special Topic Slide 22
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 Event
UGA DrawUGA I/O
SCSI Pass ThruBlock I/O
PCI I/O PCI I/ODevice Path
BusDevice Hybrid
PCINIC
PCI Video
PCIRAID
PCI I/ODevice Path
UNDI, NII
UEFI Drivers
UEFI / Framework Special TopicUEFI / Framework Special Topic Slide 23
• 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 driversUEFI Drivers
UEFI / Framework Special TopicUEFI / Framework Special Topic Slide 24
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 Drivers
UEFI / Framework Special TopicUEFI / Framework Special Topic Slide 25
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
UEFI / Framework Special TopicUEFI / Framework Special Topic Slide 26
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
UEFI / Framework Special TopicUEFI / Framework Special Topic Slide 27
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
UEFI / Framework Special TopicUEFI / Framework Special Topic Slide 28
PCI Device Drivers – Stop()Status = PciIo->Attributes( PciIo, EfiPciIoAttributeOperationSet, &ControllerContext->OriginalPciIoAttributes NULL );if (EFI_ERROR (Status)) { // Error Handling}
Restore OriginalRestore Original
Driver Guidelines
UEFI / Framework Special TopicUEFI / Framework Special Topic Slide 29
Preventing Alignment FaultsVOIDScsiDeviceNodeInit ( 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
UEFI / Framework Special TopicUEFI / Framework Special Topic Slide 30
Preventing Alignment FaultsVOIDScsiDeviceNodeInit ( 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
UEFI / Framework Special TopicUEFI / Framework Special Topic Slide 31
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 / Framework Special TopicUEFI / Framework Special Topic Slide 32
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
UEFI / Framework Special TopicUEFI / Framework Special Topic Slide 33
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
UEFI / Framework Special TopicUEFI / Framework Special Topic Slide 34
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
UEFI / Framework Special TopicUEFI / Framework Special Topic Slide 35
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
UEFI / Framework Special TopicUEFI / Framework Special Topic Slide 36
How To Improve Portability
1. Do Not Assume Max Number of Children2. Do Not Use Fixed Memory Addresses3. Do Not Use Assembly4. Do Not Use Floating Point Arithmetic5. Some Minor EBC Porting Considerations6. Bus Drivers Should Support Producing 1
Child at a time if possible (improves boot performance)
Driver Guidelines Improve PortabilityDriver Guidelines Improve Portability
Driver Guidelines
UEFI / Framework Special TopicUEFI / Framework Special Topic Slide 37
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.10Driver Writer’s Guide
Draft for Review
Version 0.9July 20, 2004
Driver Writer’s Guide
UEFI / Framework Special TopicUEFI / Framework Special Topic Slide 38
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
Driver Writer’s Guide
UEFI / Framework Special TopicUEFI / Framework Special Topic Slide 39
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
Driver Writer’s Guide
UEFI / Framework Special TopicUEFI / Framework Special Topic Slide 40
Benefits of following EFIDriver 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 EFI Driver Writer’s Guide Helps Improve EFI DriversImprove EFI Drivers
Driver Writer’s Guide
UEFI / Framework Special TopicUEFI / Framework Special Topic Slide 41
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.