1 #ifndef BABELTRACE_PLUGIN_PLUGIN_DEV_H
2 #define BABELTRACE_PLUGIN_PLUGIN_DEV_H
5 * BabelTrace - Babeltrace Plug-in Development API
7 * This is the header that you need to include for the development of
8 * a Babeltrace plug-in.
10 * Copyright 2015 Jérémie Galarneau <jeremie.galarneau@efficios.com>
11 * Copyright 2017 Philippe Proulx <pproulx@efficios.com>
13 * Author: Jérémie Galarneau <jeremie.galarneau@efficios.com>
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:
22 * The above copyright notice and this permission notice shall be included in
23 * all copies or substantial portions of the Software.
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
35 #include <babeltrace/plugin/plugin.h>
36 #include <babeltrace/component/component-class.h>
43 * Plugin interface's version, not synced with Babeltrace's version
46 #define __BT_PLUGIN_VERSION_MAJOR 1
47 #define __BT_PLUGIN_VERSION_MINOR 0
49 /* Plugin initialization function type */
50 typedef enum bt_plugin_status (*bt_plugin_init_func
)(
51 struct bt_plugin
*plugin
);
53 /* Plugin exit function type */
54 typedef enum bt_plugin_status (*bt_plugin_exit_func
)(void);
57 * Function to call from a plugin's initialization function to add a
58 * component class to a plugin object.
60 extern enum bt_plugin_status
bt_plugin_add_component_class(
61 struct bt_plugin
*plugin
,
62 struct bt_component_class
*component_class
);
64 /* Plugin descriptor: describes a single plugin (internal use) */
65 struct __bt_plugin_descriptor
{
66 /* Plugin's interface major version number */
69 /* Plugin's interface minor version number */
74 } __attribute__((packed
));
76 /* Type of a plugin attribute (internal use) */
77 enum __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,
85 /* Plugin attribute (internal use) */
86 struct __bt_plugin_descriptor_attribute
{
87 /* Plugin descriptor to which to associate this attribute */
88 const struct __bt_plugin_descriptor
*plugin_descriptor
;
90 /* Attribute's type */
91 enum __bt_plugin_descriptor_attribute_type type
;
93 /* Name of the attribute's type for debug purposes */
94 const char *type_name
;
96 /* Attribute's value */
98 /* BT_PLUGIN_DESCRIPTOR_ATTRIBUTE_TYPE_INIT */
99 bt_plugin_init_func init
;
101 /* BT_PLUGIN_DESCRIPTOR_ATTRIBUTE_TYPE_EXIT */
102 bt_plugin_exit_func exit
;
104 /* BT_PLUGIN_DESCRIPTOR_ATTRIBUTE_TYPE_AUTHOR */
107 /* BT_PLUGIN_DESCRIPTOR_ATTRIBUTE_TYPE_LICENSE */
110 /* BT_PLUGIN_DESCRIPTOR_ATTRIBUTE_TYPE_DESCRIPTION */
111 const char *description
;
113 } __attribute__((packed
));
115 /* Component class descriptor (internal use) */
116 struct __bt_plugin_component_class_descriptor
{
118 * Plugin descriptor to which to associate this component
121 const struct __bt_plugin_descriptor
*plugin_descriptor
;
124 enum bt_component_type type
;
126 /* Component class name */
129 /* Component initialization function */
130 bt_component_init_cb init_cb
;
131 } __attribute__((packed
));
133 /* Type of a component class attribute (internal use) */
134 enum __bt_plugin_component_class_descriptor_attribute_type
{
135 BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE_TYPE_DESCRIPTION
= 0,
138 /* Component class attribute (internal use) */
139 struct __bt_plugin_component_class_descriptor_attribute
{
141 * Component class plugin attribute to which to associate this
142 * component class attribute.
144 const struct __bt_plugin_component_class_descriptor
*comp_class_descriptor
;
146 /* Attribute's type */
147 enum __bt_plugin_component_class_descriptor_attribute_type type
;
149 /* Name of the attribute's type for debug purposes */
150 const char *type_name
;
152 /* Attribute's value */
154 /* BT_PLUGIN_DESCRIPTOR_ATTRIBUTE_TYPE_DESCRIPTION */
155 const char *description
;
157 } __attribute__((packed
));
160 * Variable attributes for a plugin descriptor pointer to be added to
161 * the plugin descriptor section (internal use).
163 #define __BT_PLUGIN_DESCRIPTOR_ATTRS \
164 __attribute__((section("__bt_plugin_descriptors"), used))
167 * Variable attributes for a plugin attribute pointer to be added to
168 * the plugin attribute section (internal use).
170 #define __BT_PLUGIN_DESCRIPTOR_ATTRIBUTES_ATTRS \
171 __attribute__((section("__bt_plugin_descriptor_attributes"), used))
174 * Variable attributes for a component class descriptor pointer to be
175 * added to the component class descriptor section (internal use).
177 #define __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRS \
178 __attribute__((section("__bt_plugin_component_class_descriptors"), used))
181 * Variable attributes for a component class descriptor attribute
182 * pointer to be added to the component class descriptor attribute
183 * section (internal use).
185 #define __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTES_ATTRS \
186 __attribute__((section("__bt_plugin_component_class_descriptor_attributes"), used))
189 * Declares a plugin descriptor pointer variable with a custom ID.
191 * _id: ID (any valid C identifier except `auto`).
193 #define BT_PLUGIN_DECLARE(_id) extern struct __bt_plugin_descriptor __bt_plugin_descriptor_##_id
196 * Defines a plugin descriptor with a custom ID.
198 * _id: ID (any valid C identifier except `auto`).
199 * _name: Plugin's name (C string).
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, \
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
212 * Defines a plugin attribute (generic, internal use).
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).
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, \
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
231 * Defines a plugin initialization function attribute attached to a
232 * specific plugin descriptor.
234 * _id: Plugin descriptor ID (C identifier).
235 * _x: Initialization function (bt_plugin_init_func).
237 #define BT_PLUGIN_INIT_WITH_ID(_id, _x) \
238 __BT_PLUGIN_DESCRIPTOR_ATTRIBUTE(init, BT_PLUGIN_DESCRIPTOR_ATTRIBUTE_TYPE_INIT, _id, _x)
241 * Defines a plugin exit function attribute attached to a specific
244 * _id: Plugin descriptor ID (C identifier).
245 * _x: Exit function (bt_plugin_exit_func).
247 #define BT_PLUGIN_EXIT_WITH_ID(_id, _x) \
248 __BT_PLUGIN_DESCRIPTOR_ATTRIBUTE(exit, BT_PLUGIN_DESCRIPTOR_ATTRIBUTE_TYPE_EXIT, _id, _x)
251 * Defines an author attribute attached to a specific plugin descriptor.
253 * _id: Plugin descriptor ID (C identifier).
254 * _x: Author (C string).
256 #define BT_PLUGIN_AUTHOR_WITH_ID(_id, _x) \
257 __BT_PLUGIN_DESCRIPTOR_ATTRIBUTE(author, BT_PLUGIN_DESCRIPTOR_ATTRIBUTE_TYPE_AUTHOR, _id, _x)
260 * Defines a license attribute attached to a specific plugin descriptor.
262 * _id: Plugin descriptor ID (C identifier).
263 * _x: License (C string).
265 #define BT_PLUGIN_LICENSE_WITH_ID(_id, _x) \
266 __BT_PLUGIN_DESCRIPTOR_ATTRIBUTE(license, BT_PLUGIN_DESCRIPTOR_ATTRIBUTE_TYPE_LICENSE, _id, _x)
269 * Defines a description attribute attached to a specific plugin
272 * _id: Plugin descriptor ID (C identifier).
273 * _x: Description (C string).
275 #define BT_PLUGIN_DESCRIPTION_WITH_ID(_id, _x) \
276 __BT_PLUGIN_DESCRIPTOR_ATTRIBUTE(description, BT_PLUGIN_DESCRIPTOR_ATTRIBUTE_TYPE_DESCRIPTION, _id, _x)
279 * Defines a component class descriptor with a custom ID.
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).
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, \
293 .init_cb = _init_cb, \
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
300 * Defines a component class descriptor attribute (generic, internal
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).
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, \
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
323 * Defines a description attribute attached to a specific component
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).
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)
335 * Defines a plugin descriptor with an automatic ID.
337 * _name: Plugin's name (C string).
339 #define BT_PLUGIN(_name) static BT_PLUGIN_WITH_ID(auto, #_name)
342 * Defines a plugin initialization function attribute attached to the
343 * automatic plugin descriptor.
345 * _x: Initialization function (bt_plugin_init_func).
347 #define BT_PLUGIN_INIT(_x) BT_PLUGIN_INIT_WITH_ID(auto, _x)
350 * Defines a plugin exit function attribute attached to the automatic
353 * _x: Exit function (bt_plugin_exit_func).
355 #define BT_PLUGIN_EXIT(_x) BT_PLUGIN_EXIT_WITH_ID(auto, _x)
358 * Defines an author attribute attached to the automatic plugin
361 * _x: Author (C string).
363 #define BT_PLUGIN_AUTHOR(_x) BT_PLUGIN_AUTHOR_WITH_ID(auto, _x)
366 * Defines a license attribute attached to the automatic plugin
369 * _x: License (C string).
371 #define BT_PLUGIN_LICENSE(_x) BT_PLUGIN_LICENSE_WITH_ID(auto, _x)
374 * Defines a description attribute attached to the automatic plugin
377 * _x: Description (C string).
379 #define BT_PLUGIN_DESCRIPTION(_x) BT_PLUGIN_DESCRIPTION_WITH_ID(auto, _x)
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.
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).
391 #define BT_PLUGIN_COMPONENT_CLASS(_type, _name, _init_cb) \
392 BT_PLUGIN_COMPONENT_CLASS_WITH_ID(auto, _name, _type, #_name, _init_cb)
395 * Defines a description attribute attached to a component class
396 * descriptor which is attached to the automatic plugin descriptor.
398 * _type: Component class type (enum bt_component_type).
399 * _name: Component class name (C identifier).
400 * _x: Description (C string).
402 #define BT_PLUGIN_COMPONENT_CLASS_DESCRIPTION(_type, _name, _x) \
403 BT_PLUGIN_COMPONENT_CLASS_DESCRIPTION_WITH_ID(auto, _name, _type, _x)
409 #endif /* BABELTRACE_PLUGIN_PLUGIN_DEV_H */