List_Create

include vmm.inc

mov     eax, Flags      ; creation flags
mov     ecx, NodeSize   ; size in bytes of each node in list
VMMcall List_Create

jc      error           ; carry flag set if error
mov     [List], esi     ; list handle

Creates a new list and returns a list handle that virtual devices use in subsequent calls to other list services. Uses ESI, Flags.

Returns with the carry flag clear and the list handle in the ESI register, if successful. The carry flag is set if an error occurs.

Flags

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

Value	Meaning
LF_Alloc_Error	Directs the List_Allocate service to returns with carry flag set if new node could not be allocated.
LF_Async	Creates an asynchronous list that can be used while processing interrupts.
LF_Use_Heap	Allocates nodes on the system heap. This value must not be used in combination with the LF_Async value.
LF_Swap	Allocates nodes from the swappable system heap. This value must not be used in combination with the LF_Async value.

NodeSize

Size, in bytes, of each node in the list.

If a virtual device requires large nodes, it should specify the LF_Use_Heap value to force the nodes to be allocated from the system heap. All allocate and deallocate calls for lists created in this way use the _HeapAlloc and _HeapFree services to create and destroy nodes.

To access a list during hardware interrupts, a virtual device must set the LF_Async value when creating the list. This forces list operations to be atomic operations which cannot be re-entered. When using an asynchronous list, the virtual device must disable interrupts before calling the list services. The virtual device must disable interrupts even if when not calling during an interrupt. The virtual device must use the pushf, cli, and popf instructions to disable and re-enable interrupts. It must not use the sti instruction to enable interrupts unless other documentation states that this is premitted.

If the LF_Alloc_Error value is not specified, the system crashes the current virtual machine if the List_Allocate service fails. If this value is specified, List_Allocate returns with the carry flag set when an allocation fails.

If the LF_Swap value is specified, then list nodes are allocated from the swappable system heap. Consequently, all list services related to swappable list nodes become subject to constraints on accessing swappable memory.

See also List_Allocate, List_Deallocate, List_Destroy