_PageAllocate

// C syntax
#include <vmm.h>

ULONG EXTERN _PageAllocate(ULONG nPages, ULONG pType, ULONG VM, 
    ULONG AlignMask, ULONG minPhys, ULONG maxPhys, ULONG *PhysAddr,
    ULONG flags);

; assembler syntax
include vmm.inc

VMMcall _PageAllocate, <nPages, pType, VM, AlignMask, minPhys,
    maxPhys, <OFFSET32 PhysAddr>, flags>

test    eax, eax             ; returns 0 on error
jz      error

mov     [Address], eax       ; linear address of allocated memory block

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. Uses EAX, ECX, EDX, and flags.

Returns the ring-0 linear address of the memory block (in the EAX register). For compatibility with Windows 3.1, the same value is returned in EDX. For Windows 3.1, EAX was the memory handle and EDX the memory address. For Windows 95, the handle and the linear address are always the same. Both registers are zero if an error occurs, such as insufficient memory.

nPages

Number of pages to allocate for the memory block. This parameter must not be zero.

pType

Value specifying the type of pages to allocate. Must be PG_HOOKED, PG_SYS, or PG_VM. If PG_SYS is specified, the pages are allocated in the system arena. Otherwise, they are allocated in the ring 3 shared arena. There is no real difference between the PG_HOOKED and PG_VM types.

Handle of 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 zero if the nType parameter specifies PG_SYS.

AlignMask

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

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

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

Address of a four-byte buffer that receives the physical address of the start of the memory block. The service uses this parameter only if the flags parameter specifies the PAGECONTIG and PAGEUSEALIGN values. The service ignores this parameter if it is zero.

flags

Operation flags. Can be zero or more of these 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. the page will remain locked throughout its life, use PAGEDFIXED; it's more efficient than PAGELOCKED.
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. irtual device must not specify the PAGELOCKEDIFDP value until after it has received the Init_Complete message. PAGELOCKED and PAGELOCKEDIFDP values are mutually exclusive.
PAGEUSEALIGN	Allocates pages using the alignment and physical addresses specified by the AlignMask, minPhys, and maxPhys parameters. If this value is specified, PAGEFIXED must also be specified.
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.

This service reserves linear address space by calling the _PageReserve service, and then commits physical storage by calling the _PageCommit service. The address returned by this service can be used in the same manner as the linear address returned by the _PageReserve service.

Unless the PAGELOCKED, PAGELOCKEDIFDP, or PAGEFIXED value is specified, the allocated pages are not initially present in physical memory. The system maps a page into physical memory (pages it in) when a virtual device attempts to access the page. You can force a page to be present by using the _PageLock service.

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.

See also _PageFree, _PageLock, _PageReAllocate, _PageUnLock