1 .\" Copyright (c) 2005 Robert N. M. Watson
2 .\" All rights reserved.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
7 .\" 1. Redistributions of source code must retain the above copyright
8 .\" notice, this list of conditions and the following disclaimer.
9 .\" 2. Redistributions in binary form must reproduce the above copyright
10 .\" notice, this list of conditions and the following disclaimer in the
11 .\" documentation and/or other materials provided with the distribution.
13 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND
14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
16 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE
17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
32 .Nd "library interface to retrieve kernel memory allocator statistics"
40 .Fn memstat_strerror "int error"
41 .Ss Memory Type List Management Functions
42 .Ft "struct memory_type_list *"
43 .Fn memstat_mtl_alloc "void"
44 .Ft "struct memory_type *"
45 .Fn memstat_mtl_first "struct memory_type_list *list"
46 .Ft "struct memory_type *"
47 .Fn memstat_mtl_next "struct memory_type *mtp"
48 .Ft "struct memory_type *"
50 .Fa "struct memory_type_list *list" "int allocator" "const char *name"
53 .Fn memstat_mtl_free "struct memory_type_list *list"
55 .Fn memstat_mtl_geterror "struct memory_type_list *list"
56 .Ss Allocator Query Functions
58 .Fn memstat_kvm_all "struct memory_type_list *list" "void *kvm_handle"
60 .Fn memstat_kvm_malloc "struct memory_type_list *list" "void *kvm_handle"
62 .Fn memstat_kvm_uma "struct memory_type_list *list" "void *kvm_handle"
64 .Fn memstat_sysctl_all "struct memory_type_list *list" "int flags"
66 .Fn memstat_sysctl_malloc "struct memory_type_list *list" "int flags"
68 .Fn memstat_sysctl_uma "struct memory_type_list *list" "int flags"
69 .Ss Memory Type Accessor Methods
71 .Fn memstat_get_name "const struct memory_type *mtp"
73 .Fn memstat_get_allocator "const struct memory_type *mtp"
75 .Fn memstat_get_countlimit "const struct memory_type *mtp"
77 .Fn memstat_get_byteslimit "const struct memory_type *mtp"
79 .Fn memstat_get_sizemask "const struct memory_type *mtp"
81 .Fn memstat_get_size "const struct memory_type *mtp"
83 .Fn memstat_get_memalloced "const struct memory_type *mtp"
85 .Fn memstat_get_memfreed "const struct memory_type *mtp"
87 .Fn memstat_get_numallocs "const struct memory_type *mtp"
89 .Fn memstat_get_numfrees "const struct memory_type *mtp"
91 .Fn memstat_get_bytes "const struct memory_type *mtp"
93 .Fn memstat_get_count "const struct memory_type *mtp"
95 .Fn memstat_get_free "const struct memory_type *mtp"
97 .Fn memstat_get_failures "const struct memory_type *mtp"
99 .Fn memstat_get_caller_pointer "const struct memory_type *mtp" "int index"
101 .Fo memstat_set_caller_pointer
102 .Fa "struct memory_type *mtp" "int index" "void *value"
105 .Fn memstat_get_caller_uint64 "const struct memory_type *mtp" "int index"
107 .Fo memstat_set_caller_uint64
108 .Fa "struct memory_type *mtp" "int index" "uint64_t value"
111 .Fn memstat_get_zonefree "const struct memory_type *mtp"
113 .Fn memstat_get_kegfree "const struct memory_type *mtp"
115 .Fn memstat_get_percpu_memalloced "const struct memory_type *mtp" "int cpu"
117 .Fn memstat_get_percpu_memfreed "const struct memory_type *mtp" "int cpu"
119 .Fn memstat_get_percpu_numallocs "const struct memory_type *mtp" "int cpu"
121 .Fn memstat_get_percpu_numfrees "const struct memory_type *mtp" "int cpu"
123 .Fn memstat_get_percpu_sizemask "const struct memory_type *mtp" "int cpu"
125 .Fo memstat_get_percpu_caller_pointer
126 .Fa "const struct memory_type *mtp" "int cpu" "int index"
129 .Fo memstat_set_percpu_caller_pointer
130 .Fa "struct memory_type *mtp" "int cpu" "int index" "void *value"
133 .Fo memstat_get_percpu_caller_uint64
134 .Fa "const struct memory_type *mtp" "int cpu" "int index"
137 .Fo memstat_set_percpu_caller_uint64
138 .Fa "struct memory_type *mtp" "int cpu" "int index" "uint64_t value"
141 .Fn memstat_get_percpu_free "const struct memory_type *mtp" "int cpu"
144 provides an interface to retrieve kernel memory allocator statistics, for
145 the purposes of debugging and system monitoring, insulating applications
146 from implementation details of the allocators, and allowing a tool to
147 transparently support multiple allocators.
149 supports both retrieving a single statistics snapshot, as well as
150 incrementally updating statistics for long-term monitoring.
153 describes each memory type using a
154 .Vt "struct memory_type" ,
155 an opaque memory type accessed by the application using accessor functions
158 returns and updates chains of
159 .Vt "struct memory_type"
161 .Vt "struct memory_type_list" ,
162 which will be allocated by calling
163 .Fn memstat_mtl_alloc ,
164 and freed on completion using
165 .Fn memstat_mtl_free .
166 Lists of memory types are populated via calls that query the kernel for
167 statistics information; currently:
168 .Fn memstat_kvm_all ,
169 .Fn memstat_kvm_malloc ,
170 .Fn memstat_kvm_uma ,
171 .Fn memstat_sysctl_all ,
172 .Fn memstat_sysctl_uma ,
174 .Fn memstat_sysctl_malloc .
175 Repeated calls will incrementally update the list of memory types, permitting
176 tracking over time without recreating all list state.
177 If an error is detected during a query call, error condition information may
179 .Fn memstat_mtl_geterror ,
180 and converted to a user-readable string using
181 .Fn memstat_strerror .
183 Freeing the list will free all memory type data in the list, and so
184 invalidates any outstanding pointers to entries in the list.
185 .Vt "struct memory_type"
186 entries in the list may be iterated over using
187 .Fn memstat_mtl_first
189 .Fn memstat_mtl_next ,
190 which respectively return the first entry in a list, and the next entry in a
192 .Fn memstat_mtl_find ,
193 which will return a pointer to the first entry matching the passed
196 A series of accessor methods is provided to access fields of the structure,
197 including retrieving statistics and properties, as well as setting of caller
199 Direct application access to the data structure fields is not supported.
200 .Ss Library Vt memory_type Ss Fields
202 .Vt "struct memory_type"
203 holds a description of the memory type, including its name and the allocator
204 it is managed by, as well as current statistics on use.
205 Some statistics are directly measured, others are derived from directly
207 Certain high level statistics are present across all available allocators,
208 such as the number of allocation and free operations; other measurements,
209 such as the quantity of free items in per-CPU caches, or administrative
210 limit on the number of allocations, is available only for specific
212 .Ss Caller Vt memory_type Ss Fields
213 .Vt "struct memory_type"
214 includes fields to allow the application to store data, in the form of
215 pointers and 64-bit integers, with memory types.
216 For example, the application author might make use of one of the caller
217 pointers to reference a more complex data structure tracking long-term
218 behavior of the memory type, or a window system object that is used to
219 render the state of the memory type.
220 General and per-CPU storage is provided with each
221 .Vt "struct memory_type"
222 in the form of an array of pointers and integers.
223 The array entries are accessed via the
225 argument to the get and set accessor methods.
231 .Dv MEMSTAT_MAXCALLER .
233 Caller-owned fields are initialized to
238 .Vt "struct memory_type"
239 is allocated and attached to a memory type list; these fields retain their
240 values across queries that update library-owned fields.
244 supports two kernel allocators:
252 These values may be passed to
253 .Fn memstat_mtl_find ,
254 and will be returned by
255 .Fn memstat_get_allocator .
256 Two additional constants in the allocator name space are defined:
257 .Dv ALLOCATOR_UNKNOWN ,
258 which will only be returned as a result of a library error, and
260 which can be used to specify that returning types matching any allocator is
262 .Fn memstat_mtl_find .
263 .Ss Access Method List
264 The following accessor methods are defined, of which some will be valid for
266 .Bl -tag -width indent
267 .It Fn memstat_get_name
268 Return a pointer to the name of the memory type.
269 Memory for the name is owned by
271 and will be valid through a call to
272 .Fn memstat_mtl_free .
273 Note that names will be unique with respect to a single allocator, but that
274 the same name might be used by different memory types owned by different
276 .It Fn memstat_get_allocator
277 Return an integer identifier for the memory allocator that owns the memory
279 .It Fn memstat_get_countlimit
280 If the memory type has an administrative limit on the number of simultaneous
281 allocations, return it.
282 .It Fn memstat_get_byteslimit
283 If the memory type has an administrative limit on the number of bytes of
284 memory that may be simultaneously allocated for the memory type, return it.
285 .It Fn memstat_get_sizemask
286 If the memory type supports variable allocation sizes, return a bitmask of
287 sizes allocated for the memory type.
288 .It Fn memstat_get_size
289 If the memory type supports a fixed allocation size, return that size.
290 .It Fn memstat_get_memalloced
291 Return the total number of bytes allocated for the memory type over its
293 .It Fn memstat_get_memfreed
294 Return the total number of bytes freed for the memory type over its lifetime.
295 .It Fn memstat_get_numallocs
296 Return the total number of allocations for the memory type over its lifetime.
297 .It Fn memstat_get_numfrees
298 Return the total number of frees for the memory type over its lifetime.
299 .It Fn memstat_get_bytes
300 Return the current number of bytes allocated to the memory type.
301 .It Fn memstat_get_count
302 Return the current number of allocations for the memory type.
303 .It Fn memstat_get_free
304 If the memory allocator supports a cache, return the number of items in the
306 .It Fn memstat_get_failures
307 If the memory allocator and type permit allocation failures, return the
308 number of allocation failures measured.
309 .It Fn memstat_get_caller_pointer
310 Return a caller-owned pointer for the memory type.
311 .It Fn memstat_set_caller_pointer
312 Set a caller-owned pointer for the memory type.
313 .It Fn memstat_get_caller_uint64
314 Return a caller-owned integer for the memory type.
315 .It Fn memstat_set_caller_uint64
316 Set a caller-owned integer for the memory type.
317 .It Fn memstat_get_zonefree
318 If the memory allocator supports a multi-level allocation structure, return
319 the number of cached items in the zone.
320 These items will be in a fully constructed state available for immediate
322 .It Fn memstat_get_kegfree
323 If the memory allocator supports a multi-level allocation structure, return
324 the number of cached items in the keg.
325 These items may be in a partially constructed state, and may require further
326 processing before they can be made available for use.
327 .It Fn memstat_get_percpu_memalloced
328 If the memory allocator supports per-CPU statistics, return the number of
329 bytes of memory allocated for the memory type on the CPU over its lifetime.
330 .It Fn memstat_get_percpu_memfreed
331 If the memory allocator supports per-CPU statistics, return the number of
332 bytes of memory freed from the memory type on the CPU over its lifetime.
333 .It Fn memstat_get_percpu_numallocs
334 If the memory allocator supports per-CPU statistics, return the number of
335 allocations for the memory type on the CPU over its lifetime.
336 .It Fn memstat_get_percpu_numfrees
337 If the memory allocator supports per-CPU statistics, return the number of
338 frees for the memory type on the CPU over its lifetime.
339 .It Fn memstat_get_percpu_sizemask
340 If the memory allocator supports variable size memory allocation and per-CPU
341 statistics, return the size bitmask for the memory type on the CPU.
342 .It Fn memstat_get_percpu_caller_pointer
343 Return a caller-owned per-CPU pointer for the memory type.
344 .It Fn memstat_set_percpu_caller_pointer
345 Set a caller-owned per-CPU pointer for the memory type.
346 .It Fn memstat_get_percpu_caller_uint64
347 Return a caller-owned per-CPU integer for the memory type.
348 .It Fn memstat_set_percpu_caller_uint64
349 Set a caller-owned per-CPU integer for the memory type.
350 .It Fn memstat_get_percpu_free
351 If the memory allocator supports a per-CPU cache, return the number of free
352 items in the per-CPU cache of the designated CPU.
356 functions fall into three categories: functions returning a pointer to an
357 object, functions returning an integer return value, and functions
358 implementing accessor methods returning data from a
359 .Vt "struct memory_type" .
361 Functions returning a pointer to an object will generally return
364 .Fn memstat_mtl_alloc
365 will return an error value via
367 which will consist of the value
370 .Fn memstat_mtl_first ,
371 .Fn memstat_mtl_next ,
376 when there is no entry or match in the list; however, this is not considered
377 a failure mode and no error value is available.
379 Functions returning an integer success value will return
384 If a failure is returned, the list error access method,
385 .Fn memstat_mtl_geterror ,
386 may be used to retrieve the error state.
387 The string representation of the error may be retrieved using
388 .Fn memstat_strerror .
389 Possible error values are:
390 .Bl -tag -width ".Dv MEMSTAT_ERROR_KVM_SHORTREAD"
391 .It Dv MEMSTAT_ERROR_UNDEFINED
394 .Fn memstat_mtl_geterror
395 is called on a list before an error associated with the list has occurred.
396 .It Dv MEMSTAT_ERROR_NOMEMORY
398 Occurs if library calls to
400 fail, or if a system call to retrieve kernel statistics fails with
402 .It Dv MEMSTAT_ERROR_VERSION
403 Returned if the current version of
405 is unable to interpret the statistics data returned by the kernel due to an
406 explicit version mismatch, or to differences in data structures that cannot
408 .It Dv MEMSTAT_ERROR_PERMISSION
409 Returned if a statistics source returns
415 .It Dv MEMSTAT_ERROR_DATAERROR
418 is unable to interpret statistics data returned by the data source, even
419 though there does not appear to be a version problem.
420 .It Dv MEMSTAT_ERROR_KVM
423 experiences an error while using
425 interfaces to query statistics data.
428 to retrieve the error.
429 .It Dv MEMSTAT_ERROR_KVM_NOSYMBOL
432 is unable to read a required symbol from the kernel being operated on.
433 .It Dv MEMSTAT_ERROR_KVM_SHORTREAD
436 attempts to read data from a live memory image or kernel core dump and
437 insufficient data is returned.
440 Finally, functions returning data from a
441 .Vt "struct memory_type"
442 pointer are not permitted to fail, and directly return either a statistic
443 or pointer to a string.
445 Create a memory type list, query the
447 memory allocator for available statistics, and print out the number of
448 allocations performed by the
451 .Bd -literal -offset indent
452 struct memory_type_list *mtlp;
453 struct memory_type *mtp;
456 mtlp = memstat_mtl_alloc();
458 err(-1, "memstat_mtl_alloc");
459 if (memstat_sysctl_uma(mtlp, 0) < 0)
460 err(-1, "memstat_sysctl_uma");
461 mtp = memstat_mtl_find(mtlp, ALLOCATOR_UMA, "mbuf");
463 errx(-1, "memstat_mtl_find: mbuf not found");
464 mbuf_count = memstat_get_count(mtp);
465 memstat_mtl_free(mtlp);
467 printf("mbufs: %llu\en", (unsigned long long)mbuf_count);
478 The kernel memory allocator changes necessary to support a general purpose
479 monitoring library, along with the library, were written by
480 .An Robert Watson Aq rwatson@FreeBSD.org .
482 There are memory allocators in the kernel, such as the VM page allocator
485 allocator, which are not currently supported by
488 Once a memory type is present on a memory type list, it will not be removed
489 even if the kernel no longer presents information on the type via its
490 monitoring interfaces.
491 In order to flush removed memory types, it is necessary to free the entire
492 list and allocate a new one.