VideoPortSynchronizeExecution

BOOLEAN VideoPortSynchronizeExecution(

PVOID  HwDeviceExtension,
VIDEO_SYNCHRONIZE_PRIORITY  Priority,
PMINIPORT_SYNCHRONIZE_ROUTINE  SynchronizeRoutine,
PVOID  Context	/* optional */
);

VideoPortSynchronizeExecution synchronizes the execution of a miniport-supplied HwVidSynchronizeExecutionCallback function with the miniport’s HwVidInterrupt function, if any. Otherwise, it runs HwVidSynchronizeExecutionCallback at a raised priority.

Parameters

HwDeviceExtension

Points to the miniport driver’s device extension.

Priority

Specifies the type of priority at which the given SynchronizeRoutine must be run, as one of the following:

• If Priority is set to VpLowPriority, the current thread is raised to the highest noninterrupt-masking priority. Accordingly, the current thread can be preempted only by an ISR if a device interrupts.

• If Priority is set to VpMediumPriority and the miniport has an ISR associated with its video adapter, the call to the given SynchronizeRoutine is synchronized with the miniport’s HwVidInterrupt function. Otherwise, synchronization is made at VpHighPriority level.

• If Priority is set to VpHighPriority, the hardware priority for the SynchronizeRoutine is raised to effectively mask out all interrupts in the system. VpHighPriority (and VpMediumPriority from a miniport without a HwVidInterrupt function) should not be specified unless absolutely necessary. If either is, the given SynchronizeRoutine must return control as quickly as possible. Delays can hang the entire system.

SynchronizeRoutine

Points to the miniport’s HwVidSynchronizeExecutionCallback function.

Context

Points to a caller-supplied context to be passed to the miniport’s HwVidSynchronizeExecutionCallback function. This pointer can be NULL.

Return Value

If the operation succeeds, VideoPortSynchronizeExecution returns TRUE.

Comments

Miniport drivers seldom call this routine unless either of the following conditions hold:

• The driver’s HwVidInterrupt function shares memory with other miniport functions. In order to access the shared memory in a multiprocessor-safe way, such miniport functions must call VideoPortSynchronizeExecution with HwVidSynchronizeExecutionCallback. This miniport function can safely access the shared memory because the video port driver prevents the HwVidInterrupt function from accessing the same memory concurrently.

• The adapter must be programmed with a sequence of commands without being subject to a context switch. For example, a miniport’s SvgaHwIoPortXxx function that has buffered a sequence of I/O instructions and validated the sequence might call VideoPortSynchronizeExecution with HwVidSynchronizeExecutionCallback. This miniport function can transfer the buffered and validated I/O stream to the adapter very quickly.

A caller should specify the lowest practical Priority value for the work HwVidSynchronizeExecutionCallback must do. Any CallbackRoutine that is run at a high hardware priority (VpMediumPriority or VpHighPriority) should return control as quickly as possible. A driver with such a high-priority HwVidSynchronizeExecutionCallback function should be designed to do as much work as possible in every other driver function except its HwVidSynchronizeExecutionCallback and/or HwVidInterrupt function(s).

See Also

HwVidInterrupt, HwVidSynchronizeExecutionCallback, SvgaHwIoPortXxx