2 * Copyright (C) 2017 Jérémie Galarneau <jeremie.galarneau@efficios.com>
4 * SPDX-License-Identifier: LGPL-2.1-only
8 #ifndef LTTNG_USERSPACE_PROBE_H
9 #define LTTNG_USERSPACE_PROBE_H
16 * Userspace probe lookup methods specifies how the userspace probe location
17 * specified by the user should be interpreted.
19 struct lttng_userspace_probe_location_lookup_method
;
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,
29 * Get the type of a lookup method.
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
);
36 * Destroy a lookup method.
38 extern void lttng_userspace_probe_location_lookup_method_destroy(
39 struct lttng_userspace_probe_location_lookup_method
*lookup_method
);
42 * Create a tracepoint ELF function lookup method struct.
43 * Return NULL on failure.
45 extern struct lttng_userspace_probe_location_lookup_method
*
46 lttng_userspace_probe_location_lookup_method_function_elf_create(void);
49 * Create a tracepoint SDT tracepoint lookup method struct.
50 * Return NULL on failure.
52 extern struct lttng_userspace_probe_location_lookup_method
*
53 lttng_userspace_probe_location_lookup_method_tracepoint_sdt_create(void);
57 * Contains all the information needed to compute the instrumentation point in
58 * the binary. It is used in conjonction with a lookup method.
60 struct lttng_userspace_probe_location
;
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,
68 enum lttng_userspace_probe_location_type
{
69 LTTNG_USERSPACE_PROBE_LOCATION_TYPE_UNKNOWN
= -1,
71 LTTNG_USERSPACE_PROBE_LOCATION_TYPE_FUNCTION
= 0,
72 /* SDT probe's callsites. */
73 LTTNG_USERSPACE_PROBE_LOCATION_TYPE_TRACEPOINT
= 1,
77 * Get the type of the userspace probe location.
79 extern enum lttng_userspace_probe_location_type
80 lttng_userspace_probe_location_get_type(
81 const struct lttng_userspace_probe_location
*location
);
84 * Destroy the userspace probe location.
86 extern void lttng_userspace_probe_location_destroy(
87 struct lttng_userspace_probe_location
*location
);
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,
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.
101 * The ownership of the lookup method is transferred to the created probe
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
);
110 * Get the target binary path of the probe location of the function type.
112 extern const char *lttng_userspace_probe_location_function_get_binary_path(
113 const struct lttng_userspace_probe_location
*location
);
116 * Get the target function type of the probe location of the function type.
118 extern const char *lttng_userspace_probe_location_function_get_function_name(
119 const struct lttng_userspace_probe_location
*location
);
122 * Get the FD to the target binary file to the probe location of the function
125 extern int lttng_userspace_probe_location_function_get_binary_fd(
126 const struct lttng_userspace_probe_location
*location
);
129 * Get the instrumentation type of the function probe location.
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
);
136 * Get the instrumentation type of the function probe location.
138 * LTTNG_USERSPACE_PROBE_LOCATION_FUNCTION_INSTRUMENTATION_TYPE_ENTRY.
140 * Returns LTTNG_USERSPACE_PROBE_LOCATION_STATUS_OK on success,
141 * LTTNG_USERSPACE_PROBE_LOCATION_STATUS_INVALID if invalid parameters
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
);
150 * Get the lookup method of the given userspace probe location.
151 * Returns NULL if the probe location type is unsupported.
153 * The ownership of the lookup method is NOT transferred to the caller.
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
);
160 * Create a probe location of the tracepoint type.
161 * Receives the target binary file path, probename and probe provider to
163 * On failure, NULL is returned.
165 * The ownership of the lookup method is transferred to the created probe
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
);
174 * Get the target binary path of the probe location of the tracepoint type.
176 extern const char *lttng_userspace_probe_location_tracepoint_get_binary_path(
177 const struct lttng_userspace_probe_location
*location
);
180 * Get the target probe name of the probe location of the tracepoint type.
182 extern const char *lttng_userspace_probe_location_tracepoint_get_probe_name(
183 const struct lttng_userspace_probe_location
*location
);
186 * Get the target probe provider name of the probe location of the tracepoint
189 extern const char *lttng_userspace_probe_location_tracepoint_get_provider_name(
190 const struct lttng_userspace_probe_location
*location
);
193 * Get the FD to the target binary file to the probe location of the tracepoint
196 extern int lttng_userspace_probe_location_tracepoint_get_binary_fd(
197 const struct lttng_userspace_probe_location
*location
);
203 #endif /* LTTNG_USERSPACE_PROBE_H */