1 /* 2 * Copyright (c) 2000-2004, 2012-2025 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 #include <sys/_types/_u_int64_t.h> 43 44 /* 45 * Define Controller event subclass, and associated events. 46 * Subclass of KEV_SYSTEM_CLASS 47 */ 48 49 /*! 50 * @defined KEV_CTL_SUBCLASS 51 * @discussion The kernel event subclass for kernel control events. 52 */ 53 #define KEV_CTL_SUBCLASS 2 54 55 /*! 56 * @defined KEV_CTL_REGISTERED 57 * @discussion The event code indicating a new controller was 58 * registered. The data portion will contain a ctl_event_data. 59 */ 60 #define KEV_CTL_REGISTERED 1 /* a new controller appears */ 61 62 /*! 63 * @defined KEV_CTL_DEREGISTERED 64 * @discussion The event code indicating a controller was unregistered. 65 * The data portion will contain a ctl_event_data. 66 */ 67 #define KEV_CTL_DEREGISTERED 2 /* a controller disappears */ 68 69 /*! 70 * @struct ctl_event_data 71 * @discussion This structure is used for KEV_CTL_SUBCLASS kernel 72 * events. 73 * @field ctl_id The kernel control id. 74 * @field ctl_unit The kernel control unit. 75 */ 76 struct ctl_event_data { 77 u_int32_t ctl_id; /* Kernel Controller ID */ 78 u_int32_t ctl_unit; 79 }; 80 81 /* 82 * Controls destined to the Controller Manager. 83 */ 84 85 /*! 86 * @defined CTLIOCGCOUNT 87 * @discussion The CTLIOCGCOUNT ioctl can be used to determine the 88 * number of kernel controllers registered. 89 */ 90 #define CTLIOCGCOUNT _IOR('N', 2, int) /* get number of control structures registered */ 91 92 /*! 93 * @defined CTLIOCGINFO 94 * @discussion The CTLIOCGINFO ioctl can be used to convert a kernel 95 * control name to a kernel control id. 96 */ 97 #define CTLIOCGINFO _IOWR('N', 3, struct ctl_info) /* get id from name */ 98 99 100 /*! 101 * @defined MAX_KCTL_NAME 102 * @discussion Kernel control names must be no longer than 103 * MAX_KCTL_NAME. 104 */ 105 #define MAX_KCTL_NAME 96 106 107 /* 108 * Controls destined to the Controller Manager. 109 */ 110 111 /*! 112 * @struct ctl_info 113 * @discussion This structure is used with the CTLIOCGINFO ioctl to 114 * translate from a kernel control name to a control id. 115 * @field ctl_id The kernel control id, filled out upon return. 116 * @field ctl_name The kernel control name to find. 117 */ 118 struct ctl_info { 119 u_int32_t ctl_id; /* Kernel Controller ID */ 120 char ctl_name[MAX_KCTL_NAME]; /* Kernel Controller Name (a C string) */ 121 }; 122 123 124 /*! 125 * @struct sockaddr_ctl 126 * @discussion The controller address structure is used to establish 127 * contact between a user client and a kernel controller. The 128 * sc_id/sc_unit uniquely identify each controller. sc_id is a 129 * unique identifier assigned to the controller. The identifier can 130 * be assigned by the system at registration time or be a 32-bit 131 * creator code obtained from Apple Computer. sc_unit is a unit 132 * number for this sc_id, and is privately used by the kernel 133 * controller to identify several instances of the controller. 134 * @field sc_len The length of the structure. 135 * @field sc_family AF_SYSTEM. 136 * @field ss_sysaddr AF_SYS_KERNCONTROL. 137 * @field sc_id Controller unique identifier. 138 * @field sc_unit Kernel controller private unit number. 139 * @field sc_reserved Reserved, must be set to zero. 140 */ 141 struct sockaddr_ctl { 142 u_char sc_len; /* depends on size of bundle ID string */ 143 u_char sc_family; /* AF_SYSTEM */ 144 u_int16_t ss_sysaddr; /* AF_SYS_KERNCONTROL */ 145 u_int32_t sc_id; /* Controller unique identifier */ 146 u_int32_t sc_unit; /* Developer private unit number */ 147 u_int32_t sc_reserved[5]; 148 }; 149 150 #ifdef KERNEL 151 152 #include <sys/kpi_mbuf.h> 153 154 /*! 155 * @typedef kern_ctl_ref 156 * @discussion A control reference is used to track an attached kernel 157 * control. Registering a kernel control will create a kernel 158 * control reference. This reference is required for sending data 159 * or removing the kernel control. This reference will be passed to 160 * callbacks for that kernel control. 161 */ 162 typedef void * kern_ctl_ref; 163 164 /*! 165 * @defined CTL_FLAG_PRIVILEGED 166 * @discussion The CTL_FLAG_PRIVILEGED flag is passed in ctl_flags. If 167 * this flag is set, only privileged processes may attach to this 168 * kernel control. 169 */ 170 #define CTL_FLAG_PRIVILEGED 0x1 171 /*! 172 * @defined CTL_FLAG_REG_ID_UNIT 173 * @discussion The CTL_FLAG_REG_ID_UNIT flag is passed to indicate that 174 * the ctl_id specified should be used. If this flag is not 175 * present, a unique ctl_id will be dynamically assigned to your 176 * kernel control. The CTLIOCGINFO ioctl can be used by the client 177 * to find the dynamically assigned id based on the control name 178 * specified in ctl_name. 179 */ 180 #define CTL_FLAG_REG_ID_UNIT 0x2 181 /*! 182 * @defined CTL_FLAG_REG_SOCK_STREAM 183 * @discussion Use the CTL_FLAG_REG_SOCK_STREAM flag when client need to open 184 * socket of type SOCK_STREAM to communicate with the kernel control. 185 * By default kernel control sockets are of type SOCK_DGRAM. 186 */ 187 #define CTL_FLAG_REG_SOCK_STREAM 0x4 188 189 /* Data flags for controllers */ 190 /*! 191 * @defined CTL_DATA_NOWAKEUP 192 * @discussion The CTL_DATA_NOWAKEUP flag can be used for the enqueue 193 * data and enqueue mbuf functions to indicate that the process 194 * should not be woken up yet. This is useful when you want to 195 * enqueue data using more than one call but only want to wake up 196 * the client after all of the data has been enqueued. 197 */ 198 #define CTL_DATA_NOWAKEUP 0x1 199 200 /*! 201 * @defined CTL_DATA_EOR 202 * @discussion The CTL_DATA_EOR flag can be used for the enqueue 203 * data and enqueue mbuf functions to mark the end of a record. 204 */ 205 #define CTL_DATA_EOR 0x2 206 207 __BEGIN_DECLS 208 209 /*! 210 * @typedef ctl_connect_func 211 * @discussion The ctl_connect_func is used to receive 212 * notification of a client connecting to the kernel control. 213 * @param kctlref The control ref for the kernel control the client is 214 * connecting to. 215 * @param sac The address used to connect to this control. The field sc_unit 216 * contains the unit number of the kernel control instance the client is 217 * connecting to. If CTL_FLAG_REG_ID_UNIT was set when the kernel control 218 * was registered, sc_unit is the ctl_unit of the kern_ctl_reg structure. 219 * If CTL_FLAG_REG_ID_UNIT was not set when the kernel control was 220 * registered, sc_unit is the dynamically allocated unit number of 221 * the new kernel control instance that is used for this connection. 222 * @param unitinfo A placeholder for a pointer to the optional user-defined 223 * private data associated with this kernel control instance. This 224 * opaque info will be provided to the user when the rest of the 225 * callback routines are executed. For example, it can be used 226 * to pass a pointer to an instance-specific data structure in 227 * order for the user to keep track of the states related to this 228 * kernel control instance. 229 */ 230 typedef errno_t (*ctl_connect_func)(kern_ctl_ref kctlref, 231 struct sockaddr_ctl *sac, 232 void **unitinfo); 233 234 /*! 235 * @typedef ctl_disconnect_func 236 * @discussion The ctl_disconnect_func is used to receive notification 237 * that a client has disconnected from the kernel control. This 238 * usually happens when the socket is closed. If this is the last 239 * socket attached to your kernel control, you may unregister your 240 * kernel control from this callback. 241 * @param kctlref The control ref for the kernel control instance the client has 242 * disconnected from. 243 * @param unit The unit number of the kernel control instance the client has 244 * disconnected from. 245 * @param unitinfo The user-defined private data initialized by the 246 * ctl_connect_func callback. 247 */ 248 typedef errno_t (*ctl_disconnect_func)(kern_ctl_ref kctlref, u_int32_t unit, void *unitinfo); 249 250 /*! 251 * @typedef ctl_send_func 252 * @discussion The ctl_send_func is used to receive data sent from 253 * the client to the kernel control. 254 * @param kctlref The control ref of the kernel control. 255 * @param unit The unit number of the kernel control instance the client has 256 * connected to. 257 * @param unitinfo The user-defined private data initialized by the 258 * ctl_connect_func callback. 259 * @param m The data sent by the client to the kernel control in an 260 * mbuf chain. Your function is responsible for releasing the 261 * mbuf chain. 262 * @param flags The flags specified by the client when calling 263 * send/sendto/sendmsg (MSG_OOB/MSG_DONTROUTE). 264 */ 265 typedef errno_t (*ctl_send_func)(kern_ctl_ref kctlref, u_int32_t unit, void *unitinfo, 266 mbuf_t m, int flags); 267 268 /*! 269 * @typedef ctl_setopt_func 270 * @discussion The ctl_setopt_func is used to handle set socket option 271 * calls for the SYSPROTO_CONTROL option level. 272 * @param kctlref The control ref of the kernel control. 273 * @param unit The unit number of the kernel control instance. 274 * @param unitinfo The user-defined private data initialized by the 275 * ctl_connect_func callback. 276 * @param opt The socket option. 277 * @param data A pointer to the socket option data. The data has 278 * already been copied in to the kernel for you. 279 * @param len The length of the socket option data. 280 */ 281 typedef errno_t (*ctl_setopt_func)(kern_ctl_ref kctlref, u_int32_t unit, void *unitinfo, 282 int opt, void *data, size_t len); 283 284 /*! 285 * @typedef ctl_getopt_func 286 * @discussion The ctl_getopt_func is used to handle client get socket 287 * option requests for the SYSPROTO_CONTROL option level. A buffer 288 * is allocated for storage and passed to your function. The length 289 * of that buffer is also passed. Upon return, you should set *len 290 * to length of the buffer used. In some cases, data may be NULL. 291 * When this happens, *len should be set to the length you would 292 * have returned had data not been NULL. If the buffer is too small, 293 * return an error. 294 * @param kctlref The control ref of the kernel control. 295 * @param unit The unit number of the kernel control instance. 296 * @param unitinfo The user-defined private data initialized by the 297 * ctl_connect_func callback. 298 * @param opt The socket option. 299 * @param data A buffer to copy the results in to. May be NULL, see 300 * discussion. 301 * @param len A pointer to the length of the buffer. This should be set 302 * to the length of the buffer used before returning. 303 */ 304 typedef errno_t (*ctl_getopt_func)(kern_ctl_ref kctlref, u_int32_t unit, void *unitinfo, 305 int opt, void *data, size_t *len); 306 307 #ifdef KERNEL_PRIVATE 308 /* 309 * KERN_CTL_REG_OPAQUE means that kern_ctl_reg is an opaque structure 310 * in the public header, and redeclared in kern_control_private.h. 311 */ 312 #define KERN_CTL_REG_OPAQUE 313 #endif /* KERNEL_PRIVATE */ 314 #ifdef KERN_CTL_REG_OPAQUE 315 /*! 316 * @struct kern_ctl_reg 317 * @discussion This structure defines the properties of a kernel 318 * control being registered. 319 */ 320 struct kern_ctl_reg; 321 #else 322 /*! 323 * @struct kern_ctl_reg 324 * @discussion This structure defines the properties of a kernel 325 * control being registered. 326 * @field ctl_name A Bundle ID string of up to MAX_KCTL_NAME bytes (including the ending zero). 327 * This string should not be empty. 328 * @field ctl_id The control ID may be dynamically assigned or it can be a 329 * 32-bit creator code assigned by DTS. 330 * For a DTS assigned creator code the CTL_FLAG_REG_ID_UNIT flag must be set. 331 * For a dynamically assigned control ID, do not set the CTL_FLAG_REG_ID_UNIT flag. 332 * The value of the dynamically assigned control ID is set to this field 333 * when the registration succeeds. 334 * @field ctl_unit A separate unit number to register multiple units that 335 * share the same control ID with DTS assigned creator code when 336 * the CTL_FLAG_REG_ID_UNIT flag is set. 337 * This field is ignored for a dynamically assigned control ID. 338 * @field ctl_flags CTL_FLAG_PRIVILEGED and/or CTL_FLAG_REG_ID_UNIT. 339 * @field ctl_sendsize Override the default send size. If set to zero, 340 * the default send size will be used, and this default value 341 * is set to this field to be retrieved by the caller. 342 * @field ctl_recvsize Override the default receive size. If set to 343 * zero, the default receive size will be used, and this default value 344 * is set to this field to be retrieved by the caller. 345 * @field ctl_connect Specify the function to be called whenever a client 346 * connects to the kernel control. This field must be specified. 347 * @field ctl_disconnect Specify a function to be called whenever a 348 * client disconnects from the kernel control. 349 * @field ctl_send Specify a function to handle data send from the 350 * client to the kernel control. 351 * @field ctl_setopt Specify a function to handle set socket option 352 * operations for the kernel control. 353 * @field ctl_getopt Specify a function to handle get socket option 354 * operations for the kernel control. 355 */ 356 struct kern_ctl_reg { 357 /* control information */ 358 char ctl_name[MAX_KCTL_NAME]; 359 u_int32_t ctl_id; 360 u_int32_t ctl_unit; 361 362 /* control settings */ 363 u_int32_t ctl_flags; 364 u_int32_t ctl_sendsize; 365 u_int32_t ctl_recvsize; 366 367 /* Dispatch functions */ 368 ctl_connect_func ctl_connect; 369 ctl_disconnect_func ctl_disconnect; 370 ctl_send_func ctl_send; 371 ctl_setopt_func ctl_setopt; 372 ctl_getopt_func ctl_getopt; 373 }; 374 #endif /* KERN_CTL_REG_OPAQUE */ 375 376 /*! 377 * @function ctl_register 378 * @discussion Register a kernel control. This will enable clients to 379 * connect to the kernel control using a PF_SYSTEM socket. 380 * @param userkctl A structure defining the kernel control to be 381 * attached. The ctl_connect callback must be specified, the other callbacks 382 * are optional. If ctl_connect is set to zero, ctl_register fails with 383 * the error code EINVAL. 384 * @param kctlref Upon successful return, the kctlref will contain a 385 * reference to the attached kernel control. This reference is used 386 * to unregister the kernel control. This reference will also be 387 * passed in to the callbacks each time they are called. 388 * @result 0 - Kernel control was registered. 389 * EINVAL - The registration structure was not valid. 390 * ENOMEM - There was insufficient memory. 391 * EEXIST - A controller with that id/unit is already registered. 392 */ 393 errno_t 394 ctl_register(struct kern_ctl_reg *userkctl, kern_ctl_ref *kctlref); 395 396 /*! 397 * @function ctl_deregister 398 * @discussion Unregister a kernel control. A kernel extension must 399 * unregister it's kernel control(s) before unloading. If a kernel 400 * control has clients attached, this call will fail. 401 * @param kctlref The control reference of the control to unregister. 402 * @result 0 - Kernel control was unregistered. 403 * EINVAL - The kernel control reference was invalid. 404 * EBUSY - The kernel control has clients still attached. 405 */ 406 errno_t 407 ctl_deregister(kern_ctl_ref kctlref); 408 409 /*! 410 * @function ctl_enqueuedata 411 * @discussion Send data from the kernel control to the client. 412 * @param kctlref The control reference of the kernel control. 413 * @param unit The unit number of the kernel control instance. 414 * @param data A pointer to the data to send. 415 * @param len The length of data to send. 416 * @param flags Send flags. CTL_DATA_NOWAKEUP and CTL_DATA_EOR are currently 417 * the only supported flags. 418 * @result 0 - Data was enqueued to be read by the client. 419 * EINVAL - Invalid parameters. 420 * EMSGSIZE - The buffer is too large. 421 * ENOBUFS - The queue is full or there are no free mbufs. 422 */ 423 errno_t 424 ctl_enqueuedata(kern_ctl_ref kctlref, u_int32_t unit, void *__sized_by(len) data, 425 size_t len, u_int32_t flags); 426 427 /*! 428 * @function ctl_enqueuembuf 429 * @discussion Send data stored in an mbuf chain from the kernel 430 * control to the client. The caller is responsible for freeing 431 * the mbuf chain if ctl_enqueuembuf returns an error. 432 * @param kctlref The control reference of the kernel control. 433 * @param unit The unit number of the kernel control instance. 434 * @param m An mbuf chain containing the data to send to the client. 435 * @param flags Send flags. CTL_DATA_NOWAKEUP and CTL_DATA_EOR are currently 436 * the only supported flags. 437 * @result 0 - Data was enqueued to be read by the client. 438 * EINVAL - Invalid parameters. 439 * ENOBUFS - The queue is full. 440 */ 441 errno_t 442 ctl_enqueuembuf(kern_ctl_ref kctlref, u_int32_t unit, mbuf_t m, u_int32_t flags); 443 444 /*! 445 * @function ctl_getenqueuespace 446 * @discussion Retrieve the amount of space currently available for data to be sent 447 * from the kernel control to the client. 448 * @param kctlref The control reference of the kernel control. 449 * @param unit The unit number of the kernel control instance. 450 * @param space The address where to return the current space available 451 * @result 0 - Success; the amount of space is returned to caller. 452 * EINVAL - Invalid parameters. 453 */ 454 errno_t 455 ctl_getenqueuespace(kern_ctl_ref kctlref, u_int32_t unit, size_t *space); 456 457 /*! 458 * @function ctl_getenqueuereadable 459 * @discussion Retrieve the difference between enqueued bytes and 460 * low-water mark for the socket receive buffer. 461 * @param kctlref The control reference of the kernel control. 462 * @param unit The unit number of the kernel control instance. 463 * @param difference The address at which to return the current difference 464 * between the low-water mark for the socket and the number of bytes 465 * enqueued. 0 indicates that the socket is readable by the client 466 * (the number of bytes in the buffer is above the low-water mark). 467 * @result 0 - Success; the difference is returned to caller. 468 * EINVAL - Invalid parameters. 469 */ 470 errno_t 471 ctl_getenqueuereadable(kern_ctl_ref kctlref, u_int32_t unit, u_int32_t *difference); 472 473 __END_DECLS 474 #endif /* KERNEL */ 475 476 #if defined(PRIVATE) && !defined(MODULES_SUPPORTED) 477 #include <sys/kern_control_private.h> 478 #endif /* PRIVATE && !MODULES_SUPPORTED */ 479 480 #endif /* KPI_KERN_CONTROL_H */ 481