libust/tracer.h

   1 /*
   2  * Copyright (C) 2005,2006,2008 Mathieu Desnoyers (mathieu.desnoyers@polymtl.ca)
   3  * Copyright (C) 2009 Pierre-Marc Fournier
   4  *
   5  * This contains the definitions for the Linux Trace Toolkit tracer.
   6  *
   7  * Ported to userspace by Pierre-Marc Fournier.
   8  *
   9  * This library is free software; you can redistribute it and/or
  10  * modify it under the terms of the GNU Lesser General Public
  11  * License as published by the Free Software Foundation; either
  12  * version 2.1 of the License, or (at your option) any later version.
  13  *
  14  * This library is distributed in the hope that it will be useful,
  15  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  16  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  17  * Lesser General Public License for more details.
  18  *
  19  * You should have received a copy of the GNU Lesser General Public
  20  * License along with this library; if not, write to the Free Software
  21  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301 USA
  22  */
  23
  24 #ifndef _LTT_TRACER_H
  25 #define _LTT_TRACER_H
  26
  27 #include <sys/types.h>
  28 #include <stdarg.h>
  29 #include <ust/marker.h>
  30 #include <ust/marker-internal.h>
  31 #include <ust/probe-internal.h>
  32 #include <ust/core.h>
  33 #include <ust/compat.h>
  34 #include "channels.h"
  35 #include "tracercore.h"
  36 #include "tracerconst.h"
  37 #include "buffers.h"
  38
  39 /* Number of bytes to log with a read/write event */
  40 #define LTT_LOG_RW_SIZE                 32L
  41
  42 /* Interval (in jiffies) at which the LTT per-CPU timer fires */
  43 #define LTT_PERCPU_TIMER_INTERVAL       1
  44
  45 #ifndef LTT_ARCH_TYPE
  46 #define LTT_ARCH_TYPE                   LTT_ARCH_TYPE_UNDEFINED
  47 #endif
  48
  49 #ifndef LTT_ARCH_VARIANT
  50 #define LTT_ARCH_VARIANT                LTT_ARCH_VARIANT_NONE
  51 #endif
  52
  53 struct ltt_active_ust_marker;
  54
  55 /* Maximum number of callbacks per ust_marker */
  56 #define LTT_NR_CALLBACKS        10
  57
  58 struct ltt_serialize_closure;
  59 struct ltt_probe_private_data;
  60
  61 struct ltt_serialize_closure {
  62         ltt_serialize_cb *callbacks;
  63         long cb_args[LTT_NR_CALLBACKS];
  64         unsigned int cb_idx;
  65 };
  66
  67 extern size_t ltt_serialize_data(struct ust_buffer *buf, size_t buf_offset,
  68                         struct ltt_serialize_closure *closure,
  69                         void *serialize_private,
  70                         unsigned int stack_pos_ctx, int *largest_align,
  71                         const char *fmt, va_list *args);
  72
  73 struct ltt_probe_private_data {
  74         struct ust_trace *trace;        /*
  75                                          * Target trace, for metadata
  76                                          * or statedump.
  77                                          */
  78         ltt_serialize_cb serializer;    /*
  79                                          * Serialization function override.
  80                                          */
  81         void *serialize_private;        /*
  82                                          * Private data for serialization
  83                                          * functions.
  84                                          */
  85 };
  86
  87 enum ltt_channels {
  88         LTT_CHANNEL_METADATA,
  89         LTT_CHANNEL_UST,
  90 };
  91
  92 struct chan_info_struct {
  93         const char *name;
  94         unsigned int def_subbufsize;
  95         unsigned int def_subbufcount;
  96 };
  97
  98 struct ltt_active_ust_marker {
  99         struct cds_list_head node;              /* active markers list */
 100         const char *channel;
 101         const char *name;
 102         const char *format;
 103         struct ltt_available_probe *probe;
 104 };
 105
 106 struct ust_marker; //ust//
 107 extern void ltt_vtrace(const struct ust_marker *mdata, void *probe_data,
 108         void *call_data, const char *fmt, va_list *args);
 109 extern void ltt_trace(const struct ust_marker *mdata, void *probe_data,
 110         void *call_data, const char *fmt, ...);
 111
 112 /*
 113  * Unique ID assigned to each registered probe.
 114  */
 115 enum ust_marker_id {
 116         UST_MARKER_ID_SET_MARKER_ID = 0,        /* Static IDs available (range 0-7) */
 117         UST_MARKER_ID_SET_MARKER_FORMAT,
 118         UST_MARKER_ID_COMPACT,          /* Compact IDs (range: 8-127)       */
 119         UST_MARKER_ID_DYNAMIC,          /* Dynamic IDs (range: 128-65535)   */
 120 };
 121
 122 /* static ids 0-1 reserved for internal use. */
 123 #define UST_MARKER_CORE_IDS             2
 124 static __inline__ enum ust_marker_id ust_marker_id_type(uint16_t id)
 125 {
 126         if (id < UST_MARKER_CORE_IDS)
 127                 return (enum ust_marker_id)id;
 128         else
 129                 return UST_MARKER_ID_DYNAMIC;
 130 }
 131
 132 struct user_dbg_data {
 133         unsigned long avail_size;
 134         unsigned long write;
 135         unsigned long read;
 136 };
 137
 138 struct ltt_trace_ops {
 139         /* First 32 bytes cache-hot cacheline */
 140         void (*wakeup_channel) (struct ust_channel *channel);
 141         int (*user_blocking) (struct ust_trace *trace,
 142                                 unsigned int index, size_t data_size,
 143                                 struct user_dbg_data *dbg);
 144         /* End of first 32 bytes cacheline */
 145         int (*create_dirs) (struct ust_trace *new_trace);
 146         void (*remove_dirs) (struct ust_trace *new_trace);
 147         int (*create_channel) (const char *trace_name,
 148                                 struct ust_trace *trace,
 149                                 const char *channel_name,
 150                                 struct ust_channel *channel,
 151                                 unsigned int subbuf_size,
 152                                 unsigned int n_subbufs, int overwrite);
 153         void (*finish_channel) (struct ust_channel *channel);
 154         void (*remove_channel) (struct ust_channel *channel);
 155         void (*user_errors) (struct ust_trace *trace,
 156                                 unsigned int index, size_t data_size,
 157                                 struct user_dbg_data *dbg, unsigned int cpu);
 158 };
 159
 160 struct ltt_transport {
 161         char *name;
 162         struct module *owner;
 163         struct cds_list_head node;
 164         struct ltt_trace_ops ops;
 165 };
 166
 167 enum trace_mode { LTT_TRACE_NORMAL, LTT_TRACE_FLIGHT, LTT_TRACE_HYBRID };
 168
 169 #define CHANNEL_FLAG_ENABLE     (1U<<0)
 170 #define CHANNEL_FLAG_OVERWRITE  (1U<<1)
 171
 172 /* Per-trace information - each trace/flight recorder represented by one */
 173 struct ust_trace {
 174         /* First 32 bytes cache-hot cacheline */
 175         struct cds_list_head list;
 176         struct ltt_trace_ops *ops;
 177         int active;
 178         /* Second 32 bytes cache-hot cacheline */
 179         struct ust_channel *channels;
 180         unsigned int nr_channels;
 181         u32 freq_scale;
 182         u64 start_freq;
 183         u64 start_tsc;
 184         unsigned long long start_monotonic;
 185         struct timeval          start_time;
 186         struct ltt_channel_setting *settings;
 187         struct {
 188                 struct dentry                   *trace_root;
 189         } dentry;
 190         struct urcu_ref urcu_ref; /* Each channel has a urcu_ref of the trace struct */
 191         struct ltt_transport *transport;
 192         struct urcu_ref ltt_transport_urcu_ref;
 193         char trace_name[NAME_MAX];
 194 } ____cacheline_aligned;
 195
 196 /*
 197  * We use asm/timex.h : cpu_khz/HZ variable in here : we might have to deal
 198  * specifically with CPU frequency scaling someday, so using an interpolation
 199  * between the start and end of buffer values is not flexible enough. Using an
 200  * immediate frequency value permits to calculate directly the times for parts
 201  * of a buffer that would be before a frequency change.
 202  *
 203  * Keep the natural field alignment for _each field_ within this structure if
 204  * you ever add/remove a field from this header. Packed attribute is not used
 205  * because gcc generates poor code on at least powerpc and mips. Don't ever
 206  * let gcc add padding between the structure elements.
 207  */
 208 struct ltt_subbuffer_header {
 209         uint64_t cycle_count_begin;     /* Cycle count at subbuffer start */
 210         uint64_t cycle_count_end;       /* Cycle count at subbuffer end */
 211         uint32_t magic_number;          /*
 212                                          * Trace magic number.
 213                                          * contains endianness information.
 214                                          */
 215         uint8_t major_version;
 216         uint8_t minor_version;
 217         uint8_t arch_size;              /* Architecture pointer size */
 218         uint8_t alignment;              /* LTT data alignment */
 219         uint64_t start_time_sec;        /* NTP-corrected start time */
 220         uint64_t start_time_usec;
 221         uint64_t start_freq;            /*
 222                                          * Frequency at trace start,
 223                                          * used all along the trace.
 224                                          */
 225         uint32_t freq_scale;            /* Frequency scaling (divisor) */
 226         uint32_t data_size;             /* Size of data in subbuffer */
 227         uint32_t sb_size;               /* Subbuffer size (including padding) */
 228         uint32_t events_lost;           /*
 229                                          * Events lost in this subbuffer since
 230                                          * the beginning of the trace.
 231                                          * (may overflow)
 232                                          */
 233         uint32_t subbuf_corrupt;        /*
 234                                          * Corrupted (lost) subbuffers since
 235                                          * the begginig of the trace.
 236                                          * (may overflow)
 237                                          */
 238         uint8_t header_end[0];          /* End of header */
 239 };
 240
 241 /**
 242  * ltt_subbuffer_header_size - called on buffer-switch to a new sub-buffer
 243  *
 244  * Return header size without padding after the structure. Don't use packed
 245  * structure because gcc generates inefficient code on some architectures
 246  * (powerpc, mips..)
 247  */
 248 static __inline__ size_t ltt_subbuffer_header_size(void)
 249 {
 250         return offsetof(struct ltt_subbuffer_header, header_end);
 251 }
 252
 253 extern size_t ltt_write_event_header_slow(struct ust_channel *channel,
 254                struct ust_buffer *buf, long buf_offset,
 255                u16 eID, u32 event_size,
 256                u64 tsc, unsigned int rflags);
 257
 258
 259 /*
 260  * ltt_write_event_header
 261  *
 262  * Writes the event header to the offset (already aligned on 32-bits).
 263  *
 264  * @trace : trace to write to.
 265  * @channel : pointer to the channel structure..
 266  * @buf : buffer to write to.
 267  * @buf_offset : buffer offset to write to (aligned on 32 bits).
 268  * @eID : event ID
 269  * @event_size : size of the event, excluding the event header.
 270  * @tsc : time stamp counter.
 271  * @rflags : reservation flags.
 272  *
 273  * returns : offset where the event data must be written.
 274  */
 275 static __inline__ size_t ltt_write_event_header(struct ust_channel *chan,
 276                 struct ust_buffer *buf, long buf_offset,
 277                 u16 eID, u32 event_size,
 278                 u64 tsc, unsigned int rflags)
 279 {
 280         struct ltt_event_header header;
 281
 282         if (unlikely(rflags))
 283                 goto slow_path;
 284
 285         header.id_time = eID << LTT_TSC_BITS;
 286         header.id_time |= (u32)tsc & LTT_TSC_MASK;
 287         ust_buffers_write(buf, buf_offset, &header, sizeof(header));
 288         buf_offset += sizeof(header);
 289
 290         return buf_offset;
 291
 292 slow_path:
 293         return ltt_write_event_header_slow(chan, buf, buf_offset,
 294                                 eID, event_size, tsc, rflags);
 295 }
 296
 297 /*
 298  * Control channels :
 299  * control/metadata
 300  * control/interrupts
 301  * control/...
 302  *
 303  * cpu channel :
 304  * cpu
 305  */
 306
 307 #define LTT_METADATA_CHANNEL            "metadata_state"
 308 #define LTT_UST_CHANNEL                 "ust"
 309
 310 #define LTT_FLIGHT_PREFIX       "flight-"
 311
 312 /* Tracer properties */
 313 //#define LTT_DEFAULT_SUBBUF_SIZE_LOW   134217728
 314 #define LTT_DEFAULT_SUBBUF_SIZE_LOW     65536
 315 //#define LTT_DEFAULT_SUBBUF_SIZE_LOW   4096
 316 #define LTT_DEFAULT_N_SUBBUFS_LOW       2
 317 //#define LTT_DEFAULT_SUBBUF_SIZE_MED   134217728
 318 #define LTT_DEFAULT_SUBBUF_SIZE_MED     262144
 319 //#define LTT_DEFAULT_SUBBUF_SIZE_MED   4096
 320 #define LTT_DEFAULT_N_SUBBUFS_MED       2
 321 //#define LTT_DEFAULT_SUBBUF_SIZE_HIGH  134217728
 322 #define LTT_DEFAULT_SUBBUF_SIZE_HIGH    1048576
 323 //#define LTT_DEFAULT_SUBBUF_SIZE_HIGH  4096
 324 #define LTT_DEFAULT_N_SUBBUFS_HIGH      2
 325 #define LTT_TRACER_MAGIC_NUMBER         0x00D6B7ED
 326 #define LTT_TRACER_VERSION_MAJOR        2
 327 #define LTT_TRACER_VERSION_MINOR        6
 328
 329 /**
 330  * ust_write_trace_header - Write trace header
 331  * @trace: Trace information
 332  * @header: Memory address where the information must be written to
 333  */
 334 static __inline__ void ltt_write_trace_header(struct ust_trace *trace,
 335                struct ltt_subbuffer_header *header)
 336 {
 337         header->magic_number = LTT_TRACER_MAGIC_NUMBER;
 338         header->major_version = LTT_TRACER_VERSION_MAJOR;
 339         header->minor_version = LTT_TRACER_VERSION_MINOR;
 340         header->arch_size = sizeof(void *);
 341         header->alignment = ltt_get_alignment();
 342         header->start_time_sec = trace->start_time.tv_sec;
 343         header->start_time_usec = trace->start_time.tv_usec;
 344         header->start_freq = trace->start_freq;
 345         header->freq_scale = trace->freq_scale;
 346 }
 347
 348 #ifndef UST_VALGRIND
 349
 350 static __inline__ int ust_get_cpu(void)
 351 {
 352         int cpu;
 353
 354         cpu = sched_getcpu();
 355         if (likely(cpu >= 0))
 356                 return cpu;
 357         /*
 358          * If getcpu(2) is not implemented in the Kernel use CPU 0 as fallback.
 359          */
 360         return 0;
 361 }
 362
 363 #else   /* #else #ifndef UST_VALGRIND */
 364
 365 static __inline__ int ust_get_cpu(void)
 366 {
 367         /*
 368          * Valgrind does not support the sched_getcpu() vsyscall.
 369          * It causes it to detect a segfault in the program and stop it.
 370          * So if we want to check libust with valgrind, we have to refrain
 371          * from using this call. TODO: it would probably be better to return
 372          * other values too, to better test it.
 373          */
 374         return 0;
 375 }
 376
 377 #endif  /* #else #ifndef UST_VALGRIND */
 378
 379 /*
 380  * Size reserved for high priority events (interrupts, NMI, BH) at the end of a
 381  * nearly full buffer. User space won't use this last amount of space when in
 382  * blocking mode. This space also includes the event header that would be
 383  * written by this user space event.
 384  */
 385 #define LTT_RESERVE_CRITICAL            4096
 386
 387 /* Register and unregister function pointers */
 388
 389 enum ltt_module_function {
 390         LTT_FUNCTION_RUN_FILTER,
 391         LTT_FUNCTION_FILTER_CONTROL,
 392         LTT_FUNCTION_STATEDUMP
 393 };
 394
 395 extern void ltt_transport_register(struct ltt_transport *transport);
 396 extern void ltt_transport_unregister(struct ltt_transport *transport);
 397
 398 /* Exported control function */
 399
 400 union ltt_control_args {
 401         struct {
 402                 enum trace_mode mode;
 403                 unsigned int subbuf_size_low;
 404                 unsigned int n_subbufs_low;
 405                 unsigned int subbuf_size_med;
 406                 unsigned int n_subbufs_med;
 407                 unsigned int subbuf_size_high;
 408                 unsigned int n_subbufs_high;
 409         } new_trace;
 410 };
 411
 412 extern int _ltt_trace_setup(const char *trace_name);
 413 extern int ltt_trace_setup(const char *trace_name);
 414 extern struct ust_trace *_ltt_trace_find_setup(const char *trace_name);
 415 extern int ltt_trace_set_type(const char *trace_name, const char *trace_type);
 416 extern int ltt_trace_set_channel_subbufsize(const char *trace_name,
 417                 const char *channel_name, unsigned int size);
 418 extern int ltt_trace_set_channel_subbufcount(const char *trace_name,
 419                 const char *channel_name, unsigned int cnt);
 420 extern int ltt_trace_set_channel_enable(const char *trace_name,
 421                 const char *channel_name, unsigned int enable);
 422 extern int ltt_trace_set_channel_overwrite(const char *trace_name,
 423                 const char *channel_name, unsigned int overwrite);
 424 extern int ltt_trace_alloc(const char *trace_name);
 425 extern int ltt_trace_destroy(const char *trace_name, int drop);
 426 extern int ltt_trace_start(const char *trace_name);
 427 extern int ltt_trace_stop(const char *trace_name);
 428
 429 enum ltt_filter_control_msg {
 430         LTT_FILTER_DEFAULT_ACCEPT,
 431         LTT_FILTER_DEFAULT_REJECT
 432 };
 433
 434 extern int ltt_filter_control(enum ltt_filter_control_msg msg,
 435                 const char *trace_name);
 436
 437 extern struct dentry *get_filter_root(void);
 438
 439 extern void ltt_write_trace_header(struct ust_trace *trace,
 440                 struct ltt_subbuffer_header *header);
 441 extern void ltt_buffer_destroy(struct ust_channel *ltt_chan);
 442
 443 extern void ltt_core_register(int (*function)(u8, void *));
 444
 445 extern void ltt_core_unregister(void);
 446
 447 extern void ltt_release_trace(struct urcu_ref *urcu_ref);
 448 extern void ltt_release_transport(struct urcu_ref *urcu_ref);
 449
 450 extern void ltt_dump_ust_marker_state(struct ust_trace *trace);
 451
 452 extern void ltt_lock_traces(void);
 453 extern void ltt_unlock_traces(void);
 454
 455 extern struct ust_trace *_ltt_trace_find(const char *trace_name);
 456
 457 #endif /* _LTT_TRACER_H */