Presentation is loading. Please wait.

Presentation is loading. Please wait.

Toaster Sample Package Eliyas Yakub Windows NT ® DDK Support Engineer Developer Support Microsoft Corporation.

Similar presentations


Presentation on theme: "Toaster Sample Package Eliyas Yakub Windows NT ® DDK Support Engineer Developer Support Microsoft Corporation."— Presentation transcript:

1 Toaster Sample Package Eliyas Yakub Windows NT ® DDK Support Engineer Developer Support Microsoft Corporation

2

3 Agenda Introduce various components of Toaster Sample Package Introduce various components of Toaster Sample Package Describe how the sample was implemented by highlighting core components Describe how the sample was implemented by highlighting core components

4 Package Layout Located under NTDDK\SRC\GENERAL\TOASTER Located under NTDDK\SRC\GENERAL\TOASTER

5 Objectives Of The Sample De-mystify Windows ® Driver Model De-mystify Windows ® Driver Model Through the use of sample code demonstrate how to develop: Through the use of sample code demonstrate how to develop: Bus Driver Bus Driver Function Driver Function Driver Filter Drivers (Class & Device) Filter Drivers (Class & Device) Coinstaller DLL Coinstaller DLL Power Management Power Management WMI WMI Plug and Play Notification in user-mode and kernel-mode Plug and Play Notification in user-mode and kernel-mode

6 What Is Toaster Bus Hypothetical bus for toaster devices Hypothetical bus for toaster devices Simulates hot plug-in, unplug, and eject toasters devices Simulates hot plug-in, unplug, and eject toasters devices Toasters support power management Toasters support power management Defines a new Toaster device class Defines a new Toaster device class

7 Bus Driver (BusEnum.sys) Dual personality driver Dual personality driver Use bus.inf and busf.inf to install through the Add HW Wizard Use bus.inf and busf.inf to install through the Add HW Wizard System root enumerates the bus driver System root enumerates the bus driver DriverEntry() DriverEntry() Sets dispatch points Sets dispatch points AddDevice() AddDevice() Creates FDO and attaches it to the PDO provided by the Plug and Play manager Creates FDO and attaches it to the PDO provided by the Plug and Play manager

8 Bus Driver Registers GUID_TOASTER_BUS_ENUMERATOR_INTERFAC E_CLASS interface Registers GUID_TOASTER_BUS_ENUMERATOR_INTERFAC E_CLASS interface Driver typically handles following IRPs: Driver typically handles following IRPs: IRP_MN_FILTER_RESOURCE_REQUIREMENTS IRP_MN_FILTER_RESOURCE_REQUIREMENTS IRP_MN_START_DEVICE IRP_MN_START_DEVICE IRP_MN_QUERY_CAPABILITIES IRP_MN_QUERY_CAPABILITIES IRP_MN_QUERY_PNP_DEVICE_STATE IRP_MN_QUERY_PNP_DEVICE_STATE IRP_MN_QUERY_DEVICE_RELATIONS (BusRelations) IRP_MN_QUERY_DEVICE_RELATIONS (BusRelations) This is not a complete list. Drivers shouldnt make any assumptions about the order of these IRPs This is not a complete list. Drivers shouldnt make any assumptions about the order of these IRPs

9 Plug In A Device

10 Simulating Plug-In Of New Toaster Device Application opens the interface registered by BusEnum Application opens the interface registered by BusEnum Application sends IOCTL_BUSENUM_PLUGIN_HARDWARE Application sends IOCTL_BUSENUM_PLUGIN_HARDWARE Provides Serial Number and HW ID of the device Provides Serial Number and HW ID of the device

11 Plug-In BusEnum creates a DeviceObject (PDO) for the new device BusEnum creates a DeviceObject (PDO) for the new device Initializes device extension Initializes device extension Present = TRUE; Present = TRUE; ReportedMissing = FALSE; ReportedMissing = FALSE; BusEnum notifies Plug and Play manager BusEnum notifies Plug and Play manager Calls IoInvalidateDeviceRelations() with BusRelations parameter Calls IoInvalidateDeviceRelations() with BusRelations parameter

12 Plug-In Plug and Play manager sends IRP_MN_QUERY_DEVICE_RELATIONS to BusEnums FDO Plug and Play manager sends IRP_MN_QUERY_DEVICE_RELATIONS to BusEnums FDO The BusEnum returns a list of PDO pointers The BusEnum returns a list of PDO pointers Plug and Play manager starts enumeration after discovering PDO for the new Toaster device Plug and Play manager starts enumeration after discovering PDO for the new Toaster device

13 Plug-In Plug and Play manager sends following IRPs to the new PDO to learn more about the device: Plug and Play manager sends following IRPs to the new PDO to learn more about the device: IRP_MN_QUERY_ID (BusQueryDeviceID) IRP_MN_QUERY_ID (BusQueryDeviceID) IRP_MN_QUERY_CAPABILITIES IRP_MN_QUERY_CAPABILITIES IRP_MN_QUERY_DEVICE_TEXT (Description) IRP_MN_QUERY_DEVICE_TEXT (Description) IRP_MN_QUERY_DEVICE_TEXT (Location) IRP_MN_QUERY_DEVICE_TEXT (Location) IRP_MN_QUERY_ID (BusInstanceID) IRP_MN_QUERY_ID (BusInstanceID) IRP_MN_QUERY_ID (BusQueryHardwareIDs) IRP_MN_QUERY_ID (BusQueryHardwareIDs) IRP_MN_QUERY_ID (BusQueryCompatibleIDs) IRP_MN_QUERY_ID (BusQueryCompatibleIDs) IRP_MN_QUERY_RESOURCE_REQUIREMENTS IRP_MN_QUERY_RESOURCE_REQUIREMENTS IRP_MN_QUERY_BUS_INFORMATION IRP_MN_QUERY_BUS_INFORMATION IRP_MN_QUERY_RESOURCES IRP_MN_QUERY_RESOURCES

14 Plug-In Plug and Play loads the toaster.sys function driver Plug and Play loads the toaster.sys function driver Matches the Device ID in toaster.inf Matches the Device ID in toaster.inf Loads the function Driver (toaster.sys) Loads the function Driver (toaster.sys) Calls AddDevice in toaster.sys Calls AddDevice in toaster.sys Function driver handles following Plug and Play IRPs: Function driver handles following Plug and Play IRPs: IRP_MN_FILTER_RESOURCE_REQUIREMENTS IRP_MN_FILTER_RESOURCE_REQUIREMENTS IRP_MN_QUERY_INTERFACE IRP_MN_QUERY_INTERFACE IRP_MN_START_DEVICE IRP_MN_START_DEVICE IRP_MN_QUERY_CAPABILITIES IRP_MN_QUERY_CAPABILITIES IRP_MN_QUERY_PNP_DEVICE_STATE IRP_MN_QUERY_PNP_DEVICE_STATE

15 Notify.exe FDOPDO Toast.exe FDO BusEnum.sys Toaster.sys Plug and Play Manager PDO......... PDOFDO Diagram Of Single Toaster Device

16 Notify.exe FDOPDOPDO FDO Toast.exe PDO FDO BusEnum.sys Toaster.sys Plug and Play Manager PDO......... PDO Diagram Of Two Toaster Devices

17 Unplug A Device Application sends an IOCTL_BUSENUM_UNPLUG_ HARDWARE with the Serial Number Application sends an IOCTL_BUSENUM_UNPLUG_ HARDWARE with the Serial Number BusEnum marks the device as not present BusEnum marks the device as not present Present = FALSE; Present = FALSE; BusEnum informs Plug and Play manager by calling IoInvalidateDeviceRelations() BusEnum informs Plug and Play manager by calling IoInvalidateDeviceRelations() Plug and Play manager sends IRP_MN_QUERY_DEVICE_RELATIONS Plug and Play manager sends IRP_MN_QUERY_DEVICE_RELATIONS BusEnum does not include the unplugged PDO in list of PDOs BusEnum does not include the unplugged PDO in list of PDOs

18 UnPlug Set the ReportedMissing to TRUE Set the ReportedMissing to TRUE ReportedMissing = TRUE; ReportedMissing = TRUE; The Plug and Play manager sends: The Plug and Play manager sends: IRP_MN_SURPRISE_REMOVAL IRP_MN_SURPRISE_REMOVAL IRP_MN_REMOVE_DEVICE IRP_MN_REMOVE_DEVICE Function driver detaches and deletes its device object Function driver detaches and deletes its device object Busenum deletes the PDO after receiving IRP_MN_REMOVE_DEVICE Busenum deletes the PDO after receiving IRP_MN_REMOVE_DEVICE

19 Eject A Device User Application sends IOCTL_BUSENUM_EJECT_HARDW ARE with the Serial Number User Application sends IOCTL_BUSENUM_EJECT_HARDW ARE with the Serial Number BusEnum calls IoRequestDeviceEject BusEnum calls IoRequestDeviceEject The Plug and Play manager sends: The Plug and Play manager sends: IRP_MN_QUERY_REMOVAL IRP_MN_QUERY_REMOVAL IRP_MN_REMOVE_DEVICE IRP_MN_REMOVE_DEVICE

20 Eject Plug and Play manager sends Plug and Play manager sends IRP_MN_EJECT IRP_MN_EJECT set the Present = FALSE; IRP_MN_QUERY_DEVICE_RELATION S (BusRelations) IRP_MN_QUERY_DEVICE_RELATION S (BusRelations) set the ReportedMissing = TRUE; IRP_MN_REMOVE_DEVICE IRP_MN_REMOVE_DEVICE

21 Device Plug And Play State typedef enum _DEVICE_PNP_STATE { NotStarted = 0,// Not started yet NotStarted = 0,// Not started yet Started, // Device has received the START_DEVICE IRP Started, // Device has received the START_DEVICE IRP StopPending,// Device has received the QUERY_STOP IRP StopPending,// Device has received the QUERY_STOP IRP Stopped, // Device has received the STOP_DEVICE IRP Stopped, // Device has received the STOP_DEVICE IRP RemovePending, // Device has received the QUERY_REMOVE IRP RemovePending, // Device has received the QUERY_REMOVE IRP SurpriseRemovePending, // Device has received the SURPRISE_REMOVE IRP SurpriseRemovePending, // Device has received the SURPRISE_REMOVE IRP Deleted // Device has received the REMOVE_DEVICE IRP Deleted // Device has received the REMOVE_DEVICE IRP } DEVICE_PNP_STATE; Notice the use of following macros: Notice the use of following macros: INITIALIZE_PNP_STATE INITIALIZE_PNP_STATE SET_NEW_PNP_STATE SET_NEW_PNP_STATE RESTORE_PREVIOUS_PNP_STATE RESTORE_PREVIOUS_PNP_STATE

22 PDO Deletion Bus drivers must delete the PDO only after device is physically removed Bus drivers must delete the PDO only after device is physically removed Surprise removal Surprise removal After receiving IRP_MN_REMOVE_DEVICE After receiving IRP_MN_REMOVE_DEVICE Ejecting Ejecting After receiving the second IRP_MN_REMOVE_DEVICE After receiving the second IRP_MN_REMOVE_DEVICE During ejection Plug and Play manager sends QUERY_REMOVE, REMOVE, EJECT QUERY_DEVICE_RELATIONS, REMOVE During ejection Plug and Play manager sends QUERY_REMOVE, REMOVE, EJECT QUERY_DEVICE_RELATIONS, REMOVE Second IRP_MN_REMOVE_DEVICE is sent in response to missing PDO returned with QUERY_DEVICE_RELATIONS IRP Second IRP_MN_REMOVE_DEVICE is sent in response to missing PDO returned with QUERY_DEVICE_RELATIONS IRP

23 PDO Deletion Delete all children PDOs when bus is removed or disabled Delete all children PDOs when bus is removed or disabled EXCEPTION: Do NOT delete PDOs in the process of being surprised removed EXCEPTION: Do NOT delete PDOs in the process of being surprised removed Do NOT delete PDO when device is disabled Do NOT delete PDO when device is disabled BUS Driver will receive QUERY_REMOVE / REMOVE IRPs when device is disabled BUS Driver will receive QUERY_REMOVE / REMOVE IRPs when device is disabled Do not delete the PDO because the device is still present Do not delete the PDO because the device is still present

24 Function Driver (toaster.sys) Demonstrates: Demonstrates: Plug and Play handling Plug and Play handling Power management by acting as a power policy owner of the device Power management by acting as a power policy owner of the device WMI WMI IRP Queuing, Cancel and Cleanup techniques IRP Queuing, Cancel and Cleanup techniques Demonstrates the use of IoInValidateDeviceState() to hide your device Demonstrates the use of IoInValidateDeviceState() to hide your device

25 INF Files Bus.inf: For the bus driver Bus.inf: For the bus driver Toaster.inf: For the function driver Toaster.inf: For the function driver Busf.inf: Bus driver with upper and lower device filters Busf.inf: Bus driver with upper and lower device filters Toasterf.inf: Function driver with lower and upper device and class filters Toasterf.inf: Function driver with lower and upper device and class filters Toastco.inf: Installs function driver and a coinstaller dll Toastco.inf: Installs function driver and a coinstaller dll Filter.inf: Installs a device upper filter for the toaster device using Update Driver Filter.inf: Installs a device upper filter for the toaster device using Update Driver

26 Filter Drivers A single source file is used to generate six different filter drivers: A single source file is used to generate six different filter drivers: Devupper.sys Devupper.sys Devlower.sys Devlower.sys Clasupper.sys Clasupper.sys Claslower.sys Claslower.sys BFdoLwr.sys BFdoLwr.sys BFdoUpr.sys BFdoUpr.sys To load all the filters you should use busf.inf to install the enumerator and use toasterf.inf to install device and class filters To load all the filters you should use busf.inf to install the enumerator and use toasterf.inf to install device and class filters

27 Device Filters Installation Use DDInstall.HW sections in the INF file to install filters Use DDInstall.HW sections in the INF file to install filters [Toaster_Device.NT.HW.AddReg] [Toaster_Device.NT.HW.AddReg] HKR,,"UpperFilters",0x00010000,"devupper" HKR,,"UpperFilters",0x00010000,"devupper" HKR,,"LowerFilters",0x00010000,"devlower" HKR,,"LowerFilters",0x00010000,"devlower" These sections adds above registry values under the device hardware key These sections adds above registry values under the device hardware key HKLM\System\CurrentControlSet\Enum\MsToaster\ 1&1a590e2c&1&01 HKLM\System\CurrentControlSet\Enum\MsToaster\ 1&1a590e2c&1&01 UpperFilters:REG_MULTI_SZ:Devupper UpperFilters:REG_MULTI_SZ:Devupper LowerFilters:REG_MULTI_SZ:Devlower LowerFilters:REG_MULTI_SZ:Devlower

28 Enum.exe FDOPDO Toast.exe FiDO BusEnum.sys Toaster.sys Plug and Play Manager FDO FiDO DevUpper.sys DevLower.sys PDOPDOFDO Toaster Stack With Device Filters

29 Class Filters Class filters are specified adding UpperFilters or LowerFilters name value under the class key Class filters are specified adding UpperFilters or LowerFilters name value under the class key HKLM\System\CurrentControlSet\Control \Class\{B85B7C50-6A01-11d2-B841- 00C04FAD5171} UpperFilters:REG_MULTI_SZ:ClasupperLowerFilters:REG_MULTI_SZ:Claslower

30 Enum.exe FDOPDOPDO Toast.exe FiDOFiDO BusEnum.sys Toaster.sys Plug and Play Manager FDOFDO FiDOFiDO DevUpper.sys DevLower.sys FiDOFiDO FiDOFiDO ClasLower.sys ClasUpper.sys PDO PDO FDO

31 Co-Installer Loaded whenever a toaster device is installed or removed Loaded whenever a toaster device is installed or removed Shows how to process custom sections in an INF file Shows how to process custom sections in an INF file Shows how to create a friendly name Shows how to create a friendly name

32 Notify Application Simulates plug in, unplug, and ejection of devices Simulates plug in, unplug, and ejection of devices Demonstrates how applications monitor and process user-mode Plug and Play notifications Demonstrates how applications monitor and process user-mode Plug and Play notifications Combines the functionality of Enum.exe and toast.exe Combines the functionality of Enum.exe and toast.exe

33 Notify Application Register for Interface Change Notification Register for Interface Change Notification DEV_BROADCAST_DEVICEINTERFACE filter; filter.dbcc_size = sizeof(filter); filter.dbcc_devicetype = DBT_DEVTYP_DEVICEINTERFACE; filter.dbcc_classguid = InterfaceGuid; hInterfaceNotification = RegisterDeviceNotification(hWnd, &filter, 0); Handles Plug and Play notifications Handles Plug and Play notifications DBT_DEVICEARRIVAL DBT_DEVICEARRIVAL DBT_DEVICEREMOVECOMPLETE DBT_DEVICEREMOVECOMPLETE

34 Notify Application Open a toster device and register another notification on the file handle Open a toster device and register another notification on the file handle filter.dbch_size = sizeof(filter); filter.dbch_size = sizeof(filter); filter.dbch_devicetype = DBT_DEVTYP_HANDLE; filter.dbch_devicetype = DBT_DEVTYP_HANDLE; filter.dbch_handle = DeviceInfo[NumDevices].hDevice; filter.dbch_handle = DeviceInfo[NumDevices].hDevice; DeviceInfo[NumDevices].hHandleNotification = RegisterDeviceNotification(hWnd, &filter, 0); DeviceInfo[NumDevices].hHandleNotification = RegisterDeviceNotification(hWnd, &filter, 0); Handle Device Change Notification Handle Device Change Notification DBT_DEVICEQUERYREMOVE DBT_DEVICEQUERYREMOVE DBT_DEVICEREMOVECOMPLETE DBT_DEVICEREMOVECOMPLETE DBT_DEVICEREMOVEPENDING DBT_DEVICEREMOVEPENDING DBT_DEVICEQUERYREMOVEFAILED DBT_DEVICEQUERYREMOVEFAILED

35 ToastMon Demonstrates how drivers monitor Plug and Play events of arbitrary devices Demonstrates how drivers monitor Plug and Play events of arbitrary devices Example: monitors a non-Plug and Play serial device Example: monitors a non-Plug and Play serial device Uses kernel-mode Plug and Play notification Uses kernel-mode Plug and Play notification Use toatmon.inf to install the driver through root enumeration Use toatmon.inf to install the driver through root enumeration

36 ToastMon Register for interface arrival notification in AddDevice Register for interface arrival notification in AddDevice status = IoRegisterPlugPlayNotification ( EventCategoryDeviceInterfaceChange, PNPNOTIFY_DEVICE_INTERFACE_INCLUDE_EXISTING_ INTERFACES, (PVOID)&GUID_TOASTER_DEVICE_INTERFACE_CLASS DriverObject, (PDRIVER_NOTIFICATION_CALLBACK_ROUTINE) ToastMon_PnpNotifyInterfaceChange, (PVOID)deviceExtension, &deviceExtension->NotificationHandle); Open the device in response to GUID_TOASTER_DEVICE_INTERFACE_CLASS notification callback Open the device in response to GUID_TOASTER_DEVICE_INTERFACE_CLASS notification callback

37 ToastMon Careful coding required in notification callback Careful coding required in notification callback Do NOT open interface that can cause Plug and Play event Do NOT open interface that can cause Plug and Play event Example: SWENUM Example: SWENUM Doing so can cause deadlock Doing so can cause deadlock

38 ToastMon Register for Device change notification on the FileObject Register for Device change notification on the FileObject IoRegisterPlugPlayNotification ( EventCategoryTargetDeviceChange, 0, (PVOID)List->FileObject, List->DeviceExtension-> DeviceObject->DriverObject, (PDRIVER_NOTIFICATION_CALLBACK_ROUTINE) ToastMon_PnpNotifyDeviceChange, (PVOID)List, &List->NotificationHandle); Handle Notification Callback Events For: Handle Notification Callback Events For:GUID_TARGET_DEVICE_QUERY_REMOVEGUID_TARGET_DEVICE_REMOVE_COMPLETEGUID_TARGET_DEVICE_REMOVE_CANCELLED

39 Setup Class GUID Setup class GUID is specified in the INF file Setup class GUID is specified in the INF file [Version] Signature="$WINDOWS NT$ Class=TOASTER ClassGuid={B85B7C50-6A01-11d2- B841-00C04FAD5171} All the system defined GUIDs are listed in DEVGUID.H All the system defined GUIDs are listed in DEVGUID.H

40 Interface Class GUID Interface GUIDs are used to interact with the driver Interface GUIDs are used to interact with the driver Registered in AddDevice Registered in AddDevice Enabled during Start Enabled during Start Disabled during Remove Disabled during Remove Are defined in device specific header files under the NTDDK\INC directory Are defined in device specific header files under the NTDDK\INC directory Examples: ntdd8042.h, ntddbeep.h, ntddcdrm.h, ntdddisk.h, ntddft.h, ntddft2.h, ntddkbd.h, ntddmou.h, ntddndis.h, ntddpar.h, ntddpcm.h, ntddscsi.h, ntddser.h, ntddstor.h, ntddtdi.h, ntddvol.h Examples: ntdd8042.h, ntddbeep.h, ntddcdrm.h, ntdddisk.h, ntddft.h, ntddft2.h, ntddkbd.h, ntddmou.h, ntddndis.h, ntddpar.h, ntddpcm.h, ntddscsi.h, ntddser.h, ntddstor.h, ntddtdi.h, ntddvol.h

41 Call To Action Study the toaster sample to learn how all the components of a device stack fit together Study the toaster sample to learn how all the components of a device stack fit together Sample complements the DDK documentation Sample complements the DDK documentation Contains extensive internal documentation Contains extensive internal documentation E-mail me (eliyasy@microsoft.com) with questions regarding the sample E-mail me (eliyasy@microsoft.com) with questions regarding the sampleeliyasy@microsoft.com

42 Errata In Line 63, the driver name should be toastmon.sys instead of genport.sys In Line 63, the driver name should be toastmon.sys instead of genport.sys In the toaster.c of function driver the line In the toaster.c of function driver the line IoSetCancelRoutine(nextIrp, Null) should be replace by IoSetCancelRoutine(nextIrp, Null) should be replace by If(IoSetCancelRoutine(nextIrp, Null) ) If(IoSetCancelRoutine(nextIrp, Null) ) { KeReleaseSpinlock(); KeReleaseSpinlock(); Continue; Continue; }

43


Download ppt "Toaster Sample Package Eliyas Yakub Windows NT ® DDK Support Engineer Developer Support Microsoft Corporation."

Similar presentations


Ads by Google