13. Memory Management Services

• 13.1 Get Free Memory Information
• 13.2 Allocate Memory Block
• 13.3 Free Memory Block
• 13.4 Resize Memory Block

These functions are provided to allocate linear address space.

13.1 Get Free Memory Information

This function is provided so that protected mode applications can determine how much memory is available. Under DPMI implementations that support virtual memory, it is important to consider issues such as the amount of available physical memory.

Note that since DPMI applications will often run in multi-tasking environments, this function must be considered only advisory.

To Call

     AX = 0500h
     ES:(E)DI = Selector:Offset of 30h byte buffer

Returns

     If function was successful:
     Carry flag is clear.
     ES:(E)DI = Selector:Offset of buffer with the following structure:

           Offset           Description

            00h   Largest available free block in
                  bytes

            04h   Maximum unlocked page allocation

            08h   Maximum locked page allocation

            0Ch   Linear addr space size in pages

            10h   Total number of unlocked pages

            14h   Number of free pages

            18h   Total number of physical pages

            1Ch   Free linear address space in pages

            20h   Size of paging file/partition in
                  pages

           24h-2Fh    Reserved


     If function was not successful:
     Carry flag is set.

Programmer's Notes

• 32-bit programs must use ES:EDI to point to the buffer. 16-bit programs should use ES:DI.
• DPMI implementations that do not support virtual memory (returned in flags from Get Version call) will only fill in the first field. This value specifies that largest allocation that could be made using function 0501h. Other fields will be set to -1.
• Only the first field of this structure is guaranteed to contain a valid value. All fields that are not returned by the DPMI implementation will be set to -1 (0FFFFFFFFh) to indicate that the information is not available.
• The field at offset 00h specifies the largest block of contiguous linear memory in bytes that could be allocated if the memory were to be allocated and left unlocked.
• The field at offset 04h specifies the number of pages that could be allocated. This is the value returned by field 00h / page size.
• The field at offset 08h specifies the largest block of memory in pages that could be allocated and then locked.
• The field at offset 0Ch specifies the size of the total linear address space in pages. This includes all linear address space that has already been allocated.
• The field at offset 10h specifies the total number of pages that are currently unlocked and could be paged out. This value also contains any free pages.
• The field at offset 14h specifies the number of physical pages that currently are not in use.
• The field at offset 18h specifies the total number of physical pages that the DPMI host manages. This value includes all free, locked, and unlocked physical pages.
• The field at offset 20h specifies the size of the DPMI host's paging partition or file in pages.
• To determine the size of pages for the DPMI host call the Get Page Size service (see section 15).

13.2 Allocate Memory Block

This function allocates and commits linear memory.

To Call

     AX = 0501h
     BX:CX = Size of memory block to allocate in bytes

Returns

     If function was successful:
     Carry flag is clear
     BX:CX = Linear address of allocated memory block
     SI:DI = Memory block handle (used to resize and free)

     If function was unsuccessful:
     Carry flag is set

Programmer's Notes

• This function does not allocate any selectors for the memory block. It is the responsibility of the caller to allocate and initialize any selectors needed to access the memory.
• Under DPMI implementations that support virtual memory the memory block will be allocated unlocked. If some or all of the memory should be locked you will need to use either the lock selector function or the lock linear region function.
• Under many implementations of DPMI, allocations will be page granular. This means that an allocation of 1001h bytes will result in an allocation of 2000h bytes. Therefore it is best to always allocate memory in multiples of 4K.

13.3 Free Memory Block

This function frees a memory block that was allocate through the allocate memory block function.

To Call

     AX = 0502h
     SI:DI = Handle of memory block to free

Returns

     If function was successful:
     Carry flag is clear

     If function was unsuccessful:
     Carry flag is set

Programmer's Notes

• Your program must also free any selectors that it allocated to point to the memory block.

13.4 Resize Memory Block

This function changes the size of a memory block that was allocated through the allocate memory block function.

To Call

     AX = 0503h
     BX:CX = New size of memory block to allocate in bytes
     SI:DI = Handle of memory block to resize

Returns

     If function was successful:
     Carry flag is clear
     BX:CX = New linear address of memory block
     SI:DI = New handle of memory block

     If function was unsuccessful:
     Carry flag is set

Programmer's Notes

• This function may change the linear address of the memory block and the memory handle. Therefore, you will need to update any selectors that point to the block after resizing it. You must use the new handle instead of the old one.
• This function will generate an error if a memory block is resized to 0 bytes.