[go: up one dir, main page]
1/* SPDX-License-Identifier: GPL-2.0 */
2#ifndef _LINUX_HELPER_MACROS_H_
3#define _LINUX_HELPER_MACROS_H_
4
5#include <linux/compiler_attributes.h>
6#include <linux/math.h>
7#include <linux/typecheck.h>
8#include <linux/stddef.h>
9
10/**
11 * for_each_if - helper for handling conditionals in various for_each macros
12 * @condition: The condition to check
13 *
14 * Typical use::
15 *
16 * #define for_each_foo_bar(x, y) \'
17 * list_for_each_entry(x, y->list, head) \'
18 * for_each_if(x->something == SOMETHING)
19 *
20 * The for_each_if() macro makes the use of for_each_foo_bar() less error
21 * prone.
22 */
23#define for_each_if(condition) if (!(condition)) {} else
24
25/**
26 * find_closest - locate the closest element in a sorted array
27 * @x: The reference value.
28 * @a: The array in which to look for the closest element. Must be sorted
29 * in ascending order.
30 * @as: Size of 'a'.
31 *
32 * Returns the index of the element closest to 'x'.
33 * Note: If using an array of negative numbers (or mixed positive numbers),
34 * then be sure that 'x' is of a signed-type to get good results.
35 */
36#define find_closest(x, a, as) \
37({ \
38 typeof(as) __fc_i, __fc_as = (as) - 1; \
39 long __fc_mid_x, __fc_x = (x); \
40 long __fc_left, __fc_right; \
41 typeof(*a) const *__fc_a = (a); \
42 for (__fc_i = 0; __fc_i < __fc_as; __fc_i++) { \
43 __fc_mid_x = (__fc_a[__fc_i] + __fc_a[__fc_i + 1]) / 2; \
44 if (__fc_x <= __fc_mid_x) { \
45 __fc_left = __fc_x - __fc_a[__fc_i]; \
46 __fc_right = __fc_a[__fc_i + 1] - __fc_x; \
47 if (__fc_right < __fc_left) \
48 __fc_i++; \
49 break; \
50 } \
51 } \
52 (__fc_i); \
53})
54
55/**
56 * find_closest_descending - locate the closest element in a sorted array
57 * @x: The reference value.
58 * @a: The array in which to look for the closest element. Must be sorted
59 * in descending order.
60 * @as: Size of 'a'.
61 *
62 * Similar to find_closest() but 'a' is expected to be sorted in descending
63 * order. The iteration is done in reverse order, so that the comparison
64 * of '__fc_right' & '__fc_left' also works for unsigned numbers.
65 */
66#define find_closest_descending(x, a, as) \
67({ \
68 typeof(as) __fc_i, __fc_as = (as) - 1; \
69 long __fc_mid_x, __fc_x = (x); \
70 long __fc_left, __fc_right; \
71 typeof(*a) const *__fc_a = (a); \
72 for (__fc_i = __fc_as; __fc_i >= 1; __fc_i--) { \
73 __fc_mid_x = (__fc_a[__fc_i] + __fc_a[__fc_i - 1]) / 2; \
74 if (__fc_x <= __fc_mid_x) { \
75 __fc_left = __fc_x - __fc_a[__fc_i]; \
76 __fc_right = __fc_a[__fc_i - 1] - __fc_x; \
77 if (__fc_right < __fc_left) \
78 __fc_i--; \
79 break; \
80 } \
81 } \
82 (__fc_i); \
83})
84
85/**
86 * PTR_IF - evaluate to @ptr if @cond is true, or to NULL otherwise.
87 * @cond: A conditional, usually in a form of IS_ENABLED(CONFIG_FOO)
88 * @ptr: A pointer to assign if @cond is true.
89 *
90 * PTR_IF(IS_ENABLED(CONFIG_FOO), ptr) evaluates to @ptr if CONFIG_FOO is set
91 * to 'y' or 'm', or to NULL otherwise. The @ptr argument must be a pointer.
92 *
93 * The macro can be very useful to help compiler dropping dead code.
94 *
95 * For instance, consider the following::
96 *
97 * #ifdef CONFIG_FOO_SUSPEND
98 * static int foo_suspend(struct device *dev)
99 * {
100 * ...
101 * }
102 * #endif
103 *
104 * static struct pm_ops foo_ops = {
105 * #ifdef CONFIG_FOO_SUSPEND
106 * .suspend = foo_suspend,
107 * #endif
108 * };
109 *
110 * While this works, the foo_suspend() macro is compiled conditionally,
111 * only when CONFIG_FOO_SUSPEND is set. This is problematic, as there could
112 * be a build bug in this function, we wouldn't have a way to know unless
113 * the configuration option is set.
114 *
115 * An alternative is to declare foo_suspend() always, but mark it
116 * as __maybe_unused. This works, but the __maybe_unused attribute
117 * is required to instruct the compiler that the function may not
118 * be referenced anywhere, and is safe to remove without making
119 * a fuss about it. This makes the programmer responsible for tagging
120 * the functions that can be garbage-collected.
121 *
122 * With the macro it is possible to write the following:
123 *
124 * static int foo_suspend(struct device *dev)
125 * {
126 * ...
127 * }
128 *
129 * static struct pm_ops foo_ops = {
130 * .suspend = PTR_IF(IS_ENABLED(CONFIG_FOO_SUSPEND), foo_suspend),
131 * };
132 *
133 * The foo_suspend() function will now be automatically dropped by the
134 * compiler, and it does not require any specific attribute.
135 */
136#define PTR_IF(cond, ptr) ((cond) ? (ptr) : NULL)
137
138/**
139 * u64_to_user_ptr - cast a pointer passed as u64 from user space to void __user *
140 * @x: The u64 value from user space, usually via IOCTL
141 *
142 * u64_to_user_ptr() simply casts a pointer passed as u64 from user space to void
143 * __user * correctly. Using this lets us get rid of all the tiresome casts.
144 */
145#define u64_to_user_ptr(x) \
146({ \
147 typecheck(u64, (x)); \
148 (void __user *)(uintptr_t)(x); \
149})
150
151/**
152 * is_insidevar - check if the @ptr points inside the @var memory range.
153 * @ptr: the pointer to a memory address.
154 * @var: the variable which address and size identify the memory range.
155 *
156 * Evaluates to true if the address in @ptr lies within the memory
157 * range allocated to @var.
158 */
159#define is_insidevar(ptr, var) \
160 ((uintptr_t)(ptr) >= (uintptr_t)(var) && \
161 (uintptr_t)(ptr) < (uintptr_t)(var) + sizeof(var))
162
163#endif
164

source code of linux/include/linux/util_macros.h