Commit | Line | Data |
---|---|---|
ebdb334b JR |
1 | /* |
2 | * Copyright (C) 2020 Francis Deslauriers <francis.deslauriers@efficios.com> | |
3 | * | |
4 | * SPDX-License-Identifier: LGPL-2.1-only | |
5 | * | |
6 | */ | |
7 | ||
8 | #ifndef LTTNG_MAP_H | |
9 | #define LTTNG_MAP_H | |
10 | ||
11 | #include <stddef.h> | |
12 | #include <stdbool.h> | |
13 | ||
14 | #include <lttng/domain.h> | |
15 | #include <lttng/handle.h> | |
16 | ||
17 | #include <lttng/map/map-query.h> | |
18 | ||
19 | struct lttng_map; | |
20 | struct lttng_map_list; | |
21 | ||
22 | struct lttng_map_key_value_pair; | |
23 | /* A list of key value pair. */ | |
24 | struct lttng_map_key_value_pair_list; | |
25 | /* A list of key value pair list. */ | |
26 | struct lttng_map_content; | |
27 | ||
28 | #ifdef __cplusplus | |
29 | extern "C" { | |
30 | #endif | |
31 | ||
32 | enum lttng_map_status { | |
33 | LTTNG_MAP_STATUS_OK = 0, | |
34 | LTTNG_MAP_STATUS_ERROR = -1, | |
35 | LTTNG_MAP_STATUS_INVALID = -2, | |
36 | LTTNG_MAP_STATUS_UNSET = -3, | |
37 | }; | |
38 | ||
39 | enum lttng_map_bitness { | |
40 | LTTNG_MAP_BITNESS_32BITS = 32, | |
41 | LTTNG_MAP_BITNESS_64BITS = 64, | |
42 | }; | |
43 | ||
44 | enum lttng_map_boundary_policy { | |
45 | LTTNG_MAP_BOUNDARY_POLICY_OVERFLOW, | |
46 | }; | |
47 | ||
48 | enum lttng_map_key_value_pair_list_type { | |
49 | LTTNG_MAP_KEY_VALUE_PAIR_LIST_TYPE_KERNEL, | |
50 | LTTNG_MAP_KEY_VALUE_PAIR_LIST_TYPE_UST_PER_UID, | |
51 | LTTNG_MAP_KEY_VALUE_PAIR_LIST_TYPE_UST_PER_PID, | |
52 | LTTNG_MAP_KEY_VALUE_PAIR_LIST_TYPE_UST_PER_PID_AGGREGATED, | |
53 | }; | |
54 | ||
55 | /* | |
56 | * | |
57 | * Return LTTNG_MAP_STATUS_OK on success, LTTNG_MAP_STATUS_INVALID if invalid | |
58 | * parameters are passed. | |
59 | */ | |
60 | extern enum lttng_map_status lttng_map_create(const char *name, | |
61 | unsigned int dimension_count, | |
62 | uint64_t *dimension_sizes, | |
63 | enum lttng_domain_type domain, | |
64 | enum lttng_buffer_type buffer_type, | |
65 | enum lttng_map_bitness bitness, | |
66 | enum lttng_map_boundary_policy boundary_policy, | |
67 | bool coalesce_hits, | |
68 | struct lttng_map **map); | |
69 | ||
70 | extern enum lttng_map_status lttng_map_get_name( | |
71 | const struct lttng_map *map, const char **name); | |
72 | ||
73 | extern enum lttng_map_status lttng_map_set_name( | |
74 | struct lttng_map *map, const char *name); | |
75 | ||
76 | /* | |
77 | * Get the number of dimensions. | |
78 | * | |
79 | */ | |
80 | extern unsigned int lttng_map_get_dimension_count( | |
81 | const struct lttng_map *map); | |
82 | ||
83 | /* | |
84 | * Get the number of elements for the provided dimension. | |
85 | * | |
86 | * Return LTTNG_MAP_STATUS_OK on success, LTTNG_MAP_STATUS_INVALID if invalid | |
87 | * parameters are passed. | |
88 | * | |
89 | */ | |
90 | extern enum lttng_map_status lttng_map_get_dimension_length( | |
91 | const struct lttng_map *map, unsigned int dimension, | |
92 | uint64_t *dimension_length); | |
93 | ||
94 | extern int lttng_map_get_is_enabled(const struct lttng_map *map); | |
95 | ||
96 | extern enum lttng_map_bitness lttng_map_get_bitness( | |
97 | const struct lttng_map *map); | |
98 | ||
99 | extern enum lttng_domain_type lttng_map_get_domain( | |
100 | const struct lttng_map *map); | |
101 | ||
102 | extern enum lttng_buffer_type lttng_map_get_buffer_type( | |
103 | const struct lttng_map *map); | |
104 | ||
105 | extern enum lttng_map_boundary_policy lttng_map_get_boundary_policy( | |
106 | const struct lttng_map *map); | |
107 | ||
108 | extern bool lttng_map_get_coalesce_hits( | |
109 | const struct lttng_map *map); | |
110 | ||
111 | extern void lttng_map_destroy(struct lttng_map *map); | |
112 | ||
113 | extern enum lttng_error_code lttng_add_map(struct lttng_handle *handle, | |
114 | struct lttng_map *map); | |
115 | ||
116 | extern enum lttng_error_code lttng_enable_map(struct lttng_handle *handle, | |
117 | const char *map_name); | |
118 | ||
119 | extern enum lttng_error_code lttng_disable_map(struct lttng_handle *handle, | |
120 | const char *map_name); | |
121 | ||
122 | ||
123 | /* | |
124 | * Get a map from the list at a given index. | |
125 | * | |
126 | * Note that the map list maintains the ownership of the returned map. | |
127 | * It must not be destroyed by the user, nor should a reference to it be held | |
128 | * beyond the lifetime of the map list. | |
129 | * | |
130 | * Returns a map, or NULL on error. | |
131 | */ | |
132 | extern const struct lttng_map *lttng_map_list_get_at_index( | |
133 | const struct lttng_map_list *map_list, unsigned int index); | |
134 | ||
135 | /* | |
136 | * Get the number of map in a map list. | |
137 | */ | |
138 | ||
139 | extern enum lttng_map_status lttng_map_list_get_count( | |
140 | const struct lttng_map_list *map_list, unsigned int *count); | |
141 | ||
142 | /* | |
143 | * Destroy a map list. | |
144 | */ | |
145 | extern void lttng_map_list_destroy(struct lttng_map_list *map_list); | |
146 | ||
147 | extern enum lttng_error_code lttng_list_maps(struct lttng_handle *handle, | |
148 | struct lttng_map_list **map_list); | |
149 | ||
150 | /* | |
151 | * FIXME: frdeso proper explanation | |
152 | * lttng_map_content 1 to N lttng_map_key_value_pair_list | |
153 | * lttng_map_key_value_pair_list 1 to N lttng_map_key_value_pair | |
154 | */ | |
155 | ||
156 | /* | |
157 | * Get the key of a key-value. | |
158 | * | |
159 | * The caller does not assume the ownership of the returned key. | |
160 | * The key shall only be used for the duration of the key-value's lifetime. | |
161 | * | |
162 | * Returns LTTNG_MAP_STATUS_OK and a pointer to the key-value's key on success, | |
163 | * LTTNG_MAP_STATUS_INVALID if an invalid parameter is passed, or | |
164 | */ | |
165 | extern enum lttng_map_status lttng_map_key_value_pair_get_key( | |
166 | const struct lttng_map_key_value_pair *kv_pair, const char **key); | |
167 | ||
168 | extern bool lttng_map_key_value_pair_get_has_overflowed( | |
169 | const struct lttng_map_key_value_pair *key_value); | |
170 | ||
171 | extern bool lttng_map_key_value_pair_get_has_underflowed( | |
172 | const struct lttng_map_key_value_pair *key_value); | |
173 | /* | |
174 | * Get the value of a key-value. | |
175 | * | |
176 | * The caller does not assume the ownership of the returned value. | |
177 | * The value shall only be used for the duration of the key-value's lifetime. | |
178 | * | |
179 | * Returns LTTNG_MAP_STATUS_OK and a pointer to the key-value's value on success, | |
180 | * LTTNG_MAP_STATUS_INVALID if an invalid parameter is passed. | |
181 | */ | |
182 | extern enum lttng_map_status lttng_map_key_value_pair_get_value( | |
183 | const struct lttng_map_key_value_pair *kv_pair, int64_t *value); | |
184 | ||
185 | extern enum lttng_map_status lttng_map_content_get_count( | |
186 | const struct lttng_map_content *map_content, | |
187 | unsigned int *count); | |
188 | ||
189 | extern const struct lttng_map_key_value_pair_list *lttng_map_content_get_at_index( | |
190 | const struct lttng_map_content *map_content, | |
191 | unsigned int index); | |
192 | /* | |
193 | * List all key-value pairs for the given session and map. | |
194 | * | |
195 | * On success, a newly-allocated key-value list is returned. | |
196 | * | |
197 | * The key-value list must be destroyed by the caller (see | |
198 | * lttng_map_key_value_pair_list_destroy()). | |
199 | * | |
200 | * Returns LTTNG_OK on success, else a suitable LTTng error code. | |
201 | */ | |
202 | extern enum lttng_error_code lttng_list_map_content( | |
203 | struct lttng_handle *handle, const struct lttng_map *map, | |
204 | const struct lttng_map_query *map_query, | |
205 | struct lttng_map_content **map_content); | |
206 | ||
207 | extern enum lttng_buffer_type lttng_map_content_get_buffer_type( | |
208 | const struct lttng_map_content *map_content); | |
209 | ||
210 | extern void lttng_map_content_destroy( | |
211 | struct lttng_map_content *map_content); | |
212 | /* | |
213 | * Get a key-value from the list at a given index. | |
214 | * | |
215 | * Note that the key value list maintains the ownership of the returned key | |
216 | * value. | |
217 | * It must not be destroyed by the user, nor should a reference to it be held | |
218 | * beyond the lifetime of the key value list. | |
219 | * | |
220 | * Returns a key-value, or NULL on error. | |
221 | */ | |
222 | extern const struct lttng_map_key_value_pair *lttng_map_key_value_pair_list_get_at_index( | |
223 | const struct lttng_map_key_value_pair_list *kv_pair_list, | |
224 | unsigned int index); | |
225 | ||
226 | /* | |
227 | * Get the number of key value pair in a key-value list. | |
228 | * | |
229 | * Return LTTNG_MAP_STATUS_OK on success, | |
230 | * LTTNG_MAP_STATUS_INVALID when invalid parameters are passed. | |
231 | */ | |
232 | extern enum lttng_map_status lttng_map_key_value_pair_list_get_count( | |
233 | const struct lttng_map_key_value_pair_list *kv_pair_list, | |
234 | unsigned int *count); | |
235 | ||
236 | extern enum lttng_map_key_value_pair_list_type lttng_map_key_value_pair_list_get_type( | |
237 | const struct lttng_map_key_value_pair_list *kv_pair_list); | |
238 | ||
239 | extern uint64_t lttng_map_key_value_pair_list_get_identifer( | |
240 | const struct lttng_map_key_value_pair_list *kv_pair_list); | |
241 | ||
242 | extern uint64_t lttng_map_key_value_pair_list_get_cpu( | |
243 | const struct lttng_map_key_value_pair_list *kv_pair_list); | |
244 | ||
245 | extern bool lttng_map_key_value_pair_list_get_summed_all_cpu( | |
246 | const struct lttng_map_key_value_pair_list *kv_pair_list); | |
247 | ||
248 | /* | |
249 | * Destroy a map_key_value set. | |
250 | */ | |
251 | extern void lttng_map_key_value_pair_list_destroy( | |
252 | struct lttng_map_key_value_pair_list *kv_pair_list); | |
253 | ||
254 | #ifdef __cplusplus | |
255 | } | |
256 | #endif | |
257 | ||
258 | #endif /* LTTNG_MAP_H */ |