include/lttng/lttng.h

   1 /*
   2  * lttng.h
   3  *
   4  * Linux Trace Toolkit Control Library Header File
   5  *
   6  * Copyright (C) 2011 - David Goulet <david.goulet@polymtl.ca>
   7  *
   8  * This program is free software; you can redistribute it and/or
   9  * modify it under the terms of the GNU General Public License
  10  * as published by the Free Software Foundation; either version 2
  11  * of the License, or (at your option) any later version.
  12  *
  13  * This program is distributed in the hope that it will be useful,
  14  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  16  * GNU General Public License for more details.
  17  *
  18  * You should have received a copy of the GNU General Public License
  19  * along with this program; if not, write to the Free Software
  20  * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
  21  */
  22
  23 #ifndef _LTTNG_H
  24 #define _LTTNG_H
  25
  26 #include <asm/types.h>
  27 #include <stdint.h>
  28 #include <limits.h>
  29
  30 /* Default unix group name for tracing. */
  31 #define LTTNG_DEFAULT_TRACING_GROUP "tracing"
  32
  33 /* Environment variable to set session daemon binary path. */
  34 #define LTTNG_SESSIOND_PATH_ENV "LTTNG_SESSIOND_PATH"
  35
  36 /* Default trace output directory name */
  37 #define LTTNG_DEFAULT_TRACE_DIR_NAME "lttng-traces"
  38
  39 /*
  40  * Event symbol length. Copied from LTTng kernel ABI.
  41  */
  42 #define LTTNG_SYMBOL_NAME_LEN 128
  43
  44 /*
  45  * Every lttng_event_* structure both apply to kernel event and user-space
  46  * event.
  47  *
  48  * Every lttng_kernel_* is copied from the LTTng kernel ABI.
  49  */
  50
  51 enum lttng_event_type {
  52         LTTNG_EVENT_TRACEPOINT,
  53         LTTNG_EVENT_KPROBE,
  54         LTTNG_EVENT_FUNCTION,
  55 };
  56
  57 /*
  58  * LTTng consumer mode
  59  */
  60 enum lttng_event_output {
  61         /* Using splice(2) */
  62         LTTNG_EVENT_SPLICE       = 0,
  63         /* Using mmap(2) */
  64         LTTNG_EVENT_MMAP         = 1,
  65 };
  66
  67 /* Kernel context possible type */
  68 enum lttng_kernel_context_type {
  69         LTTNG_KERNEL_CONTEXT_PID                = 0,
  70         LTTNG_KERNEL_CONTEXT_PERF_COUNTER       = 1,
  71         LTTNG_KERNEL_CONTEXT_COMM               = 2,
  72         LTTNG_KERNEL_CONTEXT_PRIO               = 3,
  73         LTTNG_KERNEL_CONTEXT_NICE               = 4,
  74         LTTNG_KERNEL_CONTEXT_VPID               = 5,
  75         LTTNG_KERNEL_CONTEXT_TID                = 6,
  76         LTTNG_KERNEL_CONTEXT_VTID               = 7,
  77         LTTNG_KERNEL_CONTEXT_PPID               = 8,
  78         LTTNG_KERNEL_CONTEXT_VPPID              = 9,
  79 };
  80
  81 /* Perf counter attributes */
  82 struct lttng_kernel_perf_counter_ctx {
  83         uint32_t type;
  84         uint64_t config;
  85         char name[LTTNG_SYMBOL_NAME_LEN];
  86 };
  87
  88 /* Event/Channel context */
  89 struct lttng_kernel_context {
  90         enum lttng_kernel_context_type ctx;
  91         union {
  92                 struct lttng_kernel_perf_counter_ctx perf_counter;
  93         } u;
  94 };
  95
  96 /*
  97  * Kernel Kprobe. Either addr is used or symbol_name and offset.
  98  */
  99 struct lttng_kernel_kprobe_attr {
 100         uint64_t addr;
 101
 102         uint64_t offset;
 103         char symbol_name[LTTNG_SYMBOL_NAME_LEN];
 104 };
 105
 106 /*
 107  * Function tracer
 108  */
 109 struct lttng_event_function_attr {
 110         char symbol_name[LTTNG_SYMBOL_NAME_LEN];
 111 };
 112
 113 /*
 114  * Generic lttng event
 115  */
 116 struct lttng_event {
 117         char name[LTTNG_SYMBOL_NAME_LEN];
 118         enum lttng_event_type type;
 119         /* Per event type configuration */
 120         union {
 121                 struct lttng_kernel_kprobe_attr kprobe;
 122                 struct lttng_event_function_attr ftrace;
 123         } attr;
 124 };
 125
 126 /*
 127  * Tracer channel attributes. For both kernel and user-space.
 128  */
 129 struct lttng_channel_attr {
 130         int overwrite;                      /* 1: overwrite, 0: discard */
 131         uint64_t subbuf_size;               /* bytes */
 132         uint64_t num_subbuf;                /* power of 2 */
 133         unsigned int switch_timer_interval; /* usec */
 134         unsigned int read_timer_interval;   /* usec */
 135         enum lttng_event_output output;     /* splice, mmap */
 136 };
 137
 138 /*
 139  * Channel information structure. For both kernel and user-space.
 140  */
 141 struct lttng_channel {
 142         char name[NAME_MAX];
 143         struct lttng_channel_attr attr;
 144 };
 145
 146 /*
 147  * Basic session information.
 148  *
 149  * This is an 'output data' meaning that it only comes *from* the session
 150  * daemon *to* the lttng client. It's basically a 'human' representation of
 151  * tracing entities (here a session).
 152  */
 153 struct lttng_session {
 154         char name[NAME_MAX];
 155         /* The path where traces are written */
 156         char path[PATH_MAX];
 157 };
 158
 159 /*
 160  * Session daemon control
 161  */
 162 extern int lttng_create_session(char *name, char *path);
 163
 164 extern int lttng_destroy_session(char *name);
 165
 166 /*
 167  * Return a "lttng_session" array. Caller must free(3) the returned data.
 168  */
 169 extern int lttng_list_sessions(struct lttng_session **sessions);
 170
 171 extern int lttng_session_daemon_alive(void);
 172
 173 /* Set tracing group for the current execution */
 174 extern int lttng_set_tracing_group(const char *name);
 175
 176 extern void lttng_set_session_name(char *name);
 177
 178 extern const char *lttng_get_readable_code(int code);
 179
 180 extern int lttng_start_tracing(char *session_name);
 181
 182 extern int lttng_stop_tracing(char *session_name);
 183
 184 /*
 185  * LTTng Kernel tracer control
 186  */
 187 extern int lttng_kernel_add_context(struct lttng_kernel_context *ctx,
 188                 char *event_name, char *channel_name);
 189
 190 extern int lttng_kernel_create_channel(struct lttng_channel *chan);
 191
 192 extern int lttng_kernel_enable_event(struct lttng_event *ev, char *channel_name);
 193
 194 extern int lttng_kernel_enable_channel(char *name);
 195
 196 extern int lttng_kernel_disable_event(char *name, char *channel_name);
 197
 198 extern int lttng_kernel_disable_channel(char *name);
 199
 200 extern int lttng_kernel_list_events(char **event_list);
 201
 202 /*
 203  * LTTng User-space tracer control
 204  */
 205
 206 //extern int lttng_ust_list_traceable_apps(pid_t **pids);
 207
 208 #endif /* _LTTNG_H */