Fix tracing events data structure

[lttng-tools.git] / include / lttng / lttng.h

diff --git a/include/lttng/lttng.h b/include/lttng/lttng.h
index 5f60300616a57788ccf3a99112a616ec02142cac..448bd9fdcf944f432a757a7622286a3c3323bdaf 100644 (file)
--- a/include/lttng/lttng.h
+++ b/include/lttng/lttng.h
@@ -33,17 +33,37 @@
 /* Environment variable to set session daemon binary path. */
 #define LTTNG_SESSIOND_PATH_ENV "LTTNG_SESSIOND_PATH"
 
+/* Default trace output directory name */
+#define LTTNG_DEFAULT_TRACE_DIR_NAME "lttng-traces"
+
 /*
- * Event symbol length.
+ * Event symbol length. Copied from LTTng kernel ABI.
  */
 #define LTTNG_SYMBOL_NAME_LEN 128
 
+/*
+ * Every lttng_event_* structure both apply to kernel event and user-space
+ * event.
+ *
+ * Every lttng_kernel_* is copied from the LTTng kernel ABI.
+ */
+
 enum lttng_event_type {
-       LTTNG_EVENT_TRACEPOINTS,
-       LTTNG_EVENT_KPROBES,
+       LTTNG_EVENT_TRACEPOINT,
+       LTTNG_EVENT_KPROBE,
        LTTNG_EVENT_FUNCTION,
 };
 
+/*
+ * LTTng consumer mode
+ */
+enum lttng_event_output {
+       /* Using splice(2) */
+       LTTNG_EVENT_SPLICE       = 0,
+       /* Using mmap(2) */
+       LTTNG_EVENT_MMAP         = 1,
+};
+
 /* Kernel context possible type */
 enum lttng_kernel_context_type {
        LTTNG_KERNEL_CONTEXT_PID                = 0,
@@ -73,14 +93,6 @@ struct lttng_kernel_context {
        } u;
 };
 
-/*
- * LTTng consumer mode
- */
-enum lttng_kernel_output {
-       LTTNG_KERNEL_SPLICE       = 0,
-       LTTNG_KERNEL_MMAP         = 1,
-};
-
 /*
  * Either addr is used or symbol_name and offset.
  */
@@ -111,28 +123,37 @@ struct lttng_event {
        } attr;
 };
 
-/* Tracer channel attributes */
+/*
+ * Tracer channel attributes. For both kernel and user-space.
+ */
 struct lttng_channel_attr {
-       int overwrite;                          /* 1: overwrite, 0: discard */
-       uint64_t subbuf_size;                   /* bytes */
-       uint64_t num_subbuf;                    /* power of 2 */
-       unsigned int switch_timer_interval;     /* usec */
-       unsigned int read_timer_interval;       /* usec */
-       enum lttng_kernel_output output;        /* splice, mmap */
+       int overwrite;                      /* 1: overwrite, 0: discard */
+       uint64_t subbuf_size;               /* bytes */
+       uint64_t num_subbuf;                /* power of 2 */
+       unsigned int switch_timer_interval; /* usec */
+       unsigned int read_timer_interval;   /* usec */
+       enum lttng_event_output output;    /* splice, mmap */
 };
 
 /*
- * Basic session information.
+ * Channel information structure. For both kernel and user-space.
  */
-struct lttng_session {
+struct lttng_channel {
        char name[NAME_MAX];
-       char path[PATH_MAX];
+       struct lttng_channel_attr attr;
 };
 
-/* Channel information structure */
-struct lttng_channel {
+/*
+ * Basic session information.
+ *
+ * This is an 'output data' meaning that it only comes *from* the session
+ * daemon *to* the lttng client. It's basically a 'human' representation of
+ * tracing entities (here a session).
+ */
+struct lttng_session {
        char name[NAME_MAX];
-       struct lttng_channel_attr attr;
+       /* The path where traces are written */
+       char path[PATH_MAX];
 };
 
 /*
@@ -146,7 +167,9 @@ extern int lttng_destroy_session(char *name);
 
 extern int lttng_disconnect_sessiond(void);
 
-/* Return an allocated array of lttng_session */
+/*
+ * Return a "lttng_session" array. Caller must free(3) the returned data.
+ */
 extern int lttng_list_sessions(struct lttng_session **sessions);
 
 extern int lttng_session_daemon_alive(void);
@@ -162,8 +185,6 @@ extern int lttng_start_tracing(char *session_name);
 
 extern int lttng_stop_tracing(char *session_name);
 
-//extern int lttng_ust_list_traceable_apps(pid_t **pids);
-
 /*
  * LTTng Kernel tracer control
  */
@@ -186,4 +207,6 @@ extern int lttng_kernel_list_events(char **event_list);
  * LTTng User-space tracer control
  */
 
+//extern int lttng_ust_list_traceable_apps(pid_t **pids);
+
 #endif /* _LTTNG_H */