Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
1/* SPDX-License-Identifier: GPL-2.0 */
2
3/*
4 * Copyright (c) 2025, Google LLC.
5 * Pasha Tatashin <pasha.tatashin@soleen.com>
6 */
7#ifndef _LINUX_LIST_PRIVATE_H
8#define _LINUX_LIST_PRIVATE_H
9
10/**
11 * DOC: Private List Primitives
12 *
13 * Provides a set of list primitives identical in function to those in
14 * ``<linux/list.h>``, but designed for cases where the embedded
15 * ``&struct list_head`` is private member.
16 */
17
18#include <linux/compiler.h>
19#include <linux/list.h>
20
21#define __list_private_offset(type, member) \
22 ((size_t)(&ACCESS_PRIVATE(((type *)0), member)))
23
24/**
25 * list_private_entry - get the struct for this entry
26 * @ptr: the &struct list_head pointer.
27 * @type: the type of the struct this is embedded in.
28 * @member: the identifier passed to ACCESS_PRIVATE.
29 */
30#define list_private_entry(ptr, type, member) ({ \
31 const struct list_head *__mptr = (ptr); \
32 (type *)((char *)__mptr - __list_private_offset(type, member)); \
33})
34
35/**
36 * list_private_first_entry - get the first element from a list
37 * @ptr: the list head to take the element from.
38 * @type: the type of the struct this is embedded in.
39 * @member: the identifier passed to ACCESS_PRIVATE.
40 */
41#define list_private_first_entry(ptr, type, member) \
42 list_private_entry((ptr)->next, type, member)
43
44/**
45 * list_private_last_entry - get the last element from a list
46 * @ptr: the list head to take the element from.
47 * @type: the type of the struct this is embedded in.
48 * @member: the identifier passed to ACCESS_PRIVATE.
49 */
50#define list_private_last_entry(ptr, type, member) \
51 list_private_entry((ptr)->prev, type, member)
52
53/**
54 * list_private_next_entry - get the next element in list
55 * @pos: the type * to cursor
56 * @member: the name of the list_head within the struct.
57 */
58#define list_private_next_entry(pos, member) \
59 list_private_entry(ACCESS_PRIVATE(pos, member).next, typeof(*(pos)), member)
60
61/**
62 * list_private_next_entry_circular - get the next element in list
63 * @pos: the type * to cursor.
64 * @head: the list head to take the element from.
65 * @member: the name of the list_head within the struct.
66 *
67 * Wraparound if pos is the last element (return the first element).
68 * Note, that list is expected to be not empty.
69 */
70#define list_private_next_entry_circular(pos, head, member) \
71 (list_is_last(&ACCESS_PRIVATE(pos, member), head) ? \
72 list_private_first_entry(head, typeof(*(pos)), member) : \
73 list_private_next_entry(pos, member))
74
75/**
76 * list_private_prev_entry - get the prev element in list
77 * @pos: the type * to cursor
78 * @member: the name of the list_head within the struct.
79 */
80#define list_private_prev_entry(pos, member) \
81 list_private_entry(ACCESS_PRIVATE(pos, member).prev, typeof(*(pos)), member)
82
83/**
84 * list_private_prev_entry_circular - get the prev element in list
85 * @pos: the type * to cursor.
86 * @head: the list head to take the element from.
87 * @member: the name of the list_head within the struct.
88 *
89 * Wraparound if pos is the first element (return the last element).
90 * Note, that list is expected to be not empty.
91 */
92#define list_private_prev_entry_circular(pos, head, member) \
93 (list_is_first(&ACCESS_PRIVATE(pos, member), head) ? \
94 list_private_last_entry(head, typeof(*(pos)), member) : \
95 list_private_prev_entry(pos, member))
96
97/**
98 * list_private_entry_is_head - test if the entry points to the head of the list
99 * @pos: the type * to cursor
100 * @head: the head for your list.
101 * @member: the name of the list_head within the struct.
102 */
103#define list_private_entry_is_head(pos, head, member) \
104 list_is_head(&ACCESS_PRIVATE(pos, member), (head))
105
106/**
107 * list_private_for_each_entry - iterate over list of given type
108 * @pos: the type * to use as a loop cursor.
109 * @head: the head for your list.
110 * @member: the name of the list_head within the struct.
111 */
112#define list_private_for_each_entry(pos, head, member) \
113 for (pos = list_private_first_entry(head, typeof(*pos), member); \
114 !list_private_entry_is_head(pos, head, member); \
115 pos = list_private_next_entry(pos, member))
116
117/**
118 * list_private_for_each_entry_reverse - iterate backwards over list of given type.
119 * @pos: the type * to use as a loop cursor.
120 * @head: the head for your list.
121 * @member: the name of the list_head within the struct.
122 */
123#define list_private_for_each_entry_reverse(pos, head, member) \
124 for (pos = list_private_last_entry(head, typeof(*pos), member); \
125 !list_private_entry_is_head(pos, head, member); \
126 pos = list_private_prev_entry(pos, member))
127
128/**
129 * list_private_for_each_entry_continue - continue iteration over list of given type
130 * @pos: the type * to use as a loop cursor.
131 * @head: the head for your list.
132 * @member: the name of the list_head within the struct.
133 *
134 * Continue to iterate over list of given type, continuing after
135 * the current position.
136 */
137#define list_private_for_each_entry_continue(pos, head, member) \
138 for (pos = list_private_next_entry(pos, member); \
139 !list_private_entry_is_head(pos, head, member); \
140 pos = list_private_next_entry(pos, member))
141
142/**
143 * list_private_for_each_entry_continue_reverse - iterate backwards from the given point
144 * @pos: the type * to use as a loop cursor.
145 * @head: the head for your list.
146 * @member: the name of the list_head within the struct.
147 *
148 * Start to iterate over list of given type backwards, continuing after
149 * the current position.
150 */
151#define list_private_for_each_entry_continue_reverse(pos, head, member) \
152 for (pos = list_private_prev_entry(pos, member); \
153 !list_private_entry_is_head(pos, head, member); \
154 pos = list_private_prev_entry(pos, member))
155
156/**
157 * list_private_for_each_entry_from - iterate over list of given type from the current point
158 * @pos: the type * to use as a loop cursor.
159 * @head: the head for your list.
160 * @member: the name of the list_head within the struct.
161 *
162 * Iterate over list of given type, continuing from current position.
163 */
164#define list_private_for_each_entry_from(pos, head, member) \
165 for (; !list_private_entry_is_head(pos, head, member); \
166 pos = list_private_next_entry(pos, member))
167
168/**
169 * list_private_for_each_entry_from_reverse - iterate backwards over list of given type
170 * from the current point
171 * @pos: the type * to use as a loop cursor.
172 * @head: the head for your list.
173 * @member: the name of the list_head within the struct.
174 *
175 * Iterate backwards over list of given type, continuing from current position.
176 */
177#define list_private_for_each_entry_from_reverse(pos, head, member) \
178 for (; !list_private_entry_is_head(pos, head, member); \
179 pos = list_private_prev_entry(pos, member))
180
181/**
182 * list_private_for_each_entry_safe - iterate over list of given type safe against removal of list entry
183 * @pos: the type * to use as a loop cursor.
184 * @n: another type * to use as temporary storage
185 * @head: the head for your list.
186 * @member: the name of the list_head within the struct.
187 */
188#define list_private_for_each_entry_safe(pos, n, head, member) \
189 for (pos = list_private_first_entry(head, typeof(*pos), member), \
190 n = list_private_next_entry(pos, member); \
191 !list_private_entry_is_head(pos, head, member); \
192 pos = n, n = list_private_next_entry(n, member))
193
194/**
195 * list_private_for_each_entry_safe_continue - continue list iteration safe against removal
196 * @pos: the type * to use as a loop cursor.
197 * @n: another type * to use as temporary storage
198 * @head: the head for your list.
199 * @member: the name of the list_head within the struct.
200 *
201 * Iterate over list of given type, continuing after current point,
202 * safe against removal of list entry.
203 */
204#define list_private_for_each_entry_safe_continue(pos, n, head, member) \
205 for (pos = list_private_next_entry(pos, member), \
206 n = list_private_next_entry(pos, member); \
207 !list_private_entry_is_head(pos, head, member); \
208 pos = n, n = list_private_next_entry(n, member))
209
210/**
211 * list_private_for_each_entry_safe_from - iterate over list from current point safe against removal
212 * @pos: the type * to use as a loop cursor.
213 * @n: another type * to use as temporary storage
214 * @head: the head for your list.
215 * @member: the name of the list_head within the struct.
216 *
217 * Iterate over list of given type from current point, safe against
218 * removal of list entry.
219 */
220#define list_private_for_each_entry_safe_from(pos, n, head, member) \
221 for (n = list_private_next_entry(pos, member); \
222 !list_private_entry_is_head(pos, head, member); \
223 pos = n, n = list_private_next_entry(n, member))
224
225/**
226 * list_private_for_each_entry_safe_reverse - iterate backwards over list safe against removal
227 * @pos: the type * to use as a loop cursor.
228 * @n: another type * to use as temporary storage
229 * @head: the head for your list.
230 * @member: the name of the list_head within the struct.
231 *
232 * Iterate backwards over list of given type, safe against removal
233 * of list entry.
234 */
235#define list_private_for_each_entry_safe_reverse(pos, n, head, member) \
236 for (pos = list_private_last_entry(head, typeof(*pos), member), \
237 n = list_private_prev_entry(pos, member); \
238 !list_private_entry_is_head(pos, head, member); \
239 pos = n, n = list_private_prev_entry(n, member))
240
241/**
242 * list_private_safe_reset_next - reset a stale list_for_each_entry_safe loop
243 * @pos: the loop cursor used in the list_for_each_entry_safe loop
244 * @n: temporary storage used in list_for_each_entry_safe
245 * @member: the name of the list_head within the struct.
246 *
247 * list_safe_reset_next is not safe to use in general if the list may be
248 * modified concurrently (eg. the lock is dropped in the loop body). An
249 * exception to this is if the cursor element (pos) is pinned in the list,
250 * and list_safe_reset_next is called after re-taking the lock and before
251 * completing the current iteration of the loop body.
252 */
253#define list_private_safe_reset_next(pos, n, member) \
254 n = list_private_next_entry(pos, member)
255
256#endif /* _LINUX_LIST_PRIVATE_H */