1. UEFI / Framework Special Topic Slide 1 UEFI Drivers UEFI / Framework Special Topic Copyright © 2007 Intel Corporation

2. UEFI / 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 means more scenarios “just work” Use of multilayer modularity means more scenarios “just work”

3. 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 Drivers

4. UEFI / 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

5. UEFI / Framework Special Topic Slide 5 Driver Design Steps 1.Determine Driver Type 2.Identify Consumed I/O Protocols 3.Identify Produced I/O Protocols 4.Identify UEFI Driver Model Protocols 5.Identify Additional Driver Features 6.Identify Target Platforms –x86 –x64 –Itanium Processor Family –EFI Byte Code (EBC) UEFI Drivers

6. UEFI / Framework Special Topic Slide 6 Complex System Example Manageable by UEFI Driver Model CPU NorthBridge CPU PCI-IBABridge USB VGA PCI-ISABridge IBA-PCIBridge KBD Mouse RemovableMedia(floppy) SCSI HardDrive HardDrive HardDrive HardDrive PCI BUS IBA BUS PCI BUS USB BUS ISA BUS UEFI Drivers See § 2.5 UEFI 2.1 Spec.

7. UEFI / Framework Special Topic Slide 7 What Type of Driver is Being Designed? UEFI Images Applications Drivers Service Drivers OS Loaders Initializing Drivers Root Bridge Drivers UEFI Driver Model Bus Drivers Device Drivers UEFI Drivers Device Drivers Bus Drivers Hybrid Drivers

8. UEFI / 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

9. UEFI / 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 Handle Examples: PCI Video Adapters USB Host Controllers USB Keyboards / USB Mice PS/2 Keyboards / PS/2 Mice UEFI Drivers Drivers Service Drivers Initializing Drivers Root Bridge Drivers UEFI Driver Model Device Drivers Bus Drivers Hybrid Drivers

10. UEFI / 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 Handle EFI_DEVICE_PATH_PROTOCOL EFI_XYZ_I/O_PROTOCOL Bus Driver EFI_BUS_SPECIFIC_DRIVER_ OVERRIDE_PROTOCO Optional

11. UEFI / 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 Handles Examples: PCI Network Interface Controllers Serial UART Controllers Drivers Service Drivers Initializing Drivers Root Bridge Drivers UEFI Driver Model Device Drivers Bus Drivers Hybrid Drivers UEFI Drivers

12. UEFI / 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: PCI SCSI Host Controllers PCI Fiber Channel Controllers Drivers Service Drivers Initializing Drivers Root Bridge Drivers UEFI Driver Model Device Drivers Bus Drivers Hybrid Drivers UEFI Drivers

13. UEFI / 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 Handles Examples: UEFI Decompress Protocol UEFI Byte Code Virtual Machine Boot Integrity Services (BIS) Drivers Service Drivers Initializing Drivers Root Bridge Drivers UEFI Driver Model Device Drivers Bus Drivers Hybrid Drivers UEFI Drivers

14. UEFI / 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 Initialization Implemented by Driver Writer Created by LoadImage() Driver Image Handle EFI_LOADED_IMAGE EFI_DRIVER_BINDING Registers Driver for Later Use

15. UEFI / 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: None Drivers Service Drivers Initializing Drivers Root Bridge Drivers UEFI Driver Model Device Drivers Bus Drivers Hybrid Drivers UEFI Drivers

16. UEFI / 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 Bridge Drivers Service Drivers Initializing Drivers Root Bridge Drivers UEFI Driver Model Device Drivers Bus Drivers Hybrid Drivers UEFI Drivers

17. UEFI / 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

18. UEFI / Framework Special Topic Slide 18 What I/O Protocols are Produced? SCSI SCSI RAID Fiber Channel SCSI Pass Thru Protocol and Block I/O Protocol FLASH UEFI Drivers

19. UEFI / 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

20. UEFI / Framework Special Topic Slide 20 Driver Image Handle EFI_LOADED_IMAGE_PROTOCOL Responsibilities of Driver Writer EFI_DRIVER_BINDING_PROTOCOL Supported() Start() Stop() Version Driver Image Handle Required Protocols Installed by the core Installed by the driver Unload() Publishe d by the driver UEFI Drivers EFI_LOADED_IMAGE_PROTOCOL See § 2.5.2 UEFI 2.1 Spec.

21. UEFI / Framework Special Topic Slide 21 More Responsibilities of Driver Writer Driver Image Handle EFI_DRIVER_CONFIGURATION_PROTOCOL SetOptions() OptionValid() ForceDefaults() SupportedLanguages EFI_DRIVER_DIAGNOSTICS_PROTOCOL RunDiagnostics() SupportedLanguages Driver Image Handle Optional Protocols EFI_COMPONENT_NAME_PROTOCOL GetDriverName() GetControllerName() SupportedLanguages UEFI Drivers

22. UEFI / 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 Draw UGA I/O SCSI Pass Thru Block I/O PCI I/O Device Path Bus DeviceHybrid PCI NIC PCI Video PCI RAID PCI I/O Device Path PCI I/O Device Path UNDI, NII UEFI Drivers

23. UEFI / 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 drivers UEFI Drivers

24. UEFI / 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

25. UEFI / 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

26. UEFI / 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

27. UEFI / 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 Enable Driver Guidelines

28. UEFI / Framework Special Topic Slide 28 PCI Device Drivers – Stop() Status = PciIo->Attributes( PciIo, EfiPciIoAttributeOperationSet, &ControllerContext->OriginalPciIoAttributes NULL ); if (EFI_ERROR (Status)) { // Error Handling } Restore Original Driver Guidelines

29. UEFI / Framework Special Topic Slide 29 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 Driver Guidelines

30. UEFI / Framework Special Topic Slide 30 Preventing Alignment Faults VOID ScsiDeviceNodeInit ( 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 alignments MyDeviceNode is aligned Driver Guidelines

31. UEFI / 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 Code Library 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

32. UEFI / 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 Opaque Not Parsed by Bus Drivers Driver Guidelines

33. UEFI / 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

34. UEFI / 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

35. UEFI / 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

36. UEFI / Framework Special Topic Slide 36 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 Portability Driver Guidelines

37. UEFI / 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.10 Driver Writer’s Guide Draft for Review Version 0.9 July 20, 2004 EFI 1.10 Driver Writer’s Guide Draft for Review Version 0.9 July 20, 2004 Driver Writer’s Guide

38. UEFI / 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

39. UEFI / 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

40. UEFI / Framework Special Topic Slide 40 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 Driver Writer’s Guide

41. UEFI / 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.