Device Enumeration

Device Enumeration

As briefly described earlier in this chapter, the PnP Configuration Manager is responsible for enumerating the hardware discovered on a system. Starting at system boot, or as devices are inserted or removed, a bus driver is responsible for identifying and listing (i.e., enumerating ) attached hardware. The hardware resources assigned to a device are supplied to the driver when the PnP Start Message subcode (IRP_MN_START_DEVICE) is sent.

The technique used to assign unique hardware resources to a device is bus-and driver-dependent. For example, it is possible that two devices installed in a system have conflicting resource requirements at boot time. Both devices might default to the same I/O port address. The PnP Configuration Manager is responsible for sorting out any such conflicts. Further, an individual driver (FDO) might choose not to utilize a resource at all. For example, printer drivers do not always use an interrupt line even though the hardware allows it. An unused printer IRQL can be safely assigned to other devices. In other words, the assignment of hardware resources is a dynamic and iterative process involving the bus and device hardware, the PnP Manager, and the device driver.

Hardware Resource Descriptors

When a driver receives the PnP subcode IRP_MN_START_DEVICE, two fields within the IRP stack list the assigned hardware resources: Parameters.StartDevice.AllocatedResourcesTranslated and Parameters.StartDevice.AllocatedResources .

The structure used to describe these resources is of the type CM_RESOURCE_LIST, which is a counted array . The first offset within the structure, Count , signifies the number of array elements which follow. Each array element is of the type CM_FULL_RESOURCE_DESCRIPTOR. The array element contains a bus type and number (e.g., ISA bus 0) as well as a CM_PARTIAL_RESOURCE_LIST, which is another counted array. Each element of the inner array is of the type CM_PARTIAL_RESOUCE_DESCRIPTOR, which finally (and thankfully) describes the resources assigned to the device. Figure 9.6 depicts this four-level structure.

Figure 9.6. Resource list data structures.

The structure of interest is within the fourth level and is a union, u . The four significant united types are Port , Interrupt , Memory , and Dma . The fields of each of these types are copied into the device extension and are used by an FDO driver for the duration. For example, when the time comes to perform an actual DMA operation, the Channel and Port offsets of the Dma structure are required.

Example code that would retrieve the i ^th element within the PARTIAL_RESOUCE_LIST follows .

PCM_RESOURCE_LIST pResourceList;
PCM_FULL_RESOURCE_DESCRIPTOR pFullDescriptor;
PCM_PARTIAL_RESOURCE_LIST pPartialList;
PCM_PARTIAL_RESOURCE_DESCRIPTOR pPartialDescriptor;
int i;
pResourceList =
     &Parameters.StartDevice.AllocatedResourcesTranslated;
pFullDescriptor =
     pResourceList->List;
pPartialList =
     pFullDescriptor->PartialResourceList;
for (i=0; i<pPartialList->Count; i++) {
     pPartialDescriptor =
          &pPartialList->PartialDescriptors[i];
     switch (pPartialDescriptor->Type) {
case Interrupt:
     pDevExt->IRQL =
          pPartialDescriptor->u.Interrupt.Level;
     pDevExt->Vector =
          pPartialDescriptor->u.Interrupt.Vector;
     pDevExt->Affinity =
          pPartialDescriptor->u.Interrupt.Affinity;
     IoConnectInterrupt(...);
     break;
case Dma:
     pDevExt->Channel =
          pPartialDescriptor->u.Dma.Channel;
     pDevExt->Port =
          pPartialDescriptor->u.Dma.Port;
     break;
case Port:
     pDevExt->PortBase =
          pPartialDescriptor->u.Port.Start;
     pDevExt->PortLength =
          pPartialDescriptor->u.Port.Length;
     ...
case Memory:
     ...
     MmMapIoSpace(...);
...
}

Using Hardware Resources Within the Driver

There are two sets of hardware resources supplied by the fields of the IRP when the IRP_MN_START_DEVICE subcode is received -raw and translated -and they serve different purposes throughout the life of the driver. (The Parameters.StartDevice.AllocatedResources field describes raw resources.)

Raw resources describe bus-relative addresses (ports, IRQLs, and DMA channels) that formerly would have been passed to routines such as HalTranslateBusAddress. Such functions are now obsolete since a PnP driver receives the translated resource list at the same time it receives the raw list. There should be a one-to-one correspondence between each raw resource and its translated counterpart .

Since the HAL macros (READ_PORT_XXX, WRITE_PORT_XXX, etc.) assume translated resources, there is little value (other than trace purposes) to keep track of raw resources.

Finally, it should be noted that devices are presented with their resource list. A driver that wishes to minimize the resources it consumes must implement a PnP handler for the IRP_MN_FILTER_RESOURCE_REQUIREMENTS subcode. The PnP Configuration Manager submits this request (opportunity) to a device stack after devices start. The PnP Manager supplies the current list of device resources and allows a driver to modify (usually by deletion) the set of resources it consumes. In this way, a printer driver, for example, could announce that the IRQL resource will not be serviced.