2 * Copyright (C) 2017 - Jérémie Galarneau <jeremie.galarneau@efficios.com>
4 * This library is free software; you can redistribute it and/or modify it
5 * under the terms of the GNU Lesser General Public License, version 2.1 only,
6 * as published by the Free Software Foundation.
8 * This library is distributed in the hope that it will be useful, but WITHOUT
9 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
10 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License
13 * You should have received a copy of the GNU Lesser General Public License
14 * along with this library; if not, write to the Free Software Foundation,
15 * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
18 #ifndef LTTNG_USERSPACE_PROBE_H
19 #define LTTNG_USERSPACE_PROBE_H
26 * Userspace probe lookup methods specifies how the userspace probe location
27 * specified by the user should be interpreted.
29 struct lttng_userspace_probe_location_lookup_method
;
31 enum lttng_userspace_probe_location_lookup_method_type
{
32 LTTNG_USERSPACE_PROBE_LOCATION_LOOKUP_METHOD_TYPE_UNKNOWN
= -1,
33 LTTNG_USERSPACE_PROBE_LOCATION_LOOKUP_METHOD_TYPE_FUNCTION_DEFAULT
= 0,
34 LTTNG_USERSPACE_PROBE_LOCATION_LOOKUP_METHOD_TYPE_FUNCTION_ELF
= 1,
35 LTTNG_USERSPACE_PROBE_LOCATION_LOOKUP_METHOD_TYPE_TRACEPOINT_SDT
= 2,
39 * Get the type of a lookup method.
41 extern enum lttng_userspace_probe_location_lookup_method_type
42 lttng_userspace_probe_location_lookup_method_get_type(
43 const struct lttng_userspace_probe_location_lookup_method
*lookup_method
);
46 * Destroy a lookup method.
48 extern void lttng_userspace_probe_location_lookup_method_destroy(
49 struct lttng_userspace_probe_location_lookup_method
*lookup_method
);
52 * Create a tracepoint ELF function lookup method struct.
53 * Return NULL on failure.
55 extern struct lttng_userspace_probe_location_lookup_method
*
56 lttng_userspace_probe_location_lookup_method_function_elf_create(void);
59 * Create a tracepoint SDT tracepoint lookup method struct.
60 * Return NULL on failure.
62 extern struct lttng_userspace_probe_location_lookup_method
*
63 lttng_userspace_probe_location_lookup_method_tracepoint_sdt_create(void);
67 * Contains all the information needed to compute the instrumentation point in
68 * the binary. It is used in conjonction with a lookup method.
70 struct lttng_userspace_probe_location
;
72 enum lttng_userspace_probe_location_type
{
73 LTTNG_USERSPACE_PROBE_LOCATION_TYPE_UNKNOWN
= -1,
74 /* Traces a function's entry and exit. */
75 LTTNG_USERSPACE_PROBE_LOCATION_TYPE_FUNCTION
= 0,
76 /* Trace a single point. */
77 LTTNG_USERSPACE_PROBE_LOCATION_TYPE_TRACEPOINT
= 1,
81 * Get the type of the userspace probe location.
83 extern enum lttng_userspace_probe_location_type
84 lttng_userspace_probe_location_get_type(
85 const struct lttng_userspace_probe_location
*location
);
88 * Destroy the userspace probe location.
90 extern void lttng_userspace_probe_location_destroy(
91 struct lttng_userspace_probe_location
*location
);
94 * Create a probe location of the function type.
95 * Receives the target binary file path and function to instrument.
96 * On failure, NULL is returned.
98 * The ownership of the lookup method is transferred to the created probe
101 extern struct lttng_userspace_probe_location
*
102 lttng_userspace_probe_location_function_create(const char *binary_path
,
103 const char *function_name
,
104 struct lttng_userspace_probe_location_lookup_method
*lookup_method
);
107 * Get the target binary path of the probe location of the function type.
109 extern const char *lttng_userspace_probe_location_function_get_binary_path(
110 const struct lttng_userspace_probe_location
*location
);
113 * Get the target function type of the probe location of the function type.
115 extern const char *lttng_userspace_probe_location_function_get_function_name(
116 const struct lttng_userspace_probe_location
*location
);
119 * Get the FD to the target binary file to the probe location of the function
122 extern int lttng_userspace_probe_location_function_get_binary_fd(
123 const struct lttng_userspace_probe_location
*location
);
126 * Get the lookup method of the given userspace probe location.
127 * Returns NULL if the probe location type is unsupported.
129 * The ownership of the lookup method is NOT transferred to the caller.
131 extern const struct lttng_userspace_probe_location_lookup_method
*
132 lttng_userspace_probe_location_get_lookup_method(
133 const struct lttng_userspace_probe_location
*location
);
136 * Create a probe location of the tracepoint type.
137 * Receives the target binary file path, probename and probe provider to
139 * On failure, NULL is returned.
141 * The ownership of the lookup method is transferred to the created probe
144 extern struct lttng_userspace_probe_location
*
145 lttng_userspace_probe_location_tracepoint_create(const char *binary_path
,
146 const char *probe_name
, const char *provider_name
,
147 struct lttng_userspace_probe_location_lookup_method
*lookup_method
);
150 * Get the target binary path of the probe location of the tracepoint type.
152 extern const char *lttng_userspace_probe_location_tracepoint_get_binary_path(
153 const struct lttng_userspace_probe_location
*location
);
156 * Get the target probe name of the probe location of the tracepoint type.
158 extern const char *lttng_userspace_probe_location_tracepoint_get_probe_name(
159 const struct lttng_userspace_probe_location
*location
);
162 * Get the target probe provider name of the probe location of the tracepoint
165 extern const char *lttng_userspace_probe_location_tracepoint_get_provider_name(
166 const struct lttng_userspace_probe_location
*location
);
169 * Get the FD to the target binary file to the probe location of the tracepoint
172 extern int lttng_userspace_probe_location_tracepoint_get_binary_fd(
173 const struct lttng_userspace_probe_location
*location
);
179 #endif /* LTTNG_USERSPACE_PROBE_H */