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