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