lib/libmemstat/memstat.h

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