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. The FD is only valid for the duration of the lifetime of `location`.
 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. The FD is only valid for the duration of the lifetime of `location`.
 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 */