VIDEO_ACCESS

VIDEO_ACCESS_RANGE

typedef struct _VIDEO_ACCESS_RANGE {
    PHYSICAL_ADDRESS RangeStart;
    ULONG RangeLength;
    UCHAR RangeInIoSpace;
    UCHAR RangeVisible;
    UCHAR RangeShareable;
} VIDEO_ACCESS_RANGE, *PVIDEO_ACCESS_RANGE;

VIDEO_ACCESS_RANGE defines a device I/O port or memory range for the video adapter. Every miniport’s HwVidFindAdapter function must set up an array of VIDEO_ACCESS_RANGE-type elements, called the access ranges array, for each video adapter the miniport supports.

For VGA-compatible miniport drivers, VIDEO_ACCESS_RANGE also defines an element in an array passed to VideoPortSetTrappedEmulatorPorts to enable or disable direct access to I/O ports by full-screen MS-DOS applications.

Members

RangeStart: Specifies the bus-relative base address of a memory or I/O port range for an element in the access ranges array passed to VideoPortVerifyAccessRanges or returned by VideoPortGetAccessRanges.
Specifies the bus-relative base address of an I/O port range for an array to be passed to VideoPortSetTrappedEmulatorPorts.
RangeLength: Specifies the number of I/O ports or size in bytes for the range.
RangeInIoSpace: Is set to TRUE (one) if the given range is in I/O space or to FALSE (zero) if the access range is in memory space.
RangeVisible: Is ignored if the miniport’s HwVidFindAdapter function is setting up the access ranges array.
Is set to TRUE by VGA-compatible miniport drivers and passed to VideoPortSetTrappedEmulatorPorts to enable direct access to the I/O port range by a full-screen MS-DOS application. If set to FALSE, application-issued instructions continue to be trapped and forwarded to the miniport’s SvgaHwIoXxx function for validation.
RangeShareable: Is set to TRUE if the access range described by this element can be shared with another driver and/or device or to FALSE if the range cannot be shared.
Is ignored by VideoPortSetTrappedEmulatorPorts.

Comments

A miniport’s HwVidFindAdapter function sets up the access ranges array for an adapter. It can use information returned by VideoPortGetBusData or VideoPortGetAccessRanges. As an alternative, it can use information retrieved from the registry by calling VideoPortGetDeviceData with a miniport-supplied HwVidQueryDeviceCallback function or VideoPortGetRegistryParameters with a miniport-supplied HwVidQueryNamedValueCallback function. If calling these VideoPortXxx does not supply the bus-relative access range values, HwVidFindAdapter can set up access ranges elements using driver-supplied bus-relative default values.

Claiming Access Ranges in the Registry

The miniport should call VideoPortVerifyAccessRanges with any access ranges obtained from VideoPortGetDeviceData, returned by VideoPortGetBusData, or supplied as defaults by the miniport. If VideoPortVerifyAccessRanges returns NO_ERROR for such an array of access ranges, the HwVidFindAdapter or HwVidQueryDeviceCallback function can then map the ranges with VideoPortGetDeviceBase and use the returned mapped logical addresses to access the adapter.

A successful call to VideoPortGetAccessRanges also claims the returned bus-relative access ranges in the registry for the caller. If the miniport driver modifies any of the returned values, it must call VideoPortVerifyAccessRanges with the full access range, including any unmodified elements. Each call to VideoPortGetAccessRanges or VideoPortVerifyAccessRanges for a particular video adapter overwrites the caller’s claimed hardware resources in the registry.

A miniport driver must not attempt to use a range for which VideoPortVerifyAccessRanges or VideoPortGetAccessRanges does not return NO_ERROR.

Mapping Access Ranges to Communicate with the Adapter

After a miniport driver has claimed resources in the registry for an adapter, it cannot use bus-relative addresses to access or configure the adapter, because the HAL can remap all bus-relative device addresses to system space, particularly in multibus machines.

The miniport’s HwVidFindAdapter function must call VideoPortGetDeviceBase to get mapped logical addresses for its access ranges. Only then can the miniport driver communicate with the video adapter by passing the returned mapped logical range addressess to the VideoPortRead/WritePortXxx to access device memory in I/O space and/or VideoPortRead/WriteRegisterXxx to access device memory in memory space.

Determining whether an Access Range is Shareable

Follow these guidelines to determine whether an access range can be shared:

If the range of memory or I/O ports should be “owned” by this driver, and/or access to this range by any other driver can cause a problem, set RangeShareable to FALSE.
If the range can be shared with a cooperating device driver, set RangeShareable to TRUE.

SVGA miniport drivers that implement all VGA functionality (declared in the registry as VgaCompatible set to one) should claim their access ranges as unshareable so the system VGA driver will not be loaded. On the other hand, miniports for adapters such as the S3 or the XGA, which set VgaCompatible to zero in the registry, should claim all the resources they share with the system VGA driver as shareable.

However, miniports for cards that work with a pass-through IOCTL and that can be connected to any VGA or SVGA card should not be using any system VGA ports or memory ranges. If they do, such a driver should not attempt to claim any of the VGA access ranges in the registry. Attempts to claim VGA resources by such a miniport driver are likely to cause a resource conflict because the driver of any SVGA card in the machine will have claimed these access ranges as unshareable.

Passing I/O Port Range Elements to VideoPortSetTrappedEmulatorPorts

All VIDEO_ACCESS_RANGE-type array elements describing I/O port ranges are assumed to be invisible, unless a VGA-compatible miniport driver in an x86-based machine explicitly resets the RangeVisible member(s) to TRUE and calls VideoPortSetTrappedEmulatorPorts to enable one or more I/O port ranges. VideoPortSetTrappedEmulatorPorts ignores the RangeShareable members of the input array.

In an array of VIDEO_ACCESS_RANGE-type elements passed to VideoPortSetTrappedEmulatorPorts, the value of each element’s RangeVisible member determines whether the given I/O port(s) can be accessed directly by the VDM (MS-DOS application running in full-screen on an x86-based machine) or whether such an application-issued I/O stream is trapped and forwarded to a miniport-supplied SvgaHwIoPortXxx function for validation first.