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,
    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

A 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.

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.

A PnP driver calls IoGetDmaAdapter when its AddDevice routine is called or when it handles 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.

The caller uses the MaximumLength member in the DeviceDescription structure to indicate the optimal number of map registers it can use. The I/O manager will attempt to allocate enough map registers to accommodate a DMA transfer operation of this maximum size. On output, the I/O manager returns, in the NumberOfMapRegisters parameter, the number of map registers that it allocates. 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.

Note  As previously described, IoGetDmaAdapter returns NULL if it does not support the version of the DMA_ADAPTER structure that is specified by DeviceDescription->Version. Callers should rely on this behavior to determine whether the routine returns a pointer to the requested version of the DMA_ADAPTER structure. When IoGetDmaAdapter returns a pointer to version 1 or version 2 of the DMA_ADAPTER structure, the Version member of this structure is always set to 1. Thus, the caller cannot use the Version member of the returned DMA_ADAPTER structure to distinguish between versions 1 and 2 of this structure.

Requirements

IRQL: PASSIVE_LEVEL

Headers: Declared in Wdm.h. Include Wdm.h, Ntddk.h, or Ntifs.h.

See Also

AddDevice, DEVICE_DESCRIPTION, DMA_ADAPTER, DMA_OPERATIONS, PutDmaAdapter