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