Introduce kernel-probe locations
[lttng-tools.git] / include / lttng / userspace-probe.h
CommitLineData
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
11#ifdef __cplusplus
12extern "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 */
19struct lttng_userspace_probe_location_lookup_method;
20
21enum 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,
f4d0bb2e 25 LTTNG_USERSPACE_PROBE_LOCATION_LOOKUP_METHOD_TYPE_TRACEPOINT_SDT = 2,
1ce46cfe
JG
26};
27
28/*
29 * Get the type of a lookup method.
30 */
31extern enum lttng_userspace_probe_location_lookup_method_type
32lttng_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 */
38extern 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 */
45extern struct lttng_userspace_probe_location_lookup_method *
46lttng_userspace_probe_location_lookup_method_function_elf_create(void);
47
f4d0bb2e
FD
48/*
49 * Create a tracepoint SDT tracepoint lookup method struct.
50 * Return NULL on failure.
51 */
52extern struct lttng_userspace_probe_location_lookup_method *
53lttng_userspace_probe_location_lookup_method_tracepoint_sdt_create(void);
54
1ce46cfe
JG
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 */
60struct lttng_userspace_probe_location;
61
9d3981b5
JG
62enum 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
1ce46cfe
JG
68enum lttng_userspace_probe_location_type {
69 LTTNG_USERSPACE_PROBE_LOCATION_TYPE_UNKNOWN = -1,
9d3981b5 70 /* Function. */
1ce46cfe 71 LTTNG_USERSPACE_PROBE_LOCATION_TYPE_FUNCTION = 0,
bff8d217 72 /* SDT probe's callsites. */
f4d0bb2e 73 LTTNG_USERSPACE_PROBE_LOCATION_TYPE_TRACEPOINT = 1,
1ce46cfe
JG
74};
75
76/*
77 * Get the type of the userspace probe location.
78 */
79extern enum lttng_userspace_probe_location_type
80lttng_userspace_probe_location_get_type(
81 const struct lttng_userspace_probe_location *location);
82
83/*
84 * Destroy the userspace probe location.
85 */
86extern void lttng_userspace_probe_location_destroy(
87 struct lttng_userspace_probe_location *location);
88
9d3981b5
JG
89
90enum 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
1ce46cfe
JG
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 */
104extern struct lttng_userspace_probe_location *
105lttng_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 */
112extern 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 */
118extern const char *lttng_userspace_probe_location_function_get_function_name(
119 const struct lttng_userspace_probe_location *location);
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
FD
124 */
125extern int lttng_userspace_probe_location_function_get_binary_fd(
126 const struct lttng_userspace_probe_location *location);
127
9d3981b5
JG
128/*
129 * Get the instrumentation type of the function probe location.
130 */
131extern enum lttng_userspace_probe_location_function_instrumentation_type
132lttng_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 */
144extern enum lttng_userspace_probe_location_status
145lttng_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
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 */
87597c2c 155extern const struct lttng_userspace_probe_location_lookup_method *
1ce46cfe
JG
156lttng_userspace_probe_location_get_lookup_method(
157 const struct lttng_userspace_probe_location *location);
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 */
168extern struct lttng_userspace_probe_location *
169lttng_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 */
176extern 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 */
182extern 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 */
189extern 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
fe489250 194 * type. The FD is only valid for the duration of the lifetime of `location`.
f4d0bb2e
FD
195 */
196extern int lttng_userspace_probe_location_tracepoint_get_binary_fd(
197 const struct lttng_userspace_probe_location *location);
198
1ce46cfe
JG
199#ifdef __cplusplus
200}
201#endif
202
203#endif /* LTTNG_USERSPACE_PROBE_H */
This page took 0.035834 seconds and 4 git commands to generate.