1 | /* |
2 | * Copyright (c) 2000-2004, 2012-2016 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 | @header kern_control.h |
30 | This header defines an API to communicate between a kernel |
31 | extension and a process outside of the kernel. |
32 | */ |
33 | |
34 | #ifndef KPI_KERN_CONTROL_H |
35 | #define KPI_KERN_CONTROL_H |
36 | |
37 | |
38 | #include <sys/appleapiopts.h> |
39 | #include <sys/_types/_u_char.h> |
40 | #include <sys/_types/_u_int16_t.h> |
41 | #include <sys/_types/_u_int32_t.h> |
42 | |
43 | /* |
44 | * Define Controller event subclass, and associated events. |
45 | * Subclass of KEV_SYSTEM_CLASS |
46 | */ |
47 | |
48 | /*! |
49 | @defined KEV_CTL_SUBCLASS |
50 | @discussion The kernel event subclass for kernel control events. |
51 | */ |
52 | #define KEV_CTL_SUBCLASS 2 |
53 | |
54 | /*! |
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 | */ |
59 | #define KEV_CTL_REGISTERED 1 /* a new controller appears */ |
60 | |
61 | /*! |
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 | */ |
66 | #define KEV_CTL_DEREGISTERED 2 /* a controller disappears */ |
67 | |
68 | /*! |
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 | */ |
75 | struct ctl_event_data { |
76 | u_int32_t ctl_id; /* Kernel Controller ID */ |
77 | u_int32_t ctl_unit; |
78 | }; |
79 | |
80 | /* |
81 | * Controls destined to the Controller Manager. |
82 | */ |
83 | |
84 | /*! |
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 */ |
90 | |
91 | /*! |
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 */ |
97 | |
98 | |
99 | /*! |
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 |
105 | |
106 | /* |
107 | * Controls destined to the Controller Manager. |
108 | */ |
109 | |
110 | /*! |
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 | */ |
117 | struct ctl_info { |
118 | u_int32_t ctl_id; /* Kernel Controller ID */ |
119 | char ctl_name[MAX_KCTL_NAME]; /* Kernel Controller Name (a C string) */ |
120 | }; |
121 | |
122 | |
123 | /*! |
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 | */ |
140 | struct sockaddr_ctl { |
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]; |
147 | }; |
148 | |
149 | #ifdef PRIVATE |
150 | |
151 | struct xkctl_reg { |
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]; |
170 | }; |
171 | |
172 | struct xkctlpcb { |
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]; |
180 | }; |
181 | |
182 | struct kctlstat { |
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))); |
197 | }; |
198 | |
199 | #endif /* PRIVATE */ |
200 | |
201 | #ifdef KERNEL |
202 | |
203 | #include <sys/kpi_mbuf.h> |
204 | |
205 | /*! |
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 | */ |
213 | typedef void * kern_ctl_ref; |
214 | |
215 | /*! |
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 |
239 | |
240 | #ifdef KERNEL_PRIVATE |
241 | /*! |
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 |
247 | |
248 | /*! |
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 |
254 | #endif /* KERNEL_PRIVATE */ |
255 | |
256 | /* Data flags for controllers */ |
257 | /*! |
258 | @defined CTL_DATA_NOWAKEUP |
259 | @discussion The CTL_DATA_NOWAKEUP flag can be used for the enqueue |
260 | data and enqueue mbuf functions to indicate that the process |
261 | should not be woken up yet. This is useful when you want to |
262 | enqueue data using more than one call but only want to wake up |
263 | the client after all of the data has been enqueued. |
264 | */ |
265 | #define CTL_DATA_NOWAKEUP 0x1 |
266 | |
267 | /*! |
268 | @defined CTL_DATA_EOR |
269 | @discussion The CTL_DATA_EOR flag can be used for the enqueue |
270 | data and enqueue mbuf functions to mark the end of a record. |
271 | */ |
272 | #define CTL_DATA_EOR 0x2 |
273 | |
274 | #ifdef KERNEL_PRIVATE |
275 | /*! |
276 | @defined CTL_DATA_CRIT |
277 | @discussion This flag indicates the data is critical to the client |
278 | and that it needs to be forced into the socket buffer |
279 | by resizing it if needed. |
280 | */ |
281 | #define CTL_DATA_CRIT 0x4 |
282 | #endif /* KERNEL_PRIVATE */ |
283 | |
284 | __BEGIN_DECLS |
285 | |
286 | /*! |
287 | @typedef ctl_connect_func |
288 | @discussion The ctl_connect_func is used to receive |
289 | notification of a client connecting to the kernel control. |
290 | @param kctlref The control ref for the kernel control the client is |
291 | connecting to. |
292 | @param sac The address used to connect to this control. The field sc_unit |
293 | contains the unit number of the kernel control instance the client is |
294 | connecting to. If CTL_FLAG_REG_ID_UNIT was set when the kernel control |
295 | was registered, sc_unit is the ctl_unit of the kern_ctl_reg structure. |
296 | If CTL_FLAG_REG_ID_UNIT was not set when the kernel control was |
297 | registered, sc_unit is the dynamically allocated unit number of |
298 | the new kernel control instance that is used for this connection. |
299 | @param unitinfo A placeholder for a pointer to the optional user-defined |
300 | private data associated with this kernel control instance. This |
301 | opaque info will be provided to the user when the rest of the |
302 | callback routines are executed. For example, it can be used |
303 | to pass a pointer to an instance-specific data structure in |
304 | order for the user to keep track of the states related to this |
305 | kernel control instance. |
306 | */ |
307 | typedef errno_t (*ctl_connect_func)(kern_ctl_ref kctlref, |
308 | struct sockaddr_ctl *sac, |
309 | void **unitinfo); |
310 | |
311 | /*! |
312 | @typedef ctl_disconnect_func |
313 | @discussion The ctl_disconnect_func is used to receive notification |
314 | that a client has disconnected from the kernel control. This |
315 | usually happens when the socket is closed. If this is the last |
316 | socket attached to your kernel control, you may unregister your |
317 | kernel control from this callback. |
318 | @param kctlref The control ref for the kernel control instance the client has |
319 | disconnected from. |
320 | @param unit The unit number of the kernel control instance the client has |
321 | disconnected from. |
322 | @param unitinfo The user-defined private data initialized by the |
323 | ctl_connect_func callback. |
324 | */ |
325 | typedef errno_t (*ctl_disconnect_func)(kern_ctl_ref kctlref, u_int32_t unit, void *unitinfo); |
326 | |
327 | /*! |
328 | @typedef ctl_send_func |
329 | @discussion The ctl_send_func is used to receive data sent from |
330 | the client to the kernel control. |
331 | @param kctlref The control ref of the kernel control. |
332 | @param unit The unit number of the kernel control instance the client has |
333 | connected to. |
334 | @param unitinfo The user-defined private data initialized by the |
335 | ctl_connect_func callback. |
336 | @param m The data sent by the client to the kernel control in an |
337 | mbuf chain. Your function is responsible for releasing the |
338 | mbuf chain. |
339 | @param flags The flags specified by the client when calling |
340 | send/sendto/sendmsg (MSG_OOB/MSG_DONTROUTE). |
341 | */ |
342 | typedef errno_t (*ctl_send_func)(kern_ctl_ref kctlref, u_int32_t unit, void *unitinfo, |
343 | mbuf_t m, int flags); |
344 | |
345 | /*! |
346 | @typedef ctl_setopt_func |
347 | @discussion The ctl_setopt_func is used to handle set socket option |
348 | calls for the SYSPROTO_CONTROL option level. |
349 | @param kctlref The control ref of the kernel control. |
350 | @param unit The unit number of the kernel control instance. |
351 | @param unitinfo The user-defined private data initialized by the |
352 | ctl_connect_func callback. |
353 | @param opt The socket option. |
354 | @param data A pointer to the socket option data. The data has |
355 | already been copied in to the kernel for you. |
356 | @param len The length of the socket option data. |
357 | */ |
358 | typedef errno_t (*ctl_setopt_func)(kern_ctl_ref kctlref, u_int32_t unit, void *unitinfo, |
359 | int opt, void *data, size_t len); |
360 | |
361 | /*! |
362 | @typedef ctl_getopt_func |
363 | @discussion The ctl_getopt_func is used to handle client get socket |
364 | option requests for the SYSPROTO_CONTROL option level. A buffer |
365 | is allocated for storage and passed to your function. The length |
366 | of that buffer is also passed. Upon return, you should set *len |
367 | to length of the buffer used. In some cases, data may be NULL. |
368 | When this happens, *len should be set to the length you would |
369 | have returned had data not been NULL. If the buffer is too small, |
370 | return an error. |
371 | @param kctlref The control ref of the kernel control. |
372 | @param unit The unit number of the kernel control instance. |
373 | @param unitinfo The user-defined private data initialized by the |
374 | ctl_connect_func callback. |
375 | @param opt The socket option. |
376 | @param data A buffer to copy the results in to. May be NULL, see |
377 | discussion. |
378 | @param len A pointer to the length of the buffer. This should be set |
379 | to the length of the buffer used before returning. |
380 | */ |
381 | typedef errno_t (*ctl_getopt_func)(kern_ctl_ref kctlref, u_int32_t unit, void *unitinfo, |
382 | int opt, void *data, size_t *len); |
383 | |
384 | #ifdef KERNEL_PRIVATE |
385 | /*! |
386 | @typedef ctl_rcvd_func |
387 | @discussion The ctl_rcvd_func is called when the client reads data from |
388 | the kernel control socket. The kernel control can use this callback |
389 | in combination with ctl_getenqueuespace() to avoid overflowing |
390 | the socket's receive buffer. When ctl_getenqueuespace() returns |
391 | 0 or ctl_enqueuedata()/ctl_enqueuembuf() return ENOBUFS, the |
392 | kernel control can wait until this callback is called before |
393 | trying to enqueue the data again. |
394 | @param kctlref The control ref of the kernel control. |
395 | @param unit The unit number of the kernel control instance. |
396 | @param unitinfo The user-defined private data initialized by the |
397 | ctl_connect_func callback. |
398 | @param flags The recv flags. See the recv(2) man page. |
399 | */ |
400 | typedef void (*ctl_rcvd_func)(kern_ctl_ref kctlref, u_int32_t unit, void *unitinfo, |
401 | int flags); |
402 | |
403 | /*! |
404 | @typedef ctl_send_list_func |
405 | @discussion The ctl_send_list_func is used to receive data sent from |
406 | the client to the kernel control. |
407 | @param kctlref The control ref of the kernel control. |
408 | @param unit The unit number of the kernel control instance the client has |
409 | connected to. |
410 | @param unitinfo The user-defined private data initialized by the |
411 | ctl_connect_func callback. |
412 | @param m The data sent by the client to the kernel control in an |
413 | mbuf packet chain. Your function is responsible for releasing |
414 | mbuf packet chain. |
415 | @param flags The flags specified by the client when calling |
416 | send/sendto/sendmsg (MSG_OOB/MSG_DONTROUTE). |
417 | */ |
418 | typedef errno_t (*ctl_send_list_func)(kern_ctl_ref kctlref, u_int32_t unit, void *unitinfo, |
419 | mbuf_t m, int flags); |
420 | |
421 | /*! |
422 | @typedef ctl_bind_func |
423 | @discussion The ctl_bind_func is an optional function that allows the client |
424 | to set up their unitinfo prior to connecting. |
425 | @param kctlref The control ref for the kernel control the client is |
426 | binding to. |
427 | @param sac The address used to connect to this control. The field sc_unit |
428 | contains the unit number of the kernel control instance the client is |
429 | binding to. If CTL_FLAG_REG_ID_UNIT was set when the kernel control |
430 | was registered, sc_unit is the ctl_unit of the kern_ctl_reg structure. |
431 | If CTL_FLAG_REG_ID_UNIT was not set when the kernel control was |
432 | registered, sc_unit is the dynamically allocated unit number of |
433 | the new kernel control instance that is used for this connection. |
434 | @param unitinfo A placeholder for a pointer to the optional user-defined |
435 | private data associated with this kernel control instance. This |
436 | opaque info will be provided to the user when the rest of the |
437 | callback routines are executed. For example, it can be used |
438 | to pass a pointer to an instance-specific data structure in |
439 | order for the user to keep track of the states related to this |
440 | kernel control instance. |
441 | */ |
442 | typedef errno_t (*ctl_bind_func)(kern_ctl_ref kctlref, |
443 | struct sockaddr_ctl *sac, |
444 | void **unitinfo); |
445 | #endif /* KERNEL_PRIVATE */ |
446 | |
447 | /*! |
448 | @struct kern_ctl_reg |
449 | @discussion This structure defines the properties of a kernel |
450 | control being registered. |
451 | @field ctl_name A Bundle ID string of up to MAX_KCTL_NAME bytes (including the ending zero). |
452 | This string should not be empty. |
453 | @field ctl_id The control ID may be dynamically assigned or it can be a |
454 | 32-bit creator code assigned by DTS. |
455 | For a DTS assigned creator code the CTL_FLAG_REG_ID_UNIT flag must be set. |
456 | For a dynamically assigned control ID, do not set the CTL_FLAG_REG_ID_UNIT flag. |
457 | The value of the dynamically assigned control ID is set to this field |
458 | when the registration succeeds. |
459 | @field ctl_unit A separate unit number to register multiple units that |
460 | share the same control ID with DTS assigned creator code when |
461 | the CTL_FLAG_REG_ID_UNIT flag is set. |
462 | This field is ignored for a dynamically assigned control ID. |
463 | @field ctl_flags CTL_FLAG_PRIVILEGED and/or CTL_FLAG_REG_ID_UNIT. |
464 | @field ctl_sendsize Override the default send size. If set to zero, |
465 | the default send size will be used, and this default value |
466 | is set to this field to be retrieved by the caller. |
467 | @field ctl_recvsize Override the default receive size. If set to |
468 | zero, the default receive size will be used, and this default value |
469 | is set to this field to be retrieved by the caller. |
470 | @field ctl_connect Specify the function to be called whenever a client |
471 | connects to the kernel control. This field must be specified. |
472 | @field ctl_disconnect Specify a function to be called whenever a |
473 | client disconnects from the kernel control. |
474 | @field ctl_send Specify a function to handle data send from the |
475 | client to the kernel control. |
476 | @field ctl_setopt Specify a function to handle set socket option |
477 | operations for the kernel control. |
478 | @field ctl_getopt Specify a function to handle get socket option |
479 | operations for the kernel control. |
480 | */ |
481 | struct kern_ctl_reg |
482 | { |
483 | /* control information */ |
484 | char ctl_name[MAX_KCTL_NAME]; |
485 | u_int32_t ctl_id; |
486 | u_int32_t ctl_unit; |
487 | |
488 | /* control settings */ |
489 | u_int32_t ctl_flags; |
490 | u_int32_t ctl_sendsize; |
491 | u_int32_t ctl_recvsize; |
492 | |
493 | /* Dispatch functions */ |
494 | ctl_connect_func ctl_connect; |
495 | ctl_disconnect_func ctl_disconnect; |
496 | ctl_send_func ctl_send; |
497 | ctl_setopt_func ctl_setopt; |
498 | ctl_getopt_func ctl_getopt; |
499 | #ifdef KERNEL_PRIVATE |
500 | ctl_rcvd_func ctl_rcvd; /* Only valid if CTL_FLAG_REG_EXTENDED is set */ |
501 | ctl_send_list_func ctl_send_list; /* Only valid if CTL_FLAG_REG_EXTENDED is set */ |
502 | ctl_bind_func ctl_bind; |
503 | #endif /* KERNEL_PRIVATE */ |
504 | }; |
505 | |
506 | /*! |
507 | @function ctl_register |
508 | @discussion Register a kernel control. This will enable clients to |
509 | connect to the kernel control using a PF_SYSTEM socket. |
510 | @param userkctl A structure defining the kernel control to be |
511 | attached. The ctl_connect callback must be specified, the other callbacks |
512 | are optional. If ctl_connect is set to zero, ctl_register fails with |
513 | the error code EINVAL. |
514 | @param kctlref Upon successful return, the kctlref will contain a |
515 | reference to the attached kernel control. This reference is used |
516 | to unregister the kernel control. This reference will also be |
517 | passed in to the callbacks each time they are called. |
518 | @result 0 - Kernel control was registered. |
519 | EINVAL - The registration structure was not valid. |
520 | ENOMEM - There was insufficient memory. |
521 | EEXIST - A controller with that id/unit is already registered. |
522 | */ |
523 | errno_t |
524 | ctl_register(struct kern_ctl_reg *userkctl, kern_ctl_ref *kctlref); |
525 | |
526 | /*! |
527 | @function ctl_deregister |
528 | @discussion Unregister a kernel control. A kernel extension must |
529 | unregister it's kernel control(s) before unloading. If a kernel |
530 | control has clients attached, this call will fail. |
531 | @param kctlref The control reference of the control to unregister. |
532 | @result 0 - Kernel control was unregistered. |
533 | EINVAL - The kernel control reference was invalid. |
534 | EBUSY - The kernel control has clients still attached. |
535 | */ |
536 | errno_t |
537 | ctl_deregister(kern_ctl_ref kctlref); |
538 | |
539 | /*! |
540 | @function ctl_enqueuedata |
541 | @discussion Send data from the kernel control to the client. |
542 | @param kctlref The control reference of the kernel control. |
543 | @param unit The unit number of the kernel control instance. |
544 | @param data A pointer to the data to send. |
545 | @param len The length of data to send. |
546 | @param flags Send flags. CTL_DATA_NOWAKEUP and CTL_DATA_EOR are currently |
547 | the only supported flags. |
548 | @result 0 - Data was enqueued to be read by the client. |
549 | EINVAL - Invalid parameters. |
550 | EMSGSIZE - The buffer is too large. |
551 | ENOBUFS - The queue is full or there are no free mbufs. |
552 | */ |
553 | errno_t |
554 | ctl_enqueuedata(kern_ctl_ref kctlref, u_int32_t unit, void *data, size_t len, u_int32_t flags); |
555 | |
556 | /*! |
557 | @function ctl_enqueuembuf |
558 | @discussion Send data stored in an mbuf chain from the kernel |
559 | control to the client. The caller is responsible for freeing |
560 | the mbuf chain if ctl_enqueuembuf returns an error. |
561 | @param kctlref The control reference of the kernel control. |
562 | @param unit The unit number of the kernel control instance. |
563 | @param m An mbuf chain containing the data to send to the client. |
564 | @param flags Send flags. CTL_DATA_NOWAKEUP and CTL_DATA_EOR are currently |
565 | the only supported flags. |
566 | @result 0 - Data was enqueued to be read by the client. |
567 | EINVAL - Invalid parameters. |
568 | ENOBUFS - The queue is full. |
569 | */ |
570 | errno_t |
571 | ctl_enqueuembuf(kern_ctl_ref kctlref, u_int32_t unit, mbuf_t m, u_int32_t flags); |
572 | |
573 | #ifdef PRIVATE |
574 | /*! |
575 | @function ctl_enqueuembuf_list |
576 | @discussion Send data stored in an mbuf packet chain from the kernel |
577 | control to the client. The caller is responsible for freeing |
578 | the mbuf chain if ctl_enqueuembuf returns an error. |
579 | Not valid if ctl_flags contains CTL_FLAG_REG_SOCK_STREAM. |
580 | @param kctlref The control reference of the kernel control. |
581 | @param unit The unit number of the kernel control instance. |
582 | @param m_list An mbuf chain containing the data to send to the client. |
583 | @param flags Send flags. CTL_DATA_NOWAKEUP is |
584 | the only supported flags. |
585 | @param m_remain A pointer to the list of mbuf packets in the chain that |
586 | could not be enqueued. |
587 | @result 0 - Data was enqueued to be read by the client. |
588 | EINVAL - Invalid parameters. |
589 | ENOBUFS - The queue is full. |
590 | */ |
591 | errno_t |
592 | ctl_enqueuembuf_list(kern_ctl_ref kctlref, u_int32_t unit, mbuf_t m_list, |
593 | u_int32_t flags, mbuf_t *m_remain); |
594 | |
595 | /*! |
596 | @function ctl_getenqueuepacketcount |
597 | @discussion Retrieve the number of packets in the socket |
598 | receive buffer. |
599 | @param kctlref The control reference of the kernel control. |
600 | @param unit The unit number of the kernel control instance. |
601 | @param pcnt The address where to return the current count. |
602 | @result 0 - Success; the packet count is returned to caller. |
603 | EINVAL - Invalid parameters. |
604 | */ |
605 | errno_t |
606 | ctl_getenqueuepacketcount(kern_ctl_ref kctlref, u_int32_t unit, u_int32_t *pcnt); |
607 | |
608 | #endif /* PRIVATE */ |
609 | |
610 | /*! |
611 | @function ctl_getenqueuespace |
612 | @discussion Retrieve the amount of space currently available for data to be sent |
613 | from the kernel control to the client. |
614 | @param kctlref The control reference of the kernel control. |
615 | @param unit The unit number of the kernel control instance. |
616 | @param space The address where to return the current space available |
617 | @result 0 - Success; the amount of space is returned to caller. |
618 | EINVAL - Invalid parameters. |
619 | */ |
620 | errno_t |
621 | ctl_getenqueuespace(kern_ctl_ref kctlref, u_int32_t unit, size_t *space); |
622 | |
623 | /*! |
624 | @function ctl_getenqueuereadable |
625 | @discussion Retrieve the difference between enqueued bytes and |
626 | low-water mark for the socket receive buffer. |
627 | @param kctlref The control reference of the kernel control. |
628 | @param unit The unit number of the kernel control instance. |
629 | @param difference The address at which to return the current difference |
630 | between the low-water mark for the socket and the number of bytes |
631 | enqueued. 0 indicates that the socket is readable by the client |
632 | (the number of bytes in the buffer is above the low-water mark). |
633 | @result 0 - Success; the difference is returned to caller. |
634 | EINVAL - Invalid parameters. |
635 | */ |
636 | errno_t |
637 | ctl_getenqueuereadable(kern_ctl_ref kctlref, u_int32_t unit, u_int32_t *difference); |
638 | |
639 | #ifdef KERNEL_PRIVATE |
640 | |
641 | #include <sys/queue.h> |
642 | #include <libkern/locks.h> |
643 | |
644 | /* |
645 | * internal structure maintained for each register controller |
646 | */ |
647 | struct ctl_cb; |
648 | struct kctl; |
649 | struct socket; |
650 | struct socket_info; |
651 | |
652 | void kctl_fill_socketinfo(struct socket *, struct socket_info *); |
653 | |
654 | u_int32_t ctl_id_by_name(const char *name); |
655 | errno_t ctl_name_by_id(u_int32_t id, char *out_name, size_t maxsize); |
656 | #endif /* KERNEL_PRIVATE */ |
657 | |
658 | __END_DECLS |
659 | #endif /* KERNEL */ |
660 | |
661 | #endif /* KPI_KERN_CONTROL_H */ |
662 | |
663 | |