lib/frrscript.h

   1 /* Scripting foo
   2  * Copyright (C) 2020  NVIDIA Corporation
   3  * Quentin Young
   4  *
   5  * This program is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License as published by the Free
   7  * Software Foundation; either version 2 of the License, or (at your option)
   8  * any later version.
   9  *
  10  * This program is distributed in the hope that it will be useful, but WITHOUT
  11  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  12  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for
  13  * more details.
  14  *
  15  * You should have received a copy of the GNU General Public License along
  16  * with this program; see the file COPYING; if not, write to the Free Software
  17  * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
  18  */
  19 #ifndef __FRRSCRIPT_H__
  20 #define __FRRSCRIPT_H__
  21
  22 #include <zebra.h>
  23
  24 #ifdef HAVE_SCRIPTING
  25
  26 #include <lua.h>
  27 #include "frrlua.h"
  28 #include "bgpd/bgp_script.h" // for peer and attr encoders/decoders
  29
  30 #ifdef __cplusplus
  31 extern "C" {
  32 #endif
  33
  34 typedef void (*encoder_func)(lua_State *, const void *);
  35 typedef void *(*decoder_func)(lua_State *, int);
  36
  37 struct frrscript_codec {
  38         const char *typename;
  39         encoder_func encoder;
  40         decoder_func decoder;
  41 };
  42
  43 struct lua_function_state {
  44         const char *name;
  45         lua_State *L;
  46 };
  47
  48 struct frrscript {
  49         /* Script name */
  50         char *name;
  51
  52         /* Hash of Lua function name to Lua function state */
  53         struct hash *lua_function_hash;
  54 };
  55
  56
  57 /*
  58  * Hash related functions for lua_function_hash
  59  */
  60
  61 void *lua_function_alloc(void *arg);
  62
  63 unsigned int lua_function_hash_key(const void *data);
  64
  65 bool lua_function_hash_cmp(const void *d1, const void *d2);
  66
  67 struct frrscript_env {
  68         /* Value type */
  69         const char *typename;
  70
  71         /* Binding name */
  72         const char *name;
  73
  74         /* Value */
  75         const void *val;
  76 };
  77
  78 /*
  79  * Create new struct frrscript for a Lua script.
  80  * This will hold the states for the Lua functions in this script.
  81  *
  82  * scriptname
  83  *     Name of the Lua script file, without the .lua
  84  */
  85 struct frrscript *frrscript_new(const char *scriptname);
  86
  87 /*
  88  * Load a function into frrscript, run callback if any
  89  */
  90 int frrscript_load(struct frrscript *fs, const char *function_name,
  91                    int (*load_cb)(struct frrscript *));
  92
  93 /*
  94  * Delete Lua function states and frrscript
  95  */
  96 void frrscript_delete(struct frrscript *fs);
  97
  98 /*
  99  * Register a Lua codec for a type.
 100  *
 101  * tname
 102  *    Name of type; e.g., "peer", "ospf_interface", etc. Chosen at will.
 103  *
 104  * codec(s)
 105  *    Function pointer to codec struct. Encoder function should push a Lua
 106  *    table representing the passed argument - which will have the C type
 107  *    associated with the chosen 'tname' to the provided stack. The decoder
 108  *    function should pop a value from the top of the stack and return a heap
 109  *    chunk containing that value. Allocations should be made with MTYPE_TMP.
 110  *
 111  *    If using the plural function variant, pass a NULL-terminated array.
 112  *
 113  */
 114 void frrscript_register_type_codec(struct frrscript_codec *codec);
 115 void frrscript_register_type_codecs(struct frrscript_codec *codecs);
 116
 117 /*
 118  * Initialize scripting subsystem. Call this before anything else.
 119  *
 120  * scriptdir
 121  *    Directory in which to look for scripts
 122  */
 123 void frrscript_init(const char *scriptdir);
 124
 125 /*
 126  * This macro is mapped to every (name, value) in frrscript_call,
 127  * so this in turn maps them onto their encoders
 128  */
 129 #define ENCODE_ARGS(name, value) ENCODE_ARGS_WITH_STATE(lfs->L, (value))
 130
 131 /*
 132  * This macro is also mapped to every (name, value) in frrscript_call, but
 133  * not every value can be mapped to its decoder - only those that appear
 134  * in the returned table will. To find out if they appear in the returned
 135  * table, first pop the value and check if its nil. Only call the decoder
 136  * if non-nil.
 137  *
 138  * At the end, the only thing left on the stack should be the
 139  * returned table.
 140  */
 141 #define DECODE_ARGS(name, value)                                               \
 142         do {                                                                   \
 143                 lua_getfield(lfs->L, 1, (name));                               \
 144                 if (lua_isnil(lfs->L, 2)) {                                    \
 145                         lua_pop(lfs->L, 1);                                    \
 146                 } else {                                                       \
 147                         DECODE_ARGS_WITH_STATE(lfs->L, (value));               \
 148                 }                                                              \
 149                 assert(lua_gettop(lfs->L) == 1);                               \
 150         } while (0)
 151
 152 /*
 153  * Maps the type of value to its encoder/decoder.
 154  * Add new mappings here.
 155  *
 156  * L
 157  *    Lua state
 158  * scriptdir
 159  *    Directory in which to look for scripts
 160  */
 161 #define ENCODE_ARGS_WITH_STATE(L, value)                                       \
 162         _Generic((value), \
 163 int : lua_pushinteger,                                          \
 164 long long * : lua_pushintegerp,                                 \
 165 struct prefix * : lua_pushprefix,                               \
 166 struct interface * : lua_pushinterface,                         \
 167 struct in_addr * : lua_pushinaddr,                              \
 168 struct in6_addr * : lua_pushin6addr,                            \
 169 union sockunion * : lua_pushsockunion,                          \
 170 time_t * : lua_pushtimet,                                       \
 171 char * : lua_pushstring_wrapper,                                \
 172 struct attr * : lua_pushattr,                                   \
 173 struct peer * : lua_pushpeer,                                   \
 174 const struct prefix * : lua_pushprefix                          \
 175 )((L), (value))
 176
 177 #define DECODE_ARGS_WITH_STATE(L, value)                                       \
 178         _Generic((value), \
 179 int : lua_decode_integer_noop,                                  \
 180 long long * : lua_decode_integerp,                              \
 181 struct prefix * : lua_decode_prefix,                            \
 182 struct interface * : lua_decode_interface,                      \
 183 struct in_addr * : lua_decode_inaddr,                           \
 184 struct in6_addr * : lua_decode_in6addr,                         \
 185 union sockunion * : lua_decode_sockunion,                       \
 186 time_t * : lua_decode_timet,                                    \
 187 char * : lua_decode_stringp,                                    \
 188 struct attr * : lua_decode_attr,                                \
 189 struct peer * : lua_decode_noop,                                \
 190 const struct prefix * : lua_decode_noop                         \
 191 )((L), -1, (value))
 192
 193 /*
 194  * Call Lua function state (abstraction for a single Lua function)
 195  *
 196  * lfs
 197  *    The Lua function to call; this should have been loaded in by
 198  *    frrscript_load(). nargs Number of arguments the function accepts
 199  *
 200  * Returns:
 201  *    0 if the script ran successfully, nonzero otherwise.
 202  */
 203 int _frrscript_call_lua(struct lua_function_state *lfs, int nargs);
 204
 205 /*
 206  * Wrapper for calling Lua function state.
 207  *
 208  * The Lua function name (f) to run should have already been checked by
 209  * frrscript_load. So this wrapper will:
 210  * 1) Find the Lua function state, which contains the Lua state
 211  * 2) Clear the Lua state (there may be leftovers items from previous call)
 212  * 3) Push the Lua function (f)
 213  * 4) Map frrscript_call arguments onto their encoder and decoders, push those
 214  * 5) Call _frrscript_call_lua (Lua execution takes place)
 215  * 6) Write back to frrscript_call arguments using their decoders
 216  *
 217  * This wrapper can be called multiple times (after one frrscript_load).
 218  *
 219  * fs
 220  *    The struct frrscript in which the Lua fuction was loaded into
 221  * f
 222  *    Name of the Lua function.
 223  *
 224  * Returns:
 225  *    0 if the script ran successfully, nonzero otherwise.
 226  */
 227 #define frrscript_call(fs, f, ...)                                                                                                                                 \
 228         ({                                                                                                                                                         \
 229                 struct lua_function_state lookup = {.name = (f)};                                                                                                  \
 230                 struct lua_function_state *lfs;                                                                                                                    \
 231                 lfs = hash_lookup((fs)->lua_function_hash, &lookup);                                                                                               \
 232                 lfs == NULL ? ({                                                                                                                                   \
 233                         zlog_err(                                                                                                                                  \
 234                                 "frrscript: '%s.lua': '%s': tried to call this function but it was not loaded",                                                    \
 235                                 (fs)->name, (f));                                                                                                                  \
 236                         1;                                                                                                                                         \
 237                 })                                                                                                                                                 \
 238                             : ({                                                                                                                                   \
 239                                       lua_settop(lfs->L, 0);                                                                                                       \
 240                                       lua_getglobal(lfs->L, f);                                                                                                    \
 241                                       MAP_LISTS(ENCODE_ARGS, ##__VA_ARGS__);                                                                                       \
 242                                       _frrscript_call_lua(                                                                                                         \
 243                                               lfs, PP_NARG(__VA_ARGS__));                                                                                          \
 244                               }) != 0                                                                                                                              \
 245                                       ? ({                                                                                                                         \
 246                                                 zlog_err(                                                                                                          \
 247                                                         "frrscript: '%s.lua': '%s': this function called but returned non-zero exit code. No variables modified.", \
 248                                                         (fs)->name, (f));                                                                                          \
 249                                                 1;                                                                                                                 \
 250                                         })                                                                                                                         \
 251                                       : ({                                                                                                                         \
 252                                                 MAP_LISTS(DECODE_ARGS,                                                                                             \
 253                                                           ##__VA_ARGS__);                                                                                          \
 254                                                 0;                                                                                                                 \
 255                                         });                                                                                                                        \
 256         })
 257
 258 /*
 259  * Get result from finished function
 260  *
 261  * fs
 262  *    The script. This script must have been run already.
 263  * function_name
 264  *    Name of the Lua function.
 265  * name
 266  *    Name of the result.
 267  *    This will be used as a string key to retrieve from the table that the
 268  *    Lua function returns.
 269  *    The name here should *not* appear in frrscript_call.
 270  * lua_to
 271  *    Function pointer to a lua_to decoder function.
 272  *    This function should allocate and decode a value from the Lua state.
 273  *
 274  * Returns:
 275  *    A pointer to the decoded value from the Lua state, or NULL if no such
 276  *    value.
 277  */
 278 void *frrscript_get_result(struct frrscript *fs, const char *function_name,
 279                            const char *name,
 280                            void *(*lua_to)(lua_State *L, int idx));
 281
 282 #ifdef __cplusplus
 283 }
 284 #endif /* __cplusplus */
 285
 286 #endif /* HAVE_SCRIPTING */
 287
 288 #endif /* __FRRSCRIPT_H__ */