lib/libmemstat/memstat.h

   1 /*-
   2  * SPDX-License-Identifier: BSD-2-Clause-FreeBSD
   3  *
   4  * Copyright (c) 2005 Robert N. M. Watson
   5  * All rights reserved.
   6  *
   7  * Redistribution and use in source and binary forms, with or without
   8  * modification, are permitted provided that the following conditions
   9  * are met:
  10  * 1. Redistributions of source code must retain the above copyright
  11  *    notice, this list of conditions and the following disclaimer.
  12  * 2. Redistributions in binary form must reproduce the above copyright
  13  *    notice, this list of conditions and the following disclaimer in the
  14  *    documentation and/or other materials provided with the distribution.
  15  *
  16  * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  17  * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19  * ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  20  * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  21  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  22  * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  23  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  24  * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  25  * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  26  * SUCH DAMAGE.
  27  *
  28  * $FreeBSD$
  29  */
  30
  31 #ifndef _MEMSTAT_H_
  32 #define _MEMSTAT_H_
  33
  34 /*
  35  * Amount of caller data to maintain for each caller data slot.  Applications
  36  * must not request more than this number of caller save data, or risk
  37  * corrupting internal libmemstat(3) data structures.  A compile time check
  38  * in the application is probably appropriate.
  39  */
  40 #define MEMSTAT_MAXCALLER       16
  41
  42 /*
  43  * libmemstat(3) is able to extract memory data from different allocators;
  44  * when it does so, it tags which allocator it got the data from so that
  45  * consumers can determine which fields are usable, as data returned varies
  46  * some.
  47  */
  48 #define ALLOCATOR_UNKNOWN       0
  49 #define ALLOCATOR_MALLOC        1
  50 #define ALLOCATOR_UMA           2
  51 #define ALLOCATOR_ANY           255
  52
  53 /*
  54  * Library maximum type name.  Should be max(set of name maximums over
  55  * various allocators).
  56  */
  57 #define MEMTYPE_MAXNAME         32
  58
  59 /*
  60  * Library error conditions, mostly from the underlying data sources.  On
  61  * failure, functions typically return (-1) or (NULL); on success, (0) or a
  62  * valid data pointer.  The error from the last operation is stored in
  63  * struct memory_type_list, and accessed via memstat_get_error(list).
  64  */
  65 #define MEMSTAT_ERROR_UNDEFINED         0       /* Initialization value. */
  66 #define MEMSTAT_ERROR_NOMEMORY          1       /* Out of memory. */
  67 #define MEMSTAT_ERROR_VERSION           2       /* Unsupported version. */
  68 #define MEMSTAT_ERROR_PERMISSION        3       /* Permission denied. */
  69 #define MEMSTAT_ERROR_DATAERROR         5       /* Error in stat data. */
  70 #define MEMSTAT_ERROR_KVM               6       /* See kvm_geterr() for err. */
  71 #define MEMSTAT_ERROR_KVM_NOSYMBOL      7       /* Symbol not available. */
  72 #define MEMSTAT_ERROR_KVM_SHORTREAD     8       /* Short kvm_read return. */
  73
  74 /*
  75  * Forward declare struct memory_type, which holds per-type properties and
  76  * statistics.  This is an opaque type, to be frobbed only from within the
  77  * library, in order to avoid building ABI assumptions into the application.
  78  * Accessor methods should be used to get and sometimes set the fields from
  79  * consumers of the library.
  80  */
  81 struct memory_type;
  82
  83 /*
  84  * struct memory_type_list is the head of a list of memory types and
  85  * statistics.
  86  */
  87 struct memory_type_list;
  88
  89 __BEGIN_DECLS
  90 /*
  91  * Functions that operate without memory type or memory type list context.
  92  */
  93 const char      *memstat_strerror(int error);
  94
  95 /*
  96  * Functions for managing memory type and statistics data.
  97  */
  98 struct memory_type_list *memstat_mtl_alloc(void);
  99 struct memory_type      *memstat_mtl_first(struct memory_type_list *list);
 100 struct memory_type      *memstat_mtl_next(struct memory_type *mtp);
 101 struct memory_type      *memstat_mtl_find(struct memory_type_list *list,
 102                             int allocator, const char *name);
 103 void    memstat_mtl_free(struct memory_type_list *list);
 104 int     memstat_mtl_geterror(struct memory_type_list *list);
 105
 106 /*
 107  * Functions to retrieve data from a live kernel using sysctl.
 108  */
 109 int     memstat_sysctl_all(struct memory_type_list *list, int flags);
 110 int     memstat_sysctl_malloc(struct memory_type_list *list, int flags);
 111 int     memstat_sysctl_uma(struct memory_type_list *list, int flags);
 112
 113 /*
 114  * Functions to retrieve data from a kernel core (or /dev/kmem).
 115  */
 116 int     memstat_kvm_all(struct memory_type_list *list, void *kvm_handle);
 117 int     memstat_kvm_malloc(struct memory_type_list *list, void *kvm_handle);
 118 int     memstat_kvm_uma(struct memory_type_list *list, void *kvm_handle);
 119
 120 /*
 121  * Accessor methods for struct memory_type.
 122  */
 123 const char      *memstat_get_name(const struct memory_type *mtp);
 124 int              memstat_get_allocator(const struct memory_type *mtp);
 125 uint64_t         memstat_get_countlimit(const struct memory_type *mtp);
 126 uint64_t         memstat_get_byteslimit(const struct memory_type *mtp);
 127 uint64_t         memstat_get_sizemask(const struct memory_type *mtp);
 128 uint64_t         memstat_get_size(const struct memory_type *mtp);
 129 uint64_t         memstat_get_rsize(const struct memory_type *mtp);
 130 uint64_t         memstat_get_memalloced(const struct memory_type *mtp);
 131 uint64_t         memstat_get_memfreed(const struct memory_type *mtp);
 132 uint64_t         memstat_get_numallocs(const struct memory_type *mtp);
 133 uint64_t         memstat_get_numfrees(const struct memory_type *mtp);
 134 uint64_t         memstat_get_bytes(const struct memory_type *mtp);
 135 uint64_t         memstat_get_count(const struct memory_type *mtp);
 136 uint64_t         memstat_get_free(const struct memory_type *mtp);
 137 uint64_t         memstat_get_failures(const struct memory_type *mtp);
 138 uint64_t         memstat_get_sleeps(const struct memory_type *mtp);
 139 void            *memstat_get_caller_pointer(const struct memory_type *mtp,
 140                     int index);
 141 void             memstat_set_caller_pointer(struct memory_type *mtp,
 142                     int index, void *value);
 143 uint64_t         memstat_get_caller_uint64(const struct memory_type *mtp,
 144                     int index);
 145 void             memstat_set_caller_uint64(struct memory_type *mtp, int index,
 146                     uint64_t value);
 147 uint64_t         memstat_get_zonefree(const struct memory_type *mtp);
 148 uint64_t         memstat_get_kegfree(const struct memory_type *mtp);
 149 uint64_t         memstat_get_percpu_memalloced(const struct memory_type *mtp,
 150                     int cpu);
 151 uint64_t         memstat_get_percpu_memfreed(const struct memory_type *mtp,
 152                     int cpu);
 153 uint64_t         memstat_get_percpu_numallocs(const struct memory_type *mtp,
 154                     int cpu);
 155 uint64_t         memstat_get_percpu_numfrees(const struct memory_type *mtp,
 156                     int cpu);
 157 uint64_t         memstat_get_percpu_sizemask(const struct memory_type *mtp,
 158                     int cpu);
 159 void            *memstat_get_percpu_caller_pointer(
 160                     const struct memory_type *mtp, int cpu, int index);
 161 void             memstat_set_percpu_caller_pointer(struct memory_type *mtp,
 162                     int cpu, int index, void *value);
 163 uint64_t         memstat_get_percpu_caller_uint64(
 164                     const struct memory_type *mtp, int cpu, int index);
 165 void             memstat_set_percpu_caller_uint64(struct memory_type *mtp,
 166                     int cpu, int index, uint64_t value);
 167 uint64_t         memstat_get_percpu_free(const struct memory_type *mtp,
 168                     int cpu);
 169 __END_DECLS
 170
 171 #endif /* !_MEMSTAT_H_ */