include/lttng/userspace-probe.h

   1 /*
   2  * Copyright (C) 2017 - Jérémie Galarneau <jeremie.galarneau@efficios.com>
   3  *
   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.
   7  *
   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
  11  * for more details.
  12  *
  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
  16  */
  17
  18 #ifndef LTTNG_USERSPACE_PROBE_H
  19 #define LTTNG_USERSPACE_PROBE_H
  20
  21 #ifdef __cplusplus
  22 extern "C" {
  23 #endif
  24
  25 /*
  26  * Userspace probe lookup methods specifies how the userspace probe location
  27  * specified by the user should be interpreted.
  28  */
  29 struct lttng_userspace_probe_location_lookup_method;
  30
  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,
  36 };
  37
  38 /*
  39  * Get the type of a lookup method.
  40  */
  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);
  44
  45 /*
  46  * Destroy a lookup method.
  47  */
  48 extern void lttng_userspace_probe_location_lookup_method_destroy(
  49                 struct lttng_userspace_probe_location_lookup_method *lookup_method);
  50
  51 /*
  52  * Create a tracepoint ELF function lookup method struct.
  53  * Return NULL on failure.
  54  */
  55 extern struct lttng_userspace_probe_location_lookup_method *
  56 lttng_userspace_probe_location_lookup_method_function_elf_create(void);
  57
  58 /*
  59  * Create a tracepoint SDT tracepoint lookup method struct.
  60  * Return NULL on failure.
  61  */
  62 extern struct lttng_userspace_probe_location_lookup_method *
  63 lttng_userspace_probe_location_lookup_method_tracepoint_sdt_create(void);
  64
  65
  66 /*
  67  * Contains all the information needed to compute the instrumentation point in
  68  * the binary. It is used in conjonction with a lookup method.
  69  */
  70 struct lttng_userspace_probe_location;
  71
  72 enum lttng_userspace_probe_location_status {
  73         LTTNG_USERSPACE_PROBE_LOCATION_STATUS_OK        = 0,
  74         /* Invalid parameters provided. */
  75         LTTNG_USERSPACE_PROBE_LOCATION_STATUS_INVALID   = -1,
  76 };
  77
  78 enum lttng_userspace_probe_location_type {
  79         LTTNG_USERSPACE_PROBE_LOCATION_TYPE_UNKNOWN     = -1,
  80         /* Function. */
  81         LTTNG_USERSPACE_PROBE_LOCATION_TYPE_FUNCTION    = 0,
  82         /* SDT probe's callsites. */
  83         LTTNG_USERSPACE_PROBE_LOCATION_TYPE_TRACEPOINT  = 1,
  84 };
  85
  86 /*
  87  * Get the type of the userspace probe location.
  88  */
  89 extern enum lttng_userspace_probe_location_type
  90 lttng_userspace_probe_location_get_type(
  91                 const struct lttng_userspace_probe_location *location);
  92
  93 /*
  94  * Destroy the userspace probe location.
  95  */
  96 extern void lttng_userspace_probe_location_destroy(
  97                 struct lttng_userspace_probe_location *location);
  98
  99
 100 enum lttng_userspace_probe_location_function_instrumentation_type {
 101         LTTNG_USERSPACE_PROBE_LOCATION_FUNCTION_INSTRUMENTATION_TYPE_UNKNOWN = -1,
 102         /* Only instrument the function's entry. */
 103         LTTNG_USERSPACE_PROBE_LOCATION_FUNCTION_INSTRUMENTATION_TYPE_ENTRY = 0,
 104 };
 105
 106 /*
 107  * Create a probe location of the function type.
 108  * Receives the target binary file path and function to instrument.
 109  * On failure, NULL is returned.
 110  *
 111  * The ownership of the lookup method is transferred to the created probe
 112  * location.
 113  */
 114 extern struct lttng_userspace_probe_location *
 115 lttng_userspace_probe_location_function_create(const char *binary_path,
 116                 const char *function_name,
 117                 struct lttng_userspace_probe_location_lookup_method *lookup_method);
 118
 119 /*
 120  * Get the target binary path of the probe location of the function type.
 121  */
 122 extern const char *lttng_userspace_probe_location_function_get_binary_path(
 123                 const struct lttng_userspace_probe_location *location);
 124
 125 /*
 126  * Get the target function type of the probe location of the function type.
 127  */
 128 extern const char *lttng_userspace_probe_location_function_get_function_name(
 129                 const struct lttng_userspace_probe_location *location);
 130
 131 /*
 132  * Get the FD to the target binary file to the probe location of the function
 133  * type.
 134  */
 135 extern int lttng_userspace_probe_location_function_get_binary_fd(
 136                 const struct lttng_userspace_probe_location *location);
 137
 138 /*
 139  * Get the instrumentation type of the function probe location.
 140  */
 141 extern enum lttng_userspace_probe_location_function_instrumentation_type
 142 lttng_userspace_probe_location_function_get_instrumentation_type(
 143                 const struct lttng_userspace_probe_location *location);
 144
 145 /*
 146  * Get the instrumentation type of the function probe location.
 147  * Defaults to
 148  * LTTNG_USERSPACE_PROBE_LOCATION_FUNCTION_INSTRUMENTATION_TYPE_ENTRY.
 149  *
 150  * Returns LTTNG_USERSPACE_PROBE_LOCATION_STATUS_OK on success,
 151  * LTTNG_USERSPACE_PROBE_LOCATION_STATUS_INVALID if invalid parameters
 152  * are provided.
 153  */
 154 extern enum lttng_userspace_probe_location_status
 155 lttng_userspace_probe_location_function_set_instrumentation_type(
 156                 const struct lttng_userspace_probe_location *location,
 157                 enum lttng_userspace_probe_location_function_instrumentation_type instrumentation_type);
 158
 159 /*
 160  * Get the lookup method of the given userspace probe location.
 161  * Returns NULL if the probe location type is unsupported.
 162  *
 163  * The ownership of the lookup method is NOT transferred to the caller.
 164  */
 165 extern const struct lttng_userspace_probe_location_lookup_method *
 166 lttng_userspace_probe_location_get_lookup_method(
 167                 const struct lttng_userspace_probe_location *location);
 168
 169 /*
 170  * Create a probe location of the tracepoint type.
 171  * Receives the target binary file path, probename and probe provider to
 172  * instrument.
 173  * On failure, NULL is returned.
 174  *
 175  * The ownership of the lookup method is transferred to the created probe
 176  * location.
 177  */
 178 extern struct lttng_userspace_probe_location *
 179 lttng_userspace_probe_location_tracepoint_create(const char *binary_path,
 180                 const char *probe_name, const char *provider_name,
 181                 struct lttng_userspace_probe_location_lookup_method *lookup_method);
 182
 183 /*
 184  * Get the target binary path of the probe location of the tracepoint type.
 185  */
 186 extern const char *lttng_userspace_probe_location_tracepoint_get_binary_path(
 187                 const struct lttng_userspace_probe_location *location);
 188
 189 /*
 190  * Get the target probe name of the probe location of the tracepoint type.
 191  */
 192 extern const char *lttng_userspace_probe_location_tracepoint_get_probe_name(
 193                 const struct lttng_userspace_probe_location *location);
 194
 195 /*
 196  * Get the target probe provider name of the probe location of the tracepoint
 197  * type.
 198  */
 199 extern const char *lttng_userspace_probe_location_tracepoint_get_provider_name(
 200                 const struct lttng_userspace_probe_location *location);
 201
 202 /*
 203  * Get the FD to the target binary file to the probe location of the tracepoint
 204  * type.
 205  */
 206 extern int lttng_userspace_probe_location_tracepoint_get_binary_fd(
 207                 const struct lttng_userspace_probe_location *location);
 208
 209 #ifdef __cplusplus
 210 }
 211 #endif
 212
 213 #endif /* LTTNG_USERSPACE_PROBE_H */