IoGetDmaAdapter

The IoGetDmaAdapter routine returns a pointer to the DMA adapter structure for a physical device object.

PDMA_ADAPTER
  IoGetDmaAdapter(
    IN PDEVICE_OBJECT  PhysicalDeviceObject,
    IN PDEVICE_DESCRIPTION  DeviceDescription,
    IN OUT PULONG  NumberOfMapRegisters
    );

Parameters

PhysicalDeviceObject

Pointer to the physical device object for the device requesting the DMA adapter structure.

DeviceDescription

Pointer to a DEVICE_DESCRIPTION structure, which describes the attributes of the physical device.

NumberOfMapRegisters

Pointer to, on output, the maximum number of map registers that the driver can allocate for any DMA transfer operation.

Return Value

IoGetDmaAdapter returns a pointer to a DMA_ADAPTER structure, which contains pointers to functions that support system-defined DMA operations. If the structure cannot be allocated, the routine returns NULL.

Headers

Declared in wdm.h and ntddk.h. Include wdm.h or ntddk.h.

Comments

Before calling this routine, a driver must zero-initialize the structure passed at DeviceDescription and then supply the relevant information for its device.

On success, the DmaOperations member of the routine's return value points to a DMA_OPERATIONS structure, which is a table of pointers to functions that the driver can use to perform subsequent DMA operations. If the driver passes DEVICE_DESCRIPTION_VERSION or DEVICE_DESCRIPTION_VERSION1 in the Version member of the DeviceDescription parameter, IoGetDmaAdapter returns a pointer to version 1 of the DMA_OPERATIONS structure. If the driver passes DEVICE_DESCRIPTION_VERSION2, IoGetDmaAdapter returns version 2 of the table if version 2 is supported, otherwise it returns NULL. Drivers must check to see if version 2 is supported before attempting to use any version 2 function.

PnP drivers call IoGetDmaAdapter when handling a PnP IRP_MN_START_DEVICE request for a device. This IRP includes information about the device's hardware resources that the driver must supply in the DeviceDescription structure.

In NumberOfMapRegisters, the caller specifies the optimal number of map registers it can use. On output, the I/O Manager returns the number of map registers it allocated. Drivers should check the returned value; there is no guarantee a driver will receive the same number of map registers it requested.

To free the adapter object, the driver should call PutDmaAdapter through the pointer returned in the DMA_ADAPTER structure.

Drivers must call this routine while running at IRQL = PASSIVE_LEVEL.

See Also

DEVICE_DESCRIPTION, DMA_ADAPTER, PutDmaAdapter