src/vlib/unix/plugin.h

   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 typedef struct
  60 {
  61   CLIB_CACHE_LINE_ALIGN_MARK (cacheline0);
  62   u8 default_disabled : 1;
  63   u8 deep_bind : 1;
  64   const char version[32];
  65   const char version_required[32];
  66   const char overrides[256];
  67   const char *early_init;
  68   const char *description;
  69 } vlib_plugin_registration_t;
  70
  71 /*
  72  * Plugins may also use this registration format, which is
  73  * easy enough to emit from e.g. a golang compiler.
  74  */
  75 typedef struct
  76 {
  77   uword data_segment_offset;
  78   uword length;
  79 } vlib_r2_string_t;
  80
  81 typedef struct
  82 {
  83   int default_disabled;
  84   vlib_r2_string_t version;
  85   vlib_r2_string_t version_required;
  86   vlib_r2_string_t overrides;
  87   vlib_r2_string_t early_init;
  88   vlib_r2_string_t description;
  89 } vlib_plugin_r2_t;
  90
  91 #define foreach_r2_string_field                 \
  92 _(version)                                      \
  93 _(version_required)                             \
  94 _(overrides)                                    \
  95 _(early_init)                                   \
  96 _(description)
  97
  98 typedef struct
  99 {
 100   u8 *name;
 101   u8 *filename;
 102   struct stat file_info;
 103   void *handle;
 104
 105   /* plugin registration */
 106   vlib_plugin_registration_t *reg;
 107   char *version;
 108 } plugin_info_t;
 109
 110 typedef struct
 111 {
 112   char *name;
 113   u8 is_disabled;
 114   u8 is_enabled;
 115   u8 skip_version_check;
 116 } plugin_config_t;
 117
 118 typedef struct
 119 {
 120   /* loaded plugin info */
 121   plugin_info_t *plugin_info;
 122   uword *plugin_by_name_hash;
 123   uword *plugin_overrides_by_name_hash;
 124
 125   /* paths and name filters */
 126   u8 *plugin_path;
 127   u8 *plugin_path_add;
 128   u8 *plugin_name_filter;
 129   u8 *vat_plugin_path;
 130   u8 *vat_plugin_name_filter;
 131   u8 plugins_default_disable;
 132
 133   /* plugin configs and hash by name */
 134   plugin_config_t *configs;
 135   uword *config_index_by_name;
 136
 137   /* Plugin log, avoid filling syslog w/ junk */
 138   vlib_log_class_t logger;
 139
 140   /* usual */
 141   vlib_main_t *vlib_main;
 142 } plugin_main_t;
 143
 144 extern plugin_main_t vlib_plugin_main;
 145
 146 clib_error_t *vlib_plugin_config (vlib_main_t * vm, unformat_input_t * input);
 147 int vlib_plugin_early_init (vlib_main_t * vm);
 148 int vlib_load_new_plugins (plugin_main_t * pm, int from_early_init);
 149 void *vlib_get_plugin_symbol (char *plugin_name, char *symbol_name);
 150 u8 *vlib_get_vat_plugin_path (void);
 151
 152 #define VLIB_PLUGIN_REGISTER() \
 153   vlib_plugin_registration_t vlib_plugin_registration \
 154   __clib_export __clib_section(".vlib_plugin_registration")
 155
 156 /* Call a plugin init function: used for init function dependencies. */
 157 #define vlib_call_plugin_init_function(vm,p,x)                  \
 158 ({                                                              \
 159   clib_error_t *(*_f)(vlib_main_t *);                           \
 160   uword *_fptr = 0;                                             \
 161   clib_error_t * _error = 0;                                    \
 162   _fptr= vlib_get_plugin_symbol                                 \
 163     (p, CLIB_STRING_MACRO(_vlib_init_function_##x));            \
 164   if (_fptr == 0)                                               \
 165     {                                                           \
 166       _error = clib_error_return                                \
 167         (0, "Plugin %s and/or symbol %s not found.",            \
 168          p, CLIB_STRING_MACRO(_vlib_init_function_##x));        \
 169     }                                                           \
 170   else                                                          \
 171     {                                                           \
 172       _f = (void *)(_fptr[0]);                                  \
 173     }                                                           \
 174   if (_fptr && ! hash_get (vm->init_functions_called, _f))      \
 175     {                                                           \
 176       hash_set1 (vm->init_functions_called, _f);                \
 177       _error = _f (vm);                                         \
 178     }                                                           \
 179   _error;                                                       \
 180  })
 181
 182 #endif /* __included_plugin_h__ */
 183
 184 /*
 185  * fd.io coding-style-patch-verification: ON
 186  *
 187  * Local Variables:
 188  * eval: (c-set-style "gnu")
 189  * End:
 190  */