blob: e3555fe3ba944e5051e3bdf9290770433ec5c21e [file] [log] [blame]
Ed Warnickecb9cada2015-12-08 15:45:58 -07001/*
2 * plugin.h: plugin handling
3 *
4 * Copyright (c) 2011 Cisco and/or its affiliates.
5 * Licensed under the Apache License, Version 2.0 (the "License");
6 * you may not use this file except in compliance with the License.
7 * You may obtain a copy of the License at:
8 *
9 * http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17
18#ifndef __included_plugin_h__
19#define __included_plugin_h__
20
21#include <vlib/vlib.h>
22#include <vlib/unix/unix.h>
23#include <sys/types.h>
24#include <sys/stat.h>
25#include <unistd.h>
26
27/*
28 * vlib plugin scheme
29 *
30 * Almost anything which can be made to work in a vlib unix
Dave Barach9b8ffd92016-07-08 08:13:45 -040031 * application will also work in a vlib plugin.
32 *
33 * The elf-section magic which registers static objects
Ed Warnickecb9cada2015-12-08 15:45:58 -070034 * works so long as plugins are preset when the vlib unix process
Dave Barach9b8ffd92016-07-08 08:13:45 -040035 * starts. But wait: there's more...
36 *
Ed Warnickecb9cada2015-12-08 15:45:58 -070037 * If an application calls vlib_load_new_plugins() -- possibly after
38 * changing vlib_plugin_main.plugin_path / vlib_plugin_main.plugin_name_filter,
39 * -- new plugins will be loaded. That, in turn, allows considerable
40 * flexibility in terms of adding feature code or fixing bugs without
41 * requiring the data-plane process to restart.
42 *
43 * When the plugin mechanism loads a plugin, it uses dlsym to locate
44 * and call the plugin's function vlib_plugin_register() if it exists.
45 * A plugin which expects to be loaded after the vlib application
46 * starts uses this callback to modify the application. If vlib_plugin_register
47 * returns non-zero, the plugin mechanism dlclose()'s the plugin.
48 *
49 * Applications control the plugin search path and name filter by
50 * declaring the variables vlib_plugin_path and vlib_plugin_name_filter.
Damjan Marion0eca04d2017-01-03 20:11:35 +010051 * libvlib.la supplies weak references for these symbols which
Ed Warnickecb9cada2015-12-08 15:45:58 -070052 * effectively disable the scheme. In order for the elf-section magic to
53 * work, static plugins must be loaded at the earliest possible moment.
54 *
55 * An application can change these parameters at any time and call
56 * vlib_load_new_plugins().
57 */
Ed Warnickecb9cada2015-12-08 15:45:58 -070058
Damjan Marionef4ddfa2021-09-15 15:08:28 +020059typedef struct
60{
61 u8 default_disabled : 1;
62 u8 deep_bind : 1;
Damjan Marion3b46cba2017-01-23 21:13:45 +010063 const char version[32];
64 const char version_required[32];
Dave Barach8dc954a2020-02-05 17:31:09 -050065 const char overrides[256];
Damjan Marion3b46cba2017-01-23 21:13:45 +010066 const char *early_init;
Damjan Marion1bfb0dd2017-03-22 11:08:39 +010067 const char *description;
Damjan Marionef4ddfa2021-09-15 15:08:28 +020068} __clib_packed vlib_plugin_registration_t;
Dave Barach9b8ffd92016-07-08 08:13:45 -040069
Dave Barach500ba9f2020-10-15 17:07:03 -040070/*
71 * Plugins may also use this registration format, which is
72 * easy enough to emit from e.g. a golang compiler.
73 */
74typedef struct
75{
76 uword data_segment_offset;
77 uword length;
78} vlib_r2_string_t;
79
80typedef struct
81{
82 int default_disabled;
83 vlib_r2_string_t version;
84 vlib_r2_string_t version_required;
85 vlib_r2_string_t overrides;
86 vlib_r2_string_t early_init;
87 vlib_r2_string_t description;
88} vlib_plugin_r2_t;
89
90#define foreach_r2_string_field \
91_(version) \
92_(version_required) \
93_(overrides) \
94_(early_init) \
95_(description)
96
Dave Barach9b8ffd92016-07-08 08:13:45 -040097typedef struct
98{
Ed Warnickecb9cada2015-12-08 15:45:58 -070099 u8 *name;
Damjan Marionf935e332017-01-06 14:33:05 +0100100 u8 *filename;
Ed Warnickecb9cada2015-12-08 15:45:58 -0700101 struct stat file_info;
102 void *handle;
Damjan Marion3b46cba2017-01-23 21:13:45 +0100103
104 /* plugin registration */
105 vlib_plugin_registration_t *reg;
106 char *version;
Ed Warnickecb9cada2015-12-08 15:45:58 -0700107} plugin_info_t;
108
Dave Barach9b8ffd92016-07-08 08:13:45 -0400109typedef struct
110{
Damjan Marion3b46cba2017-01-23 21:13:45 +0100111 char *name;
112 u8 is_disabled;
113 u8 is_enabled;
114 u8 skip_version_check;
115} plugin_config_t;
116
117typedef struct
118{
Ed Warnickecb9cada2015-12-08 15:45:58 -0700119 /* loaded plugin info */
120 plugin_info_t *plugin_info;
121 uword *plugin_by_name_hash;
Dave Barach8dc954a2020-02-05 17:31:09 -0500122 uword *plugin_overrides_by_name_hash;
Ed Warnickecb9cada2015-12-08 15:45:58 -0700123
Dave Barach0a32b602017-11-28 18:55:09 -0500124 /* paths and name filters */
Ed Warnickecb9cada2015-12-08 15:45:58 -0700125 u8 *plugin_path;
126 u8 *plugin_name_filter;
Dave Barach0a32b602017-11-28 18:55:09 -0500127 u8 *vat_plugin_path;
128 u8 *vat_plugin_name_filter;
Mohsin Kazmi06bc2602018-03-22 23:45:23 +0100129 u8 plugins_default_disable;
Ed Warnickecb9cada2015-12-08 15:45:58 -0700130
Damjan Marion3b46cba2017-01-23 21:13:45 +0100131 /* plugin configs and hash by name */
132 plugin_config_t *configs;
133 uword *config_index_by_name;
Ed Warnickecb9cada2015-12-08 15:45:58 -0700134
Dave Barach8dc954a2020-02-05 17:31:09 -0500135 /* Plugin log, avoid filling syslog w/ junk */
136 vlib_log_class_t logger;
137
Ed Warnickecb9cada2015-12-08 15:45:58 -0700138 /* usual */
139 vlib_main_t *vlib_main;
140} plugin_main_t;
141
Damjan Marion6a7acc22016-12-19 16:28:36 +0100142extern plugin_main_t vlib_plugin_main;
Ed Warnickecb9cada2015-12-08 15:45:58 -0700143
Damjan Marion3b46cba2017-01-23 21:13:45 +0100144clib_error_t *vlib_plugin_config (vlib_main_t * vm, unformat_input_t * input);
Dave Barach9b8ffd92016-07-08 08:13:45 -0400145int vlib_plugin_early_init (vlib_main_t * vm);
146int vlib_load_new_plugins (plugin_main_t * pm, int from_early_init);
Damjan Marionf935e332017-01-06 14:33:05 +0100147void *vlib_get_plugin_symbol (char *plugin_name, char *symbol_name);
Dave Barach0a32b602017-11-28 18:55:09 -0500148u8 *vlib_get_vat_plugin_path (void);
Ed Warnickecb9cada2015-12-08 15:45:58 -0700149
Damjan Marion3b46cba2017-01-23 21:13:45 +0100150#define VLIB_PLUGIN_REGISTER() \
151 vlib_plugin_registration_t vlib_plugin_registration \
BenoƮt Ganne01a103b2020-07-09 14:23:51 +0200152 CLIB_NOSANITIZE_PLUGIN_REG_SECTION \
Damjan Marion931c6f52020-10-17 13:33:32 +0200153 __clib_export __clib_section(".vlib_plugin_registration")
Damjan Marion3b46cba2017-01-23 21:13:45 +0100154
Dave Barachcabbee72017-11-18 08:43:06 -0500155/* Call a plugin init function: used for init function dependencies. */
156#define vlib_call_plugin_init_function(vm,p,x) \
157({ \
158 clib_error_t *(*_f)(vlib_main_t *); \
159 uword *_fptr = 0; \
160 clib_error_t * _error = 0; \
161 _fptr= vlib_get_plugin_symbol \
162 (p, CLIB_STRING_MACRO(_vlib_init_function_##x)); \
163 if (_fptr == 0) \
164 { \
165 _error = clib_error_return \
166 (0, "Plugin %s and/or symbol %s not found.", \
167 p, CLIB_STRING_MACRO(_vlib_init_function_##x)); \
168 } \
169 else \
170 { \
171 _f = (void *)(_fptr[0]); \
172 } \
173 if (_fptr && ! hash_get (vm->init_functions_called, _f)) \
174 { \
175 hash_set1 (vm->init_functions_called, _f); \
176 _error = _f (vm); \
177 } \
178 _error; \
179 })
180
Ed Warnickecb9cada2015-12-08 15:45:58 -0700181#endif /* __included_plugin_h__ */
Dave Barach9b8ffd92016-07-08 08:13:45 -0400182
183/*
184 * fd.io coding-style-patch-verification: ON
185 *
186 * Local Variables:
187 * eval: (c-set-style "gnu")
188 * End:
189 */