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