1 /*
2 * Copyright (c) 2003-2021 Apple Inc. All rights reserved.
3 *
4 * @APPLE_OSREFERENCE_LICENSE_HEADER_START@
5 *
6 * This file contains Original Code and/or Modifications of Original Code
7 * as defined in and that are subject to the Apple Public Source License
8 * Version 2.0 (the 'License'). You may not use this file except in
9 * compliance with the License. The rights granted to you under the License
10 * may not be used to create, or enable the creation or redistribution of,
11 * unlawful or unlicensed copies of an Apple operating system, or to
12 * circumvent, violate, or enable the circumvention or violation of, any
13 * terms of an Apple operating system software license agreement.
14 *
15 * Please obtain a copy of the License at
16 * http://www.opensource.apple.com/apsl/ and read it before using this file.
17 *
18 * The Original Code and all software distributed under the License are
19 * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
20 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
21 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
22 * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
23 * Please see the License for the specific language governing rights and
24 * limitations under the License.
25 *
26 * @APPLE_OSREFERENCE_LICENSE_HEADER_END@
27 */
28 /*-
29 * Copyright (c) 1999,2000,2001 Jonathan Lemon <[email protected]>
30 * All rights reserved.
31 *
32 * Redistribution and use in source and binary forms, with or without
33 * modification, are permitted provided that the following conditions
34 * are met:
35 * 1. Redistributions of source code must retain the above copyright
36 * notice, this list of conditions and the following disclaimer.
37 * 2. Redistributions in binary form must reproduce the above copyright
38 * notice, this list of conditions and the following disclaimer in the
39 * documentation and/or other materials provided with the distribution.
40 *
41 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
42 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
43 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
44 * ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
45 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
46 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
47 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
48 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
49 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
50 * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
51 * SUCH DAMAGE.
52 *
53 * $FreeBSD: src/sys/sys/event.h,v 1.5.2.5 2001/12/14 19:21:22 jlemon Exp $
54 */
55
56 #ifndef _SYS_EVENT_H_
57 #define _SYS_EVENT_H_
58
59 #include <machine/types.h>
60 #include <sys/cdefs.h>
61 #include <sys/queue.h>
62 #include <stdint.h>
63 #ifndef KERNEL
64 #include <sys/types.h>
65 #endif
66 #ifdef XNU_KERNEL_PRIVATE
67 #include <mach/vm_param.h>
68 #include <kern/kern_types.h>
69 #include <sys/fcntl.h> /* FREAD, FWRITE */
70 #include <kern/debug.h> /* panic */
71 #include <pthread/priority_private.h>
72 #endif /* XNU_KERNEL_PRIVATE */
73
74 /*
75 * Filter types
76 */
77 #define EVFILT_READ (-1)
78 #define EVFILT_WRITE (-2)
79 #define EVFILT_AIO (-3) /* attached to aio requests */
80 #define EVFILT_VNODE (-4) /* attached to vnodes */
81 #define EVFILT_PROC (-5) /* attached to struct proc */
82 #define EVFILT_SIGNAL (-6) /* attached to struct proc */
83 #define EVFILT_TIMER (-7) /* timers */
84 #define EVFILT_MACHPORT (-8) /* Mach portsets */
85 #define EVFILT_FS (-9) /* Filesystem events */
86 #define EVFILT_USER (-10) /* User events */
87 #ifdef PRIVATE
88 #define EVFILT_UNUSED_11 (-11) /* (-11) unused */
89 #endif
90 #define EVFILT_VM (-12) /* Virtual memory events */
91 #ifdef PRIVATE
92 #define EVFILT_SOCK (-13) /* Socket events */
93 #define EVFILT_MEMORYSTATUS (-14) /* Memorystatus events */
94 #endif /* PRIVATE */
95 #define EVFILT_EXCEPT (-15) /* Exception events */
96 #ifdef PRIVATE
97 #define EVFILT_NW_CHANNEL (-16) /* Skywalk channel events */
98 #define EVFILT_WORKLOOP (-17) /* Workloop events */
99 #endif /* PRIVATE */
100
101 #define EVFILT_SYSCOUNT 17
102 #define EVFILT_THREADMARKER EVFILT_SYSCOUNT /* Internal use only */
103
104 #pragma pack(4)
105
106 struct kevent {
107 uintptr_t ident; /* identifier for this event */
108 int16_t filter; /* filter for event */
109 uint16_t flags; /* general flags */
110 uint32_t fflags; /* filter-specific flags */
111 intptr_t data; /* filter-specific data */
112 void *udata; /* opaque user data identifier */
113 };
114
115 #ifdef KERNEL_PRIVATE
116
117 struct user64_kevent {
118 uint64_t ident; /* identifier for this event */
119 int16_t filter; /* filter for event */
120 uint16_t flags; /* general flags */
121 uint32_t fflags; /* filter-specific flags */
122 int64_t data; /* filter-specific data */
123 user_addr_t udata; /* opaque user data identifier */
124 };
125
126 struct user32_kevent {
127 uint32_t ident; /* identifier for this event */
128 int16_t filter; /* filter for event */
129 uint16_t flags; /* general flags */
130 uint32_t fflags; /* filter-specific flags */
131 int32_t data; /* filter-specific data */
132 user32_addr_t udata; /* opaque user data identifier */
133 };
134
135 #endif /* KERNEL_PRIVATE */
136
137 #pragma pack()
138
139 struct kevent64_s {
140 uint64_t ident; /* identifier for this event */
141 int16_t filter; /* filter for event */
142 uint16_t flags; /* general flags */
143 uint32_t fflags; /* filter-specific flags */
144 int64_t data; /* filter-specific data */
145 uint64_t udata; /* opaque user data identifier */
146 uint64_t ext[2]; /* filter-specific extensions */
147 };
148
149 #ifdef PRIVATE
150 struct kevent_qos_s {
151 uint64_t ident; /* identifier for this event */
152 int16_t filter; /* filter for event */
153 uint16_t flags; /* general flags */
154 int32_t qos; /* quality of service */
155 uint64_t udata; /* opaque user data identifier */
156 uint32_t fflags; /* filter-specific flags */
157 uint32_t xflags; /* extra filter-specific flags */
158 int64_t data; /* filter-specific data */
159 uint64_t ext[4]; /* filter-specific extensions */
160 };
161
162 /*
163 * Type definition for names/ids of dynamically allocated kqueues.
164 */
165 typedef uint64_t kqueue_id_t;
166 #endif /* PRIVATE */
167
168 #define EV_SET(kevp, a, b, c, d, e, f) do { \
169 struct kevent *__kevp__ = (kevp); \
170 __kevp__->ident = (a); \
171 __kevp__->filter = (b); \
172 __kevp__->flags = (c); \
173 __kevp__->fflags = (d); \
174 __kevp__->data = (e); \
175 __kevp__->udata = (f); \
176 } while(0)
177
178 #define EV_SET64(kevp, a, b, c, d, e, f, g, h) do { \
179 struct kevent64_s *__kevp__ = (kevp); \
180 __kevp__->ident = (a); \
181 __kevp__->filter = (b); \
182 __kevp__->flags = (c); \
183 __kevp__->fflags = (d); \
184 __kevp__->data = (e); \
185 __kevp__->udata = (f); \
186 __kevp__->ext[0] = (g); \
187 __kevp__->ext[1] = (h); \
188 } while(0)
189
190
191 /* kevent system call flags */
192 #define KEVENT_FLAG_NONE 0x000000 /* no flag value */
193 #define KEVENT_FLAG_IMMEDIATE 0x000001 /* immediate timeout */
194 #define KEVENT_FLAG_ERROR_EVENTS 0x000002 /* output events only include change errors */
195
196 #ifdef PRIVATE
197
198 /*
199 * Rather than provide an EV_SET_QOS macro for kevent_qos_t structure
200 * initialization, we encourage use of named field initialization support
201 * instead.
202 */
203
204 // was KEVENT_FLAG_STACK_EVENTS 0x000004
205 #define KEVENT_FLAG_STACK_DATA 0x000008 /* output data allocated as stack (grows down) */
206 // KEVENT_FLAG_POLL 0x000010
207 #define KEVENT_FLAG_WORKQ 0x000020 /* interact with the default workq kq */
208 // KEVENT_FLAG_LEGACY32 0x000040
209 // KEVENT_FLAG_LEGACY64 0x000080
210 // KEVENT_FLAG_PROC64 0x000100
211 #define KEVENT_FLAG_WORKQ_MANAGER 0x000200 /* obsolete */
212 #define KEVENT_FLAG_WORKLOOP 0x000400 /* interact with the specified workloop kq */
213 #define KEVENT_FLAG_PARKING 0x000800 /* workq thread is parking */
214 // KEVENT_FLAG_KERNEL 0x001000
215 // KEVENT_FLAG_DYNAMIC_KQUEUE 0x002000
216 // KEVENT_FLAG_NEEDS_END_PROCESSING 0x004000
217 #define KEVENT_FLAG_WORKLOOP_SERVICER_ATTACH 0x008000 /* obsolete */
218 #define KEVENT_FLAG_WORKLOOP_SERVICER_DETACH 0x010000 /* obsolete */
219 #define KEVENT_FLAG_DYNAMIC_KQ_MUST_EXIST 0x020000 /* kq lookup by id must exist */
220 #define KEVENT_FLAG_DYNAMIC_KQ_MUST_NOT_EXIST 0x040000 /* kq lookup by id must not exist */
221 #define KEVENT_FLAG_WORKLOOP_NO_WQ_THREAD 0x080000 /* obsolete */
222
223 #ifdef XNU_KERNEL_PRIVATE
224
225 #define KEVENT_FLAG_POLL 0x0010 /* Call is for poll() */
226 #define KEVENT_FLAG_LEGACY32 0x0040 /* event data in legacy 32-bit format */
227 #define KEVENT_FLAG_LEGACY64 0x0080 /* event data in legacy 64-bit format */
228 #define KEVENT_FLAG_PROC64 0x0100 /* proc is 64bits */
229 #define KEVENT_FLAG_KERNEL 0x1000 /* caller is in-kernel */
230 #define KEVENT_FLAG_DYNAMIC_KQUEUE 0x2000 /* kqueue is dynamically allocated */
231 #define KEVENT_FLAG_NEEDS_END_PROCESSING 0x4000 /* end processing required before returning */
232
233 #define KEVENT_ID_FLAG_USER (KEVENT_FLAG_WORKLOOP | \
234 KEVENT_FLAG_DYNAMIC_KQ_MUST_EXIST | KEVENT_FLAG_DYNAMIC_KQ_MUST_NOT_EXIST)
235
236 #define KEVENT_FLAG_USER (KEVENT_FLAG_IMMEDIATE | KEVENT_FLAG_ERROR_EVENTS | \
237 KEVENT_FLAG_STACK_DATA | KEVENT_FLAG_WORKQ | KEVENT_FLAG_WORKLOOP | \
238 KEVENT_FLAG_DYNAMIC_KQ_MUST_EXIST | KEVENT_FLAG_DYNAMIC_KQ_MUST_NOT_EXIST)
239
240 /*
241 * Since some filter ops are not part of the standard sysfilt_ops, we use
242 * kn_filtid starting from EVFILT_SYSCOUNT to identify these cases. This is to
243 * let kn_fops() get the correct fops for all cases.
244 */
245 #define EVFILTID_KQREAD (EVFILT_SYSCOUNT)
246 #define EVFILTID_PIPE_N (EVFILT_SYSCOUNT + 1)
247 #define EVFILTID_PIPE_R (EVFILT_SYSCOUNT + 2)
248 #define EVFILTID_PIPE_W (EVFILT_SYSCOUNT + 3)
249 #define EVFILTID_PTSD (EVFILT_SYSCOUNT + 4)
250 #define EVFILTID_SOREAD (EVFILT_SYSCOUNT + 5)
251 #define EVFILTID_SOWRITE (EVFILT_SYSCOUNT + 6)
252 #define EVFILTID_SCK (EVFILT_SYSCOUNT + 7)
253 #define EVFILTID_SOEXCEPT (EVFILT_SYSCOUNT + 8)
254 #define EVFILTID_SPEC (EVFILT_SYSCOUNT + 9)
255 #define EVFILTID_BPFREAD (EVFILT_SYSCOUNT + 10)
256 #define EVFILTID_NECP_FD (EVFILT_SYSCOUNT + 11)
257 #define EVFILTID_SKYWALK_CHANNEL_W (EVFILT_SYSCOUNT + 12)
258 #define EVFILTID_SKYWALK_CHANNEL_R (EVFILT_SYSCOUNT + 13)
259 #define EVFILTID_SKYWALK_CHANNEL_E (EVFILT_SYSCOUNT + 14)
260 #define EVFILTID_FSEVENT (EVFILT_SYSCOUNT + 15)
261 #define EVFILTID_VN (EVFILT_SYSCOUNT + 16)
262 #define EVFILTID_TTY (EVFILT_SYSCOUNT + 17)
263 #define EVFILTID_PTMX (EVFILT_SYSCOUNT + 18)
264
265 #define EVFILTID_DETACHED (EVFILT_SYSCOUNT + 19)
266 #define EVFILTID_MAX (EVFILT_SYSCOUNT + 20)
267
268 #endif /* defined(XNU_KERNEL_PRIVATE) */
269
270 #define EV_SET_QOS 0
271
272 #endif /* PRIVATE */
273
274 /* actions */
275 #define EV_ADD 0x0001 /* add event to kq (implies enable) */
276 #define EV_DELETE 0x0002 /* delete event from kq */
277 #define EV_ENABLE 0x0004 /* enable event */
278 #define EV_DISABLE 0x0008 /* disable event (not reported) */
279
280 /* flags */
281 #define EV_ONESHOT 0x0010 /* only report one occurrence */
282 #define EV_CLEAR 0x0020 /* clear event state after reporting */
283 #define EV_RECEIPT 0x0040 /* force immediate event output */
284 /* ... with or without EV_ERROR */
285 /* ... use KEVENT_FLAG_ERROR_EVENTS */
286 /* on syscalls supporting flags */
287
288 #define EV_DISPATCH 0x0080 /* disable event after reporting */
289 #define EV_UDATA_SPECIFIC 0x0100 /* unique kevent per udata value */
290
291 #define EV_DISPATCH2 (EV_DISPATCH | EV_UDATA_SPECIFIC)
292 /* ... in combination with EV_DELETE */
293 /* will defer delete until udata-specific */
294 /* event enabled. EINPROGRESS will be */
295 /* returned to indicate the deferral */
296
297 #define EV_VANISHED 0x0200 /* report that source has vanished */
298 /* ... only valid with EV_DISPATCH2 */
299
300 #define EV_SYSFLAGS 0xF000 /* reserved by system */
301 #define EV_FLAG0 0x1000 /* filter-specific flag */
302 #define EV_FLAG1 0x2000 /* filter-specific flag */
303
304 /* returned values */
305 #define EV_EOF 0x8000 /* EOF detected */
306 #define EV_ERROR 0x4000 /* error, data contains errno */
307
308 /*
309 * Filter specific flags for EVFILT_READ
310 *
311 * The default behavior for EVFILT_READ is to make the "read" determination
312 * relative to the current file descriptor read pointer.
313 *
314 * The EV_POLL flag indicates the determination should be made via poll(2)
315 * semantics. These semantics dictate always returning true for regular files,
316 * regardless of the amount of unread data in the file.
317 *
318 * On input, EV_OOBAND specifies that filter should actively return in the
319 * presence of OOB on the descriptor. It implies that filter will return
320 * if there is OOB data available to read OR when any other condition
321 * for the read are met (for example number of bytes regular data becomes >=
322 * low-watermark).
323 * If EV_OOBAND is not set on input, it implies that the filter should not actively
324 * return for out of band data on the descriptor. The filter will then only return
325 * when some other condition for read is met (ex: when number of regular data bytes
326 * >=low-watermark OR when socket can't receive more data (SS_CANTRCVMORE)).
327 *
328 * On output, EV_OOBAND indicates the presence of OOB data on the descriptor.
329 * If it was not specified as an input parameter, then the data count is the
330 * number of bytes before the current OOB marker, else data count is the number
331 * of bytes beyond OOB marker.
332 */
333 #define EV_POLL EV_FLAG0
334 #define EV_OOBAND EV_FLAG1
335
336 /*
337 * data/hint fflags for EVFILT_USER, shared with userspace
338 */
339
340 /*
341 * On input, NOTE_TRIGGER causes the event to be triggered for output.
342 */
343 #define NOTE_TRIGGER 0x01000000
344
345 /*
346 * On input, the top two bits of fflags specifies how the lower twenty four
347 * bits should be applied to the stored value of fflags.
348 *
349 * On output, the top two bits will always be set to NOTE_FFNOP and the
350 * remaining twenty four bits will contain the stored fflags value.
351 */
352 #define NOTE_FFNOP 0x00000000 /* ignore input fflags */
353 #define NOTE_FFAND 0x40000000 /* and fflags */
354 #define NOTE_FFOR 0x80000000 /* or fflags */
355 #define NOTE_FFCOPY 0xc0000000 /* copy fflags */
356 #define NOTE_FFCTRLMASK 0xc0000000 /* mask for operations */
357 #define NOTE_FFLAGSMASK 0x00ffffff
358
359 #ifdef PRIVATE
360 /*
361 * data/hint fflags for EVFILT_WORKLOOP, shared with userspace
362 *
363 * The ident for thread requests should be the dynamic ID of the workloop
364 * The ident for each sync waiter must be unique to that waiter [for this workloop]
365 *
366 *
367 * Commands:
368 *
369 * @const NOTE_WL_THREAD_REQUEST [in/out]
370 * The kevent represents asynchronous userspace work and its associated QoS.
371 * There can only be a single knote with this flag set per workloop.
372 *
373 * @const NOTE_WL_SYNC_WAIT [in/out]
374 * This bit is set when the caller is waiting to become the owner of a workloop.
375 * If the NOTE_WL_SYNC_WAKE bit is already set then the caller is not blocked,
376 * else it blocks until it is set.
377 *
378 * The QoS field of the knote is used to push on other owners or servicers.
379 *
380 * @const NOTE_WL_SYNC_WAKE [in/out]
381 * Marks the waiter knote as being eligible to become an owner
382 * This bit can only be set once, trying it again will fail with EALREADY.
383 *
384 * @const NOTE_WL_SYNC_IPC [in/out]
385 * The knote is a sync IPC redirected turnstile push.
386 *
387 * Flags/Modifiers:
388 *
389 * @const NOTE_WL_UPDATE_QOS [in] (only NOTE_WL_THREAD_REQUEST)
390 * For successful updates (EV_ADD only), learn the new userspace async QoS from
391 * the kevent qos field.
392 *
393 * @const NOTE_WL_END_OWNERSHIP [in]
394 * If the update is successful (including deletions) or returns ESTALE, and
395 * the caller thread or the "suspended" thread is currently owning the workloop,
396 * then ownership is forgotten.
397 *
398 * @const NOTE_WL_DISCOVER_OWNER [in]
399 * If the update is successful (including deletions), learn the owner identity
400 * from the loaded value during debounce. This requires an address to have been
401 * filled in the EV_EXTIDX_WL_ADDR ext field, but doesn't require a mask to have
402 * been set in the EV_EXTIDX_WL_MASK.
403 *
404 * @const NOTE_WL_IGNORE_ESTALE [in]
405 * If the operation would fail with ESTALE, mask the error and pretend the
406 * update was successful. However the operation itself didn't happen, meaning
407 * that:
408 * - attaching a new knote will not happen
409 * - dropping an existing knote will not happen
410 * - NOTE_WL_UPDATE_QOS or NOTE_WL_DISCOVER_OWNER will have no effect
411 *
412 * This modifier doesn't affect NOTE_WL_END_OWNERSHIP.
413 */
414 #define NOTE_WL_THREAD_REQUEST 0x00000001
415 #define NOTE_WL_SYNC_WAIT 0x00000004
416 #define NOTE_WL_SYNC_WAKE 0x00000008
417 #define NOTE_WL_SYNC_IPC 0x80000000
418 #define NOTE_WL_COMMANDS_MASK 0x8000000f /* Mask of all the [in] commands above */
419
420 #define NOTE_WL_UPDATE_QOS 0x00000010
421 #define NOTE_WL_END_OWNERSHIP 0x00000020
422 #define NOTE_WL_DISCOVER_OWNER 0x00000080
423 #define NOTE_WL_IGNORE_ESTALE 0x00000100
424 #define NOTE_WL_UPDATES_MASK 0x000001f0 /* Mask of all the [in] updates above */
425
426 #define NOTE_WL_UPDATE_OWNER 0 /* ... compatibility define ... */
427
428 /*
429 * EVFILT_WORKLOOP ext[] array indexes/meanings.
430 */
431 #define EV_EXTIDX_WL_LANE 0 /* lane identifier [in: sync waiter]
432 * [out: thread request] */
433 #define EV_EXTIDX_WL_ADDR 1 /* debounce address [in: NULL==no debounce] */
434 #define EV_EXTIDX_WL_MASK 2 /* debounce mask [in] */
435 #define EV_EXTIDX_WL_VALUE 3 /* debounce value [in: not current->ESTALE]
436 * [out: new/debounce value] */
437
438 #endif /* PRIVATE */
439
440 /*
441 * data/hint fflags for EVFILT_{READ|WRITE}, shared with userspace
442 *
443 * The default behavior for EVFILT_READ is to make the determination
444 * realtive to the current file descriptor read pointer.
445 */
446 #define NOTE_LOWAT 0x00000001 /* low water mark */
447
448 /* data/hint flags for EVFILT_EXCEPT, shared with userspace */
449 #define NOTE_OOB 0x00000002 /* OOB data */
450
451 /*
452 * data/hint fflags for EVFILT_VNODE, shared with userspace
453 */
454 #define NOTE_DELETE 0x00000001 /* vnode was removed */
455 #define NOTE_WRITE 0x00000002 /* data contents changed */
456 #define NOTE_EXTEND 0x00000004 /* size increased */
457 #define NOTE_ATTRIB 0x00000008 /* attributes changed */
458 #define NOTE_LINK 0x00000010 /* link count changed */
459 #define NOTE_RENAME 0x00000020 /* vnode was renamed */
460 #define NOTE_REVOKE 0x00000040 /* vnode access was revoked */
461 #define NOTE_NONE 0x00000080 /* No specific vnode event: to test for EVFILT_READ activation*/
462 #define NOTE_FUNLOCK 0x00000100 /* vnode was unlocked by flock(2) */
463 #define NOTE_LEASE_DOWNGRADE 0x00000200 /* lease downgrade requested */
464 #define NOTE_LEASE_RELEASE 0x00000400 /* lease release requested */
465
466 /*
467 * data/hint fflags for EVFILT_PROC, shared with userspace
468 *
469 * Please note that EVFILT_PROC and EVFILT_SIGNAL share the same knote list
470 * that hangs off the proc structure. They also both play games with the hint
471 * passed to KNOTE(). If NOTE_SIGNAL is passed as a hint, then the lower bits
472 * of the hint contain the signal. IF NOTE_FORK is passed, then the lower bits
473 * contain the PID of the child (but the pid does not get passed through in
474 * the actual kevent).
475 */
476 enum {
477 eNoteReapDeprecated __deprecated_enum_msg("This kqueue(2) EVFILT_PROC flag is deprecated") = 0x10000000
478 };
479
480 #define NOTE_EXIT 0x80000000 /* process exited */
481 #define NOTE_FORK 0x40000000 /* process forked */
482 #define NOTE_EXEC 0x20000000 /* process exec'd */
483 #define NOTE_REAP ((unsigned int)eNoteReapDeprecated /* 0x10000000 */ ) /* process reaped */
484 #define NOTE_SIGNAL 0x08000000 /* shared with EVFILT_SIGNAL */
485 #define NOTE_EXITSTATUS 0x04000000 /* exit status to be returned, valid for child process or when allowed to signal target pid */
486 #define NOTE_EXIT_DETAIL 0x02000000 /* provide details on reasons for exit */
487
488 #define NOTE_PDATAMASK 0x000fffff /* mask for signal & exit status */
489 #define NOTE_PCTRLMASK (~NOTE_PDATAMASK)
490
491 /*
492 * If NOTE_EXITSTATUS is present, provide additional info about exiting process.
493 */
494 enum {
495 eNoteExitReparentedDeprecated __deprecated_enum_msg("This kqueue(2) EVFILT_PROC flag is no longer sent") = 0x00080000
496 };
497 #define NOTE_EXIT_REPARENTED ((unsigned int)eNoteExitReparentedDeprecated) /* exited while reparented */
498
499 /*
500 * If NOTE_EXIT_DETAIL is present, these bits indicate specific reasons for exiting.
501 */
502 #define NOTE_EXIT_DETAIL_MASK 0x00070000
503 #define NOTE_EXIT_DECRYPTFAIL 0x00010000
504 #define NOTE_EXIT_MEMORY 0x00020000
505 #define NOTE_EXIT_CSERROR 0x00040000
506
507 #ifdef PRIVATE
508
509 /*
510 * If NOTE_EXIT_MEMORY is present, these bits indicate specific jetsam condition.
511 */
512 #define NOTE_EXIT_MEMORY_DETAIL_MASK 0xfe000000
513 #define NOTE_EXIT_MEMORY_VMPAGESHORTAGE 0x80000000 /* jetsam condition: lowest jetsam priority proc killed due to vm page shortage */
514 #define NOTE_EXIT_MEMORY_VMTHRASHING 0x40000000 /* jetsam condition: lowest jetsam priority proc killed due to vm thrashing */
515 #define NOTE_EXIT_MEMORY_HIWAT 0x20000000 /* jetsam condition: process reached its high water mark */
516 #define NOTE_EXIT_MEMORY_PID 0x10000000 /* jetsam condition: special pid kill requested */
517 #define NOTE_EXIT_MEMORY_IDLE 0x08000000 /* jetsam condition: idle process cleaned up */
518 #define NOTE_EXIT_MEMORY_VNODE 0X04000000 /* jetsam condition: virtual node kill */
519 #define NOTE_EXIT_MEMORY_FCTHRASHING 0x02000000 /* jetsam condition: lowest jetsam priority proc killed due to filecache thrashing */
520
521 #endif
522
523 /*
524 * data/hint fflags for EVFILT_VM, shared with userspace.
525 */
526 #define NOTE_VM_PRESSURE 0x80000000 /* will react on memory pressure */
527 #define NOTE_VM_PRESSURE_TERMINATE 0x40000000 /* will quit on memory pressure, possibly after cleaning up dirty state */
528 #define NOTE_VM_PRESSURE_SUDDEN_TERMINATE 0x20000000 /* will quit immediately on memory pressure */
529 #define NOTE_VM_ERROR 0x10000000 /* there was an error */
530
531 #ifdef PRIVATE
532
533 /*
534 * data/hint fflags for EVFILT_MEMORYSTATUS, shared with userspace.
535 */
536 #define NOTE_MEMORYSTATUS_PRESSURE_NORMAL 0x00000001 /* system memory pressure has returned to normal */
537 #define NOTE_MEMORYSTATUS_PRESSURE_WARN 0x00000002 /* system memory pressure has changed to the warning state */
538 #define NOTE_MEMORYSTATUS_PRESSURE_CRITICAL 0x00000004 /* system memory pressure has changed to the critical state */
539 #define NOTE_MEMORYSTATUS_LOW_SWAP 0x00000008 /* system is in a low-swap state */
540 #define NOTE_MEMORYSTATUS_PROC_LIMIT_WARN 0x00000010 /* process memory limit has hit a warning state */
541 #define NOTE_MEMORYSTATUS_PROC_LIMIT_CRITICAL 0x00000020 /* process memory limit has hit a critical state - soft limit */
542 #define NOTE_MEMORYSTATUS_MSL_STATUS 0xf0000000 /* bits used to request change to process MSL status */
543
544 #ifdef KERNEL_PRIVATE
545 /*
546 * data/hint fflags for EVFILT_MEMORYSTATUS, but not shared with userspace.
547 */
548 #define NOTE_MEMORYSTATUS_PROC_LIMIT_WARN_ACTIVE 0x00000040 /* Used to restrict sending a warn event only once, per active limit, soft limits only */
549 #define NOTE_MEMORYSTATUS_PROC_LIMIT_WARN_INACTIVE 0x00000080 /* Used to restrict sending a warn event only once, per inactive limit, soft limit only */
550 #define NOTE_MEMORYSTATUS_PROC_LIMIT_CRITICAL_ACTIVE 0x00000100 /* Used to restrict sending a critical event only once per active limit, soft limit only */
551 #define NOTE_MEMORYSTATUS_PROC_LIMIT_CRITICAL_INACTIVE 0x00000200 /* Used to restrict sending a critical event only once per inactive limit, soft limit only */
552 #define NOTE_MEMORYSTATUS_JETSAM_FG_BAND 0x00000400 /* jetsam is approaching foreground band */
553
554 /*
555 * Use this mask to protect the kernel private flags.
556 */
557 #define EVFILT_MEMORYSTATUS_ALL_MASK \
558 (NOTE_MEMORYSTATUS_PRESSURE_NORMAL | NOTE_MEMORYSTATUS_PRESSURE_WARN | NOTE_MEMORYSTATUS_PRESSURE_CRITICAL | NOTE_MEMORYSTATUS_LOW_SWAP | \
559 NOTE_MEMORYSTATUS_PROC_LIMIT_WARN | NOTE_MEMORYSTATUS_PROC_LIMIT_CRITICAL | NOTE_MEMORYSTATUS_MSL_STATUS)
560
561 #endif /* KERNEL_PRIVATE */
562
563 typedef enum vm_pressure_level {
564 kVMPressureNormal = 0,
565 kVMPressureWarning = 1,
566 kVMPressureUrgent = 2,
567 kVMPressureCritical = 3,
568 kVMPressureJetsam = 4, /* jetsam approaching FG bands */
569 } vm_pressure_level_t;
570
571 #endif /* PRIVATE */
572
573 /*
574 * data/hint fflags for EVFILT_TIMER, shared with userspace.
575 * The default is a (repeating) interval timer with the data
576 * specifying the timeout interval in milliseconds.
577 *
578 * All timeouts are implicitly EV_CLEAR events.
579 */
580 #define NOTE_SECONDS 0x00000001 /* data is seconds */
581 #define NOTE_USECONDS 0x00000002 /* data is microseconds */
582 #define NOTE_NSECONDS 0x00000004 /* data is nanoseconds */
583 #define NOTE_ABSOLUTE 0x00000008 /* absolute timeout */
584 /* ... implicit EV_ONESHOT, timeout uses the gettimeofday epoch */
585 #define NOTE_LEEWAY 0x00000010 /* ext[1] holds leeway for power aware timers */
586 #define NOTE_CRITICAL 0x00000020 /* system does minimal timer coalescing */
587 #define NOTE_BACKGROUND 0x00000040 /* system does maximum timer coalescing */
588 #define NOTE_MACH_CONTINUOUS_TIME 0x00000080
589 /*
590 * NOTE_MACH_CONTINUOUS_TIME:
591 * with NOTE_ABSOLUTE: causes the timer to continue to tick across sleep,
592 * still uses gettimeofday epoch
593 * with NOTE_MACHTIME and NOTE_ABSOLUTE: uses mach continuous time epoch
594 * without NOTE_ABSOLUTE (interval timer mode): continues to tick across sleep
595 */
596 #define NOTE_MACHTIME 0x00000100 /* data is mach absolute time units */
597 /* timeout uses the mach absolute time epoch */
598
599 #ifdef PRIVATE
600 /*
601 * data/hint fflags for EVFILT_SOCK, shared with userspace.
602 *
603 */
604 #define NOTE_CONNRESET 0x00000001 /* Received RST */
605 #define NOTE_READCLOSED 0x00000002 /* Read side is shutdown */
606 #define NOTE_WRITECLOSED 0x00000004 /* Write side is shutdown */
607 #define NOTE_TIMEOUT 0x00000008 /* timeout: rexmt, keep-alive or persist */
608 #define NOTE_NOSRCADDR 0x00000010 /* source address not available */
609 #define NOTE_IFDENIED 0x00000020 /* interface denied connection */
610 #define NOTE_SUSPEND 0x00000040 /* output queue suspended */
611 #define NOTE_RESUME 0x00000080 /* output queue resumed */
612 #define NOTE_KEEPALIVE 0x00000100 /* TCP Keepalive received */
613 #define NOTE_ADAPTIVE_WTIMO 0x00000200 /* TCP adaptive write timeout */
614 #define NOTE_ADAPTIVE_RTIMO 0x00000400 /* TCP adaptive read timeout */
615 #define NOTE_CONNECTED 0x00000800 /* socket is connected */
616 #define NOTE_DISCONNECTED 0x00001000 /* socket is disconnected */
617 #define NOTE_CONNINFO_UPDATED 0x00002000 /* connection info was updated */
618 #define NOTE_NOTIFY_ACK 0x00004000 /* notify acknowledgement */
619 #define NOTE_WAKE_PKT 0x00008000 /* received wake packet */
620
621 #define EVFILT_SOCK_LEVEL_TRIGGER_MASK \
622 (NOTE_READCLOSED | NOTE_WRITECLOSED | NOTE_SUSPEND | NOTE_RESUME | \
623 NOTE_CONNECTED | NOTE_DISCONNECTED)
624
625 #define EVFILT_SOCK_ALL_MASK \
626 (NOTE_CONNRESET | NOTE_READCLOSED | NOTE_WRITECLOSED | NOTE_TIMEOUT | \
627 NOTE_NOSRCADDR | NOTE_IFDENIED | NOTE_SUSPEND | NOTE_RESUME | \
628 NOTE_KEEPALIVE | NOTE_ADAPTIVE_WTIMO | NOTE_ADAPTIVE_RTIMO | \
629 NOTE_CONNECTED | NOTE_DISCONNECTED | NOTE_CONNINFO_UPDATED | \
630 NOTE_NOTIFY_ACK | NOTE_WAKE_PKT)
631
632 #endif /* PRIVATE */
633
634 /*
635 * data/hint fflags for EVFILT_MACHPORT, shared with userspace.
636 *
637 * Only portsets are supported at this time.
638 *
639 * The fflags field can optionally contain the MACH_RCV_MSG, MACH_RCV_LARGE,
640 * and related trailer receive options as defined in <mach/message.h>.
641 * The presence of these flags directs the kevent64() call to attempt to receive
642 * the message during kevent delivery, rather than just indicate that a message exists.
643 * On setup, The ext[0] field contains the receive buffer pointer and ext[1] contains
644 * the receive buffer length. Upon event delivery, the actual received message size
645 * is returned in ext[1]. As with mach_msg(), the buffer must be large enough to
646 * receive the message and the requested (or default) message trailers. In addition,
647 * the fflags field contains the return code normally returned by mach_msg().
648 *
649 * If MACH_RCV_MSG is specified, and the ext[1] field specifies a zero length, the
650 * system call argument specifying an ouput area (kevent_qos) will be consulted. If
651 * the system call specified an output data area, the user-space address
652 * of the received message is carved from that provided output data area (if enough
653 * space remains there). The address and length of each received message is
654 * returned in the ext[0] and ext[1] fields (respectively) of the corresponding kevent.
655 *
656 * IF_MACH_RCV_VOUCHER_CONTENT is specified, the contents of the message voucher is
657 * extracted (as specified in the xflags field) and stored in ext[2] up to ext[3]
658 * length. If the input length is zero, and the system call provided a data area,
659 * the space for the voucher content is carved from the provided space and its
660 * address and length is returned in ext[2] and ext[3] respectively.
661 *
662 * If no message receipt options were provided in the fflags field on setup, no
663 * message is received by this call. Instead, on output, the data field simply
664 * contains the name of the actual port detected with a message waiting.
665 */
666
667 /*
668 * DEPRECATED!!!!!!!!!
669 * NOTE_TRACK, NOTE_TRACKERR, and NOTE_CHILD are no longer supported as of 10.5
670 */
671 /* additional flags for EVFILT_PROC */
672 #define NOTE_TRACK 0x00000001 /* follow across forks */
673 #define NOTE_TRACKERR 0x00000002 /* could not track child */
674 #define NOTE_CHILD 0x00000004 /* am a child process */
675
676
677 #ifdef PRIVATE
678 /*
679 * data/hint fflags for EVFILT_NW_CHANNEL, shared with userspace.
680 */
681 #define NOTE_FLOW_ADV_UPDATE 0x00000001 /* flow advisory update */
682 #define NOTE_CHANNEL_EVENT 0x00000002 /* generic channel event */
683 #define NOTE_IF_ADV_UPD 0x00000004 /* Interface advisory update */
684
685 #define EVFILT_NW_CHANNEL_ALL_MASK \
686 (NOTE_FLOW_ADV_UPDATE | NOTE_CHANNEL_EVENT | NOTE_IF_ADV_UPD)
687 #endif /* PRIVATE */
688
689 #ifndef KERNEL
690 /* Temporay solution for BootX to use inode.h till kqueue moves to vfs layer */
691 struct knote;
692 SLIST_HEAD(klist, knote);
693 #endif
694
695 #ifdef KERNEL
696
697 #ifdef XNU_KERNEL_PRIVATE
698 LIST_HEAD(knote_list, knote);
699 TAILQ_HEAD(kqtailq, knote); /* a list of "queued" events */
700
701 /* index into various kq queues */
702 typedef uint8_t kq_index_t;
703
704 /* lskq(1) knows about this type */
705 __options_decl(kn_status_t, uint16_t /* 12 bits really */, {
706 KN_ACTIVE = 0x001, /* event has been triggered */
707 KN_QUEUED = 0x002, /* event is on queue */
708 KN_DISABLED = 0x004, /* event is disabled */
709 KN_DROPPING = 0x008, /* knote is being dropped */
710 KN_LOCKED = 0x010, /* knote is locked (kq_knlocks) */
711 KN_POSTING = 0x020, /* f_event() in flight */
712 // was KN_STAYACTIVE = 0x040,
713 KN_DEFERDELETE = 0x080, /* defer delete until re-enabled */
714 KN_MERGE_QOS = 0x100, /* f_event() / f_* ran concurrently and overrides must merge */
715 KN_REQVANISH = 0x200, /* requested EV_VANISH */
716 KN_VANISHED = 0x400, /* has vanished */
717 KN_SUPPRESSED = 0x800, /* event is suppressed during delivery */
718 });
719
720 #if __LP64__
721 #define KNOTE_KQ_PACKED_BITS 42
722 #define KNOTE_KQ_PACKED_SHIFT 0
723 #define KNOTE_KQ_PACKED_BASE 0
724 #else
725 #define KNOTE_KQ_PACKED_BITS 32
726 #define KNOTE_KQ_PACKED_SHIFT 0
727 #define KNOTE_KQ_PACKED_BASE 0
728 #endif
729
730 _Static_assert(!VM_PACKING_IS_BASE_RELATIVE(KNOTE_KQ_PACKED),
731 "Make sure the knote pointer packing is based on arithmetic shifts");
732
733 struct kqueue;
734 struct knote {
735 TAILQ_ENTRY(knote) kn_tqe; /* linkage for tail queue */
736 SLIST_ENTRY(knote) kn_link; /* linkage for search list */
737 SLIST_ENTRY(knote) kn_selnext; /* klist element chain */
738
739 kn_status_t kn_status : 12;
740 uintptr_t
741 kn_qos_index:4, /* in-use qos index */
742 kn_qos_override:3, /* qos override index */
743 kn_is_fd:1, /* knote is an fd */
744 kn_vnode_kqok:1,
745 kn_vnode_use_ofst:1;
746 #if __LP64__
747 uintptr_t kn_kq_packed : KNOTE_KQ_PACKED_BITS;
748 #else
749 uintptr_t kn_kq_packed;
750 #endif
751
752 /* per filter stash of data (pointer, uint32_t or uint64_t) */
753 union {
754 void *kn_hook;
755 uint32_t kn_hook32;
756 };
757
758 /* per filter pointer to the resource being watched */
759 union {
760 struct fileproc *kn_fp;
761 struct proc *kn_proc;
762 struct ipc_object *kn_ipc_obj;
763 struct thread_call *kn_thcall;
764 struct thread *kn_thread;
765 };
766
767 /*
768 * Mimic kevent_qos so that knote_fill_kevent code is not horrid,
769 * but with subtleties:
770 *
771 * - kevent_qos_s::filter is 16bits where ours is 8, and we use the top
772 * bits to store the real specialized filter.
773 * knote_fill_kevent* will always force the top bits to 0xff.
774 *
775 * - kevent_qos_s::xflags is not kept, kn_sfflags takes its place,
776 * knote_fill_kevent* will set xflags to 0.
777 *
778 * - kevent_qos_s::data is saved as kn_sdata and filters are encouraged
779 * to use knote_fill_kevent, knote_fill_kevent_with_sdata will copy
780 * kn_sdata as the output value.
781 *
782 * knote_fill_kevent_with_sdata() programatically asserts
783 * these aliasings are respected.
784 */
785 struct kevent_internal_s {
786 uint64_t kei_ident; /* identifier for this event */
787 #ifdef __LITTLE_ENDIAN__
788 int8_t kei_filter; /* filter for event */
789 uint8_t kei_filtid; /* actual filter for event */
790 #else
791 uint8_t kei_filtid; /* actual filter for event */
792 int8_t kei_filter; /* filter for event */
793 #endif
794 uint16_t kei_flags; /* general flags */
795 int32_t kei_qos; /* quality of service */
796 uint64_t kei_udata; /* opaque user data identifier */
797 uint32_t kei_fflags; /* filter-specific flags */
798 uint32_t kei_sfflags; /* knote: saved fflags */
799 int64_t kei_sdata; /* knote: filter-specific saved data */
800 uint64_t kei_ext[4]; /* filter-specific extensions */
801 } kn_kevent;
802
803 #define kn_id kn_kevent.kei_ident
804 #define kn_filtid kn_kevent.kei_filtid
805 #define kn_filter kn_kevent.kei_filter
806 #define kn_flags kn_kevent.kei_flags
807 #define kn_qos kn_kevent.kei_qos
808 #define kn_udata kn_kevent.kei_udata
809 #define kn_fflags kn_kevent.kei_fflags
810 #define kn_sfflags kn_kevent.kei_sfflags
811 #define kn_sdata kn_kevent.kei_sdata
812 #define kn_ext kn_kevent.kei_ext
813 };
814
815 static inline struct kqueue *
knote_get_kq(struct knote * kn)816 knote_get_kq(struct knote *kn)
817 {
818 vm_offset_t ptr = VM_UNPACK_POINTER(kn->kn_kq_packed, KNOTE_KQ_PACKED);
819 return __unsafe_forge_single(struct kqueue *, ptr);
820 }
821
822 static inline int
knote_get_seltype(struct knote * kn)823 knote_get_seltype(struct knote *kn)
824 {
825 switch (kn->kn_filter) {
826 case EVFILT_READ:
827 return FREAD;
828 case EVFILT_WRITE:
829 return FWRITE;
830 default:
831 panic("%s(%p): invalid filter %d\n",
832 __func__, kn, kn->kn_filter);
833 return 0;
834 }
835 }
836
837 struct kevent_ctx_s {
838 uint64_t kec_data_avail; /* address of remaining data size */
839 user_addr_t kec_data_out; /* extra data pointer */
840 user_size_t kec_data_size; /* total extra data size */
841 user_size_t kec_data_resid; /* residual extra data size */
842 uint64_t kec_deadline; /* wait deadline unless KEVENT_FLAG_IMMEDIATE */
843 struct fileproc *kec_fp; /* fileproc to pass to fp_drop or NULL */
844 int kec_fd; /* fd to pass to fp_drop or -1 */
845
846 /* the fields below are only set during process / scan */
847 int kec_process_nevents; /* user-level event count */
848 int kec_process_noutputs; /* number of events output */
849 unsigned int kec_process_flags; /* kevent flags, only set for process */
850 user_addr_t kec_process_eventlist; /* user-level event list address */
851 };
852 typedef struct kevent_ctx_s *kevent_ctx_t;
853
854 kevent_ctx_t
855 kevent_get_context(thread_t thread);
856
857 /*
858 * Filter operators
859 *
860 * These routines, provided by each filter, are called to attach, detach, deliver events,
861 * change/update filter registration and process/deliver events:
862 *
863 * - the f_attach, f_touch, f_process and f_detach callbacks are always
864 * serialized with respect to each other for the same knote.
865 *
866 * - the f_event routine is called with a use-count taken on the knote to
867 * prolongate its lifetime and protect against drop, but is not otherwise
868 * serialized with other routine calls.
869 *
870 * - the f_detach routine is always called last, and is serialized with all
871 * other callbacks, including f_event calls.
872 *
873 *
874 * Here are more details:
875 *
876 * f_isfd -
877 * identifies if the "ident" field in the kevent structure is a file-descriptor.
878 *
879 * If so, the knote is associated with the file descriptor prior to attach and
880 * auto-removed when the file descriptor is closed (this latter behavior may change
881 * for EV_DISPATCH2 kevent types to allow delivery of events identifying unintended
882 * closes).
883 *
884 * Otherwise the knote is hashed by the ident and has no auto-close behavior.
885 *
886 * f_adjusts_qos -
887 * identifies if the filter can adjust its QoS during its lifetime.
888 *
889 * Filters using this facility should request the new overrides they want
890 * using the appropriate FILTER_{RESET,ADJUST}_EVENT_QOS extended codes.
891 *
892 * Currently, EVFILT_MACHPORT is the only filter using this facility.
893 *
894 * f_extended_codes -
895 * identifies if the filter returns extended codes from its routines
896 * (see FILTER_ACTIVE, ...) or 0 / 1 values.
897 *
898 * f_attach -
899 * called to attach the knote to the underlying object that will be delivering events
900 * through it when EV_ADD is supplied and no existing matching event is found
901 *
902 * provided a knote that is pre-attached to the fd or hashed (see above) but is
903 * specially marked to avoid concurrent access until the attach is complete. The
904 * kevent structure embedded in this knote has been filled in with a sanitized
905 * version of the user-supplied kevent data. However, the user-supplied filter-specific
906 * flags (fflags) and data fields have been moved into the knote's kn_sfflags and kn_sdata
907 * fields respectively. These are usually interpretted as a set of "interest" flags and
908 * data by each filter - to be matched against delivered events.
909 *
910 * The attach operator indicated errors by setting the EV_ERROR flog in the flags field
911 * embedded in the knote's kevent structure - with the specific error indicated in the
912 * corresponding data field.
913 *
914 * The return value indicates if the knote should already be considered "activated" at
915 * the time of attach (one or more of the interest events has already occured).
916 *
917 * f_detach -
918 * called to disassociate the knote from the underlying object delivering events
919 * the filter should not attempt to deliver events through this knote after this
920 * operation returns control to the kq system.
921 *
922 * f_event -
923 * if the knote() function (or KNOTE() macro) is called against a list of knotes,
924 * this operator will be called on each knote in the list.
925 *
926 * The "hint" parameter is completely filter-specific, but usually indicates an
927 * event or set of events that have occured against the source object associated
928 * with the list.
929 *
930 * The return value indicates if the knote should already be considered "activated" at
931 * the time of attach (one or more of the interest events has already occured).
932 *
933 * f_process -
934 * called when attempting to deliver triggered events to user-space.
935 *
936 * If the knote was previously activated, this operator will be called when a
937 * thread is trying to deliver events to user-space. The filter gets one last
938 * chance to determine if the event/events are still interesting for this knote
939 * (are the conditions still right to deliver an event). If so, the filter
940 * fills in the output kevent structure with the information to be delivered.
941 *
942 * The input context/data parameter is used during event delivery. Some
943 * filters allow additional data delivery as part of event delivery. This
944 * context field indicates if space was made available for these additional
945 * items and how that space is to be allocated/carved-out.
946 *
947 * The filter may set EV_CLEAR or EV_ONESHOT in the output flags field to indicate
948 * special post-delivery dispositions for the knote.
949 *
950 * EV_CLEAR - indicates that all matching events have been delivered. Even
951 * though there were events to deliver now, there will not be any
952 * more until some additional events are delivered to the knote
953 * via the f_event operator, or the interest set is changed via
954 * the f_touch operator. The knote can remain deactivated after
955 * processing this event delivery.
956 *
957 * EV_ONESHOT - indicates that this is the last event to be delivered via
958 * this knote. It will automatically be deleted upon delivery
959 * (or if in dispatch-mode, upon re-enablement after this delivery).
960 *
961 * The return value indicates if the knote has delivered an output event.
962 * Unless one of the special output flags was set in the output kevent, a non-
963 * zero return value ALSO indicates that the knote should be re-activated
964 * for future event processing (in case it delivers level-based or a multi-edge
965 * type events like message queues that already exist).
966 *
967 * NOTE: In the future, the boolean may change to an enum that allows more
968 * explicit indication of just delivering a current event vs delivering
969 * an event with more events still pending.
970 *
971 * f_touch -
972 * called to update the knote with new state from the user during
973 * EVFILT_ADD/ENABLE/DISABLE on an already-attached knote.
974 *
975 * f_touch should copy relevant new data from the kevent into the knote.
976 *
977 * operator must lock against concurrent f_event operations.
978 *
979 * A return value of 1 indicates that the knote should now be considered
980 * 'activated'.
981 *
982 * f_touch can set EV_ERROR with specific error in the data field to
983 * return an error to the client. You should return 1 to indicate that
984 * the kevent needs to be activated and processed.
985 *
986 * f_allow_drop -
987 *
988 * [OPTIONAL] If this function is non-null, then it indicates that the
989 * filter wants to validate EV_DELETE events. This is necessary if
990 * a particular filter needs to synchronize knote deletion with its own
991 * filter lock.
992 *
993 * When true is returned, the the EV_DELETE is allowed and can proceed.
994 *
995 * If false is returned, the EV_DELETE doesn't proceed, and the passed in
996 * kevent is used for the copyout to userspace.
997 *
998 * Currently, EVFILT_WORKLOOP is the only filter using this facility.
999 *
1000 * f_post_register_wait -
1001 * [OPTIONAL] called when attach or touch return the FILTER_REGISTER_WAIT
1002 * extended code bit. It is possible to use this facility when the last
1003 * register command wants to wait.
1004 *
1005 * Currently, EVFILT_WORKLOOP is the only filter using this facility.
1006 *
1007 * f_sanitized_copyout -
1008 * [OPTIONAL] If this function is non-null, then it should be used so
1009 * that the filter can provide a sanitized copy of the current contents
1010 * of a knote to userspace. This prevents leaking of any sensitive
1011 * information like kernel pointers which might be stashed in filter
1012 * specific data.
1013 *
1014 * Currently, EVFILT_MACHPORT uses this facility.
1015 */
1016
1017 struct _kevent_register;
1018 struct knote_lock_ctx;
1019 struct proc;
1020 struct uthread;
1021 struct waitq;
1022 struct thread_group;
1023
1024 struct filterops {
1025 bool f_isfd; /* true if ident == filedescriptor */
1026 bool f_adjusts_qos; /* true if the filter can override the knote */
1027 bool f_extended_codes; /* hooks return extended codes */
1028
1029 int (*f_attach)(struct knote *kn, struct kevent_qos_s *kev);
1030 void (*f_detach)(struct knote *kn);
1031 int (*f_event)(struct knote *kn, long hint);
1032 int (*f_touch)(struct knote *kn, struct kevent_qos_s *kev);
1033 int (*f_process)(struct knote *kn, struct kevent_qos_s *kev);
1034
1035 /* optional & advanced */
1036 bool (*f_allow_drop)(struct knote *kn, struct kevent_qos_s *kev);
1037 void (*f_post_register_wait)(struct uthread *uth, struct knote *kn,
1038 struct _kevent_register *ss_kr);
1039 void (*f_sanitized_copyout)(struct knote *kn, struct kevent_qos_s *kev);
1040 };
1041
1042 /*
1043 * Extended codes returned by filter routines when f_extended_codes is set.
1044 *
1045 * FILTER_ACTIVE
1046 * The filter is active and a call to f_process() may return an event.
1047 *
1048 * For f_process() the meaning is slightly different: the knote will be
1049 * activated again as long as f_process returns FILTER_ACTIVE, unless
1050 * EV_CLEAR is set, which require a new f_event to reactivate the knote.
1051 *
1052 * Valid: f_attach, f_event, f_touch, f_process
1053 * Implicit: -
1054 * Ignored: -
1055 *
1056 * FILTER_REGISTER_WAIT
1057 * The filter wants its f_post_register_wait() to be called.
1058 *
1059 * Note: It is only valid to ask for this behavior for a workloop kqueue,
1060 * and is really only meant to be used by EVFILT_WORKLOOP.
1061 *
1062 * Valid: f_attach, f_touch
1063 * Implicit: -
1064 * Ignored: f_event, f_process
1065 *
1066 * FILTER_UPDATE_REQ_QOS
1067 * The filter wants the passed in QoS to be updated as the new intrinsic qos
1068 * for this knote. If the kevent `qos` field is 0, no update is performed.
1069 *
1070 * This also will reset the event QoS, so FILTER_ADJUST_EVENT_QOS() must
1071 * also be used if an override should be maintained.
1072 *
1073 * Note: when this is used in f_touch, the incoming qos validation
1074 * is under the responsiblity of the filter.
1075 *
1076 * Valid: f_touch
1077 * Implicit: f_attach
1078 * Ignored: f_event, f_process
1079 *
1080 * FILTER_RESET_EVENT_QOS
1081 * FILTER_ADJUST_EVENT_QOS(qos)
1082 * The filter wants the QoS of the next event delivery to be overridden
1083 * at the specified QoS. This allows for the next event QoS to be elevated
1084 * from the knote requested qos (See FILTER_UPDATE_REQ_QOS).
1085 *
1086 * Event QoS Overrides are reset when a particular knote is no longer
1087 * active. Hence this is ignored if FILTER_ACTIVE isn't also returned.
1088 *
1089 * Races between an f_event() and any other f_* routine asking for
1090 * a specific QoS override are handled generically and the filters do not
1091 * have to worry about them.
1092 *
1093 * To use this facility, filters MUST set their f_adjusts_qos bit to true.
1094 *
1095 * It is expected that filters will return the new QoS they expect to be
1096 * applied from any f_* callback except for f_process() where no specific
1097 * information should be provided. Filters should not try to hide no-ops,
1098 * kevent will already optimize these away.
1099 *
1100 * Valid: f_touch, f_attach, f_event, f_process
1101 * Implicit: -
1102 * Ignored: -
1103 *
1104 * FILTER_THREADREQ_NODEFEER
1105 * The filter has moved a turnstile priority push away from the current
1106 * thread, preemption has been disabled, and thread requests need to be
1107 * commited before preemption is re-enabled.
1108 *
1109 *
1110 * Valid: f_attach, f_touch
1111 * Implicit: -
1112 * Invalid: f_event, f_process
1113 */
1114 #define FILTER_ACTIVE 0x00000001
1115 #define FILTER_REGISTER_WAIT 0x00000002
1116 #define FILTER_UPDATE_REQ_QOS 0x00000004
1117 #define FILTER_ADJUST_EVENT_QOS_BIT 0x00000008
1118 #define FILTER_ADJUST_EVENT_QOS_MASK 0x00000070
1119 #define FILTER_ADJUST_EVENT_QOS_SHIFT 4
1120 #define FILTER_ADJUST_EVENT_QOS(qos) \
1121 (((qos) << FILTER_ADJUST_EVENT_QOS_SHIFT) | FILTER_ADJUST_EVENT_QOS_BIT)
1122 #define FILTER_GET_EVENT_QOS(result) \
1123 ((result >> FILTER_ADJUST_EVENT_QOS_SHIFT) & THREAD_QOS_LAST)
1124 #define FILTER_RESET_EVENT_QOS FILTER_ADJUST_EVENT_QOS_BIT
1125 #define FILTER_THREADREQ_NODEFEER 0x00000080
1126 #define FILTER_ADJUST_EVENT_IOTIER_BIT 0x00000100
1127
1128 #define filter_call(_ops, call) \
1129 ((_ops)->f_extended_codes ? (_ops)->call : !!((_ops)->call))
1130
1131 SLIST_HEAD(klist, knote);
1132 extern void knote_init(void);
1133 extern void klist_init(struct klist *list);
1134
1135 #define KNOTE(list, hint) knote(list, hint)
1136 #define KNOTE_ATTACH(list, kn) knote_attach(list, kn)
1137 #define KNOTE_DETACH(list, kn) knote_detach(list, kn)
1138
1139 extern void knote(struct klist *list, long hint);
1140 extern int knote_attach(struct klist *list, struct knote *kn);
1141 extern int knote_detach(struct klist *list, struct knote *kn);
1142 extern void knote_vanish(struct klist *list, bool make_active);
1143
1144 extern void knote_set_error(struct knote *kn, int error);
1145 extern int64_t knote_low_watermark(const struct knote *kn) __pure2;
1146 extern void knote_fill_kevent_with_sdata(struct knote *kn, struct kevent_qos_s *kev);
1147 extern void knote_fill_kevent(struct knote *kn, struct kevent_qos_s *kev, int64_t data);
1148
1149 extern void knote_fdclose(struct proc *p, int fd);
1150 extern const struct filterops *knote_fops(struct knote *kn);
1151
1152 extern struct turnstile *kqueue_turnstile(struct kqueue *);
1153 extern struct turnstile *kqueue_alloc_turnstile(struct kqueue *);
1154 extern void kqueue_set_iotier_override(struct kqueue *kqu, uint8_t iotier_override);
1155 extern uint8_t kqueue_get_iotier_override(struct kqueue *kqu);
1156
1157 int kevent_proc_copy_uptrs(void *proc, uint64_t *buf, uint32_t bufsize);
1158 #if CONFIG_PREADOPT_TG
1159 extern void kqueue_set_preadopted_thread_group(struct kqueue *kq, struct thread_group *tg, thread_qos_t qos);
1160 extern bool kqueue_process_preadopt_thread_group(thread_t t, struct kqueue *kq, struct thread_group *tg);
1161 #endif
1162
1163 int kevent_copyout_proc_dynkqids(void *proc, user_addr_t ubuf,
1164 uint32_t ubufsize, int32_t *nkqueues_out);
1165 int kevent_copyout_dynkqinfo(void *proc, kqueue_id_t kq_id, user_addr_t ubuf,
1166 uint32_t ubufsize, int32_t *size_out);
1167 int kevent_copyout_dynkqextinfo(void *proc, kqueue_id_t kq_id, user_addr_t ubuf,
1168 uint32_t ubufsize, int32_t *nknotes_out);
1169
1170 extern int filt_wlattach_sync_ipc(struct knote *kn);
1171 extern void filt_wldetach_sync_ipc(struct knote *kn);
1172
1173 extern int kevent_workq_internal(struct proc *p,
1174 user_addr_t changelist, int nchanges,
1175 user_addr_t eventlist, int nevents,
1176 user_addr_t data_out, user_size_t *data_available,
1177 unsigned int flags, int32_t *retval);
1178
1179 #elif defined(KERNEL_PRIVATE) /* !XNU_KERNEL_PRIVATE: kexts still need a klist structure definition */
1180
1181 struct proc;
1182 struct knote;
1183 SLIST_HEAD(klist, knote);
1184
1185 #endif /* !XNU_KERNEL_PRIVATE && KERNEL_PRIVATE */
1186
1187 #else /* KERNEL */
1188
1189 struct timespec;
1190
1191 __BEGIN_DECLS
1192 int kqueue(void);
1193 int kevent(int kq,
1194 const struct kevent *changelist, int nchanges,
1195 struct kevent *eventlist, int nevents,
1196 const struct timespec *timeout);
1197 int kevent64(int kq,
1198 const struct kevent64_s *changelist, int nchanges,
1199 struct kevent64_s *eventlist, int nevents,
1200 unsigned int flags,
1201 const struct timespec *timeout);
1202
1203 #ifdef PRIVATE
1204 int kevent_qos(int kq,
1205 const struct kevent_qos_s *changelist, int nchanges,
1206 struct kevent_qos_s *eventlist, int nevents,
1207 void *data_out, size_t *data_available,
1208 unsigned int flags);
1209
1210 int kevent_id(kqueue_id_t id,
1211 const struct kevent_qos_s *changelist, int nchanges,
1212 struct kevent_qos_s *eventlist, int nevents,
1213 void *data_out, size_t *data_available,
1214 unsigned int flags);
1215 #endif /* PRIVATE */
1216
1217 __END_DECLS
1218
1219
1220 #endif /* KERNEL */
1221
1222 #ifdef PRIVATE
1223
1224 /* Flags for pending events notified by kernel via return-to-kernel ast */
1225 #define R2K_WORKLOOP_PENDING_EVENTS 0x1
1226 #define R2K_WORKQ_PENDING_EVENTS 0x2
1227
1228 /* Flags for notifying what to do when there is a workqueue quantum expiry */
1229 #define PTHREAD_WQ_QUANTUM_EXPIRY_NARROW 0x1
1230 #define PTHREAD_WQ_QUANTUM_EXPIRY_SHUFFLE 0x2
1231
1232 #endif /* PRIVATE */
1233
1234 #endif /* !_SYS_EVENT_H_ */
1235