Kernel Plug And Play In Windows Vista

1. Kernel Plug And Play In Windows Vista Allen MarshallLead Program ManagerWindows Core Platform ArchitectureMicrosoft Corporation

2. Agenda • Enhanced scenario support • Device custom properties • Device ejection support • Asynchronous PnP operations • Kernel PnP diagnostic tracing • Supporting hardware evolution • Legacy reduction • Interrupt enhancements • Large system support • Multilevel rebalance • Machine.inf logistics • Common BIOS errata that impact PnP

3. Background • Windows Vista features continued advancement of Windows kernel PnP support, driven by • Evolving hardware technologies • PCI Express • NUMA relations in many systems • Mainstream adoption of advanced server configurations • Hot add memory • Continued development to enhance existing and enable new scenarios • Enabling faster system startup • Improved diagnostics, manageability

4. Enhanced Scenario SupportDevice properties in Windows • Today, Windows provides the kernel DDI IoOpenDeviceRegistryKey() • Returns a device or driver registry key • Drivers can access registry data using standard registry DDIs • Setup information • Name of the device’s PDO • Use of a DDI is preferred to accessing the registry directly • Allows better abstraction in the operating system • Backing store location may change in the future • Windows Vista will extend this to allow custom device properties to be both set and retrieved for a device node

5. Enhanced Scenario SupportCustom property DDIs in Windows Vista • This offers several practical applications • The device’s bus driver can set these custom device properties on the device’s devnode • The device may store useful information in its firmware, and make this available to the OS • Icon image • Device description string • Manufacturer’s web site URL • Device driver • Kernel-mode • IoSetDevicePropertyData() • IoGetDevicePropertyData() • User-mode • SetupDi…()

6. Enhanced Scenario SupportDevice custom property DDIs • Function prototypes are declared in wdm.h • Bus drivers should not call these DDIs until they have received a IRP_MN_QUERY_RESOURCE_REQUIREMENTS IRP • This will ensure that PnP has created and initialized the device node associated with the PDO • Calling too early results in bug check 0xCA PNP_DETECTED_FATAL_ERROR • Callers must be running at IRQL == PASSIVE_LEVEL • Locale-neutral property replace any existing locale-specific properties • If you have a locale specific property, be sure to set this property for all relevant locales

7. Enhanced Scenario SupportDevice custom property DDIs • Pdo – pointer to the physical device object • PropertyKey – pointer to the property key identifying the property • Lcid – language identifier • Flags • PLUGPLAY_PROPERTY_PERSISTENT – Property should be persisted across boots • Type – custom property type • Size – custom property data size • Data – pointer to the custom property data NTSTATUS IoSetDevicePropertyData ( __in PDEVICE_OBJECT Pdo, __in CONST DEVPROPKEY *PropertyKey, __in_LCID Lcid, __in ULONG Flags, __in DEVPROPTYPE Type, __in ULONG Size, __in_opt PVOID Data )

8. Enhanced Scenario SupportDevice custom property DDIs • Deleting custom device data • If Data is NULL, the specified property will be deleted • If Data is NULL and LCID is specified, then the property data for the specified LCID will be deleted • If Data is NULL and LCID is LOCALE_NEUTRAL, then property data for all languages will be deleted

9. Enhanced Scenario SupportDevice custom property DDIs • Pdo – pointer to the physical device object • PropertyKey – pointer to the property key identifying the property • Lcid – language identifier • Flags – reserved • Size – custom property data size • Data – pointer to the custom property data • RequiredSize – pointer that receives the required size for getting the data • Type – pointer that receives the custom property data type IoGetDevicePropertyData ( __in PDEVICE_OBJECT Pdo, __in CONST DEVPROPKEY *PropertyKey, __in LCID Lcid, __reserved ULONG Flags, __in ULONG Size, __out PVOID Data, __out PULONG RequiredSize, __out PDEVPROPTYPE Type )

10. Enhanced Scenario SupportDevice custom property DDIs • The PCI driver in Windows Vista will expose certain properties for a PCI root bus and PCI bridges and devices using these DDIs • These properties are available to other kernel mode and user mode components once the root bus or a PCI device is started • Not shown in Windows Vista UI • Function drivers can retrieve custom properties for PCI devices once the PDO completes the Start IRP • If a property is not applicable to a PCI device, then it will not be set and cannot be retrieved • These properties are volatile and are automatically refreshed across reboots or change of device location • These are read-only properties, and may not be modified • Any modification to these properties from user or kernel mode will not change the operational behavior of a root bus or a device

11. Enhanced Scenario SupportDevice custom property DDIs • Examples • PCI root bus • Secondary side characteristics • Secondary side speed and mode • Available when the platform defines _DSM method function 4 for the PCI host bridge • PCI device • Device current speed and mode • Applicable for PCI Conventional and PCI-X devices • Device BaseClass, SubClass

12. Enhanced Scenario SupportDevice ejection DDIs • Windows today provides the IoDeviceEjectRequest() DDI • Typically called by a bus driver to notify the PnP manager that a hardware device eject button for one of the bus driver’s child devices has been pressed • Callers of this API have no elegant way to know if the device eject has succeeded • This can lead to unnecessary complication in driver code, such as polling or other undesirable workarounds • Asynchronous behavior • Returns no NTSTATUS code (returns VOID)

13. Enhanced Scenario SupportDevice ejection DDIs • In order to better enable hardware evolution and enhance diagnostics, Windows Vista introduces an improved device eject DDI • IoDeviceEjectRequestEx() • Supersedes IoDeviceEjectRequest() • Provides an asynchronous callback mechanism • Allows the caller to determine if and when the actual device ejection has completed successfully • Other software actions may be taken, e.g. • Update a management console; illuminate eject complete indicator • Allows callers to pass in a callback and context to be invoked upon successful completion of the hardware eject operation • Enables synchronous ejection behavior

14. Enhanced Scenario SupportDevice ejection DDIs • Providing an asynchronous callback leads to less complexity in 3rd party driver code • Allows platform firmware a deterministic means to know ejection completion status via _OST • Improves stability, reliability • Fosters easier development and debugging, etc.

15. Enhanced Scenario SupportDevice ejection DDIs • PhysicalDeviceObject – pointer to the PDO of the device to eject • Callback – pointer to the caller's callback if they want to find out the ultimate status of the eject operation • Context – context value passed to the callback • Return Value – standard NTSTATUS codes • If this function succeeds, it does *not* mean that the eject has succeeded rather, it means that the eject was successfully queued up and that the caller's callback will be called with the final status • If this function fails, the caller's callback is not called NTSTATUS IoRequestDeviceEjectEx( __in PDEVICE_OBJECT PhysicalDeviceObject, __in_opt PIO_DEVICE_EJECT_CALLBACK Callback, __in_opt PVOID Context );

16. Enhanced Scenario SupportInterrupt DDIs • With the advent of PCI Express MSI/MSI-X, Windows Vista includes several interrupt architecture enhancements • Kernel PnP exports a new DDI for connecting to interrupts: IoConnectInterruptEx() • Required for devices that support Message-signaled interrupts • For details, refer to the white paper “Interrupt Architecture Enhancements in Windows”

17. Enhanced Scenario SupportAsynchronous PnP operations • Two of the slowest PnP operations are • Starting a device • IRP_MN_START_DEVICE • Enumerating a bus • IRP_MN_QUERY_RELATIONS – BusRelations • Historically, PnP serialized these operations • In Windows Vista, these operations are overlapped • Offers substantive savings on consumer desktops • ≈ 1 to 3 seconds by overlapping PATA/SATA enumeration • Huge gains possible on systems with large number of slow devices

18. Enhanced Scenario SupportAsynchronous PnP operations • Driver participation is required to enable parallelism • Drivers should pend these IRPs • IRP_MN_QUERY_RELATIONS (BusRelations) • IRP_MN_START_DEVICE • PnP manager will dispatch other operations while the IRP is in a pended state • This only works if drivers participate • On older versions of Windows, pending an IRP has no net effect • PnP manager will wait for the pended IRP to complete • PnP will provide tracing data • Allows driver writers to determine how long it takes to complete these IRPs • Indicates if the IRP was pended

19. Enhanced Scenario SupportAsynchronous PnP operations • Drivers having start order dependencies will not work • E.g., PS/2 mouse and keyboard • Avoid these types of dependencies in your designs • Plug and play will serialize operations around drivers known to have such dependencies • Avoid exposing any start order-dependent information • Network connection numbers • Disk numbers • COM port numbers

20. Enhanced Scenario SupportKernel PnP diagnostic tracing • Windows Vista contains diagnostic tracing hooks around plug and play operations • Allows tracing failed PnP operations such as • Ejection failures • Code 10 failures (device failed to start) • Data may be utilized for • Identifying problematic systems or devices • Discovering failure trends

21. Enhanced Scenario SupportKernel PnP diagnostic tracing • Tracing is visible in Event Viewer • Ejection failures will appear in the System channel by default • More detailed tracing can be enabled for the Kernel-PnP Diagnostic provider • Refer to WHDC for additional details

22. Enhanced Scenario SupportKernel PnP diagnostic tracing

23. Hardware Evolution SupportLegacy reduction • Microsoft is continuing to eliminate legacy platform support as new technologies mature • Reduces platform complexity while increasing flexibility • Improves system reliability • Reduces firmware code size • Future legacy reduction efforts will be communicated in the Windows Hardware Newsletter

24. Hardware Evolution SupportLegacy reduction • ACPI support is required in Windows Vista • Only the ACPI HAL and multiprocessor kernel are provided • APM, MPS, PNPBIOS support has been removed • No ISAPnP enumeration support • isapnp.sys is not installed by default • Requires reference in your device’s .inf • Minimal functionality preserved in msisadrv.sys • Contains routines to manage an ISA bridge • Allows exporting an interrupt translator interface from the HAL • Required to support PS/2 keyboards and mice

25. Hardware Evolution SupportLarge resource descriptors • Previous versions of Windows operating systems limited the length of a single address range descriptor to 4 GB • Ranges > 4 GB had to be broken up into n contiguous 4 GB ranges • Windows XP and Windows Server 2003 will bug check if they encounter resource descriptors > 4 GB • Windows Vista introduces support for large memory descriptors • BIOS ASL can use QWORD resource descriptors to describe ranges > 4 GB

26. Hardware Evolution SupportLarge resource descriptors • Windows Vista defines new large memory resource types • Defined in wdm.h • Used internally in Windows Vista to support Hot Add memory, large PCI Express BARs • Used by: acpi.sys, pci.sys • These memory types should only be accessed using the DDIs provided • Details will be published in the WDK

27. Hardware Evolution SupportLarge resource descriptors

28. Hardware Evolution SupportLarge resource descriptors • NTSTATUS • RtlIoEncodeMemIoResource ( • __in PIO_RESOURCE_DESCRIPTOR Descriptor, • __in UCHAR Type, • __in ULONGLONG Length, • __in ULONGLONG Alignment, • __in ULONGLONG MinimumAddress, • __in ULONGLONG MaximumAddress • ); • NTSTATUS • RtlCmEncodeMemIoResource ( • __in PCM_PARTIAL_RESOURCE_DESCRIPTOR Descriptor, • __in UCHAR Type, • __in ULONGLONG Length, • __in ULONGLONG Start • ); • ULONGLONG • RtlIoDecodeMemIoResource ( • __in PIO_RESOURCE_DESCRIPTOR Descriptor, • __out_opt PULONGLONG Alignment, • __out_opt PULONGLONG MinimumAddress, • __out_opt PULONGLONG MaximumAddress • ); • ULONGLONG • RtlCmDecodeMemIoResource ( • __in PCM_PARTIAL_RESOURCE_DESCRIPTOR Descriptor, • __out_opt PULONGLONG Start • );

29. Hardware Evolution SupportDescribing resource domains • A resource domain starts with either • An ACPI module device • A PCI root bridge (PCI Express root port) • All child resources within a resource domain must be claimed by the root • For a subtractive PCI bridge, subtractive resources must be reported • Positive decode resources must be correctly reported by the PCI bridge • All PCI bus numbers must be accurately reported

30. Hardware Evolution SupportNUMA support • Windows Server Longhorn will make use of platform-reported proximity relationships • Correlates devices with temporal memory and processor resources • Key driver routines are invoked on the closest processor, so memory will be allocated from NUMA local memory • Requires no driver changes • AddDevice, IRP_MN_QUERY_DEVICE_RELATIONS-BusRelations • The platform should include _PXM in the appropriate scope in the system hierarchy • _PXM must correlate to either SRAT or ACPI namespace information for memory and processor

31. Hardware Evolution SupportResource allocation • Windows Vista introduces several changes to resource allocation to better support PCI bridges • Partial arbitration • Support for both pure and partially subtractive PCI bridges • Windows Vista has reduced the default sizes for PCI bridge windows • On a large server system, previous default bridge window sizes could lead to resources being over-committed • I/O windows are limited to 4 K • PCI Express endpoints may not use I/O • Memory windows are limited to 1 MB

32. Hardware Evolution SupportResource allocation • If a critical device is a peer of a non-boot configured device, the parent PCI bridge won’t get rebalanced • Example devices that will limit rebalance • Debugger devices (USB or 1394) • VGA • Mass storage device • Partially boot configured bridges will not be rebalanced • Bridge windows can’t be expanded • Devices behind the bridge may not be functional due to resource conflicts or failures • Platform must boot configure required boot devices • If devices requiring boot configuration are behind a bridge, boot configure all devices behind the bridge

33. Hardware Evolution SupportMultilevel resource rebalance • Multilevel resource rebalance is a mechanism used by PnP to dynamically reconfigure a device hierarchy that has already been assigned resources • Allows for optimal resource assignment for a newly added device • BIOS solution may over-commit resources • Allows Windows Vista to dynamically respond to events like docking or hot add of devices • Multilevel rebalance has implications for devices behind PCI bridges and BIOS configuration of bridges and devices • This will allow dynamic adjustment of PCI bridge resources • Resource rebalance is transparent to applications

34. Hardware Evolution SupportMultilevel resource rebalance • Rebalance event flow • Resource rebalance is triggered by a hardware event • Plug and play attempts to stop devices • New resource assignments are computed using devices that can be stopped • Plug and play stops devices that can be stopped • Plug and play restarts stopped devices with new resource assignments

35. Hardware Evolution SupportMultilevel resource rebalance • Example driver events that will trigger resource rebalance • Plug and play cannot assign resources to a newly added device • For instance, a PCI ExpressCard device is inserted and the memory range for the parent PCI bridge cannot accommodate the device’s memory requirements • Driver reports that its resource requirements have changed • Device driver calls IoInvalidateDeviceState() and reports PNP_DEVICE_RESOURCE_REQUIREMENTS_CHANGED in the subsequent IRP_MN_QUERY_PNP_DEVICE_STATE • Allows a driver to relinquish unused resources back to the system

36. Hardware Evolution SupportMultilevel resource rebalance Started State IRP_MN_QUERY_STOP_DEVICE (1) IRP_MN_CANCEL_STOP_DEVICE (4) Stop-Pending State IRP_MN_STOP_DEVICE (2) Stopped State IRP_MN_START_DEVICE (3) Failed Restart (5)

37. Hardware Evolution SupportMultilevel Resource Rebalance • Handling Resource Rebalance Requests • Plug and play will send IRP_MN_QUERY_STOP_DEVICE to drivers • Devices that succeed this IRP will participate • Succeed this IRP as much as possible • If succeeded, plug and play will send • IRP_MN_STOP_DEVICE • IRP_MN_START_DEVICE • With new set of resources • If a child device fails this IRP, its parent cannot be stopped • Failing this IRP can cause resource rebalance to fail • Some device will not work in the system • Code 12 – CM_PROB_NORMAL_CONFLICT • If you fail IRP_MN_QUERY_STOP_DEVICE, you will receive IRP_MN_CANCEL_STOP_DEVICE

38. Hardware Evolution SupportMultilevel resource rebalance • When you receive IRP_MN_STOP_DEVICE, drivers must • Queue all I/O requests (do not fail I/O) • Release all hardware resources • Disconnect interrupts • Unmap I/O, memory and disable hardware decodes • Do not put the device into D3 • Do not reset I/O queues • When you receive a IRP_MN_START_DEVICE after a IRP_MN_STOP_DEVICE, drivers must • Treat the resources as new resources • Reconnect new interrupts • Map new I/O, memory and enable hardware decodes • Do not re-initialize IO queues • Resume handling I/O

39. Hardware Evolution SupportMultilevel resource rebalance • Be prepared to handle resource rebalance in your device drivers • You may see IRP_MN_SURPRISE_REMOVAL immediately after IRP_MN_STOP_DEVICE • If a parent device failed its IRP_MN_START_DEVICE during rebalance • You may see a IRP_MN_CANCEL_STOP_DEVICEwithout seeing a IRP_MN_QUERY_STOP_DEVICE • This can happen if someone above you in the stack fails IRP_MN_QUERY_STOP_DEVICE and completes the IRP

40. Hardware Evolution SupportMultilevel resource rebalance • Test your driver for resource rebalance requests • Enable driver verifier • Run pnpdtest.exe to attempt resource rebalance on your device • Pnpdtest.exe is available in the WDK

41. Avoiding PnP Problems • MCFG resource conflicts • Claim MCFG resources as a motherboard resource devnode • As a peer of your root PCI bus • Correctly report subtractive decode resources • Properly report resources for subtractive bridges • All subtractive devices must be accounted for at the hierarchy root • Correct use of motherboard resource devnodes • Claim resources at the proper level in the device hierarchy • E.g., ISA resources should be under the PCI-ISA bridge • Should represent real addresses not discoverable by the OS • Provide an _DIS method for devices claiming resources not decoded by actual hardware

42. Machine.inf Logistics • Machine.inf is the INF file used by the Windows operating system • To map core chipset hardware and BIOS-enumerated device identifiers (IDs) during the Windows startup process • Machine.inf requires updates • When new chipsets evolve • When system manufacturers change device description strings for their current chipsets • Updates are incorporated into the latest Windows build on a quarterly basis

43. Machine.inf Logistics • Submissions for Windows Vista will be accepted up until the Release Candidate 1 (RC1) milestone • You are required to provide two test hardware systems to Microsoft • Use care with NO_DRV versus PCI_DRV .inf directives • System can become inoperative if NO_DRV is specified on PCI bridges with child devices • For details, refer to the white paperMachine.inf Update Submission Procedure

44. Call To Action • Continue driving deprecation of unnecessary legacy BIOS features • Firmware developers should start using large resource descriptors for systems running Windows Vista • Take advantage of the enhanced ejection infrastructure in Windows Vista • Test and report issues to Microsoft • Driver developers should begin using IoConnectInterruptEx() • Driver developers must properly design and test for to support changes in PnP • Asynchronous operations – measure start performance improvements • Multilevel resource rebalance • New PnP DDIs

45. Additional Resources • Web Resources • Plug and Play – Architecture and Driver Support http://www.microsoft.com/whdc/system/pnppwr/pnp/default.mspx • White Papers • Firmware Allocation of PCI Device Resources in Windowshttp://www.microsoft.com/whdc/system/bus/pci/PCI-rsc.mspx • Interrupt Architecture Enhancements in Windowshttp://www.microsoft.com/whdc/system/bus/PCI/MSI.mspx • PCI Multi-level Rebalance in Windows Longhornhttp://www.microsoft.com/whdc/system/bus/PCI/multilevel-rebal.mspx • Supporting Subtractive PCI-to-PCI Bridges in Windowshttp://www.microsoft.com/whdc/system/bus/pci/PCIbridge-subtr.mspx • Machine.inf Update Submission Procedurehttp://www.microsoft.com/whdc/system/CEC/machine_inf.mspx • Related Sessions • CPA0070 PCI Express In-Depth for Windows Vista • CPA002 ACPI in Windows Vista • Kernel PnP support questions Ntpnp @ microsoft.com

46. © 2006 Microsoft Corporation. All rights reserved. Microsoft, Windows, Windows Vista and other product names are or may be registered trademarks and/or trademarks in the U.S. and/or other countries. The information herein is for informational purposes only and represents the current view of Microsoft Corporation as of the date of this presentation. Because Microsoft must respond to changing market conditions, it should not be interpreted to be a commitment on the part of Microsoft, and Microsoft cannot guarantee the accuracy of any information provided after the date of this presentation. MICROSOFT MAKES NO WARRANTIES, EXPRESS, IMPLIED OR STATUTORY, AS TO THE INFORMATION IN THIS PRESENTATION.