BUS_INTERFACE_STANDARD

The BUS_INTERFACE_STANDARD interface structure allows device drivers to make direct calls to parent bus driver routines.

typedef struct _BUS_INTERFACE_STANDARD {
  // generic interface header
  USHORT Size;
  USHORT Version;
  PVOID Context;
  PINTERFACE_REFERENCE InterfaceReference;
  PINTERFACE_DEREFERENCE InterfaceDereference;
  // standard bus interface
  PTRANSLATE_BUS_ADDRESS TranslateBusAddress;
  PGET_DMA_ADAPTER GetDmaAdapter;
  PGET_SET_DEVICE_DATA SetBusData;
  PGET_SET_DEVICE_DATA GetBusData;
} BUS_INTERFACE_STANDARD, *PBUS_INTERFACE_STANDARD;

Members

Size

Indicates the size, in bytes, of this structure.

Version

Indicates the driver-defined interface version.

Context

Pointer to interface-specific context information.

InterfaceReference

Pointer to a routine that increments the interface's reference count.

InterfaceDereference

Pointer to a routine that decrements the interface's reference count.

TranslateBusAddress

Pointer to a routine of type PTRANSLATE_BUS_ADDRESS that translates addresses on the parent bus to logical addresses.

GetDmaAdapter

Pointer to a routine of type PGET_DMA_ADAPTER that returns a DMA adapter structure (DMA_ADAPTER) for the target device.

SetBusData

Pointer to a routine of type PGET_SET_DEVICE_DATA that writes data to the device's configuration space.

GetBusData

Pointer to a routine of type PGET_SET_DEVICE_DATA that reads data from the device's configuration space.

Headers

Declared in ntddk.h. Include ntddk.h.

Comments

BUS_INTERFACE_STANDARD is an extension of the INTERFACE structure. For a description of the function prototypes of members InterfaceReference and InterfaceDereference, see the reference page for the INTERFACE structure.

Some operations on a device are reserved for the device's parent bus driver. Such operations might include accessing the device-specific configuration space of a bus, or programming a DMA controller.

To read from or write to a device's configuration space, a device driver must rely on the agency of the bus driver in either of two ways:

• By sending I/O request packets (IRPs) IRP_MN_READ_CONFIG and IRP_MN_WRITE_CONFIG to the bus driver.
• By obtaining an interface from the bus driver. The device driver can then access its device's configuration space by making direct calls to the bus driver routines provided by the interface. BUS_INTERFACE_STANDARD is such an interface, and its member routines, GetBusData and SetBusData, can be used to read from and write to a device's configuration space respectively.

For more information on the methods of access configuration space, see Accessing Device Configuration Space.

Some devices, such as bus-mastering storage devices, have on-board DMA controllers, but the device drivers for these devices can not program these DMA controllers directly. Instead they must rely on routines provided by the parent bus driver. For a device driver to program the DMA controller for its device, it must first request an adapter object from the parent bus driver. The adapter object contains the routines supplied by the bus driver that can be used to program the device's DMA controller. Device drivers must rely on the BUS_INTERFACE_STANDARD, either directly or indirectly, to obtain the adapter object.

If the driver is executing at IRQL = PASSIVE_LEVEL should obtain a device's DMA adapter object by calling IoGetDmaAdapter. IoGetDmaAdapter detects whether the bus driver supports the BUS_INTERFACE_STANDARD interface, and if it does, IoGetDmaAdapter calls the routine pointed to by the GetDmaAdapter member of this interface to obtain the adapter object. Otherwise, IoGetDmaAdapter calls an equivalent legacy routine.

However, if a driver must obtain an adapter object while running at IRQL >= DISPATCH_LEVEL, it cannot do so with IoGetDmaAdapter. In such a case, the driver must query for the BUS_INTERFACE_STANDARD interface while still at IRQL = PASSIVE_LEVEL using IRP_MN_QUERY_INTERFACE. The driver can then call the interface routine pointed to by GetDmaAdapter directly while running at IRQL >= DISPATCH_LEVEL.

See Also

IoGetDmaAdapter, DEVICE_DESCRIPTION, DMA_ADAPTER, IRP_MN_QUERY_INTERFACE, INTERFACE, IRP_MN_READ_CONFIG, IRP_MN_WRITE_CONFIG