Creating Device Objects in a Bus Driver

Each bus driver must create a framework device object when it discovers that a child device is connected to a parent device. The parent device is typically a bus, but it can also be a multifunction device for which each function requires a separate set of drivers (such as a sound card that supports digital audio and MIDI). The device objects that bus drivers create are called physical device objects (PDOs) because each represents an actual connection of one piece of hardware (the child) to another (the parent).

The process of identifying and reporting the devices that are connected to a bus is called bus enumeration.

• If a bus driver performs dynamic bus enumeration, its EvtChildListCreateDevice callback function receives a handle to a WDFDEVICE_INIT structure.

• If a bus driver performs static bus enumeration, it must call WdfPdoInitAllocate to obtain a handle to a WDFDEVICE_INIT structure.

For more information about bus enumeration, see Enumerating the Devices on a Bus.

A bus driver can call a set of framework device object initialization methods, which store information in the WDFDEVICE_INIT structure. Additionally, bus drivers can call framework PDO initialization methods.

Creating a framework device object for an enumerated child device typically includes the following steps:

• Registering bus driver-specific callback functions.

  Most bus drivers call WdfPdoInitSetEventCallbacks, because they must specify the system hardware resources that a device requires. For more information about specifying hardware resources, see Hardware Resources for Framework-Based Drivers. Additional callback functions can be registered if the device and driver support ejection.

• Reporting device identification strings.

  Bus drivers must report the device's identification strings by calling WdfPdoInitAssignDeviceID, WdfPdoInitAssignInstanceID, WdfPdoInitAddCompatibleID, and WdfPdoInitAddHardwareID for each type of string that the device supports. In addition, bus drivers that use version 1.9 or later of the framework can call WdfPdoInitAssignContainerID.

• Reporting whether the bus driver can support the device in raw mode.

  If the bus driver supports raw mode for the device, it must call WdfPdoInitAssignRawDevice.

• Providing displayable text that describes the device.

  Bus drivers call WdfPdoInitAddDeviceText and WdfPdoInitSetDefaultLocale to provide text that describes the device to users, in multiple languages.

• Creating the device object.

  The final step in creating a device object is to call WdfDeviceCreate.

If the driver encounters an error while initializing the WDFDEVICE_INIT structure that it obtained from WdfPdoInitAllocate, the driver must call WdfDeviceInitFree instead of WdfDeviceCreate.

After the bus driver has created the device object, it typically calls WdfDeviceSetPnpCapabilities and WdfDeviceSetPowerCapabilities to report the device's Plug and Play and power capabilities.

Each bus driver is also the function driver for the bus adapter. Therefore, the driver must also provide an EvtDriverDeviceAdd callback function. This callback function creates a functional device object (FDO) for each bus adapter on the system. For more information about creating FDOs, see Creating Device Objects in a Function Driver.