vlib/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_unix.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
  60
  61 typedef struct
  62 {
  63   u8 *name;
  64   struct stat file_info;
  65   void *handle;
  66 } plugin_info_t;
  67
  68 typedef struct
  69 {
  70   /* loaded plugin info */
  71   plugin_info_t *plugin_info;
  72   uword *plugin_by_name_hash;
  73
  74   /* path and name filter */
  75   u8 *plugin_path;
  76   u8 *plugin_name_filter;
  77
  78   /* handoff structure get callback */
  79   void *handoff_structure_get_cb;
  80
  81   /* usual */
  82   vlib_main_t *vlib_main;
  83 } plugin_main_t;
  84
  85 extern plugin_main_t vlib_plugin_main;
  86
  87 int vlib_plugin_early_init (vlib_main_t * vm);
  88 int vlib_load_new_plugins (plugin_main_t * pm, int from_early_init);
  89
  90 #endif /* __included_plugin_h__ */
  91
  92 /*
  93  * fd.io coding-style-patch-verification: ON
  94  *
  95  * Local Variables:
  96  * eval: (c-set-style "gnu")
  97  * End:
  98  */