List_Allocate

include vmm.inc

mov     esi, List       ; list handle
VMMcall List_Allocate

jc      not_allocated   ; carry flag set if error
mov     [Node], eax     ; address of new node

Allocates a new node for the specified list. A virtual device can attach the new node to the list using the List_Attach, List_Attach_Tail or List_Insert service. The contents of the new node are undefined. Uses EAX, Flags.

• Returns with the carry flag clear and the address of the new node in the EAX register if successful. For lists created using the LF_Alloc_Error value, the service returns with the carry flag set if a node cannot be allocated. For other lists, the service does not return if a node cannot be allocated. (It crashes the current virtual machine instead.)

List

Handle of the list.

If the list is created using the LF_Use_Heap value, this service calls the _HeapAllocate service for each node, in which case all the rules regarding heap access apply to List_Allocate as well.

Otherwise, the service allocates nodes from a pool of free nodes. This avoids the overhead of calling the _HeapAllocate service for every node allocation. This non-reliance on _HeapAllocate has both positive and negative consequences. On the positive side, it means that List_Allocate can be called at times when _HeapAllocate cannot be called, such as during hardware interrupts. On the negative side, this means that if the VMM cannot satisfy the allocation request from its pool of free nodes, it cannot obtain more memory from the heap because it might not be safe to call _HeapAllocate at the time the call to List_Allocate made. VMM maintains an emergency pool of memory into which it can dip when faced with this situation. The emergency pool is refreshed from the system heap at a time when _HeapAllocate is safe to call.

The consequence of this tradeoff is that virtual devices should not allocate large numbers of nodes in rapid succession from lists not marked LF_Use_Heap, because that would dry up the free list and emergency pool, causing List_Allocate to fail.

See also List_Attach, List_Attach_Tail, List_Create, List_Deallocate, List_Insert