FD.io VPP  v21.01.1
Vector Packet Processing
plugin.h
Go to the documentation of this file.
1 /*
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
31  * application will also work in a vlib plugin.
32  *
33  * The elf-section magic which registers static objects
34  * works so long as plugins are preset when the vlib unix process
35  * starts. But wait: there's more...
36  *
37  * 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.
51  * libvlib.la supplies weak references for these symbols which
52  * 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  */
58 
59 /* *INDENT-OFF* */
60 typedef CLIB_PACKED(struct {
61  u8 default_disabled;
62  const char version[32];
63  const char version_required[32];
64  const char overrides[256];
65  const char *early_init;
66  const char *description;
67 }) vlib_plugin_registration_t;
68 /* *INDENT-ON* */
69 
70 /*
71  * Plugins may also use this registration format, which is
72  * easy enough to emit from e.g. a golang compiler.
73  */
74 typedef struct
75 {
79 
80 typedef struct
81 {
89 
90 #define foreach_r2_string_field \
91 _(version) \
92 _(version_required) \
93 _(overrides) \
94 _(early_init) \
95 _(description)
96 
97 typedef struct
98 {
99  u8 *name;
101  struct stat file_info;
102  void *handle;
103 
104  /* plugin registration */
105  vlib_plugin_registration_t *reg;
106  char *version;
107 } plugin_info_t;
108 
109 typedef struct
110 {
111  char *name;
116 
117 typedef struct
118 {
119  /* loaded plugin info */
123 
124  /* paths and name filters */
130 
131  /* plugin configs and hash by name */
134 
135  /* Plugin log, avoid filling syslog w/ junk */
137 
138  /* usual */
140 } plugin_main_t;
141 
143 
146 int vlib_load_new_plugins (plugin_main_t * pm, int from_early_init);
147 void *vlib_get_plugin_symbol (char *plugin_name, char *symbol_name);
149 
150 #define VLIB_PLUGIN_REGISTER() \
151  vlib_plugin_registration_t vlib_plugin_registration \
152  CLIB_NOSANITIZE_PLUGIN_REG_SECTION \
153  __clib_export __clib_section(".vlib_plugin_registration")
154 
155 /* 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 
181 #endif /* __included_plugin_h__ */
182 
183 /*
184  * fd.io coding-style-patch-verification: ON
185  *
186  * Local Variables:
187  * eval: (c-set-style "gnu")
188  * End:
189  */
vlib_main_t * vlib_main
Definition: plugin.h:139
u8 * filename
Definition: plugin.h:100
u8 * plugin_path
Definition: plugin.h:125
u8 * plugin_name_filter
Definition: plugin.h:126
uword * plugin_overrides_by_name_hash
Definition: plugin.h:122
char * name
Definition: plugin.h:111
u8 * vat_plugin_name_filter
Definition: plugin.h:128
plugin_main_t vlib_plugin_main
Definition: plugin.c:23
clib_error_t * vlib_plugin_config(vlib_main_t *vm, unformat_input_t *input)
Definition: plugin.c:720
vlib_main_t * vm
Definition: in2out_ed.c:1580
unsigned char u8
Definition: types.h:56
uword * config_index_by_name
Definition: plugin.h:133
vlib_r2_string_t early_init
Definition: plugin.h:86
u32 vlib_log_class_t
Definition: vlib.h:51
u8 * vlib_get_vat_plugin_path(void)
Definition: plugin.c:608
vlib_plugin_registration_t * reg
Definition: plugin.h:105
int vlib_plugin_early_init(vlib_main_t *vm)
Definition: plugin.c:587
u8 * name
Definition: plugin.h:99
vlib_log_class_t logger
Definition: plugin.h:136
char * version
Definition: plugin.h:106
struct _unformat_input_t unformat_input_t
int default_disabled
Definition: plugin.h:82
int vlib_load_new_plugins(plugin_main_t *pm, int from_early_init)
Definition: plugin.c:416
plugin_info_t * plugin_info
Definition: plugin.h:120
typedef CLIB_PACKED(struct { u8 default_disabled;const char version[32];const char version_required[32];const char overrides[256];const char *early_init;const char *description;}) vlib_plugin_registration_t
vlib_r2_string_t description
Definition: plugin.h:87
vlib_r2_string_t version_required
Definition: plugin.h:84
vlib_r2_string_t version
Definition: plugin.h:83
u8 * vat_plugin_path
Definition: plugin.h:127
vlib_r2_string_t overrides
Definition: plugin.h:85
void * vlib_get_plugin_symbol(char *plugin_name, char *symbol_name)
Definition: plugin.c:38
void * handle
Definition: plugin.h:102
uword length
Definition: plugin.h:77
uword data_segment_offset
Definition: plugin.h:76
u64 uword
Definition: types.h:112
option version
Definition: sample.api:19
plugin_config_t * configs
Definition: plugin.h:132
u8 skip_version_check
Definition: plugin.h:114
uword * plugin_by_name_hash
Definition: plugin.h:121
u8 plugins_default_disable
Definition: plugin.h:129