include/lttng/marker.h

   1 #ifndef _UST_MARKER_H
   2 #define _UST_MARKER_H
   3
   4 /*
   5  * Code markup for dynamic and static tracing.
   6  *
   7  * See Documentation/marker.txt.
   8  *
   9  * (C) Copyright 2006 Mathieu Desnoyers <mathieu.desnoyers@polymtl.ca>
  10  * (C) Copyright 2009 Pierre-Marc Fournier <pierre-marc dot fournier at polymtl dot ca>
  11  * (C) Copyright 2011 Mathieu Desnoyers <mathieu.desnoyers@efficios.com>
  12  *
  13  * This library is free software; you can redistribute it and/or
  14  * modify it under the terms of the GNU Lesser General Public
  15  * License as published by the Free Software Foundation;
  16  * version 2.1 of the License.
  17  *
  18  * This library is distributed in the hope that it will be useful,
  19  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  20  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  21  * Lesser General Public License for more details.
  22  *
  23  * You should have received a copy of the GNU Lesser General Public
  24  * License along with this library; if not, write to the Free Software
  25  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301 USA
  26  */
  27
  28 #include <stdarg.h>
  29 #include <stdint.h>
  30 #include <stddef.h>
  31 #include <bits/wordsize.h>
  32 #include <urcu/list.h>
  33
  34 #ifdef __cplusplus
  35 extern "C" {
  36 #endif
  37
  38 struct ust_marker;
  39 struct ust_marker_probe_array;
  40
  41 /**
  42  * ust_marker_probe_func - Type of a marker probe function
  43  * @mdata: marker data
  44  * @probe_private: probe private data
  45  * @call_private: call site private data
  46  * @fmt: format string
  47  * @args: variable argument list pointer. Use a pointer to overcome C's
  48  *        inability to pass this around as a pointer in a portable manner in
  49  *        the callee otherwise.
  50  *
  51  * Type of marker probe functions. They receive the mdata and need to parse the
  52  * format string to recover the variable argument list.
  53  */
  54 typedef void ust_marker_probe_func(const struct ust_marker *mdata,
  55                 void *probe_private, void *call_private,
  56                 const char *fmt, va_list *args);
  57
  58 struct ust_marker_probe_closure {
  59         ust_marker_probe_func *func;    /* Callback */
  60         void *probe_private;            /* Private probe data */
  61 };
  62
  63 struct ust_marker {
  64         const char *channel;    /* Name of channel where to send data */
  65         const char *name;       /* Marker name */
  66         const char *format;     /* Marker format string, describing the
  67                                  * variable argument list.
  68                                  */
  69         char state;             /* State. */
  70         char ptype;             /* probe type : 0 : single, 1 : multi */
  71                                 /* Probe wrapper */
  72         uint16_t channel_id;    /* Numeric channel identifier, dynamic */
  73         uint16_t event_id;      /* Numeric event identifier, dynamic */
  74         void (*call)(const struct ust_marker *mdata, void *call_private, ...);
  75         struct ust_marker_probe_closure single;
  76         struct ust_marker_probe_array *multi;
  77         const char *tp_name;    /* Optional tracepoint name */
  78         void *tp_cb;            /* Optional tracepoint callback */
  79 };
  80
  81 /*
  82  * We keep the "channel" as internal field for marker.c *only*. It will be
  83  * removed soon.
  84  */
  85
  86 /*
  87  * __ust_marker_ptrs section is not const (read-only) because it needs to be
  88  * read-write to let the linker apply relocations and keep the object PIC.
  89  */
  90 #define _DEFINE_UST_MARKER(channel, name, tp_name_str, tp_cb, format)   \
  91                 static const char __mstrtab_##channel##_##name[]        \
  92                 __attribute__((section("__ust_markers_strings")))       \
  93                 = #channel "\0" #name "\0" format;                      \
  94                 static struct ust_marker __ust_marker_def_##name        \
  95                 __attribute__((section("__ust_markers"))) =             \
  96                 { __mstrtab_##channel##_##name,                         \
  97                   &__mstrtab_##channel##_##name[sizeof(#channel)],      \
  98                   &__mstrtab_##channel##_##name[sizeof(#channel) +      \
  99                                                 sizeof(#name)],         \
 100                   0, 0, 0, 0, ust_marker_probe_cb,                      \
 101                   { __ust_marker_empty_function, NULL},                 \
 102                   NULL, tp_name_str, tp_cb };                           \
 103                 static struct ust_marker * __ust_marker_ptr_##name      \
 104                         __attribute__((used, section("__ust_marker_ptrs"))) = \
 105                         &__ust_marker_def_##name
 106
 107 /*
 108  * Make sure the alignment of the structure in the __ust_marker section will
 109  * not add unwanted padding between the beginning of the section and the
 110  * structure. Force alignment to the same alignment as the section start.
 111  */
 112
 113 #define __ust_marker(channel, name, call_private, format, args...)      \
 114         do {                                                            \
 115                 _DEFINE_UST_MARKER(channel, name, NULL, NULL, format);  \
 116                 __ust_marker_check_format(format, ## args);             \
 117                 if (__builtin_expect(!!(__ust_marker_def_##name.state), 0)) \
 118                         (__ust_marker_def_##name.call)                  \
 119                                 (&__ust_marker_def_##name, call_private,\
 120                                 ## args);                               \
 121         } while (0)
 122
 123 /**
 124  * ust_marker - Marker using code patching
 125  * @name: marker name, not quoted.
 126  * @format: format string
 127  * @args...: variable argument list
 128  *
 129  * Places a marker at caller site.
 130  */
 131 #define ust_marker(name, format, args...) \
 132         __ust_marker(ust, name, NULL, format, ## args)
 133
 134 static inline __attribute__((deprecated))
 135 void __trace_mark_is_deprecated()
 136 {
 137 }
 138
 139 /**
 140  * UST_MARKER_NOARGS - Format string for a marker with no argument.
 141  */
 142 #define UST_MARKER_NOARGS " "
 143
 144 /* To be used for string format validity checking with gcc */
 145 static inline
 146 void __attribute__((format(printf, 1, 2)))
 147  ___ust_marker_check_format(const char *fmt, ...)
 148 {
 149 }
 150
 151 #define __ust_marker_check_format(format, args...)                      \
 152         do {                                                            \
 153                 if (0)                                                  \
 154                         ___ust_marker_check_format(format, ## args);    \
 155         } while (0)
 156
 157 extern ust_marker_probe_func __ust_marker_empty_function;
 158
 159 extern void ust_marker_probe_cb(const struct ust_marker *mdata,
 160         void *call_private, ...);
 161
 162 struct ust_marker_lib {
 163         struct ust_marker * const *ust_marker_start;
 164         int ust_marker_count;
 165         struct cds_list_head list;
 166 };
 167
 168 #define UST_MARKER_LIB                                                  \
 169         extern struct ust_marker * const __start___ust_marker_ptrs[] __attribute__((weak, visibility("hidden"))); \
 170         extern struct ust_marker * const __stop___ust_marker_ptrs[] __attribute__((weak, visibility("hidden"))); \
 171         static struct ust_marker * __ust_marker_ptr_dummy               \
 172                 __attribute__((used, section("__ust_marker_ptrs")));    \
 173                                                                         \
 174         static void __attribute__((constructor)) __ust_marker__init(void) \
 175         {                                                               \
 176                 ust_marker_register_lib(__start___ust_marker_ptrs,      \
 177                                     __stop___ust_marker_ptrs            \
 178                                     - __start___ust_marker_ptrs);       \
 179         }                                                               \
 180                                                                         \
 181         static void __attribute__((destructor)) __ust_marker__destroy(void) \
 182         {                                                               \
 183                 ust_marker_unregister_lib(__start___ust_marker_ptrs);   \
 184         }
 185
 186 extern
 187 int ust_marker_register_lib(struct ust_marker * const *ust_marker_start,
 188                             int ust_marker_count);
 189 extern
 190 int ust_marker_unregister_lib(struct ust_marker * const *ust_marker_start);
 191
 192 /*
 193  * trace_mark() -- DEPRECATED
 194  * @channel: name prefix, not quoted. Ignored.
 195  * @name: marker name, not quoted.
 196  * @format: format string
 197  * @args...: variable argument list
 198  *
 199  * Kept as a compatibility API and is *DEPRECATED* in favor of
 200  * ust_marker().
 201  */
 202 #define trace_mark(channel, name, format, args...)      \
 203         __trace_mark_is_deprecated();                   \
 204         ust_marker(name, format, ## args)
 205
 206 static inline __attribute__((deprecated))
 207 void __MARKER_LIB_IS_DEPRECATED()
 208 {
 209 }
 210
 211 /*
 212  * MARKER_LIB is kept for backward compatibility and is *DEPRECATED*.
 213  * Use UST_MARKER_LIB instead.
 214  */
 215 #define MARKER_LIB                      \
 216         __MARKER_LIB_IS_DEPRECATED();   \
 217         UST_MARKER_LIB
 218
 219 /**
 220  * MARKER_NOARGS - Compatibility API. *DEPRECATED*. Use
 221  * UST_MARKER_NOARGS instead.
 222  */
 223 #define MARK_NOARGS     UST_MARKER_NOARGS
 224
 225 #ifdef __cplusplus
 226 }
 227 #endif
 228
 229 #endif /* _UST_MARKER_H */