/src/frr/lib/mgmt_be_client.h

Source
// SPDX-License-Identifier: GPL-2.0-or-later
/*
 * MGMTD Backend Client Library api interfaces
 * Copyright (C) 2021  Vmware, Inc.
 *           Pushpasis Sarkar <spushpasis@vmware.com>
 */

#ifndef _FRR_MGMTD_BE_CLIENT_H_
#define _FRR_MGMTD_BE_CLIENT_H_

#ifdef __cplusplus
extern "C" {
#endif

#include "northbound.h"
#include "mgmt_pb.h"
#include "mgmtd/mgmt_defines.h"

/***************************************************************
 * Client IDs
 ***************************************************************/

/*
 * Add enum value for each supported component, wrap with
 * #ifdef HAVE_COMPONENT
 */
enum mgmt_be_client_id {
  MGMTD_BE_CLIENT_ID_MIN = 0,
  MGMTD_BE_CLIENT_ID_INIT = -1,
#ifdef HAVE_STATICD
  MGMTD_BE_CLIENT_ID_STATICD,
#endif
  MGMTD_BE_CLIENT_ID_MAX
};

#define FOREACH_MGMTD_BE_CLIENT_ID(id)      \
  for ((id) = MGMTD_BE_CLIENT_ID_MIN;   \
       (id) < MGMTD_BE_CLIENT_ID_MAX; (id)++)

/***************************************************************
 * Constants
 ***************************************************************/

#define MGMTD_BE_CLIENT_ERROR_STRING_MAX_LEN 32

#define MGMTD_BE_DEFAULT_CONN_RETRY_INTVL_SEC 5

#define MGMTD_BE_MSG_PROC_DELAY_USEC 10
#define MGMTD_BE_MAX_NUM_MSG_PROC 500

#define MGMTD_BE_MSG_WRITE_DELAY_MSEC 1
#define MGMTD_BE_MAX_NUM_MSG_WRITE 1000

#define GMGD_BE_MAX_NUM_REQ_ITEMS 64

#define MGMTD_BE_MSG_MAX_LEN 16384

#define MGMTD_SOCKET_BE_SEND_BUF_SIZE 65535
#define MGMTD_SOCKET_BE_RECV_BUF_SIZE MGMTD_SOCKET_BE_SEND_BUF_SIZE

#define MGMTD_MAX_CFG_CHANGES_IN_BATCH        \
  ((10 * MGMTD_BE_MSG_MAX_LEN) /       \
   (MGMTD_MAX_XPATH_LEN + MGMTD_MAX_YANG_VALUE_LEN))

/*
 * MGMTD_BE_MSG_MAX_LEN must be used 80%
 * since there is overhead of google protobuf
 * that gets added to sent message
 */
#define MGMTD_BE_CFGDATA_PACKING_EFFICIENCY 0.8
#define MGMTD_BE_CFGDATA_MAX_MSG_LEN                                        \
  (MGMTD_BE_MSG_MAX_LEN * MGMTD_BE_CFGDATA_PACKING_EFFICIENCY)

#define MGMTD_BE_MAX_BATCH_IDS_IN_REQ                                       \
  (MGMTD_BE_MSG_MAX_LEN - 128) / sizeof(uint64_t)

#define MGMTD_BE_CONTAINER_NODE_VAL "<<container>>"

/***************************************************************
 * Data-structures
 ***************************************************************/

#define MGMTD_BE_MAX_CLIENTS_PER_XPATH_REG 32

struct mgmt_be_client;

struct mgmt_be_client_txn_ctx {
  uintptr_t *user_ctx;
};

/**
 * Backend client callbacks.
 *
 * Callbacks:
 *  client_connect_notify: called when connection is made/lost to mgmtd.
 *  txn_notify: called when a txn has been created
 */
struct mgmt_be_client_cbs {
  void (*client_connect_notify)(struct mgmt_be_client *client,
              uintptr_t usr_data, bool connected);

  void (*txn_notify)(struct mgmt_be_client *client, uintptr_t usr_data,
         struct mgmt_be_client_txn_ctx *txn_ctx,
         bool destroyed);
};

/***************************************************************
 * Global data exported
 ***************************************************************/

extern const char *mgmt_be_client_names[MGMTD_BE_CLIENT_ID_MAX + 1];

static inline const char *mgmt_be_client_id2name(enum mgmt_be_client_id id)
{
  if (id > MGMTD_BE_CLIENT_ID_MAX)
    id = MGMTD_BE_CLIENT_ID_MAX;
  return mgmt_be_client_names[id];
}

static inline enum mgmt_be_client_id
mgmt_be_client_name2id(const char *name)
{
  enum mgmt_be_client_id id;

  FOREACH_MGMTD_BE_CLIENT_ID (id) {
    if (!strncmp(mgmt_be_client_names[id], name,
           MGMTD_CLIENT_NAME_MAX_LEN))
      return id;
  }

  return MGMTD_BE_CLIENT_ID_MAX;
}

extern struct debug mgmt_dbg_be_client;

/***************************************************************
 * API prototypes
 ***************************************************************/

#define MGMTD_BE_CLIENT_DBG(fmt, ...)                                          \
  DEBUGD(&mgmt_dbg_be_client, "BE-CLIENT: %s: " fmt, __func__,           \
         ##__VA_ARGS__)
#define MGMTD_BE_CLIENT_ERR(fmt, ...)                                          \
  zlog_err("BE-CLIENT: %s: ERROR: " fmt, __func__, ##__VA_ARGS__)
#define MGMTD_DBG_BE_CLIENT_CHECK()                                            \
  DEBUG_MODE_CHECK(&mgmt_dbg_be_client, DEBUG_MODE_ALL)

/**
 * Create backend client and connect to MGMTD.
 *
 * Args:
 *  client_name: the name of the client
 *  cbs: callbacks for various events.
 *  event_loop: the main event loop.
 *
 * Returns:
 *    Backend client object.
 */
extern struct mgmt_be_client *
mgmt_be_client_create(const char *name, struct mgmt_be_client_cbs *cbs,
          uintptr_t user_data, struct event_loop *event_loop);

/*
 * Initialize library vty (adds debug support).
 *
 * This call should be added to your component when enabling other vty code to
 * enable mgmtd client debugs. When adding, one needs to also add a their
 * component in `xref2vtysh.py` as well.
 */
extern void mgmt_be_client_lib_vty_init(void);

/*
 * Print enabled debugging commands.
 */
extern void mgmt_debug_be_client_show_debug(struct vty *vty);

/*
 * [Un]-subscribe with MGMTD for one or more YANG subtree(s).
 *
 * client
 *    The client object.
 *
 * reg_yang_xpaths
 *    Yang xpath(s) that needs to be [un]-subscribed from/to
 *
 * num_xpaths
 *    Number of xpaths
 *
 * Returns:
 *    MGMTD_SUCCESS on success, MGMTD_* otherwise.
 */
extern int mgmt_be_send_subscr_req(struct mgmt_be_client *client,
           bool subscr_xpaths, int num_xpaths,
           char **reg_xpaths);

/*
 * Destroy backend client and cleanup everything.
 */
extern void mgmt_be_client_destroy(struct mgmt_be_client *client);

#ifdef __cplusplus
}
#endif

#endif /* _FRR_MGMTD_BE_CLIENT_H_ */

Coverage Report

Created: 2025-10-23 06:55

Line	Count	Source
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	0	#define MGMTD_BE_MAX_NUM_MSG_PROC 500
50
51		#define MGMTD_BE_MSG_WRITE_DELAY_MSEC 1
52	0	#define MGMTD_BE_MAX_NUM_MSG_WRITE 1000
53
54		#define GMGD_BE_MAX_NUM_REQ_ITEMS 64
55
56	0	#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	0	((10 * MGMTD_BE_MSG_MAX_LEN) / \
63	0	(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	0	(MGMTD_BE_MSG_MAX_LEN - 128) / sizeof(uint64_t)
76
77	0	#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	0	{
115	0	if (id > MGMTD_BE_CLIENT_ID_MAX)
116	0	id = MGMTD_BE_CLIENT_ID_MAX;
117	0	return mgmt_be_client_names[id];
118	0	} Unexecuted instantiation: command.c:mgmt_be_client_id2name Unexecuted instantiation: mgmt_be_client.c:mgmt_be_client_id2name
119
120		static inline enum mgmt_be_client_id
121		mgmt_be_client_name2id(const char *name)
122	0	{
123	0	enum mgmt_be_client_id id;
124	0
125	0	FOREACH_MGMTD_BE_CLIENT_ID (id) {
126	0	if (!strncmp(mgmt_be_client_names[id], name,
127	0	MGMTD_CLIENT_NAME_MAX_LEN))
128	0	return id;
129	0	}
130	0
131	0	return MGMTD_BE_CLIENT_ID_MAX;
132	0	} Unexecuted instantiation: command.c:mgmt_be_client_name2id Unexecuted instantiation: mgmt_be_client.c:mgmt_be_client_name2id
133
134		extern struct debug mgmt_dbg_be_client;
135
136		/***************************************************************
137		* API prototypes
138		***************************************************************/
139
140		#define MGMTD_BE_CLIENT_DBG(fmt, ...) \
141	0	DEBUGD(&mgmt_dbg_be_client, "BE-CLIENT: %s: " fmt, __func__, \
142	0	##__VA_ARGS__)
143		#define MGMTD_BE_CLIENT_ERR(fmt, ...) \
144	0	zlog_err("BE-CLIENT: %s: ERROR: " fmt, __func__, ##__VA_ARGS__)
145		#define MGMTD_DBG_BE_CLIENT_CHECK() \
146	0	DEBUG_MODE_CHECK(&mgmt_dbg_be_client, DEBUG_MODE_ALL)
147
148		/**
149		* Create backend client and connect to MGMTD.
150		*
151		* Args:
152		* client_name: the name of the client
153		* cbs: callbacks for various events.
154		* event_loop: the main event loop.
155		*
156		* Returns:
157		* Backend client object.
158		*/
159		extern struct mgmt_be_client *
160		mgmt_be_client_create(const char name, struct mgmt_be_client_cbs cbs,
161		uintptr_t user_data, struct event_loop *event_loop);
162
163		/*
164		* Initialize library vty (adds debug support).
165		*
166		* This call should be added to your component when enabling other vty code to
167		* enable mgmtd client debugs. When adding, one needs to also add a their
168		* component in `xref2vtysh.py` as well.
169		*/
170		extern void mgmt_be_client_lib_vty_init(void);
171
172		/*
173		* Print enabled debugging commands.
174		*/
175		extern void mgmt_debug_be_client_show_debug(struct vty *vty);
176
177		/*
178		* [Un]-subscribe with MGMTD for one or more YANG subtree(s).
179		*
180		* client
181		* The client object.
182		*
183		* reg_yang_xpaths
184		* Yang xpath(s) that needs to be [un]-subscribed from/to
185		*
186		* num_xpaths
187		* Number of xpaths
188		*
189		* Returns:
190		* MGMTD_SUCCESS on success, MGMTD_* otherwise.
191		*/
192		extern int mgmt_be_send_subscr_req(struct mgmt_be_client *client,
193		bool subscr_xpaths, int num_xpaths,
194		char **reg_xpaths);
195
196		/*
197		* Destroy backend client and cleanup everything.
198		*/
199		extern void mgmt_be_client_destroy(struct mgmt_be_client *client);
200
201		#ifdef __cplusplus
202		}
203		#endif
204
205		#endif /* _FRR_MGMTD_BE_CLIENT_H_ */