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 };
  36
  37 /*
  38  * Get the type of a lookup method.
  39  */
  40 extern enum lttng_userspace_probe_location_lookup_method_type
  41 lttng_userspace_probe_location_lookup_method_get_type(
  42                 const struct lttng_userspace_probe_location_lookup_method *lookup_method);
  43
  44 /*
  45  * Destroy a lookup method.
  46  */
  47 extern void lttng_userspace_probe_location_lookup_method_destroy(
  48                 struct lttng_userspace_probe_location_lookup_method *lookup_method);
  49
  50 /*
  51  * Create a tracepoint ELF function lookup method struct.
  52  * Return NULL on failure.
  53  */
  54 extern struct lttng_userspace_probe_location_lookup_method *
  55 lttng_userspace_probe_location_lookup_method_function_elf_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_type {
  65         LTTNG_USERSPACE_PROBE_LOCATION_TYPE_UNKNOWN     = -1,
  66         LTTNG_USERSPACE_PROBE_LOCATION_TYPE_FUNCTION    = 0,
  67 };
  68
  69 /*
  70  * Get the type of the userspace probe location.
  71  */
  72 extern enum lttng_userspace_probe_location_type
  73 lttng_userspace_probe_location_get_type(
  74                 const struct lttng_userspace_probe_location *location);
  75
  76 /*
  77  * Destroy the userspace probe location.
  78  */
  79 extern void lttng_userspace_probe_location_destroy(
  80                 struct lttng_userspace_probe_location *location);
  81
  82 /*
  83  * Create a probe location of the function type.
  84  * Receives the target binary file path and function to instrument.
  85  * On failure, NULL is returned.
  86  *
  87  * The ownership of the lookup method is transferred to the created probe
  88  * location.
  89  */
  90 extern struct lttng_userspace_probe_location *
  91 lttng_userspace_probe_location_function_create(const char *binary_path,
  92                 const char *function_name,
  93                 struct lttng_userspace_probe_location_lookup_method *lookup_method);
  94
  95 /*
  96  * Get the target binary path of the probe location of the function type.
  97  */
  98 extern const char *lttng_userspace_probe_location_function_get_binary_path(
  99                 const struct lttng_userspace_probe_location *location);
 100
 101 /*
 102  * Get the target function type of the probe location of the function type.
 103  */
 104 extern const char *lttng_userspace_probe_location_function_get_function_name(
 105                 const struct lttng_userspace_probe_location *location);
 106
 107 /*
 108  * Get the FD to the target binary file to the probe location of the function
 109  * type.
 110  */
 111 extern int lttng_userspace_probe_location_function_get_binary_fd(
 112                 const struct lttng_userspace_probe_location *location);
 113
 114 /*
 115  * Get the lookup method of the given userspace probe location.
 116  * Returns NULL if the probe location type is unsupported.
 117  *
 118  * The ownership of the lookup method is NOT transferred to the caller.
 119  */
 120 extern struct lttng_userspace_probe_location_lookup_method *
 121 lttng_userspace_probe_location_get_lookup_method(
 122                 const struct lttng_userspace_probe_location *location);
 123
 124 #ifdef __cplusplus
 125 }
 126 #endif
 127
 128 #endif /* LTTNG_USERSPACE_PROBE_H */