include/ust/ustd.h

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