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