FlushAdapterBuffersEx

FlushAdapterBuffersEx routine

The FlushAdapterBuffersEx routine flushes any data that remains in the data cache at the end of a DMA transfer operation performed by a system DMA controller or bus-master device.

Syntax


NTSTATUS FlushAdapterBuffersEx(
  _In_ PDMA_ADAPTER DmaAdapter,
  _In_ PMDL         Mdl,
  _In_ PVOID        MapRegisterBase,
  _In_ ULONGLONG    Offset,
  _In_ ULONG        Length,
  _In_ BOOLEAN      WriteToDevice
);

Parameters

DmaAdapter [in]

A pointer to a DMA_ADAPTER structure. This structure is the adapter object that represents the driver's system DMA channel or bus-master device. The caller obtained this pointer from a previous call to the IoGetDmaAdapter routine.

Mdl [in]

A pointer to the MDL chain that describes the pages of memory that are to be flushed. Set this parameter to point to the MDL chain that was used for the DMA transfer. For more information, see the description of the Mdl parameter in GetScatterGatherListEx, BuildScatterGatherListEx, or MapTransferEx.

MapRegisterBase [in]

A handle to the map registers that were previously allocated for the adapter object.

Offset [in]

The starting offset relative to the start of the MDL chain to use for the flush operation. Set this parameter to the value that was used as the starting offset for the DMA transfer. For more information, see the description of the Offset parameter in GetScatterGatherListEx, BuildScatterGatherListEx, or MapTransferEx.

Length [in]

The number of bytes of data to flush. Set this parameter to the value that was used as the transfer length for the DMA transfer. For more information, see the description of the Length parameter in GetScatterGatherListEx, BuildScatterGatherListEx, or MapTransferEx.

WriteToDevice [in]

The direction of the DMA transfer. Set this parameter to the value that was used as the transfer direction for the DMA transfer. For more information, see the description of the WriteToDevice parameter in GetScatterGatherListEx, BuildScatterGatherListEx, or MapTransferEx.

Return value

FlushAdapterBuffersEx returns STATUS_SUCCESS if the call is successful. Possible error return values include the following status codes.

Return codeDescription
STATUS_INVALID_PARAMETERS

The routine failed due to invalid parameter values passed by the caller.

 

Remarks

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

FlushAdapterBuffersEx enables processor cache coherency in hardware platforms that do not implement hardware-enforced cache coherency (bus snooping). In addition, for a system DMA transfer, FlushAdapterBuffersEx flushes any data that remains in the system DMA controller's internal cache.

The driver that initiates a scatter/gather DMA transfer must ensure that all of the transferred data is flushed from the cache after the transfer completes. The driver should call FlushAdapterBuffersEx before the driver completes the IRP that requested the DMA transfer, and before the driver frees the map registers. For more information, see Flushing Cached Data during DMA Operations.

FlushAdapterBuffersEx is an extended version of the FlushAdapterBuffers routine. FlushAdapterBuffersEx can flush an entire scatter/gather list in one call. In contrast, to use FlushAdapterBuffers to flush a scatter/gather list requires a separate call for each MDL in the MDL chain.

FlushAdapterBuffersEx can be used in place of FlushAdapterBuffers to flush the buffer for a one-packet DMA transfer. In this case, the MDL chain that the Mdl parameter points to contains only one MDL. A benefit of using FlushAdapterBuffersEx in this way is that the caller can specify an offset into the MDL.

If FlushAdapterBuffersEx is called before the DMA transfer operation finishes, this call might cancel the transfer before it can finish or might cause undefined behavior.

Requirements

Target platform

Version

Available starting with Windows 8.

Header

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

IRQL

<= DISPATCH_LEVEL

See also

BuildScatterGatherListEx
DMA_ADAPTER
DMA_OPERATIONS
FlushAdapterBuffers
GetScatterGatherListEx
IoGetDmaAdapter
MapTransferEx

 

 

Send comments about this topic to Microsoft

Show:
© 2016 Microsoft