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 */ 257