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;
  86
  87 struct mgmt_be_client_txn_ctx {
  88         uintptr_t *user_ctx;
  89 };
  90
  91 /**
  92  * Backend client callbacks.
  93  *
  94  * Callbacks:
  95  *      client_connect_notify: called when connection is made/lost to mgmtd.
  96  *      txn_notify: called when a txn has been created
  97  */
  98 struct mgmt_be_client_cbs {
  99         void (*client_connect_notify)(struct mgmt_be_client *client,
 100                                       uintptr_t usr_data, bool connected);
 101
 102         void (*txn_notify)(struct mgmt_be_client *client, uintptr_t usr_data,
 103                            struct mgmt_be_client_txn_ctx *txn_ctx,
 104                            bool destroyed);
 105 };
 106
 107 /***************************************************************
 108  * Global data exported
 109  ***************************************************************/
 110
 111 extern const char *mgmt_be_client_names[MGMTD_BE_CLIENT_ID_MAX + 1];
 112
 113 static inline const char *mgmt_be_client_id2name(enum mgmt_be_client_id id)
 114 {
 115         if (id > MGMTD_BE_CLIENT_ID_MAX)
 116                 id = MGMTD_BE_CLIENT_ID_MAX;
 117         return mgmt_be_client_names[id];
 118 }
 119
 120 static inline enum mgmt_be_client_id
 121 mgmt_be_client_name2id(const char *name)
 122 {
 123         enum mgmt_be_client_id id;
 124
 125         FOREACH_MGMTD_BE_CLIENT_ID (id) {
 126                 if (!strncmp(mgmt_be_client_names[id], name,
 127                              MGMTD_CLIENT_NAME_MAX_LEN))
 128                         return id;
 129         }
 130
 131         return MGMTD_BE_CLIENT_ID_MAX;
 132 }
 133
 134 /***************************************************************
 135  * API prototypes
 136  ***************************************************************/
 137
 138 /**
 139  * Create backend client and connect to MGMTD.
 140  *
 141  * Args:
 142  *      client_name: the name of the client
 143  *      cbs: callbacks for various events.
 144  *      event_loop: the main event loop.
 145  *
 146  * Returns:
 147  *    Backend client object.
 148  */
 149 extern struct mgmt_be_client *
 150 mgmt_be_client_create(const char *name, struct mgmt_be_client_cbs *cbs,
 151                       uintptr_t user_data, struct event_loop *event_loop);
 152
 153 /*
 154  * Initialize library vty (adds debug support).
 155  *
 156  * This call should be added to your component when enabling other vty code to
 157  * enable mgmtd client debugs. When adding, one needs to also add a their
 158  * component in `xref2vtysh.py` as well.
 159  */
 160 extern void mgmt_be_client_lib_vty_init(void);
 161
 162 /*
 163  * Print enabled debugging commands.
 164  */
 165 extern void mgmt_debug_be_client_show_debug(struct vty *vty);
 166
 167 /*
 168  * [Un]-subscribe with MGMTD for one or more YANG subtree(s).
 169  *
 170  * client
 171  *    The client object.
 172  *
 173  * reg_yang_xpaths
 174  *    Yang xpath(s) that needs to be [un]-subscribed from/to
 175  *
 176  * num_xpaths
 177  *    Number of xpaths
 178  *
 179  * Returns:
 180  *    MGMTD_SUCCESS on success, MGMTD_* otherwise.
 181  */
 182 extern int mgmt_be_send_subscr_req(struct mgmt_be_client *client,
 183                                    bool subscr_xpaths, int num_xpaths,
 184                                    char **reg_xpaths);
 185
 186 /*
 187  * Destroy backend client and cleanup everything.
 188  */
 189 extern void mgmt_be_client_destroy(struct mgmt_be_client *client);
 190
 191 #ifdef __cplusplus
 192 }
 193 #endif
 194
 195 #endif /* _FRR_MGMTD_BE_CLIENT_H_ */