diff options
Diffstat (limited to 'lib/libmemstat/libmemstat.3')
| -rw-r--r-- | lib/libmemstat/libmemstat.3 | 499 |
1 files changed, 499 insertions, 0 deletions
diff --git a/lib/libmemstat/libmemstat.3 b/lib/libmemstat/libmemstat.3 new file mode 100644 index 0000000000000..0f6255399ea51 --- /dev/null +++ b/lib/libmemstat/libmemstat.3 @@ -0,0 +1,499 @@ +.\" Copyright (c) 2005 Robert N. M. Watson +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd February 11, 2014 +.Dt LIBMEMSTAT 3 +.Os +.Sh NAME +.Nm libmemstat +.Nd "library interface to retrieve kernel memory allocator statistics" +.Sh LIBRARY +.Lb libmemstat +.Sh SYNOPSIS +.In sys/types.h +.In memstat.h +.Ss General Functions +.Ft "const char *" +.Fn memstat_strerror "int error" +.Ss Memory Type List Management Functions +.Ft "struct memory_type_list *" +.Fn memstat_mtl_alloc "void" +.Ft "struct memory_type *" +.Fn memstat_mtl_first "struct memory_type_list *list" +.Ft "struct memory_type *" +.Fn memstat_mtl_next "struct memory_type *mtp" +.Ft "struct memory_type *" +.Fo memstat_mtl_find +.Fa "struct memory_type_list *list" "int allocator" "const char *name" +.Fc +.Ft void +.Fn memstat_mtl_free "struct memory_type_list *list" +.Ft int +.Fn memstat_mtl_geterror "struct memory_type_list *list" +.Ss Allocator Query Functions +.Ft int +.Fn memstat_kvm_all "struct memory_type_list *list" "void *kvm_handle" +.Ft int +.Fn memstat_kvm_malloc "struct memory_type_list *list" "void *kvm_handle" +.Ft int +.Fn memstat_kvm_uma "struct memory_type_list *list" "void *kvm_handle" +.Ft int +.Fn memstat_sysctl_all "struct memory_type_list *list" "int flags" +.Ft int +.Fn memstat_sysctl_malloc "struct memory_type_list *list" "int flags" +.Ft int +.Fn memstat_sysctl_uma "struct memory_type_list *list" "int flags" +.Ss Memory Type Accessor Methods +.Ft "const char *" +.Fn memstat_get_name "const struct memory_type *mtp" +.Ft int +.Fn memstat_get_allocator "const struct memory_type *mtp" +.Ft uint64_t +.Fn memstat_get_countlimit "const struct memory_type *mtp" +.Ft uint64_t +.Fn memstat_get_byteslimit "const struct memory_type *mtp" +.Ft uint64_t +.Fn memstat_get_sizemask "const struct memory_type *mtp" +.Ft uint64_t +.Fn memstat_get_size "const struct memory_type *mtp" +.Ft uint64_t +.Fn memstat_get_rsize "const struct memory_type *mtp" +.Ft uint64_t +.Fn memstat_get_memalloced "const struct memory_type *mtp" +.Ft uint64_t +.Fn memstat_get_memfreed "const struct memory_type *mtp" +.Ft uint64_t +.Fn memstat_get_numallocs "const struct memory_type *mtp" +.Ft uint64_t +.Fn memstat_get_numfrees "const struct memory_type *mtp" +.Ft uint64_t +.Fn memstat_get_bytes "const struct memory_type *mtp" +.Ft uint64_t +.Fn memstat_get_count "const struct memory_type *mtp" +.Ft uint64_t +.Fn memstat_get_free "const struct memory_type *mtp" +.Ft uint64_t +.Fn memstat_get_failures "const struct memory_type *mtp" +.Ft "void *" +.Fn memstat_get_caller_pointer "const struct memory_type *mtp" "int index" +.Ft void +.Fo memstat_set_caller_pointer +.Fa "struct memory_type *mtp" "int index" "void *value" +.Fc +.Ft uint64_t +.Fn memstat_get_caller_uint64 "const struct memory_type *mtp" "int index" +.Ft void +.Fo memstat_set_caller_uint64 +.Fa "struct memory_type *mtp" "int index" "uint64_t value" +.Fc +.Ft uint64_t +.Fn memstat_get_zonefree "const struct memory_type *mtp" +.Ft uint64_t +.Fn memstat_get_kegfree "const struct memory_type *mtp" +.Ft uint64_t +.Fn memstat_get_percpu_memalloced "const struct memory_type *mtp" "int cpu" +.Ft uint64_t +.Fn memstat_get_percpu_memfreed "const struct memory_type *mtp" "int cpu" +.Ft uint64_t +.Fn memstat_get_percpu_numallocs "const struct memory_type *mtp" "int cpu" +.Ft uint64_t +.Fn memstat_get_percpu_numfrees "const struct memory_type *mtp" "int cpu" +.Ft uint64_t +.Fn memstat_get_percpu_sizemask "const struct memory_type *mtp" "int cpu" +.Ft "void *" +.Fo memstat_get_percpu_caller_pointer +.Fa "const struct memory_type *mtp" "int cpu" "int index" +.Fc +.Ft void +.Fo memstat_set_percpu_caller_pointer +.Fa "struct memory_type *mtp" "int cpu" "int index" "void *value" +.Fc +.Ft uint64_t +.Fo memstat_get_percpu_caller_uint64 +.Fa "const struct memory_type *mtp" "int cpu" "int index" +.Fc +.Ft void +.Fo memstat_set_percpu_caller_uint64 +.Fa "struct memory_type *mtp" "int cpu" "int index" "uint64_t value" +.Fc +.Ft uint64_t +.Fn memstat_get_percpu_free "const struct memory_type *mtp" "int cpu" +.Sh DESCRIPTION +.Nm +provides an interface to retrieve kernel memory allocator statistics, for +the purposes of debugging and system monitoring, insulating applications +from implementation details of the allocators, and allowing a tool to +transparently support multiple allocators. +.Nm +supports both retrieving a single statistics snapshot, as well as +incrementally updating statistics for long-term monitoring. +.Pp +.Nm +describes each memory type using a +.Vt "struct memory_type" , +an opaque memory type accessed by the application using accessor functions +in the library. +.Nm +returns and updates chains of +.Vt "struct memory_type" +via a +.Vt "struct memory_type_list" , +which will be allocated by calling +.Fn memstat_mtl_alloc , +and freed on completion using +.Fn memstat_mtl_free . +Lists of memory types are populated via calls that query the kernel for +statistics information; currently: +.Fn memstat_kvm_all , +.Fn memstat_kvm_malloc , +.Fn memstat_kvm_uma , +.Fn memstat_sysctl_all , +.Fn memstat_sysctl_uma , +and +.Fn memstat_sysctl_malloc . +Repeated calls will incrementally update the list of memory types, permitting +tracking over time without recreating all list state. +If an error is detected during a query call, error condition information may +be retrieved using +.Fn memstat_mtl_geterror , +and converted to a user-readable string using +.Fn memstat_strerror . +.Pp +Freeing the list will free all memory type data in the list, and so +invalidates any outstanding pointers to entries in the list. +.Vt "struct memory_type" +entries in the list may be iterated over using +.Fn memstat_mtl_first +and +.Fn memstat_mtl_next , +which respectively return the first entry in a list, and the next entry in a +list. +.Fn memstat_mtl_find , +which will return a pointer to the first entry matching the passed +parameters. +.Pp +A series of accessor methods is provided to access fields of the structure, +including retrieving statistics and properties, as well as setting of caller +owned fields. +Direct application access to the data structure fields is not supported. +.Ss Library Vt memory_type Ss Fields +Each +.Vt "struct memory_type" +holds a description of the memory type, including its name and the allocator +it is managed by, as well as current statistics on use. +Some statistics are directly measured, others are derived from directly +measured statistics. +Certain high level statistics are present across all available allocators, +such as the number of allocation and free operations; other measurements, +such as the quantity of free items in per-CPU caches, or administrative +limit on the number of allocations, is available only for specific +allocators. +.Ss Caller Vt memory_type Ss Fields +.Vt "struct memory_type" +includes fields to allow the application to store data, in the form of +pointers and 64-bit integers, with memory types. +For example, the application author might make use of one of the caller +pointers to reference a more complex data structure tracking long-term +behavior of the memory type, or a window system object that is used to +render the state of the memory type. +General and per-CPU storage is provided with each +.Vt "struct memory_type" +in the form of an array of pointers and integers. +The array entries are accessed via the +.Fa index +argument to the get and set accessor methods. +Possible values of +.Fa index +range between +0 +and +.Dv MEMSTAT_MAXCALLER . +.Pp +Caller-owned fields are initialized to +0 +or +.Dv NULL +when a new +.Vt "struct memory_type" +is allocated and attached to a memory type list; these fields retain their +values across queries that update library-owned fields. +.Ss Allocator Types +Currently, +.Nm +supports two kernel allocators: +.Dv ALLOCATOR_UMA +for +.Xr uma 9 , +and +.Dv ALLOCATOR_MALLOC +for +.Xr malloc 9 . +These values may be passed to +.Fn memstat_mtl_find , +and will be returned by +.Fn memstat_get_allocator . +Two additional constants in the allocator name space are defined: +.Dv ALLOCATOR_UNKNOWN , +which will only be returned as a result of a library error, and +.Dv ALLOCATOR_ANY , +which can be used to specify that returning types matching any allocator is +permittable from +.Fn memstat_mtl_find . +.Ss Access Method List +The following accessor methods are defined, of which some will be valid for +a given memory type: +.Bl -tag -width indent +.It Fn memstat_get_name +Return a pointer to the name of the memory type. +Memory for the name is owned by +.Nm +and will be valid through a call to +.Fn memstat_mtl_free . +Note that names will be unique with respect to a single allocator, but that +the same name might be used by different memory types owned by different +memory allocators. +.It Fn memstat_get_allocator +Return an integer identifier for the memory allocator that owns the memory +type. +.It Fn memstat_get_countlimit +If the memory type has an administrative limit on the number of simultaneous +allocations, return it. +.It Fn memstat_get_byteslimit +If the memory type has an administrative limit on the number of bytes of +memory that may be simultaneously allocated for the memory type, return it. +.It Fn memstat_get_sizemask +If the memory type supports variable allocation sizes, return a bitmask of +sizes allocated for the memory type. +.It Fn memstat_get_size +If the memory type supports a fixed allocation size, return that size. +.It Fn memstat_get_rsize +If the memory type supports a fixed allocation size, return real size +of an allocation. +Real size can exceed requested size due to alignment constraints or +implicit padding. +.It Fn memstat_get_memalloced +Return the total number of bytes allocated for the memory type over its +lifetime. +.It Fn memstat_get_memfreed +Return the total number of bytes freed for the memory type over its lifetime. +.It Fn memstat_get_numallocs +Return the total number of allocations for the memory type over its lifetime. +.It Fn memstat_get_numfrees +Return the total number of frees for the memory type over its lifetime. +.It Fn memstat_get_bytes +Return the current number of bytes allocated to the memory type. +.It Fn memstat_get_count +Return the current number of allocations for the memory type. +.It Fn memstat_get_free +If the memory allocator supports a cache, return the number of items in the +cache. +.It Fn memstat_get_failures +If the memory allocator and type permit allocation failures, return the +number of allocation failures measured. +.It Fn memstat_get_caller_pointer +Return a caller-owned pointer for the memory type. +.It Fn memstat_set_caller_pointer +Set a caller-owned pointer for the memory type. +.It Fn memstat_get_caller_uint64 +Return a caller-owned integer for the memory type. +.It Fn memstat_set_caller_uint64 +Set a caller-owned integer for the memory type. +.It Fn memstat_get_zonefree +If the memory allocator supports a multi-level allocation structure, return +the number of cached items in the zone. +These items will be in a fully constructed state available for immediate +use. +.It Fn memstat_get_kegfree +If the memory allocator supports a multi-level allocation structure, return +the number of cached items in the keg. +These items may be in a partially constructed state, and may require further +processing before they can be made available for use. +.It Fn memstat_get_percpu_memalloced +If the memory allocator supports per-CPU statistics, return the number of +bytes of memory allocated for the memory type on the CPU over its lifetime. +.It Fn memstat_get_percpu_memfreed +If the memory allocator supports per-CPU statistics, return the number of +bytes of memory freed from the memory type on the CPU over its lifetime. +.It Fn memstat_get_percpu_numallocs +If the memory allocator supports per-CPU statistics, return the number of +allocations for the memory type on the CPU over its lifetime. +.It Fn memstat_get_percpu_numfrees +If the memory allocator supports per-CPU statistics, return the number of +frees for the memory type on the CPU over its lifetime. +.It Fn memstat_get_percpu_sizemask +If the memory allocator supports variable size memory allocation and per-CPU +statistics, return the size bitmask for the memory type on the CPU. +.It Fn memstat_get_percpu_caller_pointer +Return a caller-owned per-CPU pointer for the memory type. +.It Fn memstat_set_percpu_caller_pointer +Set a caller-owned per-CPU pointer for the memory type. +.It Fn memstat_get_percpu_caller_uint64 +Return a caller-owned per-CPU integer for the memory type. +.It Fn memstat_set_percpu_caller_uint64 +Set a caller-owned per-CPU integer for the memory type. +.It Fn memstat_get_percpu_free +If the memory allocator supports a per-CPU cache, return the number of free +items in the per-CPU cache of the designated CPU. +.El +.Sh RETURN VALUES +.Nm +functions fall into three categories: functions returning a pointer to an +object, functions returning an integer return value, and functions +implementing accessor methods returning data from a +.Vt "struct memory_type" . +.Pp +Functions returning a pointer to an object will generally return +.Dv NULL +on failure. +.Fn memstat_mtl_alloc +will return an error value via +.Va errno , +which will consist of the value +.Er ENOMEM . +Functions +.Fn memstat_mtl_first , +.Fn memstat_mtl_next , +and +.Fn memstat_mtl_find +will return +.Dv NULL +when there is no entry or match in the list; however, this is not considered +a failure mode and no error value is available. +.Pp +Functions returning an integer success value will return +0 +on success, or +\-1 +on failure. +If a failure is returned, the list error access method, +.Fn memstat_mtl_geterror , +may be used to retrieve the error state. +The string representation of the error may be retrieved using +.Fn memstat_strerror . +Possible error values are: +.Bl -tag -width ".Dv MEMSTAT_ERROR_KVM_SHORTREAD" +.It Dv MEMSTAT_ERROR_UNDEFINED +Undefined error. +Occurs if +.Fn memstat_mtl_geterror +is called on a list before an error associated with the list has occurred. +.It Dv MEMSTAT_ERROR_NOMEMORY +Insufficient memory. +Occurs if library calls to +.Xr malloc 3 +fail, or if a system call to retrieve kernel statistics fails with +.Er ENOMEM . +.It Dv MEMSTAT_ERROR_VERSION +Returned if the current version of +.Nm +is unable to interpret the statistics data returned by the kernel due to an +explicit version mismatch, or to differences in data structures that cannot +be reconciled. +.It Dv MEMSTAT_ERROR_PERMISSION +Returned if a statistics source returns +.Va errno +values of +.Er EACCES +or +.Er EPERM . +.It Dv MEMSTAT_ERROR_DATAERROR +Returned if +.Nm +is unable to interpret statistics data returned by the data source, even +though there does not appear to be a version problem. +.It Dv MEMSTAT_ERROR_KVM +Returned if +.Nm +experiences an error while using +.Xr kvm 3 +interfaces to query statistics data. +Use +.Xr kvm_geterr 3 +to retrieve the error. +.It Dv MEMSTAT_ERROR_KVM_NOSYMBOL +Returned if +.Nm +is unable to read a required symbol from the kernel being operated on. +.It Dv MEMSTAT_ERROR_KVM_SHORTREAD +Returned if +.Nm +attempts to read data from a live memory image or kernel core dump and +insufficient data is returned. +.El +.Pp +Finally, functions returning data from a +.Vt "struct memory_type" +pointer are not permitted to fail, and directly return either a statistic +or pointer to a string. +.Sh EXAMPLES +Create a memory type list, query the +.Xr uma 9 +memory allocator for available statistics, and print out the number of +allocations performed by the +.Dv mbuf +zone. +.Bd -literal -offset indent +struct memory_type_list *mtlp; +struct memory_type *mtp; +uint64_t mbuf_count; + +mtlp = memstat_mtl_alloc(); +if (mtlp == NULL) + err(-1, "memstat_mtl_alloc"); +if (memstat_sysctl_uma(mtlp, 0) < 0) + err(-1, "memstat_sysctl_uma"); +mtp = memstat_mtl_find(mtlp, ALLOCATOR_UMA, "mbuf"); +if (mtp == NULL) + errx(-1, "memstat_mtl_find: mbuf not found"); +mbuf_count = memstat_get_count(mtp); +memstat_mtl_free(mtlp); + +printf("mbufs: %llu\en", (unsigned long long)mbuf_count); +.Ed +.Sh SEE ALSO +.Xr malloc 9 , +.Xr uma 9 +.Sh HISTORY +The +.Nm +library appeared in +.Fx 6.0 . +.Sh AUTHORS +The kernel memory allocator changes necessary to support a general purpose +monitoring library, along with the library, were written by +.An Robert Watson Aq Mt rwatson@FreeBSD.org . +.Sh BUGS +There are memory allocators in the kernel, such as the VM page allocator +and +.Nm sf_buf +allocator, which are not currently supported by +.Nm . +.Pp +Once a memory type is present on a memory type list, it will not be removed +even if the kernel no longer presents information on the type via its +monitoring interfaces. +In order to flush removed memory types, it is necessary to free the entire +list and allocate a new one. |