Commit | Line | Data |
---|---|---|
1ce46cfe | 1 | /* |
ab5be9fa | 2 | * Copyright (C) 2017 Jérémie Galarneau <jeremie.galarneau@efficios.com> |
1ce46cfe | 3 | * |
ab5be9fa | 4 | * SPDX-License-Identifier: LGPL-2.1-only |
1ce46cfe | 5 | * |
1ce46cfe JG |
6 | */ |
7 | ||
8 | #ifndef LTTNG_USERSPACE_PROBE_H | |
9 | #define LTTNG_USERSPACE_PROBE_H | |
10 | ||
4bd69c5f SM |
11 | #include <lttng/lttng-export.h> |
12 | ||
1ce46cfe JG |
13 | #ifdef __cplusplus |
14 | extern "C" { | |
15 | #endif | |
16 | ||
17 | /* | |
18 | * Userspace probe lookup methods specifies how the userspace probe location | |
19 | * specified by the user should be interpreted. | |
20 | */ | |
21 | struct lttng_userspace_probe_location_lookup_method; | |
22 | ||
23 | enum lttng_userspace_probe_location_lookup_method_type { | |
28f23191 JG |
24 | LTTNG_USERSPACE_PROBE_LOCATION_LOOKUP_METHOD_TYPE_UNKNOWN = -1, |
25 | LTTNG_USERSPACE_PROBE_LOCATION_LOOKUP_METHOD_TYPE_FUNCTION_DEFAULT = 0, | |
26 | LTTNG_USERSPACE_PROBE_LOCATION_LOOKUP_METHOD_TYPE_FUNCTION_ELF = 1, | |
27 | LTTNG_USERSPACE_PROBE_LOCATION_LOOKUP_METHOD_TYPE_TRACEPOINT_SDT = 2, | |
1ce46cfe JG |
28 | }; |
29 | ||
30 | /* | |
31 | * Get the type of a lookup method. | |
32 | */ | |
4bd69c5f | 33 | LTTNG_EXPORT extern enum lttng_userspace_probe_location_lookup_method_type |
1ce46cfe | 34 | lttng_userspace_probe_location_lookup_method_get_type( |
28f23191 | 35 | const struct lttng_userspace_probe_location_lookup_method *lookup_method); |
1ce46cfe JG |
36 | |
37 | /* | |
38 | * Destroy a lookup method. | |
39 | */ | |
4bd69c5f | 40 | LTTNG_EXPORT extern void lttng_userspace_probe_location_lookup_method_destroy( |
28f23191 | 41 | struct lttng_userspace_probe_location_lookup_method *lookup_method); |
1ce46cfe JG |
42 | |
43 | /* | |
44 | * Create a tracepoint ELF function lookup method struct. | |
45 | * Return NULL on failure. | |
46 | */ | |
4bd69c5f | 47 | LTTNG_EXPORT extern struct lttng_userspace_probe_location_lookup_method * |
1ce46cfe JG |
48 | lttng_userspace_probe_location_lookup_method_function_elf_create(void); |
49 | ||
f4d0bb2e FD |
50 | /* |
51 | * Create a tracepoint SDT tracepoint lookup method struct. | |
52 | * Return NULL on failure. | |
53 | */ | |
4bd69c5f | 54 | LTTNG_EXPORT extern struct lttng_userspace_probe_location_lookup_method * |
f4d0bb2e FD |
55 | lttng_userspace_probe_location_lookup_method_tracepoint_sdt_create(void); |
56 | ||
1ce46cfe JG |
57 | /* |
58 | * Contains all the information needed to compute the instrumentation point in | |
59 | * the binary. It is used in conjonction with a lookup method. | |
60 | */ | |
61 | struct lttng_userspace_probe_location; | |
62 | ||
9d3981b5 | 63 | enum lttng_userspace_probe_location_status { |
28f23191 | 64 | LTTNG_USERSPACE_PROBE_LOCATION_STATUS_OK = 0, |
9d3981b5 | 65 | /* Invalid parameters provided. */ |
28f23191 | 66 | LTTNG_USERSPACE_PROBE_LOCATION_STATUS_INVALID = -1, |
9d3981b5 JG |
67 | }; |
68 | ||
1ce46cfe | 69 | enum lttng_userspace_probe_location_type { |
28f23191 | 70 | LTTNG_USERSPACE_PROBE_LOCATION_TYPE_UNKNOWN = -1, |
9d3981b5 | 71 | /* Function. */ |
28f23191 | 72 | LTTNG_USERSPACE_PROBE_LOCATION_TYPE_FUNCTION = 0, |
bff8d217 | 73 | /* SDT probe's callsites. */ |
28f23191 | 74 | LTTNG_USERSPACE_PROBE_LOCATION_TYPE_TRACEPOINT = 1, |
1ce46cfe JG |
75 | }; |
76 | ||
77 | /* | |
78 | * Get the type of the userspace probe location. | |
79 | */ | |
4bd69c5f | 80 | LTTNG_EXPORT extern enum lttng_userspace_probe_location_type |
28f23191 | 81 | lttng_userspace_probe_location_get_type(const struct lttng_userspace_probe_location *location); |
1ce46cfe JG |
82 | |
83 | /* | |
84 | * Destroy the userspace probe location. | |
85 | */ | |
28f23191 JG |
86 | LTTNG_EXPORT extern void |
87 | lttng_userspace_probe_location_destroy(struct lttng_userspace_probe_location *location); | |
9d3981b5 JG |
88 | |
89 | enum lttng_userspace_probe_location_function_instrumentation_type { | |
90 | LTTNG_USERSPACE_PROBE_LOCATION_FUNCTION_INSTRUMENTATION_TYPE_UNKNOWN = -1, | |
91 | /* Only instrument the function's entry. */ | |
92 | LTTNG_USERSPACE_PROBE_LOCATION_FUNCTION_INSTRUMENTATION_TYPE_ENTRY = 0, | |
93 | }; | |
94 | ||
1ce46cfe JG |
95 | /* |
96 | * Create a probe location of the function type. | |
97 | * Receives the target binary file path and function to instrument. | |
98 | * On failure, NULL is returned. | |
99 | * | |
100 | * The ownership of the lookup method is transferred to the created probe | |
101 | * location. | |
102 | */ | |
4bd69c5f | 103 | LTTNG_EXPORT extern struct lttng_userspace_probe_location * |
28f23191 JG |
104 | lttng_userspace_probe_location_function_create( |
105 | const char *binary_path, | |
106 | const char *function_name, | |
107 | struct lttng_userspace_probe_location_lookup_method *lookup_method); | |
1ce46cfe JG |
108 | |
109 | /* | |
110 | * Get the target binary path of the probe location of the function type. | |
111 | */ | |
4bd69c5f | 112 | LTTNG_EXPORT extern const char *lttng_userspace_probe_location_function_get_binary_path( |
28f23191 | 113 | const struct lttng_userspace_probe_location *location); |
1ce46cfe JG |
114 | |
115 | /* | |
116 | * Get the target function type of the probe location of the function type. | |
117 | */ | |
4bd69c5f | 118 | LTTNG_EXPORT extern const char *lttng_userspace_probe_location_function_get_function_name( |
28f23191 | 119 | const struct lttng_userspace_probe_location *location); |
1ce46cfe | 120 | |
394357fe FD |
121 | /* |
122 | * Get the FD to the target binary file to the probe location of the function | |
fe489250 | 123 | * type. The FD is only valid for the duration of the lifetime of `location`. |
394357fe | 124 | */ |
4bd69c5f | 125 | LTTNG_EXPORT extern int lttng_userspace_probe_location_function_get_binary_fd( |
28f23191 | 126 | const struct lttng_userspace_probe_location *location); |
394357fe | 127 | |
9d3981b5 JG |
128 | /* |
129 | * Get the instrumentation type of the function probe location. | |
130 | */ | |
4bd69c5f | 131 | LTTNG_EXPORT extern enum lttng_userspace_probe_location_function_instrumentation_type |
9d3981b5 | 132 | lttng_userspace_probe_location_function_get_instrumentation_type( |
28f23191 | 133 | const struct lttng_userspace_probe_location *location); |
9d3981b5 JG |
134 | |
135 | /* | |
136 | * Get the instrumentation type of the function probe location. | |
137 | * Defaults to | |
138 | * LTTNG_USERSPACE_PROBE_LOCATION_FUNCTION_INSTRUMENTATION_TYPE_ENTRY. | |
139 | * | |
140 | * Returns LTTNG_USERSPACE_PROBE_LOCATION_STATUS_OK on success, | |
141 | * LTTNG_USERSPACE_PROBE_LOCATION_STATUS_INVALID if invalid parameters | |
142 | * are provided. | |
143 | */ | |
4bd69c5f | 144 | LTTNG_EXPORT extern enum lttng_userspace_probe_location_status |
9d3981b5 | 145 | lttng_userspace_probe_location_function_set_instrumentation_type( |
28f23191 JG |
146 | const struct lttng_userspace_probe_location *location, |
147 | enum lttng_userspace_probe_location_function_instrumentation_type instrumentation_type); | |
9d3981b5 | 148 | |
1ce46cfe JG |
149 | /* |
150 | * Get the lookup method of the given userspace probe location. | |
151 | * Returns NULL if the probe location type is unsupported. | |
152 | * | |
153 | * The ownership of the lookup method is NOT transferred to the caller. | |
154 | */ | |
4bd69c5f | 155 | LTTNG_EXPORT extern const struct lttng_userspace_probe_location_lookup_method * |
1ce46cfe | 156 | lttng_userspace_probe_location_get_lookup_method( |
28f23191 | 157 | const struct lttng_userspace_probe_location *location); |
1ce46cfe | 158 | |
f4d0bb2e FD |
159 | /* |
160 | * Create a probe location of the tracepoint type. | |
161 | * Receives the target binary file path, probename and probe provider to | |
162 | * instrument. | |
163 | * On failure, NULL is returned. | |
164 | * | |
165 | * The ownership of the lookup method is transferred to the created probe | |
166 | * location. | |
167 | */ | |
4bd69c5f | 168 | LTTNG_EXPORT extern struct lttng_userspace_probe_location * |
28f23191 JG |
169 | lttng_userspace_probe_location_tracepoint_create( |
170 | const char *binary_path, | |
171 | const char *probe_name, | |
172 | const char *provider_name, | |
173 | struct lttng_userspace_probe_location_lookup_method *lookup_method); | |
f4d0bb2e FD |
174 | |
175 | /* | |
176 | * Get the target binary path of the probe location of the tracepoint type. | |
177 | */ | |
4bd69c5f | 178 | LTTNG_EXPORT extern const char *lttng_userspace_probe_location_tracepoint_get_binary_path( |
28f23191 | 179 | const struct lttng_userspace_probe_location *location); |
f4d0bb2e FD |
180 | |
181 | /* | |
182 | * Get the target probe name of the probe location of the tracepoint type. | |
183 | */ | |
4bd69c5f | 184 | LTTNG_EXPORT extern const char *lttng_userspace_probe_location_tracepoint_get_probe_name( |
28f23191 | 185 | const struct lttng_userspace_probe_location *location); |
f4d0bb2e FD |
186 | |
187 | /* | |
188 | * Get the target probe provider name of the probe location of the tracepoint | |
189 | * type. | |
190 | */ | |
4bd69c5f | 191 | LTTNG_EXPORT extern const char *lttng_userspace_probe_location_tracepoint_get_provider_name( |
28f23191 | 192 | const struct lttng_userspace_probe_location *location); |
f4d0bb2e FD |
193 | |
194 | /* | |
195 | * Get the FD to the target binary file to the probe location of the tracepoint | |
fe489250 | 196 | * type. The FD is only valid for the duration of the lifetime of `location`. |
f4d0bb2e | 197 | */ |
4bd69c5f | 198 | LTTNG_EXPORT extern int lttng_userspace_probe_location_tracepoint_get_binary_fd( |
28f23191 | 199 | const struct lttng_userspace_probe_location *location); |
f4d0bb2e | 200 | |
1ce46cfe JG |
201 | #ifdef __cplusplus |
202 | } | |
203 | #endif | |
204 | ||
205 | #endif /* LTTNG_USERSPACE_PROBE_H */ |