unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (OpenBSD-5.7)
Page:
Section:
Apropos / Subsearch:
optional field

KM_ALLOC(9)              BSD Kernel Developer's Manual             KM_ALLOC(9)

NAME
     km_alloc, km_free -- kernel memory allocator

SYNOPSIS
     #include <&lt;sys/types.h>&gt;
     #include <&lt;uvm/uvm_extern.h>&gt;

     void *
     km_alloc(size_t size, struct kmem_va_mode *kv, struct kmem_pa_mode *kp,
         struct kmem_dyn_mode *kd);

     void
     km_free(void *v, size_t size, struct kmem_va_mode *kv,
         struct kmem_pa_mode *pa);

DESCRIPTION
     The km_alloc() function allocates kernel virtual space optionally backed
     by physical pages.  The km_free() function frees the space that was pre-
     viously allocated by km_alloc().

     The size argument specifies the size of the allocation and must be a mul-
     tiple of PAGE_SIZE.  The kv and kp arguments specify the type of virtual
     and physical memory to be allocated.  The kd argument specifies addi-
     tional options for the allocation.  The arguments passed to km_free()
     must match those that were used to obtain the space in km_alloc().

     Typically a user will use certain predefined modes for memory allocation.
     For virtual space the predefined modes are:

        kv_any       Allocates the virtual space anywhere.
        kv_intrsafe  Allocates the virtual space in the interrupt safe map.
        kv_page      Allocates single pages.

     For physical pages the predefined modes are:

        kp_dirty     Maps dirty pages into the allocation.
        kp_zero      Maps zeroed pages into the allocation.
        kp_dma       Maps dma-accessible pages into the allocation.
        kp_dma_zero  Maps zeroed dma-accessible pages into the allocation.
        kp_pageable  Pages will be demand paged.
        kp_none      Leaves the allocation unmapped.

     The other parameters for allocation are:

        kd_waitok   Sleeping for physical pages is allowed.
        kd_nowait   Sleeping is not allowed.
        kd_trylock  Fail if the allocator cannot obtain locks without waiting.

     In case the predefined allocation modes are not sufficient, a custom
     allocation mode can be created.  The structure controlling the virtual
     space alloction is:

     struct kmem_va_mode {
             struct vm_map **kv_map;
             vsize_t kv_align;
             int kv_wait;
             int kv_singlepage;
             int kv_executable;
     };

     kv_map         A pointer to the pointer to the uvm_map the space will be
                    allocated from.

     kv_align       Alignment constraint of the allocated space.

     kv_wait        A flag indicating whether the allocator should wait for
                    space to be freed if the allocation cannot be satisfied.

     kv_singlepage  A flag indicating if the allocations will always be for
                    single pages.

     kv_executable  A flag indicating if the memory mapped should be mapped
                    permitting execution.

     struct kmem_pa_mode {
             struct uvm_constraint_range *kp_constraint;
             struct uvm_object **kp_object;
             paddr_t kp_align;
             paddr_t kp_boundary;
             int kp_nomem;
             int kp_maxseg;
             int kp_zero;
             int kp_pageable;
     };

     kp_constraint  A pointer to physical allocation constraints.

     kp_object      A pointer to a pointer to a uvm_object if the pages should
                    be backed by a kernel object.

     kp_align       Physical alignment of the first page in the allocation.

     kp_boundary    Boundary that the physical addresses can't cross if the
                    allocation is contiguous.

     kp_nomem       A flag that specifies that the allocation should not be
                    backed by physical pages.

     kp_maxseg      Maximal amount of contiguous physical segments in the
                    allocation.

     kp_zero        A flag that specifies if the returned memory should be
                    zeroed.

     kp_pageable    A flag that specifies if the returned memory should be
                    demand paged from the backing object instead of being
                    allocated up front.

     struct kmem_dyn_mode {
             int kd_waitok;
             int kd_trylock;
             voff_t kd_prefer;
             int *kd_slowdown;
     };

     kd_waitok    A flag that specifies if the allocator may sleep waiting for
                  memory.

     kd_trylock   A flag that specifies if the allocator should fail if it
                  can't immediately obtain a lock.

     kd_prefer    An offset given to PMAP_PREFER to virtually align the allo-
                  cated space.

     kd_slowdown  A pointer to an integer that will be set to 1 if the inter-
                  nal single page allocator needs the caller to back off to
                  allow the allocator to catch up.

RETURN VALUES
     km_alloc() returns a kernel virtual address or NULL if the allocation
     cannot be satisifed.

SEE ALSO
     malloc(9), uvm(9)

BSD                              June 4, 2013                              BSD