ubc_release(9) [netbsd man page]

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

NAME

     ubc -- unified buffer cache

SYNOPSIS

     #include <uvm/uvm.h>

     void *
     ubc_alloc(struct uvm_object *uobj, voff_t offset, vsize_t *lenp, int advice, int flags);

     void
     ubc_release(void *va, int flags);

     int
     ubc_uiomove(struct uvm_object *uobj, struct uio *uio, vsize_t todo, int advice, int flags);

     void
     ubc_purge(struct uvm_object *uobj);

DESCRIPTION

     ubc_alloc() creates a kernel mapping of uobj starting at offset offset.  The desired length of the mapping is pointed to by lenp, but the
     actual mapping may be smaller than this.  lenp is updated to contain the actual length mapped.  advice is the access pattern hint, which must
     be one of

	   UVM_ADV_NORMAL      No hint
	   UVM_ADV_RANDOM      Random access hint
	   UVM_ADV_SEQUENTIAL  Sequential access hint (from lower offset to higher offset)

     The possible flags are

	   UBC_READ	       Mapping will be accessed for read.
	   UBC_WRITE	       Mapping will be accessed for write.
	   UBC_FAULTBUSY       Fault in window's pages already during mapping operation.  Makes sense only for write.

     Once the mapping is created, it must be accessed only by methods that can handle faults, such as uiomove() or kcopy().  Page faults on the
     mapping will result in the object's pager method being called to resolve the fault.

     ubc_release() frees the mapping at va for reuse.  The mapping may be cached to speed future accesses to the same region of the object.  The
     flags can be any of

	   UBC_UNMAP	       Do not cache mapping.

     ubc_uiomove() allocates an UBC memory window, performs I/O on it and unmaps the window.  The advice parameter takes the same values as the
     respective parameter in ubc_alloc() and the flags parameter takes the same arguments as ubc_alloc() and ubc_release().  Additionally, the
     flag UBC_PARTIALOK can be provided to indicate that it is acceptable to return if an error occurs mid-transfer.

     ubc_purge() disassociates all UBC structures from an empty UVM object, specified by uobj.

CODE REFERENCES

     The ubc subsystem is implemented within the file sys/uvm/uvm_bio.c.

SEE ALSO

     pmap(9), uiomove(9), uvm(9), vnode(9), vnodeops(9)

     Chuck Silvers, "UBC: An Efficient Unified I/O and Memory Caching Subsystem for NetBSD", Proceedings of the FREENIX Track: 2000 USENIX Annual
     Technical Conference, USENIX Association, http://www.usenix.org/event/usenix2000/freenix/full_papers/silvers/silvers.pdf, 285-290, June
     18-23, 2000.

HISTORY

     UBC first appeared in NetBSD 1.6.

AUTHORS

     Chuck Silvers <chuq@chuq.com> designed and implemented the UBC part of UVM, which uses UVM pages to cache vnode data rather than the tradi-
     tional buffer cache buffers.

BSD
								   June 14, 2011							       BSD

UVM_MAP(9)						   BSD 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_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.  If 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.  If 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.

     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 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	 Mark to extract inherit flags.

     The values that advice can take are:

     UVM_ADV_NORMAL	 "Normal" use.

     UVM_ADV_RANDOM	 "Random" access likelyhood.

     UVM_ADV_SEQUENTIAL  "Sequential" access likelyhood.

     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	 User for BSS: alocate 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().

     The UVM_MAPFLAG macro arguments can be combined with an or operator.  There are several special purpose macros for checking protection combi-
     nations, 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_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 optimised 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.

BSD
								   June 3, 2011 							       BSD