HalGetBusDataByOffset function (ntddk.h)

Article
01/17/2024

Warning

HalGetBusDataByOffset and HalSetBusDataByOffset are provided for backward compatibility but should be used only if the methods recommended in Accessing Device Configuration Space cannot be used.

This function retrieves information, starting at the offset, about a slot or address on an I/O bus.

Syntax

NTHALAPI ULONG HalGetBusDataByOffset(
  [in] BUS_DATA_TYPE BusDataType,
  [in] ULONG         BusNumber,
  [in] ULONG         SlotNumber,
  [in] PVOID         Buffer,
  [in] ULONG         Offset,
  [in] ULONG         Length
);

Parameters

[in] BusDataType

Bus data to retrieve. The upper bound on the bus types supported is always MaximumBusDataType. The only supported BusDataType is PCIConfiguration All other types are deprecated.

[in] BusNumber

Zero-based and system-assigned number of the bus in systems with several buses of the same BusDataType. This argument also carries the segment number. To specify the segment number, use (Segment << 8) | BusNumber

[in] SlotNumber

Logical slot number or location of the device. If you specify PCIConfiguration as the BusDataType, this value is a PCI_SLOT_NUMBER value, which is the slot and function numbers combined.

[in] Buffer

Pointer to a caller-supplied buffer for configuration information specific to BusDataType.

If you specify PCIConfiguration, the buffer contains the PCI config space information for the specified SlotNumber and function number. The specified Offset and Length determine how much information to supply. Certain members of PCI config space have read-only values The caller is responsible for preserving the system-supplied values of read-only members. Note that for a Type-1 PCI device, HalSetBusDataByOffset prevents writes to registers inside the common header (first 256bytes of the config space).

[in] Offset

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.

[in] Length

Maximum number of bytes in the Buffer.

Return value

The return value is the actual length read from the config space.

Remarks

Device drivers call this function during initialization to locate their devices on a particular I/O bus. You can use the returned bus-type-specific configuration data in later calls to other configuration and initialization functions, such as HalTranslateBusAddress.

When accessing the device-specific area of the PCI configuration space, HalGetBusDataByOffset guarantees that this function never reads or writes data outside the range specified by the input Offset and Length. Even if the input Length is exactly a 1-byte or 2-byte word, this function never accesses any data outside the requested range.

Requirements

Requirement	Value
Header	ntddk.h (include Ntddk.h)