| blob | cbb596ff0016c76a30b61dafd40918e6d732dbd1 |
1 .\" $NetBSD: uvm.9,v 1.100 2009/10/21 22:18:37 wiz Exp $
2 .\"
3 .\" Copyright (c) 1998 Matthew R. Green
4 .\" All rights reserved.
5 .\"
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
8 .\" are met:
9 .\" 1. Redistributions of source code must retain the above copyright
10 .\" notice, this list of conditions and the following disclaimer.
11 .\" 2. Redistributions in binary form must reproduce the above copyright
12 .\" notice, this list of conditions and the following disclaimer in the
13 .\" documentation and/or other materials provided with the distribution.
14 .\"
15 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
16 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
17 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
18 .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
19 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
20 .\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
21 .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
22 .\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
23 .\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
24 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
25 .\" SUCH DAMAGE.
26 .\"
27 .Dd December 21, 2009
28 .Dt UVM 9
29 .Os
30 .Sh NAME
31 .Nm uvm
32 .Nd virtual memory system external interface
33 .Sh SYNOPSIS
34 .In sys/param.h
35 .In uvm/uvm.h
36 .Sh DESCRIPTION
37 The UVM virtual memory system manages access to the computer's memory
38 resources.
39 User processes and the kernel access these resources through
40 UVM's external interface.
41 UVM's external interface includes functions that:
42 .Pp
43 .Bl -hyphen -compact
44 .It
45 initialize UVM sub-systems
46 .It
47 manage virtual address spaces
48 .It
49 resolve page faults
50 .It
51 memory map files and devices
52 .It
53 perform uio-based I/O to virtual memory
54 .It
55 allocate and free kernel virtual memory
56 .It
57 allocate and free physical memory
58 .El
59 .Pp
60 In addition to exporting these services, UVM has two kernel-level processes:
61 pagedaemon and swapper.
62 The pagedaemon process sleeps until physical memory becomes scarce.
63 When that happens, pagedaemon is awoken.
64 It scans physical memory, paging out and freeing memory that has not
65 been recently used.
66 The swapper process swaps in runnable processes that are currently swapped
67 out, if there is room.
68 .Pp
69 There are also several miscellaneous functions.
70 .Sh INITIALIZATION
71 .Bl -ohang
72 .It Ft void
73 .Fn uvm_init "void" ;
74 .It Ft void
75 .Fn uvm_init_limits "struct lwp *l" ;
76 .It Ft void
77 .Fn uvm_setpagesize "void" ;
78 .It Ft void
79 .Fn uvm_swap_init "void" ;
80 .El
81 .Pp
82 .Fn uvm_init
83 sets up the UVM system at system boot time, after the
84 console has been setup.
85 It initializes global state, the page, map, kernel virtual memory state,
86 machine-dependent physical map, kernel memory allocator,
87 pager and anonymous memory sub-systems, and then enables
88 paging of kernel objects.
89 .Pp
90 .Fn uvm_init_limits
91 initializes process limits for the named process.
92 This is for use by the system startup for process zero, before any
93 other processes are created.
94 .Pp
95 .Fn uvm_setpagesize
96 initializes the uvmexp members pagesize (if not already done by
97 machine-dependent code), pageshift and pagemask.
98 It should be called by machine-dependent code early in the
99 .Fn pmap_init
100 call (see
101 .Xr pmap 9 ) .
102 .Pp
103 .Fn uvm_swap_init
104 initializes the swap sub-system.
105 .Sh VIRTUAL ADDRESS SPACE MANAGEMENT
106 .Bl -ohang
107 .It Ft int
108 .Fn 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" ;
109 .It Ft void
110 .Fn uvm_unmap "struct vm_map *map" "vaddr_t start" "vaddr_t end" ;
111 .It Ft int
112 .Fn uvm_map_pageable "struct vm_map *map" "vaddr_t start" "vaddr_t end" "bool new_pageable" "int lockflags" ;
113 .It Ft bool
114 .Fn uvm_map_checkprot "struct vm_map *map" "vaddr_t start" "vaddr_t end" "vm_prot_t protection" ;
115 .It Ft int
116 .Fn uvm_map_protect "struct vm_map *map" "vaddr_t start" "vaddr_t end" "vm_prot_t new_prot" "bool set_max" ;
117 .It Ft int
118 .Fn uvm_deallocate "struct vm_map *map" "vaddr_t start" "vsize_t size" ;
119 .It Ft struct vmspace *
120 .Fn uvmspace_alloc "vaddr_t min" "vaddr_t max" "int pageable" ;
121 .It Ft void
122 .Fn uvmspace_exec "struct lwp *l" "vaddr_t start" "vaddr_t end" ;
123 .It Ft struct vmspace *
124 .Fn uvmspace_fork "struct vmspace *vm" ;
125 .It Ft void
126 .Fn uvmspace_free "struct vmspace *vm1" ;
127 .It Ft void
128 .Fn uvmspace_share "struct proc *p1" "struct proc *p2" ;
129 .It Ft void
130 .Fn uvmspace_unshare "struct lwp *l" ;
131 .It Ft bool
132 .Fn uvm_uarea_alloc "vaddr_t *uaddrp" ;
133 .It Ft void
134 .Fn uvm_uarea_free "vaddr_t uaddr" ;
135 .El
136 .Pp
137 .Fn uvm_map
138 establishes a valid mapping in map
139 .Fa map ,
140 which must be unlocked.
141 The new mapping has size
142 .Fa size ,
143 which must be a multiple of
144 .Dv PAGE_SIZE .
145 The
146 .Fa uobj
147 and
148 .Fa uoffset
149 arguments can have four meanings.
150 When
151 .Fa uobj
152 is
153 .Dv NULL
154 and
155 .Fa uoffset
156 is
157 .Dv UVM_UNKNOWN_OFFSET ,
158 .Fn uvm_map
159 does not use the machine-dependent
160 .Dv PMAP_PREFER
161 function.
162 If
163 .Fa uoffset
164 is any other value, it is used as the hint to
165 .Dv PMAP_PREFER .
166 When
167 .Fa uobj
168 is not
169 .Dv NULL
170 and
171 .Fa uoffset
172 is
173 .Dv UVM_UNKNOWN_OFFSET ,
174 .Fn uvm_map
175 finds the offset based upon the virtual address, passed as
176 .Fa startp .
177 If
178 .Fa uoffset
179 is any other value, we are doing a normal mapping at this offset.
180 The start address of the map will be returned in
181 .Fa startp .
182 .Pp
183 .Fa align
184 specifies alignment of mapping unless
185 .Dv UVM_FLAG_FIXED
186 is specified in
187 .Fa flags .
188 .Fa align
189 must be a power of 2.
190 .Pp
191 .Fa flags
192 passed to
193 .Fn uvm_map
194 are typically created using the
195 .Fn UVM_MAPFLAG "vm_prot_t prot" "vm_prot_t maxprot" "vm_inherit_t inh" "int advice" "int flags"
196 macro, which uses the following values.
197 The
198 .Fa prot
199 and
200 .Fa maxprot
201 can take are:
202 .Bd -literal
203 #define UVM_PROT_MASK 0x07 /* protection mask */
204 #define UVM_PROT_NONE 0x00 /* protection none */
205 #define UVM_PROT_ALL 0x07 /* everything */
206 #define UVM_PROT_READ 0x01 /* read */
207 #define UVM_PROT_WRITE 0x02 /* write */
208 #define UVM_PROT_EXEC 0x04 /* exec */
209 #define UVM_PROT_R 0x01 /* read */
210 #define UVM_PROT_W 0x02 /* write */
211 #define UVM_PROT_RW 0x03 /* read-write */
212 #define UVM_PROT_X 0x04 /* exec */
213 #define UVM_PROT_RX 0x05 /* read-exec */
214 #define UVM_PROT_WX 0x06 /* write-exec */
215 #define UVM_PROT_RWX 0x07 /* read-write-exec */
216 .Ed
217 .Pp
218 The values that
219 .Fa inh
220 can take are:
221 .Bd -literal
222 #define UVM_INH_MASK 0x30 /* inherit mask */
223 #define UVM_INH_SHARE 0x00 /* "share" */
224 #define UVM_INH_COPY 0x10 /* "copy" */
225 #define UVM_INH_NONE 0x20 /* "none" */
226 #define UVM_INH_DONATE 0x30 /* "donate" \*[Lt]\*[Lt] not used */
227 .Ed
228 .Pp
229 The values that
230 .Fa advice
231 can take are:
232 .Bd -literal
233 #define UVM_ADV_NORMAL 0x0 /* 'normal' */
234 #define UVM_ADV_RANDOM 0x1 /* 'random' */
235 #define UVM_ADV_SEQUENTIAL 0x2 /* 'sequential' */
236 #define UVM_ADV_MASK 0x7 /* mask */
237 .Ed
238 .Pp
239 The values that
240 .Fa flags
241 can take are:
242 .Bd -literal
243 #define UVM_FLAG_FIXED 0x010000 /* find space */
244 #define UVM_FLAG_OVERLAY 0x020000 /* establish overlay */
245 #define UVM_FLAG_NOMERGE 0x040000 /* don't merge map entries */
246 #define UVM_FLAG_COPYONW 0x080000 /* set copy_on_write flag */
247 #define UVM_FLAG_AMAPPAD 0x100000 /* for bss: pad amap to reduce malloc() */
248 #define UVM_FLAG_TRYLOCK 0x200000 /* fail if we can not lock map */
249 .Ed
250 .Pp
251 The
252 .Dv UVM_MAPFLAG
253 macro arguments can be combined with an or operator.
254 There are several special purpose macros for checking protection
255 combinations, e.g., the
256 .Dv UVM_PROT_WX
257 macro.
258 There are also some additional macros to extract bits from the flags.
259 The
260 .Dv UVM_PROTECTION ,
261 .Dv UVM_INHERIT ,
262 .Dv UVM_MAXPROTECTION
263 and
264 .Dv UVM_ADVICE
265 macros return the protection, inheritance, maximum protection and advice,
266 respectively.
267 .Fn uvm_map
268 returns a standard UVM return value.
269 .Pp
270 .Fn uvm_unmap
271 removes a valid mapping,
272 from
273 .Fa start
274 to
275 .Fa end ,
276 in map
277 .Fa map ,
278 which must be unlocked.
279 .Pp
280 .Fn uvm_map_pageable
281 changes the pageability of the pages in the range from
282 .Fa start
283 to
284 .Fa end
285 in map
286 .Fa map
287 to
288 .Fa new_pageable .
289 .Fn uvm_map_pageable
290 returns a standard UVM return value.
291 .Pp
292 .Fn uvm_map_checkprot
293 checks the protection of the range from
294 .Fa start
295 to
296 .Fa end
297 in map
298 .Fa map
299 against
300 .Fa protection .
301 This returns either
302 .Dv true
303 or
304 .Dv false .
305 .Pp
306 .Fn uvm_map_protect
307 changes the protection
308 .Fa start
309 to
310 .Fa end
311 in map
312 .Fa map
313 to
314 .Fa new_prot ,
315 also setting the maximum protection to the region to
316 .Fa new_prot
317 if
318 .Fa set_max
319 is true.
320 This function returns a standard UVM return value.
321 .Pp
322 .Fn uvm_deallocate
323 deallocates kernel memory in map
324 .Fa map
325 from address
326 .Fa start
327 to
328 .Fa start + size .
329 .Pp
330 .Fn uvmspace_alloc
331 allocates and returns a new address space, with ranges from
332 .Fa min
333 to
334 .Fa max ,
335 setting the pageability of the address space to
336 .Fa pageable .
337 .Pp
338 .Fn uvmspace_exec
339 either reuses the address space of lwp
340 .Fa l
341 if there are no other references to it, or creates
342 a new one with
343 .Fn uvmspace_alloc .
344 The range of valid addresses in the address space is reset to
345 .Fa start
346 through
347 .Fa end .
348 .Pp
349 .Fn uvmspace_fork
350 creates and returns a new address space based upon the
351 .Fa vm1
352 address space, typically used when allocating an address space for a
353 child process.
354 .Pp
355 .Fn uvmspace_free
356 lowers the reference count on the address space
357 .Fa vm ,
358 freeing the data structures if there are no other references.
359 .Pp
360 .Fn uvmspace_share
361 causes process
362 .Pa p2
363 to share the address space of
364 .Fa p1 .
365 .Pp
366 .Fn uvmspace_unshare
367 ensures that lwp
368 .Fa l
369 has its own, unshared address space, by creating a new one if
370 necessary by calling
371 .Fn uvmspace_fork .
372 .Pp
373 .Fn uvm_uarea_alloc
374 allocates virtual space for a u-area (i.e., a kernel stack) and stores
375 its virtual address in
376 .Fa *uaddrp .
377 The return value is
378 .Dv true
379 if the u-area is already backed by wired physical memory, otherwise
380 .Dv false .
381 .Pp
382 .Fn uvm_uarea_free
383 frees a u-area allocated with
384 .Fn uvm_uarea_alloc ,
385 freeing both the virtual space and any physical pages which may have been
386 allocated to back that virtual space later.
387 .Sh PAGE FAULT HANDLING
388 .Bl -ohang
389 .It Ft int
390 .Fn uvm_fault "struct vm_map *orig_map" "vaddr_t vaddr" "vm_prot_t access_type" ;
391 .El
392 .Pp
393 .Fn uvm_fault
394 is the main entry point for faults.
395 It takes
396 .Fa orig_map
397 as the map the fault originated in, a
398 .Fa vaddr
399 offset into the map the fault occurred, and
400 .Fa access_type
401 describing the type of access requested.
402 .Fn uvm_fault
403 returns a standard UVM return value.
404 .Sh VIRTUAL MEMORY I/O
405 .Bl -ohang
406 .It Ft int
407 .Fn uvm_io "struct vm_map *map" "struct uio *uio" ;
408 .El
409 .Pp
410 .Fn uvm_io
411 performs the I/O described in
412 .Fa uio
413 on the memory described in
414 .Fa map .
415 .Sh ALLOCATION OF KERNEL MEMORY
416 .Bl -ohang
417 .It Ft vaddr_t
418 .Fn uvm_km_alloc "struct vm_map *map" "vsize_t size" "vsize_t align" "uvm_flag_t flags" ;
419 .It Ft void
420 .Fn uvm_km_free "struct vm_map *map" "vaddr_t addr" "vsize_t size" "uvm_flag_t flags" ;
421 .It Ft struct vm_map *
422 .Fn uvm_km_suballoc "struct vm_map *map" "vaddr_t *min" "vaddr_t *max" \
423 "vsize_t size" "int flags" "bool fixed" "struct vm_map *submap" ;
424 .El
425 .Pp
426 .Fn uvm_km_alloc
427 allocates
428 .Fa size
429 bytes of kernel memory in map
430 .Fa map .
431 The first address of the allocated memory range will be aligned according to the
432 .Fa align
433 argument
434 .Pq specify 0 if no alignment is necessary .
435 The alignment must be a multiple of page size.
436 The
437 .Fa flags
438 is a bitwise inclusive OR of the allocation type and operation flags.
439 .Pp
440 The allocation type should be one of:
441 .Bl -tag -width UVM_KMF_PAGEABLE
442 .It UVM_KMF_WIRED
443 Wired memory.
444 .It UVM_KMF_PAGEABLE
445 Demand-paged zero-filled memory.
446 .It UVM_KMF_VAONLY
447 Virtual address only.
448 No physical pages are mapped in the allocated region.
449 If necessary, it's the caller's responsibility to enter page mappings.
450 It's also the caller's responsibility to clean up the mappings before freeing
451 the address range.
452 .El
453 .Pp
454 The following operation flags are available:
455 .Bl -tag -width UVM_KMF_PAGEABLE
456 .It UVM_KMF_CANFAIL
457 Can fail even if
458 .Dv UVM_KMF_NOWAIT
459 is not specified and
460 .Dv UVM_KMF_WAITVA
461 is specified.
462 .It UVM_KMF_ZERO
463 Request zero-filled memory.
464 Only supported for
465 .Dv UVM_KMF_WIRED .
466 Shouldn't be used with other types.
467 .It UVM_KMF_TRYLOCK
468 Fail if we can't lock the map.
469 .It UVM_KMF_NOWAIT
470 Fail immediately if no memory is available.
471 .It UVM_KMF_WAITVA
472 Sleep to wait for the virtual address resources if needed.
473 .El
474 .Pp
475 (If neither
476 .Dv UVM_KMF_NOWAIT
477 nor
478 .Dv UVM_KMF_CANFAIL
479 are specified and
480 .Dv UVM_KMF_WAITVA
481 is specified,
482 .Fn uvm_km_alloc
483 will never fail, but rather sleep indefinitely until the allocation succeeds.)
484 .Pp
485 Pageability of the pages allocated with
486 .Dv UVM_KMF_PAGEABLE
487 can be changed by
488 .Fn uvm_map_pageable .
489 In that case, the entire range must be changed atomically.
490 Changing a part of the range is not supported.
491 .Pp
492 .Fn uvm_km_free
493 frees the memory range allocated by
494 .Fn uvm_km_alloc .
495 .Fa addr
496 must be an address returned by
497 .Fn uvm_km_alloc .
498 .Fa map
499 and
500 .Fa size
501 must be the same as the ones used for the corresponding
502 .Fn uvm_km_alloc .
503 .Fa flags
504 must be the allocation type used for the corresponding
505 .Fn uvm_km_alloc .
506 .Pp
507 .Fn uvm_km_free
508 is the only way to free memory ranges allocated by
509 .Fn uvm_km_alloc .
510 .Fn uvm_unmap
511 must not be used.
512 .Pp
513 .Fn uvm_km_suballoc
514 allocates submap from
515 .Fa map ,
516 creating a new map if
517 .Fa submap
518 is
519 .Dv NULL .
520 The addresses of the submap can be specified exactly by setting the
521 .Fa fixed
522 argument to true, which causes the
523 .Fa min
524 argument to specify the beginning of the address in the submap.
525 If
526 .Fa fixed
527 is false, any address of size
528 .Fa size
529 will be allocated from
530 .Fa map
531 and the start and end addresses returned in
532 .Fa min
533 and
534 .Fa max .
535 The
536 .Fa flags
537 are used to initialize the created submap.
538 The following flags could be set:
539 .Bl -tag -width VM_MAP_PAGEABLE
540 .It VM_MAP_PAGEABLE
541 Entries in the map may be paged out.
542 .It VM_MAP_INTRSAFE
543 Map should be interrupt-safe.
544 .It VM_MAP_TOPDOWN
545 A top-down mapping should be arranged.
546 .El
547 .Sh ALLOCATION OF PHYSICAL MEMORY
548 .Bl -ohang
549 .It Ft struct vm_page *
550 .Fn uvm_pagealloc "struct uvm_object *uobj" "voff_t off" "struct vm_anon *anon" "int flags" ;
551 .It Ft void
552 .Fn uvm_pagerealloc "struct vm_page *pg" "struct uvm_object *newobj" "voff_t newoff" ;
553 .It Ft void
554 .Fn uvm_pagefree "struct vm_page *pg" ;
555 .It Ft int
556 .Fn uvm_pglistalloc "psize_t size" "paddr_t low" "paddr_t high" "paddr_t alignment" "paddr_t boundary" "struct pglist *rlist" "int nsegs" "int waitok" ;
557 .It Ft void
558 .Fn uvm_pglistfree "struct pglist *list" ;
559 .It Ft void
560 .Fn uvm_page_physload "paddr_t start" "paddr_t end" "paddr_t avail_start" "paddr_t avail_end" "int free_list" ;
561 .El
562 .Pp
563 .Fn uvm_pagealloc
564 allocates a page of memory at virtual address
565 .Fa off
566 in either the object
567 .Fa uobj
568 or the anonymous memory
569 .Fa anon ,
570 which must be locked by the caller.
571 Only one of
572 .Fa uobj
573 and
574 .Fa anon
575 can be non
576 .Dv NULL .
577 Returns
578 .Dv NULL
579 when no page can be found.
580 The flags can be any of
581 .Bd -literal
582 #define UVM_PGA_USERESERVE 0x0001 /* ok to use reserve pages */
583 #define UVM_PGA_ZERO 0x0002 /* returned page must be zero'd */
584 .Ed
585 .Pp
586 .Dv UVM_PGA_USERESERVE
587 means to allocate a page even if that will result in the number of free pages
588 being lower than
589 .Dv uvmexp.reserve_pagedaemon
590 (if the current thread is the pagedaemon) or
591 .Dv uvmexp.reserve_kernel
592 (if the current thread is not the pagedaemon).
593 .Dv UVM_PGA_ZERO
594 causes the returned page to be filled with zeroes, either by allocating it
595 from a pool of pre-zeroed pages or by zeroing it in-line as necessary.
596 .Pp
597 .Fn uvm_pagerealloc
598 reallocates page
599 .Fa pg
600 to a new object
601 .Fa newobj ,
602 at a new offset
603 .Fa newoff .
604 .Pp
605 .Fn uvm_pagefree
606 frees the physical page
607 .Fa pg .
608 If the content of the page is known to be zero-filled,
609 caller should set
610 .Dv PG_ZERO
611 in pg-\*[Gt]flags so that the page allocator will use
612 the page to serve future
613 .Dv UVM_PGA_ZERO
614 requests efficiently.
615 .Pp
616 .Fn uvm_pglistalloc
617 allocates a list of pages for size
618 .Fa size
619 byte under various constraints.
620 .Fa low
621 and
622 .Fa high
623 describe the lowest and highest addresses acceptable for the list.
624 If
625 .Fa alignment
626 is non-zero, it describes the required alignment of the list, in
627 power-of-two notation.
628 If
629 .Fa boundary
630 is non-zero, no segment of the list may cross this power-of-two
631 boundary, relative to zero.
632 .Fa nsegs
633 is the maximum number of physically contiguous segments.
634 If
635 .Fa waitok
636 is non-zero, the function may sleep until enough memory is available.
637 (It also may give up in some situations, so a non-zero
638 .Fa waitok
639 does not imply that
640 .Fn uvm_pglistalloc
641 cannot return an error.)
642 The allocated memory is returned in the
643 .Fa rlist
644 list; the caller has to provide storage only, the list is initialized by
645 .Fn uvm_pglistalloc .
646 .Pp
647 .Fn uvm_pglistfree
648 frees the list of pages pointed to by
649 .Fa list .
650 If the content of the page is known to be zero-filled,
651 caller should set
652 .Dv PG_ZERO
653 in pg-\*[Gt]flags so that the page allocator will use
654 the page to serve future
655 .Dv UVM_PGA_ZERO
656 requests efficiently.
657 .Pp
658 .Fn uvm_page_physload
659 loads physical memory segments into VM space on the specified
660 .Fa free_list .
661 It must be called at system boot time to set up physical memory
662 management pages.
663 The arguments describe the
664 .Fa start
665 and
666 .Fa end
667 of the physical addresses of the segment, and the available start and end
668 addresses of pages not already in use.
669 If a system has memory banks of
670 different speeds the slower memory should be given a higher
671 .Fa free_list
672 value.
673 .\" XXX expand on "system boot time"!
674 .Sh PROCESSES
675 .Bl -ohang
676 .It Ft void
677 .Fn uvm_pageout "void" ;
678 .It Ft void
679 .Fn uvm_scheduler "void" ;
680 .El
681 .Pp
682 .Fn uvm_pageout
683 is the main loop for the page daemon.
684 .Pp
685 .Fn uvm_scheduler
686 is the process zero main loop, which is to be called after the
687 system has finished starting other processes.
688 It handles the swapping in of runnable, swapped out processes in priority
689 order.
690 .Sh PAGE LOAN
691 .Bl -ohang
692 .It Ft int
693 .Fn uvm_loan "struct vm_map *map" "vaddr_t start" "vsize_t len" "void *v" "int flags" ;
694 .It Ft void
695 .Fn uvm_unloan "void *v" "int npages" "int flags" ;
696 .El
697 .Pp
698 .Fn uvm_loan
699 loans pages in a map out to anons or to the kernel.
700 .Fa map
701 should be unlocked,
702 .Fa start
703 and
704 .Fa len
705 should be multiples of
706 .Dv PAGE_SIZE .
707 Argument
708 .Fa flags
709 should be one of
710 .Bd -literal
711 #define UVM_LOAN_TOANON 0x01 /* loan to anons */
712 #define UVM_LOAN_TOPAGE 0x02 /* loan to kernel */
713 .Ed
714 .Pp
715 .Fa v
716 should be pointer to array of pointers to
717 .Li struct anon
718 or
719 .Li struct vm_page ,
720 as appropriate.
721 The caller has to allocate memory for the array and
722 ensure it's big enough to hold
723 .Fa len / PAGE_SIZE
724 pointers.
725 Returns 0 for success, or appropriate error number otherwise.
726 Note that wired pages can't be loaned out and
727 .Fn uvm_loan
728 will fail in that case.
729 .Pp
730 .Fn uvm_unloan
731 kills loans on pages or anons.
732 The
733 .Fa v
734 must point to the array of pointers initialized by previous call to
735 .Fn uvm_loan .
736 .Fa npages
737 should match number of pages allocated for loan, this also matches
738 number of items in the array.
739 Argument
740 .Fa flags
741 should be one of
742 .Bd -literal
743 #define UVM_LOAN_TOANON 0x01 /* loan to anons */
744 #define UVM_LOAN_TOPAGE 0x02 /* loan to kernel */
745 .Ed
746 .Pp
747 and should match what was used for previous call to
748 .Fn uvm_loan .
749 .Sh MISCELLANEOUS FUNCTIONS
750 .Bl -ohang
751 .It Ft struct uvm_object *
752 .Fn uao_create "vsize_t size" "int flags" ;
753 .It Ft void
754 .Fn uao_detach "struct uvm_object *uobj" ;
755 .It Ft void
756 .Fn uao_reference "struct uvm_object *uobj" ;
757 .It Ft bool
758 .Fn uvm_chgkprot "void *addr" "size_t len" "int rw" ;
759 .It Ft void
760 .Fn uvm_kernacc "void *addr" "size_t len" "int rw" ;
761 .It Ft int
762 .Fn uvm_vslock "struct vmspace *vs" "void *addr" "size_t len" "vm_prot_t prot" ;
763 .It Ft void
764 .Fn uvm_vsunlock "struct vmspace *vs" "void *addr" "size_t len" ;
765 .It Ft void
766 .Fn uvm_meter "void" ;
767 .It Ft void
768 .Fn uvm_proc_fork "struct proc *p1" "struct proc *p2" "bool shared" ;
769 .It Ft int
770 .Fn uvm_grow "struct proc *p" "vaddr_t sp" ;
771 .It Ft void
772 .Fn uvn_findpages "struct uvm_object *uobj" "voff_t offset" "int *npagesp" "struct vm_page **pps" "int flags" ;
773 .It Ft void
774 .Fn uvm_vnp_setsize "struct vnode *vp" "voff_t newsize" ;
775 .It Ft void
776 .Fn uvm_swap_stats "int cmd" "struct swapent *sep" "int sec" "register_t *retval" ;
777 .El
778 .Pp
779 The
780 .Fn uao_create ,
781 .Fn uao_detach ,
782 and
783 .Fn uao_reference
784 functions operate on anonymous memory objects, such as those used to support
785 System V shared memory.
786 .Fn uao_create
787 returns an object of size
788 .Fa size
789 with flags:
790 .Bd -literal
791 #define UAO_FLAG_KERNOBJ 0x1 /* create kernel object */
792 #define UAO_FLAG_KERNSWAP 0x2 /* enable kernel swap */
793 .Ed
794 .Pp
795 which can only be used once each at system boot time.
796 .Fn uao_reference
797 creates an additional reference to the named anonymous memory object.
798 .Fn uao_detach
799 removes a reference from the named anonymous memory object, destroying
800 it if removing the last reference.
801 .Pp
802 .Fn uvm_chgkprot
803 changes the protection of kernel memory from
804 .Fa addr
805 to
806 .Fa addr + len
807 to the value of
808 .Fa rw .
809 This is primarily useful for debuggers, for setting breakpoints.
810 This function is only available with options
811 .Dv KGDB .
812 .Pp
813 .Fn uvm_kernacc
814 checks the access at address
815 .Fa addr
816 to
817 .Fa addr + len
818 for
819 .Fa rw
820 access in the kernel address space.
821 .Pp
822 .Fn uvm_vslock
823 and
824 .Fn uvm_vsunlock
825 control the wiring and unwiring of pages for process
826 .Fa p
827 from
828 .Fa addr
829 to
830 .Fa addr + len .
831 These functions are normally used to wire memory for I/O.
832 .Pp
833 .Fn uvm_meter
834 calculates the load average.
835 .Pp
836 .Fn uvm_proc_fork
837 forks a virtual address space for process' (old)
838 .Fa p1
839 and (new)
840 .Fa p2 .
841 If the
842 .Fa shared
843 argument is non zero, p1 shares its address space with p2,
844 otherwise a new address space is created.
845 This function currently has no return value, and thus cannot fail.
846 In the future, this function will be changed to allow it to
847 fail in low memory conditions.
848 .Pp
849 .Fn uvm_grow
850 increases the stack segment of process
851 .Fa p
852 to include
853 .Fa sp .
854 .Pp
855 .Fn uvn_findpages
856 looks up or creates pages in
857 .Fa uobj
858 at offset
859 .Fa offset ,
860 marks them busy and returns them in the
861 .Fa pps
862 array.
863 Currently
864 .Fa uobj
865 must be a vnode object.
866 The number of pages requested is pointed to by
867 .Fa npagesp ,
868 and this value is updated with the actual number of pages returned.
869 The flags can be
870 .Bd -literal
871 #define UFP_ALL 0x00 /* return all pages requested */
872 #define UFP_NOWAIT 0x01 /* don't sleep */
873 #define UFP_NOALLOC 0x02 /* don't allocate new pages */
874 #define UFP_NOCACHE 0x04 /* don't return pages which already exist */
875 #define UFP_NORDONLY 0x08 /* don't return PG_READONLY pages */
876 .Ed
877 .Pp
878 .Dv UFP_ALL
879 is a pseudo-flag meaning all requested pages should be returned.
880 .Dv UFP_NOWAIT
881 means that we must not sleep.
882 .Dv UFP_NOALLOC
883 causes any pages which do not already exist to be skipped.
884 .Dv UFP_NOCACHE
885 causes any pages which do already exist to be skipped.
886 .Dv UFP_NORDONLY
887 causes any pages which are marked PG_READONLY to be skipped.
888 .Pp
889 .Fn uvm_vnp_setsize
890 sets the size of vnode
891 .Fa vp
892 to
893 .Fa newsize .
894 Caller must hold a reference to the vnode.
895 If the vnode shrinks, pages no longer used are discarded.
896 .Pp
897 .Fn uvm_swap_stats
898 implements the
899 .Dv SWAP_STATS
900 and
901 .Dv SWAP_OSTATS
902 operation of the
903 .Xr swapctl 2
904 system call.
905 .Fa cmd
906 is the requested command,
907 .Dv SWAP_STATS
908 or
909 .Dv SWAP_OSTATS .
910 The function will copy no more than
911 .Fa sec
912 entries in the array pointed by
913 .Fa sep .
914 On return,
915 .Fa retval
916 holds the actual number of entries copied in the array.
917 .Sh SYSCTL
918 UVM provides support for the
919 .Dv CTL_VM
920 domain of the
921 .Xr sysctl 3
922 hierarchy.
923 It handles the
924 .Dv VM_LOADAVG ,
925 .Dv VM_METER ,
926 .Dv VM_UVMEXP ,
927 and
928 .Dv VM_UVMEXP2
929 nodes, which return the current load averages, calculates current VM
930 totals, returns the uvmexp structure, and a kernel version independent
931 view of the uvmexp structure, respectively.
932 It also exports a number of tunables that control how much VM space is
933 allowed to be consumed by various tasks.
934 The load averages are typically accessed from userland using the
935 .Xr getloadavg 3
936 function.
937 The uvmexp structure has all global state of the UVM system,
938 and has the following members:
939 .Bd -literal
940 /* vm_page constants */
941 int pagesize; /* size of a page (PAGE_SIZE): must be power of 2 */
942 int pagemask; /* page mask */
943 int pageshift; /* page shift */
945 /* vm_page counters */
946 int npages; /* number of pages we manage */
947 int free; /* number of free pages */
948 int active; /* number of active pages */
949 int inactive; /* number of pages that we free'd but may want back */
950 int paging; /* number of pages in the process of being paged out */
951 int wired; /* number of wired pages */
952 int reserve_pagedaemon; /* number of pages reserved for pagedaemon */
953 int reserve_kernel; /* number of pages reserved for kernel */
955 /* pageout params */
956 int freemin; /* min number of free pages */
957 int freetarg; /* target number of free pages */
958 int inactarg; /* target number of inactive pages */
959 int wiredmax; /* max number of wired pages */
961 /* swap */
962 int nswapdev; /* number of configured swap devices in system */
963 int swpages; /* number of PAGE_SIZE'ed swap pages */
964 int swpginuse; /* number of swap pages in use */
965 int nswget; /* number of times fault calls uvm_swap_get() */
966 int nanon; /* number total of anon's in system */
967 int nfreeanon; /* number of free anon's */
969 /* stat counters */
970 int faults; /* page fault count */
971 int traps; /* trap count */
972 int intrs; /* interrupt count */
973 int swtch; /* context switch count */
974 int softs; /* software interrupt count */
975 int syscalls; /* system calls */
976 int pageins; /* pagein operation count */
977 /* pageouts are in pdpageouts below */
978 int pgswapin; /* pages swapped in */
979 int pgswapout; /* pages swapped out */
980 int forks; /* forks */
981 int forks_ppwait; /* forks where parent waits */
982 int forks_sharevm; /* forks where vmspace is shared */
984 /* fault subcounters */
985 int fltnoram; /* number of times fault was out of ram */
986 int fltnoanon; /* number of times fault was out of anons */
987 int fltpgwait; /* number of times fault had to wait on a page */
988 int fltpgrele; /* number of times fault found a released page */
989 int fltrelck; /* number of times fault relock called */
990 int fltrelckok; /* number of times fault relock is a success */
991 int fltanget; /* number of times fault gets anon page */
992 int fltanretry; /* number of times fault retrys an anon get */
993 int fltamcopy; /* number of times fault clears "needs copy" */
994 int fltnamap; /* number of times fault maps a neighbor anon page */
995 int fltnomap; /* number of times fault maps a neighbor obj page */
996 int fltlget; /* number of times fault does a locked pgo_get */
997 int fltget; /* number of times fault does an unlocked get */
998 int flt_anon; /* number of times fault anon (case 1a) */
999 int flt_acow; /* number of times fault anon cow (case 1b) */
1000 int flt_obj; /* number of times fault is on object page (2a) */
1001 int flt_prcopy; /* number of times fault promotes with copy (2b) */
1002 int flt_przero; /* number of times fault promotes with zerofill (2b) */
1004 /* daemon counters */
1005 int pdwoke; /* number of times daemon woke up */
1006 int pdrevs; /* number of times daemon rev'd clock hand */
1007 int pdfreed; /* number of pages daemon freed since boot */
1008 int pdscans; /* number of pages daemon scanned since boot */
1009 int pdanscan; /* number of anonymous pages scanned by daemon */
1010 int pdobscan; /* number of object pages scanned by daemon */
1011 int pdreact; /* number of pages daemon reactivated since boot */
1012 int pdbusy; /* number of times daemon found a busy page */
1013 int pdpageouts; /* number of times daemon started a pageout */
1014 int pdpending; /* number of times daemon got a pending pageout */
1015 int pddeact; /* number of pages daemon deactivates */
1016 .Ed
1017 .Sh NOTES
1018 .Fn uvm_chgkprot
1019 is only available if the kernel has been compiled with options
1020 .Dv KGDB .
1021 .Pp
1022 All structure and types whose names begin with
1023 .Dq vm_
1024 will be renamed to
1025 .Dq uvm_ .
1026 .Sh SEE ALSO
1027 .Xr swapctl 2 ,
1028 .Xr getloadavg 3 ,
1029 .Xr kvm 3 ,
1030 .Xr sysctl 3 ,
1031 .Xr ddb 4 ,
1032 .Xr options 4 ,
1033 .Xr memoryallocators 9 ,
1034 .Xr pmap 9 ,
1035 .Xr ubc 9
1036 .Sh HISTORY
1037 UVM is a new VM system developed at Washington University in St. Louis
1038 (Missouri).
1039 UVM's roots lie partly in the Mach-based
1040 .Bx 4.4
1041 VM system, the
1042 .Fx
1043 VM system, and the SunOS 4 VM system.
1044 UVM's basic structure is based on the
1045 .Bx 4.4
1046 VM system.
1047 UVM's new anonymous memory system is based on the
1048 anonymous memory system found in the SunOS 4 VM (as described in papers
1049 published by Sun Microsystems, Inc.).
1050 UVM also includes a number of features new to
1051 .Bx
1052 including page loanout, map entry passing, simplified
1053 copy-on-write, and clustered anonymous memory pageout.
1054 UVM is also further documented in an August 1998 dissertation by
1055 Charles D. Cranor.
1056 .Pp
1057 UVM appeared in
1058 .Nx 1.4 .
1059 .Sh AUTHORS
1060 Charles D. Cranor
1061 .Aq chuck@ccrc.wustl.edu
1062 designed and implemented UVM.
1063 .Pp
1064 Matthew Green
1065 .Aq mrg@eterna.com.au
1066 wrote the swap-space management code and handled the logistical issues
1067 involved with merging UVM into the
1068 .Nx
1069 source tree.
1070 .Pp
1071 Chuck Silvers
1072 .Aq chuq@chuq.com
1073 implemented the aobj pager, thus allowing UVM to support System V shared
1074 memory and process swapping.