liblttd/liblttd.h

   1 /*
   2  * liblttd header file
   3  *
   4  * Copyright 2005-2010 -
   5  *               Mathieu Desnoyers <mathieu.desnoyers@polymtl.ca>
   6  * Copyright 2010-
   7  *               Oumarou Dicko <oumarou.dicko@polymtl.ca>
   8  *               Michael Sills-Lavoie <michael.sills-lavoie@polymtl.ca>
   9  *
  10  * This library is free software; you can redistribute it and/or
  11  * modify it under the terms of the GNU Lesser General Public
  12  * License as published by the Free Software Foundation; either
  13  * version 2.1 of the License, or (at your option) any later version.
  14  *
  15  * This library is distributed in the hope that it will be useful,
  16  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  17  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  18  * Lesser General Public License for more details.
  19  *
  20  * You should have received a copy of the GNU Lesser General Public
  21  * License along with this library; if not, write to the Free Software
  22  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
  23  */
  24
  25 #ifndef _LIBLTTD_H
  26 #define _LIBLTTD_H
  27
  28 #include <pthread.h>
  29 #include <dirent.h>
  30
  31 /**
  32  * struct fd_pair - Contains the data associated with the channel file
  33  * descriptor. The lib user can use user_data to store the data associated to
  34  * the specified channel. The lib user can read but MUST NOT change the other
  35  * attributes.
  36  * @channel: channel file descriptor
  37  * @n_sb: the number of subbuffer for this channel
  38  * @max_sb_size: the subbuffer size for this channel
  39  * @mmap: Not used anymore.
  40  * @mutex: a mutex for internal library usage
  41  * @user_data: library user data
  42  */
  43 struct fd_pair {
  44         int channel;
  45         unsigned int n_sb;
  46         unsigned int max_sb_size;
  47         void *mmap;
  48         pthread_mutex_t mutex;
  49         void *user_data;
  50 };
  51
  52 struct channel_trace_fd {
  53         struct fd_pair *pair;
  54         int num_pairs;
  55 };
  56
  57 struct inotify_watch {
  58         int wd;
  59         char path_channel[PATH_MAX];
  60         char *base_path_channel;
  61 };
  62
  63 struct inotify_watch_array {
  64         struct inotify_watch *elem;
  65         int num;
  66 };
  67
  68 struct liblttd_callbacks;
  69
  70 /**
  71  * struct liblttd_instance - Contains the data associated with a trace instance.
  72  * The lib user can read but MUST NOT change any attributes but callbacks.
  73  * @callbacks: Contains the necessary callbacks for a tracing session.
  74  */
  75 struct liblttd_instance {
  76         struct liblttd_callbacks *callbacks;
  77
  78         int inotify_fd;
  79         struct channel_trace_fd fd_pairs;
  80         struct inotify_watch_array inotify_watch_array;
  81
  82         /* protects fd_pairs and inotify_watch_array */
  83         pthread_rwlock_t fd_pairs_lock;
  84
  85         char channel_name[PATH_MAX];
  86         unsigned long num_threads;
  87         int quit_program;
  88         int dump_flight_only;
  89         int dump_normal_only;
  90         int verbose_mode;
  91 };
  92
  93 /**
  94 * struct liblttd_callbacks - Contains the necessary callbacks for a tracing
  95 * session. The user can set the unnecessary functions to NULL if he does not
  96 * need them.
  97 */
  98 struct liblttd_callbacks {
  99         /**
 100          * on_open_channel - Is called after a channel file is open.
 101          *
 102          * @data: pointer to the callbacks structure that has been passed to
 103          *        the lib.
 104          * @pair: structure that contains the data associated with the
 105          *        channel file descriptor. The library user can use user_data to
 106          *        store the data associated to the specified channel.
 107          * @relative_channel_path:
 108          *        represents a relative path to the channel file. This path is
 109          *        relative to the root folder of the trace channels.
 110          *
 111          * Returns 0 if the callback succeeds else not 0.
 112          */
 113         int (*on_open_channel)(struct liblttd_callbacks *data,
 114                                struct fd_pair *pair,
 115                                char *relative_channel_path);
 116
 117         /**
 118          * on_close_channel - Is called after a channel file is closed.
 119          *
 120          * @data: pointer to the callbacks structure that has been passed to the
 121          *        lib.
 122          * @pair: structure that contains the data associated with the channel
 123          *        file descriptor. The lib user should clean user_data at this
 124          *        time.
 125          *
 126          * Returns 0 if the callback succeeds else not 0.
 127          *
 128          * After a channel file has been closed, it will never be read again.
 129          */
 130         int (*on_close_channel)(struct liblttd_callbacks *data,
 131                                 struct fd_pair *pair);
 132
 133         /**
 134          * on_new_channels_folder - Is called when the library enter in a new
 135          * subfolder while it is scanning the trace channel tree. It can be used
 136          * to create the output file structure of the trace.
 137          *
 138          * @data: pointer to the callbacks structure that has been passed to the
 139          *        library.
 140          * @relative_folder_path:
 141          *        represents a relative path to the channel folder. This path is
 142          *        relative to the root folder of the trace channels.
 143          *
 144          * Returns 0 if the callback succeeds else not 0.
 145          */
 146         int (*on_new_channels_folder)(struct liblttd_callbacks *data,
 147                                       char *relative_folder_path);
 148
 149         /**
 150          * on_read_subbuffer - Is called after a subbuffer is a reserved.
 151          *
 152          * @data: pointer to the callbacks structure that has been passed to the
 153          *        library.
 154          * @pair: structure that contains the data associated with the channel
 155          *        file descriptor.
 156          * @len:  represents the length the data that has to be read.
 157          *
 158          * Returns 0 if the callback succeeds else not 0.
 159          *
 160          * It has to be thread safe, because it is called by many threads.
 161          */
 162         int (*on_read_subbuffer)(struct liblttd_callbacks *data,
 163                                 struct fd_pair *pair, unsigned int len);
 164
 165         /**
 166          * on_trace_en - Is called at the very end of the tracing session. At
 167          * this time, all the channels have been closed and the threads have
 168          * been destroyed.
 169          *
 170          * @instance: pointer to the instance structure that has been passed to
 171          *            the library.
 172          *
 173          * Returns 0 if the callback succeeds else not 0.
 174          *
 175          * After this callback is called, no other callback will be called
 176          * again and the tracing instance will be deleted automatically by
 177          * liblttd. After this call, the user must not use the liblttd instance.
 178          */
 179         int (*on_trace_end)(struct liblttd_instance *instance);
 180
 181         /**
 182          * on_new_thread - Is called after a new thread has been created.
 183          *
 184          * @data: pointer to the callbacks structure that has been passed to the
 185          *        lib.
 186          * @thread_num: represents the id of the thread.
 187          *
 188          * Returns 0 if the callback succeeds else not 0.
 189          *
 190          * It has to be thread safe, because it is called by many threads.
 191          */
 192         int (*on_new_thread)(struct liblttd_callbacks *data,
 193                              unsigned long thread_num);
 194
 195         /**
 196          * on_close_thread - Is called just before a thread is destroyed.
 197          *
 198          * @data: pointer to the callbacks structure that has been passed to the
 199          *        library.
 200          * @thread_num: represents the number of the thread.
 201          *
 202          * Returns 0 if the callback succeeds else not 0.
 203          *
 204          * It has to be thread safe, because it is called by many threads.
 205          */
 206         int (*on_close_thread)(struct liblttd_callbacks *data,
 207                                unsigned long thread_num);
 208
 209         /**
 210          * The library's data.
 211          */
 212         void *user_data;
 213 };
 214
 215 /**
 216  * liblttd_new_instance - Is called to create a new tracing session.
 217  *
 218  * @callbacks:    Pointer to a callbacks structure that contain the user
 219  *                callbacks and data.
 220  * @channel_path: This argument is a path to the root folder of the trace's
 221  *                channels.
 222  * @n_threads:    This argument represents the number of threads that will be
 223  *                used by the library.
 224  * @flight_only:  If this argument to set to 1, only the channel that are in
 225  *                flight recorder mode will be recorded.
 226  * @normal_only:  If this argument to set to 1, only the channel that are in
 227  *                normal mode will be recorded.
 228  * @verbose:      If this argument to set to 1, more informations will be
 229  *                printed.
 230  *
 231  * Returns the instance if the function succeeds else NULL.
 232  */
 233 struct liblttd_instance *
 234 liblttd_new_instance(struct liblttd_callbacks *callbacks, char *channel_path,
 235                      unsigned long n_threads, int flight_only, int normal_only,
 236                      int verbose);
 237
 238 /**
 239  * liblttd_start - Is called to start a new tracing session.
 240  *
 241  * @instance: The tracing session instance that needs to be started.
 242  *
 243  * Returns 0 if the function succeeds.
 244  *
 245  * This is a blocking function. The caller will be blocked on it until the
 246  * tracing session is stopped by the user using liblttd_stop_instance or until
 247  * the trace is stopped by LTTng directly.
 248  */
 249 int liblttd_start_instance(struct liblttd_instance *instance);
 250
 251 /**
 252  * liblttd_stop - Is called to stop a tracing session.
 253  *
 254  * @instance: The tracing session instance that needs to be stoped.
 255  *
 256  * Returns 0 if the function succeeds.
 257  *
 258  * This function returns immediately, it only tells liblttd to stop the
 259  * instance. The on_trace_end callback will be called when the tracing session
 260  * will really be stopped (after every thread has finished using it). The
 261  * instance is deleted automatically by liblttd after on_trace_end is called.
 262  */
 263 int liblttd_stop_instance(struct liblttd_instance *instance);
 264
 265 #endif /*_LIBLTTD_H */