EXTENT(9) | Kernel Developer's Manual | EXTENT(9)

# NAME

`extent_create`, `extent_destroy`, `extent_alloc`, `extent_alloc_with_descr`, `extent_alloc_subregion`, `extent_alloc_subregion_with_descr`, `extent_alloc_region`, `extent_alloc_region_with_descr`, `extent_free`, `extent_print` — general purpose extent manager

# SYNOPSIS

`#include <sys/malloc.h>`
`#include <sys/extent.h>`

struct extent *
`extent_create`(char *name, u_long start, u_long end, int mtype, caddr_t storage, size_t storagesize, int flags);

void
`extent_destroy`(struct extent *ex);

int
`extent_alloc`(struct extent *ex, u_long size, u_long alignment, u_long skew, u_long boundary, int flags, u_long *result);

int
`extent_alloc_with_descr`(struct extent *ex, u_long size, u_long alignment, u_long skew, u_long boundary, int flags, struct extent_region *rp, u_long *result);

int
`extent_alloc_subregion`(struct extent *ex, u_long substart, u_long subend, u_long size, u_long alignment, u_long skew, u_long boundary, int flags, u_long *result);

int
`extent_alloc_subregion_with_descr`(struct extent *ex, u_long substart, u_long subend, u_long size, u_long alignment, u_long skew, u_long boundary, int flags, struct extent_region *rp, u_long *result);

int
`extent_alloc_region`(struct extent *ex, u_long start, u_long size, int flags);

int
`extent_alloc_region_with_descr`(struct extent *ex, u_long start, u_long size, int flags, struct extent_region *rp);

int
`extent_free`(struct extent *ex, u_long start, u_long size, int flags);

void
`extent_print`(struct extent *ex);

# DESCRIPTION

The extent manager provides management of areas of memory or other enumerable spaces (such as I/O ports). An opaque structure called an `extent map` keeps track of allocated regions within the enumerable space.

`extent_create`() creates an extent map managing the space from start to end inclusive. All memory allocation will use the memory type mtype (see malloc(9)). The extent map will have the name name, used for identification in case of errors or in ddb(4) `show extents`. If the flag `EX_NOCOALESCE` is set, internal coalescing of regions is disabled, and only entire regions may be freed within the extent map, so that `extent_free`() will never have to allocate a region descriptor. If the flag `EX_FILLED` is set, the entire space managed by the extent map will be allocated upon creation of the extent map, such that selected regions may be made available through calls to `extent_free`().

Some applications may want to use an extent map but can't use `malloc`() and `free`(). These applications may provide pre-allocated storage for all descriptor overhead with the arguments storage and storagesize. An extent of this type is called a `fixed extent`. If the application can safely use `malloc`() and `free`(), storage should be `NULL`. A fixed extent has a fixed number of region descriptors, so care should be taken to provide enough storage for them; alternatively, the flag `EX_MALLOCOK` may be passed to extent requests to indicate that a fixed extent map may be extended using a call to `malloc`(). Note that passing the flag `EX_FILLED` to `extent_create`() will consume a region descriptor upon creation of the extent map.

The caller should pass the flag `EX_WAITOK` or `EX_NOWAIT` to extent functions that have a memory overhead, to specify whether it is okay to wait. These functions are `extent_create`() (non fixed extents), `extent_free`() (unless `EX_NOCOALESCE` is set), `extent_alloc`(), `extent_alloc_subregion`() and `extent_alloc_region`().

`extent_destroy`() destroys the extent map ex, freeing all allocated regions. If the extent is not a fixed extent, the region and internal extent descriptors themselves are freed. This function always succeeds.

`extent_alloc`() allocates a region in the extent map ex of size size that fits the provided parameters. There are two distinct allocation policies, which are selected by the flags argument:

`EX_FAST`
  Allocate the first region that fits the provided parameters, regardless of resulting extent fragmentation.
default
  Allocate the smallest region that is capable of holding the request, thus minimizing fragmentation of the extent.

The caller may specify that it is okay to wait for space to become free in the extent by setting the flag `EX_WAITSPACE`. If `EX_WAITSPACE` is not set, the allocation will fail if the request cannot be satisfied without sleeping.

The request will be aligned to a multiple of alignment. That value must be a power of 2. If no alignment is necessary, the value `EX_NOALIGN` should be specified. If skew is non-zero, it modifies the requested alignment result in the following way: the value (result - skew) is aligned to alignment boundaries. skew must be a smaller number than alignment. If boundary is not `EX_NOBOUNDARY`, the allocated region will not cross any boundary lines, spaced boundary apart. If the caller specifies the `EX_BOUNDZERO` flag, boundary lines begin at zero. Otherwise, boundary lines begin at the beginning of the extent. The allocated region may begin on a boundary line, but the end of the region will not touch nor cross a boundary line. A boundary argument smaller than the sum of the requested skew and the size of the request is invalid. Upon successful completion, *result will contain the start of the allocated region.

`extent_alloc_with_descr`() is similar to `extent_alloc`() but allows the caller to provide a pre-allocated region descriptor instead of having the function allocate one. This function can only be used with extents that have the `EX_NOCOALESCE` property.

`extent_alloc_subregion`() and `extent_alloc_subregion_with_descr`() are generalized versions of `extent_alloc`() and `extent_alloc_with_descr`() that allow the caller to specify that the allocated region must fall within the subregion from substart to subend inclusive.

`extent_alloc_region`() allocates the specific region in the extent map ex beginning at start with the size size. If the caller specifies the `EX_CONFLICTOK` flag, the allocation will succeed even if part of the requested region has already been allocated. The caller may specify that it is okay to wait for the indicated region to be free by setting the flag `EX_WAITSPACE`. If neither `EX_WAITSPACE` nor `EX_CONFLICTOK` is set, the allocation will fail if the request cannot be satisfied without sleeping.

`extent_alloc_region_with_descr`() is similar to `extent_alloc_region`() but allows the caller to provide a pre-allocated region descriptor instead of having the function allocate one. This function can only be used with extents that have the `EX_NOCOALESCE` property.

`extent_free`() frees a region of size bytes starting at start in the extent map ex. If the extent has the `EX_NOCOALESCE` property, only entire regions may be freed. If the extent has the `EX_NOCOALESCE` property and the caller attempts to free a partial region, behavior is undefined. If called on an extent without the `EX_NOCOALESCE` property, this function can fail with error codes listed below, otherwise this function will always succeed.

`extent_print`() Prints out information about extent ex. This function always succeeds.

# RETURN VALUES

The behavior of all extent manager functions is undefined if given invalid arguments. `extent_create`() returns the extent map on success, or `NULL` if it fails to allocate storage for the extent map. It always succeeds when creating a fixed extent or when given the flag `EX_WAITOK`. `extent_alloc`(), `extent_alloc_region`(), `extent_alloc_subregion`(), and `extent_free`() return one of the following values:

`0`
  Operation was successful.
`ENOMEM`
  If `EX_NOWAIT` is specified, the extent manager was not able to allocate a region descriptor for the new region or to split a region when freeing a partial region.
`EAGAIN`
  Requested region is not available and `EX_WAITSPACE` was not specified.
`EINTR`
  Process received a signal while waiting for the requested region to become available in the extent.

# EXAMPLES

Here is an example of a (useless) function that uses several of the extent manager routines.

    void
    func()
    {
    	struct extent *foo_ex;
    	u_long region_start;
    	int error;

    	/*
    	 * Extent "foo" manages a 256k region starting at 0x0 and
    	 * only allows complete regions to be freed so that
    	 * extent_free() never needs to allocate memory.
    	 */
    	foo_ex = extent_create("foo", 0x0, 0x3ffff, M_DEVBUF,
    	    NULL, 0, EX_WAITOK | EX_NOCOALESCE);

    	/*
    	 * Allocate an 8k region, aligned to a 4k boundary, which
    	 * does not cross any of the 3 64k boundaries (at 64k,
    	 * 128k, and 192k) within the extent.
    	 */
    	error = extent_alloc(foo_ex, 0x2000, 0x1000, 0x10000,
    	    EX_NOWAIT, &region_start);
    	if (error)
    		panic("you lose");

    	/*
    	 * Give up the extent.
    	 */
    	extent_destroy(foo_ex);
    }

# CODE REFERENCES

The extent manager itself is implemented within the file sys/kern/subr_extent.c.

The i386 bus management code uses the extent manager for managing I/O ports and I/O memory. See sys/arch/i386/i386/machdep.c.

# SEE ALSO

ddb(4), malloc(9)

# HISTORY

The extent manager appeared in NetBSD 1.3.

# AUTHORS

The extent manager was designed and implemented by Jason R. Thorpe <thorpej@NetBSD.ORG>. Matthias Drochner <drochner@zelux6.zel.kfa-juelich.de> contributed to the initial testing and optimization of the implementation. Chris Demetriou <cgd@NetBSD.ORG> contributed many architectural suggestions.

January 19, 2024 | Debian