1/* 2 * Copyright (c) 2000-2004 Apple Computer, 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/* Data flags for controllers */ 186/*! 187 @defined CTL_DATA_NOWAKEUP 188 @discussion The CTL_DATA_NOWAKEUP flag can be used for the enqueue 189 data and enqueue mbuf functions to indicate that the process 190 should not be woken up yet. This is useful when you want to 191 enqueue data using more than one call but only want to wake up 192 the client after all of the data has been enqueued. 193*/ 194#define CTL_DATA_NOWAKEUP 0x1 195/*! 196 @defined CTL_DATA_EOR 197 @discussion The CTL_DATA_EOR flag can be used for the enqueue 198 data and enqueue mbuf functions to mark the end of a record. 199*/ 200#define CTL_DATA_EOR 0x2 201 202__BEGIN_DECLS 203 204/*! 205 @typedef ctl_connect_func 206 @discussion The ctl_connect_func is used to receive 207 notification of a client connecting to the kernel control. 208 @param kctlref The control ref for the kernel control the client is 209 connecting to. 210 @param sac The address used to connect to this control. The field sc_unit 211 contains the unit number of the kernel control instance the client is 212 connecting to. If CTL_FLAG_REG_ID_UNIT was set when the kernel control 213 was registered, sc_unit is the ctl_unit of the kern_ctl_reg structure. 214 If CTL_FLAG_REG_ID_UNIT was not set when the kernel control was 215 registered, sc_unit is the dynamically allocated unit number of 216 the new kernel control instance that is used for this connection. 217 @param unitinfo A placeholder for a pointer to the optional user-defined 218 private data associated with this kernel control instance. This 219 opaque info will be provided to the user when the rest of the 220 callback routines are executed. For example, it can be used 221 to pass a pointer to an instance-specific data structure in 222 order for the user to keep track of the states related to this 223 kernel control instance. 224 */ 225typedef errno_t (*ctl_connect_func)(kern_ctl_ref kctlref, 226 struct sockaddr_ctl *sac, 227 void **unitinfo); 228 229/*! 230 @typedef ctl_disconnect_func 231 @discussion The ctl_disconnect_func is used to receive notification 232 that a client has disconnected from the kernel control. This 233 usually happens when the socket is closed. If this is the last 234 socket attached to your kernel control, you may unregister your 235 kernel control from this callback. 236 @param kctlref The control ref for the kernel control instance the client has 237 disconnected from. 238 @param unit The unit number of the kernel control instance the client has 239 disconnected from. 240 @param unitinfo The user-defined private data initialized by the 241 ctl_connect_func callback. 242 */ 243typedef errno_t (*ctl_disconnect_func)(kern_ctl_ref kctlref, u_int32_t unit, void *unitinfo); 244 245/*! 246 @typedef ctl_send_func 247 @discussion The ctl_send_func is used to receive data sent from 248 the client to the kernel control. 249 @param kctlref The control ref of the kernel control. 250 @param unit The unit number of the kernel control instance the client has 251 connected to. 252 @param unitinfo The user-defined private data initialized by the 253 ctl_connect_func callback. 254 @param m The data sent by the client to the kernel control in an 255 mbuf chain. Your function is responsible for releasing the 256 mbuf chain. 257 @param flags The flags specified by the client when calling 258 send/sendto/sendmsg (MSG_OOB/MSG_DONTROUTE). 259 */ 260typedef errno_t (*ctl_send_func)(kern_ctl_ref kctlref, u_int32_t unit, void *unitinfo, 261 mbuf_t m, int flags); 262 263/*! 264 @typedef ctl_setopt_func 265 @discussion The ctl_setopt_func is used to handle set socket option 266 calls for the SYSPROTO_CONTROL option level. 267 @param kctlref The control ref of the kernel control. 268 @param unit The unit number of the kernel control instance. 269 @param unitinfo The user-defined private data initialized by the 270 ctl_connect_func callback. 271 @param opt The socket option. 272 @param data A pointer to the socket option data. The data has 273 already been copied in to the kernel for you. 274 @param len The length of the socket option data. 275 */ 276typedef errno_t (*ctl_setopt_func)(kern_ctl_ref kctlref, u_int32_t unit, void *unitinfo, 277 int opt, void *data, size_t len); 278 279/*! 280 @typedef ctl_getopt_func 281 @discussion The ctl_getopt_func is used to handle client get socket 282 option requests for the SYSPROTO_CONTROL option level. A buffer 283 is allocated for storage and passed to your function. The length 284 of that buffer is also passed. Upon return, you should set *len 285 to length of the buffer used. In some cases, data may be NULL. 286 When this happens, *len should be set to the length you would 287 have returned had data not been NULL. If the buffer is too small, 288 return an error. 289 @param kctlref The control ref of the kernel control. 290 @param unit The unit number of the kernel control instance. 291 @param unitinfo The user-defined private data initialized by the 292 ctl_connect_func callback. 293 @param opt The socket option. 294 @param data A buffer to copy the results in to. May be NULL, see 295 discussion. 296 @param len A pointer to the length of the buffer. This should be set 297 to the length of the buffer used before returning. 298 */ 299typedef errno_t (*ctl_getopt_func)(kern_ctl_ref kctlref, u_int32_t unit, void *unitinfo, 300 int opt, void *data, size_t *len); 301 302/*! 303 @struct kern_ctl_reg 304 @discussion This structure defines the properties of a kernel 305 control being registered. 306 @field ctl_name A Bundle ID string of up to MAX_KCTL_NAME bytes (including the ending zero). 307 This string should not be empty. 308 @field ctl_id The control ID may be dynamically assigned or it can be a 309 32-bit creator code assigned by DTS. 310 For a DTS assigned creator code the CTL_FLAG_REG_ID_UNIT flag must be set. 311 For a dynamically assigned control ID, do not set the CTL_FLAG_REG_ID_UNIT flag. 312 The value of the dynamically assigned control ID is set to this field 313 when the registration succeeds. 314 @field ctl_unit A separate unit number to register multiple units that 315 share the same control ID with DTS assigned creator code when 316 the CTL_FLAG_REG_ID_UNIT flag is set. 317 This field is ignored for a dynamically assigned control ID. 318 @field ctl_flags CTL_FLAG_PRIVILEGED and/or CTL_FLAG_REG_ID_UNIT. 319 @field ctl_sendsize Override the default send size. If set to zero, 320 the default send size will be used, and this default value 321 is set to this field to be retrieved by the caller. 322 @field ctl_recvsize Override the default receive size. If set to 323 zero, the default receive size will be used, and this default value 324 is set to this field to be retrieved by the caller. 325 @field ctl_connect Specify the function to be called whenever a client 326 connects to the kernel control. This field must be specified. 327 @field ctl_disconnect Specify a function to be called whenever a 328 client disconnects from the kernel control. 329 @field ctl_send Specify a function to handle data send from the 330 client to the kernel control. 331 @field ctl_setopt Specify a function to handle set socket option 332 operations for the kernel control. 333 @field ctl_getopt Specify a function to handle get socket option 334 operations for the kernel control. 335*/ 336struct kern_ctl_reg 337{ 338 /* control information */ 339 char ctl_name[MAX_KCTL_NAME]; 340 u_int32_t ctl_id; 341 u_int32_t ctl_unit; 342 343 /* control settings */ 344 u_int32_t ctl_flags; 345 u_int32_t ctl_sendsize; 346 u_int32_t ctl_recvsize; 347 348 /* Dispatch functions */ 349 ctl_connect_func ctl_connect; 350 ctl_disconnect_func ctl_disconnect; 351 ctl_send_func ctl_send; 352 ctl_setopt_func ctl_setopt; 353 ctl_getopt_func ctl_getopt; 354}; 355 356/*! 357 @function ctl_register 358 @discussion Register a kernel control. This will enable clients to 359 connect to the kernel control using a PF_SYSTEM socket. 360 @param userkctl A structure defining the kernel control to be 361 attached. The ctl_connect callback must be specified, the other callbacks 362 are optional. If ctl_connect is set to zero, ctl_register fails with 363 the error code EINVAL. 364 @param kctlref Upon successful return, the kctlref will contain a 365 reference to the attached kernel control. This reference is used 366 to unregister the kernel control. This reference will also be 367 passed in to the callbacks each time they are called. 368 @result 0 - Kernel control was registered. 369 EINVAL - The registration structure was not valid. 370 ENOMEM - There was insufficient memory. 371 EEXIST - A controller with that id/unit is already registered. 372 */ 373errno_t 374ctl_register(struct kern_ctl_reg *userkctl, kern_ctl_ref *kctlref); 375 376/*! 377 @function ctl_deregister 378 @discussion Unregister a kernel control. A kernel extension must 379 unregister it's kernel control(s) before unloading. If a kernel 380 control has clients attached, this call will fail. 381 @param kctlref The control reference of the control to unregister. 382 @result 0 - Kernel control was unregistered. 383 EINVAL - The kernel control reference was invalid. 384 EBUSY - The kernel control has clients still attached. 385 */ 386errno_t 387ctl_deregister(kern_ctl_ref kctlref); 388 389/*! 390 @function ctl_enqueuedata 391 @discussion Send data from the kernel control to the client. 392 @param kctlref The control reference of the kernel control. 393 @param unit The unit number of the kernel control instance. 394 @param data A pointer to the data to send. 395 @param len The length of data to send. 396 @param flags Send flags. CTL_DATA_NOWAKEUP is currently the only 397 supported flag. 398 @result 0 - Data was enqueued to be read by the client. 399 EINVAL - Invalid parameters. 400 EMSGSIZE - The buffer is too large. 401 ENOBUFS - The queue is full or there are no free mbufs. 402 */ 403errno_t 404ctl_enqueuedata(kern_ctl_ref kctlref, u_int32_t unit, void *data, size_t len, u_int32_t flags); 405 406/*! 407 @function ctl_enqueuembuf 408 @discussion Send data stored in an mbuf chain from the kernel 409 control to the client. The caller is responsible for freeing 410 the mbuf chain if ctl_enqueuembuf returns an error. 411 @param kctlref The control reference of the kernel control. 412 @param unit The unit number of the kernel control instance. 413 @param m An mbuf chain containing the data to send to the client. 414 @param flags Send flags. CTL_DATA_NOWAKEUP is currently the only 415 supported flag. 416 @result 0 - Data was enqueued to be read by the client. 417 EINVAL - Invalid parameters. 418 ENOBUFS - The queue is full. 419 */ 420errno_t 421ctl_enqueuembuf(kern_ctl_ref kctlref, u_int32_t unit, mbuf_t m, u_int32_t flags); 422 423 424/*! 425 @function ctl_getenqueuespace 426 @discussion Retrieve the amount of space currently available for data to be sent 427 from the kernel control to the client. 428 @param kctlref The control reference of the kernel control. 429 @param unit The unit number of the kernel control instance. 430 @param space The address where to return the current space available 431 @result 0 - Success; the amount of space is returned to caller. 432 EINVAL - Invalid parameters. 433 */ 434errno_t 435ctl_getenqueuespace(kern_ctl_ref kctlref, u_int32_t unit, size_t *space); 436 437#ifdef KERNEL_PRIVATE 438u_int32_t ctl_id_by_name(const char *name); 439errno_t ctl_name_by_id(u_int32_t id, char *out_name, size_t maxsize); 440#endif /* KERNEL_PRIVATE */ 441 442__END_DECLS 443#endif /* KERNEL */ 444 445#endif /* KPI_KERN_CONTROL_H */ 446 447