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/kernelcompat.h>
  30 #include "channels.h"
  31 #include "tracercore.h"
  32 #include "tracerconst.h"
  33 #include <ust/marker.h>
  34 #include <ust/probe.h>
  35
  36 /* Number of bytes to log with a read/write event */
  37 #define LTT_LOG_RW_SIZE                 32L
  38
  39 /* Interval (in jiffies) at which the LTT per-CPU timer fires */
  40 #define LTT_PERCPU_TIMER_INTERVAL       1
  41
  42 #ifndef LTT_ARCH_TYPE
  43 #define LTT_ARCH_TYPE                   LTT_ARCH_TYPE_UNDEFINED
  44 #endif
  45
  46 #ifndef LTT_ARCH_VARIANT
  47 #define LTT_ARCH_VARIANT                LTT_ARCH_VARIANT_NONE
  48 #endif
  49
  50 struct ltt_active_marker;
  51
  52 /* Maximum number of callbacks per marker */
  53 #define LTT_NR_CALLBACKS        10
  54
  55 struct ltt_serialize_closure;
  56 struct ltt_probe_private_data;
  57
  58 struct ltt_serialize_closure {
  59         ltt_serialize_cb *callbacks;
  60         long cb_args[LTT_NR_CALLBACKS];
  61         unsigned int cb_idx;
  62 };
  63
  64 extern size_t ltt_serialize_data(struct ust_buffer *buf, size_t buf_offset,
  65                         struct ltt_serialize_closure *closure,
  66                         void *serialize_private,
  67                         int *largest_align, const char *fmt, va_list *args);
  68
  69 struct ltt_probe_private_data {
  70         struct ust_trace *trace;        /*
  71                                          * Target trace, for metadata
  72                                          * or statedump.
  73                                          */
  74         ltt_serialize_cb serializer;    /*
  75                                          * Serialization function override.
  76                                          */
  77         void *serialize_private;        /*
  78                                          * Private data for serialization
  79                                          * functions.
  80                                          */
  81 };
  82
  83 enum ltt_channels {
  84         LTT_CHANNEL_METADATA,
  85         LTT_CHANNEL_UST,
  86 };
  87
  88 struct ltt_active_marker {
  89         struct list_head node;          /* active markers list */
  90         const char *channel;
  91         const char *name;
  92         const char *format;
  93         struct ltt_available_probe *probe;
  94 };
  95
  96 struct marker; //ust//
  97 extern void ltt_vtrace(const struct marker *mdata, void *probe_data,
  98         struct registers *regs, void *call_data, const char *fmt, va_list *args);
  99 extern void ltt_trace(const struct marker *mdata, void *probe_data,
 100         struct registers *regs, void *call_data, const char *fmt, ...);
 101
 102 /*
 103  * Unique ID assigned to each registered probe.
 104  */
 105 enum marker_id {
 106         MARKER_ID_SET_MARKER_ID = 0,    /* Static IDs available (range 0-7) */
 107         MARKER_ID_SET_MARKER_FORMAT,
 108         MARKER_ID_COMPACT,              /* Compact IDs (range: 8-127)       */
 109         MARKER_ID_DYNAMIC,              /* Dynamic IDs (range: 128-65535)   */
 110 };
 111
 112 /* static ids 0-1 reserved for internal use. */
 113 #define MARKER_CORE_IDS         2
 114 static __inline__ enum marker_id marker_id_type(uint16_t id)
 115 {
 116         if (id < MARKER_CORE_IDS)
 117                 return (enum marker_id)id;
 118         else
 119                 return MARKER_ID_DYNAMIC;
 120 }
 121
 122 struct user_dbg_data {
 123         unsigned long avail_size;
 124         unsigned long write;
 125         unsigned long read;
 126 };
 127
 128 struct ltt_trace_ops {
 129         /* First 32 bytes cache-hot cacheline */
 130         void (*wakeup_channel) (struct ust_channel *channel);
 131         int (*user_blocking) (struct ust_trace *trace,
 132                                 unsigned int index, size_t data_size,
 133                                 struct user_dbg_data *dbg);
 134         /* End of first 32 bytes cacheline */
 135         int (*create_dirs) (struct ust_trace *new_trace);
 136         void (*remove_dirs) (struct ust_trace *new_trace);
 137         int (*create_channel) (const char *trace_name,
 138                                 struct ust_trace *trace,
 139                                 const char *channel_name,
 140                                 struct ust_channel *channel,
 141                                 unsigned int subbuf_size,
 142                                 unsigned int n_subbufs, int overwrite);
 143         void (*finish_channel) (struct ust_channel *channel);
 144         void (*remove_channel) (struct ust_channel *channel);
 145         void (*user_errors) (struct ust_trace *trace,
 146                                 unsigned int index, size_t data_size,
 147                                 struct user_dbg_data *dbg, unsigned int cpu);
 148 };
 149
 150 struct ltt_transport {
 151         char *name;
 152         struct module *owner;
 153         struct list_head node;
 154         struct ltt_trace_ops ops;
 155 };
 156
 157 enum trace_mode { LTT_TRACE_NORMAL, LTT_TRACE_FLIGHT, LTT_TRACE_HYBRID };
 158
 159 #define CHANNEL_FLAG_ENABLE     (1U<<0)
 160 #define CHANNEL_FLAG_OVERWRITE  (1U<<1)
 161
 162 /* Per-trace information - each trace/flight recorder represented by one */
 163 struct ust_trace {
 164         /* First 32 bytes cache-hot cacheline */
 165         struct list_head list;
 166         struct ltt_trace_ops *ops;
 167         int active;
 168         /* Second 32 bytes cache-hot cacheline */
 169         struct ust_channel *channels;
 170         unsigned int nr_channels;
 171         u32 freq_scale;
 172         u64 start_freq;
 173         u64 start_tsc;
 174         unsigned long long start_monotonic;
 175         struct timeval          start_time;
 176         struct ltt_channel_setting *settings;
 177         struct {
 178                 struct dentry                   *trace_root;
 179         } dentry;
 180         struct kref kref; /* Each channel has a kref of the trace struct */
 181         struct ltt_transport *transport;
 182         struct kref ltt_transport_kref;
 183         char trace_name[NAME_MAX];
 184 } ____cacheline_aligned;
 185
 186 /*
 187  * We use asm/timex.h : cpu_khz/HZ variable in here : we might have to deal
 188  * specifically with CPU frequency scaling someday, so using an interpolation
 189  * between the start and end of buffer values is not flexible enough. Using an
 190  * immediate frequency value permits to calculate directly the times for parts
 191  * of a buffer that would be before a frequency change.
 192  *
 193  * Keep the natural field alignment for _each field_ within this structure if
 194  * you ever add/remove a field from this header. Packed attribute is not used
 195  * because gcc generates poor code on at least powerpc and mips. Don't ever
 196  * let gcc add padding between the structure elements.
 197  */
 198 struct ltt_subbuffer_header {
 199         uint64_t cycle_count_begin;     /* Cycle count at subbuffer start */
 200         uint64_t cycle_count_end;       /* Cycle count at subbuffer end */
 201         uint32_t magic_number;          /*
 202                                          * Trace magic number.
 203                                          * contains endianness information.
 204                                          */
 205         uint8_t major_version;
 206         uint8_t minor_version;
 207         uint8_t arch_size;              /* Architecture pointer size */
 208         uint8_t alignment;              /* LTT data alignment */
 209         uint64_t start_time_sec;        /* NTP-corrected start time */
 210         uint64_t start_time_usec;
 211         uint64_t start_freq;            /*
 212                                          * Frequency at trace start,
 213                                          * used all along the trace.
 214                                          */
 215         uint32_t freq_scale;            /* Frequency scaling (divisor) */
 216         uint32_t lost_size;             /* Size unused at end of subbuffer */
 217         uint32_t buf_size;              /* Size of this subbuffer */
 218         uint32_t events_lost;           /*
 219                                          * Events lost in this subbuffer since
 220                                          * the beginning of the trace.
 221                                          * (may overflow)
 222                                          */
 223         uint32_t subbuf_corrupt;        /*
 224                                          * Corrupted (lost) subbuffers since
 225                                          * the begginig of the trace.
 226                                          * (may overflow)
 227                                          */
 228         uint8_t header_end[0];          /* End of header */
 229 };
 230
 231 /**
 232  * ltt_subbuffer_header_size - called on buffer-switch to a new sub-buffer
 233  *
 234  * Return header size without padding after the structure. Don't use packed
 235  * structure because gcc generates inefficient code on some architectures
 236  * (powerpc, mips..)
 237  */
 238 static __inline__ size_t ltt_subbuffer_header_size(void)
 239 {
 240         return offsetof(struct ltt_subbuffer_header, header_end);
 241 }
 242
 243 extern size_t ltt_write_event_header_slow(struct ust_trace *trace,
 244                struct ust_channel *channel,
 245                struct ust_buffer *buf, long buf_offset,
 246                u16 eID, u32 event_size,
 247                u64 tsc, unsigned int rflags);
 248
 249
 250 /*
 251  * ltt_write_event_header
 252  *
 253  * Writes the event header to the offset (already aligned on 32-bits).
 254  *
 255  * @trace : trace to write to.
 256  * @channel : pointer to the channel structure..
 257  * @buf : buffer to write to.
 258  * @buf_offset : buffer offset to write to (aligned on 32 bits).
 259  * @eID : event ID
 260  * @event_size : size of the event, excluding the event header.
 261  * @tsc : time stamp counter.
 262  * @rflags : reservation flags.
 263  *
 264  * returns : offset where the event data must be written.
 265  */
 266 static __inline__ size_t ltt_write_event_header(struct ust_trace *trace,
 267                 struct ust_channel *channel,
 268                 struct ust_buffer *buf, long buf_offset,
 269                 u16 eID, u32 event_size,
 270                 u64 tsc, unsigned int rflags)
 271 {
 272         struct ltt_event_header header;
 273
 274         if (unlikely(rflags))
 275                 goto slow_path;
 276
 277         header.id_time = eID << LTT_TSC_BITS;
 278
 279         return buf_offset;
 280
 281 slow_path:
 282         return ltt_write_event_header_slow(trace, channel, buf, buf_offset,
 283                                 eID, event_size, tsc, rflags);
 284 }
 285
 286 /*
 287  * Control channels :
 288  * control/metadata
 289  * control/interrupts
 290  * control/...
 291  *
 292  * cpu channel :
 293  * cpu
 294  */
 295
 296 #define LTT_METADATA_CHANNEL            "metadata_state"
 297 #define LTT_UST_CHANNEL                 "ust"
 298
 299 #define LTT_FLIGHT_PREFIX       "flight-"
 300
 301 /* Tracer properties */
 302 //#define LTT_DEFAULT_SUBBUF_SIZE_LOW   134217728
 303 #define LTT_DEFAULT_SUBBUF_SIZE_LOW     65536
 304 //#define LTT_DEFAULT_SUBBUF_SIZE_LOW   4096
 305 #define LTT_DEFAULT_N_SUBBUFS_LOW       2
 306 //#define LTT_DEFAULT_SUBBUF_SIZE_MED   134217728
 307 #define LTT_DEFAULT_SUBBUF_SIZE_MED     262144
 308 //#define LTT_DEFAULT_SUBBUF_SIZE_MED   4096
 309 #define LTT_DEFAULT_N_SUBBUFS_MED       2
 310 //#define LTT_DEFAULT_SUBBUF_SIZE_HIGH  134217728
 311 #define LTT_DEFAULT_SUBBUF_SIZE_HIGH    1048576
 312 //#define LTT_DEFAULT_SUBBUF_SIZE_HIGH  4096
 313 #define LTT_DEFAULT_N_SUBBUFS_HIGH      2
 314 #define LTT_TRACER_MAGIC_NUMBER         0x00D6B7ED
 315 #define LTT_TRACER_VERSION_MAJOR        2
 316 #define LTT_TRACER_VERSION_MINOR        4
 317
 318 /**
 319  * ust_write_trace_header - Write trace header
 320  * @trace: Trace information
 321  * @header: Memory address where the information must be written to
 322  */
 323 static __inline__ void ltt_write_trace_header(struct ust_trace *trace,
 324                struct ltt_subbuffer_header *header)
 325 {
 326         header->magic_number = LTT_TRACER_MAGIC_NUMBER;
 327         header->major_version = LTT_TRACER_VERSION_MAJOR;
 328         header->minor_version = LTT_TRACER_VERSION_MINOR;
 329         header->arch_size = sizeof(void *);
 330         header->alignment = ltt_get_alignment();
 331         header->start_time_sec = trace->start_time.tv_sec;
 332         header->start_time_usec = trace->start_time.tv_usec;
 333         header->start_freq = trace->start_freq;
 334         header->freq_scale = trace->freq_scale;
 335 }
 336
 337
 338 /*
 339  * Size reserved for high priority events (interrupts, NMI, BH) at the end of a
 340  * nearly full buffer. User space won't use this last amount of space when in
 341  * blocking mode. This space also includes the event header that would be
 342  * written by this user space event.
 343  */
 344 #define LTT_RESERVE_CRITICAL            4096
 345
 346 /* Register and unregister function pointers */
 347
 348 enum ltt_module_function {
 349         LTT_FUNCTION_RUN_FILTER,
 350         LTT_FUNCTION_FILTER_CONTROL,
 351         LTT_FUNCTION_STATEDUMP
 352 };
 353
 354 extern void ltt_transport_register(struct ltt_transport *transport);
 355 extern void ltt_transport_unregister(struct ltt_transport *transport);
 356
 357 /* Exported control function */
 358
 359 union ltt_control_args {
 360         struct {
 361                 enum trace_mode mode;
 362                 unsigned int subbuf_size_low;
 363                 unsigned int n_subbufs_low;
 364                 unsigned int subbuf_size_med;
 365                 unsigned int n_subbufs_med;
 366                 unsigned int subbuf_size_high;
 367                 unsigned int n_subbufs_high;
 368         } new_trace;
 369 };
 370
 371 extern int _ltt_trace_setup(const char *trace_name);
 372 extern int ltt_trace_setup(const char *trace_name);
 373 extern struct ust_trace *_ltt_trace_find_setup(const char *trace_name);
 374 extern int ltt_trace_set_type(const char *trace_name, const char *trace_type);
 375 extern int ltt_trace_set_channel_subbufsize(const char *trace_name,
 376                 const char *channel_name, unsigned int size);
 377 extern int ltt_trace_set_channel_subbufcount(const char *trace_name,
 378                 const char *channel_name, unsigned int cnt);
 379 extern int ltt_trace_set_channel_enable(const char *trace_name,
 380                 const char *channel_name, unsigned int enable);
 381 extern int ltt_trace_set_channel_overwrite(const char *trace_name,
 382                 const char *channel_name, unsigned int overwrite);
 383 extern int ltt_trace_alloc(const char *trace_name);
 384 extern int ltt_trace_destroy(const char *trace_name);
 385 extern int ltt_trace_start(const char *trace_name);
 386 extern int ltt_trace_stop(const char *trace_name);
 387
 388 enum ltt_filter_control_msg {
 389         LTT_FILTER_DEFAULT_ACCEPT,
 390         LTT_FILTER_DEFAULT_REJECT
 391 };
 392
 393 extern int ltt_filter_control(enum ltt_filter_control_msg msg,
 394                 const char *trace_name);
 395
 396 extern struct dentry *get_filter_root(void);
 397
 398 extern void ltt_write_trace_header(struct ust_trace *trace,
 399                 struct ltt_subbuffer_header *header);
 400 extern void ltt_buffer_destroy(struct ust_channel *ltt_chan);
 401
 402 extern void ltt_core_register(int (*function)(u8, void *));
 403
 404 extern void ltt_core_unregister(void);
 405
 406 extern void ltt_release_trace(struct kref *kref);
 407 extern void ltt_release_transport(struct kref *kref);
 408
 409 extern void ltt_dump_marker_state(struct ust_trace *trace);
 410
 411 extern void ltt_lock_traces(void);
 412 extern void ltt_unlock_traces(void);
 413
 414 extern struct ust_trace *_ltt_trace_find(const char *trace_name);
 415
 416 #endif /* _LTT_TRACER_H */