1 /*
2  * Copyright (c) 2006-2019 Red Hat, Inc.
3  *
4  * All rights reserved.
5  *
6  * Author: Christine Caulfield (ccaulfi@redhat.com)
7  * Author: Jan Friesse (jfriesse@redhat.com)
8  *
9  * This software licensed under BSD license, the text of which follows:
10  *
11  * Redistribution and use in source and binary forms, with or without
12  * modification, are permitted provided that the following conditions are met:
13  *
14  * - Redistributions of source code must retain the above copyright notice,
15  *   this list of conditions and the following disclaimer.
16  * - Redistributions in binary form must reproduce the above copyright notice,
17  *   this list of conditions and the following disclaimer in the documentation
18  *   and/or other materials provided with the distribution.
19  * - Neither the name of the MontaVista Software, Inc. nor the names of its
20  *   contributors may be used to endorse or promote products derived from this
21  *   software without specific prior written permission.
22  *
23  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
24  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
25  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
26  * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
27  * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
28  * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
29  * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
30  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
31  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
32  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
33  * THE POSSIBILITY OF SUCH DAMAGE.
34  */
35 #ifndef COROSYNC_CPG_H_DEFINED
36 #define COROSYNC_CPG_H_DEFINED
37 
38 #include <netinet/in.h>
39 #include <corosync/corotypes.h>
40 
41 #ifdef __cplusplus
42 extern "C" {
43 #endif
44 
45 /**
46  * @addtogroup cpg_corosync
47  *
48  * @{
49  */
50 /**
51  * @brief cpg_handle_t
52  */
53 typedef uint64_t cpg_handle_t;
54 
55 /**
56  * @brief cpg_iteration_handle_t
57  */
58 typedef uint64_t cpg_iteration_handle_t;
59 
60 /**
61  * @brief The cpg_guarantee_t enum
62  */
63 typedef enum {
64 	CPG_TYPE_UNORDERED, /**< not implemented */
65 	CPG_TYPE_FIFO,      /**< same as agreed */
66 	CPG_TYPE_AGREED,
67 	CPG_TYPE_SAFE       /**< not implemented */
68 } cpg_guarantee_t;
69 
70 /**
71  * @brief The cpg_flow_control_state_t enum
72  */
73 typedef enum {
74 	CPG_FLOW_CONTROL_DISABLED, /**< flow control is disabled - new messages may be sent */
75 	CPG_FLOW_CONTROL_ENABLED   /**< flow control is enabled - new messages should not be sent */
76 } cpg_flow_control_state_t;
77 
78 
79 /**
80  * @brief The cpg_reason_t enum
81  */
82 typedef enum {
83 	CPG_REASON_UNDEFINED = 0,
84 	CPG_REASON_JOIN = 1,
85 	CPG_REASON_LEAVE = 2,
86 	CPG_REASON_NODEDOWN = 3,
87 	CPG_REASON_NODEUP = 4,
88 	CPG_REASON_PROCDOWN = 5
89 } cpg_reason_t;
90 
91 /**
92  * @brief The cpg_iteration_type_t enum
93  */
94 typedef enum {
95 	CPG_ITERATION_NAME_ONLY = 1,
96 	CPG_ITERATION_ONE_GROUP = 2,
97 	CPG_ITERATION_ALL = 3,
98 } cpg_iteration_type_t;
99 
100 /**
101  * @brief The cpg_model_t enum
102  */
103 typedef enum {
104 	CPG_MODEL_V1 = 1,
105 } cpg_model_t;
106 
107 /**
108  * @brief The cpg_address struct
109  */
110 struct cpg_address {
111 	uint32_t nodeid;
112 	uint32_t pid;
113 	uint32_t reason;
114 };
115 
116 #define CPG_MAX_NAME_LENGTH 128
117 /**
118  * @brief The cpg_name struct
119  */
120 struct cpg_name {
121 	uint32_t length;
122 	char value[CPG_MAX_NAME_LENGTH];
123 };
124 
125 #define CPG_MEMBERS_MAX 128
126 
127 /**
128  * @brief The cpg_iteration_description_t struct
129  */
130 struct cpg_iteration_description_t {
131 	struct cpg_name group;
132 	uint32_t nodeid;
133 	uint32_t pid;
134 };
135 
136 /**
137  * @brief The cpg_ring_id struct
138  */
139 struct cpg_ring_id {
140 	uint32_t nodeid;
141 	uint64_t seq;
142 };
143 
144 /**
145  * @brief The cpg_deliver_fn_t callback
146  */
147 typedef void (*cpg_deliver_fn_t) (
148 	cpg_handle_t handle,
149 	const struct cpg_name *group_name,
150 	uint32_t nodeid,
151 	uint32_t pid,
152 	/**
153 	 * Unlike many "msg" pointers, this one is deliberately *not*
154 	 * declared const in order to permit in-place endian conversion.
155 	 */
156 	void *msg,
157 	size_t msg_len);
158 
159 /**
160  * @brief The cpg_confchg_fn_t callback
161  */
162 typedef void (*cpg_confchg_fn_t) (
163 	cpg_handle_t handle,
164 	const struct cpg_name *group_name,
165 	const struct cpg_address *member_list, size_t member_list_entries,
166 	const struct cpg_address *left_list, size_t left_list_entries,
167 	const struct cpg_address *joined_list, size_t joined_list_entries);
168 
169 /**
170  * @brief The cpg_totem_confchg_fn_t callback
171  */
172 typedef void (*cpg_totem_confchg_fn_t) (
173 	cpg_handle_t handle,
174 	struct cpg_ring_id ring_id,
175 	uint32_t member_list_entries,
176 	const uint32_t *member_list);
177 
178 /**
179  * @brief The cpg_callbacks_t struct
180  */
181 typedef struct {
182 	cpg_deliver_fn_t cpg_deliver_fn;
183 	cpg_confchg_fn_t cpg_confchg_fn;
184 } cpg_callbacks_t;
185 
186 /**
187  * @brief The cpg_model_data_t struct
188  */
189 typedef struct {
190 	cpg_model_t model;
191 } cpg_model_data_t;
192 
193 #define CPG_MODEL_V1_DELIVER_INITIAL_TOTEM_CONF 0x01
194 
195 /**
196  * @brief The cpg_model_v1_data_t struct
197  */
198 typedef struct {
199 	cpg_model_t model;
200 	cpg_deliver_fn_t cpg_deliver_fn;
201 	cpg_confchg_fn_t cpg_confchg_fn;
202 	cpg_totem_confchg_fn_t cpg_totem_confchg_fn;
203 	unsigned int flags;
204 } cpg_model_v1_data_t;
205 
206 
207 /** @} */
208 
209 /**
210  * @brief Create a new cpg connection
211  * @param handle
212  * @param callbacks
213  * @return
214  */
215 cs_error_t cpg_initialize (
216 	cpg_handle_t *handle,
217 	cpg_callbacks_t *callbacks);
218 
219 /**
220  * @brief Create a new cpg connection, initialize with model
221  * @param handle
222  * @param model
223  * @param model_data
224  * @param context
225  * @return
226  */
227 cs_error_t cpg_model_initialize (
228 	cpg_handle_t *handle,
229 	cpg_model_t model,
230 	cpg_model_data_t *model_data,
231 	void *context);
232 
233 /**
234  * @brief Close the cpg handle
235  * @param handle
236  * @return
237  */
238 cs_error_t cpg_finalize (
239 	cpg_handle_t handle);
240 
241 /**
242  * @brief Get a file descriptor on which to poll.
243  *
244  * cpg_handle_t is NOT a file descriptor and may not be used directly.
245  *
246  * @param handle
247  * @param fd
248  * @return
249  */
250 cs_error_t cpg_fd_get (
251 	cpg_handle_t handle,
252 	int *fd);
253 
254 /**
255  * @brief Get maximum size of a message that will not be fragmented
256  * @param handle
257  * @param size
258  * @return
259  */
260 cs_error_t cpg_max_atomic_msgsize_get (
261 	cpg_handle_t handle,
262 	uint32_t *size);
263 
264 /**
265  * @brief Get contexts for a CPG handle
266  * @param handle
267  * @param context
268  * @return
269  */
270 cs_error_t cpg_context_get (
271 	cpg_handle_t handle,
272 	void **context);
273 
274 /**
275  * @brief Set contexts for a CPG handle
276  * @param handle
277  * @param context
278  * @return
279  */
280 cs_error_t cpg_context_set (
281 	cpg_handle_t handle,
282 	void *context);
283 
284 /**
285  * @brief  Dispatch messages and configuration changes
286  * @param handle
287  * @param dispatch_types
288  * @return
289  */
290 cs_error_t cpg_dispatch (
291 	cpg_handle_t handle,
292 	cs_dispatch_flags_t dispatch_types);
293 
294 /**
295  * @brief Join one or more groups.
296  *
297  * messages multicasted with cpg_mcast_joined will be sent to every
298  * group that has been joined on handle handle.  Any message multicasted
299  * to a group that has been previously joined will be delivered in cpg_dispatch
300  *
301  * @param handle
302  * @param group
303  * @return
304  */
305 cs_error_t cpg_join (
306 	cpg_handle_t handle,
307 	const struct cpg_name *group);
308 
309 /**
310  * @brief Leave one or more groups
311  * @param handle
312  * @param group
313  * @return
314  */
315 cs_error_t cpg_leave (
316 	cpg_handle_t handle,
317 	const struct cpg_name *group);
318 
319 /**
320  * @brief Multicast to groups joined with cpg_join.
321  *
322  * @param handle
323  * @param guarantee
324  * @param iovec This iovec will be multicasted to all groups joined with
325  *              the cpg_join interface for handle.
326  * @param iov_len
327  */
328 cs_error_t cpg_mcast_joined (
329 	cpg_handle_t handle,
330 	cpg_guarantee_t guarantee,
331 	const struct iovec *iovec,
332 	unsigned int iov_len);
333 
334 /**
335  * @brief Get membership information from cpg
336  * @param handle
337  * @param groupName
338  * @param member_list
339  * @param member_list_entries
340  * @return
341  */
342 cs_error_t cpg_membership_get (
343 	cpg_handle_t handle,
344 	struct cpg_name *groupName,
345 	struct cpg_address *member_list,
346 	int *member_list_entries);
347 /**
348  * @brief cpg_local_get
349  * @param handle
350  * @param local_nodeid
351  * @return
352  */
353 cs_error_t cpg_local_get (
354 	cpg_handle_t handle,
355 	unsigned int *local_nodeid);
356 
357 /**
358  * @brief cpg_flow_control_state_get
359  * @param handle
360  * @param flow_control_enabled
361  * @return
362  */
363 cs_error_t cpg_flow_control_state_get (
364 	cpg_handle_t handle,
365 	cpg_flow_control_state_t *flow_control_enabled);
366 
367 /**
368  * @brief cpg_zcb_alloc
369  * @param handle
370  * @param size
371  * @param buffer
372  * @return
373  */
374 cs_error_t cpg_zcb_alloc (
375 	cpg_handle_t handle,
376 	size_t size,
377 	void **buffer);
378 
379 /**
380  * @brief cpg_zcb_free
381  * @param handle
382  * @param buffer
383  * @return
384  */
385 cs_error_t cpg_zcb_free (
386 	cpg_handle_t handle,
387 	void *buffer);
388 
389 /**
390  * @brief cpg_zcb_mcast_joined
391  * @param handle
392  * @param guarantee
393  * @param msg
394  * @param msg_len
395  * @return
396  */
397 cs_error_t cpg_zcb_mcast_joined (
398 	cpg_handle_t handle,
399 	cpg_guarantee_t guarantee,
400 	void *msg,
401 	size_t msg_len);
402 
403 /**
404  * @brief cpg_iteration_initialize
405  * @param handle
406  * @param iteration_type
407  * @param group
408  * @param cpg_iteration_handle
409  * @return
410  */
411 cs_error_t cpg_iteration_initialize(
412 	cpg_handle_t handle,
413 	cpg_iteration_type_t iteration_type,
414 	const struct cpg_name *group,
415 	cpg_iteration_handle_t *cpg_iteration_handle);
416 
417 /**
418  * @brief cpg_iteration_next
419  * @param handle
420  * @param description
421  * @return
422  */
423 cs_error_t cpg_iteration_next(
424 	cpg_iteration_handle_t handle,
425 	struct cpg_iteration_description_t *description);
426 
427 /**
428  * @brief cpg_iteration_finalize
429  * @param handle
430  * @return
431  */
432 cs_error_t cpg_iteration_finalize (
433 	cpg_iteration_handle_t handle);
434 
435 #ifdef __cplusplus
436 }
437 #endif
438 
439 #endif /* COROSYNC_CPG_H_DEFINED */
440