lib/mgmt_be_client.h

   1 // SPDX-License-Identifier: GPL-2.0-or-later
   2 /*
   3  * MGMTD Backend Client Library api interfaces
   4  * Copyright (C) 2021  Vmware, Inc.
   5  *                     Pushpasis Sarkar <spushpasis@vmware.com>
   6  */
   7
   8 #ifndef _FRR_MGMTD_BE_CLIENT_H_
   9 #define _FRR_MGMTD_BE_CLIENT_H_
  10
  11 #ifdef __cplusplus
  12 extern "C" {
  13 #endif
  14
  15 #include "northbound.h"
  16 #include "mgmt_pb.h"
  17 #include "mgmtd/mgmt_defines.h"
  18
  19 /***************************************************************
  20  * Client IDs
  21  ***************************************************************/
  22
  23 /*
  24  * Add enum value for each supported component, wrap with
  25  * #ifdef HAVE_COMPONENT
  26  */
  27 enum mgmt_be_client_id {
  28         MGMTD_BE_CLIENT_ID_MIN = 0,
  29         MGMTD_BE_CLIENT_ID_INIT = -1,
  30 #ifdef HAVE_STATICD
  31         MGMTD_BE_CLIENT_ID_STATICD,
  32 #endif
  33         MGMTD_BE_CLIENT_ID_MAX
  34 };
  35
  36 #define FOREACH_MGMTD_BE_CLIENT_ID(id)                  \
  37         for ((id) = MGMTD_BE_CLIENT_ID_MIN;             \
  38              (id) < MGMTD_BE_CLIENT_ID_MAX; (id)++)
  39
  40 /***************************************************************
  41  * Constants
  42  ***************************************************************/
  43
  44 #define MGMTD_BE_CLIENT_ERROR_STRING_MAX_LEN 32
  45
  46 #define MGMTD_BE_DEFAULT_CONN_RETRY_INTVL_SEC 5
  47
  48 #define MGMTD_BE_MSG_PROC_DELAY_USEC 10
  49 #define MGMTD_BE_MAX_NUM_MSG_PROC 500
  50
  51 #define MGMTD_BE_MSG_WRITE_DELAY_MSEC 1
  52 #define MGMTD_BE_MAX_NUM_MSG_WRITE 1000
  53
  54 #define GMGD_BE_MAX_NUM_REQ_ITEMS 64
  55
  56 #define MGMTD_BE_MSG_MAX_LEN 16384
  57
  58 #define MGMTD_SOCKET_BE_SEND_BUF_SIZE 65535
  59 #define MGMTD_SOCKET_BE_RECV_BUF_SIZE MGMTD_SOCKET_BE_SEND_BUF_SIZE
  60
  61 #define MGMTD_MAX_CFG_CHANGES_IN_BATCH                          \
  62         ((10 * MGMTD_BE_MSG_MAX_LEN) /                          \
  63          (MGMTD_MAX_XPATH_LEN + MGMTD_MAX_YANG_VALUE_LEN))
  64
  65 /*
  66  * MGMTD_BE_MSG_MAX_LEN must be used 80%
  67  * since there is overhead of google protobuf
  68  * that gets added to sent message
  69  */
  70 #define MGMTD_BE_CFGDATA_PACKING_EFFICIENCY 0.8
  71 #define MGMTD_BE_CFGDATA_MAX_MSG_LEN                                        \
  72         (MGMTD_BE_MSG_MAX_LEN * MGMTD_BE_CFGDATA_PACKING_EFFICIENCY)
  73
  74 #define MGMTD_BE_MAX_BATCH_IDS_IN_REQ                                       \
  75         (MGMTD_BE_MSG_MAX_LEN - 128) / sizeof(uint64_t)
  76
  77 #define MGMTD_BE_CONTAINER_NODE_VAL "<<container>>"
  78
  79 /***************************************************************
  80  * Data-structures
  81  ***************************************************************/
  82
  83 #define MGMTD_BE_MAX_CLIENTS_PER_XPATH_REG 32
  84
  85 struct mgmt_be_client_txn_ctx {
  86         uintptr_t *user_ctx;
  87 };
  88
  89 /*
  90  * All the client-specific information this library needs to
  91  * initialize itself, setup connection with MGMTD BackEnd interface
  92  * and carry on all required procedures appropriately.
  93  *
  94  * BackEnd clients need to initialise a instance of this structure
  95  * with appropriate data and pass it while calling the API
  96  * to initialize the library (See mgmt_be_client_lib_init for
  97  * more details).
  98  */
  99 struct mgmt_be_client_params {
 100         char name[MGMTD_CLIENT_NAME_MAX_LEN];
 101         uintptr_t user_data;
 102         unsigned long conn_retry_intvl_sec;
 103
 104         void (*client_connect_notify)(uintptr_t lib_hndl,
 105                                       uintptr_t usr_data,
 106                                       bool connected);
 107
 108         void (*client_subscribe_notify)(
 109                 uintptr_t lib_hndl, uintptr_t usr_data,
 110                 struct nb_yang_xpath **xpath,
 111                 enum mgmt_result subscribe_result[], int num_paths);
 112
 113         void (*txn_notify)(
 114                 uintptr_t lib_hndl, uintptr_t usr_data,
 115                 struct mgmt_be_client_txn_ctx *txn_ctx, bool destroyed);
 116
 117         enum mgmt_result (*data_validate)(
 118                 uintptr_t lib_hndl, uintptr_t usr_data,
 119                 struct mgmt_be_client_txn_ctx *txn_ctx,
 120                 struct nb_yang_xpath *xpath, struct nb_yang_value *data,
 121                 bool delete, char *error_if_any);
 122
 123         enum mgmt_result (*data_apply)(
 124                 uintptr_t lib_hndl, uintptr_t usr_data,
 125                 struct mgmt_be_client_txn_ctx *txn_ctx,
 126                 struct nb_yang_xpath *xpath, struct nb_yang_value *data,
 127                 bool delete);
 128
 129         enum mgmt_result (*get_data_elem)(
 130                 uintptr_t lib_hndl, uintptr_t usr_data,
 131                 struct mgmt_be_client_txn_ctx *txn_ctx,
 132                 struct nb_yang_xpath *xpath, struct nb_yang_xpath_elem *elem);
 133
 134         enum mgmt_result (*get_data)(
 135                 uintptr_t lib_hndl, uintptr_t usr_data,
 136                 struct mgmt_be_client_txn_ctx *txn_ctx,
 137                 struct nb_yang_xpath *xpath, bool keys_only,
 138                 struct nb_yang_xpath_elem **elems, int *num_elems,
 139                 int *next_key);
 140
 141         enum mgmt_result (*get_next_data)(
 142                 uintptr_t lib_hndl, uintptr_t usr_data,
 143                 struct mgmt_be_client_txn_ctx *txn_ctx,
 144                 struct nb_yang_xpath *xpath, bool keys_only,
 145                 struct nb_yang_xpath_elem **elems, int *num_elems);
 146 };
 147
 148 /***************************************************************
 149  * Global data exported
 150  ***************************************************************/
 151
 152 extern const char *mgmt_be_client_names[MGMTD_BE_CLIENT_ID_MAX + 1];
 153
 154 static inline const char *mgmt_be_client_id2name(enum mgmt_be_client_id id)
 155 {
 156         if (id > MGMTD_BE_CLIENT_ID_MAX)
 157                 id = MGMTD_BE_CLIENT_ID_MAX;
 158         return mgmt_be_client_names[id];
 159 }
 160
 161 static inline enum mgmt_be_client_id
 162 mgmt_be_client_name2id(const char *name)
 163 {
 164         enum mgmt_be_client_id id;
 165
 166         FOREACH_MGMTD_BE_CLIENT_ID (id) {
 167                 if (!strncmp(mgmt_be_client_names[id], name,
 168                              MGMTD_CLIENT_NAME_MAX_LEN))
 169                         return id;
 170         }
 171
 172         return MGMTD_BE_CLIENT_ID_MAX;
 173 }
 174
 175 /***************************************************************
 176  * API prototypes
 177  ***************************************************************/
 178
 179 /*
 180  * Initialize library and try connecting with MGMTD.
 181  *
 182  * params
 183  *    Backend client parameters.
 184  *
 185  * master_thread
 186  *    Thread master.
 187  *
 188  * Returns:
 189  *    Backend client lib handler (nothing but address of mgmt_be_client_ctx)
 190  */
 191 extern uintptr_t mgmt_be_client_lib_init(struct mgmt_be_client_params *params,
 192                                          struct event_loop *master_thread);
 193
 194 /*
 195  * Initialize library vty (adds debug support).
 196  *
 197  * This call should be added to your component when enabling other vty code to
 198  * enable mgmtd client debugs. When adding, one needs to also add a their
 199  * component in `xref2vtysh.py` as well.
 200  */
 201 extern void mgmt_be_client_lib_vty_init(void);
 202
 203 /*
 204  * Print enabled debugging commands.
 205  */
 206 extern void mgmt_debug_be_client_show_debug(struct vty *vty);
 207
 208 /*
 209  * Subscribe with MGMTD for one or more YANG subtree(s).
 210  *
 211  * lib_hndl
 212  *    Client library handler.
 213  *
 214  * reg_yang_xpaths
 215  *    Yang xpath(s) that needs to be subscribed to.
 216  *
 217  * num_xpaths
 218  *    Number of xpaths
 219  *
 220  * Returns:
 221  *    MGMTD_SUCCESS on success, MGMTD_* otherwise.
 222  */
 223 extern enum mgmt_result mgmt_be_subscribe_yang_data(uintptr_t lib_hndl,
 224                                                        char **reg_yang_xpaths,
 225                                                        int num_xpaths);
 226
 227 /*
 228  * Send one or more YANG notifications to MGMTD daemon.
 229  *
 230  * lib_hndl
 231  *    Client library handler.
 232  *
 233  * data_elems
 234  *    Yang data elements from data tree.
 235  *
 236  * num_elems
 237  *    Number of data elements.
 238  *
 239  * Returns:
 240  *    MGMTD_SUCCESS on success, MGMTD_* otherwise.
 241  */
 242 extern enum mgmt_result
 243 mgmt_be_send_yang_notify(uintptr_t lib_hndl, Mgmtd__YangData **data_elems,
 244                             int num_elems);
 245
 246 /*
 247  * Un-subscribe with MGMTD for one or more YANG subtree(s).
 248  *
 249  * lib_hndl
 250  *    Client library handler.
 251  *
 252  * reg_yang_xpaths
 253  *    Yang xpath(s) that needs to be un-subscribed from.
 254  *
 255  * num_reg_xpaths
 256  *    Number of subscribed xpaths
 257  *
 258  * Returns:
 259  *    MGMTD_SUCCESS on success, MGMTD_* otherwise.
 260  */
 261 enum mgmt_result mgmt_be_unsubscribe_yang_data(uintptr_t lib_hndl,
 262                                                   char **reg_yang_xpaths,
 263                                                   int num_reg_xpaths);
 264
 265 /*
 266  * Destroy library and cleanup everything.
 267  */
 268 extern void mgmt_be_client_lib_destroy(uintptr_t lib_hndl);
 269
 270 #ifdef __cplusplus
 271 }
 272 #endif
 273
 274 #endif /* _FRR_MGMTD_BE_CLIENT_H_ */