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