VideoPortSetTrappedEmulatorPorts function (video.h)
VGA-compatible (SVGA) miniport drivers call the VideoPortSetTrappedEmulatorPorts function to dynamically change the list of I/O ports that are trapped when a VDM (video display monitor) runs in full-screen mode on an x86-based machine.
Syntax
VIDEOPORT_DEPRECATED VIDEOPORT_API VP_STATUS VideoPortSetTrappedEmulatorPorts(
PVOID HwDeviceExtension,
ULONG NumAccessRanges,
[in] PVIDEO_ACCESS_RANGE AccessRange
);
Parameters
HwDeviceExtension
Pointer to the miniport driver's device extension.
NumAccessRanges
Specifies the number of elements in the AccessRange array.
[in] AccessRange
Pointer to an array of VIDEO_ACCESS_RANGE elements. Each element describes a proper subrange of the EmulatorAccessEntries that the miniport driver set up in VIDEO_PORT_CONFIG_INFO. Setting the RangeVisible member of an AccessRange element to TRUE enables direct access to the I/O port range by the full-screen MS-DOS application. Setting a RangeVisible member to FALSE causes application-issued INs, INSB/INSW/INSDs, OUTs and/or OUTSB/OUTSW/OUTSDs to that range to be trapped and forwarded to the corresponding miniport driver SvgaHwIoPortXxx function for validation.
The AccessRange array passed to VideoPortSetTrappedEmulatorPorts must be a proper subset of the I/O port range(s) that the HwVidFindAdapter function set up in the EmulatorAccessEntries array of the VIDEO_PORT_CONFIG_INFO structure. Any I/O port ranges in the access ranges array that are not included in the EmulatorAccessEntries array are trapped and reflected to the user-mode VDD.
Return value
VideoPortSetTrappedEmulatorPorts returns NO_ERROR if it successfully changed the trapped ports. Otherwise, it returns ERROR_INVALID_PARAMETER.
Remarks
By default, the AccessRange of I/O ports that full-screen MS-DOS applications can access directly includes none of the access range array elements describing I/O port ranges that also have corresponding elements in the EmulatorAccessEntries array of the VIDEO_PORT_CONFIG_INFO structure. That is, I/O port ranges with corresponding emulator access entries are, by default, hooked to the miniport driver's SvgaHwIoPortXxx functions so application-issued instructions are forwarded to the SvgaHwIoPortXxx functions for validation.
A VGA-compatible SVGA miniport driver can enable and disable ranges of I/O ports on an as-needed basis with calls to VideoPortSetTrappedEmulatorPorts. Enabled port ranges allow a full-screen MS-DOS application to access those I/O ports directly, without having application-issued assembly instructions trapped and forwarded to the miniport driver's SvgaHwIoPortXxx functions for validation first. Direct I/O port access for such an application gives the user faster video I/O response times.
VideoPortSetTrappedEmulatorPorts scans the AccessRange parameter array from the first element to the last, enabling and disabling I/O ports as directed in each element. Note that a range of enabled ports (the RangeVisible member set to TRUE) can be disabled again in the same call if the miniport driver includes a duplicate description of the same range with the RangeVisible member set to FALSE. Note also that a miniport driver can enable a wide range of I/O ports in the initial element of the AccessRange array and selectively disable subranges of ports in subsequent array elements when it calls VideoPortSetTrappedEmulatorPorts.
All full-screen MS-DOS applications use the same IOPM (I/O permission map) in x86-based machines and, therefore, the same set of enabled or disabled I/O ports. On each switch to such a full-screen application, a VGA-compatible miniport driver's HwVidStartIO function is called with the IOCTL_VIDEO_ENABLE_VDM VRP. The miniport driver should then reinitialize a default set of directly accessible I/O ports, which can include any ports in the EmulatorAccessEntries array.
While giving full-screen MS-DOS applications on x86-based machines direct access to the video ports makes application-initiated video operations faster, every VGA-compatible SVGA miniport driver must continue to trap a subset of critical I/O ports to prevent such an application from hanging the machine. In particular, such miniport drivers should always trap application I/O to the VGA-compatible adapter sequencer and miscellaneous output registers. Such a miniport driver should also trap and validate application-issued direct I/O that could cause the machine to hang for any additional adapter-dependent subset of I/O ports.
Calling VideoPortSetTrappedEmulatorPorts again and resetting the RangeVisible member of an AccessRange element to FALSE causes the application-issued instructions for that range to be forwarded to the corresponding miniport driver SvgaHwIoPortXxx function.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Available in Windows 2000 and later versions of the Windows operating systems. |
| Target Platform | Desktop |
| Header | video.h (include Video.h) |
| Library | Videoprt.lib |
| DLL | Videoprt.sys |
| IRQL | PASSIVE_LEVEL |