The IoGetDmaAdapter routine returns a pointer to the DMA adapter structure for a physical device object.
_DMA_ADAPTER * IoGetDmaAdapter( PDEVICE_OBJECT PhysicalDeviceObject, _DEVICE_DESCRIPTION *DeviceDescription, PULONG NumberOfMapRegisters );
Pointer to the physical device object for the device requesting the DMA adapter structure.
Pointer to a DEVICE_DESCRIPTION structure, which describes the attributes of the physical device. Regardless of the version set in the DEVICE_DESCRIPTION structure, this function always returns
DMA_ADAPTER->Version == 1.
A pointer to, on output, the maximum number of map registers that the driver can allocate for any DMA transfer operation.
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. See version comment above in description of DeviceDescription parameter.
Before calling this routine, a driver must zero-initialize the DEVICE_DESCRIPTION structure pointed to by DeviceDescription and then add the relevant information for its device to this structure.
On success, the DmaOperations member of the routine's return value points to a DMA_ADAPTER structure. This structure contains a pointer to a DMA_OPERATIONS structure, which is a table of pointers to functions that the driver can subsequently use to perform DMA operations. The version of this structure that the routine returns is determined as follows:
- If the driver sets the Version member of the DEVICE_DESCRIPTION structure to DEVICE_DESCRIPTION_VERSION or DEVICE_DESCRIPTION_VERSION1, the returned DMA_ADAPTER structure points to version 1 of the DMA_OPERATIONS structure.
- If the driver sets Version = DEVICE_DESCRIPTION_VERSION2, the returned DMA_ADAPTER structure points to version 2 of the DMA_OPERATIONS structure if version 2 is supported; otherwise, the routine returns NULL. Drivers must check to see if version 2 is supported before attempting to use any version 2 function.
- If the driver sets Version = DEVICE_DESCRIPTION_VERSION3, the returned DMA_ADAPTER structure points to version 3 of the DMA_OPERATIONS structure if version 3 is supported; otherwise, the routine returns NULL. Drivers must check to see if version 3 is supported before attempting to use any version 3 function. Version 3 is supported starting with Windows 8.
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.
|Minimum supported client||Available starting with Windows 2000.|
|Header||wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)|
|DDI compliance rules||IrqlIoPassive5, PowerIrpDDis, HwStorPortProhibitedDDIs|