HalGetBusDataByOffset

ULONG
HalGetBusDataByOffset(
IN BUS_DATA_TYPE BusDataType,
IN ULONG BusNumber,
IN ULONG SlotNumber,
IN PVOID Buffer,
IN ULONG Offset,
IN ULONG Length
);

HalGetBusDataByOffset obtains details, starting at the given offset, about a given slot on an I/O bus.

Parameters

BusDataType

Specifies the type of bus data to be retrieved. Currently, its value can be the following: EisaConfiguration, Pos, or PCIConfiguration. However, additional types of dynamically configurable buses will be supported in future versions of Windows NT. The upper bound on the bus types supported is always MaximumBusDataType.

BusNumber

Specifies the zero-based and system-assigned number of the bus in systems with more than one bus of the same BusDataType.

SlotNumber

Specifes the logical slot number. When PCIConfiguration is specified, this is a PCI_SLOT_NUMBER-type value.

Buffer

Points to a caller-supplied buffer for configuration information specific to BusDataType

If EisaConfiguration is specified, the buffer will contain the CM_EISA_SLOT_INFORMATION structure followed by zero or more CM_EISA_FUNCTION_INFORMATION structures for the specified slot.

If Pos is specified, the buffer will contain a CM_MCA_POS_DATA structure for the specified slot.

When PCIConfiguration is specified, the buffer will contain some or all of the PCI_COMMON_CONFIG information for the given SlotNumber. The specified Offset and Length determine how much information is requested.

Offset

Specifies zero if the BusDataType is EisaConfiguration or Pos. Otherwise, specifies the byte offset in the PCI_COMMON_CONFIG structure for which the requested information should be returned. Callers can use the system-defined constant PCI_COMMON_HDR_LENGTH to specify the device-specific area of PCI_COMMON_CONFIG.

Length

Specifies the maximum number of bytes to return in the Buffer.

Return Value

HalGetBusDataByOffset returns the number of bytes of data it wrote in the given buffer. If the given BusDataType is not valid for the current platform, this routine returns zero.

When the input BusType is PCIConfiguration, HalGetBusDataByOffset can return either of the following values to indicate an error:

Value

Meaning

0 (zero)

The specified PCI bus does not exist.

2

The specified PCI bus exists, but there is no device at the given PCI SlotNumber. The Buffer also contains the value PCI_INVALID_VENDOR_ID at the PCI_COMMON_CONFIG VendorId member.

Comments

Device drivers call this routine during initialization to locate their devices on a particular I/O bus in the machine. The bus-type-specific configuration data returned is later used in calls to other configuration and initialization routines, such as HalTranslateBusAddress, HalGetInterrupt, HalGetAdapter, IoAssignResources or HalAssignSlotResources, and so forth.

When accessing the device-specific area of the PCI configuration space, HalGetBusDataByOffset guarantees the following:

This routine never reads or writes data outside the range specified by the input Offset and Length.
Even if the input Length is exactly a byte or a (two-byte) word, this routine never accesses any data outside the requested range.

If the input BusDataType is PCIConfiguration, callers of HalGetBusDataByOffset can be running at IRQL <= DISPATCH_LEVEL. Otherwise, callers of HalGetBusDataByOffset must be running at IRQL PASSIVE_LEVEL.

Value	Meaning
0 (zero)	The specified PCI bus does not exist.
2	The specified PCI bus exists, but there is no device at the given PCI SlotNumber. The Buffer also contains the value PCI_INVALID_VENDOR_ID at the PCI_COMMON_CONFIG VendorId member.