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 { | |
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, | |
f4d0bb2e | 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 JG |
34 | lttng_userspace_probe_location_lookup_method_get_type( |
35 | const struct lttng_userspace_probe_location_lookup_method *lookup_method); | |
36 | ||
37 | /* | |
38 | * Destroy a lookup method. | |
39 | */ | |
4bd69c5f | 40 | LTTNG_EXPORT extern void lttng_userspace_probe_location_lookup_method_destroy( |
1ce46cfe JG |
41 | struct lttng_userspace_probe_location_lookup_method *lookup_method); |
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 | /* | |
59 | * Contains all the information needed to compute the instrumentation point in | |
60 | * the binary. It is used in conjonction with a lookup method. | |
61 | */ | |
62 | struct lttng_userspace_probe_location; | |
63 | ||
9d3981b5 JG |
64 | enum lttng_userspace_probe_location_status { |
65 | LTTNG_USERSPACE_PROBE_LOCATION_STATUS_OK = 0, | |
66 | /* Invalid parameters provided. */ | |
67 | LTTNG_USERSPACE_PROBE_LOCATION_STATUS_INVALID = -1, | |
68 | }; | |
69 | ||
1ce46cfe JG |
70 | enum lttng_userspace_probe_location_type { |
71 | LTTNG_USERSPACE_PROBE_LOCATION_TYPE_UNKNOWN = -1, | |
9d3981b5 | 72 | /* Function. */ |
1ce46cfe | 73 | LTTNG_USERSPACE_PROBE_LOCATION_TYPE_FUNCTION = 0, |
bff8d217 | 74 | /* SDT probe's callsites. */ |
f4d0bb2e | 75 | LTTNG_USERSPACE_PROBE_LOCATION_TYPE_TRACEPOINT = 1, |
1ce46cfe JG |
76 | }; |
77 | ||
78 | /* | |
79 | * Get the type of the userspace probe location. | |
80 | */ | |
4bd69c5f | 81 | LTTNG_EXPORT extern enum lttng_userspace_probe_location_type |
1ce46cfe JG |
82 | lttng_userspace_probe_location_get_type( |
83 | const struct lttng_userspace_probe_location *location); | |
84 | ||
85 | /* | |
86 | * Destroy the userspace probe location. | |
87 | */ | |
4bd69c5f | 88 | LTTNG_EXPORT extern void lttng_userspace_probe_location_destroy( |
1ce46cfe JG |
89 | struct lttng_userspace_probe_location *location); |
90 | ||
9d3981b5 JG |
91 | |
92 | enum lttng_userspace_probe_location_function_instrumentation_type { | |
93 | LTTNG_USERSPACE_PROBE_LOCATION_FUNCTION_INSTRUMENTATION_TYPE_UNKNOWN = -1, | |
94 | /* Only instrument the function's entry. */ | |
95 | LTTNG_USERSPACE_PROBE_LOCATION_FUNCTION_INSTRUMENTATION_TYPE_ENTRY = 0, | |
96 | }; | |
97 | ||
1ce46cfe JG |
98 | /* |
99 | * Create a probe location of the function type. | |
100 | * Receives the target binary file path and function to instrument. | |
101 | * On failure, NULL is returned. | |
102 | * | |
103 | * The ownership of the lookup method is transferred to the created probe | |
104 | * location. | |
105 | */ | |
4bd69c5f | 106 | LTTNG_EXPORT extern struct lttng_userspace_probe_location * |
1ce46cfe JG |
107 | lttng_userspace_probe_location_function_create(const char *binary_path, |
108 | const char *function_name, | |
109 | struct lttng_userspace_probe_location_lookup_method *lookup_method); | |
110 | ||
111 | /* | |
112 | * Get the target binary path of the probe location of the function type. | |
113 | */ | |
4bd69c5f | 114 | LTTNG_EXPORT extern const char *lttng_userspace_probe_location_function_get_binary_path( |
1ce46cfe JG |
115 | const struct lttng_userspace_probe_location *location); |
116 | ||
117 | /* | |
118 | * Get the target function type of the probe location of the function type. | |
119 | */ | |
4bd69c5f | 120 | LTTNG_EXPORT extern const char *lttng_userspace_probe_location_function_get_function_name( |
1ce46cfe JG |
121 | const struct lttng_userspace_probe_location *location); |
122 | ||
394357fe FD |
123 | /* |
124 | * Get the FD to the target binary file to the probe location of the function | |
fe489250 | 125 | * type. The FD is only valid for the duration of the lifetime of `location`. |
394357fe | 126 | */ |
4bd69c5f | 127 | LTTNG_EXPORT extern int lttng_userspace_probe_location_function_get_binary_fd( |
394357fe FD |
128 | const struct lttng_userspace_probe_location *location); |
129 | ||
9d3981b5 JG |
130 | /* |
131 | * Get the instrumentation type of the function probe location. | |
132 | */ | |
4bd69c5f | 133 | LTTNG_EXPORT extern enum lttng_userspace_probe_location_function_instrumentation_type |
9d3981b5 JG |
134 | lttng_userspace_probe_location_function_get_instrumentation_type( |
135 | const struct lttng_userspace_probe_location *location); | |
136 | ||
137 | /* | |
138 | * Get the instrumentation type of the function probe location. | |
139 | * Defaults to | |
140 | * LTTNG_USERSPACE_PROBE_LOCATION_FUNCTION_INSTRUMENTATION_TYPE_ENTRY. | |
141 | * | |
142 | * Returns LTTNG_USERSPACE_PROBE_LOCATION_STATUS_OK on success, | |
143 | * LTTNG_USERSPACE_PROBE_LOCATION_STATUS_INVALID if invalid parameters | |
144 | * are provided. | |
145 | */ | |
4bd69c5f | 146 | LTTNG_EXPORT extern enum lttng_userspace_probe_location_status |
9d3981b5 JG |
147 | lttng_userspace_probe_location_function_set_instrumentation_type( |
148 | const struct lttng_userspace_probe_location *location, | |
149 | enum lttng_userspace_probe_location_function_instrumentation_type instrumentation_type); | |
150 | ||
1ce46cfe JG |
151 | /* |
152 | * Get the lookup method of the given userspace probe location. | |
153 | * Returns NULL if the probe location type is unsupported. | |
154 | * | |
155 | * The ownership of the lookup method is NOT transferred to the caller. | |
156 | */ | |
4bd69c5f | 157 | LTTNG_EXPORT extern const struct lttng_userspace_probe_location_lookup_method * |
1ce46cfe JG |
158 | lttng_userspace_probe_location_get_lookup_method( |
159 | const struct lttng_userspace_probe_location *location); | |
160 | ||
f4d0bb2e FD |
161 | /* |
162 | * Create a probe location of the tracepoint type. | |
163 | * Receives the target binary file path, probename and probe provider to | |
164 | * instrument. | |
165 | * On failure, NULL is returned. | |
166 | * | |
167 | * The ownership of the lookup method is transferred to the created probe | |
168 | * location. | |
169 | */ | |
4bd69c5f | 170 | LTTNG_EXPORT extern struct lttng_userspace_probe_location * |
f4d0bb2e FD |
171 | lttng_userspace_probe_location_tracepoint_create(const char *binary_path, |
172 | const char *probe_name, const char *provider_name, | |
173 | struct lttng_userspace_probe_location_lookup_method *lookup_method); | |
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( |
f4d0bb2e FD |
179 | const struct lttng_userspace_probe_location *location); |
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( |
f4d0bb2e FD |
185 | const struct lttng_userspace_probe_location *location); |
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( |
f4d0bb2e FD |
192 | const struct lttng_userspace_probe_location *location); |
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( |
f4d0bb2e FD |
199 | const struct lttng_userspace_probe_location *location); |
200 | ||
1ce46cfe JG |
201 | #ifdef __cplusplus |
202 | } | |
203 | #endif | |
204 | ||
205 | #endif /* LTTNG_USERSPACE_PROBE_H */ |