Tue Apr 14 13:35:33 2015 UTC ()
Pull up following revision(s) (requested by riastradh in ticket #1275):
	share/man/man9/uvm_km.9: revision 1.4
Clarify uvm_km_alloc is contiguous and zero result means fail.


(msaitoh)
diff -r1.2.4.1 -r1.2.4.2 src/share/man/man9/uvm_km.9
cvs diff -r1.2.4.1 -r1.2.4.2 src/share/man/man9/uvm_km.9 (switch to unified diff)

--- src/share/man/man9/uvm_km.9 2014/09/29 18:38:09 1.2.4.1
+++ src/share/man/man9/uvm_km.9 2015/04/14 13:35:33 1.2.4.2
@@ -1,184 +1,185 @@ @@ -1,184 +1,185 @@
1.\" $NetBSD: uvm_km.9,v 1.2.4.1 2014/09/29 18:38:09 msaitoh Exp $ 1.\" $NetBSD: uvm_km.9,v 1.2.4.2 2015/04/14 13:35:33 msaitoh Exp $
2.\" 2.\"
3.\" Copyright (c) 1998 Matthew R. Green 3.\" Copyright (c) 1998 Matthew R. Green
4.\" All rights reserved. 4.\" All rights reserved.
5.\" 5.\"
6.\" Redistribution and use in source and binary forms, with or without 6.\" Redistribution and use in source and binary forms, with or without
7.\" modification, are permitted provided that the following conditions 7.\" modification, are permitted provided that the following conditions
8.\" are met: 8.\" are met:
9.\" 1. Redistributions of source code must retain the above copyright 9.\" 1. Redistributions of source code must retain the above copyright
10.\" notice, this list of conditions and the following disclaimer. 10.\" notice, this list of conditions and the following disclaimer.
11.\" 2. Redistributions in binary form must reproduce the above copyright 11.\" 2. Redistributions in binary form must reproduce the above copyright
12.\" notice, this list of conditions and the following disclaimer in the 12.\" notice, this list of conditions and the following disclaimer in the
13.\" documentation and/or other materials provided with the distribution. 13.\" documentation and/or other materials provided with the distribution.
14.\" 14.\"
15.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 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 16.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
17.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 17.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
18.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 18.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
19.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, 19.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
20.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 20.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
21.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED 21.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
22.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 22.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
23.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 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 24.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
25.\" SUCH DAMAGE. 25.\" SUCH DAMAGE.
26.\" 26.\"
27.Dd June 3, 2011 27.Dd June 3, 2011
28.Dt UVM_KM 9 28.Dt UVM_KM 9
29.Os 29.Os
30.Sh NAME 30.Sh NAME
31.Nm uvm_km 31.Nm uvm_km
32.Nd raw kernel memory or address space allocator 32.Nd raw kernel memory or address space allocator
33.Sh SYNOPSIS 33.Sh SYNOPSIS
34.In sys/param.h 34.In sys/param.h
35.In uvm/uvm.h 35.In uvm/uvm.h
36.Ft vaddr_t 36.Ft vaddr_t
37.Fn uvm_km_alloc "struct vm_map *map" "vsize_t size" "vsize_t align" "uvm_flag_t flags" 37.Fn uvm_km_alloc "struct vm_map *map" "vsize_t size" "vsize_t align" "uvm_flag_t flags"
38.Ft void 38.Ft void
39.Fn uvm_km_free "struct vm_map *map" "vaddr_t addr" "vsize_t size" "uvm_flag_t flags" 39.Fn uvm_km_free "struct vm_map *map" "vaddr_t addr" "vsize_t size" "uvm_flag_t flags"
40.Ft struct vm_map * 40.Ft struct vm_map *
41.Fn uvm_km_suballoc "struct vm_map *map" "vaddr_t *min" "vaddr_t *max" \ 41.Fn uvm_km_suballoc "struct vm_map *map" "vaddr_t *min" "vaddr_t *max" \
42"vsize_t size" "int flags" "bool fixed" "struct vm_map *submap" 42"vsize_t size" "int flags" "bool fixed" "struct vm_map *submap"
43.Sh DESCRIPTION 43.Sh DESCRIPTION
44The UVM facility for allocation of kernel memory or address space in pages. 44The UVM facility for allocation of kernel memory or address space in pages.
45Both wired and pageable memory can be allocated by this facility, as well 45Both wired and pageable memory can be allocated by this facility, as well
46as kernel address space. 46as kernel address space.
47Note that this is a raw allocator. 47Note that this is a raw allocator.
48For general purpose memory allocation, 48For general purpose memory allocation,
49.Xr kmem 9 49.Xr kmem 9
50interface should be used. 50interface should be used.
51.Sh FUNCTIONS 51.Sh FUNCTIONS
52.Fn uvm_km_alloc 52.Fn uvm_km_alloc
53allocates 53allocates a contiguous range of
54.Fa size 54.Fa size
55bytes of kernel memory in map 55bytes of kernel memory in map
56.Fa map . 56.Fa map
 57and returns the virtual address of the range, or returns zero on failure.
57The first address of the allocated memory range will be aligned according to the 58The first address of the allocated memory range will be aligned according to the
58.Fa align 59.Fa align
59argument 60argument
60.Pq specify 0 if no alignment is necessary . 61.Pq specify 0 if no alignment is necessary .
61The alignment must be a multiple of page size. 62The alignment must be a multiple of page size.
62The 63The
63.Fa flags 64.Fa flags
64is a bitwise inclusive OR of the allocation type and operation flags. 65is a bitwise inclusive OR of the allocation type and operation flags.
65.Pp 66.Pp
66The allocation type should be one of: 67The allocation type should be one of:
67.Bl -tag -width UVM_KMF_PAGEABLE 68.Bl -tag -width UVM_KMF_PAGEABLE
68.It UVM_KMF_WIRED 69.It UVM_KMF_WIRED
69Wired memory. 70Wired memory.
70.It UVM_KMF_PAGEABLE 71.It UVM_KMF_PAGEABLE
71Demand-paged zero-filled memory. 72Demand-paged zero-filled memory.
72.It UVM_KMF_VAONLY 73.It UVM_KMF_VAONLY
73Virtual address only. 74Virtual address only.
74No physical pages are mapped in the allocated region. 75No physical pages are mapped in the allocated region.
75If necessary, it is the caller's responsibility to enter page mappings. 76If necessary, it is the caller's responsibility to enter page mappings.
76It is also the caller's responsibility to clean up the mappings before freeing 77It is also the caller's responsibility to clean up the mappings before freeing
77the address range. 78the address range.
78.El 79.El
79.Pp 80.Pp
80The following operation flags are available: 81The following operation flags are available:
81.Bl -tag -width UVM_KMF_PAGEABLE 82.Bl -tag -width UVM_KMF_PAGEABLE
82.It UVM_KMF_CANFAIL 83.It UVM_KMF_CANFAIL
83Can fail even if 84Can fail even if
84.Dv UVM_KMF_NOWAIT 85.Dv UVM_KMF_NOWAIT
85is not specified and 86is not specified and
86.Dv UVM_KMF_WAITVA 87.Dv UVM_KMF_WAITVA
87is specified. 88is specified.
88.It UVM_KMF_ZERO 89.It UVM_KMF_ZERO
89Request zero-filled memory. 90Request zero-filled memory.
90Only supported for 91Only supported for
91.Dv UVM_KMF_WIRED . 92.Dv UVM_KMF_WIRED .
92Should not be used with other types. 93Should not be used with other types.
93.It UVM_KMF_TRYLOCK 94.It UVM_KMF_TRYLOCK
94Fail if cannot lock the map without sleeping. 95Fail if cannot lock the map without sleeping.
95.It UVM_KMF_NOWAIT 96.It UVM_KMF_NOWAIT
96Fail immediately if no memory is available. 97Fail immediately if no memory is available.
97.It UVM_KMF_WAITVA 98.It UVM_KMF_WAITVA
98Sleep to wait for the virtual address resources if needed. 99Sleep to wait for the virtual address resources if needed.
99.El 100.El
100.Pp 101.Pp
101If neither 102If neither
102.Dv UVM_KMF_NOWAIT 103.Dv UVM_KMF_NOWAIT
103nor 104nor
104.Dv UVM_KMF_CANFAIL 105.Dv UVM_KMF_CANFAIL
105are specified and 106are specified and
106.Dv UVM_KMF_WAITVA 107.Dv UVM_KMF_WAITVA
107is specified, 108is specified,
108.Fn uvm_km_alloc 109.Fn uvm_km_alloc
109will never fail, but rather sleep indefinitely until the allocation succeeds. 110will never fail, but rather sleep indefinitely until the allocation succeeds.
110.Pp 111.Pp
111Pageability of the pages allocated with 112Pageability of the pages allocated with
112.Dv UVM_KMF_PAGEABLE 113.Dv UVM_KMF_PAGEABLE
113can be changed by 114can be changed by
114.Fn uvm_map_pageable . 115.Fn uvm_map_pageable .
115In that case, the entire range must be changed atomically. 116In that case, the entire range must be changed atomically.
116Changing a part of the range is not supported. 117Changing a part of the range is not supported.
117.Pp 118.Pp
118.Fn uvm_km_free 119.Fn uvm_km_free
119frees the memory range allocated by 120frees the memory range allocated by
120.Fn uvm_km_alloc . 121.Fn uvm_km_alloc .
121.Fa addr 122.Fa addr
122must be an address returned by 123must be an address returned by
123.Fn uvm_km_alloc . 124.Fn uvm_km_alloc .
124.Fa map 125.Fa map
125and 126and
126.Fa size 127.Fa size
127must be the same as the ones used for the corresponding 128must be the same as the ones used for the corresponding
128.Fn uvm_km_alloc . 129.Fn uvm_km_alloc .
129.Fa flags 130.Fa flags
130must be the allocation type used for the corresponding 131must be the allocation type used for the corresponding
131.Fn uvm_km_alloc . 132.Fn uvm_km_alloc .
132Note that 133Note that
133.Fn uvm_km_free 134.Fn uvm_km_free
134is the only way to free memory ranges allocated by 135is the only way to free memory ranges allocated by
135.Fn uvm_km_alloc . 136.Fn uvm_km_alloc .
136.Fn uvm_unmap 137.Fn uvm_unmap
137must not be used. 138must not be used.
138.Pp 139.Pp
139.Fn uvm_km_suballoc 140.Fn uvm_km_suballoc
140allocates submap from 141allocates submap from
141.Fa map , 142.Fa map ,
142creating a new map if 143creating a new map if
143.Fa submap 144.Fa submap
144is 145is
145.Dv NULL . 146.Dv NULL .
146The addresses of the submap can be specified explicitly by setting the 147The addresses of the submap can be specified explicitly by setting the
147.Fa fixed 148.Fa fixed
148argument to true, which causes the 149argument to true, which causes the
149.Fa min 150.Fa min
150argument to specify the beginning of the address in the submap. 151argument to specify the beginning of the address in the submap.
151If 152If
152.Fa fixed 153.Fa fixed
153is false, any address of size 154is false, any address of size
154.Fa size 155.Fa size
155will be allocated from 156will be allocated from
156.Fa map 157.Fa map
157and the start and end addresses returned in 158and the start and end addresses returned in
158.Fa min 159.Fa min
159and 160and
160.Fa max . 161.Fa max .
161The 162The
162.Fa flags 163.Fa flags
163are used to initialize the created submap. 164are used to initialize the created submap.
164The following flags can be set: 165The following flags can be set:
165.Bl -tag -width VM_MAP_PAGEABLE 166.Bl -tag -width VM_MAP_PAGEABLE
166.It VM_MAP_PAGEABLE 167.It VM_MAP_PAGEABLE
167Entries in the map may be paged out. 168Entries in the map may be paged out.
168.It VM_MAP_INTRSAFE 169.It VM_MAP_INTRSAFE
169Map should be interrupt-safe. 170Map should be interrupt-safe.
170.It VM_MAP_TOPDOWN 171.It VM_MAP_TOPDOWN
171A top-down mapping should be arranged. 172A top-down mapping should be arranged.
172.El 173.El
173.Sh SEE ALSO 174.Sh SEE ALSO
174.Xr kmem 9 , 175.Xr kmem 9 ,
175.Xr pmap 9 , 176.Xr pmap 9 ,
176.Xr pool_cache 9 , 177.Xr pool_cache 9 ,
177.Xr uvm 9 , 178.Xr uvm 9 ,
178.Xr uvm_map 9 , 179.Xr uvm_map 9 ,
179.Xr vmem 9 180.Xr vmem 9
180.Sh HISTORY 181.Sh HISTORY
181UVM and 182UVM and
182.Nm 183.Nm
183first appeared in 184first appeared in
184.Nx 1.4 . 185.Nx 1.4 .