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