Move enum bt_component_type to component.h
[babeltrace.git] / include / babeltrace / plugin / plugin-dev.h
... / ...
CommitLineData
1#ifndef BABELTRACE_PLUGIN_PLUGIN_DEV_H
2#define BABELTRACE_PLUGIN_PLUGIN_DEV_H
3
4/*
5 * BabelTrace - Babeltrace Plug-in Development API
6 *
7 * This is the header that you need to include for the development of
8 * a Babeltrace plug-in.
9 *
10 * Copyright 2015 Jérémie Galarneau <jeremie.galarneau@efficios.com>
11 * Copyright 2017 Philippe Proulx <pproulx@efficios.com>
12 *
13 * Author: Jérémie Galarneau <jeremie.galarneau@efficios.com>
14 *
15 * Permission is hereby granted, free of charge, to any person obtaining a copy
16 * of this software and associated documentation files (the "Software"), to deal
17 * in the Software without restriction, including without limitation the rights
18 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
19 * copies of the Software, and to permit persons to whom the Software is
20 * furnished to do so, subject to the following conditions:
21 *
22 * The above copyright notice and this permission notice shall be included in
23 * all copies or substantial portions of the Software.
24 *
25 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
26 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
27 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
28 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
29 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
30 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
31 * SOFTWARE.
32 */
33
34#include <stdint.h>
35#include <babeltrace/plugin/plugin.h>
36#include <babeltrace/component/component-class.h>
37
38#ifdef __cplusplus
39extern "C" {
40#endif
41
42/*
43 * Plugin interface's version, not synced with Babeltrace's version
44 * (internal use).
45 */
46#define __BT_PLUGIN_VERSION_MAJOR 1
47#define __BT_PLUGIN_VERSION_MINOR 0
48
49/* Plugin initialization function type */
50typedef enum bt_plugin_status (*bt_plugin_init_func)(
51 struct bt_plugin *plugin);
52
53/* Plugin exit function type */
54typedef enum bt_plugin_status (*bt_plugin_exit_func)(void);
55
56/*
57 * Function to call from a plugin's initialization function to add a
58 * component class to a plugin object.
59 */
60extern enum bt_plugin_status bt_plugin_add_component_class(
61 struct bt_plugin *plugin,
62 struct bt_component_class *component_class);
63
64/* Plugin descriptor: describes a single plugin (internal use) */
65struct __bt_plugin_descriptor {
66 /* Plugin's interface major version number */
67 uint32_t major;
68
69 /* Plugin's interface minor version number */
70 uint32_t minor;
71
72 /* Plugin's name */
73 const char *name;
74} __attribute__((packed));
75
76/* Type of a plugin attribute (internal use) */
77enum __bt_plugin_descriptor_attribute_type {
78 BT_PLUGIN_DESCRIPTOR_ATTRIBUTE_TYPE_INIT = 0,
79 BT_PLUGIN_DESCRIPTOR_ATTRIBUTE_TYPE_EXIT = 1,
80 BT_PLUGIN_DESCRIPTOR_ATTRIBUTE_TYPE_AUTHOR = 2,
81 BT_PLUGIN_DESCRIPTOR_ATTRIBUTE_TYPE_LICENSE = 3,
82 BT_PLUGIN_DESCRIPTOR_ATTRIBUTE_TYPE_DESCRIPTION = 4,
83};
84
85/* Plugin attribute (internal use) */
86struct __bt_plugin_descriptor_attribute {
87 /* Plugin descriptor to which to associate this attribute */
88 const struct __bt_plugin_descriptor *plugin_descriptor;
89
90 /* Attribute's type */
91 enum __bt_plugin_descriptor_attribute_type type;
92
93 /* Name of the attribute's type for debug purposes */
94 const char *type_name;
95
96 /* Attribute's value */
97 union {
98 /* BT_PLUGIN_DESCRIPTOR_ATTRIBUTE_TYPE_INIT */
99 bt_plugin_init_func init;
100
101 /* BT_PLUGIN_DESCRIPTOR_ATTRIBUTE_TYPE_EXIT */
102 bt_plugin_exit_func exit;
103
104 /* BT_PLUGIN_DESCRIPTOR_ATTRIBUTE_TYPE_AUTHOR */
105 const char *author;
106
107 /* BT_PLUGIN_DESCRIPTOR_ATTRIBUTE_TYPE_LICENSE */
108 const char *license;
109
110 /* BT_PLUGIN_DESCRIPTOR_ATTRIBUTE_TYPE_DESCRIPTION */
111 const char *description;
112 } value;
113} __attribute__((packed));
114
115/* Component class descriptor (internal use) */
116struct __bt_plugin_component_class_descriptor {
117 /*
118 * Plugin descriptor to which to associate this component
119 * class descriptor.
120 */
121 const struct __bt_plugin_descriptor *plugin_descriptor;
122
123 /* Component type */
124 enum bt_component_type type;
125
126 /* Component class name */
127 const char *name;
128
129 /* Component initialization function */
130 bt_component_init_cb init_cb;
131} __attribute__((packed));
132
133/* Type of a component class attribute (internal use) */
134enum __bt_plugin_component_class_descriptor_attribute_type {
135 BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE_TYPE_DESCRIPTION = 0,
136};
137
138/* Component class attribute (internal use) */
139struct __bt_plugin_component_class_descriptor_attribute {
140 /*
141 * Component class plugin attribute to which to associate this
142 * component class attribute.
143 */
144 const struct __bt_plugin_component_class_descriptor *comp_class_descriptor;
145
146 /* Attribute's type */
147 enum __bt_plugin_component_class_descriptor_attribute_type type;
148
149 /* Name of the attribute's type for debug purposes */
150 const char *type_name;
151
152 /* Attribute's value */
153 union {
154 /* BT_PLUGIN_DESCRIPTOR_ATTRIBUTE_TYPE_DESCRIPTION */
155 const char *description;
156 } value;
157} __attribute__((packed));
158
159/*
160 * Variable attributes for a plugin descriptor pointer to be added to
161 * the plugin descriptor section (internal use).
162 */
163#define __BT_PLUGIN_DESCRIPTOR_ATTRS \
164 __attribute__((section("__bt_plugin_descriptors"), used))
165
166/*
167 * Variable attributes for a plugin attribute pointer to be added to
168 * the plugin attribute section (internal use).
169 */
170#define __BT_PLUGIN_DESCRIPTOR_ATTRIBUTES_ATTRS \
171 __attribute__((section("__bt_plugin_descriptor_attributes"), used))
172
173/*
174 * Variable attributes for a component class descriptor pointer to be
175 * added to the component class descriptor section (internal use).
176 */
177#define __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRS \
178 __attribute__((section("__bt_plugin_component_class_descriptors"), used))
179
180/*
181 * Variable attributes for a component class descriptor attribute
182 * pointer to be added to the component class descriptor attribute
183 * section (internal use).
184 */
185#define __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTES_ATTRS \
186 __attribute__((section("__bt_plugin_component_class_descriptor_attributes"), used))
187
188/*
189 * Declares a plugin descriptor pointer variable with a custom ID.
190 *
191 * _id: ID (any valid C identifier except `auto`).
192 */
193#define BT_PLUGIN_DECLARE(_id) extern struct __bt_plugin_descriptor __bt_plugin_descriptor_##_id
194
195/*
196 * Defines a plugin descriptor with a custom ID.
197 *
198 * _id: ID (any valid C identifier except `auto`).
199 * _name: Plugin's name (C string).
200 */
201#define BT_PLUGIN_WITH_ID(_id, _name) \
202 struct __bt_plugin_descriptor __bt_plugin_descriptor_##_id = { \
203 .major = __BT_PLUGIN_VERSION_MAJOR, \
204 .minor = __BT_PLUGIN_VERSION_MINOR, \
205 .name = _name, \
206 }; \
207 static struct __bt_plugin_descriptor const * const __bt_plugin_descriptor_##_id##_ptr __BT_PLUGIN_DESCRIPTOR_ATTRS = &__bt_plugin_descriptor_##_id; \
208 extern struct __bt_plugin_descriptor const *__start___bt_plugin_descriptors; \
209 extern struct __bt_plugin_descriptor const *__stop___bt_plugin_descriptors
210
211/*
212 * Defines a plugin attribute (generic, internal use).
213 *
214 * _attr_name: Name of the attribute (C identifier).
215 * _attr_type: Type of the attribute (enum __bt_plugin_descriptor_attribute_type).
216 * _id: Plugin descriptor ID (C identifier).
217 * _x: Value.
218 */
219#define __BT_PLUGIN_DESCRIPTOR_ATTRIBUTE(_attr_name, _attr_type, _id, _x) \
220 static struct __bt_plugin_descriptor_attribute __bt_plugin_descriptor_attribute_##_id##_##_attr_name = { \
221 .plugin_descriptor = &__bt_plugin_descriptor_##_id, \
222 .type = _attr_type, \
223 .type_name = #_attr_name, \
224 .value._attr_name = _x, \
225 }; \
226 static struct __bt_plugin_descriptor_attribute const * const __bt_plugin_descriptor_attribute_##_id##_##_attr_name##_ptr __BT_PLUGIN_DESCRIPTOR_ATTRIBUTES_ATTRS = &__bt_plugin_descriptor_attribute_##_id##_##_attr_name; \
227 extern struct __bt_plugin_descriptor_attribute const *__start___bt_plugin_descriptor_attributes; \
228 extern struct __bt_plugin_descriptor_attribute const *__stop___bt_plugin_descriptor_attributes
229
230/*
231 * Defines a plugin initialization function attribute attached to a
232 * specific plugin descriptor.
233 *
234 * _id: Plugin descriptor ID (C identifier).
235 * _x: Initialization function (bt_plugin_init_func).
236 */
237#define BT_PLUGIN_INIT_WITH_ID(_id, _x) \
238 __BT_PLUGIN_DESCRIPTOR_ATTRIBUTE(init, BT_PLUGIN_DESCRIPTOR_ATTRIBUTE_TYPE_INIT, _id, _x)
239
240/*
241 * Defines a plugin exit function attribute attached to a specific
242 * plugin descriptor.
243 *
244 * _id: Plugin descriptor ID (C identifier).
245 * _x: Exit function (bt_plugin_exit_func).
246 */
247#define BT_PLUGIN_EXIT_WITH_ID(_id, _x) \
248 __BT_PLUGIN_DESCRIPTOR_ATTRIBUTE(exit, BT_PLUGIN_DESCRIPTOR_ATTRIBUTE_TYPE_EXIT, _id, _x)
249
250/*
251 * Defines an author attribute attached to a specific plugin descriptor.
252 *
253 * _id: Plugin descriptor ID (C identifier).
254 * _x: Author (C string).
255 */
256#define BT_PLUGIN_AUTHOR_WITH_ID(_id, _x) \
257 __BT_PLUGIN_DESCRIPTOR_ATTRIBUTE(author, BT_PLUGIN_DESCRIPTOR_ATTRIBUTE_TYPE_AUTHOR, _id, _x)
258
259/*
260 * Defines a license attribute attached to a specific plugin descriptor.
261 *
262 * _id: Plugin descriptor ID (C identifier).
263 * _x: License (C string).
264 */
265#define BT_PLUGIN_LICENSE_WITH_ID(_id, _x) \
266 __BT_PLUGIN_DESCRIPTOR_ATTRIBUTE(license, BT_PLUGIN_DESCRIPTOR_ATTRIBUTE_TYPE_LICENSE, _id, _x)
267
268/*
269 * Defines a description attribute attached to a specific plugin
270 * descriptor.
271 *
272 * _id: Plugin descriptor ID (C identifier).
273 * _x: Description (C string).
274 */
275#define BT_PLUGIN_DESCRIPTION_WITH_ID(_id, _x) \
276 __BT_PLUGIN_DESCRIPTOR_ATTRIBUTE(description, BT_PLUGIN_DESCRIPTOR_ATTRIBUTE_TYPE_DESCRIPTION, _id, _x)
277
278/*
279 * Defines a component class descriptor with a custom ID.
280 *
281 * _id: ID (any valid C identifier except `auto`).
282 * _comp_class_id: Component class ID (C identifier).
283 * _type: Component class type (enum bt_component_type).
284 * _name: Component class name (C string).
285 * _init_func: Component class's initialization function
286 * (bt_component_init_cb).
287 */
288#define BT_PLUGIN_COMPONENT_CLASS_WITH_ID(_id, _comp_class_id, _type, _name, _init_cb) \
289 static struct __bt_plugin_component_class_descriptor __bt_plugin_component_class_descriptor_##_id##_##_comp_class_id##_##_type = { \
290 .plugin_descriptor = &__bt_plugin_descriptor_##_id, \
291 .type = _type, \
292 .name = _name, \
293 .init_cb = _init_cb, \
294 }; \
295 static struct __bt_plugin_component_class_descriptor const * const __bt_plugin_component_class_descriptor_##_id##_##_comp_class_id##_##_type##_ptr __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRS = &__bt_plugin_component_class_descriptor_##_id##_##_comp_class_id##_##_type; \
296 extern struct __bt_plugin_component_class_descriptor const *__start___bt_plugin_component_class_descriptors; \
297 extern struct __bt_plugin_component_class_descriptor const *__stop___bt_plugin_component_class_descriptors
298
299/*
300 * Defines a component class descriptor attribute (generic, internal
301 * use).
302 *
303 * _id: Plugin descriptor ID (C identifier).
304 * _comp_class_id: Component class ID (C identifier).
305 * _type: Component class type (enum bt_component_type).
306 * _attr_name: Name of the attribute (C identifier).
307 * _attr_type: Type of the attribute
308 * (enum __bt_plugin_descriptor_attribute_type).
309 * _x: Value.
310 */
311#define __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE(_attr_name, _attr_type, _id, _comp_class_id, _type, _x) \
312 static struct __bt_plugin_component_class_descriptor_attribute __bt_plugin_component_class_descriptor_attribute_##_id##_##_comp_class_id##_##_type##_##_attr_name = { \
313 .comp_class_descriptor = &__bt_plugin_component_class_descriptor_##_id##_##_comp_class_id##_##_type, \
314 .type = _attr_type, \
315 .type_name = #_attr_name, \
316 .value.description = _x, \
317 }; \
318 static struct __bt_plugin_component_class_descriptor_attribute const * const __bt_plugin_component_class_descriptor_attribute_##_id##_##_comp_class_id##_##_type##_##_attr_name##_ptr __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTES_ATTRS = &__bt_plugin_component_class_descriptor_attribute_##_id##_##_comp_class_id##_##_type##_##_attr_name; \
319 extern struct __bt_plugin_component_class_descriptor_attribute const *__start___bt_plugin_component_class_descriptor_attributes; \
320 extern struct __bt_plugin_component_class_descriptor_attribute const *__stop___bt_plugin_component_class_descriptor_attributes
321
322/*
323 * Defines a description attribute attached to a specific component
324 * class descriptor.
325 *
326 * _id: Plugin descriptor ID (C identifier).
327 * _comp_class_id: Component class descriptor ID (C identifier).
328 * _type: Component class type (enum bt_component_type).
329 * _x: Description (C string).
330 */
331#define BT_PLUGIN_COMPONENT_CLASS_DESCRIPTION_WITH_ID(_id, _comp_class_id, _type, _x) \
332 __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE(description, BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE_TYPE_DESCRIPTION, _id, _comp_class_id, _type, _x)
333
334/*
335 * Defines a plugin descriptor with an automatic ID.
336 *
337 * _name: Plugin's name (C string).
338 */
339#define BT_PLUGIN(_name) static BT_PLUGIN_WITH_ID(auto, #_name)
340
341/*
342 * Defines a plugin initialization function attribute attached to the
343 * automatic plugin descriptor.
344 *
345 * _x: Initialization function (bt_plugin_init_func).
346 */
347#define BT_PLUGIN_INIT(_x) BT_PLUGIN_INIT_WITH_ID(auto, _x)
348
349 /*
350 * Defines a plugin exit function attribute attached to the automatic
351 * plugin descriptor.
352 *
353 * _x: Exit function (bt_plugin_exit_func).
354 */
355#define BT_PLUGIN_EXIT(_x) BT_PLUGIN_EXIT_WITH_ID(auto, _x)
356
357/*
358 * Defines an author attribute attached to the automatic plugin
359 * descriptor.
360 *
361 * _x: Author (C string).
362 */
363#define BT_PLUGIN_AUTHOR(_x) BT_PLUGIN_AUTHOR_WITH_ID(auto, _x)
364
365/*
366 * Defines a license attribute attached to the automatic plugin
367 * descriptor.
368 *
369 * _x: License (C string).
370 */
371#define BT_PLUGIN_LICENSE(_x) BT_PLUGIN_LICENSE_WITH_ID(auto, _x)
372
373/*
374 * Defines a description attribute attached to the automatic plugin
375 * descriptor.
376 *
377 * _x: Description (C string).
378 */
379#define BT_PLUGIN_DESCRIPTION(_x) BT_PLUGIN_DESCRIPTION_WITH_ID(auto, _x)
380
381/*
382 * Defines a component class attached to the automatic plugin
383 * descriptor. Its ID is the same as its name, hence its name must be a
384 * C identifier in this version.
385 *
386 * _type: Component class type (enum bt_component_type).
387 * _name: Component class name (C identifier).
388 * _init_cb: Component class's initialization function
389 * (bt_component_init_cb).
390 */
391#define BT_PLUGIN_COMPONENT_CLASS(_type, _name, _init_cb) \
392 BT_PLUGIN_COMPONENT_CLASS_WITH_ID(auto, _name, _type, #_name, _init_cb)
393
394/*
395 * Defines a description attribute attached to a component class
396 * descriptor which is attached to the automatic plugin descriptor.
397 *
398 * _type: Component class type (enum bt_component_type).
399 * _name: Component class name (C identifier).
400 * _x: Description (C string).
401 */
402#define BT_PLUGIN_COMPONENT_CLASS_DESCRIPTION(_type, _name, _x) \
403 BT_PLUGIN_COMPONENT_CLASS_DESCRIPTION_WITH_ID(auto, _name, _type, _x)
404
405#ifdef __cplusplus
406}
407#endif
408
409#endif /* BABELTRACE_PLUGIN_PLUGIN_DEV_H */
This page took 0.029439 seconds and 4 git commands to generate.