1/*
2 * Copyright (c) 2000-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/* Copyright (c) 1998, 1999 Apple Computer, Inc. All Rights Reserved */
29/*!
30 * @header kern_event.h
31 * This header defines in-kernel functions for generating kernel events as
32 * well as functions for receiving kernel events using a kernel event
33 * socket.
34 */
35
36#ifndef SYS_KERN_EVENT_H
37#define SYS_KERN_EVENT_H
38
39#include <sys/appleapiopts.h>
40#include <sys/ioccom.h>
41#include <sys/sys_domain.h>
42
43#define KEV_SNDSPACE (4 * 1024)
44#define KEV_RECVSPACE (32 * 1024)
45
46#define KEV_ANY_VENDOR 0
47#define KEV_ANY_CLASS 0
48#define KEV_ANY_SUBCLASS 0
49
50/*
51 * Vendor Code
52 */
53
54/*!
55 * @defined KEV_VENDOR_APPLE
56 * @discussion Apple generated kernel events use the hard coded vendor code
57 * value of 1. Third party kernel events use a dynamically allocated vendor
58 * code. The vendor code can be found using the SIOCGKEVVENDOR ioctl.
59 */
60#define KEV_VENDOR_APPLE 1
61
62/*
63 * Definition of top-level classifications for KEV_VENDOR_APPLE
64 */
65
66/*!
67 * @defined KEV_NETWORK_CLASS
68 * @discussion Network kernel event class.
69 */
70#define KEV_NETWORK_CLASS 1
71
72/*!
73 * @defined KEV_IOKIT_CLASS
74 * @discussion IOKit kernel event class.
75 */
76#define KEV_IOKIT_CLASS 2
77
78/*!
79 * @defined KEV_SYSTEM_CLASS
80 * @discussion System kernel event class.
81 */
82#define KEV_SYSTEM_CLASS 3
83
84/*!
85 * @defined KEV_APPLESHARE_CLASS
86 * @discussion AppleShare kernel event class.
87 */
88#define KEV_APPLESHARE_CLASS 4
89
90/*!
91 * @defined KEV_FIREWALL_CLASS
92 * @discussion Firewall kernel event class.
93 */
94#define KEV_FIREWALL_CLASS 5
95
96/*!
97 * @defined KEV_IEEE80211_CLASS
98 * @discussion IEEE 802.11 kernel event class.
99 */
100#define KEV_IEEE80211_CLASS 6
101
102/*!
103 * @defined KEV_NKE_CLASS
104 * @discussion NKE kernel event class.
105 */
106#define KEV_NKE_CLASS 7
107
108#define KEV_NKE_ALF_SUBCLASS 1
109#define KEV_NKE_ALF_STATE_CHANGED 1
110
111/*
112 * The following struct is KPI, but it was originally defined with a trailing
113 * array member of size one, intended to be used as a Variable-Length Array.
114 * That's problematic because the compiler doesn't know that the array is
115 * accessed out-of-bounds and can assume it isn't. This makes
116 * -Warray-bounds-pointer-arithmetic sad. We can't just change the code because
117 * it requires users to also change their uses of the class, at a minimum
118 * because kern_event_msg's size changes when making the last member a VLA. This
119 * macro allows users of this KPI to opt-in to the new behavior.
120 */
121#if defined(XNU_KERN_EVENT_DATA_IS_VLA)
122#define XNU_KERN_EVENT_DATA_SIZE /* nothing, it's a VLA */
123#else
124#define XNU_KERN_EVENT_DATA_SIZE 1
125#endif
126
127/*!
128 * @struct kern_event_msg
129 * @discussion This structure is prepended to all kernel events. This
130 * structure is used to determine the format of the remainder of
131 * the kernel event. This structure will appear on all messages
132 * received on a kernel event socket. To post a kernel event, a
133 * slightly different structure is used.
134 * @field total_size Total size of the kernel event message including the
135 * header.
136 * @field vendor_code The vendor code indicates which vendor generated the
137 * kernel event. This gives every vendor a unique set of classes
138 * and subclasses to use. Use the SIOCGKEVVENDOR ioctl to look up
139 * vendor codes for vendors other than Apple. Apple uses
140 * KEV_VENDOR_APPLE.
141 * @field kev_class The class of the kernel event.
142 * @field kev_subclass The subclass of the kernel event.
143 * @field id Monotonically increasing value.
144 * @field event_code The event code.
145 * @field event_data Any additional data about this event. Format will
146 * depend on the vendor_code, kev_class, kev_subclass, and
147 * event_code. The length of the event_data can be determined
148 * using total_size - KEV_MSG_HEADER_SIZE.
149 */
150struct kern_event_msg {
151 u_int32_t total_size; /* Size of entire event msg */
152 u_int32_t vendor_code; /* For non-Apple extensibility */
153 u_int32_t kev_class; /* Layer of event source */
154 u_int32_t kev_subclass; /* Component within layer */
155 u_int32_t id; /* Monotonically increasing value */
156 u_int32_t event_code; /* unique code */
157 u_int32_t event_data[XNU_KERN_EVENT_DATA_SIZE]; /* One or more data words */
158};
159
160/*!
161 * @defined KEV_MSG_HEADER_SIZE
162 * @discussion Size of the header portion of the kern_event_msg structure.
163 * This accounts for everything right up to event_data. The size
164 * of the data can be found by subtracting KEV_MSG_HEADER_SIZE
165 * from the total size from the kern_event_msg.
166 */
167#define KEV_MSG_HEADER_SIZE (offsetof(struct kern_event_msg, event_data[0]))
168
169/*!
170 * @struct kev_request
171 * @discussion This structure is used with the SIOCSKEVFILT and
172 * SIOCGKEVFILT to set and get the control filter setting for a
173 * kernel control socket.
174 * @field total_size Total size of the kernel event message including the
175 * header.
176 * @field vendor_code All kernel events that don't match this vendor code
177 * will be ignored. KEV_ANY_VENDOR can be used to receive kernel
178 * events with any vendor code.
179 * @field kev_class All kernel events that don't match this class will be
180 * ignored. KEV_ANY_CLASS can be used to receive kernel events with
181 * any class.
182 * @field kev_subclass All kernel events that don't match this subclass
183 * will be ignored. KEV_ANY_SUBCLASS can be used to receive kernel
184 * events with any subclass.
185 */
186struct kev_request {
187 u_int32_t vendor_code;
188 u_int32_t kev_class;
189 u_int32_t kev_subclass;
190};
191
192/*!
193 * @defined KEV_VENDOR_CODE_MAX_STR_LEN
194 * @discussion This define sets the maximum length of a string that can be
195 * used to identify a vendor or kext when looking up a vendor code.
196 */
197#define KEV_VENDOR_CODE_MAX_STR_LEN 200
198
199/*!
200 * @struct kev_vendor_code
201 * @discussion This structure is used with the SIOCGKEVVENDOR ioctl to
202 * convert from a string identifying a kext or vendor, in the
203 * form of a bundle identifier, to a vendor code.
204 * @field vendor_code After making the SIOCGKEVVENDOR ioctl call, this will
205 * be filled in with the vendor code if there is one.
206 * @field vendor_string A bundle style identifier.
207 */
208#pragma pack(4)
209struct kev_vendor_code {
210 u_int32_t vendor_code;
211 char vendor_string[KEV_VENDOR_CODE_MAX_STR_LEN];
212};
213#pragma pack()
214
215/*!
216 * @defined SIOCGKEVID
217 * @discussion Retrieve the current event id. Each event generated will
218 * have a new id. The next event to be generated will have an id
219 * of id+1.
220 */
221#define SIOCGKEVID _IOR('e', 1, u_int32_t)
222
223/*!
224 * @defined SIOCSKEVFILT
225 * @discussion Set the kernel event filter for this socket. Kernel events
226 * not matching this filter will not be received on this socket.
227 */
228#define SIOCSKEVFILT _IOW('e', 2, struct kev_request)
229
230/*!
231 * @defined SIOCGKEVFILT
232 * @discussion Retrieve the kernel event filter for this socket. Kernel
233 * events not matching this filter will not be received on this
234 * socket.
235 */
236#define SIOCGKEVFILT _IOR('e', 3, struct kev_request)
237
238/*!
239 * @defined SIOCGKEVVENDOR
240 * @discussion Lookup the vendor code for the specified vendor. ENOENT will
241 * be returned if a vendor code for that vendor string does not
242 * exist.
243 */
244#define SIOCGKEVVENDOR _IOWR('e', 4, struct kev_vendor_code)
245
246#ifdef PRIVATE
247struct xkevtpcb {
248 u_int32_t kep_len;
249 u_int32_t kep_kind;
250 u_int64_t kep_evtpcb;
251 u_int32_t kep_vendor_code_filter;
252 u_int32_t kep_class_filter;
253 u_int32_t kep_subclass_filter;
254};
255
256struct kevtstat {
257 u_int64_t kes_pcbcount __attribute__((aligned(8)));
258 u_int64_t kes_gencnt __attribute__((aligned(8)));
259 u_int64_t kes_badvendor __attribute__((aligned(8)));
260 u_int64_t kes_toobig __attribute__((aligned(8)));
261 u_int64_t kes_nomem __attribute__((aligned(8)));
262 u_int64_t kes_fullsock __attribute__((aligned(8)));
263 u_int64_t kes_posted __attribute__((aligned(8)));
264};
265#endif /* PRIVATE */
266
267#ifdef KERNEL
268/*!
269 * @define N_KEV_VECTORS
270 * @discussion The maximum number of kev_d_vectors for a kernel event.
271 */
272#define N_KEV_VECTORS 5
273
274/*!
275 * @struct kev_d_vectors
276 * @discussion This structure is used to append some data to a kernel
277 * event.
278 * @field data_length The length of data.
279 * @field data_ptr A pointer to data.
280 */
281struct kev_d_vectors {
282 u_int32_t data_length; /* Length of the event data */
283 void *data_ptr; /* Pointer to event data */
284};
285
286/*!
287 * @struct kev_msg
288 * @discussion This structure is used when posting a kernel event.
289 * @field vendor_code The vendor code assigned by kev_vendor_code_find.
290 * @field kev_class The event's class.
291 * @field kev_class The event's subclass.
292 * @field kev_class The event's code.
293 * @field dv An array of vectors describing additional data to be appended
294 * to the kernel event.
295 */
296struct kev_msg {
297 u_int32_t vendor_code; /* For non-Apple extensibility */
298 u_int32_t kev_class; /* Layer of event source */
299 u_int32_t kev_subclass; /* Component within layer */
300 u_int32_t event_code; /* The event code */
301 struct kev_d_vectors dv[N_KEV_VECTORS]; /* Up to n data vectors */
302};
303
304/*!
305 * @function kev_vendor_code_find
306 * @discussion Lookup a vendor_code given a unique string. If the vendor
307 * code has not been used since launch, a unique integer will be
308 * assigned for that string. Vendor codes will remain the same
309 * until the machine is rebooted.
310 * @param vendor_string A bundle style vendor identifier(i.e. com.apple).
311 * @param vendor_code Upon return, a unique vendor code for use when
312 * posting kernel events.
313 * @result May return ENOMEM if memory constraints prevent allocation of a
314 * new vendor code.
315 */
316errno_t kev_vendor_code_find(const char *vendor_string, u_int32_t *vendor_code);
317
318/*!
319 * @function kev_msg_post
320 * @discussion Post a kernel event message.
321 * @param event_msg A structure defining the kernel event message to post.
322 * @result Will return zero upon success. May return a number of errors
323 * depending on the type of failure. EINVAL indicates that there
324 * was something wrong with the kerne event. The vendor code of
325 * the kernel event must be assigned using kev_vendor_code_find.
326 * If the message is too large, EMSGSIZE will be returned.
327 */
328errno_t kev_msg_post(struct kev_msg *event_msg);
329
330#ifdef PRIVATE
331/*
332 * Internal version of kev_msg_post. Allows posting Apple vendor code kernel
333 * events.
334 */
335int kev_post_msg(struct kev_msg *event);
336int kev_post_msg_nowait(struct kev_msg *event);
337
338LIST_HEAD(kern_event_head, kern_event_pcb);
339
340struct kern_event_pcb {
341 decl_lck_mtx_data(, evp_mtx); /* per-socket mutex */
342 LIST_ENTRY(kern_event_pcb) evp_link; /* glue on list of all PCBs */
343 struct socket *evp_socket; /* pointer back to socket */
344 u_int32_t evp_vendor_code_filter;
345 u_int32_t evp_class_filter;
346 u_int32_t evp_subclass_filter;
347};
348
349#define sotoevpcb(so) ((struct kern_event_pcb *)((so)->so_pcb))
350
351#endif /* PRIVATE */
352#endif /* KERNEL */
353#endif /* SYS_KERN_EVENT_H */
354