Skip to content

Latest commit

 

History

History
168 lines (124 loc) · 7.91 KB

nf-video-videoportmapmemory.md

File metadata and controls

168 lines (124 loc) · 7.91 KB
Raw
UID title description old-location tech.root ms.date keywords ms.keywords req.header req.include-header req.target-type req.target-min-winverclnt req.target-min-winversvr req.kmdf-ver req.umdf-ver req.ddi-compliance req.unicode-ansi req.idl req.max-support req.namespace req.assembly req.type-library req.lib req.dll req.irql targetos req.typenames f1_keywords topic_type api_type api_location api_name
NF:video.VideoPortMapMemory
VideoPortMapMemory function (video.h)
The VideoPortMapMemory function maps a range of bus-relative physical addresses of video memory into system space or into the virtual address space of a user-mode process.
display\videoportmapmemory.htm
display
05/10/2018
VideoPortMapMemory function
VideoPortMapMemory, VideoPortMapMemory function [Display Devices], VideoPort_Functions_53fef559-5fbb-4e9a-9152-b44be67bd63c.xml, display.videoportmapmemory, video/VideoPortMapMemory
video.h
Video.h
Desktop
Available in Windows 2000 and later versions of the Windows operating systems.
Videoprt.lib
Videoprt.sys
PASSIVE_LEVEL
Windows
VideoPortMapMemory
video/VideoPortMapMemory
APIRef
kbSyntax
DllExport
Videoprt.sys
VideoPortMapMemory

VideoPortMapMemory function

-description

The VideoPortMapMemory function maps a range of bus-relative physical addresses of video memory into system space or into the virtual address space of a user-mode process. A video miniport driver calls VideoPortMapMemory when it handles IOCTL_VIDEO_MAP_VIDEO_MEMORY, IOCTL_VIDEO_SHARE_VIDEO_MEMORY, or IOCTL_VIDEO_QUERY_PUBLIC_ACCESS_RANGES.

-parameters

-param HwDeviceExtension

Pointer to the miniport driver's device extension.

-param PhysicalAddress

The bus-relative base address of the range to map.

-param Length

On input, specifies the number of bytes of video memory to map. On output, receives the size of the memory actually mapped, which might be rounded to a system-determined alignment boundary. (However, the miniport and display drivers cannot access any memory that is outside the range delimited by the input value at Length.)

-param InIoSpace

Pointer to a variable that indicates the location of the range. The variable can be one of the following flags or an ORed, compatible combination of these flags.

Flag Meaning
VIDEO_MEMORY_SPACE_DENSE Obsolete.
VIDEO_MEMORY_SPACE_IO The address range is in I/O space, not in memory space.
VIDEO_MEMORY_SPACE_MEMORY The address range is in memory space, not in I/O space.
VIDEO_MEMORY_SPACE_P6CACHE The processor aggregates a sequence of write operations, sends them to a cache line, and later flushes the cache. This flag is meaningful only if VIDEO_MEMORY_SPACE_IO is not set.
Designates the video memory as write-combined (WC). For information about WC caching, see the Write-Combining Memory in Video Miniport Drivers website article.
VIDEO_MEMORY_SPACE_USER_MODE The address range should be mapped into the virtual address space of a user-mode process, not into system space. This flag is meaningful only if VIDEO_MEMORY_SPACE_IO is not set.

-param VirtualAddress

Pointer to a variable that, on input, is either NULL or a handle to a user-mode process. If the input value is NULL, this routine maps the video memory into system space. Otherwise, this routine maps the video memory into the virtual address space of the user-mode process that is identified by the handle. On output, receives the base virtual address of the mapping.

-returns

VideoPortMapMemory returns NO_ERROR if it successfully mapped the specified range; otherwise, it returns ERROR_INVALID_PARAMETER.

-remarks

VideoPortMapMemory runs in kernel mode within the same context as the user-mode thread that initiated the call.

VideoPortGetDeviceBase and VideoPortMapMemory can both be called by the video miniport driver to map video memory into a virtual address space. If you call both of these functions to map the same physical addresses, or if you call one of the functions more than once to map the same physical addresses, you might have more than one virtual-address range that maps to the same physical-address range. In that case, you must set the VIDEO_MEMORY_SPACE_P6CACHE flag of the InIoSpace parameter to the same value in all of those calls.

Every universal memory architecture (UMA) display device uses a frame buffer that is located in main memory rather than on a PCI bus. In this case, do not call VideoPortMapMemory to map the frame buffer. To map a UMA frame buffer into system space, call MmMapIoSpace. To map a UMA frame buffer into the virtual address space of a user-mode process, perform the following steps:

  1. Call ZwOpenSection to get a handle to the operating system's physical-memory section object, which is named \Device\PhysicalMemory.
  2. Call ZwMapViewOfSection to map a view of the frame buffer into the virtual address space of the current process.
The following example shows how to map a UMA frame buffer into the virtual address space of the current process. 
UNICODE_STRING    UnicodeString;          // Name of the section object
OBJECT_ATTRIBUTES ObjectAttributes;       // Description for the section object
HANDLE            hPhysicalMemoryHandle;  // Handle to the section object
PHYSICAL_ADDRESS  MappedLength;           // Length of the frame buffer

PHYSICAL_ADDRESS  MappedBase;             // Base physical address (CPU-relative)
                                          // of the frame buffer

// Allocate a variable to receive the base virtual address of the view.
// Set it to NULL for input to ZwMapViewOfSection, to specify that the memory
// manager (rather than the caller) should determine the base virtual address.
PVOID pViewBase = NULL;

RtlInitUnicodeString(&UnicodeString, L"\\Device\\PhysicalMemory");

InitializeObjectAttributes(
   &ObjectAttributes,
   &UnicodeString,
   OBJ_CASE_INSENSITIVE | OBJ_KERNEL_HANDLE,
   (HANDLE) NULL,
   (PSECURITY_DESCRIPTOR) NULL);

// Open a handle to the physical-memory section object.
ntStatus = ZwOpenSection(&hPhysicalMemoryHandle, SECTION_ALL_ACCESS, &ObjectAttributes);

if(NT_SUCCESS(ntStatus))
{
   ntStatus = ZwMapViewOfSection(
      hPhysicalMemoryHandle,
      NtCurrentProcess(),
      &pViewBase,
      0L,
      (ULONG_PTR)MappedLength.QuadPart,
      &MappedBase,
      (PULONG_PTR)(&(MappedLength.QuadPart)),
      ViewUnmap,
      0,
      PAGE_READWRITE | PAGE_WRITECOMBINE);

   if(NT_SUCCESS(ntStatus))
   {
      // pViewBase holds the base virtual address of the view.
   }

   // Close the handle to the physical-memory section object.
   ZwClose(hPhysicalMemoryHandle);
}

Miniport drivers should use VideoPortMapMemory to manage video adapters that allow the video frame buffer to be completely mapped at all times. That is, miniport drivers for adapters that are not restricted to using banks to map a slice at a time can use the more efficient VideoPortMapMemory.

-see-also

IOCTL_VIDEO_MAP_VIDEO_MEMORY

VIDEO_REQUEST_PACKET

VideoPortUnmapMemory