View source for DevHelp VMAlloc

{{DISPLAYTITLE:DevHelp_VMAlloc}}
This service allocates virtual memory and, depending on the value of a flag, either commits physical storage or maps virtual memory to a given physical address. 

==Syntax==
===C===
<PRE>
USHORT APIENTRY DevHelp_VMAlloc( ULONG  Flags,
                                 ULONG  Size,
                                 LIN    PhysAddr,
                                 PLIN   LinearAddr,
                                 PPVOID SysReserved)
</PRE>

===Assembler===
<PRE>
MOV   ECX,Size               ; Size of objects in bytes.
MOV   EDI,OFFSET PhysAddr    ; Linear address of a doubleword containing
                             ; physical address to be mapped (Not used if set to
                             ; -1)  (Used only if Flags is set to 8 or 16)
MOV   EAX,Flags              ; Flags used for allocation request
                             ; VMDHA_16MB - If bit 0 is set (000000001B), the
                             ;    object will be allocated below the 16 MB
                             ;    address line.
                             ; VMDHA_FIXED - If bit 1 (000000010B) is set,
                             ;    the object needs to be fixed in memory
                             ;    at all times.  If this bit is clear,
                             ;    then the object may be moved or paged
                             ;    out as necessary.
                             ; VMDHA_SWAP - If bit 2 (000000100B) is set, then
                             ;    swappable memory will be allocated for the
                             ;    object.  If this bit is clear, then the memory
                             ;    will either movable or fixed, depending on the
                             ;    setting of bit 1.
                             ;    If this bit is set, bit 1 must be clear.
                             ; VMDHA_CONTIG - If bit 3 (000001000B) is set,
                             ;    the object needs to be allocated in
                             ;    contiguous memory.  If this bit is clear,
                             ;    then the pages can be discontiguous in
                             ;    physical memory.  In order to request
                             ;    contiguous memory the  physical device
                             ;    driver must have also requested fixed
                             ;    memory (bit 1 must also be set).
                             ; VMDHA_PHYS - If bit 4 (000010000B) is set,
                             ;    then a linear address mapping will be
                             ;    obtained for the physical address
                             ;    passed in the PhysAddr pointer.
                             ; VMDHA_PROCESS - If bit 5 (000100000B) is set,
                             ;    the linear address returned will be in
                             ;    process address range.  If this bit is
                             ;    clear, the allocation/mapping will be done
                             ;    in global address range, that is, accessible
                             ;    out of the current process' context.
                             ; VMDHA_SGSCONT - If bit 6 (001000000B) is set,
                             ;    the allocated memory can be registered
                             ;    under screen group switch control. This
                             ;    flag is valid only if mapping is in
                             ;    process address range as well (bit 5 must
                             ;    be set).
                             ; VMDHA_RESERVE - Bit 7 (010000000B) is reserved
                             ;    and should be set to 0.
                             ; VMDHA_RESERVE - If bit 8 (100000000B) is
                             ;    set, the memory will only be reserved.
                             ;    No commitment will be done and any
                             ;    attempt to access reserved but not
                             ;    committed  memory will cause a fatal
                             ;    page.
                             ;
                             ; VMDHA_USEHIGHMEM - If bit 11
                             ;    (0000100000000000B) is set, the object
                             ;    will be allocated above the 16MB
                             ;    address line (if possible). If
                             ;    memory above 16MB exists but there
                             ;    is not enough to  satisfy the
                             ;    request, memory above 16MB  will be
                             ;    used first and the remaining
                             ;    amount will be taken from memory below
                             ;    16MB.  If no memory above 16MB exists,
                             ;    the allocation will be taken from
                             ;    existing  memory.  The memory is
                             ;    freed by calling the  DevHlp_VMFree
                             ;    function. This bit is only  valid
                             ;    during device driver initialization.
                             ;    If this bit is used at any other
                             ;    time, VMAlloc will return an
                             ;    error (ERROR_INVALID_PARAMETER).
                             ;    All other bits must be Clear.

MOV   DL,DevHlp_VMAlloc

CALL  [Device_Help]

</PRE>

==Parameters==
===C===
;''Flags'' ([[ULONG]]) - input: Flags used for allocation request

<PRE>
                             ; VMDHA_16MB - If bit 0 is set (000000001B), the
                             ;    object will be allocated below the 16 MB
                             ;    address line.
                             ; VMDHA_FIXED - If bit 1 (000000010B) is set,
                             ;    the object needs to be fixed in memory
                             ;    at all times.  If this bit is clear,
                             ;    then the object may be moved or paged
                             ;    out as necessary.
                             ; VMDHA_SWAP - If bit 2 (000000100B) is set, then
                             ;    swappable memory will be allocated for the
                             ;    object.  If this bit is clear, then the memory
                             ;    will either movable or fixed, depending on the
                             ;    setting of bit 1.
                             ;    If this bit is set, bit 1 must be clear.
                             ; VMDHA_CONTIG - If bit 3 (000001000B) is set,
                             ;    the object needs to be allocated in
                             ;    contiguous memory.  If this bit is clear,
                             ;    then the pages can be discontiguous in
                             ;    physical memory.  In order to request
                             ;    contiguous memory the  physical device
                             ;    driver must have also requested fixed
                             ;    memory (bit 1 must also be set).
                             ; VMDHA_PHYS - If bit 4 (000010000B) is set,
                             ;    then a linear address mapping will be
                             ;    obtained for the physical address
                             ;    passed in the PhysAddr pointer.
                             ; VMDHA_PROCESS - If bit 5 (000100000B) is set,
                             ;    the linear address returned will be in
                             ;    process address range.  If this bit is
                             ;    clear, the allocation/mapping will be done
                             ;    in global address range, that is, accessible
                             ;    out of the current process' context.
                             ; VMDHA_SGSCONT - If bit 6 (001000000B) is set,
                             ;    the allocated memory can be registered
                             ;    under screen group switch control. This
                             ;    flag is valid only if mapping is in
                             ;    process address range as well (bit 5 must
                             ;    be set).
                             ; Bit 7 (010000000B) is reserved and should be
                             ;    set to 0.
                             ; VMDHA_RESERVE - If bit 8 (100000000B) is set, the
                             ;    memory will only be reserved.
                             ;    No commitment will be done and any
                             ;    attempt to access reserved but not committed
                             ;    memory will cause a fatal page fault.
                             ; VMDHA_USEHIGHMEM- If bit 11
                             ;    (0000100000000000B) is set, the object
                             ;    will be allocated above the 16MB address line
                             ;    (if possible). If memory above 16MB exists but
                             ;    there is not enough to satisfy the request,
                             ;    memory above 16MB will be used first and the
                             ;    remaining amount will be taken from memory
                             ;    below 16MB.  If no memory above 16MB exists,
                             ;    the allocation will be taken from existing
                             ;    memory.  The memory is freed  by calling the
                             ;    DevHlp_VMFree function.  This bit is only
                             ;    valid during device driver initialization.
                             ;    If this bit is used at any other time, VMAlloc
                             ;    will return an error (ERROR_INVALID_PARAMETER).
                             ; All other bits must be Clear.
</PRE>

;''Size'' ([[ULONG]]) - input: Size of object in bytes
                             
;''PhysAddr'' (LIN) - input: Linear Address of the variable containing the physical address to be mapped.
                             
;''LinearAddr'' (PLIN) - input: A pointer to a variable that will receive a Linear Address.
                          
;''SysReserved'' (PPVOID) - input: Reserved for system use.  SysReserved must be initialized to the 16:16 address of a DWORD of device driver storage.  A value will be filled but do not interpret it.

===Assembler===
<PRE>
MOV   ECX,Size               ; Size of objects in bytes.
MOV   EDI,OFFSET PhysAddr    ; Linear address of a doubleword containing
                             ; physical address to be mapped (Not used if set to
                             ; -1)  (Used only if Flags is set to 8 or 16)
MOV   EAX,Flags              ; Flags used for allocation request
                             ; VMDHA_16MB - If bit 0 is set (000000001B), the
                             ;    object will be allocated below the 16 MB
                             ;    address line.
                             ; VMDHA_FIXED - If bit 1 (000000010B) is set,
                             ;    the object needs to be fixed in memory
                             ;    at all times.  If this bit is clear,
                             ;    then the object may be moved or paged
                             ;    out as necessary.
                             ; VMDHA_SWAP - If bit 2 (000000100B) is set, then
                             ;    swappable memory will be allocated for the
                             ;    object.  If this bit is clear, then the memory
                             ;    will either movable or fixed, depending on the
                             ;    setting of bit 1.
                             ;    If this bit is set, bit 1 must be clear.
                             ; VMDHA_CONTIG - If bit 3 (000001000B) is set,
                             ;    the object needs to be allocated in
                             ;    contiguous memory.  If this bit is clear,
                             ;    then the pages can be discontiguous in
                             ;    physical memory.  In order to request
                             ;    contiguous memory the  physical device
                             ;    driver must have also requested fixed
                             ;    memory (bit 1 must also be set).
                             ; VMDHA_PHYS - If bit 4 (000010000B) is set,
                             ;    then a linear address mapping will be
                             ;    obtained for the physical address
                             ;    passed in the PhysAddr pointer.
                             ; VMDHA_PROCESS - If bit 5 (000100000B) is set,
                             ;    the linear address returned will be in
                             ;    process address range.  If this bit is
                             ;    clear, the allocation/mapping will be done
                             ;    in global address range, that is, accessible
                             ;    out of the current process' context.
                             ; VMDHA_SGSCONT - If bit 6 (001000000B) is set,
                             ;    the allocated memory can be registered
                             ;    under screen group switch control. This
                             ;    flag is valid only if mapping is in
                             ;    process address range as well (bit 5 must
                             ;    be set).
                             ; VMDHA_RESERVE - Bit 7 (010000000B) is reserved
                             ;    and should be set to 0.
                             ; VMDHA_RESERVE - If bit 8 (100000000B) is
                             ;    set, the memory will only be reserved.
                             ;    No commitment will be done and any
                             ;    attempt to access reserved but not
                             ;    committed  memory will cause a fatal
                             ;    page.
                             ;
                             ; VMDHA_USEHIGHMEM - If bit 11
                             ;    (0000100000000000B) is set, the object
                             ;    will be allocated above the 16MB
                             ;    address line (if possible). If
                             ;    memory above 16MB exists but there
                             ;    is not enough to  satisfy the
                             ;    request, memory above 16MB  will be
                             ;    used first and the remaining
                             ;    amount will be taken from memory below
                             ;    16MB.  If no memory above 16MB exists,
                             ;    the allocation will be taken from
                             ;    existing  memory.  The memory is
                             ;    freed by calling the  DevHlp_VMFree
                             ;    function. This bit is only  valid
                             ;    during device driver initialization.
                             ;    If this bit is used at any other
                             ;    time, VMAlloc will return an
                             ;    error (ERROR_INVALID_PARAMETER).
                             ;    All other bits must be Clear.
</PRE>

==Return Code==

===C===
;Success Indicator: 0 if object is allocated. Linear address of object is returned.
:;Possible errors: ERROR_INVALID_PARAMETER  (87)

===Assembler===
<PRE>
   'C' Clear if object allocated.
       EAX = Linear address of object.

   'C' Set if error.
       EAX = Error code.
            Possible errors:
               ERROR_INVALID_PARAMETER (87)
</PRE>

==Remarks==
This function obtains a global, Ring 0, linear mapping to a block of memory. The physical address of the memory can be specified for non-system memory or the system will allocate the block from general system memory. A linear address is returned to address the memory. For contiguous fixed allocation requests, the physical address is also returned.

Virtual memory is allocated in global (system) address space, unless private process space is requested. Memory requested in process space can only be swapped. If requested, memory allocated in process space can be registered under screen group switch control. In that case, a task is denied write access to this memory unless it is in the foreground.

Bit 0 is used by physical device drivers, which cannot support more than 16MB addresses. If the physical device driver requests memory below 16MB, the memory must also be resident at all times. If bit 4 is set, virtual memory is mapped to a given physical address. The physical address passed should be the Linear address of the variable containing the physical address to be mapped. In this case, the physical memory must be fixed or locked (that is, bit 1 should be set as well). This could be used for non-system memory like Video buffers. If it is used for system memory, it is the responsibility of the device driver to ensure that the physical pages corresponding to the PhysAddr never move or become invalid. Memory or mapping allocated with bit 6 set is invalid when the process is not in the foreground. If bit 8 is set, the linear address returned is page aligned. The size requested is rounded up to the nearest page boundary. All other allocations can return byte-granular size and addresses.

To use the memory management DevHlp services to give a process access to a video buffer, perform the following steps:

* Call VMAlloc to obtain a linear address in the process's address space for the physical buffer. Register it under screen group switch control to invalidate access to it if the task is not current.

* If the process needs to access the memory with a tiled Local Descriptor Table (LDT) selector, allocate with a selector map request and use the FlatToSel macro to convert the linear address returned by VMAlloc to an LDT selector:offset.

* Call VMFree to remove addressability to the buffer.

==Example Code==
===C===
<PRE>
#include  "dhcalls.h"

USHORT APIENTRY DevHelp_VMAlloc( ULONG  Flags,
                                 ULONG  Size,
                                 LIN    PhysAddr,
                                 PLIN   LinearAddr,
                                 PPVOID SysReserved)
</PRE>

==Related Functions==

[[Category:DevHlps]]