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_rsize "const struct memory_type *mtp"
85 .Fn memstat_get_memalloced "const struct memory_type *mtp"
87 .Fn memstat_get_memfreed "const struct memory_type *mtp"
89 .Fn memstat_get_numallocs "const struct memory_type *mtp"
91 .Fn memstat_get_numfrees "const struct memory_type *mtp"
93 .Fn memstat_get_bytes "const struct memory_type *mtp"
95 .Fn memstat_get_count "const struct memory_type *mtp"
97 .Fn memstat_get_free "const struct memory_type *mtp"
99 .Fn memstat_get_failures "const struct memory_type *mtp"
101 .Fn memstat_get_caller_pointer "const struct memory_type *mtp" "int index"
103 .Fo memstat_set_caller_pointer
104 .Fa "struct memory_type *mtp" "int index" "void *value"
107 .Fn memstat_get_caller_uint64 "const struct memory_type *mtp" "int index"
109 .Fo memstat_set_caller_uint64
110 .Fa "struct memory_type *mtp" "int index" "uint64_t value"
113 .Fn memstat_get_zonefree "const struct memory_type *mtp"
115 .Fn memstat_get_kegfree "const struct memory_type *mtp"
117 .Fn memstat_get_percpu_memalloced "const struct memory_type *mtp" "int cpu"
119 .Fn memstat_get_percpu_memfreed "const struct memory_type *mtp" "int cpu"
121 .Fn memstat_get_percpu_numallocs "const struct memory_type *mtp" "int cpu"
123 .Fn memstat_get_percpu_numfrees "const struct memory_type *mtp" "int cpu"
125 .Fn memstat_get_percpu_sizemask "const struct memory_type *mtp" "int cpu"
127 .Fo memstat_get_percpu_caller_pointer
128 .Fa "const struct memory_type *mtp" "int cpu" "int index"
131 .Fo memstat_set_percpu_caller_pointer
132 .Fa "struct memory_type *mtp" "int cpu" "int index" "void *value"
135 .Fo memstat_get_percpu_caller_uint64
136 .Fa "const struct memory_type *mtp" "int cpu" "int index"
139 .Fo memstat_set_percpu_caller_uint64
140 .Fa "struct memory_type *mtp" "int cpu" "int index" "uint64_t value"
143 .Fn memstat_get_percpu_free "const struct memory_type *mtp" "int cpu"
146 provides an interface to retrieve kernel memory allocator statistics, for
147 the purposes of debugging and system monitoring, insulating applications
148 from implementation details of the allocators, and allowing a tool to
149 transparently support multiple allocators.
151 supports both retrieving a single statistics snapshot, as well as
152 incrementally updating statistics for long-term monitoring.
155 describes each memory type using a
156 .Vt "struct memory_type" ,
157 an opaque memory type accessed by the application using accessor functions
160 returns and updates chains of
161 .Vt "struct memory_type"
163 .Vt "struct memory_type_list" ,
164 which will be allocated by calling
165 .Fn memstat_mtl_alloc ,
166 and freed on completion using
167 .Fn memstat_mtl_free .
168 Lists of memory types are populated via calls that query the kernel for
169 statistics information; currently:
170 .Fn memstat_kvm_all ,
171 .Fn memstat_kvm_malloc ,
172 .Fn memstat_kvm_uma ,
173 .Fn memstat_sysctl_all ,
174 .Fn memstat_sysctl_uma ,
176 .Fn memstat_sysctl_malloc .
177 Repeated calls will incrementally update the list of memory types, permitting
178 tracking over time without recreating all list state.
179 If an error is detected during a query call, error condition information may
181 .Fn memstat_mtl_geterror ,
182 and converted to a user-readable string using
183 .Fn memstat_strerror .
185 Freeing the list will free all memory type data in the list, and so
186 invalidates any outstanding pointers to entries in the list.
187 .Vt "struct memory_type"
188 entries in the list may be iterated over using
189 .Fn memstat_mtl_first
191 .Fn memstat_mtl_next ,
192 which respectively return the first entry in a list, and the next entry in a
194 .Fn memstat_mtl_find ,
195 which will return a pointer to the first entry matching the passed
198 A series of accessor methods is provided to access fields of the structure,
199 including retrieving statistics and properties, as well as setting of caller
201 Direct application access to the data structure fields is not supported.
202 .Ss Library Vt memory_type Ss Fields
204 .Vt "struct memory_type"
205 holds a description of the memory type, including its name and the allocator
206 it is managed by, as well as current statistics on use.
207 Some statistics are directly measured, others are derived from directly
209 Certain high level statistics are present across all available allocators,
210 such as the number of allocation and free operations; other measurements,
211 such as the quantity of free items in per-CPU caches, or administrative
212 limit on the number of allocations, is available only for specific
214 .Ss Caller Vt memory_type Ss Fields
215 .Vt "struct memory_type"
216 includes fields to allow the application to store data, in the form of
217 pointers and 64-bit integers, with memory types.
218 For example, the application author might make use of one of the caller
219 pointers to reference a more complex data structure tracking long-term
220 behavior of the memory type, or a window system object that is used to
221 render the state of the memory type.
222 General and per-CPU storage is provided with each
223 .Vt "struct memory_type"
224 in the form of an array of pointers and integers.
225 The array entries are accessed via the
227 argument to the get and set accessor methods.
233 .Dv MEMSTAT_MAXCALLER .
235 Caller-owned fields are initialized to
240 .Vt "struct memory_type"
241 is allocated and attached to a memory type list; these fields retain their
242 values across queries that update library-owned fields.
246 supports two kernel allocators:
254 These values may be passed to
255 .Fn memstat_mtl_find ,
256 and will be returned by
257 .Fn memstat_get_allocator .
258 Two additional constants in the allocator name space are defined:
259 .Dv ALLOCATOR_UNKNOWN ,
260 which will only be returned as a result of a library error, and
262 which can be used to specify that returning types matching any allocator is
264 .Fn memstat_mtl_find .
265 .Ss Access Method List
266 The following accessor methods are defined, of which some will be valid for
268 .Bl -tag -width indent
269 .It Fn memstat_get_name
270 Return a pointer to the name of the memory type.
271 Memory for the name is owned by
273 and will be valid through a call to
274 .Fn memstat_mtl_free .
275 Note that names will be unique with respect to a single allocator, but that
276 the same name might be used by different memory types owned by different
278 .It Fn memstat_get_allocator
279 Return an integer identifier for the memory allocator that owns the memory
281 .It Fn memstat_get_countlimit
282 If the memory type has an administrative limit on the number of simultaneous
283 allocations, return it.
284 .It Fn memstat_get_byteslimit
285 If the memory type has an administrative limit on the number of bytes of
286 memory that may be simultaneously allocated for the memory type, return it.
287 .It Fn memstat_get_sizemask
288 If the memory type supports variable allocation sizes, return a bitmask of
289 sizes allocated for the memory type.
290 .It Fn memstat_get_size
291 If the memory type supports a fixed allocation size, return that size.
292 .It Fn memstat_get_rsize
293 If the memory type supports a fixed allocation size, return real size
295 Real size can exceed requested size due to alignment constraints or
297 .It Fn memstat_get_memalloced
298 Return the total number of bytes allocated for the memory type over its
300 .It Fn memstat_get_memfreed
301 Return the total number of bytes freed for the memory type over its lifetime.
302 .It Fn memstat_get_numallocs
303 Return the total number of allocations for the memory type over its lifetime.
304 .It Fn memstat_get_numfrees
305 Return the total number of frees for the memory type over its lifetime.
306 .It Fn memstat_get_bytes
307 Return the current number of bytes allocated to the memory type.
308 .It Fn memstat_get_count
309 Return the current number of allocations for the memory type.
310 .It Fn memstat_get_free
311 If the memory allocator supports a cache, return the number of items in the
313 .It Fn memstat_get_failures
314 If the memory allocator and type permit allocation failures, return the
315 number of allocation failures measured.
316 .It Fn memstat_get_caller_pointer
317 Return a caller-owned pointer for the memory type.
318 .It Fn memstat_set_caller_pointer
319 Set a caller-owned pointer for the memory type.
320 .It Fn memstat_get_caller_uint64
321 Return a caller-owned integer for the memory type.
322 .It Fn memstat_set_caller_uint64
323 Set a caller-owned integer for the memory type.
324 .It Fn memstat_get_zonefree
325 If the memory allocator supports a multi-level allocation structure, return
326 the number of cached items in the zone.
327 These items will be in a fully constructed state available for immediate
329 .It Fn memstat_get_kegfree
330 If the memory allocator supports a multi-level allocation structure, return
331 the number of cached items in the keg.
332 These items may be in a partially constructed state, and may require further
333 processing before they can be made available for use.
334 .It Fn memstat_get_percpu_memalloced
335 If the memory allocator supports per-CPU statistics, return the number of
336 bytes of memory allocated for the memory type on the CPU over its lifetime.
337 .It Fn memstat_get_percpu_memfreed
338 If the memory allocator supports per-CPU statistics, return the number of
339 bytes of memory freed from the memory type on the CPU over its lifetime.
340 .It Fn memstat_get_percpu_numallocs
341 If the memory allocator supports per-CPU statistics, return the number of
342 allocations for the memory type on the CPU over its lifetime.
343 .It Fn memstat_get_percpu_numfrees
344 If the memory allocator supports per-CPU statistics, return the number of
345 frees for the memory type on the CPU over its lifetime.
346 .It Fn memstat_get_percpu_sizemask
347 If the memory allocator supports variable size memory allocation and per-CPU
348 statistics, return the size bitmask for the memory type on the CPU.
349 .It Fn memstat_get_percpu_caller_pointer
350 Return a caller-owned per-CPU pointer for the memory type.
351 .It Fn memstat_set_percpu_caller_pointer
352 Set a caller-owned per-CPU pointer for the memory type.
353 .It Fn memstat_get_percpu_caller_uint64
354 Return a caller-owned per-CPU integer for the memory type.
355 .It Fn memstat_set_percpu_caller_uint64
356 Set a caller-owned per-CPU integer for the memory type.
357 .It Fn memstat_get_percpu_free
358 If the memory allocator supports a per-CPU cache, return the number of free
359 items in the per-CPU cache of the designated CPU.
363 functions fall into three categories: functions returning a pointer to an
364 object, functions returning an integer return value, and functions
365 implementing accessor methods returning data from a
366 .Vt "struct memory_type" .
368 Functions returning a pointer to an object will generally return
371 .Fn memstat_mtl_alloc
372 will return an error value via
374 which will consist of the value
377 .Fn memstat_mtl_first ,
378 .Fn memstat_mtl_next ,
383 when there is no entry or match in the list; however, this is not considered
384 a failure mode and no error value is available.
386 Functions returning an integer success value will return
391 If a failure is returned, the list error access method,
392 .Fn memstat_mtl_geterror ,
393 may be used to retrieve the error state.
394 The string representation of the error may be retrieved using
395 .Fn memstat_strerror .
396 Possible error values are:
397 .Bl -tag -width ".Dv MEMSTAT_ERROR_KVM_SHORTREAD"
398 .It Dv MEMSTAT_ERROR_UNDEFINED
401 .Fn memstat_mtl_geterror
402 is called on a list before an error associated with the list has occurred.
403 .It Dv MEMSTAT_ERROR_NOMEMORY
405 Occurs if library calls to
407 fail, or if a system call to retrieve kernel statistics fails with
409 .It Dv MEMSTAT_ERROR_VERSION
410 Returned if the current version of
412 is unable to interpret the statistics data returned by the kernel due to an
413 explicit version mismatch, or to differences in data structures that cannot
415 .It Dv MEMSTAT_ERROR_PERMISSION
416 Returned if a statistics source returns
422 .It Dv MEMSTAT_ERROR_DATAERROR
425 is unable to interpret statistics data returned by the data source, even
426 though there does not appear to be a version problem.
427 .It Dv MEMSTAT_ERROR_KVM
430 experiences an error while using
432 interfaces to query statistics data.
435 to retrieve the error.
436 .It Dv MEMSTAT_ERROR_KVM_NOSYMBOL
439 is unable to read a required symbol from the kernel being operated on.
440 .It Dv MEMSTAT_ERROR_KVM_SHORTREAD
443 attempts to read data from a live memory image or kernel core dump and
444 insufficient data is returned.
447 Finally, functions returning data from a
448 .Vt "struct memory_type"
449 pointer are not permitted to fail, and directly return either a statistic
450 or pointer to a string.
452 Create a memory type list, query the
454 memory allocator for available statistics, and print out the number of
455 allocations performed by the
458 .Bd -literal -offset indent
459 struct memory_type_list *mtlp;
460 struct memory_type *mtp;
463 mtlp = memstat_mtl_alloc();
465 err(-1, "memstat_mtl_alloc");
466 if (memstat_sysctl_uma(mtlp, 0) < 0)
467 err(-1, "memstat_sysctl_uma");
468 mtp = memstat_mtl_find(mtlp, ALLOCATOR_UMA, "mbuf");
470 errx(-1, "memstat_mtl_find: mbuf not found");
471 mbuf_count = memstat_get_count(mtp);
472 memstat_mtl_free(mtlp);
474 printf("mbufs: %llu\en", (unsigned long long)mbuf_count);
485 The kernel memory allocator changes necessary to support a general purpose
486 monitoring library, along with the library, were written by
487 .An Robert Watson Aq Mt rwatson@FreeBSD.org .
489 There are memory allocators in the kernel, such as the VM page allocator
492 allocator, which are not currently supported by
495 Once a memory type is present on a memory type list, it will not be removed
496 even if the kernel no longer presents information on the type via its
497 monitoring interfaces.
498 In order to flush removed memory types, it is necessary to free the entire
499 list and allocate a new one.