xref: /freebsd/lib/libmemstat/memstat.h (revision 1e413cf93298b5b97441a21d9a50fdcd0ee9945e)
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  * Number of CPU slots in library-internal data structures.  This should be
34  * at least the value of MAXCPU from param.h.
35  */
36 #define	MEMSTAT_MAXCPU	32
37 
38 /*
39  * Amount of caller data to maintain for each caller data slot.  Applications
40  * must not request more than this number of caller save data, or risk
41  * corrupting internal libmemstat(3) data structures.  A compile time check
42  * in the application is probably appropriate.
43  */
44 #define	MEMSTAT_MAXCALLER	16
45 
46 /*
47  * libmemstat(3) is able to extract memory data from different allocators;
48  * when it does so, it tags which allocator it got the data from so that
49  * consumers can determine which fields are usable, as data returned varies
50  * some.
51  */
52 #define	ALLOCATOR_UNKNOWN	0
53 #define	ALLOCATOR_MALLOC	1
54 #define	ALLOCATOR_UMA		2
55 #define	ALLOCATOR_ANY		255
56 
57 /*
58  * Library maximum type name.  Should be max(set of name maximums over
59  * various allocators).
60  */
61 #define	MEMTYPE_MAXNAME		32
62 
63 /*
64  * Library error conditions, mostly from the underlying data sources.  On
65  * failure, functions typically return (-1) or (NULL); on success, (0) or a
66  * valid data pointer.  The error from the last operation is stored in
67  * struct memory_type_list, and accessed via memstat_get_error(list).
68  */
69 #define	MEMSTAT_ERROR_UNDEFINED		0	/* Initialization value. */
70 #define	MEMSTAT_ERROR_NOMEMORY		1	/* Out of memory. */
71 #define	MEMSTAT_ERROR_VERSION		2	/* Unsupported version. */
72 #define	MEMSTAT_ERROR_PERMISSION	3	/* Permission denied. */
73 #define	MEMSTAT_ERROR_TOOMANYCPUS	4	/* Too many CPUs. */
74 #define	MEMSTAT_ERROR_DATAERROR		5	/* Error in stat data. */
75 #define	MEMSTAT_ERROR_KVM		6	/* See kvm_geterr() for err. */
76 #define	MEMSTAT_ERROR_KVM_NOSYMBOL	7	/* Symbol not available. */
77 #define	MEMSTAT_ERROR_KVM_SHORTREAD	8	/* Short kvm_read return. */
78 
79 /*
80  * Forward declare struct memory_type, which holds per-type properties and
81  * statistics.  This is an opaque type, to be frobbed only from within the
82  * library, in order to avoid building ABI assumptions into the application.
83  * Accessor methods should be used to get and sometimes set the fields from
84  * consumers of the library.
85  */
86 struct memory_type;
87 
88 /*
89  * struct memory_type_list is the head of a list of memory types and
90  * statistics.
91  */
92 struct memory_type_list;
93 
94 __BEGIN_DECLS
95 /*
96  * Functions that operate without memory type or memory type list context.
97  */
98 const char	*memstat_strerror(int error);
99 
100 /*
101  * Functions for managing memory type and statistics data.
102  */
103 struct memory_type_list	*memstat_mtl_alloc(void);
104 struct memory_type	*memstat_mtl_first(struct memory_type_list *list);
105 struct memory_type	*memstat_mtl_next(struct memory_type *mtp);
106 struct memory_type	*memstat_mtl_find(struct memory_type_list *list,
107 			    int allocator, const char *name);
108 void	memstat_mtl_free(struct memory_type_list *list);
109 int	memstat_mtl_geterror(struct memory_type_list *list);
110 
111 /*
112  * Functions to retrieve data from a live kernel using sysctl.
113  */
114 int	memstat_sysctl_all(struct memory_type_list *list, int flags);
115 int	memstat_sysctl_malloc(struct memory_type_list *list, int flags);
116 int	memstat_sysctl_uma(struct memory_type_list *list, int flags);
117 
118 /*
119  * Functions to retrieve data from a kernel core (or /dev/kmem).
120  */
121 int	memstat_kvm_all(struct memory_type_list *list, void *kvm_handle);
122 int	memstat_kvm_malloc(struct memory_type_list *list, void *kvm_handle);
123 int	memstat_kvm_uma(struct memory_type_list *list, void *kvm_handle);
124 
125 /*
126  * Accessor methods for struct memory_type.
127  */
128 const char	*memstat_get_name(const struct memory_type *mtp);
129 int		 memstat_get_allocator(const struct memory_type *mtp);
130 uint64_t	 memstat_get_countlimit(const struct memory_type *mtp);
131 uint64_t	 memstat_get_byteslimit(const struct memory_type *mtp);
132 uint64_t	 memstat_get_sizemask(const struct memory_type *mtp);
133 uint64_t	 memstat_get_size(const struct memory_type *mtp);
134 uint64_t	 memstat_get_memalloced(const struct memory_type *mtp);
135 uint64_t	 memstat_get_memfreed(const struct memory_type *mtp);
136 uint64_t	 memstat_get_numallocs(const struct memory_type *mtp);
137 uint64_t	 memstat_get_numfrees(const struct memory_type *mtp);
138 uint64_t	 memstat_get_bytes(const struct memory_type *mtp);
139 uint64_t	 memstat_get_count(const struct memory_type *mtp);
140 uint64_t	 memstat_get_free(const struct memory_type *mtp);
141 uint64_t	 memstat_get_failures(const struct memory_type *mtp);
142 void		*memstat_get_caller_pointer(const struct memory_type *mtp,
143 		    int index);
144 void		 memstat_set_caller_pointer(struct memory_type *mtp,
145 		    int index, void *value);
146 uint64_t	 memstat_get_caller_uint64(const struct memory_type *mtp,
147 		    int index);
148 void		 memstat_set_caller_uint64(struct memory_type *mtp, int index,
149 		    uint64_t value);
150 uint64_t	 memstat_get_zonefree(const struct memory_type *mtp);
151 uint64_t	 memstat_get_kegfree(const struct memory_type *mtp);
152 uint64_t	 memstat_get_percpu_memalloced(const struct memory_type *mtp,
153 		    int cpu);
154 uint64_t	 memstat_get_percpu_memfreed(const struct memory_type *mtp,
155 		    int cpu);
156 uint64_t	 memstat_get_percpu_numallocs(const struct memory_type *mtp,
157 		    int cpu);
158 uint64_t	 memstat_get_percpu_numfrees(const struct memory_type *mtp,
159 		    int cpu);
160 uint64_t	 memstat_get_percpu_sizemask(const struct memory_type *mtp,
161 		    int cpu);
162 void		*memstat_get_percpu_caller_pointer(
163 		    const struct memory_type *mtp, int cpu, int index);
164 void		 memstat_set_percpu_caller_pointer(struct memory_type *mtp,
165 		    int cpu, int index, void *value);
166 uint64_t	 memstat_get_percpu_caller_uint64(
167 		    const struct memory_type *mtp, int cpu, int index);
168 void		 memstat_set_percpu_caller_uint64(struct memory_type *mtp,
169 		    int cpu, int index, uint64_t value);
170 uint64_t	 memstat_get_percpu_free(const struct memory_type *mtp,
171 		    int cpu);
172 __END_DECLS
173 
174 #endif /* !_MEMSTAT_H_ */
175