Print this page
5513 KM_NORMALPRI should be documented in kmem_alloc(9f) and kmem_cache_create(9f) man pages
14465 Present KM_NOSLEEP_LAZY as documented interface
Change-Id: I002ec28ddf390650f1fcba1ca94f6abfdb241439
| Split |
Close |
| Expand all |
| Collapse all |
--- old/usr/src/man/man9f/kmem_alloc.9f.man.txt
+++ new/usr/src/man/man9f/kmem_alloc.9f.man.txt
1 1 KMEM_ALLOC(9F) Kernel Functions for Drivers KMEM_ALLOC(9F)
2 2
3 3
4 4
5 5 NAME
6 6 kmem_alloc, kmem_zalloc, kmem_free - allocate kernel memory
7 7
8 8 SYNOPSIS
9 9 #include <sys/types.h>
10 10 #include <sys/kmem.h>
11 11
12 12
13 13
14 14 void *kmem_alloc(size_t size, int flag);
15 15
16 16
17 17 void *kmem_zalloc(size_t size, int flag);
18 18
19 19
20 20 void kmem_free(void *buf, size_t size);
21 21
22 22
|
↓ open down ↓ |
22 lines elided |
↑ open up ↑ |
23 23 INTERFACE LEVEL
24 24 Architecture independent level 1 (DDI/DKI).
25 25
26 26 PARAMETERS
27 27 size
28 28 Number of bytes to allocate.
29 29
30 30
31 31 flag
32 32 Determines whether caller can sleep for memory. Possible flags
33 - are KM_SLEEP to allow sleeping until memory is available, or
34 - KM_NOSLEEP to return NULL immediately if memory is not
35 - available.
33 + are KM_SLEEP to allow sleeping until memory is available,
34 + KM_NOSLEEP to return NULL if memory is not available even after
35 + some reclamation attempts, and KM_NOSLEEP_LAZY to return NULL
36 + without reclamation attempts. KM_NOSLEEP_LAZY is actually two
37 + flags combined: (KM_NOSLEEP | KM_NORMALPRI), the latter flag
38 + indicating not to attempt reclamation before giving up and
39 + returning NULL. If any mention of KM_NOSLEEP appears in this
40 + man page by itself, it applies equally to KM_NOSLEEP_LAZY as
41 + well.
36 42
37 43
38 44 buf
39 45 Pointer to allocated memory.
40 46
41 47
42 48 DESCRIPTION
43 49 The kmem_alloc() function allocates size bytes of kernel memory and
44 50 returns a pointer to the allocated memory. The allocated memory is at
45 51 least double-word aligned, so it can hold any C data structure. No
46 52 greater alignment can be assumed. flag determines whether the caller
47 53 can sleep for memory. KM_SLEEP allocations may sleep but are
48 - guaranteed to succeed. KM_NOSLEEP allocations are guaranteed not to
49 - sleep but may fail (return NULL) if no memory is currently available.
50 - The initial contents of memory allocated using kmem_alloc() are random
51 - garbage.
54 + guaranteed to succeed. KM_NOSLEEP and KM_NOSLEEP_LAZY allocations are
55 + guaranteed not to sleep but may fail (return NULL) if no memory is
56 + currently available. KM_NOSLEEP will first attempt to aggressively
57 + reclaim memory from otherwise unused blocks, while KM_NOSLEEP_LAZY will
58 + not attempt any reclamation. The initial contents of memory allocated
59 + using kmem_alloc() are random garbage.
52 60
53 61
54 62 The kmem_zalloc() function is like kmem_alloc() but returns zero-filled
55 63 memory.
56 64
57 65
58 66 The kmem_free() function frees previously allocated kernel memory. The
59 67 buffer address and size must exactly match the original allocation.
60 68 Memory cannot be returned piecemeal.
61 69
62 70 RETURN VALUES
63 71 If successful, kmem_alloc() and kmem_zalloc() return a pointer to the
64 72 allocated memory. If KM_NOSLEEP is set and memory cannot be allocated
65 73 without sleeping, kmem_alloc() and kmem_zalloc() return NULL.
66 74
67 75 CONTEXT
68 76 The kmem_alloc() and kmem_zalloc() functions can be called from
69 77 interrupt context only if the KM_NOSLEEP flag is set. They can be
70 78 called from user context with any valid flag. The kmem_free() function
71 79 can be called from from user, interrupt, or kernel context.
72 80
73 81 SEE ALSO
74 82 copyout(9F), freerbuf(9F), getrbuf(9F)
75 83
76 84
77 85 Writing Device Drivers
78 86
79 87 WARNINGS
80 88 Memory allocated using kmem_alloc() is not paged. Available memory is
81 89 therefore limited by the total physical memory on the system. It is
82 90 also limited by the available kernel virtual address space, which is
83 91 often the more restrictive constraint on large-memory configurations.
84 92
85 93
86 94 Excessive use of kernel memory is likely to affect overall system
87 95 performance. Overcommitment of kernel memory will cause the system to
88 96 hang or panic.
89 97
90 98
91 99 Misuse of the kernel memory allocator, such as writing past the end of
92 100 a buffer, using a buffer after freeing it, freeing a buffer twice, or
93 101 freeing a null or invalid pointer, will corrupt the kernel heap and may
94 102 cause the system to corrupt data or panic.
95 103
96 104
97 105 The initial contents of memory allocated using kmem_alloc() are random
98 106 garbage. This random garbage may include secure kernel data. Therefore,
99 107 uninitialized kernel memory should be handled carefully. For example,
100 108 never copyout(9F) a potentially uninitialized buffer.
101 109
102 110 NOTES
103 111 kmem_alloc(0, flag) always returns NULL, but if KM_SLEEP is set, this
104 112 behavior is considered to be deprecated; the system may be configured
105 113 to explicitly panic in this case in lieu of returning NULL.
106 114 kmem_free(NULL, 0) is legal, however.
107 115
108 116
109 117
110 118 November 20, 2019 KMEM_ALLOC(9F)
|
↓ open down ↓ |
49 lines elided |
↑ open up ↑ |
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX