_Allocate_Global_V86_Data

_Allocate_Global_V86_Data_Area

include vmm.inc

VMMcall _Allocate_Global_V86_Data_Area, <nBytes, flags>

or      eax, eax        ; zero if error
jz      error
mov     [Address], eax  ; ring-0 linear address of block

Allocates a block of memory from the global V86 data area. The block is for exclusive use by the virtual device. Virtual devices use this service to allocate memory for device-specific objects which must be accessible to both the virtual device and software running in the virtual machine. This service is only available during initialization. Uses EAX, ECX, EDX, and Flags.

Returns the ring-0 linear address of the block in the EAX register if successful, zero otherwise.
If GVDAInquire is given, EAX contains the size in bytes of the largest block that satisfies the request, but that does not move the first V86 page. EAX contains zero if all such requests move the first V86 page.

nBytes

Number of bytes to allocate. This parameter should be a multiple of 4096.

flags

Operation flags. Can be zero or more of these values:

Value	Meaning
GVDADWordAlign	Aligns block on a doubleword boundary. If no alignment value is given, the service aligns the block on a byte boundary.
GVDAHighSysCritOK	Informs the service that the virtual device can manage a block that resides in high MS-DOS memory. The service allocates from high MS-DOS memory only if such memory is available (for example, implemented as XMS UMBs) and the virtual device specifies this value. A virtual device can use this value only while processing the Sys_Critical_Init message. n first allocated, a block in high MS-DOS memory may not be immediately usable since memory supporting the area may not yet have been mapped. The system maps the memory for the area at some time during the Sys_Critical_Init message, but there is no guarantee as to when. GVDAHighSysCritOK value is only available for Windows version 3.1 or later.
GVDAInquire	Returns the size in bytes of the largest block that satisfies the requested alignment but does not require the first V86 page to be moved. The nBytes parameter is not used if this value is specified. irtual device typically uses this value, while processing the Init_Complete message, to allocate portions of the global V86 data area that might otherwise go unused. The GVDAInquire value is only available for Windows version 3.1 or later.
GVDAInstance	Creates an instance data block allowing the virtual device to maintain different values in the block for each virtual machine. If this value is not given, the service creates a global block in which the same data is available to all virtual machines.
GVDAOptInstance	Allows the virtual machine manager to determine whether to create an instance data block or a global data block.
GVDAPageAlign	Aligns block on a page (4 kilobyte) boundary. If no alignment value is given, the service aligns the block on a byte boundary. GVDAWordAlign, GVDADWordAlign, GVDAParaAlign, and GVDAPageAlign values are mutually exclusive.
GVDAParaAlign	Aligns block on a paragraph (16-byte) boundary. If no alignment value is given, the service aligns the block on a byte boundary.
GVDAReclaim	Unmaps any physical pages in the block while mapping the system nul page into the block. The service places unmapped physical pages in the free list. This value only applies if the GVDAPageAlign value is also given. If this value is not given, the service ignores any physical pages it unmaps. It is up to the virtual device to reclaim these pages. GVDAReclaim and GVDAInstance values are mutually exclusive.
GVDAWordAlign	Aligns block on a word boundary. If no alignment value is given, the service aligns the block on a byte boundary.
GVDAZeroInit	Fills the block with zeros. If this value is not given, the initial content of the block is undefined.

All other values are reserved.

If this service returns an error, the virtual device should consider this a fatal error and respond accordingly.

The size returned when the GVDAInquire value is given may be less than a reasonable minimum. For instance, if GVDAPageAlign is specified, the return size may be less than 4096. It is up to the virtual device to check for this.

For blocks allocated with GVDAInstance, this service calls automatically calls the _AddInstanceItem service.

The _Allocate_Global_V86_Data_Area service is not available and must not be called if the virtual device has allocated a temporary block using the _Allocate_Temp_V86_Data_Area service. The virtual device must free the block before it can call the _Allocate_Global_V86_Data_Area service.

If GVDAReclaim is not given, the virtual device should reclaim the physical addresses of any unmapped physical pages, and map the pages to other addresses. A virtual device reclaims the physical addresses by using the _CopyPageTable service to retrieve the page-table entries for the system virtual machine. The virtual device can then use the _PhysIntoV86 service to map the physical pages into the V86 address space.

See also _CopyPageTable, _PhysIntoV86