1 /*
2  * Copyright © 2008 Kristian Høgsberg
3  *
4  * Permission is hereby granted, free of charge, to any person obtaining
5  * a copy of this software and associated documentation files (the
6  * "Software"), to deal in the Software without restriction, including
7  * without limitation the rights to use, copy, modify, merge, publish,
8  * distribute, sublicense, and/or sell copies of the Software, and to
9  * permit persons to whom the Software is furnished to do so, subject to
10  * the following conditions:
11  *
12  * The above copyright notice and this permission notice (including the
13  * next paragraph) shall be included in all copies or substantial
14  * portions of the Software.
15  *
16  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
17  * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
18  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
19  * NONINFRINGEMENT.  IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
20  * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
21  * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
22  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
23  * SOFTWARE.
24  */
25 
26 /** \file wayland-util.h
27  *
28  * \brief Utility classes, functions, and macros.
29  */
30 
31 #ifndef WAYLAND_UTIL_H
32 #define WAYLAND_UTIL_H
33 
34 #include <math.h>
35 #include <stddef.h>
36 #include <inttypes.h>
37 #include <stdarg.h>
38 
39 #ifdef  __cplusplus
40 extern "C" {
41 #endif
42 
43 /** Visibility attribute */
44 #if defined(__GNUC__) && __GNUC__ >= 4
45 #define WL_EXPORT __attribute__ ((visibility("default")))
46 #else
47 #define WL_EXPORT
48 #endif
49 
50 /** Deprecated attribute */
51 #if defined(__GNUC__) && __GNUC__ >= 4
52 #define WL_DEPRECATED __attribute__ ((deprecated))
53 #else
54 #define WL_DEPRECATED
55 #endif
56 
57 /**
58  * Printf-style argument attribute
59  *
60  * \param x Ordinality of the format string argument
61  * \param y Ordinality of the argument to check against the format string
62  *
63  * \sa https://gcc.gnu.org/onlinedocs/gcc-3.2.1/gcc/Function-Attributes.html
64  */
65 #if defined(__GNUC__) && __GNUC__ >= 4
66 #define WL_PRINTF(x, y) __attribute__((__format__(__printf__, x, y)))
67 #else
68 #define WL_PRINTF(x, y)
69 #endif
70 
71 /**
72  * Protocol message signature
73  *
74  * A wl_message describes the signature of an actual protocol message, such as a
75  * request or event, that adheres to the Wayland protocol wire format. The
76  * protocol implementation uses a wl_message within its demarshal machinery for
77  * decoding messages between a compositor and its clients. In a sense, a
78  * wl_message is to a protocol message like a class is to an object.
79  *
80  * The `name` of a wl_message is the name of the corresponding protocol message.
81  * The `signature` is an ordered list of symbols representing the data types
82  * of message arguments and, optionally, a protocol version and indicators for
83  * nullability. A leading integer in the `signature` indicates the _since_
84  * version of the protocol message. A `?` preceding a data type symbol indicates
85  * that the following argument type is nullable. When no arguments accompany a
86  * message, `signature` is an empty string.
87  *
88  * * `i`: int
89  * * `u`: uint
90  * * `f`: fixed
91  * * `s`: string
92  * * `o`: object
93  * * `n`: new_id
94  * * `a`: array
95  * * `h`: fd
96  * * `?`: following argument is nullable
97  *
98  * While demarshaling primitive arguments is straightforward, when demarshaling
99  * messages containing `object` or `new_id` arguments, the protocol
100  * implementation often must determine the type of the object. The `types` of a
101  * wl_message is an array of wl_interface references that correspond to `o` and
102  * `n` arguments in `signature`, with `NULL` placeholders for arguments with
103  * non-object types.
104  *
105  * Consider the protocol event wl_display `delete_id` that has a single `uint`
106  * argument. The wl_message is:
107  *
108  * \code
109  * { "delete_id", "u", [NULL] }
110  * \endcode
111  *
112  * Here, the message `name` is `"delete_id"`, the `signature` is `"u"`, and the
113  * argument `types` is `[NULL]`, indicating that the `uint` argument has no
114  * corresponding wl_interface since it is a primitive argument.
115  *
116  * In contrast, consider a `wl_foo` interface supporting protocol request `bar`
117  * that has existed since version 2, and has two arguments: a `uint` and an
118  * object of type `wl_baz_interface` that may be `NULL`. Such a `wl_message`
119  * might be:
120  *
121  * \code
122  * { "bar", "2u?o", [NULL, &wl_baz_interface] }
123  * \endcode
124  *
125  * Here, the message `name` is `"bar"`, and the `signature` is `"2u?o"`. Notice
126  * how the `2` indicates the protocol version, the `u` indicates the first
127  * argument type is `uint`, and the `?o` indicates that the second argument
128  * is an object that may be `NULL`. Lastly, the argument `types` array indicates
129  * that no wl_interface corresponds to the first argument, while the type
130  * `wl_baz_interface` corresponds to the second argument.
131  *
132  * \sa wl_argument
133  * \sa wl_interface
134  * \sa <a href="https://wayland.freedesktop.org/docs/html/ch04.html#sect-Protocol-Wire-Format">Wire Format</a>
135  */
136 struct wl_message {
137 	/** Message name */
138 	const char *name;
139 	/** Message signature */
140 	const char *signature;
141 	/** Object argument interfaces */
142 	const struct wl_interface **types;
143 };
144 
145 struct wl_interface {
146 	const char *name;
147 	int version;
148 	int method_count;
149 	const struct wl_message *methods;
150 	int event_count;
151 	const struct wl_message *events;
152 };
153 
154 /** \class wl_list
155  *
156  * \brief Doubly-linked list
157  *
158  * On its own, an instance of `struct wl_list` represents the sentinel head of
159  * a doubly-linked list, and must be initialized using wl_list_init().
160  * When empty, the list head's `next` and `prev` members point to the list head
161  * itself, otherwise `next` references the first element in the list, and `prev`
162  * refers to the last element in the list.
163  *
164  * Use the `struct wl_list` type to represent both the list head and the links
165  * between elements within the list. Use wl_list_empty() to determine if the
166  * list is empty in O(1).
167  *
168  * All elements in the list must be of the same type. The element type must have
169  * a `struct wl_list` member, often named `link` by convention. Prior to
170  * insertion, there is no need to initialize an element's `link` - invoking
171  * wl_list_init() on an individual list element's `struct wl_list` member is
172  * unnecessary if the very next operation is wl_list_insert(). However, a
173  * common idiom is to initialize an element's `link` prior to removal - ensure
174  * safety by invoking wl_list_init() before wl_list_remove().
175  *
176  * Consider a list reference `struct wl_list foo_list`, an element type as
177  * `struct element`, and an element's link member as `struct wl_list link`.
178  *
179  * The following code initializes a list and adds three elements to it.
180  *
181  * \code
182  * struct wl_list foo_list;
183  *
184  * struct element {
185  *         int foo;
186  *         struct wl_list link;
187  * };
188  * struct element e1, e2, e3;
189  *
190  * wl_list_init(&foo_list);
191  * wl_list_insert(&foo_list, &e1.link);   // e1 is the first element
192  * wl_list_insert(&foo_list, &e2.link);   // e2 is now the first element
193  * wl_list_insert(&e2.link, &e3.link); // insert e3 after e2
194  * \endcode
195  *
196  * The list now looks like <em>[e2, e3, e1]</em>.
197  *
198  * The `wl_list` API provides some iterator macros. For example, to iterate
199  * a list in ascending order:
200  *
201  * \code
202  * struct element *e;
203  * wl_list_for_each(e, foo_list, link) {
204  *         do_something_with_element(e);
205  * }
206  * \endcode
207  *
208  * See the documentation of each iterator for details.
209  * \sa http://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/tree/include/linux/list.h
210  */
211 struct wl_list {
212 	struct wl_list *prev;
213 	struct wl_list *next;
214 };
215 
216 /**
217  * Initializes the list.
218  *
219  * \param list List to initialize
220  *
221  * \memberof wl_list
222  */
223 void
224 wl_list_init(struct wl_list *list);
225 
226 /**
227  * Inserts an element into the list, after the element represented by \p list.
228  * When \p list is a reference to the list itself (the head), set the containing
229  * struct of \p elm as the first element in the list.
230  *
231  * \note If \p elm is already part of a list, inserting it again will lead to
232  *       list corruption.
233  *
234  * \param list List element after which the new element is inserted
235  * \param elm Link of the containing struct to insert into the list
236  *
237  * \memberof wl_list
238  */
239 void
240 wl_list_insert(struct wl_list *list, struct wl_list *elm);
241 
242 /**
243  * Removes an element from the list.
244  *
245  * \note This operation leaves \p elm in an invalid state.
246  *
247  * \param elm Link of the containing struct to remove from the list
248  *
249  * \memberof wl_list
250  */
251 void
252 wl_list_remove(struct wl_list *elm);
253 
254 /**
255  * Determines the length of the list.
256  *
257  * \note This is an O(n) operation.
258  *
259  * \param list List whose length is to be determined
260  *
261  * \return Number of elements in the list
262  *
263  * \memberof wl_list
264  */
265 int
266 wl_list_length(const struct wl_list *list);
267 
268 /**
269  * Determines if the list is empty.
270  *
271  * \param list List whose emptiness is to be determined
272  *
273  * \return 1 if empty, or 0 if not empty
274  *
275  * \memberof wl_list
276  */
277 int
278 wl_list_empty(const struct wl_list *list);
279 
280 /**
281  * Inserts all of the elements of one list into another, after the element
282  * represented by \p list.
283  *
284  * \note This leaves \p other in an invalid state.
285  *
286  * \param list List element after which the other list elements will be inserted
287  * \param other List of elements to insert
288  *
289  * \memberof wl_list
290  */
291 void
292 wl_list_insert_list(struct wl_list *list, struct wl_list *other);
293 
294 /**
295  * Retrieves a pointer to a containing struct, given a member name.
296  *
297  * This macro allows "conversion" from a pointer to a member to its containing
298  * struct. This is useful if you have a contained item like a wl_list,
299  * wl_listener, or wl_signal, provided via a callback or other means, and would
300  * like to retrieve the struct that contains it.
301  *
302  * To demonstrate, the following example retrieves a pointer to
303  * `example_container` given only its `destroy_listener` member:
304  *
305  * \code
306  * struct example_container {
307  *         struct wl_listener destroy_listener;
308  *         // other members...
309  * };
310  *
311  * void example_container_destroy(struct wl_listener *listener, void *data)
312  * {
313  *         struct example_container *ctr;
314  *
315  *         ctr = wl_container_of(listener, ctr, destroy_listener);
316  *         // destroy ctr...
317  * }
318  * \endcode
319  *
320  * \note `sample` need not be a valid pointer. A null or uninitialised pointer
321  *       is sufficient.
322  *
323  * \param ptr Valid pointer to the contained member
324  * \param sample Pointer to a struct whose type contains \p ptr
325  * \param member Named location of \p ptr within the \p sample type
326  *
327  * \return The container for the specified pointer
328  */
329 #define wl_container_of(ptr, sample, member)				\
330 	(__typeof__(sample))((char *)(ptr) -				\
331 			     offsetof(__typeof__(*sample), member))
332 
333 /**
334  * Iterates over a list.
335  *
336  * This macro expresses a for-each iterator for wl_list. Given a list and
337  * wl_list link member name (often named `link` by convention), this macro
338  * assigns each element in the list to \p pos, which can then be referenced in
339  * a trailing code block. For example, given a wl_list of `struct message`
340  * elements:
341  *
342  * \code
343  * struct message {
344  *         char *contents;
345  *         wl_list link;
346  * };
347  *
348  * struct wl_list *message_list;
349  * // Assume message_list now "contains" many messages
350  *
351  * struct message *m;
352  * wl_list_for_each(m, message_list, link) {
353  *         do_something_with_message(m);
354  * }
355  * \endcode
356  *
357  * \param pos Cursor that each list element will be assigned to
358  * \param head Head of the list to iterate over
359  * \param member Name of the link member within the element struct
360  *
361  * \relates wl_list
362  */
363 #define wl_list_for_each(pos, head, member)				\
364 	for (pos = wl_container_of((head)->next, pos, member);	\
365 	     &pos->member != (head);					\
366 	     pos = wl_container_of(pos->member.next, pos, member))
367 
368 /**
369  * Iterates over a list, safe against removal of the list element.
370  *
371  * \note Only removal of the current element, \p pos, is safe. Removing
372  *       any other element during traversal may lead to a loop malfunction.
373  *
374  * \sa wl_list_for_each()
375  *
376  * \param pos Cursor that each list element will be assigned to
377  * \param tmp Temporary pointer of the same type as \p pos
378  * \param head Head of the list to iterate over
379  * \param member Name of the link member within the element struct
380  *
381  * \relates wl_list
382  */
383 #define wl_list_for_each_safe(pos, tmp, head, member)			\
384 	for (pos = wl_container_of((head)->next, pos, member),		\
385 	     tmp = wl_container_of((pos)->member.next, tmp, member);	\
386 	     &pos->member != (head);					\
387 	     pos = tmp,							\
388 	     tmp = wl_container_of(pos->member.next, tmp, member))
389 
390 /**
391  * Iterates backwards over a list.
392  *
393  * \sa wl_list_for_each()
394  *
395  * \param pos Cursor that each list element will be assigned to
396  * \param head Head of the list to iterate over
397  * \param member Name of the link member within the element struct
398  *
399  * \relates wl_list
400  */
401 #define wl_list_for_each_reverse(pos, head, member)			\
402 	for (pos = wl_container_of((head)->prev, pos, member);	\
403 	     &pos->member != (head);					\
404 	     pos = wl_container_of(pos->member.prev, pos, member))
405 
406 /**
407  * Iterates backwards over a list, safe against removal of the list element.
408  *
409  * \note Only removal of the current element, \p pos, is safe. Removing
410  *       any other element during traversal may lead to a loop malfunction.
411  *
412  * \sa wl_list_for_each()
413  *
414  * \param pos Cursor that each list element will be assigned to
415  * \param tmp Temporary pointer of the same type as \p pos
416  * \param head Head of the list to iterate over
417  * \param member Name of the link member within the element struct
418  *
419  * \relates wl_list
420  */
421 #define wl_list_for_each_reverse_safe(pos, tmp, head, member)		\
422 	for (pos = wl_container_of((head)->prev, pos, member),	\
423 	     tmp = wl_container_of((pos)->member.prev, tmp, member);	\
424 	     &pos->member != (head);					\
425 	     pos = tmp,							\
426 	     tmp = wl_container_of(pos->member.prev, tmp, member))
427 
428 /**
429  * \class wl_array
430  *
431  * Dynamic array
432  *
433  * A wl_array is a dynamic array that can only grow until released. It is
434  * intended for relatively small allocations whose size is variable or not known
435  * in advance. While construction of a wl_array does not require all elements to
436  * be of the same size, wl_array_for_each() does require all elements to have
437  * the same type and size.
438  *
439  */
440 struct wl_array {
441 	size_t size;
442 	size_t alloc;
443 	void *data;
444 };
445 
446 /**
447  * Initializes the array.
448  *
449  * \param array Array to initialize
450  *
451  * \memberof wl_array
452  */
453 void
454 wl_array_init(struct wl_array *array);
455 
456 /**
457  * Releases the array data.
458  *
459  * \note Leaves the array in an invalid state.
460  *
461  * \param array Array whose data is to be released
462  *
463  * \memberof wl_array
464  */
465 void
466 wl_array_release(struct wl_array *array);
467 
468 /**
469  * Increases the size of the array by \p size bytes.
470  *
471  * \param array Array whose size is to be increased
472  * \param size Number of bytes to increase the size of the array by
473  *
474  * \return A pointer to the beginning of the newly appended space, or NULL when
475  *         resizing fails.
476  *
477  * \memberof wl_array
478  */
479 void *
480 wl_array_add(struct wl_array *array, size_t size);
481 
482 /**
483  * Copies the contents of \p source to \p array.
484  *
485  * \param array Destination array to copy to
486  * \param source Source array to copy from
487  *
488  * \return 0 on success, or -1 on failure
489  *
490  * \memberof wl_array
491  */
492 int
493 wl_array_copy(struct wl_array *array, struct wl_array *source);
494 
495 /**
496  * Iterates over an array.
497  *
498  * This macro expresses a for-each iterator for wl_array. It assigns each
499  * element in the array to \p pos, which can then be referenced in a trailing
500  * code block. \p pos must be a pointer to the array element type, and all
501  * array elements must be of the same type and size.
502  *
503  * \param pos Cursor that each array element will be assigned to
504  * \param array Array to iterate over
505  *
506  * \relates wl_array
507  * \sa wl_list_for_each()
508  */
509 #define wl_array_for_each(pos, array)					\
510 	for (pos = (array)->data;					\
511 	     (const char *) pos < ((const char *) (array)->data + (array)->size); \
512 	     (pos)++)
513 
514 /**
515  * Fixed-point number
516  *
517  * A `wl_fixed_t` is a 24.8 signed fixed-point number with a sign bit, 23 bits
518  * of integer precision and 8 bits of decimal precision. Consider `wl_fixed_t`
519  * as an opaque struct with methods that facilitate conversion to and from
520  * `double` and `int` types.
521  */
522 typedef int32_t wl_fixed_t;
523 
524 /**
525  * Converts a fixed-point number to a floating-point number.
526  *
527  * \param f Fixed-point number to convert
528  *
529  * \return Floating-point representation of the fixed-point argument
530  */
531 static inline double
wl_fixed_to_double(wl_fixed_t f)532 wl_fixed_to_double(wl_fixed_t f)
533 {
534 	union {
535 		double d;
536 		int64_t i;
537 	} u;
538 
539 	u.i = ((1023LL + 44LL) << 52) + (1LL << 51) + f;
540 
541 	return u.d - (3LL << 43);
542 }
543 
544 /**
545  * Converts a floating-point number to a fixed-point number.
546  *
547  * \param d Floating-point number to convert
548  *
549  * \return Fixed-point representation of the floating-point argument
550  */
551 static inline wl_fixed_t
wl_fixed_from_double(double d)552 wl_fixed_from_double(double d)
553 {
554 	union {
555 		double d;
556 		int64_t i;
557 	} u;
558 
559 	u.d = d + (3LL << (51 - 8));
560 
561 	return u.i;
562 }
563 
564 /**
565  * Converts a fixed-point number to an integer.
566  *
567  * \param f Fixed-point number to convert
568  *
569  * \return Integer component of the fixed-point argument
570  */
571 static inline int
wl_fixed_to_int(wl_fixed_t f)572 wl_fixed_to_int(wl_fixed_t f)
573 {
574 	return f / 256;
575 }
576 
577 /**
578  * Converts an integer to a fixed-point number.
579  *
580  * \param i Integer to convert
581  *
582  * \return Fixed-point representation of the integer argument
583  */
584 static inline wl_fixed_t
wl_fixed_from_int(int i)585 wl_fixed_from_int(int i)
586 {
587 	return i * 256;
588 }
589 
590 /**
591  * \brief A union representing all of the basic data types that can be passed
592  * along the wayland wire format.
593  *
594  * This union represents all of the basic data types that can be passed in the
595  * wayland wire format.  It is used by dispatchers and runtime-friendly
596  * versions of the event and request marshaling functions.
597  */
598 union wl_argument {
599 	int32_t i; /**< signed integer */
600 	uint32_t u; /**< unsigned integer */
601 	wl_fixed_t f; /**< fixed point */
602 	const char *s; /**< string */
603 	struct wl_object *o; /**< object */
604 	uint32_t n; /**< new_id */
605 	struct wl_array *a; /**< array */
606 	int32_t h; /**< file descriptor */
607 };
608 
609 /**
610  * \brief A function pointer type for a dispatcher.
611  *
612  * A dispatcher is a function that handles the emitting of callbacks in client
613  * code.  For programs directly using the C library, this is done by using
614  * libffi to call function pointers.  When binding to languages other than C,
615  * dispatchers provide a way to abstract the function calling process to be
616  * friendlier to other function calling systems.
617  *
618  * A dispatcher takes five arguments:  The first is the dispatcher-specific
619  * implementation data associated with the target object.  The second is the
620  * object on which the callback is being invoked (either wl_proxy or
621  * wl_resource).  The third and fourth arguments are the opcode the wl_message
622  * structure corresponding to the callback being emitted.  The final argument
623  * is an array of arguments received from the other process via the wire
624  * protocol.
625  */
626 typedef int (*wl_dispatcher_func_t)(const void *, void *, uint32_t,
627 				    const struct wl_message *,
628 				    union wl_argument *);
629 
630 typedef void (*wl_log_func_t)(const char *, va_list) WL_PRINTF(1, 0);
631 
632 /** \enum wl_iterator_result
633  *
634  * This enum represents the return value of an iterator function.
635  */
636 enum wl_iterator_result {
637 	/** Stop the iteration */
638 	WL_ITERATOR_STOP,
639 	/** Continue the iteration */
640 	WL_ITERATOR_CONTINUE
641 };
642 
643 #ifdef  __cplusplus
644 }
645 #endif
646 
647 #endif
648