|
include vmm.inc VMMcall _PageAllocate, <nPages, pType, VM, AlignMask, minPhys, maxPhys, <OFFSET32 PhysAddr>, flags> mov ecx, eax ; zero in eax and edx if error or ecx, edx jz error mov [Handle], eax ; memory handle mov [Address], edx ; ring-0 address of memory block |
The _PageAllocate service allocates a block of memory consisting of the specified number of pages. This service reserves linear address space for the memory block, and depending on the value of the flags parameter, may also map the linear addresses to physical memory, locking the pages in memory. The service returns a memory handle that can be used in subsequent memory management functions to lock, unlock, reallocate, and free the memory block.
nPages
Specifies the number of pages to allocate for the memory block. This parameter must not be zero.
pType
Specifies the type of pages to allocate. It can be one of the following values:
| Value | Meaning |
| PG_HOOKED | Allocates pages that are mapped into the virtual machine at locations for which a page-fault handler has been installed. These pages are specific to a particular virtual machine. |
| PG_SYS | Allocates global system pages that are valid in all virtual machines. |
| PG_VM | Allocates pages that are specific to a particular virtual machine. The handle of PG_VM memory blocks will typically be placed in the virtual machine's control block. |
VM
Specifies a handle identifying the virtual machine for which to allocate the pages. This parameter applies to pages allocated using the PG_VM and PG_HOOKED values only. This parameter must be set to zero when using the PG_SYS value.
AlignMask
Specifies an alignment mask that defines acceptable starting page numbers for the memory block. This parameter can be one of the following values:
| Value | Meaning |
| 00000000h | Physical address is a multiple of 4K. |
| 00000001h | Physical address is a multiple of 8K. |
| 00000003h | Physical address is a multiple of 16K. |
| 00000007h | Physical address is a multiple of 32K. |
| 0000000Fh | Physical address is a multiple of 64K. |
| 0000001Fh | Physical address is a multiple of 128K. |
This parameter is used only if the flags parameter specifies the PageUseAlign value.
minPhys
Specifies the minimum acceptable physical page number in the memory block. All page numbers must be greater than or equal to this value. This parameter is used only if the flags parameter specifies the PageUseAlign value.
maxPhys
Specifies the maximum acceptable physical page number in the memory block. All page numbers must be less than this value. This parameter is used only if the flags parameter specifies the PageUseAlign value.
PhysAddr
Points to the four-byte buffer to receive the physical address of the start of the memory block. The service uses this parameter only if the flags parameter specifies the PageUseAlign value.
flags
Specifies the operation flags. This parameter can be a combination of the following values:
| Value | Meaning |
| PageContig | Allocates contiguous physical pages to create the memory block. This value is ignored if the PageUseAlign value is not also specified. |
| PageFixed | Locks the allocated pages in memory at a fixed linear address, and prevents the pages from subsequently being unlocked or moved. The service locks the memory block regardless of the type of virtual page swap device present. |
| PageLocked | Locks the allocated pages in the memory. The pages can be subsequently unlocked using the _PageUnLock service. The service locks the memory block regardless of the type of virtual page swap device present. |
| PageLockedIfDP | Locks the allocated pages in the memory only if the virtual page swap device uses MS-DOS or BIOS functions to write to the hardware. If the pages are locked, they can be subsequently unlocked using the _PageUnLock service. |
| A virtual device must not specify the PageLockedIfDP value until after it has received the Init_Complete message. | |
| The PageLocked and PageLockedIfDP values are mutually exclusive. | |
| PageMapFreePhysReg | Allocates a free physical region, which a virtual device may use to map physical pages that otherwise are placed in the system's free memory pool. The nPages parameter specifies the number of pages in the region. The pType parameter must be set to PG_SYS and the VM, AlignMask, minPhys, maxPhys, and PhysAddr parameters must be set to zero. A free physical region cannot be reallocated or freed; these regions exist for the duration of the Windows session. |
| This value is only available during initialization, and only in Windows version 3.1 or later. | |
| PageUseAlign | Allocates pages using the alignment and physical addresses specified by the AlignMask, minPhys, and maxPhys parameters. The PageUseAlign value is only available during initialization, and can only be used in combination with the PageFixed value. |
| PageZeroInit | Fills the memory block with zeros. If this value is not given, the contents of the memory block are undefined. |
All other values are reserved.
The EAX register contains the memory handle of the block, and the EDX register contains the ring-0 linear address of the memory block. Otherwise, the EAX and EDX registers both contain zero to indicate an error such insufficient memory to satisfy the request.
Unless the PageLocked, PageLockedIfDP, or PageFixed value is specified, this service allocates linear address space without mapping the addresses to physical memory. In this case, the system maps the physical page when the virtual device attempts to access an address in the address space. A virtual device can also use the _PageLock service to force this mapping.
Virtual devices use the PageUseAlign value to allocate buffers for use by the device which have additional alignment restrictions enforced by the hardware. For example, a DMA may require buffers to start at addresses that are a multiple of 64K or 128K. When allocating such buffers, the PageContig value is often used in combination with PageUseAlign.
The action specified by the PageLockedIfDP value is available only after the virtual page swap device has been initialized.
Virtual devices must never rely on apparent relationships between the memory handle and the ring-0, or physical address of a memory block.
All pages in the free physical region are initially not present. Virtual devices use the MapFreePhysReg service to map physical pages into the region and use the UnmapFreePhysReg service to remove pages from the region. Since the system does not provide a backing store for a free physical region, unmapping a page makes the previous contents unrecoverable. The MapFreePhysReg and UnmapFreePhysReg services can only be be used within a free-physical-region callback procedure installed using the _SetFreePhysRegCalBk service.
EAX, EDX