VideoPortStartDma function (video.h)

Article
10/21/2021

The VideoPortStartDma function prepares the system for a DMA operation. As soon as the appropriate resource is available, VideoPortStartDma creates a scatter/gather list, initializes the system resources, and calls the video miniport driver-supplied HwVidExecuteDma routine to carry out the DMA operation.

Syntax

VIDEOPORT_DEPRECATED VIDEOPORT_API VP_STATUS VideoPortStartDma(
  [in]      IN PVOID           HwDeviceExtension,
  [in]      IN PVP_DMA_ADAPTER VpDmaAdapter,
  [in]      IN PVOID           Mdl,
  [in]      IN ULONG           Offset,
  [in, out] IN OUT PULONG      pLength,
  [in]      IN PEXECUTE_DMA    ExecuteDmaRoutine,
  [in]      IN PVOID           Context,
  [in]      IN BOOLEAN         WriteToDevice
);

Parameters

[in] HwDeviceExtension

Pointer to the miniport driver's device extension.

[in] VpDmaAdapter

Pointer to the VP_DMA_ADAPTER structure that represents the bus-master adapter. This structure is returned from a call to VideoPortGetDmaAdapter.

[in] Mdl

Pointer to the MDL that describes the buffer. This pointer is returned from a call to the video port driver's VideoPortLockBuffer function.

[in] Offset

Specifies the byte offset in the buffer at which the DMA operation begins. The Mdl parameter describes this buffer.

[in, out] pLength

Pointer to a variable that specifies the requested transfer size, in bytes, and that will receive the actual size to be transferred. The variable will be updated when either of the following events occurs: VideoPortStartDma returns or HwVidExecuteDma is called. It is therefore safe to read this variable from within HwVidExecuteDma even before VideoPortStartDma returns.

[in] ExecuteDmaRoutine

Pointer to a miniport driver-supplied HwVidExecuteDma callback routine. VideoPortStartDma calls this routine to program the hardware registers and start the actual DMA operation.

[in] Context

Pointer to the driver-determined context to be passed to the miniport driver's HwVidExecuteDma callback routine. Since the HwVidExecuteDma callback routine runs at DISPATCH_LEVEL, the data that Context points to should be in nonpaged memory.

[in] WriteToDevice

Specifies the direction of the DMA transfer. A value of TRUE denotes a transfer from the buffer to the device, and a value of FALSE denotes a transfer from the device to the buffer.

Return value

VideoPortStartDma returns one of the following status codes:

Return code	Description
NO_ERROR	The operation was successfully carried out.
ERROR_NOT_ENOUGH_MEMORY	There are not enough system resources for this operation.

Remarks

To prepare for a DMA-transfer operation, VideoPortStartDma:

Flushes the memory region in the host processor's caches.
Builds a scatter/gather list.
Calls the video miniport driver's HwVidExecuteDma callback.

It is possible that not all of the requested data has been transferred, since the actual amount of memory transferred is limited by the number of map registers available to the driver. Callers of this function should inspect the actual transfer size returned at pLength to determine whether additional data remains to be transferred. If so, the miniport driver should call VideoPortStartDma (and subsequently, VideoPortCompleteDma) as many times as necessary to fulfill the entire transfer request.

Requirements

Requirement	Value
Minimum supported client	Available in Windows XP and later versions of the Windows operating systems.
Target Platform	Desktop
Header	video.h (include Video.h)
Library	Videoprt.lib
DLL	Videoprt.sys
IRQL	<=DISPATCH_LEVEL