Ed Warnicke | cb9cada | 2015-12-08 15:45:58 -0700 | [diff] [blame] | 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 |
Dave Barach | 9b8ffd9 | 2016-07-08 08:13:45 -0400 | [diff] [blame] | 31 | * application will also work in a vlib plugin. |
| 32 | * |
| 33 | * The elf-section magic which registers static objects |
Ed Warnicke | cb9cada | 2015-12-08 15:45:58 -0700 | [diff] [blame] | 34 | * works so long as plugins are preset when the vlib unix process |
Dave Barach | 9b8ffd9 | 2016-07-08 08:13:45 -0400 | [diff] [blame] | 35 | * starts. But wait: there's more... |
| 36 | * |
Ed Warnicke | cb9cada | 2015-12-08 15:45:58 -0700 | [diff] [blame] | 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. |
Damjan Marion | 0eca04d | 2017-01-03 20:11:35 +0100 | [diff] [blame] | 51 | * libvlib.la supplies weak references for these symbols which |
Ed Warnicke | cb9cada | 2015-12-08 15:45:58 -0700 | [diff] [blame] | 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 | */ |
Ed Warnicke | cb9cada | 2015-12-08 15:45:58 -0700 | [diff] [blame] | 58 | |
Damjan Marion | ef4ddfa | 2021-09-15 15:08:28 +0200 | [diff] [blame^] | 59 | typedef struct |
| 60 | { |
| 61 | u8 default_disabled : 1; |
| 62 | u8 deep_bind : 1; |
Damjan Marion | 3b46cba | 2017-01-23 21:13:45 +0100 | [diff] [blame] | 63 | const char version[32]; |
| 64 | const char version_required[32]; |
Dave Barach | 8dc954a | 2020-02-05 17:31:09 -0500 | [diff] [blame] | 65 | const char overrides[256]; |
Damjan Marion | 3b46cba | 2017-01-23 21:13:45 +0100 | [diff] [blame] | 66 | const char *early_init; |
Damjan Marion | 1bfb0dd | 2017-03-22 11:08:39 +0100 | [diff] [blame] | 67 | const char *description; |
Damjan Marion | ef4ddfa | 2021-09-15 15:08:28 +0200 | [diff] [blame^] | 68 | } __clib_packed vlib_plugin_registration_t; |
Dave Barach | 9b8ffd9 | 2016-07-08 08:13:45 -0400 | [diff] [blame] | 69 | |
Dave Barach | 500ba9f | 2020-10-15 17:07:03 -0400 | [diff] [blame] | 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 | { |
| 76 | uword data_segment_offset; |
| 77 | uword length; |
| 78 | } vlib_r2_string_t; |
| 79 | |
| 80 | typedef 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 Barach | 9b8ffd9 | 2016-07-08 08:13:45 -0400 | [diff] [blame] | 97 | typedef struct |
| 98 | { |
Ed Warnicke | cb9cada | 2015-12-08 15:45:58 -0700 | [diff] [blame] | 99 | u8 *name; |
Damjan Marion | f935e33 | 2017-01-06 14:33:05 +0100 | [diff] [blame] | 100 | u8 *filename; |
Ed Warnicke | cb9cada | 2015-12-08 15:45:58 -0700 | [diff] [blame] | 101 | struct stat file_info; |
| 102 | void *handle; |
Damjan Marion | 3b46cba | 2017-01-23 21:13:45 +0100 | [diff] [blame] | 103 | |
| 104 | /* plugin registration */ |
| 105 | vlib_plugin_registration_t *reg; |
| 106 | char *version; |
Ed Warnicke | cb9cada | 2015-12-08 15:45:58 -0700 | [diff] [blame] | 107 | } plugin_info_t; |
| 108 | |
Dave Barach | 9b8ffd9 | 2016-07-08 08:13:45 -0400 | [diff] [blame] | 109 | typedef struct |
| 110 | { |
Damjan Marion | 3b46cba | 2017-01-23 21:13:45 +0100 | [diff] [blame] | 111 | char *name; |
| 112 | u8 is_disabled; |
| 113 | u8 is_enabled; |
| 114 | u8 skip_version_check; |
| 115 | } plugin_config_t; |
| 116 | |
| 117 | typedef struct |
| 118 | { |
Ed Warnicke | cb9cada | 2015-12-08 15:45:58 -0700 | [diff] [blame] | 119 | /* loaded plugin info */ |
| 120 | plugin_info_t *plugin_info; |
| 121 | uword *plugin_by_name_hash; |
Dave Barach | 8dc954a | 2020-02-05 17:31:09 -0500 | [diff] [blame] | 122 | uword *plugin_overrides_by_name_hash; |
Ed Warnicke | cb9cada | 2015-12-08 15:45:58 -0700 | [diff] [blame] | 123 | |
Dave Barach | 0a32b60 | 2017-11-28 18:55:09 -0500 | [diff] [blame] | 124 | /* paths and name filters */ |
Ed Warnicke | cb9cada | 2015-12-08 15:45:58 -0700 | [diff] [blame] | 125 | u8 *plugin_path; |
| 126 | u8 *plugin_name_filter; |
Dave Barach | 0a32b60 | 2017-11-28 18:55:09 -0500 | [diff] [blame] | 127 | u8 *vat_plugin_path; |
| 128 | u8 *vat_plugin_name_filter; |
Mohsin Kazmi | 06bc260 | 2018-03-22 23:45:23 +0100 | [diff] [blame] | 129 | u8 plugins_default_disable; |
Ed Warnicke | cb9cada | 2015-12-08 15:45:58 -0700 | [diff] [blame] | 130 | |
Damjan Marion | 3b46cba | 2017-01-23 21:13:45 +0100 | [diff] [blame] | 131 | /* plugin configs and hash by name */ |
| 132 | plugin_config_t *configs; |
| 133 | uword *config_index_by_name; |
Ed Warnicke | cb9cada | 2015-12-08 15:45:58 -0700 | [diff] [blame] | 134 | |
Dave Barach | 8dc954a | 2020-02-05 17:31:09 -0500 | [diff] [blame] | 135 | /* Plugin log, avoid filling syslog w/ junk */ |
| 136 | vlib_log_class_t logger; |
| 137 | |
Ed Warnicke | cb9cada | 2015-12-08 15:45:58 -0700 | [diff] [blame] | 138 | /* usual */ |
| 139 | vlib_main_t *vlib_main; |
| 140 | } plugin_main_t; |
| 141 | |
Damjan Marion | 6a7acc2 | 2016-12-19 16:28:36 +0100 | [diff] [blame] | 142 | extern plugin_main_t vlib_plugin_main; |
Ed Warnicke | cb9cada | 2015-12-08 15:45:58 -0700 | [diff] [blame] | 143 | |
Damjan Marion | 3b46cba | 2017-01-23 21:13:45 +0100 | [diff] [blame] | 144 | clib_error_t *vlib_plugin_config (vlib_main_t * vm, unformat_input_t * input); |
Dave Barach | 9b8ffd9 | 2016-07-08 08:13:45 -0400 | [diff] [blame] | 145 | int vlib_plugin_early_init (vlib_main_t * vm); |
| 146 | int vlib_load_new_plugins (plugin_main_t * pm, int from_early_init); |
Damjan Marion | f935e33 | 2017-01-06 14:33:05 +0100 | [diff] [blame] | 147 | void *vlib_get_plugin_symbol (char *plugin_name, char *symbol_name); |
Dave Barach | 0a32b60 | 2017-11-28 18:55:09 -0500 | [diff] [blame] | 148 | u8 *vlib_get_vat_plugin_path (void); |
Ed Warnicke | cb9cada | 2015-12-08 15:45:58 -0700 | [diff] [blame] | 149 | |
Damjan Marion | 3b46cba | 2017-01-23 21:13:45 +0100 | [diff] [blame] | 150 | #define VLIB_PLUGIN_REGISTER() \ |
| 151 | vlib_plugin_registration_t vlib_plugin_registration \ |
BenoƮt Ganne | 01a103b | 2020-07-09 14:23:51 +0200 | [diff] [blame] | 152 | CLIB_NOSANITIZE_PLUGIN_REG_SECTION \ |
Damjan Marion | 931c6f5 | 2020-10-17 13:33:32 +0200 | [diff] [blame] | 153 | __clib_export __clib_section(".vlib_plugin_registration") |
Damjan Marion | 3b46cba | 2017-01-23 21:13:45 +0100 | [diff] [blame] | 154 | |
Dave Barach | cabbee7 | 2017-11-18 08:43:06 -0500 | [diff] [blame] | 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 | |
Ed Warnicke | cb9cada | 2015-12-08 15:45:58 -0700 | [diff] [blame] | 181 | #endif /* __included_plugin_h__ */ |
Dave Barach | 9b8ffd9 | 2016-07-08 08:13:45 -0400 | [diff] [blame] | 182 | |
| 183 | /* |
| 184 | * fd.io coding-style-patch-verification: ON |
| 185 | * |
| 186 | * Local Variables: |
| 187 | * eval: (c-set-style "gnu") |
| 188 | * End: |
| 189 | */ |