HalTranslateBusAddress

HalTranslateBusAddress

BOOLEAN
HalTranslateBusAddress(
IN INTERFACE_TYPE InterfaceType,
IN ULONG BusNumber,
IN PHYSICAL_ADDRESS BusAddress,
IN OUT PULONG AddressSpace,
OUT PPHYSICAL_ADDRESS TranslatedAddress
);

HalTranslateBusAddress translates a bus-specific address into the corresponding system logical address.

Parameters

InterfaceType

Specifies the bus interface type, which can be one of the following: Internal, Isa, Eisa, MicroChannel, TurboChannel, or PCIBus. However, additional types of buses will be supported in future versions of Windows NT. The upper bound on the types of buses supported is always MaximumInterfaceType.

BusNumber

Specifies the zero-based and system-assigned bus number for the device, used together with InterfaceType to identify the bus for systems with more than one bus of the same type.

BusAddress

Specifies the bus-relative address.

AddressSpace

In cross-platform-portable drivers, specifies whether the address is a port number or a memory address; AddressSpace 0x0 indicates memory, 0x1 is I/O space.

Translated Address

Is a pointer to the translated address.

Return Value

A return value of TRUE indicates the system logical address corresponding to the given BusNumber and BusAddress has been returned in TranslatedAddress.

Comments

The value returned for TranslatedAddress must be used in a subsequent call to MmMapIoSpace if the AddressSpace value of zero is returned.

There are many ways to connect a peripheral bus into a system. The memory address space of the bus, referred to as the logical address space, can be directly merged with the physical address space of the host, or some mapping may be involved. Also, some machines can have more than one bus, or a bus can have more than one address space, as in having separate memory and I/O addresses.

A device driver calls HalTranslateBusAddress to perform this translation. The parameters to this routine include a bus number to support platforms with more than one bus of the same InterfaceType, the bus address to be translated, and an AddressSpace specifier typically used to differentiate between memory and I/O space, if these are separate. The driver might obtain these parameters from the registry, by calling HalGetBusData or HalGetBusDataByOffset and interrogating the device hardware, by calling IoAssignResources or HalAssignSlotResources, or by using defaults and claiming them in the registry.

Callers of HalTranslateBusAddress must be running at IRQL <= DISPATCH_LEVEL. Usually, the caller is running at IRQL PASSIVE_LEVEL, because this routine is seldom called except when a driver is initializing.