HalSetBusDataByOffset

HalSetBusDataByOffset

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

HalSetBusDataByOffset sets bus-configuration data for a device on a dynamically configurable I/O bus with a published, standard interface.

Parameters

BusDataType

Specifies the type of bus data to be set. Currently, its value can be the following: PCIConfiguration. However, additional types of bus configuration 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 with configuration information specific to BusDataType.

When PCIConfiguration is specified, the buffer contains some or all of the PCI_COMMON_CONFIG information for the given SlotNumber. The specified Offset and Length determine how much information is supplied. Certain members of PCI_COMMON_CONFIG have read-only values, and the caller is responsible for preserving the system-supplied values of read-only members.

Offset

Specifies the byte offset in the PCI_COMMON_CONFIG structure at which the caller-supplied configuration values begin. Callers can use the system-defined constant PCI_COMMON_HDR_LENGTH to specify the device-specific area of PCI_COMMON_CONFIG.

Length

Specifies the number of bytes in the Buffer.

Return Value

HalSetBusDataByOffset returns the number of bytes of data successfully set for the given SlotNumber. If the given BusDataType is not valid for the current platform or if the supplied information is invalid, this routine returns zero.

Comments

Callers of HalAssignSlotResources or IoAssignResources seldom call HalSetBusDataByOffset or HalSetBusData, because each of these XxAssignXxx routines sets up the configuration information for the given SlotNumber and returns the information to the caller. However, a driver can call HalSetBusDataByOffset or HalSetBusData if unusual circumstances or the nature of its device requires such a call. For example, a driver might call either of these routines to clear a bit in the PCI status register if its device signals a target abort during initialization.

When accessing the device-specific area of the PCI configuration space, HalSetBusDataByOffset 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 HalSetBusDataByOffset can be running at IRQL <= DISPATCH_LEVEL. Otherwise, callers of HalSetBusDataByOffset must be running at IRQL PASSIVE_LEVEL.