include/ust/ustconsumer.h

   1 /*
   2  * libustconsumer 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  *               Alexis Halle <alexis.halle@polymtl.ca>
  10  *
  11  * This library is free software; you can redistribute it and/or
  12  * modify it under the terms of the GNU Lesser General Public
  13  * License as published by the Free Software Foundation; either
  14  * version 2.1 of the License, or (at your option) any later version.
  15  *
  16  * This library is distributed in the hope that it will be useful,
  17  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  18  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  19  * Lesser General Public License for more details.
  20  *
  21  * You should have received a copy of the GNU Lesser General Public
  22  * License along with this library; if not, write to the Free Software
  23  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
  24  */
  25
  26 #ifndef _USTCONSUMER_H
  27 #define _USTCONSUMER_H
  28
  29 #include <pthread.h>
  30 #include <dirent.h>
  31 #include <unistd.h>
  32 #include <urcu/list.h>
  33
  34 #define USTCONSUMER_DEFAULT_TRACE_PATH "/tmp/usttrace"
  35
  36 struct ustcomm_sock;
  37
  38 struct buffer_info {
  39         char *name;
  40         char *trace;
  41         char *channel;
  42         int channel_cpu;
  43
  44         pid_t pid;
  45         int app_sock;
  46         /* The pipe file descriptor */
  47         int pipe_fd;
  48
  49         int shmid;
  50         int bufstruct_shmid;
  51
  52         /* the buffer memory */
  53         void *mem;
  54         /* buffer size */
  55         int memlen;
  56         /* number of subbuffers in buffer */
  57         int n_subbufs;
  58         /* size of each subbuffer */
  59         int subbuf_size;
  60         /* subbuf size count order */
  61         int subbuf_size_order;
  62         /* alloc size of all subbuf */
  63         int alloc_size;
  64
  65         /* the buffer information struct */
  66         void *bufstruct_mem;
  67
  68         long consumed_old;
  69
  70         int64_t pidunique;
  71
  72         void *user_data;
  73 };
  74
  75 struct ustconsumer_callbacks;
  76
  77 /**
  78  * struct ustconsumer_instance - Contains the data associated with a trace instance.
  79  * The lib user can read but MUST NOT change any attributes but callbacks.
  80  * @callbacks: Contains the necessary callbacks for a tracing session.
  81  */
  82 struct ustconsumer_instance {
  83         struct ustconsumer_callbacks *callbacks;
  84         int quit_program;
  85         int is_init;
  86         struct cds_list_head connections;
  87         int epoll_fd;
  88         struct ustcomm_sock *listen_sock;
  89         char *sock_path;
  90         pthread_mutex_t mutex;
  91         int active_buffers;
  92         int active_threads;
  93 };
  94
  95 /**
  96 * struct ustconsumer_callbacks - Contains the necessary callbacks for a tracing
  97 * session. The user can set the unnecessary functions to NULL if he does not
  98 * need them.
  99 */
 100 struct ustconsumer_callbacks {
 101         /**
 102          * on_open_buffer - Is called after a buffer is attached to process memory
 103          *
 104          * @data: pointer to the callbacks structure that has been passed to the
 105          *        library.
 106          * @buf: structure that contains the data associated with the buffer
 107          *
 108          * Returns 0 if the callback succeeds else not 0.
 109          *
 110          * It has to be thread safe, because it is called by many threads.
 111          */
 112         int (*on_open_buffer)(struct ustconsumer_callbacks *data,
 113                                 struct buffer_info *buf);
 114
 115         /**
 116          * on_close_buffer - Is called after a buffer is detached from process memory
 117          *
 118          * @data: pointer to the callbacks structure that has been passed to the
 119          *        library.
 120          * @buf: structure that contains the data associated with the buffer
 121          *
 122          * Returns 0 if the callback succeeds else not 0.
 123          *
 124          * It has to be thread safe, because it is called by many threads.
 125          */
 126         int (*on_close_buffer)(struct ustconsumer_callbacks *data,
 127                                 struct buffer_info *buf);
 128
 129         /**
 130          * on_read_subbuffer - Is called after a subbuffer is a reserved.
 131          *
 132          * @data: pointer to the callbacks structure that has been passed to the
 133          *        library.
 134          * @buf: structure that contains the data associated with the buffer
 135          *
 136          * Returns 0 if the callback succeeds else not 0.
 137          *
 138          * It has to be thread safe, because it is called by many threads.
 139          */
 140         int (*on_read_subbuffer)(struct ustconsumer_callbacks *data,
 141                                 struct buffer_info *buf);
 142
 143         /**
 144          * on_read_partial_subbuffer - Is called when an incomplete subbuffer
 145          *                             is being salvaged from an app crash
 146          *
 147          * @data: pointer to the callbacks structure that has been passed to the
 148          *        library.
 149          * @buf: structure that contains the data associated with the buffer
 150          * @subbuf_index: index of the subbuffer to read in the buffer
 151          * @valid_length: number of bytes considered safe to read
 152          *
 153          * Returns 0 if the callback succeeds else not 0.
 154          *
 155          * It has to be thread safe, because it is called by many threads.
 156          */
 157         int (*on_read_partial_subbuffer)(struct ustconsumer_callbacks *data,
 158                                         struct buffer_info *buf,
 159                                         long subbuf_index,
 160                                         unsigned long valid_length);
 161
 162         /**
 163          * on_put_error - Is called when a put error has occured and the last
 164          *                subbuffer read is no longer safe to keep
 165          *
 166          * @data: pointer to the callbacks structure that has been passed to the
 167          *        library.
 168          * @buf: structure that contains the data associated with the buffer
 169          *
 170          * Returns 0 if the callback succeeds else not 0.
 171          *
 172          * It has to be thread safe, because it is called by many threads.
 173          */
 174         int (*on_put_error)(struct ustconsumer_callbacks *data,
 175                                 struct buffer_info *buf);
 176
 177         /**
 178          * on_new_thread - Is called when a new thread is created
 179          *
 180          * @data: pointer to the callbacks structure that has been passed to the
 181          *        library.
 182          *
 183          * Returns 0 if the callback succeeds else not 0.
 184          *
 185          * It has to be thread safe, because it is called by many threads.
 186          */
 187         int (*on_new_thread)(struct ustconsumer_callbacks *data);
 188
 189         /**
 190          * on_close_thread - Is called just before a thread is destroyed
 191          *
 192          * @data: pointer to the callbacks structure that has been passed to the
 193          *        library.
 194          *
 195          * Returns 0 if the callback succeeds else not 0.
 196          *
 197          * It has to be thread safe, because it is called by many threads.
 198          */
 199         int (*on_close_thread)(struct ustconsumer_callbacks *data);
 200
 201         /**
 202          * on_trace_end - Is called at the very end of the tracing session. At
 203          * this time, everything has been closed and the threads have
 204          * been destroyed.
 205          *
 206          * @instance: pointer to the instance structure that has been passed to
 207          *            the library.
 208          *
 209          * Returns 0 if the callback succeeds else not 0.
 210          *
 211          * After this callback is called, no other callback will be called
 212          * again and the tracing instance will be deleted automatically by
 213          * libustconsumer. After this call, the user must not use the libustconsumer instance.
 214          */
 215         int (*on_trace_end)(struct ustconsumer_instance *instance);
 216
 217         /**
 218          * The library's data.
 219          */
 220         void *user_data;
 221 };
 222
 223 /**
 224  * ustconsumer_new_instance - Is called to create a new tracing session.
 225  *
 226  * @callbacks:    Pointer to a callbacks structure that contain the user
 227  *                callbacks and data.
 228  * @sock_path:    Path to the socket used for communication with the traced app
 229  *
 230  * Returns the instance if the function succeeds else NULL.
 231  */
 232 struct ustconsumer_instance *
 233 ustconsumer_new_instance(
 234         struct ustconsumer_callbacks *callbacks, char *sock_path);
 235
 236 /**
 237  * ustconsumer_delete_instance - Is called to free a ustconsumer_instance struct
 238  *
 239  * @instance: The tracing session instance that needs to be freed.
 240  *
 241  * This function should only be called if the instance has not been started,
 242  * as it will automatically be called at the end of ustconsumer_start_instance.
 243  */
 244 void ustconsumer_delete_instance(struct ustconsumer_instance *instance);
 245
 246 /**
 247  * ustconsumer_init_instance - Is called to initiliaze a new tracing session
 248  *
 249  * @instance: The tracing session instance that needs to be started.
 250  *
 251  * Returns 0 if the function succeeds.
 252  *
 253  * This function must be called between ustconsumer_new_instance and
 254  * ustconsumer_start_instance. It sets up the communication between the library
 255  * and the tracing application.
 256  */
 257 int ustconsumer_init_instance(struct ustconsumer_instance *instance);
 258
 259 /**
 260  * ustconsumer_start_instance - Is called to start a new tracing session.
 261  *
 262  * @instance: The tracing session instance that needs to be started.
 263  *
 264  * Returns 0 if the function succeeds.
 265  *
 266  * This is a blocking function. The caller will be blocked on it until the
 267  * tracing session is stopped by the user using ustconsumer_stop_instance or until
 268  * the traced application terminates
 269  */
 270 int ustconsumer_start_instance(struct ustconsumer_instance *instance);
 271
 272 /**
 273  * ustconsumer_stop_instance - Is called to stop a tracing session.
 274  *
 275  * @instance: The tracing session instance that needs to be stoped.
 276  * @send_msg: If true, a message will be sent to the listening thread through
 277  *            the daemon socket to force it to return from the poll syscall
 278  *            and realize that it must close. This is not necessary if the
 279  *            instance is being stopped as part of an interrupt handler, as
 280  *            the interrupt itself will cause poll to return.
 281  *
 282  * Returns 0 if the function succeeds.
 283  *
 284  * This function returns immediately, it only tells libustconsumer to stop the
 285  * instance. The on_trace_end callback will be called when the tracing session
 286  * will really be stopped. The instance is deleted automatically by libustconsumer
 287  * after on_trace_end is called.
 288  */
 289 int ustconsumer_stop_instance(struct ustconsumer_instance *instance, int send_msg);
 290
 291 #endif /* _USTCONSUMER_H */
 292