4 * Copyright 2005-2010 -
5 * Mathieu Desnoyers <mathieu.desnoyers@polymtl.ca>
7 * Oumarou Dicko <oumarou.dicko@polymtl.ca>
8 * Michael Sills-Lavoie <michael.sills-lavoie@polymtl.ca>
9 * Alexis Halle <alexis.halle@polymtl.ca>
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.
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.
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
33 #define USTD_DEFAULT_TRACE_PATH "/tmp/usttrace"
38 struct ustcomm_connection conn
;
43 /* the buffer memory */
47 /* number of subbuffers in buffer */
49 /* size of each subbuffer */
52 /* the buffer information struct */
62 struct libustd_callbacks
;
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.
69 struct libustd_instance
{
70 struct libustd_callbacks
*callbacks
;
73 struct ustcomm_ustd comm
;
75 pthread_mutex_t mutex
;
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
84 struct libustd_callbacks
{
86 * on_open_buffer - Is called after a buffer is attached to process memory
88 * @data: pointer to the callbacks structure that has been passed to the
90 * @buf: structure that contains the data associated with the buffer
92 * Returns 0 if the callback succeeds else not 0.
94 * It has to be thread safe, because it is called by many threads.
96 int (*on_open_buffer
)(struct libustd_callbacks
*data
,
97 struct buffer_info
*buf
);
100 * on_close_buffer - Is called after a buffer is detached from process memory
102 * @data: pointer to the callbacks structure that has been passed to the
104 * @buf: structure that contains the data associated with the buffer
106 * Returns 0 if the callback succeeds else not 0.
108 * It has to be thread safe, because it is called by many threads.
110 int (*on_close_buffer
)(struct libustd_callbacks
*data
,
111 struct buffer_info
*buf
);
114 * on_read_subbuffer - Is called after a subbuffer is a reserved.
116 * @data: pointer to the callbacks structure that has been passed to the
118 * @buf: structure that contains the data associated with the buffer
120 * Returns 0 if the callback succeeds else not 0.
122 * It has to be thread safe, because it is called by many threads.
124 int (*on_read_subbuffer
)(struct libustd_callbacks
*data
,
125 struct buffer_info
*buf
);
128 * on_read_partial_subbuffer - Is called when an incomplete subbuffer
129 * is being salvaged from an app crash
131 * @data: pointer to the callbacks structure that has been passed to the
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
137 * Returns 0 if the callback succeeds else not 0.
139 * It has to be thread safe, because it is called by many threads.
141 int (*on_read_partial_subbuffer
)(struct libustd_callbacks
*data
,
142 struct buffer_info
*buf
,
144 unsigned long valid_length
);
147 * on_put_error - Is called when a put error has occured and the last
148 * subbuffer read is no longer safe to keep
150 * @data: pointer to the callbacks structure that has been passed to the
152 * @buf: structure that contains the data associated with the buffer
154 * Returns 0 if the callback succeeds else not 0.
156 * It has to be thread safe, because it is called by many threads.
158 int (*on_put_error
)(struct libustd_callbacks
*data
,
159 struct buffer_info
*buf
);
162 * on_new_thread - Is called when a new thread is created
164 * @data: pointer to the callbacks structure that has been passed to the
167 * Returns 0 if the callback succeeds else not 0.
169 * It has to be thread safe, because it is called by many threads.
171 int (*on_new_thread
)(struct libustd_callbacks
*data
);
174 * on_close_thread - Is called just before a thread is destroyed
176 * @data: pointer to the callbacks structure that has been passed to the
179 * Returns 0 if the callback succeeds else not 0.
181 * It has to be thread safe, because it is called by many threads.
183 int (*on_close_thread
)(struct libustd_callbacks
*data
);
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
190 * @instance: pointer to the instance structure that has been passed to
193 * Returns 0 if the callback succeeds else not 0.
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.
199 int (*on_trace_end
)(struct libustd_instance
*instance
);
202 * The library's data.
208 * libustd_new_instance - Is called to create a new tracing session.
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
214 * Returns the instance if the function succeeds else NULL.
216 struct libustd_instance
*
217 libustd_new_instance(
218 struct libustd_callbacks
*callbacks
, char *sock_path
);
221 * libustd_delete_instance - Is called to free a libustd_instance struct
223 * @instance: The tracing session instance that needs to be freed.
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.
228 void libustd_delete_instance(struct libustd_instance
*instance
);
231 * libustd_init_instance - Is called to initiliaze a new tracing session
233 * @instance: The tracing session instance that needs to be started.
235 * Returns 0 if the function succeeds.
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.
241 int libustd_init_instance(struct libustd_instance
*instance
);
244 * libustd_start_instance - Is called to start a new tracing session.
246 * @instance: The tracing session instance that needs to be started.
248 * Returns 0 if the function succeeds.
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
254 int libustd_start_instance(struct libustd_instance
*instance
);
257 * libustd_stop_instance - Is called to stop a tracing session.
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.
266 * Returns 0 if the function succeeds.
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.
273 int libustd_stop_instance(struct libustd_instance
*instance
, int send_msg
);
275 void finish_consuming_dead_subbuffer(struct libustd_callbacks
*callbacks
, struct buffer_info
*buf
);
276 size_t subbuffer_data_size(void *subbuf
);
278 #endif /* LIBUSTD_H */