]>
Commit | Line | Data |
---|---|---|
9bccf70c | 1 | /* |
39037602 | 2 | * Copyright (c) 2000-2004, 2012-2016 Apple Inc. All rights reserved. |
5d5c5d0d | 3 | * |
2d21ac55 | 4 | * @APPLE_OSREFERENCE_LICENSE_HEADER_START@ |
0a7de745 | 5 | * |
2d21ac55 A |
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. | |
0a7de745 | 14 | * |
2d21ac55 A |
15 | * Please obtain a copy of the License at |
16 | * http://www.opensource.apple.com/apsl/ and read it before using this file. | |
0a7de745 | 17 | * |
2d21ac55 A |
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 | |
8f6c56a5 A |
20 | * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES, |
21 | * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY, | |
2d21ac55 A |
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. | |
0a7de745 | 25 | * |
2d21ac55 | 26 | * @APPLE_OSREFERENCE_LICENSE_HEADER_END@ |
9bccf70c | 27 | */ |
91447636 | 28 | /*! |
0a7de745 A |
29 | * @header kern_control.h |
30 | * This header defines an API to communicate between a kernel | |
31 | * extension and a process outside of the kernel. | |
91447636 | 32 | */ |
9bccf70c | 33 | |
91447636 A |
34 | #ifndef KPI_KERN_CONTROL_H |
35 | #define KPI_KERN_CONTROL_H | |
9bccf70c | 36 | |
9bccf70c A |
37 | |
38 | #include <sys/appleapiopts.h> | |
5ba3f43e A |
39 | #include <sys/_types/_u_char.h> |
40 | #include <sys/_types/_u_int16_t.h> | |
41 | #include <sys/_types/_u_int32_t.h> | |
9bccf70c | 42 | |
9bccf70c A |
43 | /* |
44 | * Define Controller event subclass, and associated events. | |
91447636 | 45 | * Subclass of KEV_SYSTEM_CLASS |
9bccf70c A |
46 | */ |
47 | ||
91447636 | 48 | /*! |
0a7de745 A |
49 | * @defined KEV_CTL_SUBCLASS |
50 | * @discussion The kernel event subclass for kernel control events. | |
51 | */ | |
91447636 A |
52 | #define KEV_CTL_SUBCLASS 2 |
53 | ||
54 | /*! | |
0a7de745 A |
55 | * @defined KEV_CTL_REGISTERED |
56 | * @discussion The event code indicating a new controller was | |
57 | * registered. The data portion will contain a ctl_event_data. | |
58 | */ | |
91447636 | 59 | #define KEV_CTL_REGISTERED 1 /* a new controller appears */ |
9bccf70c | 60 | |
91447636 | 61 | /*! |
0a7de745 A |
62 | * @defined KEV_CTL_DEREGISTERED |
63 | * @discussion The event code indicating a controller was unregistered. | |
64 | * The data portion will contain a ctl_event_data. | |
65 | */ | |
91447636 | 66 | #define KEV_CTL_DEREGISTERED 2 /* a controller disappears */ |
9bccf70c | 67 | |
91447636 | 68 | /*! |
0a7de745 A |
69 | * @struct ctl_event_data |
70 | * @discussion This structure is used for KEV_CTL_SUBCLASS kernel | |
71 | * events. | |
72 | * @field ctl_id The kernel control id. | |
73 | * @field ctl_unit The kernel control unit. | |
74 | */ | |
9bccf70c | 75 | struct ctl_event_data { |
0a7de745 A |
76 | u_int32_t ctl_id; /* Kernel Controller ID */ |
77 | u_int32_t ctl_unit; | |
9bccf70c A |
78 | }; |
79 | ||
9bccf70c A |
80 | /* |
81 | * Controls destined to the Controller Manager. | |
82 | */ | |
83 | ||
91447636 | 84 | /*! |
0a7de745 A |
85 | * @defined CTLIOCGCOUNT |
86 | * @discussion The CTLIOCGCOUNT ioctl can be used to determine the | |
87 | * number of kernel controllers registered. | |
88 | */ | |
89 | #define CTLIOCGCOUNT _IOR('N', 2, int) /* get number of control structures registered */ | |
91447636 A |
90 | |
91 | /*! | |
0a7de745 A |
92 | * @defined CTLIOCGINFO |
93 | * @discussion The CTLIOCGINFO ioctl can be used to convert a kernel | |
94 | * control name to a kernel control id. | |
95 | */ | |
96 | #define CTLIOCGINFO _IOWR('N', 3, struct ctl_info) /* get id from name */ | |
91447636 A |
97 | |
98 | ||
99 | /*! | |
0a7de745 A |
100 | * @defined MAX_KCTL_NAME |
101 | * @discussion Kernel control names must be no longer than | |
102 | * MAX_KCTL_NAME. | |
103 | */ | |
104 | #define MAX_KCTL_NAME 96 | |
9bccf70c A |
105 | |
106 | /* | |
91447636 | 107 | * Controls destined to the Controller Manager. |
9bccf70c A |
108 | */ |
109 | ||
91447636 | 110 | /*! |
0a7de745 A |
111 | * @struct ctl_info |
112 | * @discussion This structure is used with the CTLIOCGINFO ioctl to | |
113 | * translate from a kernel control name to a control id. | |
114 | * @field ctl_id The kernel control id, filled out upon return. | |
115 | * @field ctl_name The kernel control name to find. | |
116 | */ | |
91447636 | 117 | struct ctl_info { |
0a7de745 A |
118 | u_int32_t ctl_id; /* Kernel Controller ID */ |
119 | char ctl_name[MAX_KCTL_NAME]; /* Kernel Controller Name (a C string) */ | |
91447636 A |
120 | }; |
121 | ||
122 | ||
123 | /*! | |
0a7de745 A |
124 | * @struct sockaddr_ctl |
125 | * @discussion The controller address structure is used to establish | |
126 | * contact between a user client and a kernel controller. The | |
127 | * sc_id/sc_unit uniquely identify each controller. sc_id is a | |
128 | * unique identifier assigned to the controller. The identifier can | |
129 | * be assigned by the system at registration time or be a 32-bit | |
130 | * creator code obtained from Apple Computer. sc_unit is a unit | |
131 | * number for this sc_id, and is privately used by the kernel | |
132 | * controller to identify several instances of the controller. | |
133 | * @field sc_len The length of the structure. | |
134 | * @field sc_family AF_SYSTEM. | |
135 | * @field ss_sysaddr AF_SYS_KERNCONTROL. | |
136 | * @field sc_id Controller unique identifier. | |
137 | * @field sc_unit Kernel controller private unit number. | |
138 | * @field sc_reserved Reserved, must be set to zero. | |
139 | */ | |
91447636 | 140 | struct sockaddr_ctl { |
0a7de745 A |
141 | u_char sc_len; /* depends on size of bundle ID string */ |
142 | u_char sc_family; /* AF_SYSTEM */ | |
143 | u_int16_t ss_sysaddr; /* AF_SYS_KERNCONTROL */ | |
144 | u_int32_t sc_id; /* Controller unique identifier */ | |
145 | u_int32_t sc_unit; /* Developer private unit number */ | |
146 | u_int32_t sc_reserved[5]; | |
9bccf70c | 147 | }; |
9bccf70c | 148 | |
fe8ab488 A |
149 | #ifdef PRIVATE |
150 | ||
151 | struct xkctl_reg { | |
0a7de745 A |
152 | u_int32_t xkr_len; |
153 | u_int32_t xkr_kind; | |
154 | u_int32_t xkr_id; | |
155 | u_int32_t xkr_reg_unit; | |
156 | u_int32_t xkr_flags; | |
157 | u_int64_t xkr_kctlref; | |
158 | u_int32_t xkr_recvbufsize; | |
159 | u_int32_t xkr_sendbufsize; | |
160 | u_int32_t xkr_lastunit; | |
161 | u_int32_t xkr_pcbcount; | |
162 | u_int64_t xkr_connect; | |
163 | u_int64_t xkr_disconnect; | |
164 | u_int64_t xkr_send; | |
165 | u_int64_t xkr_send_list; | |
166 | u_int64_t xkr_setopt; | |
167 | u_int64_t xkr_getopt; | |
168 | u_int64_t xkr_rcvd; | |
169 | char xkr_name[MAX_KCTL_NAME]; | |
fe8ab488 A |
170 | }; |
171 | ||
172 | struct xkctlpcb { | |
0a7de745 A |
173 | u_int32_t xkp_len; |
174 | u_int32_t xkp_kind; | |
175 | u_int64_t xkp_kctpcb; | |
176 | u_int32_t xkp_unit; | |
177 | u_int32_t xkp_kctlid; | |
178 | u_int64_t xkp_kctlref; | |
179 | char xkp_kctlname[MAX_KCTL_NAME]; | |
fe8ab488 A |
180 | }; |
181 | ||
182 | struct kctlstat { | |
0a7de745 A |
183 | u_int64_t kcs_reg_total __attribute__((aligned(8))); |
184 | u_int64_t kcs_reg_count __attribute__((aligned(8))); | |
185 | u_int64_t kcs_pcbcount __attribute__((aligned(8))); | |
186 | u_int64_t kcs_gencnt __attribute__((aligned(8))); | |
187 | u_int64_t kcs_connections __attribute__((aligned(8))); | |
188 | u_int64_t kcs_conn_fail __attribute__((aligned(8))); | |
189 | u_int64_t kcs_send_fail __attribute__((aligned(8))); | |
190 | u_int64_t kcs_send_list_fail __attribute__((aligned(8))); | |
191 | u_int64_t kcs_enqueue_fail __attribute__((aligned(8))); | |
192 | u_int64_t kcs_enqueue_fullsock __attribute__((aligned(8))); | |
193 | u_int64_t kcs_bad_kctlref __attribute__((aligned(8))); | |
194 | u_int64_t kcs_tbl_size_too_big __attribute__((aligned(8))); | |
195 | u_int64_t kcs_enqdata_mb_alloc_fail __attribute__((aligned(8))); | |
196 | u_int64_t kcs_enqdata_sbappend_fail __attribute__((aligned(8))); | |
fe8ab488 A |
197 | }; |
198 | ||
199 | #endif /* PRIVATE */ | |
200 | ||
9bccf70c | 201 | #ifdef KERNEL |
9bccf70c | 202 | |
91447636 A |
203 | #include <sys/kpi_mbuf.h> |
204 | ||
205 | /*! | |
0a7de745 A |
206 | * @typedef kern_ctl_ref |
207 | * @discussion A control reference is used to track an attached kernel | |
208 | * control. Registering a kernel control will create a kernel | |
209 | * control reference. This reference is required for sending data | |
210 | * or removing the kernel control. This reference will be passed to | |
211 | * callbacks for that kernel control. | |
212 | */ | |
9bccf70c A |
213 | typedef void * kern_ctl_ref; |
214 | ||
91447636 | 215 | /*! |
0a7de745 A |
216 | * @defined CTL_FLAG_PRIVILEGED |
217 | * @discussion The CTL_FLAG_PRIVILEGED flag is passed in ctl_flags. If | |
218 | * this flag is set, only privileged processes may attach to this | |
219 | * kernel control. | |
220 | */ | |
221 | #define CTL_FLAG_PRIVILEGED 0x1 | |
222 | /*! | |
223 | * @defined CTL_FLAG_REG_ID_UNIT | |
224 | * @discussion The CTL_FLAG_REG_ID_UNIT flag is passed to indicate that | |
225 | * the ctl_id specified should be used. If this flag is not | |
226 | * present, a unique ctl_id will be dynamically assigned to your | |
227 | * kernel control. The CTLIOCGINFO ioctl can be used by the client | |
228 | * to find the dynamically assigned id based on the control name | |
229 | * specified in ctl_name. | |
230 | */ | |
231 | #define CTL_FLAG_REG_ID_UNIT 0x2 | |
232 | /*! | |
233 | * @defined CTL_FLAG_REG_SOCK_STREAM | |
234 | * @discussion Use the CTL_FLAG_REG_SOCK_STREAM flag when client need to open | |
235 | * socket of type SOCK_STREAM to communicate with the kernel control. | |
236 | * By default kernel control sockets are of type SOCK_DGRAM. | |
237 | */ | |
238 | #define CTL_FLAG_REG_SOCK_STREAM 0x4 | |
9bccf70c | 239 | |
39236c6e A |
240 | #ifdef KERNEL_PRIVATE |
241 | /*! | |
0a7de745 A |
242 | * @defined CTL_FLAG_REG_EXTENDED |
243 | * @discussion This flag indicates that this kernel control utilizes the | |
244 | * the extended fields within the kern_ctl_reg structure. | |
245 | */ | |
246 | #define CTL_FLAG_REG_EXTENDED 0x8 | |
fe8ab488 A |
247 | |
248 | /*! | |
0a7de745 A |
249 | * @defined CTL_FLAG_REG_CRIT |
250 | * @discussion This flag indicates that this kernel control utilizes the | |
251 | * the extended fields within the kern_ctl_reg structure. | |
252 | */ | |
253 | #define CTL_FLAG_REG_CRIT 0x10 | |
f427ee49 A |
254 | |
255 | /*! | |
256 | * @defined CTL_FLAG_REG_SETUP | |
257 | * @discussion This flag indicates that this kernel control utilizes the | |
258 | * the setup callback field within the kern_ctl_reg structure. | |
259 | */ | |
260 | #define CTL_FLAG_REG_SETUP 0x20 | |
39236c6e A |
261 | #endif /* KERNEL_PRIVATE */ |
262 | ||
9bccf70c | 263 | /* Data flags for controllers */ |
91447636 | 264 | /*! |
0a7de745 A |
265 | * @defined CTL_DATA_NOWAKEUP |
266 | * @discussion The CTL_DATA_NOWAKEUP flag can be used for the enqueue | |
267 | * data and enqueue mbuf functions to indicate that the process | |
268 | * should not be woken up yet. This is useful when you want to | |
269 | * enqueue data using more than one call but only want to wake up | |
270 | * the client after all of the data has been enqueued. | |
271 | */ | |
272 | #define CTL_DATA_NOWAKEUP 0x1 | |
fe8ab488 | 273 | |
91447636 | 274 | /*! |
0a7de745 A |
275 | * @defined CTL_DATA_EOR |
276 | * @discussion The CTL_DATA_EOR flag can be used for the enqueue | |
277 | * data and enqueue mbuf functions to mark the end of a record. | |
278 | */ | |
279 | #define CTL_DATA_EOR 0x2 | |
9bccf70c | 280 | |
fe8ab488 A |
281 | #ifdef KERNEL_PRIVATE |
282 | /*! | |
0a7de745 A |
283 | * @defined CTL_DATA_CRIT |
284 | * @discussion This flag indicates the data is critical to the client | |
285 | * and that it needs to be forced into the socket buffer | |
286 | * by resizing it if needed. | |
287 | */ | |
288 | #define CTL_DATA_CRIT 0x4 | |
fe8ab488 A |
289 | #endif /* KERNEL_PRIVATE */ |
290 | ||
2d21ac55 A |
291 | __BEGIN_DECLS |
292 | ||
91447636 | 293 | /*! |
0a7de745 A |
294 | * @typedef ctl_connect_func |
295 | * @discussion The ctl_connect_func is used to receive | |
296 | * notification of a client connecting to the kernel control. | |
297 | * @param kctlref The control ref for the kernel control the client is | |
298 | * connecting to. | |
299 | * @param sac The address used to connect to this control. The field sc_unit | |
300 | * contains the unit number of the kernel control instance the client is | |
301 | * connecting to. If CTL_FLAG_REG_ID_UNIT was set when the kernel control | |
302 | * was registered, sc_unit is the ctl_unit of the kern_ctl_reg structure. | |
303 | * If CTL_FLAG_REG_ID_UNIT was not set when the kernel control was | |
304 | * registered, sc_unit is the dynamically allocated unit number of | |
305 | * the new kernel control instance that is used for this connection. | |
306 | * @param unitinfo A placeholder for a pointer to the optional user-defined | |
307 | * private data associated with this kernel control instance. This | |
308 | * opaque info will be provided to the user when the rest of the | |
309 | * callback routines are executed. For example, it can be used | |
310 | * to pass a pointer to an instance-specific data structure in | |
311 | * order for the user to keep track of the states related to this | |
312 | * kernel control instance. | |
313 | */ | |
314 | typedef errno_t (*ctl_connect_func)(kern_ctl_ref kctlref, | |
315 | struct sockaddr_ctl *sac, | |
316 | void **unitinfo); | |
317 | ||
318 | /*! | |
319 | * @typedef ctl_disconnect_func | |
320 | * @discussion The ctl_disconnect_func is used to receive notification | |
321 | * that a client has disconnected from the kernel control. This | |
322 | * usually happens when the socket is closed. If this is the last | |
323 | * socket attached to your kernel control, you may unregister your | |
324 | * kernel control from this callback. | |
325 | * @param kctlref The control ref for the kernel control instance the client has | |
326 | * disconnected from. | |
327 | * @param unit The unit number of the kernel control instance the client has | |
328 | * disconnected from. | |
329 | * @param unitinfo The user-defined private data initialized by the | |
330 | * ctl_connect_func callback. | |
9bccf70c | 331 | */ |
91447636 A |
332 | typedef errno_t (*ctl_disconnect_func)(kern_ctl_ref kctlref, u_int32_t unit, void *unitinfo); |
333 | ||
334 | /*! | |
0a7de745 A |
335 | * @typedef ctl_send_func |
336 | * @discussion The ctl_send_func is used to receive data sent from | |
337 | * the client to the kernel control. | |
338 | * @param kctlref The control ref of the kernel control. | |
339 | * @param unit The unit number of the kernel control instance the client has | |
340 | * connected to. | |
341 | * @param unitinfo The user-defined private data initialized by the | |
342 | * ctl_connect_func callback. | |
343 | * @param m The data sent by the client to the kernel control in an | |
344 | * mbuf chain. Your function is responsible for releasing the | |
345 | * mbuf chain. | |
346 | * @param flags The flags specified by the client when calling | |
347 | * send/sendto/sendmsg (MSG_OOB/MSG_DONTROUTE). | |
91447636 A |
348 | */ |
349 | typedef errno_t (*ctl_send_func)(kern_ctl_ref kctlref, u_int32_t unit, void *unitinfo, | |
0a7de745 A |
350 | mbuf_t m, int flags); |
351 | ||
352 | /*! | |
353 | * @typedef ctl_setopt_func | |
354 | * @discussion The ctl_setopt_func is used to handle set socket option | |
355 | * calls for the SYSPROTO_CONTROL option level. | |
356 | * @param kctlref The control ref of the kernel control. | |
357 | * @param unit The unit number of the kernel control instance. | |
358 | * @param unitinfo The user-defined private data initialized by the | |
359 | * ctl_connect_func callback. | |
360 | * @param opt The socket option. | |
361 | * @param data A pointer to the socket option data. The data has | |
362 | * already been copied in to the kernel for you. | |
363 | * @param len The length of the socket option data. | |
91447636 A |
364 | */ |
365 | typedef errno_t (*ctl_setopt_func)(kern_ctl_ref kctlref, u_int32_t unit, void *unitinfo, | |
0a7de745 A |
366 | int opt, void *data, size_t len); |
367 | ||
368 | /*! | |
369 | * @typedef ctl_getopt_func | |
370 | * @discussion The ctl_getopt_func is used to handle client get socket | |
371 | * option requests for the SYSPROTO_CONTROL option level. A buffer | |
372 | * is allocated for storage and passed to your function. The length | |
373 | * of that buffer is also passed. Upon return, you should set *len | |
374 | * to length of the buffer used. In some cases, data may be NULL. | |
375 | * When this happens, *len should be set to the length you would | |
376 | * have returned had data not been NULL. If the buffer is too small, | |
377 | * return an error. | |
378 | * @param kctlref The control ref of the kernel control. | |
379 | * @param unit The unit number of the kernel control instance. | |
380 | * @param unitinfo The user-defined private data initialized by the | |
381 | * ctl_connect_func callback. | |
382 | * @param opt The socket option. | |
383 | * @param data A buffer to copy the results in to. May be NULL, see | |
384 | * discussion. | |
385 | * @param len A pointer to the length of the buffer. This should be set | |
386 | * to the length of the buffer used before returning. | |
91447636 A |
387 | */ |
388 | typedef errno_t (*ctl_getopt_func)(kern_ctl_ref kctlref, u_int32_t unit, void *unitinfo, | |
0a7de745 | 389 | int opt, void *data, size_t *len); |
91447636 | 390 | |
39236c6e A |
391 | #ifdef KERNEL_PRIVATE |
392 | /*! | |
0a7de745 A |
393 | * @typedef ctl_rcvd_func |
394 | * @discussion The ctl_rcvd_func is called when the client reads data from | |
395 | * the kernel control socket. The kernel control can use this callback | |
396 | * in combination with ctl_getenqueuespace() to avoid overflowing | |
397 | * the socket's receive buffer. When ctl_getenqueuespace() returns | |
398 | * 0 or ctl_enqueuedata()/ctl_enqueuembuf() return ENOBUFS, the | |
399 | * kernel control can wait until this callback is called before | |
400 | * trying to enqueue the data again. | |
401 | * @param kctlref The control ref of the kernel control. | |
402 | * @param unit The unit number of the kernel control instance. | |
403 | * @param unitinfo The user-defined private data initialized by the | |
404 | * ctl_connect_func callback. | |
405 | * @param flags The recv flags. See the recv(2) man page. | |
39236c6e A |
406 | */ |
407 | typedef void (*ctl_rcvd_func)(kern_ctl_ref kctlref, u_int32_t unit, void *unitinfo, | |
0a7de745 A |
408 | int flags); |
409 | ||
410 | /*! | |
411 | * @typedef ctl_send_list_func | |
412 | * @discussion The ctl_send_list_func is used to receive data sent from | |
413 | * the client to the kernel control. | |
414 | * @param kctlref The control ref of the kernel control. | |
415 | * @param unit The unit number of the kernel control instance the client has | |
416 | * connected to. | |
417 | * @param unitinfo The user-defined private data initialized by the | |
418 | * ctl_connect_func callback. | |
419 | * @param m The data sent by the client to the kernel control in an | |
420 | * mbuf packet chain. Your function is responsible for releasing | |
421 | * mbuf packet chain. | |
422 | * @param flags The flags specified by the client when calling | |
423 | * send/sendto/sendmsg (MSG_OOB/MSG_DONTROUTE). | |
fe8ab488 A |
424 | */ |
425 | typedef errno_t (*ctl_send_list_func)(kern_ctl_ref kctlref, u_int32_t unit, void *unitinfo, | |
0a7de745 A |
426 | mbuf_t m, int flags); |
427 | ||
428 | /*! | |
429 | * @typedef ctl_bind_func | |
430 | * @discussion The ctl_bind_func is an optional function that allows the client | |
431 | * to set up their unitinfo prior to connecting. | |
432 | * @param kctlref The control ref for the kernel control the client is | |
433 | * binding to. | |
434 | * @param sac The address used to connect to this control. The field sc_unit | |
435 | * contains the unit number of the kernel control instance the client is | |
436 | * binding to. If CTL_FLAG_REG_ID_UNIT was set when the kernel control | |
437 | * was registered, sc_unit is the ctl_unit of the kern_ctl_reg structure. | |
438 | * If CTL_FLAG_REG_ID_UNIT was not set when the kernel control was | |
439 | * registered, sc_unit is the dynamically allocated unit number of | |
440 | * the new kernel control instance that is used for this connection. | |
441 | * @param unitinfo A placeholder for a pointer to the optional user-defined | |
442 | * private data associated with this kernel control instance. This | |
443 | * opaque info will be provided to the user when the rest of the | |
444 | * callback routines are executed. For example, it can be used | |
445 | * to pass a pointer to an instance-specific data structure in | |
446 | * order for the user to keep track of the states related to this | |
447 | * kernel control instance. | |
5c9f4661 A |
448 | */ |
449 | typedef errno_t (*ctl_bind_func)(kern_ctl_ref kctlref, | |
0a7de745 A |
450 | struct sockaddr_ctl *sac, |
451 | void **unitinfo); | |
f427ee49 A |
452 | |
453 | /*! | |
454 | * @typedef ctl_setup_func | |
455 | * @discussion The ctl_setup_func is an optional function that allows the client | |
456 | * to pick a unit number in the case that the caller hasn't specified one | |
457 | * @param unit A placeholder for a pointer to the unit number that is selected with | |
458 | * this kernel control instance | |
459 | * @param unitinfo A placeholder for a pointer to the optional user-defined | |
460 | * private data associated with this kernel control instance. This | |
461 | * opaque info will be provided to the user when the rest of the | |
462 | * callback routines are executed. For example, it can be used | |
463 | * to pass a pointer to an instance-specific data structure in | |
464 | * order for the user to keep track of the states related to this | |
465 | * kernel control instance. | |
466 | */ | |
467 | typedef errno_t (*ctl_setup_func)(u_int32_t *unit, void **unitinfo); | |
39236c6e A |
468 | #endif /* KERNEL_PRIVATE */ |
469 | ||
91447636 | 470 | /*! |
0a7de745 A |
471 | * @struct kern_ctl_reg |
472 | * @discussion This structure defines the properties of a kernel | |
473 | * control being registered. | |
474 | * @field ctl_name A Bundle ID string of up to MAX_KCTL_NAME bytes (including the ending zero). | |
475 | * This string should not be empty. | |
476 | * @field ctl_id The control ID may be dynamically assigned or it can be a | |
477 | * 32-bit creator code assigned by DTS. | |
478 | * For a DTS assigned creator code the CTL_FLAG_REG_ID_UNIT flag must be set. | |
479 | * For a dynamically assigned control ID, do not set the CTL_FLAG_REG_ID_UNIT flag. | |
480 | * The value of the dynamically assigned control ID is set to this field | |
481 | * when the registration succeeds. | |
482 | * @field ctl_unit A separate unit number to register multiple units that | |
483 | * share the same control ID with DTS assigned creator code when | |
484 | * the CTL_FLAG_REG_ID_UNIT flag is set. | |
485 | * This field is ignored for a dynamically assigned control ID. | |
486 | * @field ctl_flags CTL_FLAG_PRIVILEGED and/or CTL_FLAG_REG_ID_UNIT. | |
487 | * @field ctl_sendsize Override the default send size. If set to zero, | |
488 | * the default send size will be used, and this default value | |
489 | * is set to this field to be retrieved by the caller. | |
490 | * @field ctl_recvsize Override the default receive size. If set to | |
491 | * zero, the default receive size will be used, and this default value | |
492 | * is set to this field to be retrieved by the caller. | |
493 | * @field ctl_connect Specify the function to be called whenever a client | |
494 | * connects to the kernel control. This field must be specified. | |
495 | * @field ctl_disconnect Specify a function to be called whenever a | |
496 | * client disconnects from the kernel control. | |
497 | * @field ctl_send Specify a function to handle data send from the | |
498 | * client to the kernel control. | |
499 | * @field ctl_setopt Specify a function to handle set socket option | |
500 | * operations for the kernel control. | |
501 | * @field ctl_getopt Specify a function to handle get socket option | |
502 | * operations for the kernel control. | |
503 | */ | |
504 | struct kern_ctl_reg { | |
91447636 | 505 | /* control information */ |
0a7de745 A |
506 | char ctl_name[MAX_KCTL_NAME]; |
507 | u_int32_t ctl_id; | |
508 | u_int32_t ctl_unit; | |
509 | ||
510 | /* control settings */ | |
511 | u_int32_t ctl_flags; | |
512 | u_int32_t ctl_sendsize; | |
513 | u_int32_t ctl_recvsize; | |
514 | ||
515 | /* Dispatch functions */ | |
516 | ctl_connect_func ctl_connect; | |
517 | ctl_disconnect_func ctl_disconnect; | |
518 | ctl_send_func ctl_send; | |
519 | ctl_setopt_func ctl_setopt; | |
520 | ctl_getopt_func ctl_getopt; | |
39236c6e | 521 | #ifdef KERNEL_PRIVATE |
0a7de745 A |
522 | ctl_rcvd_func ctl_rcvd; /* Only valid if CTL_FLAG_REG_EXTENDED is set */ |
523 | ctl_send_list_func ctl_send_list;/* Only valid if CTL_FLAG_REG_EXTENDED is set */ | |
524 | ctl_bind_func ctl_bind; | |
f427ee49 | 525 | ctl_setup_func ctl_setup; |
39236c6e | 526 | #endif /* KERNEL_PRIVATE */ |
9bccf70c A |
527 | }; |
528 | ||
91447636 | 529 | /*! |
0a7de745 A |
530 | * @function ctl_register |
531 | * @discussion Register a kernel control. This will enable clients to | |
532 | * connect to the kernel control using a PF_SYSTEM socket. | |
533 | * @param userkctl A structure defining the kernel control to be | |
534 | * attached. The ctl_connect callback must be specified, the other callbacks | |
535 | * are optional. If ctl_connect is set to zero, ctl_register fails with | |
536 | * the error code EINVAL. | |
537 | * @param kctlref Upon successful return, the kctlref will contain a | |
538 | * reference to the attached kernel control. This reference is used | |
539 | * to unregister the kernel control. This reference will also be | |
540 | * passed in to the callbacks each time they are called. | |
541 | * @result 0 - Kernel control was registered. | |
542 | * EINVAL - The registration structure was not valid. | |
543 | * ENOMEM - There was insufficient memory. | |
544 | * EEXIST - A controller with that id/unit is already registered. | |
545 | */ | |
546 | errno_t | |
547 | ctl_register(struct kern_ctl_reg *userkctl, kern_ctl_ref *kctlref); | |
548 | ||
549 | /*! | |
550 | * @function ctl_deregister | |
551 | * @discussion Unregister a kernel control. A kernel extension must | |
552 | * unregister it's kernel control(s) before unloading. If a kernel | |
553 | * control has clients attached, this call will fail. | |
554 | * @param kctlref The control reference of the control to unregister. | |
555 | * @result 0 - Kernel control was unregistered. | |
556 | * EINVAL - The kernel control reference was invalid. | |
557 | * EBUSY - The kernel control has clients still attached. | |
558 | */ | |
559 | errno_t | |
560 | ctl_deregister(kern_ctl_ref kctlref); | |
561 | ||
562 | /*! | |
563 | * @function ctl_enqueuedata | |
564 | * @discussion Send data from the kernel control to the client. | |
565 | * @param kctlref The control reference of the kernel control. | |
566 | * @param unit The unit number of the kernel control instance. | |
567 | * @param data A pointer to the data to send. | |
568 | * @param len The length of data to send. | |
569 | * @param flags Send flags. CTL_DATA_NOWAKEUP and CTL_DATA_EOR are currently | |
570 | * the only supported flags. | |
571 | * @result 0 - Data was enqueued to be read by the client. | |
572 | * EINVAL - Invalid parameters. | |
573 | * EMSGSIZE - The buffer is too large. | |
574 | * ENOBUFS - The queue is full or there are no free mbufs. | |
91447636 A |
575 | */ |
576 | errno_t | |
91447636 | 577 | ctl_enqueuedata(kern_ctl_ref kctlref, u_int32_t unit, void *data, size_t len, u_int32_t flags); |
9bccf70c | 578 | |
91447636 | 579 | /*! |
0a7de745 A |
580 | * @function ctl_enqueuembuf |
581 | * @discussion Send data stored in an mbuf chain from the kernel | |
582 | * control to the client. The caller is responsible for freeing | |
583 | * the mbuf chain if ctl_enqueuembuf returns an error. | |
584 | * @param kctlref The control reference of the kernel control. | |
585 | * @param unit The unit number of the kernel control instance. | |
586 | * @param m An mbuf chain containing the data to send to the client. | |
587 | * @param flags Send flags. CTL_DATA_NOWAKEUP and CTL_DATA_EOR are currently | |
588 | * the only supported flags. | |
589 | * @result 0 - Data was enqueued to be read by the client. | |
590 | * EINVAL - Invalid parameters. | |
591 | * ENOBUFS - The queue is full. | |
592 | */ | |
593 | errno_t | |
91447636 | 594 | ctl_enqueuembuf(kern_ctl_ref kctlref, u_int32_t unit, mbuf_t m, u_int32_t flags); |
9bccf70c | 595 | |
fe8ab488 A |
596 | #ifdef PRIVATE |
597 | /*! | |
0a7de745 A |
598 | * @function ctl_enqueuembuf_list |
599 | * @discussion Send data stored in an mbuf packet chain from the kernel | |
600 | * control to the client. The caller is responsible for freeing | |
601 | * the mbuf chain if ctl_enqueuembuf returns an error. | |
602 | * Not valid if ctl_flags contains CTL_FLAG_REG_SOCK_STREAM. | |
603 | * @param kctlref The control reference of the kernel control. | |
604 | * @param unit The unit number of the kernel control instance. | |
605 | * @param m_list An mbuf chain containing the data to send to the client. | |
606 | * @param flags Send flags. CTL_DATA_NOWAKEUP is | |
607 | * the only supported flags. | |
608 | * @param m_remain A pointer to the list of mbuf packets in the chain that | |
609 | * could not be enqueued. | |
610 | * @result 0 - Data was enqueued to be read by the client. | |
611 | * EINVAL - Invalid parameters. | |
612 | * ENOBUFS - The queue is full. | |
613 | */ | |
614 | errno_t | |
fe8ab488 | 615 | ctl_enqueuembuf_list(kern_ctl_ref kctlref, u_int32_t unit, mbuf_t m_list, |
0a7de745 | 616 | u_int32_t flags, mbuf_t *m_remain); |
fe8ab488 | 617 | |
3e170ce0 | 618 | /*! |
0a7de745 A |
619 | * @function ctl_getenqueuepacketcount |
620 | * @discussion Retrieve the number of packets in the socket | |
621 | * receive buffer. | |
622 | * @param kctlref The control reference of the kernel control. | |
623 | * @param unit The unit number of the kernel control instance. | |
624 | * @param pcnt The address where to return the current count. | |
625 | * @result 0 - Success; the packet count is returned to caller. | |
626 | * EINVAL - Invalid parameters. | |
3e170ce0 A |
627 | */ |
628 | errno_t | |
629 | ctl_getenqueuepacketcount(kern_ctl_ref kctlref, u_int32_t unit, u_int32_t *pcnt); | |
fe8ab488 | 630 | |
3e170ce0 | 631 | #endif /* PRIVATE */ |
91447636 A |
632 | |
633 | /*! | |
0a7de745 A |
634 | * @function ctl_getenqueuespace |
635 | * @discussion Retrieve the amount of space currently available for data to be sent | |
636 | * from the kernel control to the client. | |
637 | * @param kctlref The control reference of the kernel control. | |
638 | * @param unit The unit number of the kernel control instance. | |
639 | * @param space The address where to return the current space available | |
640 | * @result 0 - Success; the amount of space is returned to caller. | |
641 | * EINVAL - Invalid parameters. | |
9bccf70c | 642 | */ |
0a7de745 | 643 | errno_t |
91447636 A |
644 | ctl_getenqueuespace(kern_ctl_ref kctlref, u_int32_t unit, size_t *space); |
645 | ||
fe8ab488 | 646 | /*! |
0a7de745 A |
647 | * @function ctl_getenqueuereadable |
648 | * @discussion Retrieve the difference between enqueued bytes and | |
649 | * low-water mark for the socket receive buffer. | |
650 | * @param kctlref The control reference of the kernel control. | |
651 | * @param unit The unit number of the kernel control instance. | |
652 | * @param difference The address at which to return the current difference | |
653 | * between the low-water mark for the socket and the number of bytes | |
654 | * enqueued. 0 indicates that the socket is readable by the client | |
655 | * (the number of bytes in the buffer is above the low-water mark). | |
656 | * @result 0 - Success; the difference is returned to caller. | |
657 | * EINVAL - Invalid parameters. | |
fe8ab488 A |
658 | */ |
659 | errno_t | |
660 | ctl_getenqueuereadable(kern_ctl_ref kctlref, u_int32_t unit, u_int32_t *difference); | |
661 | ||
6d2010ae | 662 | #ifdef KERNEL_PRIVATE |
fe8ab488 A |
663 | |
664 | #include <sys/queue.h> | |
665 | #include <libkern/locks.h> | |
666 | ||
667 | /* | |
668 | * internal structure maintained for each register controller | |
669 | */ | |
670 | struct ctl_cb; | |
3e170ce0 | 671 | struct kctl; |
fe8ab488 | 672 | struct socket; |
3e170ce0 | 673 | struct socket_info; |
fe8ab488 | 674 | |
3e170ce0 | 675 | void kctl_fill_socketinfo(struct socket *, struct socket_info *); |
fe8ab488 | 676 | |
6d2010ae A |
677 | u_int32_t ctl_id_by_name(const char *name); |
678 | errno_t ctl_name_by_id(u_int32_t id, char *out_name, size_t maxsize); | |
f427ee49 A |
679 | |
680 | extern const u_int32_t ctl_maxunit; | |
6d2010ae A |
681 | #endif /* KERNEL_PRIVATE */ |
682 | ||
2d21ac55 | 683 | __END_DECLS |
9bccf70c A |
684 | #endif /* KERNEL */ |
685 | ||
91447636 | 686 | #endif /* KPI_KERN_CONTROL_H */ |