Commit | Line | Data |
---|---|---|
008e2515 MSL |
1 | /* liblttd header file |
2 | * | |
3 | * Copyright 2010- | |
4 | * Oumarou Dicko <oumarou.dicko@polymtl.ca> | |
5 | * Michael Sills-Lavoie <michael.sills-lavoie@polymtl.ca> | |
6 | * | |
7 | * | |
8 | * This program is free software; you can redistribute it and/or modify | |
9 | * it under the terms of the GNU General Public License as published by | |
10 | * the Free Software Foundation; either version 2 of the License, or | |
11 | * (at your option) any later version. | |
12 | * | |
13 | * This program is distributed in the hope that it will be useful, | |
14 | * but WITHOUT ANY WARRANTY; without even the implied warranty of | |
15 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | |
16 | * GNU General Public License for more details. | |
17 | * | |
18 | */ | |
19 | ||
20 | #ifndef _LIBLTTD_H | |
21 | #define _LIBLTTD_H | |
22 | ||
23 | #include <pthread.h> | |
24 | ||
25 | /** | |
26 | * This structure contains the data associated with the channel file descriptor. | |
27 | * The lib user can use user_data to store the data associated to the specified | |
28 | * channel. The lib user can read but MUST NOT change the other attributes. | |
29 | */ | |
30 | struct fd_pair { | |
31 | /** | |
32 | * This is the channel file descriptor. | |
33 | */ | |
34 | int channel; | |
35 | ||
36 | /** | |
37 | * This is the number of subbuffer for this channel. | |
38 | */ | |
39 | unsigned int n_sb; | |
40 | ||
41 | /** | |
42 | * This is the subbuffer size for this channel. | |
43 | */ | |
44 | unsigned int max_sb_size; | |
45 | ||
46 | /** | |
47 | * Not used anymore. | |
48 | */ | |
49 | void *mmap; | |
50 | ||
51 | /** | |
52 | * This is a mutex for internal library usage. | |
53 | */ | |
54 | pthread_mutex_t mutex; | |
55 | ||
56 | /** | |
57 | * Library user data. | |
58 | */ | |
59 | void *user_data; | |
60 | }; | |
61 | ||
62 | /** | |
63 | * This structure contains the necessary callbacks for a tracing session. The | |
64 | * user can set the unnecessary functions to NULL if he does not need them. | |
65 | */ | |
66 | struct liblttd_callbacks { | |
67 | /** | |
68 | * This callback is called after a channel file is open. | |
69 | * | |
70 | * @args data This argument is a pointeur to the callbacks struct that | |
71 | * has been passed to the lib. | |
72 | * @args pair This structure contains the data associated with the | |
73 | * channel file descriptor. The lib user can use user_data to | |
74 | * store the data associated to the specified channel. | |
75 | * @args relative_channel_path This argument represents a relative path | |
76 | * to the channel file. This path is relative to the root | |
77 | * folder of the trace channels. | |
78 | * | |
79 | * @return Should return 0 if the callback succeeds else not 0. | |
80 | */ | |
81 | int(*on_open_channel)(struct liblttd_callbacks *data, | |
82 | struct fd_pair *pair, char *relative_channel_path); | |
83 | ||
84 | /** | |
85 | * This callback is called after a channel file is closed. | |
86 | * | |
87 | * @remarks After a channel file has been closed, it will never be read | |
88 | * again. | |
89 | * | |
90 | * @args data This argument is a pointeur to the callbacks struct that | |
91 | * has been passed to the lib. | |
92 | * @args pair This structure contains the data associated with the | |
93 | * channel file descriptor. The lib user should clean | |
94 | * user_data at this time. | |
95 | * | |
96 | * @return Should return 0 if the callback succeeds else not 0. | |
97 | */ | |
98 | int(*on_close_channel)(struct liblttd_callbacks *data, | |
99 | struct fd_pair *pair); | |
100 | ||
101 | ||
102 | /** | |
103 | * This callback is called when the library enter in a new subfolder | |
104 | * while it is scanning the trace channel tree. It can be used to create | |
105 | * the output file structure of the trace. | |
106 | * | |
107 | * @args data This argument is a pointeur to the callbacks struct that | |
108 | * has been passed to the lib. | |
109 | * @args relative_folder_path This argument represents a relative path | |
110 | * to the channel folder. This path is relative to the root | |
111 | * folder of the trace channels. | |
112 | * | |
113 | * @return Should return 0 if the callback succeeds else not 0. | |
114 | */ | |
115 | int(*on_new_channels_folder)(struct liblttd_callbacks *data, | |
116 | char *relative_folder_path); | |
117 | ||
118 | /** | |
119 | * This callback is called after a subbuffer is a reserved. | |
120 | * | |
121 | * @attention It has to be thread safe, it'll be called by many threads. | |
122 | * | |
123 | * @args data This argument is a pointeur to the callbacks struct that | |
124 | * has been passed to the lib. | |
125 | * @args pair This structure contains the data associated with the | |
126 | * channel file descriptor. The lib user should clean | |
127 | * user_data at this time. | |
128 | * @args len This argument represents the length the data that has to be | |
129 | * read. | |
130 | * | |
131 | * @return Should return 0 if the callback succeeds else not 0. | |
132 | */ | |
133 | int(*on_read_subbuffer)(struct liblttd_callbacks *data, | |
134 | struct fd_pair *pair, unsigned int len); | |
135 | ||
136 | /** | |
137 | * This callback is called at the very end of the tracing session. At | |
138 | * this time, all the channels have been closed and the threads have been | |
139 | * destroyed. | |
140 | * | |
141 | * @remarks After this callback is called, no other callback will be | |
142 | * called again. | |
143 | * | |
144 | * @attention It has to be thread safe, it'll be called by many threads. | |
145 | * | |
146 | * @args data This argument is a pointeur to the callbacks struct that | |
147 | * has been passed to the lib. | |
148 | * | |
149 | * @return Should return 0 if the callback succeeds else not 0. | |
150 | */ | |
151 | int(*on_trace_end)(struct liblttd_callbacks *data); | |
152 | ||
153 | /** | |
154 | * This callback is called after a new thread has been created. | |
155 | * | |
156 | * @attention It has to be thread safe, it'll be called by many threads. | |
157 | * | |
158 | * @args data This argument is a pointeur to the callbacks struct that | |
159 | * has been passed to the lib. | |
160 | * @args thread_num This argument represents the id of the thread. | |
161 | * | |
162 | * @return Should return 0 if the callback succeeds else not 0. | |
163 | */ | |
164 | int(*on_new_thread)(struct liblttd_callbacks *data, | |
165 | unsigned long thread_num); | |
166 | ||
167 | /** | |
168 | * This callback is called just before a thread is destroyed. | |
169 | * | |
170 | * @attention It has to be thread safe, it'll be called by many threads. | |
171 | * | |
172 | * @args data This argument is a pointeur to the callbacks struct that | |
173 | * has been passed to the lib. | |
174 | * @args thread_num This argument represents the number of the thread. | |
175 | * | |
176 | * @return Should return 0 if the callback succeeds else not 0. | |
177 | */ | |
178 | int(*on_close_thread)(struct liblttd_callbacks *data, | |
179 | unsigned long thread_num); | |
180 | ||
181 | /** | |
182 | * This is where the user can put the library's data. | |
183 | */ | |
184 | void *user_data; | |
185 | }; | |
186 | ||
187 | /** | |
188 | * This function is called to start a new tracing session. | |
189 | * | |
190 | * @attention It has to be thread safe, it'll be called by many threads. | |
191 | * | |
192 | * @args channel_path This argument is a path to the root folder of the trace's | |
193 | * channels. | |
194 | * @args n_threads This argument represents the number of threads that will be | |
195 | * used by the library. | |
196 | * @args flight_only If this argument to set to 1, only the channel that are in | |
197 | * flight recorder mode will be recorded. | |
198 | * @args normal_only If this argument to set to 1, only the channel that are in | |
199 | * normal mode will be recorded. | |
200 | * @args verbose If this argument to set to 1, more informations will be printed. | |
201 | * @args user_data This argument is a pointeur to the callbacks struct that | |
202 | * contains the user's functions. | |
203 | * | |
204 | * @return Return 0 if the function succeeds else not 0. | |
205 | */ | |
206 | int liblttd_start(char *channel_path, unsigned long n_threads, | |
207 | int flight_only, int normal_only, int verbose, | |
208 | struct liblttd_callbacks *user_data); | |
209 | ||
210 | /** | |
211 | * This function is called to stop a tracing session. | |
212 | * | |
213 | * @return Return 0 if the function succeeds. | |
214 | */ | |
215 | int liblttd_stop(); | |
216 | ||
217 | #endif /*_LIBLTTD_H */ | |
218 |