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 "mgmtd/mgmt_defines.h"
  16 #include "mgmt_pb.h"
  17
  18 /***************************************************************
  19  * Macros
  20  ***************************************************************/
  21
  22 /*
  23  * The server port MGMTD daemon is listening for Backend Client
  24  * connections.
  25  */
  26
  27 #define MGMTD_FE_CLIENT_ERROR_STRING_MAX_LEN 32
  28
  29 #define MGMTD_FE_DEFAULT_CONN_RETRY_INTVL_SEC 5
  30
  31 #define MGMTD_FE_MSG_PROC_DELAY_USEC 10
  32 #define MGMTD_FE_MAX_NUM_MSG_PROC 500
  33
  34 #define MGMTD_FE_MSG_WRITE_DELAY_MSEC 1
  35 #define MGMTD_FE_MAX_NUM_MSG_WRITE 100
  36
  37 #define GMGD_FE_MAX_NUM_REQ_ITEMS 64
  38
  39 #define MGMTD_FE_MSG_MAX_LEN 9000
  40
  41 #define MGMTD_SOCKET_FE_SEND_BUF_SIZE 65535
  42 #define MGMTD_SOCKET_FE_RECV_BUF_SIZE MGMTD_SOCKET_FE_SEND_BUF_SIZE
  43
  44 /***************************************************************
  45  * Data-structures
  46  ***************************************************************/
  47
  48 #define MGMTD_SESSION_ID_NONE 0
  49
  50 #define MGMTD_CLIENT_ID_NONE 0
  51
  52 #define MGMTD_DS_NONE MGMTD__DATASTORE_ID__DS_NONE
  53 #define MGMTD_DS_RUNNING MGMTD__DATASTORE_ID__RUNNING_DS
  54 #define MGMTD_DS_CANDIDATE MGMTD__DATASTORE_ID__CANDIDATE_DS
  55 #define MGMTD_DS_OPERATIONAL MGMTD__DATASTORE_ID__OPERATIONAL_DS
  56 #define MGMTD_DS_MAX_ID MGMTD_DS_OPERATIONAL + 1
  57
  58 struct mgmt_fe_msg_hdr {
  59         uint16_t marker;
  60         uint16_t len; /* Includes header */
  61 };
  62 #define MGMTD_FE_MSG_HDR_LEN sizeof(struct mgmt_fe_msg_hdr)
  63 #define MGMTD_FE_MSG_MARKER 0xdeaf
  64
  65 struct mgmt_fe_msg {
  66         struct mgmt_fe_msg_hdr hdr;
  67         uint8_t payload[];
  68 };
  69
  70 /*
  71  * All the client specific information this library needs to
  72  * initialize itself, setup connection with MGMTD FrontEnd interface
  73  * and carry on all required procedures appropriately.
  74  *
  75  * FrontEnd clients need to initialise a instance of this structure
  76  * with appropriate data and pass it while calling the API
  77  * to initialize the library (See mgmt_fe_client_lib_init for
  78  * more details).
  79  */
  80 struct mgmt_fe_client_params {
  81         char name[MGMTD_CLIENT_NAME_MAX_LEN];
  82         uintptr_t user_data;
  83         unsigned long conn_retry_intvl_sec;
  84
  85         void (*client_connect_notify)(uintptr_t lib_hndl,
  86                                       uintptr_t user_data,
  87                                       bool connected);
  88
  89         void (*client_session_notify)(uintptr_t lib_hndl,
  90                                       uintptr_t user_data,
  91                                       uint64_t client_id,
  92                                       bool create, bool success,
  93                                       uintptr_t session_id,
  94                                       uintptr_t user_session_ctx);
  95
  96         void (*lock_ds_notify)(uintptr_t lib_hndl, uintptr_t user_data,
  97                                uint64_t client_id, uintptr_t session_id,
  98                                uintptr_t user_session_ctx, uint64_t req_id,
  99                                bool lock_ds, bool success,
 100                                Mgmtd__DatastoreId ds_id, char *errmsg_if_any);
 101
 102         void (*set_config_notify)(uintptr_t lib_hndl, uintptr_t user_data,
 103                                   uint64_t client_id, uintptr_t session_id,
 104                                   uintptr_t user_session_ctx, uint64_t req_id,
 105                                   bool success, Mgmtd__DatastoreId ds_id,
 106                                   char *errmsg_if_any);
 107
 108         void (*commit_config_notify)(
 109                 uintptr_t lib_hndl, uintptr_t user_data, uint64_t client_id,
 110                 uintptr_t session_id, uintptr_t user_session_ctx,
 111                 uint64_t req_id, bool success, Mgmtd__DatastoreId src_ds_id,
 112                 Mgmtd__DatastoreId dst_ds_id, bool validate_only,
 113                 char *errmsg_if_any);
 114
 115         enum mgmt_result (*get_data_notify)(
 116                 uintptr_t lib_hndl, uintptr_t user_data, uint64_t client_id,
 117                 uintptr_t session_id, uintptr_t user_session_ctx,
 118                 uint64_t req_id, bool success, Mgmtd__DatastoreId ds_id,
 119                 Mgmtd__YangData **yang_data, size_t num_data, int next_key,
 120                 char *errmsg_if_any);
 121
 122         enum mgmt_result (*data_notify)(
 123                 uint64_t client_id, uint64_t session_id, uintptr_t user_data,
 124                 uint64_t req_id, Mgmtd__DatastoreId ds_id,
 125                 Mgmtd__YangData **yang_data, size_t num_data);
 126 };
 127
 128 /***************************************************************
 129  * API prototypes
 130  ***************************************************************/
 131
 132 /*
 133  * Initialize library and try connecting with MGMTD FrontEnd interface.
 134  *
 135  * params
 136  *    Frontend client parameters.
 137  *
 138  * master_thread
 139  *    Thread master.
 140  *
 141  * Returns:
 142  *    Frontend client lib handler (nothing but address of mgmt_fe_client_ctx)
 143  */
 144 extern uintptr_t
 145 mgmt_fe_client_lib_init(struct mgmt_fe_client_params *params,
 146                             struct thread_master *master_thread);
 147
 148 /*
 149  * Create a new Session for a Frontend Client connection.
 150  *
 151  * lib_hndl
 152  *    Client library handler.
 153  *
 154  * client_id
 155  *    Unique identifier of client.
 156  *
 157  * user_ctx
 158  *    Client context.
 159  *
 160  * Returns:
 161  *    MGMTD_SUCCESS on success, MGMTD_* otherwise.
 162  */
 163 extern enum mgmt_result mgmt_fe_create_client_session(uintptr_t lib_hndl,
 164                                                           uint64_t client_id,
 165                                                           uintptr_t user_ctx);
 166
 167 /*
 168  * Delete an existing Session for a Frontend Client connection.
 169  *
 170  * lib_hndl
 171  *    Client library handler.
 172  *
 173  * client_id
 174  *    Unique identifier of client.
 175  *
 176  * Returns:
 177  *    MGMTD_SUCCESS on success, MGMTD_* otherwise.
 178  */
 179 extern enum mgmt_result mgmt_fe_destroy_client_session(uintptr_t lib_hndl,
 180                                                        uint64_t client_id);
 181
 182 /*
 183  * Send UN/LOCK_DS_REQ to MGMTD for a specific Datastore DS.
 184  *
 185  * lib_hndl
 186  *    Client library handler.
 187  *
 188  * session_id
 189  *    Client session ID.
 190  *
 191  * req_id
 192  *    Client request ID.
 193  *
 194  * ds_id
 195  *    Datastore ID (Running/Candidate/Oper/Startup)
 196  *
 197  * lock_ds
 198  *    TRUE for lock request, FALSE for unlock request.
 199  *
 200  * Returns:
 201  *    MGMTD_SUCCESS on success, MGMTD_* otherwise.
 202  */
 203 extern enum mgmt_result
 204 mgmt_fe_lock_ds(uintptr_t lib_hndl, uintptr_t session_id, uint64_t req_id,
 205                     Mgmtd__DatastoreId ds_id, bool lock_ds);
 206
 207 /*
 208  * Send SET_CONFIG_REQ to MGMTD for one or more config data(s).
 209  *
 210  * lib_hndl
 211  *    Client library handler.
 212  *
 213  * session_id
 214  *    Client session ID.
 215  *
 216  * req_id
 217  *    Client request ID.
 218  *
 219  * ds_id
 220  *    Datastore ID (Running/Candidate/Oper/Startup)
 221  *
 222  * conf_req
 223  *    Details regarding the SET_CONFIG_REQ.
 224  *
 225  * num_req
 226  *    Number of config requests.
 227  *
 228  * implcit commit
 229  *    TRUE for implicit commit, FALSE otherwise.
 230  *
 231  * dst_ds_id
 232  *    Destination Datastore ID where data needs to be set.
 233  *
 234  * Returns:
 235  *    MGMTD_SUCCESS on success, MGMTD_* otherwise.
 236  */
 237 extern enum mgmt_result
 238 mgmt_fe_set_config_data(uintptr_t lib_hndl, uintptr_t session_id,
 239                             uint64_t req_id, Mgmtd__DatastoreId ds_id,
 240                             Mgmtd__YangCfgDataReq **config_req, int num_req,
 241                             bool implicit_commit, Mgmtd__DatastoreId dst_ds_id);
 242
 243 /*
 244  * Send SET_COMMMIT_REQ to MGMTD for one or more config data(s).
 245  *
 246  * lib_hndl
 247  *    Client library handler.
 248  *
 249  * session_id
 250  *    Client session ID.
 251  *
 252  * req_id
 253  *    Client request ID.
 254  *
 255  * src_ds_id
 256  *    Source datastore ID from where data needs to be committed from.
 257  *
 258  * dst_ds_id
 259  *    Destination datastore ID where data needs to be committed to.
 260  *
 261  * validate_only
 262  *    TRUE if data needs to be validated only, FALSE otherwise.
 263  *
 264  * abort
 265  *    TRUE if need to restore Src DS back to Dest DS, FALSE otherwise.
 266  *
 267  * Returns:
 268  *    MGMTD_SUCCESS on success, MGMTD_* otherwise.
 269  */
 270 extern enum mgmt_result
 271 mgmt_fe_commit_config_data(uintptr_t lib_hndl, uintptr_t session_id,
 272                                uint64_t req_id, Mgmtd__DatastoreId src_ds_id,
 273                                Mgmtd__DatastoreId dst_ds_id, bool validate_only,
 274                                bool abort);
 275
 276 /*
 277  * Send GET_CONFIG_REQ to MGMTD for one or more config data item(s).
 278  *
 279  * lib_hndl
 280  *    Client library handler.
 281  *
 282  * session_id
 283  *    Client session ID.
 284  *
 285  * req_id
 286  *    Client request ID.
 287  *
 288  * ds_id
 289  *    Datastore ID (Running/Candidate)
 290  *
 291  * data_req
 292  *    Get config requested.
 293  *
 294  * num_req
 295  *    Number of get config requests.
 296  *
 297  * Returns:
 298  *    MGMTD_SUCCESS on success, MGMTD_* otherwise.
 299  */
 300 extern enum mgmt_result
 301 mgmt_fe_get_config_data(uintptr_t lib_hndl, uintptr_t session_id,
 302                             uint64_t req_id, Mgmtd__DatastoreId ds_id,
 303                             Mgmtd__YangGetDataReq **data_req, int num_reqs);
 304
 305 /*
 306  * Send GET_DATA_REQ to MGMTD for one or more data item(s).
 307  *
 308  * Similar to get config request but supports getting data
 309  * from operational ds aka backend clients directly.
 310  */
 311 extern enum mgmt_result
 312 mgmt_fe_get_data(uintptr_t lib_hndl, uintptr_t session_id, uint64_t req_id,
 313                      Mgmtd__DatastoreId ds_id, Mgmtd__YangGetDataReq **data_req,
 314                      int num_reqs);
 315
 316 /*
 317  * Send NOTIFY_REGISTER_REQ to MGMTD daemon.
 318  *
 319  * lib_hndl
 320  *    Client library handler.
 321  *
 322  * session_id
 323  *    Client session ID.
 324  *
 325  * req_id
 326  *    Client request ID.
 327  *
 328  * ds_id
 329  *    Datastore ID.
 330  *
 331  * register_req
 332  *    TRUE if registering, FALSE otherwise.
 333  *
 334  * data_req
 335  *    Details of the YANG notification data.
 336  *
 337  * num_reqs
 338  *    Number of data requests.
 339  *
 340  * Returns:
 341  *    MGMTD_SUCCESS on success, MGMTD_* otherwise.
 342  */
 343 extern enum mgmt_result
 344 mgmt_fe_register_yang_notify(uintptr_t lib_hndl, uintptr_t session_id,
 345                                  uint64_t req_id, Mgmtd__DatastoreId ds_id,
 346                                  bool register_req,
 347                                  Mgmtd__YangDataXPath **data_req, int num_reqs);
 348
 349 /*
 350  * Destroy library and cleanup everything.
 351  */
 352 extern void mgmt_fe_client_lib_destroy(uintptr_t lib_hndl);
 353
 354 #ifdef __cplusplus
 355 }
 356 #endif
 357
 358 #endif /* _FRR_MGMTD_FE_CLIENT_H_ */