VirtualCopy (Windows CE 5.0)

  • Article

Send Feedback

This function dynamically maps a virtual address to a physical address by creating a new page-table entry. Terminate the mapping by calling VirtualFree.

BOOL VirtualCopy( LPVOID lpvDest, LPVOID lpvSrc, DWORD cbSize, DWORD fdwProtect );

Parameters

  • lpvDest
    [in] Pointer to the destination memory, which must be reserved.
  • lpvSrc
    [in] Pointer to committed memory.
  • cbSize
    [in] Size, in bytes, of the region. The allocated pages include all pages containing one or more bytes in the range from lpAddress to lpAddress+cbSize. This means that a 2-byte range straddling a page boundary causes both pages to be included in the allocated region.
  • fdwProtect
    [in] Type of access protection. If the pages are being committed, any one of a number of flags can be specified, along with the PAGE_GUARD and PAGE_NOCACHE, protection modifier flags. The following table shows the flags that can be specified.
    Value Description
    PAGE_READONLY Enables read access to the committed region of pages. An attempt to write to the committed region results in an access violation. If the system differentiates between read-only access and execute access, an attempt to execute code in the committed region results in an access violation.
    PAGE_READWRITE Enables both read and write access to the committed region of pages.
    PAGE_EXECUTE Enables execution access to the committed region of pages. An attempt to read or write to the committed region results in an access violation.
    PAGE_EXECUTE_READ Enables execute and read access to the committed region of pages. An attempt to write to the committed region results in an access violation.
    PAGE_EXECUTE_READWRITE Enables execute, read, and write access to the committed region of pages.
    PAGE_GUARD Pages in the region become guard pages. Any attempt to read from or write to a guard page causes the operating system to raise the STATUS_GUARD_PAGE exception and turn off the guard page status. Guard pages thus act as a one-shot access alarm.

    The PAGE_GUARD flag is a page protection modifier. An application uses it with one of the other page protection flags, with one exception: it cannot be used with PAGE_NOACCESS.

    When an access attempt leads the operating system to turn off guard page status, the underlying page protection takes over.

    If a guard page exception occurs during a system service, the service typically returns a failure status indicator.
    PAGE_NOACCESS Disables all access to the committed region of pages. An attempt to read from, write to, or execute in the committed region results in an access violation exception, called a general protection (GP) fault.
    PAGE_NOCACHE Allows no caching of the committed regions of pages. The hardware attributes for the physical memory should be specified as no cache. It is useful for device drivers; when, for example, mapping a video frame buffer with no caching. This flag is a page protection modifier and is valid only when used with one of the page protections other than PAGE_NOACCESS.
    PAGE_PHYSICAL Used to map a physical memory region. When using this flag, divide the physical address — that is, lpvSrc — by 256. Memory mapped with PAGE_PHYSICAL is not freed until the device is rebooted. Calling VirtualFree will not free this mapped physical memory. PAGE_PHYSICAL is intended for use with dedicated hardware buffers, so it cannot be freed after being mapped.

Return Values

TRUE indicates success; FALSE indicates failure. To obtain extended error information, call GetLastError.

Remarks

The virtual page offset and physical page offset must be the same because one virtual page can only be mapped to one physical page. For example, consider the following invalid call to VirtualCopy:

VirtualCopy (0x50000, 0xC00DA800, 0x1000, . . .);

The virtual to physical mapping requested are as follows:

(0x50000, 0x50800) to (0xC0DA800, 0xC0DB000)

(0x50800, 0x51000) to (0xC0DB000, 0xC0DB800)

In the above example, the virtual page (0x50000, 0x51000) must be mapped to two different physical pages, (0xC00DA000) and (0xC00DB000), but virtual memory cannot support this scenario.

The following code example shows how VirtualCopy is called to map a 128-KB region at physical address 0x64000000.

VirtualCopy(pvDest,
  (void *)(0x64000000/256),
  128*1024,
  PAGE_READWRITE | PAGE_PHYSICAL | PAGE_NOCACHE
);

Drivers or applications that run in user mode must use this function, because user-mode threads do not have permission to access physical memory directly.

This function ensures that the operating system maps a mapped virtual address to the specific physical address of the registers or frame buffer it needs to read or write. Before the thread calls VirtualCopy, it must first obtain a virtual address by calling VirtualAlloc. VirtualAlloc and VirtualCopy must be called at the beginning of every device driver thread or application that must access peripheral registers. This sequence of function calls is available in the MmMapIoSpace function.

The following code example shows a user-mode driver thread. For more examples, see the sample device driver code provided with Platform Builder, located in the directory %_WINCEROOT%\Platform\%BSP%\Drivers and %_WINCEROOT%\Public\Common\OAK\Drivers.

#include <windows.h>

#define PHYSADDR  ((PVOID)0x10000000)
// PHYSADDR is the physical address of the peripheral
// registers

#define SIZE  (4800*4)

LPVOID lpv;
BOOL bRet;

lpv = VirtualAlloc(0, SIZE, MEM_RESERVE, PAGE_NOACCESS);
// For a user mode driver, always leave the first
// parameter 0 and use only the flags MEM_RESERVE
// and PAGE_NOACCESS Check the return value: lpv == 0
// is an error

printf(TEXT("VirtualAlloc reservation @%8.8lx\r\n"), lpv);
bRet = VirtualCopy(lpv, PHYSADDR>>8, SIZE, PAGE_READWRITE | PAGE_NOCACHE | PAGE_PHYSICAL);
// The lpv parameter is the virtual address returned
// by VirtualAlloc().
// Always use PAGE_NOCACHE */

// Check the return value: bRet ==0 is an error */
printf(TEXT("VirtualCopy returned: %d\r\n"), bRet);

// At this point lpv is a virtual address which maps
// the I/O registers
// at PHYSADDR for SIZE bytes */

The destination address defined by the lpvDest parameter must be an address range that has been reserved by a call to VirtualAlloc. VirtualAlloc, with the flags MEM_RESERVE and PAGE_NOACCESS and a size greater than or equal to 2 MB, is allocated outside the process virtual memory space. Otherwise, it is allocated inside the processes virtual memory space.

Requirements

OS Versions: Windows CE 2.10 and later.
Header: Pkfuncs.h.
Link Library: Coredll.lib.

See Also

CEL_VIRTUAL_COPY | CeLogData | HiveRAMRegion | MmMapIoSpace | NdisFlushBuffer | Trusted APIs | VirtualAlloc | VirtualFree

Send Feedback on this topic to the authors

Feedback FAQs

© 2006 Microsoft Corporation. All rights reserved.