SYNOPSIS
In sys/vmem.h Ft vmem_t * Fn vmem_create const char *name vmem_addr_t base vmem_size_t size vmem_size_t quantum vmem_size_t qcache_max int flags Ft int Fn vmem_add vmem_t *vm vmem_addr_t addr vmem_size_t size int flags Ft int Fn vmem_xalloc vmem_t *vm const vmem_size_t size vmem_size_t align const vmem_size_t phase const vmem_size_t nocross const vmem_addr_t minaddr const vmem_addr_t maxaddr int flags vmem_addr_t *addrp Ft void Fn vmem_xfree vmem_t *vm vmem_addr_t addr vmem_size_t size Ft int Fn vmem_alloc vmem_t *vm vmem_size_t size int flags vmem_addr_t *addrp Ft void Fn vmem_free vmem_t *vm vmem_addr_t addr vmem_size_t size Ft void Fn vmem_destroy vmem_t *vmDESCRIPTION
The is a general purpose resource allocator. Despite its name, it can be used for arbitrary resources other than virtual memory.Fn vmem_create creates a new vmem arena.
- Fa name
- The string to describe the vmem.
- Fa base
- The start address of the initial span. Pass 0 if no initial span is required.
- Fa size
- The size of the initial span. Pass 0 if no initial span is required.
- Fa quantum
- The smallest unit of allocation.
- Fa qcache_max
- The largest size of allocations which can be served by quantum cache. It is merely a hint and can be ignored.
- Fa flags
-
Combination of
malloc(9)
wait flag and
allocation strategy flag:
- M_FIRSTFIT
- Prefer allocation performance.
- M_BESTFIT
- Prefer space efficiency.
Fn vmem_add adds a span of size Fa size starting at Fa addr to the arena. Returns 0 on success, ENOMEM on failure. Fa flags is malloc(9) wait flag.
Fn vmem_xalloc allocates a resource from the arena.
- Fa vm
- The arena which we allocate from.
- Fa size
- Specify the size of the allocation.
- Fa align
- If zero, don't care about the alignment of the allocation. Otherwise, request a resource segment starting at offset Fa phase from an Fa align aligned boundary.
- Fa phase
- See the above description of Fa align . If Fa align is zero, Fa phase should be zero. Otherwise, Fa phase should be smaller than Fa align .
- Fa nocross
- Request a resource which doesn't cross Fa nocross aligned boundary.
- Fa minaddr
- Specify the minimum address which can be allocated, or VMEM_ADDR_MIN if the caller does not care.
- Fa maxaddr
- Specify the maximum address which can be allocated, or VMEM_ADDR_MAX if the caller does not care.
- Fa flags
- A bitwise OR of an allocation strategy and a malloc(9) wait flag. The allocation strategy is one of M_FIRSTFIT and M_BESTFIT
- Fa addrp
- On success, if Fa addrp is not NULL Fn vmem_xalloc overwrites it with the start address of the allocated span.
Fn vmem_xfree frees resource allocated by Fn vmem_xalloc to the arena.
- Fa vm
- The arena which we free to.
- Fa addr
- The resource being freed. It must be the one returned by Fn vmem_xalloc . Notably, it must not be the one from Fn vmem_alloc . Otherwise, the behaviour is undefined.
- Fa size
- The size of the resource being freed. It must be the same as the Fa size argument used for Fn vmem_xalloc .
Fn vmem_alloc allocates a resource from the arena.
- Fa vm
- The arena which we allocate from.
- Fa size
- Specify the size of the allocation.
- Fa flags
- A bitwise OR of an allocation strategy flag (see above) and a malloc(9) sleep flag.
- Fa addrp
- On success, if Fa addrp is not NULL Fn vmem_alloc overwrites it with the start address of the allocated span.
Fn vmem_free frees resource allocated by Fn vmem_alloc to the arena.
- Fa vm
- The arena which we free to.
- Fa addr
- The resource being freed. It must be the one returned by Fn vmem_alloc . Notably, it must not be the one from Fn vmem_xalloc . Otherwise, the behaviour is undefined.
- Fa size
- The size of the resource being freed. It must be the same as the Fa size argument used for Fn vmem_alloc .
Fn vmem_destroy destroys a vmem arena.
- Fa vm
- The vmem arena being destroyed. The caller should ensure that no one will use it anymore.
RETURN VALUES
Fn vmem_create returns a pointer to the newly allocated vmem_t. Otherwise, it returns NULLOn success, Fn vmem_xalloc and Fn vmem_alloc return 0. Otherwise, ENOMEM is returned.