2 * libustconsumer header file
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
26 #ifndef _USTCONSUMER_H
27 #define _USTCONSUMER_H
31 #include <ust/kcompat/kcompat.h>
32 #include <urcu/list.h>
34 #define USTCONSUMER_DEFAULT_TRACE_PATH "/tmp/usttrace"
46 /* The pipe file descriptor */
52 /* the buffer memory */
56 /* number of subbuffers in buffer */
58 /* size of each subbuffer */
60 /* subbuf size count order */
61 int subbuf_size_order
;
62 /* alloc size of all subbuf */
65 /* the buffer information struct */
75 struct ustconsumer_callbacks
;
78 * struct ustconsumer_instance - Contains the data associated with a trace instance.
79 * The lib user can read but MUST NOT change any attributes but callbacks.
80 * @callbacks: Contains the necessary callbacks for a tracing session.
82 struct ustconsumer_instance
{
83 struct ustconsumer_callbacks
*callbacks
;
86 struct cds_list_head connections
;
88 struct ustcomm_sock
*listen_sock
;
90 pthread_mutex_t mutex
;
95 * struct ustconsumer_callbacks - Contains the necessary callbacks for a tracing
96 * session. The user can set the unnecessary functions to NULL if he does not
99 struct ustconsumer_callbacks
{
101 * on_open_buffer - Is called after a buffer is attached to process memory
103 * @data: pointer to the callbacks structure that has been passed to the
105 * @buf: structure that contains the data associated with the buffer
107 * Returns 0 if the callback succeeds else not 0.
109 * It has to be thread safe, because it is called by many threads.
111 int (*on_open_buffer
)(struct ustconsumer_callbacks
*data
,
112 struct buffer_info
*buf
);
115 * on_close_buffer - Is called after a buffer is detached from process memory
117 * @data: pointer to the callbacks structure that has been passed to the
119 * @buf: structure that contains the data associated with the buffer
121 * Returns 0 if the callback succeeds else not 0.
123 * It has to be thread safe, because it is called by many threads.
125 int (*on_close_buffer
)(struct ustconsumer_callbacks
*data
,
126 struct buffer_info
*buf
);
129 * on_read_subbuffer - Is called after a subbuffer is a reserved.
131 * @data: pointer to the callbacks structure that has been passed to the
133 * @buf: structure that contains the data associated with the buffer
135 * Returns 0 if the callback succeeds else not 0.
137 * It has to be thread safe, because it is called by many threads.
139 int (*on_read_subbuffer
)(struct ustconsumer_callbacks
*data
,
140 struct buffer_info
*buf
);
143 * on_read_partial_subbuffer - Is called when an incomplete subbuffer
144 * is being salvaged from an app crash
146 * @data: pointer to the callbacks structure that has been passed to the
148 * @buf: structure that contains the data associated with the buffer
149 * @subbuf_index: index of the subbuffer to read in the buffer
150 * @valid_length: number of bytes considered safe to read
152 * Returns 0 if the callback succeeds else not 0.
154 * It has to be thread safe, because it is called by many threads.
156 int (*on_read_partial_subbuffer
)(struct ustconsumer_callbacks
*data
,
157 struct buffer_info
*buf
,
159 unsigned long valid_length
);
162 * on_put_error - Is called when a put error has occured and the last
163 * subbuffer read is no longer safe to keep
165 * @data: pointer to the callbacks structure that has been passed to the
167 * @buf: structure that contains the data associated with the buffer
169 * Returns 0 if the callback succeeds else not 0.
171 * It has to be thread safe, because it is called by many threads.
173 int (*on_put_error
)(struct ustconsumer_callbacks
*data
,
174 struct buffer_info
*buf
);
177 * on_new_thread - Is called when a new thread is created
179 * @data: pointer to the callbacks structure that has been passed to the
182 * Returns 0 if the callback succeeds else not 0.
184 * It has to be thread safe, because it is called by many threads.
186 int (*on_new_thread
)(struct ustconsumer_callbacks
*data
);
189 * on_close_thread - Is called just before a thread is destroyed
191 * @data: pointer to the callbacks structure that has been passed to the
194 * Returns 0 if the callback succeeds else not 0.
196 * It has to be thread safe, because it is called by many threads.
198 int (*on_close_thread
)(struct ustconsumer_callbacks
*data
);
201 * on_trace_end - Is called at the very end of the tracing session. At
202 * this time, everything has been closed and the threads have
205 * @instance: pointer to the instance structure that has been passed to
208 * Returns 0 if the callback succeeds else not 0.
210 * After this callback is called, no other callback will be called
211 * again and the tracing instance will be deleted automatically by
212 * libustconsumer. After this call, the user must not use the libustconsumer instance.
214 int (*on_trace_end
)(struct ustconsumer_instance
*instance
);
217 * The library's data.
223 * ustconsumer_new_instance - Is called to create a new tracing session.
225 * @callbacks: Pointer to a callbacks structure that contain the user
226 * callbacks and data.
227 * @sock_path: Path to the socket used for communication with the traced app
229 * Returns the instance if the function succeeds else NULL.
231 struct ustconsumer_instance
*
232 ustconsumer_new_instance(
233 struct ustconsumer_callbacks
*callbacks
, char *sock_path
);
236 * ustconsumer_delete_instance - Is called to free a ustconsumer_instance struct
238 * @instance: The tracing session instance that needs to be freed.
240 * This function should only be called if the instance has not been started,
241 * as it will automatically be called at the end of ustconsumer_start_instance.
243 void ustconsumer_delete_instance(struct ustconsumer_instance
*instance
);
246 * ustconsumer_init_instance - Is called to initiliaze a new tracing session
248 * @instance: The tracing session instance that needs to be started.
250 * Returns 0 if the function succeeds.
252 * This function must be called between ustconsumer_new_instance and
253 * ustconsumer_start_instance. It sets up the communication between the library
254 * and the tracing application.
256 int ustconsumer_init_instance(struct ustconsumer_instance
*instance
);
259 * ustconsumer_start_instance - Is called to start a new tracing session.
261 * @instance: The tracing session instance that needs to be started.
263 * Returns 0 if the function succeeds.
265 * This is a blocking function. The caller will be blocked on it until the
266 * tracing session is stopped by the user using ustconsumer_stop_instance or until
267 * the traced application terminates
269 int ustconsumer_start_instance(struct ustconsumer_instance
*instance
);
272 * ustconsumer_stop_instance - Is called to stop a tracing session.
274 * @instance: The tracing session instance that needs to be stoped.
275 * @send_msg: If true, a message will be sent to the listening thread through
276 * the daemon socket to force it to return from the poll syscall
277 * and realize that it must close. This is not necessary if the
278 * instance is being stopped as part of an interrupt handler, as
279 * the interrupt itself will cause poll to return.
281 * Returns 0 if the function succeeds.
283 * This function returns immediately, it only tells libustconsumer to stop the
284 * instance. The on_trace_end callback will be called when the tracing session
285 * will really be stopped. The instance is deleted automatically by libustconsumer
286 * after on_trace_end is called.
288 int ustconsumer_stop_instance(struct ustconsumer_instance
*instance
, int send_msg
);
290 #endif /* _USTCONSUMER_H */