PFREE_ADAPTER_OBJECT callback function (wdm.h)
The FreeAdapterObject routine releases the specified adapter object after a driver has completed all DMA operations.
Syntax
PFREE_ADAPTER_OBJECT PfreeAdapterObject;
void PfreeAdapterObject(
[in] PDMA_ADAPTER DmaAdapter,
[in] IO_ALLOCATION_ACTION AllocationAction
)
{...}
Parameters
[in] DmaAdapter
A pointer to a DMA_ADAPTER structure. This structure is the adapter object that is to be released. This object represents the driver's bus-master DMA device or system DMA channel. The caller obtained this pointer from a previous call to the IoGetDmaAdapter routine.
[in] AllocationAction
The type of deallocation that the calling driver requests. Set this parameter to an IO_ALLOCATION_ACTION enumeration value. For more information, see the Remarks section.
Return value
None
Remarks
FreeAdapterObject is not a system routine that can be called directly by name. This routine can be called only by pointer from the address returned in a DMA_OPERATIONS structure. Drivers obtain the address of this routine by calling IoGetDmaAdapter with the Version member of the DeviceDescription parameter set to DEVICE_DESCRIPTION_VERSION3. If IoGetDmaAdapter returns NULL, the routine is not available on your platform.
If AllocationAction = DeallocateObject, the FreeAdapterObject call releases the adapter object, and releases any map registers that might be allocated for this object.
If AllocationAction = DeallocateObjectKeepRegisters, the FreeAdapterObject call releases the adapter object, but does not release any map registers. In this case, the driver must explicitly release any allocated map registers by calling the FreeMapRegisters routine.
If AllocationAction = KeepObject, the FreeAdapterObject call has no effect.
FreeAdapterObject can be used to deallocate DMA resources that are allocated by calls to the AllocateAdapterChannelEx, GetScatterGatherListEx, and BuildScatterGatherListEx routines. If the driver calls one of these routines synchronously, the ExecutionRoutine parameter is optional and can be omitted. In this case, the driver can use the adapter object and map registers that are allocated by the call. After the driver initiates the DMA transfer, the driver can call FreeAdapterObject to deallocate the adapter object and, if necessary, the map registers.
The FreeAdapterChannel routine is similar to FreeAdapterObject. FreeAdapterChannel always releases the adapter object and any allocated map registers. This behavior is similar to that of FreeAdapterObject if AllocationAction = DeallocateObject.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Available starting with Windows 8. |
| Target Platform | Desktop |
| Header | wdm.h (include Wdm.h, Ntddk.h, Ntifs.h) |
| IRQL | <= DISPATCH_LEVEL |