16.8.2.2  Calling HalGetBusData or HalGetBusDataByOffset

NT device drivers can call HalGetBusDataByOffset or HalGetBusData to get hardware configuration information, particularly for devices on EISA, MCA, or PCI buses.

Figure 16.8 illustrates a device driver’s call to HalGetBusData(ByOffset).

Figure 16.8    Getting Hardware Configuration Information from an I/O Bus

As Figure 16.8 shows, HalGetBusDataByOffset returns bus-type-specific configuration information for a particular slot (or location, depending on the input BusDataType value) on a particular I/O bus to a driver-allocated buffer.

An NT device driver can allocate memory for such a buffer from paged pool, as described in Section 16.4.1.3. The Length value passed to HalGetBusDataByOffset, which specifies the maximum amount of configuration data requested, usually is the NumberOfBytes that was passed in the driver’s call to ExAllocatePool or ExAllocatePoolWithTag.

HalGetBusDataByOffset returns a value indicating the number of bytes of configuration information it wrote at the given Buffer. The structure of returned bus-relative configuration information depends on the input BusDataType. For more specific information about these system-defined structures for a particular types of I/O buses and about HalGetBusDataByOffset and HalGetBusData, see the Kernel-Mode Driver Reference.

HalGetBusDataByOffset takes an Offset parameter that specifies the offset within a dynamically configurable bus’s configuration structure from which subsequent bytes should be returned in the driver-allocated buffer. For such an I/O bus, the structure of its configuration information is defined by the standard for that type of bus. Drivers of devices on such a bus also might call HalSetBusData or HalSetBusDataByOffset.

Drivers of devices on other types of buses that are not dynamically configurable also can call HalGetBusDataByOffset if they pass an Offset of zero. A call to HalGetBusData is equivalent to a call to HalGetBusDataByOffset with a zero Offset.

As Figure 16.8 suggests, a device driver can call HalGetBusDataByOffset more than once for a particular I/O bus to investigate the devices in each slot. A driver must call HalGetBusData to investigate each possible location for the BusDataType Cmos.

If there is more than one bus of a given BusDataType in the machine, an NT device driver also can increment the input BusNumber and call HalGetBusData or HalGetBusDataByOffset until the driver has looped through all slots on all I/O buses of that type in the machine.

Note that HalGetBusData or HalGetBusDataByOffset also might get configuration information about the number of I/O buses of a particular type in a machine from the registry, as suggested by Figure 16.8.