Updated: 2022/Sep/29

Please read Privacy Policy. It's for your privacy.


UVM_MAP(9)                 Kernel Developer's Manual                UVM_MAP(9)

NAME
     uvm_map - virtual address space management interface

SYNOPSIS
     #include <sys/param.h>
     #include <uvm/uvm.h>

     int
     uvm_map(struct vm_map *map, vaddr_t *startp, vsize_t size,
         struct uvm_object *uobj, voff_t uoffset, vsize_t align,
         uvm_flag_t flags);

     void
     uvm_unmap(struct vm_map *map, vaddr_t start, vaddr_t end);

     int
     uvm_map_pageable(struct vm_map *map, vaddr_t start, vaddr_t end,
         bool new_pageable, int lockflags);

     bool
     uvm_map_checkprot(struct vm_map *map, vaddr_t start, vaddr_t end,
         vm_prot_t protection);

     int
     uvm_map_protect(struct vm_map *map, vaddr_t start, vaddr_t end,
         vm_prot_t new_prot, bool set_max);

     int
     uvm_map_protect_user(struct lwp *l, vaddr_t start, vaddr_t end,
         vm_prot_t new_prot);

     int
     uvm_deallocate(struct vm_map *map, vaddr_t start, vsize_t size);

     struct vmspace *
     uvmspace_alloc(vaddr_t min, vaddr_t max);

     void
     uvmspace_exec(struct lwp *l, vaddr_t start, vaddr_t end);

     struct vmspace *
     uvmspace_fork(struct vmspace *vm);

     void
     uvmspace_free(struct vmspace *vm);

     void
     uvmspace_share(struct proc *p1, struct proc *p2);

     vaddr_t
     uvm_uarea_alloc(void);

     void
     uvm_uarea_free(vaddr_t uaddr);

     vaddr_t
     uvm_uarea_system_alloc(void);

     void
     uvm_uarea_system_free(vaddr_t uaddr);

DESCRIPTION
     The UVM facility for virtual address space management.

FUNCTIONS
     uvm_map() establishes a valid mapping in map map, which must be unlocked.
     The new mapping has size size, which must be a multiple of PAGE_SIZE.

     The uobj and uoffset arguments can have four meanings:
            When uobj is NULL and uoffset is UVM_UNKNOWN_OFFSET, uvm_map()
             does not use the machine-dependent PMAP_PREFER function.
            When uobj is NULL and uoffset is any other value, it is used as
             the hint to PMAP_PREFER.
            When uobj is not NULL and uoffset is UVM_UNKNOWN_OFFSET,
             uvm_map() finds the offset based upon the virtual address, passed
             as startp.
            When uobj is not NULL and uoffset is any other value, then a
             regular mapping is performed at this offset.  The start address
             of the map will be returned in startp.
     If uobj is supplied, then uvm_map() consumes the caller's reference to
     uobj on success; uvm_unmap() will release it when removing this mapping.
     On failure, uvm_map() leaves the reference count of uobj unmodified.

     align specifies alignment of mapping unless UVM_FLAG_FIXED is specified
     in flags.  align must be a power of 2.

     flags passed to uvm_map() are typically created using the
     UVM_MAPFLAG(vm_prot_t prot, vm_prot_t maxprot, vm_inherit_t inh, int
     advice, int flags) macro, which uses the following values.

     The values that prot and maxprot can take are:
         UVM_PROT_NONE       No protection bits.
         UVM_PROT_R          Read.
         UVM_PROT_W          Write.
         UVM_PROT_X          Exec.
         UVM_PROT_MASK       Mask to extraction the protection bits.
     Additionally, the following constants for ORed values are available:
     UVM_PROT_RW, UVM_PROT_RX, UVM_PROT_WX and UVM_PROT_RWX.

     The values that inh can take are:
         UVM_INH_SHARE       Share the map.
         UVM_INH_COPY        Copy the map.
         UVM_INH_NONE        No inheritance.
         UVM_INH_MASK        Mask to extract inherit flags.

     The values that advice can take are:
         UVM_ADV_NORMAL      "Normal" use.
         UVM_ADV_RANDOM      "Random" access likelihood.
         UVM_ADV_SEQUENTIAL  "Sequential" access likelihood.
         UVM_ADV_MASK        Mask to extract the advice flags.

     The values that flags can take are:
         UVM_FLAG_FIXED      Attempt to map on the address specified by
                             startp.  Otherwise, it is used just as a hint.
         UVM_FLAG_OVERLAY    Establish overlay.
         UVM_FLAG_NOMERGE    Do not merge map entries, if such merge is
                             possible.
         UVM_FLAG_COPYONW    Use copy-on-write i.e. do not fault in the pages
                             immediately.
         UVM_FLAG_AMAPPAD    Used for BSS: allocate larger amap, if extending
                             is likely.
         UVM_FLAG_TRYLOCK    Fail if cannot acquire the lock immediately.
         UVM_FLAG_NOWAIT     Not allowed to sleep.  Fail, in such case.
         UVM_FLAG_QUANTUM    Indicates that map entry cannot be split once
                             mapped.
         UVM_FLAG_WAITVA     Sleep until VA space is available, if it is not.
         UVM_FLAG_VAONLY     Unmap only VA space.  Used by uvm_unmap().
         UVM_FLAG_UNMAP      Any existing entries in the range for this
                             mapping should be unmapped as part of creating
                             the new mapping.  Use of this flag without also
                             specifying UVM_FLAG_FIXED is a bug.

     The UVM_MAPFLAG macro arguments can be combined with an or operator.
     There are several special purpose macros for checking protection
     combinations, e.g., the UVM_PROT_WX.  There are also some additional
     macros to extract bits from the flags.  The UVM_PROTECTION, UVM_INHERIT,
     UVM_MAXPROTECTION and UVM_ADVICE macros return the protection,
     inheritance, maximum protection, and advice, respectively.  uvm_map()
     returns zero on success or error number otherwise.

     uvm_unmap() removes a valid mapping, from start to end, in map map, which
     must be unlocked.

     uvm_map_pageable() changes the pageability of the pages in the range from
     start to end in map map to new_pageable.  uvm_map_pageable() returns zero
     on success or error number otherwise.

     uvm_map_checkprot() checks the protection of the range from start to end
     in map map against protection.  This returns either true or false.

     uvm_map_protect() changes the protection start to end in map map to
     new_prot, also setting the maximum protection to the region to new_prot
     if set_max is true.  This function returns a standard UVM return value.

     uvm_map_protect_user() verifies that the new permissions honor PAX
     restrictions if applicable and forwards to uvm_map_protect() on passing.

     uvm_deallocate() deallocates kernel memory in map map from address start
     to start + size.

     uvmspace_alloc() allocates and returns a new address space, with ranges
     from min to max.

     uvmspace_exec() either reuses the address space of thread l (its process)
     if there are no other references to it, or creates a new one with
     uvmspace_alloc().  The range of valid addresses in the address space is
     reset to start through end.

     uvmspace_fork() creates and returns a new address space based upon the vm
     address space, typically used when allocating an address space for a
     child process.

     uvmspace_free() lowers the reference count on the address space vm,
     freeing the data structures if there are no other references.

     uvmspace_share() causes process p2 to share the address space of p1.

     uvm_uarea_alloc() allocates memory for a u-area (i.e. kernel stack, PCB,
     etc) and returns the address.

     uvm_uarea_free() frees a u-area allocated with uvm_uarea_alloc().

     uvm_uarea_system_alloc() and uvm_uarea_system_free() are optimized
     routines, which are used for kernel threads.

SEE ALSO
     pmap(9), uvm(9), uvm_km(9), vmem(9)

HISTORY
     UVM and uvm_map first appeared in NetBSD 1.4.

NetBSD 10.99                     May 20, 2017                     NetBSD 10.99