Document additional aspects of libmemstat(3):

- Short description of each memory type access method.

- Descriptions of libmemstat(3) errors and memstat_mtl_geterror(3).

MFC after:	1 day

2 files changed, 171 insertions, 0 deletions

diff --git a/lib/libmemstat/Makefile b/lib/libmemstat/Makefile
index 464400c..e58f99e 100644
--- a/lib/libmemstat/Makefile
+++ b/lib/libmemstat/Makefile
@@ -16,6 +16,7 @@ MLINKS+=	libmemstat.3 memstat_mtl_first.3
 MLINKS+=	libmemstat.3 memstat_mtl_next.3
 MLINKS+=	libmemstat.3 memstat_mtl_find.3
 MLINKS+=	libmemstat.3 memstat_mtl_free.3
+MLINKS+=	libmemstat.3 memstat_mtl_geterror.3
 MLINKS+=	libmemstat.3 memstat_sysctl_all.3
 MLINKS+=	libmemstat.3 memstat_sysctl_malloc.3
 MLINKS+=	libmemstat.3 memstat_sysctl_uma.3
diff --git a/lib/libmemstat/libmemstat.3 b/lib/libmemstat/libmemstat.3
index a97d7ba..2e9f0bf 100644
--- a/lib/libmemstat/libmemstat.3
+++ b/lib/libmemstat/libmemstat.3
@@ -46,6 +46,8 @@
 .Fn memstat_mtl_find "struct memory_type_list *list" "int allocator" "const char *name"
 .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_sysctl_all "struct memory_type_list *list" "int flags"
@@ -146,6 +148,10 @@ 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 .
+.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
@@ -226,6 +232,170 @@ which will only be returned as a result of a library error, and
 which can be used to specify that returning types matching any allocator is
 permittible 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:
+.Pp
+.Bl -tag -width "memstat_get_name" -compact -offset wee
+.It 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 memstat_get_allocator
+Return an integer identifier for the memory allocator that owns the memory
+type.
+.It memstat_get_countlimit
+If the memory type has an administrative limit on the number of simultaneous
+allocations, return it.
+.It memstat_get_byteslimit
+If the memory type has an administrative limit on the number of bytes of
+memory that may be simultaenously allocated for the memory type, return it.
+.It memstat_get_sizemask
+If the memory type supports variable allocation sizes, return a bitmask of
+sizes allocated for the memory type.
+.It memstat_get_size
+If the memory type supports a fixed allocation size, return that size.
+.It memstat_get_memalloced
+Return the total number of bytes allocated for the memory type over its
+lifetime.
+.It memstat_get_memfreed
+Return the total number of bytes freed for the memory type over its lifetime.
+.It memstat_get_numallocs
+Return the total number of allocations for the memory type over its lifetime.
+.It memstat_get_numfrees
+Return the total number of frees for the memory type over its lifetime.
+.It memstat_get_bytes
+Return the current number of bytes allocated to the memory type.
+.It memstat_get_count
+Return the current number of allocations for the memory type.
+.It memstat_get_free
+If the memory allocator supports a cache, return the number of items in the
+cache.
+.It memstat_get_failures
+If the memory allocator and type permit allocation failures, return the
+number of allocation failures measured.
+.It memstat_get_caller_pointer
+Return a caller-owned pointer for the memory type.
+.It memstat_set_caller_pointer
+Set a caller-owned pointer for the memory type.
+.It memstat_get_caller_uint64
+Return a caller-owned integer for the memory type.
+.It memstat_set_caller_uint64
+Set a caller-owned integer for the memory type.
+.It 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 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 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 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 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 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 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 memstat_get_percpu_caller_pointer
+Return a caller-owned per-CPU pointer for the memory type.
+.It memstat_set_percpu_caller_pointer
+Set a caller-owned per-CPU pointer for the memory type.
+.It memstat_get_percpu_caller_uint64
+Return a caller-owned per-CPU integer for the memory type.
+.It memsttat_set_percpu_caller_uint64
+Set a caller-owned per-CPU integer for the memory type.
+.It 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
+.Dv 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 a integer success valuye will return
+.Dv 0
+on success, or
+.Dv -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.  Possible error values are:
+.Pp
+.Bl -tag -width "MEMSTAT_ERROR_TOOMANYCPUS" -compact -offset wee
+.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
+.Dv EACCES
+or
+.Dv EPERM .
+.It Dv MEMSTAT_ERROR_TOOMANYCPUS
+Returned if the compile-time limit on the number of CPUs in
+.Nm
+is lower than the number of CPUs returned by a statistics data source.
+.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.
+.El
+.Pp
+Finally, functions returning data from a
+.Dt 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