[mirror_frr.git] / lib / mgmt_be_client.h

// 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 "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,
#if 0 /* example */
#ifdef HAVE_STATICD
	MGMTD_BE_CLIENT_ID_STATICD,
#endif
#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_msg_hdr {
	uint16_t marker;
	uint16_t len; /* Includes header */
};
#define MGMTD_BE_MSG_HDR_LEN sizeof(struct mgmt_be_msg_hdr)
#define MGMTD_BE_MSG_MARKER 0xfeed

struct mgmt_be_msg {
	struct mgmt_be_msg_hdr hdr;
	uint8_t payload[];
};

struct mgmt_be_client_txn_ctx {
	uintptr_t *user_ctx;
};

/*
 * All the client-specific information this library needs to
 * initialize itself, setup connection with MGMTD BackEnd interface
 * and carry on all required procedures appropriately.
 *
 * BackEnd clients need to initialise a instance of this structure
 * with appropriate data and pass it while calling the API
 * to initialize the library (See mgmt_be_client_lib_init for
 * more details).
 */
struct mgmt_be_client_params {
	char name[MGMTD_CLIENT_NAME_MAX_LEN];
	uintptr_t user_data;
	unsigned long conn_retry_intvl_sec;

	void (*client_connect_notify)(uintptr_t lib_hndl,
				      uintptr_t usr_data,
				      bool connected);

	void (*client_subscribe_notify)(
		uintptr_t lib_hndl, uintptr_t usr_data,
		struct nb_yang_xpath **xpath,
		enum mgmt_result subscribe_result[], int num_paths);

	void (*txn_notify)(
		uintptr_t lib_hndl, uintptr_t usr_data,
		struct mgmt_be_client_txn_ctx *txn_ctx, bool destroyed);

	enum mgmt_result (*data_validate)(
		uintptr_t lib_hndl, uintptr_t usr_data,
		struct mgmt_be_client_txn_ctx *txn_ctx,
		struct nb_yang_xpath *xpath, struct nb_yang_value *data,
		bool delete, char *error_if_any);

	enum mgmt_result (*data_apply)(
		uintptr_t lib_hndl, uintptr_t usr_data,
		struct mgmt_be_client_txn_ctx *txn_ctx,
		struct nb_yang_xpath *xpath, struct nb_yang_value *data,
		bool delete);

	enum mgmt_result (*get_data_elem)(
		uintptr_t lib_hndl, uintptr_t usr_data,
		struct mgmt_be_client_txn_ctx *txn_ctx,
		struct nb_yang_xpath *xpath, struct nb_yang_xpath_elem *elem);

	enum mgmt_result (*get_data)(
		uintptr_t lib_hndl, uintptr_t usr_data,
		struct mgmt_be_client_txn_ctx *txn_ctx,
		struct nb_yang_xpath *xpath, bool keys_only,
		struct nb_yang_xpath_elem **elems, int *num_elems,
		int *next_key);

	enum mgmt_result (*get_next_data)(
		uintptr_t lib_hndl, uintptr_t usr_data,
		struct mgmt_be_client_txn_ctx *txn_ctx,
		struct nb_yang_xpath *xpath, bool keys_only,
		struct nb_yang_xpath_elem **elems, int *num_elems);
};

/***************************************************************
 * 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;
}

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

/*
 * Initialize library and try connecting with MGMTD.
 *
 * params
 *    Backend client parameters.
 *
 * master_thread
 *    Thread master.
 *
 * Returns:
 *    Backend client lib handler (nothing but address of mgmt_be_client_ctx)
 */
extern uintptr_t
mgmt_be_client_lib_init(struct mgmt_be_client_params *params,
			   struct thread_master *master_thread);

/*
 * Subscribe with MGMTD for one or more YANG subtree(s).
 *
 * lib_hndl
 *    Client library handler.
 *
 * reg_yang_xpaths
 *    Yang xpath(s) that needs to be subscribed to.
 *
 * num_xpaths
 *    Number of xpaths
 *
 * Returns:
 *    MGMTD_SUCCESS on success, MGMTD_* otherwise.
 */
extern enum mgmt_result mgmt_be_subscribe_yang_data(uintptr_t lib_hndl,
						       char **reg_yang_xpaths,
						       int num_xpaths);

/*
 * Send one or more YANG notifications to MGMTD daemon.
 *
 * lib_hndl
 *    Client library handler.
 *
 * data_elems
 *    Yang data elements from data tree.
 *
 * num_elems
 *    Number of data elements.
 *
 * Returns:
 *    MGMTD_SUCCESS on success, MGMTD_* otherwise.
 */
extern enum mgmt_result
mgmt_be_send_yang_notify(uintptr_t lib_hndl, Mgmtd__YangData **data_elems,
			    int num_elems);

/*
 * Un-subscribe with MGMTD for one or more YANG subtree(s).
 *
 * lib_hndl
 *    Client library handler.
 *
 * reg_yang_xpaths
 *    Yang xpath(s) that needs to be un-subscribed from.
 *
 * num_reg_xpaths
 *    Number of subscribed xpaths
 *
 * Returns:
 *    MGMTD_SUCCESS on success, MGMTD_* otherwise.
 */
enum mgmt_result mgmt_be_unsubscribe_yang_data(uintptr_t lib_hndl,
						  char **reg_yang_xpaths,
						  int num_reg_xpaths);

/*
 * Destroy library and cleanup everything.
 */
extern void mgmt_be_client_lib_destroy(uintptr_t lib_hndl);

#ifdef __cplusplus
}
#endif

#endif /* _FRR_MGMTD_BE_CLIENT_H_ */
Commit	Line	Data
7d65b7b7 CH	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 "mgmtd/mgmt_defines.h"
	16
	17	/***************************************************************
	18	* Client IDs
	19	***************************************************************/
	20
	21	/*
	22	* Add enum value for each supported component, wrap with
	23	* #ifdef HAVE_COMPONENT
	24	*/
	25	enum mgmt_be_client_id {
	26	MGMTD_BE_CLIENT_ID_MIN = 0,
	27	MGMTD_BE_CLIENT_ID_INIT = -1,
	28	#if 0 /* example */
	29	#ifdef HAVE_STATICD
	30	MGMTD_BE_CLIENT_ID_STATICD,
	31	#endif
	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_msg_hdr {
86	uint16_t marker;
87	uint16_t len; /* Includes header */
88	};
89	#define MGMTD_BE_MSG_HDR_LEN sizeof(struct mgmt_be_msg_hdr)
90	#define MGMTD_BE_MSG_MARKER 0xfeed
91
92	struct mgmt_be_msg {
93	struct mgmt_be_msg_hdr hdr;
94	uint8_t payload[];
95	};
96
97	struct mgmt_be_client_txn_ctx {
98	uintptr_t *user_ctx;
99	};
100
101	/*
102	* All the client-specific information this library needs to
103	* initialize itself, setup connection with MGMTD BackEnd interface
104	* and carry on all required procedures appropriately.
105	*
106	* BackEnd clients need to initialise a instance of this structure
107	* with appropriate data and pass it while calling the API
108	* to initialize the library (See mgmt_be_client_lib_init for
109	* more details).
110	*/
111	struct mgmt_be_client_params {
112	char name[MGMTD_CLIENT_NAME_MAX_LEN];
113	uintptr_t user_data;
114	unsigned long conn_retry_intvl_sec;
115
116	void (*client_connect_notify)(uintptr_t lib_hndl,
117	uintptr_t usr_data,
118	bool connected);
119
120	void (*client_subscribe_notify)(
121	uintptr_t lib_hndl, uintptr_t usr_data,
122	struct nb_yang_xpath **xpath,
123	enum mgmt_result subscribe_result[], int num_paths);
124
125	void (*txn_notify)(
126	uintptr_t lib_hndl, uintptr_t usr_data,
127	struct mgmt_be_client_txn_ctx *txn_ctx, bool destroyed);
128
129	enum mgmt_result (*data_validate)(
130	uintptr_t lib_hndl, uintptr_t usr_data,
131	struct mgmt_be_client_txn_ctx *txn_ctx,
132	struct nb_yang_xpath xpath, struct nb_yang_value data,
133	bool delete, char *error_if_any);
134
135	enum mgmt_result (*data_apply)(
136	uintptr_t lib_hndl, uintptr_t usr_data,
137	struct mgmt_be_client_txn_ctx *txn_ctx,
138	struct nb_yang_xpath xpath, struct nb_yang_value data,
139	bool delete);
140
141	enum mgmt_result (*get_data_elem)(
142	uintptr_t lib_hndl, uintptr_t usr_data,
143	struct mgmt_be_client_txn_ctx *txn_ctx,
144	struct nb_yang_xpath xpath, struct nb_yang_xpath_elem elem);
145
146	enum mgmt_result (*get_data)(
147	uintptr_t lib_hndl, uintptr_t usr_data,
148	struct mgmt_be_client_txn_ctx *txn_ctx,
149	struct nb_yang_xpath *xpath, bool keys_only,
150	struct nb_yang_xpath_elem *elems, int num_elems,
151	int *next_key);
152
153	enum mgmt_result (*get_next_data)(
154	uintptr_t lib_hndl, uintptr_t usr_data,
155	struct mgmt_be_client_txn_ctx *txn_ctx,
156	struct nb_yang_xpath *xpath, bool keys_only,
157	struct nb_yang_xpath_elem *elems, int num_elems);
158	};
159
160	/***************************************************************
161	* Global data exported
162	***************************************************************/
163
164	extern const char *mgmt_be_client_names[MGMTD_BE_CLIENT_ID_MAX + 1];
165
166	static inline const char *mgmt_be_client_id2name(enum mgmt_be_client_id id)
167	{
168	if (id > MGMTD_BE_CLIENT_ID_MAX)
169	id = MGMTD_BE_CLIENT_ID_MAX;
170	return mgmt_be_client_names[id];
171	}
172
173	static inline enum mgmt_be_client_id
174	mgmt_be_client_name2id(const char *name)
175	{
176	enum mgmt_be_client_id id;
177
178	FOREACH_MGMTD_BE_CLIENT_ID (id) {
179	if (!strncmp(mgmt_be_client_names[id], name,
180	MGMTD_CLIENT_NAME_MAX_LEN))
181	return id;
182	}
183
184	return MGMTD_BE_CLIENT_ID_MAX;
185	}
186
187	/***************************************************************
188	* API prototypes
189	***************************************************************/
190
191	/*
192	* Initialize library and try connecting with MGMTD.
193	*
194	* params
195	* Backend client parameters.
196	*
197	* master_thread
198	* Thread master.
199	*
200	* Returns:
201	* Backend client lib handler (nothing but address of mgmt_be_client_ctx)
202	*/
203	extern uintptr_t
204	mgmt_be_client_lib_init(struct mgmt_be_client_params *params,
205	struct thread_master *master_thread);
206
207	/*
208	* Subscribe with MGMTD for one or more YANG subtree(s).
209	*
210	* lib_hndl
211	* Client library handler.
212	*
213	* reg_yang_xpaths
214	* Yang xpath(s) that needs to be subscribed to.
215	*
216	* num_xpaths
217	* Number of xpaths
218	*
219	* Returns:
220	* MGMTD_SUCCESS on success, MGMTD_* otherwise.
221	*/
222	extern enum mgmt_result mgmt_be_subscribe_yang_data(uintptr_t lib_hndl,
223	char **reg_yang_xpaths,
224	int num_xpaths);
225
226	/*
227	* Send one or more YANG notifications to MGMTD daemon.
228	*
229	* lib_hndl
230	* Client library handler.
231	*
232	* data_elems
233	* Yang data elements from data tree.
234	*
235	* num_elems
236	* Number of data elements.
237	*
238	* Returns:
239	* MGMTD_SUCCESS on success, MGMTD_* otherwise.
240	*/
241	extern enum mgmt_result
242	mgmt_be_send_yang_notify(uintptr_t lib_hndl, Mgmtd__YangData **data_elems,
243	int num_elems);
244
245	/*
246	* Un-subscribe with MGMTD for one or more YANG subtree(s).
247	*
248	* lib_hndl
249	* Client library handler.
250	*
251	* reg_yang_xpaths
252	* Yang xpath(s) that needs to be un-subscribed from.
253	*
254	* num_reg_xpaths
255	* Number of subscribed xpaths
256	*
257	* Returns:
258	* MGMTD_SUCCESS on success, MGMTD_* otherwise.
259	*/
260	enum mgmt_result mgmt_be_unsubscribe_yang_data(uintptr_t lib_hndl,
261	char **reg_yang_xpaths,
262	int num_reg_xpaths);
263
264	/*
265	* Destroy library and cleanup everything.
266	*/
267	extern void mgmt_be_client_lib_destroy(uintptr_t lib_hndl);
268
269	#ifdef __cplusplus
270	}
271	#endif
272
273	#endif /* _FRR_MGMTD_BE_CLIENT_H_ */