VideoPortGetAccessRanges

VP_STATUS VideoPortGetAccessRanges(

VideoPortGetAccessRanges retrieves bus-relative configuration information and, if possible, claims these hardware resources in the registry for the caller.

Parameters

HwDeviceExtension

Points to the miniport driver's device extension.

NumRequestedResources

Specifies the number of elements in the RequestedResources array, described next.

RequestedResources

An array of IO_RESOURCE_DESCRIPTOR-type elements. Each descriptor specifies a single hardware resource that the miniport needs, prefers, or can use as an alternative to that specified in another array element. For detailed information about this structure, see the description of IoAssignResources.

NumAccessRanges

Specifies the number of elements in the AccessRanges array, described next.

AccessRanges

Points to an area on the stack or to a static structure in the miniport driver to which VideoPortGetAccessRanges returns an array of ACCESS_RANGE-type elements filled with the bus-relative device memory ranges for the adapter.

VendorId

Should be set to NULL if the adapter is not a PCI device. Otherwise, this points to a USHORT-type value, allocated by the PCI SIG, that identifies the manufacturer of the adapter.

DeviceId

Should be set to NULL if the adapter is not a PCI device. Otherwise, this points to a USHORT value that identifies a particular PCI video adapter model. This value is assigned by the manufacturer.

Slot

Points to a variable specifying the logical slot number or location of the adapter, depending on the type of bus. For a PCI adapter, Slot points to a PCI_SLOT_NUMBER structure that locates the adapter on the PCI bus on return from VideoPortGetAccessRanges.

Return Value

VideoPortGetAccessRanges returns NO_ERROR if it successfully filled in the AccessRanges information or returned configuration information at RequestedResources.

Comments

VideoPortGetAccessRanges can be called only from a miniport's HwVidFindAdapter function.

For most miniport drivers, VideoPortGetAccessRanges can retrieve, verify, and claim the bus-relative access ranges and any interrupt and/or DMA channel/port used by a particular video adapter, while VideoPortVerifyAccessRanges can only verify and claim miniport-specified resources. That is, for all configuration information that it returns, VideoPortGetAccessRanges claims the corresponding hardware resources in the registry for the caller. A miniport driver need not call VideoPortVerifyAccessRanges with the returned bus-relative configuration information, unless the miniport driver attempts to modify any of the returned values.

Each successful call to VideoPortGetAccessRanges or VideoPortVerifyAccessRanges for a particular adapter overwrites the miniport's preceding claim on hardware resources in the registry.

After a successful call to VideoPortGetAccessRanges, the miniport driver must map the returned bus-relative ranges to logical ranges with VideoPortGetDeviceBase before calling the appropriate VideoPortRead/WriteXxx function to communicate with the adapter.

Usually, the miniport driver of a PCI device should have its HwVidFindAdapter function call VideoPortGetAccessRanges, rather than attempting to manipulate the nondevice-specific PCI_COMMON_CONFIG information returned by a call to VideoPortGetBusData. Such a driver generally can call VideoPortGetAccessRanges with a NULL RequestedResources pointer. The video port driver then uses the PCI bus's configuration space to determine the resources for the video adapter. Such a miniport can call VideoPortGetAccessRanges with a set of driver-supplied RequestedResources specifications if its original call fails to return valid configuration data for the adapter.

Note that miniport drivers of adapters on other types of I/O buses also can call VideoPortGetAccessRanges. These drivers should call VideoPortGetAccessRanges with a RequestedResources pointer to a driver-supplied array of I/O resource descriptors.

If the HwVidFindAdapter function claims bus-relative access ranges and possibly other hardware resources for an adapter but then determines that it does not support the adapter, the miniport driver must erase its claims on hardware resources in the registry by calling VideoPortGetAccessRanges or VideoPortVerifyAccessRanges with the NumAccessRanges parameter set to zero.

See Also

HwVidFindAdapter, IoAssignResources, PCI_COMMON_CONFIG, PCI_SLOT_NUMBER, VIDEO_PORT_CONFIG_INFO, VideoPortGetBusData, VideoPortGetDeviceBase, VideoPortSetBusData, VideoPortVerifyAccessRanges