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 #include <lttng/lttng-export.h>
  12
  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,
  27         LTTNG_USERSPACE_PROBE_LOCATION_LOOKUP_METHOD_TYPE_TRACEPOINT_SDT    = 2,
  28 };
  29
  30 /*
  31  * Get the type of a lookup method.
  32  */
  33 LTTNG_EXPORT extern enum lttng_userspace_probe_location_lookup_method_type
  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  */
  40 LTTNG_EXPORT extern void lttng_userspace_probe_location_lookup_method_destroy(
  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  */
  47 LTTNG_EXPORT extern struct lttng_userspace_probe_location_lookup_method *
  48 lttng_userspace_probe_location_lookup_method_function_elf_create(void);
  49
  50 /*
  51  * Create a tracepoint SDT tracepoint lookup method struct.
  52  * Return NULL on failure.
  53  */
  54 LTTNG_EXPORT extern struct lttng_userspace_probe_location_lookup_method *
  55 lttng_userspace_probe_location_lookup_method_tracepoint_sdt_create(void);
  56
  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
  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
  70 enum lttng_userspace_probe_location_type {
  71         LTTNG_USERSPACE_PROBE_LOCATION_TYPE_UNKNOWN     = -1,
  72         /* Function. */
  73         LTTNG_USERSPACE_PROBE_LOCATION_TYPE_FUNCTION    = 0,
  74         /* SDT probe's callsites. */
  75         LTTNG_USERSPACE_PROBE_LOCATION_TYPE_TRACEPOINT  = 1,
  76 };
  77
  78 /*
  79  * Get the type of the userspace probe location.
  80  */
  81 LTTNG_EXPORT extern enum lttng_userspace_probe_location_type
  82 lttng_userspace_probe_location_get_type(
  83                 const struct lttng_userspace_probe_location *location);
  84
  85 /*
  86  * Destroy the userspace probe location.
  87  */
  88 LTTNG_EXPORT extern void lttng_userspace_probe_location_destroy(
  89                 struct lttng_userspace_probe_location *location);
  90
  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
  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  */
 106 LTTNG_EXPORT extern struct lttng_userspace_probe_location *
 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  */
 114 LTTNG_EXPORT extern const char *lttng_userspace_probe_location_function_get_binary_path(
 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  */
 120 LTTNG_EXPORT extern const char *lttng_userspace_probe_location_function_get_function_name(
 121                 const struct lttng_userspace_probe_location *location);
 122
 123 /*
 124  * Get the FD to the target binary file to the probe location of the function
 125  * type. The FD is only valid for the duration of the lifetime of `location`.
 126  */
 127 LTTNG_EXPORT extern int lttng_userspace_probe_location_function_get_binary_fd(
 128                 const struct lttng_userspace_probe_location *location);
 129
 130 /*
 131  * Get the instrumentation type of the function probe location.
 132  */
 133 LTTNG_EXPORT extern enum lttng_userspace_probe_location_function_instrumentation_type
 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  */
 146 LTTNG_EXPORT extern enum lttng_userspace_probe_location_status
 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
 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  */
 157 LTTNG_EXPORT extern const struct lttng_userspace_probe_location_lookup_method *
 158 lttng_userspace_probe_location_get_lookup_method(
 159                 const struct lttng_userspace_probe_location *location);
 160
 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  */
 170 LTTNG_EXPORT extern struct lttng_userspace_probe_location *
 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  */
 178 LTTNG_EXPORT extern const char *lttng_userspace_probe_location_tracepoint_get_binary_path(
 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  */
 184 LTTNG_EXPORT extern const char *lttng_userspace_probe_location_tracepoint_get_probe_name(
 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  */
 191 LTTNG_EXPORT extern const char *lttng_userspace_probe_location_tracepoint_get_provider_name(
 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
 196  * type. The FD is only valid for the duration of the lifetime of `location`.
 197  */
 198 LTTNG_EXPORT extern int lttng_userspace_probe_location_tracepoint_get_binary_fd(
 199                 const struct lttng_userspace_probe_location *location);
 200
 201 #ifdef __cplusplus
 202 }
 203 #endif
 204
 205 #endif /* LTTNG_USERSPACE_PROBE_H */