]> git.saurik.com Git - apple/xnu.git/blame - bsd/sys/kern_control.h
xnu-7195.101.1.tar.gz
[apple/xnu.git] / bsd / sys / kern_control.h
CommitLineData
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 75struct 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 117struct 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 140struct 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
151struct 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
172struct 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
182struct 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
213typedef 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 */
314typedef 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
332typedef 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 */
349typedef 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 */
365typedef 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 */
388typedef 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 */
407typedef 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 */
425typedef 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 */
449typedef 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 */
467typedef 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 */
504struct 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 */
546errno_t
547ctl_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 */
559errno_t
560ctl_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 */
576errno_t
91447636 577ctl_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 */
593errno_t
91447636 594ctl_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 */
614errno_t
fe8ab488 615ctl_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 */
628errno_t
629ctl_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 643errno_t
91447636
A
644ctl_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 */
659errno_t
660ctl_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 */
670struct ctl_cb;
3e170ce0 671struct kctl;
fe8ab488 672struct socket;
3e170ce0 673struct socket_info;
fe8ab488 674
3e170ce0 675void kctl_fill_socketinfo(struct socket *, struct socket_info *);
fe8ab488 676
6d2010ae
A
677u_int32_t ctl_id_by_name(const char *name);
678errno_t ctl_name_by_id(u_int32_t id, char *out_name, size_t maxsize);
f427ee49
A
679
680extern 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 */