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 /*
  60  * All the client specific information this library needs to
  61  * initialize itself, setup connection with MGMTD FrontEnd interface
  62  * and carry on all required procedures appropriately.
  63  *
  64  * FrontEnd clients need to initialise a instance of this structure
  65  * with appropriate data and pass it while calling the API
  66  * to initialize the library (See mgmt_fe_client_lib_init for
  67  * more details).
  68  */
  69 struct mgmt_fe_client_params {
  70         char name[MGMTD_CLIENT_NAME_MAX_LEN];
  71         uintptr_t user_data;
  72         unsigned long conn_retry_intvl_sec;
  73
  74         void (*client_connect_notify)(uintptr_t lib_hndl,
  75                                       uintptr_t user_data,
  76                                       bool connected);
  77
  78         void (*client_session_notify)(uintptr_t lib_hndl,
  79                                       uintptr_t user_data,
  80                                       uint64_t client_id,
  81                                       bool create, bool success,
  82                                       uintptr_t session_id,
  83                                       uintptr_t user_session_ctx);
  84
  85         void (*lock_ds_notify)(uintptr_t lib_hndl, uintptr_t user_data,
  86                                uint64_t client_id, uintptr_t session_id,
  87                                uintptr_t user_session_ctx, uint64_t req_id,
  88                                bool lock_ds, bool success,
  89                                Mgmtd__DatastoreId ds_id, char *errmsg_if_any);
  90
  91         void (*set_config_notify)(uintptr_t lib_hndl, uintptr_t user_data,
  92                                   uint64_t client_id, uintptr_t session_id,
  93                                   uintptr_t user_session_ctx, uint64_t req_id,
  94                                   bool success, Mgmtd__DatastoreId ds_id,
  95                                   char *errmsg_if_any);
  96
  97         void (*commit_config_notify)(
  98                 uintptr_t lib_hndl, uintptr_t user_data, uint64_t client_id,
  99                 uintptr_t session_id, uintptr_t user_session_ctx,
 100                 uint64_t req_id, bool success, Mgmtd__DatastoreId src_ds_id,
 101                 Mgmtd__DatastoreId dst_ds_id, bool validate_only,
 102                 char *errmsg_if_any);
 103
 104         enum mgmt_result (*get_data_notify)(
 105                 uintptr_t lib_hndl, uintptr_t user_data, uint64_t client_id,
 106                 uintptr_t session_id, uintptr_t user_session_ctx,
 107                 uint64_t req_id, bool success, Mgmtd__DatastoreId ds_id,
 108                 Mgmtd__YangData **yang_data, size_t num_data, int next_key,
 109                 char *errmsg_if_any);
 110
 111         enum mgmt_result (*data_notify)(
 112                 uint64_t client_id, uint64_t session_id, uintptr_t user_data,
 113                 uint64_t req_id, Mgmtd__DatastoreId ds_id,
 114                 Mgmtd__YangData **yang_data, size_t num_data);
 115 };
 116
 117 /***************************************************************
 118  * API prototypes
 119  ***************************************************************/
 120
 121 /*
 122  * Initialize library and try connecting with MGMTD FrontEnd interface.
 123  *
 124  * params
 125  *    Frontend client parameters.
 126  *
 127  * master_thread
 128  *    Thread master.
 129  *
 130  * Returns:
 131  *    Frontend client lib handler (nothing but address of mgmt_fe_client_ctx)
 132  */
 133 extern uintptr_t mgmt_fe_client_lib_init(struct mgmt_fe_client_params *params,
 134                                          struct event_loop *master_thread);
 135
 136 /*
 137  * Initialize library vty (adds debug support).
 138  *
 139  * This call should be added to your component when enabling other vty code to
 140  * enable mgmtd client debugs. When adding, one needs to also add a their
 141  * component in `xref2vtysh.py` as well.
 142  */
 143 extern void mgmt_fe_client_lib_vty_init(void);
 144
 145 /*
 146  * Print enabled debugging commands.
 147  */
 148 extern void mgmt_debug_fe_client_show_debug(struct vty *vty);
 149
 150 /*
 151  * Create a new Session for a Frontend Client connection.
 152  *
 153  * lib_hndl
 154  *    Client library handler.
 155  *
 156  * client_id
 157  *    Unique identifier of client.
 158  *
 159  * user_ctx
 160  *    Client context.
 161  *
 162  * Returns:
 163  *    MGMTD_SUCCESS on success, MGMTD_* otherwise.
 164  */
 165 extern enum mgmt_result mgmt_fe_create_client_session(uintptr_t lib_hndl,
 166                                                           uint64_t client_id,
 167                                                           uintptr_t user_ctx);
 168
 169 /*
 170  * Delete an existing Session for a Frontend Client connection.
 171  *
 172  * lib_hndl
 173  *    Client library handler.
 174  *
 175  * client_id
 176  *    Unique identifier of client.
 177  *
 178  * Returns:
 179  *    MGMTD_SUCCESS on success, MGMTD_* otherwise.
 180  */
 181 extern enum mgmt_result mgmt_fe_destroy_client_session(uintptr_t lib_hndl,
 182                                                        uint64_t client_id);
 183
 184 /*
 185  * Send UN/LOCK_DS_REQ to MGMTD for a specific Datastore DS.
 186  *
 187  * lib_hndl
 188  *    Client library handler.
 189  *
 190  * session_id
 191  *    Client session ID.
 192  *
 193  * req_id
 194  *    Client request ID.
 195  *
 196  * ds_id
 197  *    Datastore ID (Running/Candidate/Oper/Startup)
 198  *
 199  * lock_ds
 200  *    TRUE for lock request, FALSE for unlock request.
 201  *
 202  * Returns:
 203  *    MGMTD_SUCCESS on success, MGMTD_* otherwise.
 204  */
 205 extern enum mgmt_result
 206 mgmt_fe_lock_ds(uintptr_t lib_hndl, uintptr_t session_id, uint64_t req_id,
 207                     Mgmtd__DatastoreId ds_id, bool lock_ds);
 208
 209 /*
 210  * Send SET_CONFIG_REQ to MGMTD for one or more config data(s).
 211  *
 212  * lib_hndl
 213  *    Client library handler.
 214  *
 215  * session_id
 216  *    Client session ID.
 217  *
 218  * req_id
 219  *    Client request ID.
 220  *
 221  * ds_id
 222  *    Datastore ID (Running/Candidate/Oper/Startup)
 223  *
 224  * conf_req
 225  *    Details regarding the SET_CONFIG_REQ.
 226  *
 227  * num_req
 228  *    Number of config requests.
 229  *
 230  * implcit commit
 231  *    TRUE for implicit commit, FALSE otherwise.
 232  *
 233  * dst_ds_id
 234  *    Destination Datastore ID where data needs to be set.
 235  *
 236  * Returns:
 237  *    MGMTD_SUCCESS on success, MGMTD_* otherwise.
 238  */
 239 extern enum mgmt_result
 240 mgmt_fe_set_config_data(uintptr_t lib_hndl, uintptr_t session_id,
 241                             uint64_t req_id, Mgmtd__DatastoreId ds_id,
 242                             Mgmtd__YangCfgDataReq **config_req, int num_req,
 243                             bool implicit_commit, Mgmtd__DatastoreId dst_ds_id);
 244
 245 /*
 246  * Send SET_COMMMIT_REQ to MGMTD for one or more config data(s).
 247  *
 248  * lib_hndl
 249  *    Client library handler.
 250  *
 251  * session_id
 252  *    Client session ID.
 253  *
 254  * req_id
 255  *    Client request ID.
 256  *
 257  * src_ds_id
 258  *    Source datastore ID from where data needs to be committed from.
 259  *
 260  * dst_ds_id
 261  *    Destination datastore ID where data needs to be committed to.
 262  *
 263  * validate_only
 264  *    TRUE if data needs to be validated only, FALSE otherwise.
 265  *
 266  * abort
 267  *    TRUE if need to restore Src DS back to Dest DS, FALSE otherwise.
 268  *
 269  * Returns:
 270  *    MGMTD_SUCCESS on success, MGMTD_* otherwise.
 271  */
 272 extern enum mgmt_result
 273 mgmt_fe_commit_config_data(uintptr_t lib_hndl, uintptr_t session_id,
 274                                uint64_t req_id, Mgmtd__DatastoreId src_ds_id,
 275                                Mgmtd__DatastoreId dst_ds_id, bool validate_only,
 276                                bool abort);
 277
 278 /*
 279  * Send GET_CONFIG_REQ to MGMTD for one or more config data item(s).
 280  *
 281  * lib_hndl
 282  *    Client library handler.
 283  *
 284  * session_id
 285  *    Client session ID.
 286  *
 287  * req_id
 288  *    Client request ID.
 289  *
 290  * ds_id
 291  *    Datastore ID (Running/Candidate)
 292  *
 293  * data_req
 294  *    Get config requested.
 295  *
 296  * num_req
 297  *    Number of get config requests.
 298  *
 299  * Returns:
 300  *    MGMTD_SUCCESS on success, MGMTD_* otherwise.
 301  */
 302 extern enum mgmt_result
 303 mgmt_fe_get_config_data(uintptr_t lib_hndl, uintptr_t session_id,
 304                             uint64_t req_id, Mgmtd__DatastoreId ds_id,
 305                             Mgmtd__YangGetDataReq **data_req, int num_reqs);
 306
 307 /*
 308  * Send GET_DATA_REQ to MGMTD for one or more data item(s).
 309  *
 310  * Similar to get config request but supports getting data
 311  * from operational ds aka backend clients directly.
 312  */
 313 extern enum mgmt_result
 314 mgmt_fe_get_data(uintptr_t lib_hndl, uintptr_t session_id, uint64_t req_id,
 315                      Mgmtd__DatastoreId ds_id, Mgmtd__YangGetDataReq **data_req,
 316                      int num_reqs);
 317
 318 /*
 319  * Send NOTIFY_REGISTER_REQ to MGMTD daemon.
 320  *
 321  * lib_hndl
 322  *    Client library handler.
 323  *
 324  * session_id
 325  *    Client session ID.
 326  *
 327  * req_id
 328  *    Client request ID.
 329  *
 330  * ds_id
 331  *    Datastore ID.
 332  *
 333  * register_req
 334  *    TRUE if registering, FALSE otherwise.
 335  *
 336  * data_req
 337  *    Details of the YANG notification data.
 338  *
 339  * num_reqs
 340  *    Number of data requests.
 341  *
 342  * Returns:
 343  *    MGMTD_SUCCESS on success, MGMTD_* otherwise.
 344  */
 345 extern enum mgmt_result
 346 mgmt_fe_register_yang_notify(uintptr_t lib_hndl, uintptr_t session_id,
 347                                  uint64_t req_id, Mgmtd__DatastoreId ds_id,
 348                                  bool register_req,
 349                                  Mgmtd__YangDataXPath **data_req, int num_reqs);
 350
 351 /*
 352  * Destroy library and cleanup everything.
 353  */
 354 extern void mgmt_fe_client_lib_destroy(uintptr_t lib_hndl);
 355
 356 #ifdef __cplusplus
 357 }
 358 #endif
 359
 360 #endif /* _FRR_MGMTD_FE_CLIENT_H_ */