FreeAdapterObject routine

The FreeAdapterObject routine releases the specified adapter object after a driver has completed all DMA operations.

Syntax


VOID FreeAdapterObject(
  _In_ PDMA_ADAPTER         DmaAdapter,
  _In_ IO_ALLOCATION_ACTION AllocationAction
);

Parameters

DmaAdapter [in]

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.

AllocationAction [in]

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

Target platform

Desktop

Version

Available starting with Windows 8.

Header

Wdm.h (include Wdm.h, Ntddk.h, or Ntifs.h)

IRQL

<= DISPATCH_LEVEL

See also

AdapterControl
AdapterListControl
AllocateAdapterChannel
AllocateAdapterChannelEx
BuildScatterGatherListEx
DMA_ADAPTER
DMA_OPERATIONS
FreeAdapterChannel
FreeMapRegisters
GetScatterGatherListEx
IO_ALLOCATION_ACTION
IoGetDmaAdapter

 

 

Send comments about this topic to Microsoft

Show:
© 2015 Microsoft