lib/mgmt_fe_client.h

   1 // SPDX-License-Identifier: GPL-2.0-or-later
   2 /*
   3  * MGMTD Frontend Client Library api interfaces
   4  * Copyright (C) 2021  Vmware, Inc.
   5  *                     Pushpasis Sarkar <spushpasis@vmware.com>
   6  */
   7
   8 #ifndef _FRR_MGMTD_FE_CLIENT_H_
   9 #define _FRR_MGMTD_FE_CLIENT_H_
  10
  11 #ifdef __cplusplus
  12 extern "C" {
  13 #endif
  14
  15 #include "mgmt_pb.h"
  16 #include "frrevent.h"
  17 #include "mgmtd/mgmt_defines.h"
  18
  19 /***************************************************************
  20  * Macros
  21  ***************************************************************/
  22
  23 /*
  24  * The server port MGMTD daemon is listening for Backend Client
  25  * connections.
  26  */
  27
  28 #define MGMTD_FE_CLIENT_ERROR_STRING_MAX_LEN 32
  29
  30 #define MGMTD_FE_DEFAULT_CONN_RETRY_INTVL_SEC 5
  31
  32 #define MGMTD_FE_MSG_PROC_DELAY_USEC 10
  33 #define MGMTD_FE_MAX_NUM_MSG_PROC 500
  34
  35 #define MGMTD_FE_MSG_WRITE_DELAY_MSEC 1
  36 #define MGMTD_FE_MAX_NUM_MSG_WRITE 100
  37
  38 #define GMGD_FE_MAX_NUM_REQ_ITEMS 64
  39
  40 #define MGMTD_FE_MSG_MAX_LEN 9000
  41
  42 #define MGMTD_SOCKET_FE_SEND_BUF_SIZE 65535
  43 #define MGMTD_SOCKET_FE_RECV_BUF_SIZE MGMTD_SOCKET_FE_SEND_BUF_SIZE
  44
  45 /***************************************************************
  46  * Data-structures
  47  ***************************************************************/
  48
  49 #define MGMTD_SESSION_ID_NONE 0
  50
  51 #define MGMTD_CLIENT_ID_NONE 0
  52
  53 #define MGMTD_DS_NONE MGMTD__DATASTORE_ID__DS_NONE
  54 #define MGMTD_DS_RUNNING MGMTD__DATASTORE_ID__RUNNING_DS
  55 #define MGMTD_DS_CANDIDATE MGMTD__DATASTORE_ID__CANDIDATE_DS
  56 #define MGMTD_DS_OPERATIONAL MGMTD__DATASTORE_ID__OPERATIONAL_DS
  57 #define MGMTD_DS_MAX_ID MGMTD_DS_OPERATIONAL + 1
  58
  59 struct mgmt_fe_client;
  60
  61
  62 /*
  63  * All the client specific information this library needs to
  64  * initialize itself, setup connection with MGMTD FrontEnd interface
  65  * and carry on all required procedures appropriately.
  66  *
  67  * FrontEnd clients need to initialise a instance of this structure
  68  * with appropriate data and pass it while calling the API
  69  * to initialize the library (See mgmt_fe_client_lib_init for
  70  * more details).
  71  */
  72 struct mgmt_fe_client_cbs {
  73         void (*client_connect_notify)(struct mgmt_fe_client *client,
  74                                       uintptr_t user_data, bool connected);
  75
  76         void (*client_session_notify)(struct mgmt_fe_client *client,
  77                                       uintptr_t user_data, uint64_t client_id,
  78                                       bool create, bool success,
  79                                       uintptr_t session_id,
  80                                       uintptr_t user_session_client);
  81
  82         void (*lock_ds_notify)(struct mgmt_fe_client *client,
  83                                uintptr_t user_data, uint64_t client_id,
  84                                uintptr_t session_id,
  85                                uintptr_t user_session_client, uint64_t req_id,
  86                                bool lock_ds, bool success,
  87                                Mgmtd__DatastoreId ds_id, char *errmsg_if_any);
  88
  89         void (*set_config_notify)(struct mgmt_fe_client *client,
  90                                   uintptr_t user_data, uint64_t client_id,
  91                                   uintptr_t session_id,
  92                                   uintptr_t user_session_client,
  93                                   uint64_t req_id, bool success,
  94                                   Mgmtd__DatastoreId ds_id,
  95                                   char *errmsg_if_any);
  96
  97         void (*commit_config_notify)(struct mgmt_fe_client *client,
  98                                      uintptr_t user_data, uint64_t client_id,
  99                                      uintptr_t session_id,
 100                                      uintptr_t user_session_client,
 101                                      uint64_t req_id, bool success,
 102                                      Mgmtd__DatastoreId src_ds_id,
 103                                      Mgmtd__DatastoreId dst_ds_id,
 104                                      bool validate_only, char *errmsg_if_any);
 105
 106         int (*get_data_notify)(struct mgmt_fe_client *client,
 107                                uintptr_t user_data, uint64_t client_id,
 108                                uintptr_t session_id,
 109                                uintptr_t user_session_client, uint64_t req_id,
 110                                bool success, Mgmtd__DatastoreId ds_id,
 111                                Mgmtd__YangData **yang_data, size_t num_data,
 112                                int next_key, char *errmsg_if_any);
 113
 114         int (*data_notify)(uint64_t client_id, uint64_t session_id,
 115                            uintptr_t user_data, uint64_t req_id,
 116                            Mgmtd__DatastoreId ds_id,
 117                            Mgmtd__YangData **yang_data, size_t num_data);
 118 };
 119
 120 extern struct debug mgmt_dbg_fe_client;
 121
 122 #define MGMTD_FE_CLIENT_DBG(fmt, ...)                                          \
 123         DEBUGD(&mgmt_dbg_fe_client, "FE-CLIENT: %s:" fmt, __func__,            \
 124                ##__VA_ARGS__)
 125 #define MGMTD_FE_CLIENT_ERR(fmt, ...)                                          \
 126         zlog_err("FE-CLIENT: %s: ERROR: " fmt, __func__, ##__VA_ARGS__)
 127 #define MGMTD_DBG_FE_CLIENT_CHECK()                                            \
 128         DEBUG_MODE_CHECK(&mgmt_dbg_fe_client, DEBUG_MODE_ALL)
 129
 130
 131 /***************************************************************
 132  * API prototypes
 133  ***************************************************************/
 134
 135 /*
 136  * Initialize library and try connecting with MGMTD FrontEnd interface.
 137  *
 138  * params
 139  *    Frontend client parameters.
 140  *
 141  * master_thread
 142  *    Thread master.
 143  *
 144  * Returns:
 145  *    Frontend client lib handler (nothing but address of mgmt_fe_client)
 146  */
 147 extern struct mgmt_fe_client *
 148 mgmt_fe_client_create(const char *client_name, struct mgmt_fe_client_cbs *cbs,
 149                       uintptr_t user_data, struct event_loop *event_loop);
 150
 151 /*
 152  * Initialize library vty (adds debug support).
 153  *
 154  * This call should be added to your component when enabling other vty
 155  * code to enable mgmtd client debugs. When adding, one needs to also
 156  * add a their component in `xref2vtysh.py` as well.
 157  */
 158 extern void mgmt_fe_client_lib_vty_init(void);
 159
 160 /*
 161  * Print enabled debugging commands.
 162  */
 163 extern void mgmt_debug_fe_client_show_debug(struct vty *vty);
 164
 165 /*
 166  * Create a new Session for a Frontend Client connection.
 167  *
 168  * lib_hndl
 169  *    Client library handler.
 170  *
 171  * client_id
 172  *    Unique identifier of client.
 173  *
 174  * user_client
 175  *    Client context.
 176  *
 177  * Returns:
 178  *    MGMTD_SUCCESS on success, MGMTD_* otherwise.
 179  */
 180 extern enum mgmt_result
 181 mgmt_fe_create_client_session(struct mgmt_fe_client *client, uint64_t client_id,
 182                               uintptr_t user_client);
 183
 184 /*
 185  * Delete an existing Session for a Frontend Client connection.
 186  *
 187  * lib_hndl
 188  *    Client library handler.
 189  *
 190  * client_id
 191  *    Unique identifier of client.
 192  *
 193  * Returns:
 194  *    0 on success, otherwise msg_conn_send_msg() return values.
 195  */
 196 extern enum mgmt_result
 197 mgmt_fe_destroy_client_session(struct mgmt_fe_client *client,
 198                                uint64_t client_id);
 199
 200 /*
 201  * Send UN/LOCK_DS_REQ to MGMTD for a specific Datastore DS.
 202  *
 203  * lib_hndl
 204  *    Client library handler.
 205  *
 206  * session_id
 207  *    Client session ID.
 208  *
 209  * req_id
 210  *    Client request ID.
 211  *
 212  * ds_id
 213  *    Datastore ID (Running/Candidate/Oper/Startup)
 214  *
 215  * lock_ds
 216  *    TRUE for lock request, FALSE for unlock request.
 217  *
 218  * Returns:
 219  *    0 on success, otherwise msg_conn_send_msg() return values.
 220  */
 221 extern int mgmt_fe_send_lockds_req(struct mgmt_fe_client *client,
 222                                    uint64_t session_id, uint64_t req_id,
 223                                    Mgmtd__DatastoreId ds_id, bool lock_ds);
 224
 225 /*
 226  * Send SET_CONFIG_REQ to MGMTD for one or more config data(s).
 227  *
 228  * lib_hndl
 229  *    Client library handler.
 230  *
 231  * session_id
 232  *    Client session ID.
 233  *
 234  * req_id
 235  *    Client request ID.
 236  *
 237  * ds_id
 238  *    Datastore ID (Running/Candidate/Oper/Startup)
 239  *
 240  * conf_req
 241  *    Details regarding the SET_CONFIG_REQ.
 242  *
 243  * num_req
 244  *    Number of config requests.
 245  *
 246  * implcit commit
 247  *    TRUE for implicit commit, FALSE otherwise.
 248  *
 249  * dst_ds_id
 250  *    Destination Datastore ID where data needs to be set.
 251  *
 252  * Returns:
 253  *    0 on success, otherwise msg_conn_send_msg() return values.
 254  */
 255
 256 extern int mgmt_fe_send_setcfg_req(struct mgmt_fe_client *client,
 257                                    uint64_t session_id, uint64_t req_id,
 258                                    Mgmtd__DatastoreId ds_id,
 259                                    Mgmtd__YangCfgDataReq **config_req,
 260                                    int num_req, bool implicit_commit,
 261                                    Mgmtd__DatastoreId dst_ds_id);
 262
 263 /*
 264  * Send SET_COMMMIT_REQ to MGMTD for one or more config data(s).
 265  *
 266  * lib_hndl
 267  *    Client library handler.
 268  *
 269  * session_id
 270  *    Client session ID.
 271  *
 272  * req_id
 273  *    Client request ID.
 274  *
 275  * src_ds_id
 276  *    Source datastore ID from where data needs to be committed from.
 277  *
 278  * dst_ds_id
 279  *    Destination datastore ID where data needs to be committed to.
 280  *
 281  * validate_only
 282  *    TRUE if data needs to be validated only, FALSE otherwise.
 283  *
 284  * abort
 285  *    TRUE if need to restore Src DS back to Dest DS, FALSE otherwise.
 286  *
 287  * Returns:
 288  *    0 on success, otherwise msg_conn_send_msg() return values.
 289  */
 290 extern int mgmt_fe_send_commitcfg_req(struct mgmt_fe_client *client,
 291                                       uint64_t session_id, uint64_t req_id,
 292                                       Mgmtd__DatastoreId src_ds_id,
 293                                       Mgmtd__DatastoreId dst_ds_id,
 294                                       bool validate_only, bool abort);
 295
 296 /*
 297  * Send GET_CONFIG_REQ to MGMTD for one or more config data item(s).
 298  *
 299  * lib_hndl
 300  *    Client library handler.
 301  *
 302  * session_id
 303  *    Client session ID.
 304  *
 305  * req_id
 306  *    Client request ID.
 307  *
 308  * ds_id
 309  *    Datastore ID (Running/Candidate)
 310  *
 311  * data_req
 312  *    Get config requested.
 313  *
 314  * num_req
 315  *    Number of get config requests.
 316  *
 317  * Returns:
 318  *    0 on success, otherwise msg_conn_send_msg() return values.
 319  */
 320 extern int mgmt_fe_send_getcfg_req(struct mgmt_fe_client *client,
 321                                    uint64_t session_id, uint64_t req_id,
 322                                    Mgmtd__DatastoreId ds_id,
 323                                    Mgmtd__YangGetDataReq **data_req,
 324                                    int num_reqs);
 325
 326 /*
 327  * Send GET_DATA_REQ to MGMTD for one or more data item(s).
 328  *
 329  * Similar to get config request but supports getting data
 330  * from operational ds aka backend clients directly.
 331  */
 332 extern int mgmt_fe_send_getdata_req(struct mgmt_fe_client *client,
 333                                     uint64_t session_id, uint64_t req_id,
 334                                     Mgmtd__DatastoreId ds_id,
 335                                     Mgmtd__YangGetDataReq **data_req,
 336                                     int num_reqs);
 337
 338 /*
 339  * Send NOTIFY_REGISTER_REQ to MGMTD daemon.
 340  *
 341  * lib_hndl
 342  *    Client library handler.
 343  *
 344  * session_id
 345  *    Client session ID.
 346  *
 347  * req_id
 348  *    Client request ID.
 349  *
 350  * ds_id
 351  *    Datastore ID.
 352  *
 353  * register_req
 354  *    TRUE if registering, FALSE otherwise.
 355  *
 356  * data_req
 357  *    Details of the YANG notification data.
 358  *
 359  * num_reqs
 360  *    Number of data requests.
 361  *
 362  * Returns:
 363  *    0 on success, otherwise msg_conn_send_msg() return values.
 364  */
 365 extern int mgmt_fe_send_regnotify_req(struct mgmt_fe_client *client,
 366                                       uint64_t session_id, uint64_t req_id,
 367                                       Mgmtd__DatastoreId ds_id,
 368                                       bool register_req,
 369                                       Mgmtd__YangDataXPath **data_req,
 370                                       int num_reqs);
 371
 372 /*
 373  * Destroy library and cleanup everything.
 374  */
 375 extern void mgmt_fe_client_destroy(struct mgmt_fe_client *client);
 376
 377 /*
 378  * Get count of open sessions.
 379  */
 380 extern uint mgmt_fe_client_session_count(struct mgmt_fe_client *client);
 381
 382 #ifdef __cplusplus
 383 }
 384 #endif
 385
 386 #endif /* _FRR_MGMTD_FE_CLIENT_H_ */