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. 256 @param flags The flags specified by the client when calling 257 send/sendto/sendmsg (MSG_OOB/MSG_DONTROUTE). 258 */ 259typedef errno_t (*ctl_send_func)(kern_ctl_ref kctlref, u_int32_t unit, void *unitinfo, 260 mbuf_t m, int flags); 261 262/*! 263 @typedef ctl_setopt_func 264 @discussion The ctl_setopt_func is used to handle set socket option 265 calls for the SYSPROTO_CONTROL option level. 266 @param kctlref The control ref of the kernel control. 267 @param unit The unit number of the kernel control instance. 268 @param unitinfo The user-defined private data initialized by the 269 ctl_connect_func callback. 270 @param opt The socket option. 271 @param data A pointer to the socket option data. The data has 272 already been copied in to the kernel for you. 273 @param len The length of the socket option data. 274 */ 275typedef errno_t (*ctl_setopt_func)(kern_ctl_ref kctlref, u_int32_t unit, void *unitinfo, 276 int opt, void *data, size_t len); 277 278/*! 279 @typedef ctl_getopt_func 280 @discussion The ctl_getopt_func is used to handle client get socket 281 option requests for the SYSPROTO_CONTROL option level. A buffer 282 is allocated for storage and passed to your function. The length 283 of that buffer is also passed. Upon return, you should set *len 284 to length of the buffer used. In some cases, data may be NULL. 285 When this happens, *len should be set to the length you would 286 have returned had data not been NULL. If the buffer is too small, 287 return an error. 288 @param kctlref The control ref of the kernel control. 289 @param unit The unit number of the kernel control instance. 290 @param unitinfo The user-defined private data initialized by the 291 ctl_connect_func callback. 292 @param opt The socket option. 293 @param data A buffer to copy the results in to. May be NULL, see 294 discussion. 295 @param len A pointer to the length of the buffer. This should be set 296 to the length of the buffer used before returning. 297 */ 298typedef errno_t (*ctl_getopt_func)(kern_ctl_ref kctlref, u_int32_t unit, void *unitinfo, 299 int opt, void *data, size_t *len); 300 301/*! 302 @struct kern_ctl_reg 303 @discussion This structure defines the properties of a kernel 304 control being registered. 305 @field ctl_name A Bundle ID string of up to MAX_KCTL_NAME bytes (including the ending zero). 306 This string should not be empty. 307 @field ctl_id The control ID may be dynamically assigned or it can be a 308 32-bit creator code assigned by DTS. 309 For a DTS assigned creator code the CTL_FLAG_REG_ID_UNIT flag must be set. 310 For a dynamically assigned control ID, do not set the CTL_FLAG_REG_ID_UNIT flag. 311 The value of the dynamically assigned control ID is set to this field 312 when the registration succeeds. 313 @field ctl_unit A separate unit number to register multiple units that 314 share the same control ID with DTS assigned creator code when 315 the CTL_FLAG_REG_ID_UNIT flag is set. 316 This field is ignored for a dynamically assigned control ID. 317 @field ctl_flags CTL_FLAG_PRIVILEGED and/or CTL_FLAG_REG_ID_UNIT. 318 @field ctl_sendsize Override the default send size. If set to zero, 319 the default send size will be used, and this default value 320 is set to this field to be retrieved by the caller. 321 @field ctl_recvsize Override the default receive size. If set to 322 zero, the default receive size will be used, and this default value 323 is set to this field to be retrieved by the caller. 324 @field ctl_connect Specify the function to be called whenever a client 325 connects to the kernel control. This field must be specified. 326 @field ctl_disconnect Specify a function to be called whenever a 327 client disconnects from the kernel control. 328 @field ctl_send Specify a function to handle data send from the 329 client to the kernel control. 330 @field ctl_setopt Specify a function to handle set socket option 331 operations for the kernel control. 332 @field ctl_getopt Specify a function to handle get socket option 333 operations for the kernel control. 334*/ 335struct kern_ctl_reg 336{ 337 /* control information */ 338 char ctl_name[MAX_KCTL_NAME]; 339 u_int32_t ctl_id; 340 u_int32_t ctl_unit; 341 342 /* control settings */ 343 u_int32_t ctl_flags; 344 u_int32_t ctl_sendsize; 345 u_int32_t ctl_recvsize; 346 347 /* Dispatch functions */ 348 ctl_connect_func ctl_connect; 349 ctl_disconnect_func ctl_disconnect; 350 ctl_send_func ctl_send; 351 ctl_setopt_func ctl_setopt; 352 ctl_getopt_func ctl_getopt; 353}; 354 355/*! 356 @function ctl_register 357 @discussion Register a kernel control. This will enable clients to 358 connect to the kernel control using a PF_SYSTEM socket. 359 @param userkctl A structure defining the kernel control to be 360 attached. The ctl_connect callback must be specified, the other callbacks 361 are optional. If ctl_connect is set to zero, ctl_register fails with 362 the error code EINVAL. 363 @param kctlref Upon successful return, the kctlref will contain a 364 reference to the attached kernel control. This reference is used 365 to unregister the kernel control. This reference will also be 366 passed in to the callbacks each time they are called. 367 @result 0 - Kernel control was registered. 368 EINVAL - The registration structure was not valid. 369 ENOMEM - There was insufficient memory. 370 EEXIST - A controller with that id/unit is already registered. 371 */ 372errno_t 373ctl_register(struct kern_ctl_reg *userkctl, kern_ctl_ref *kctlref); 374 375/*! 376 @function ctl_deregister 377 @discussion Unregister a kernel control. A kernel extension must 378 unregister it's kernel control(s) before unloading. If a kernel 379 control has clients attached, this call will fail. 380 @param kctlref The control reference of the control to unregister. 381 @result 0 - Kernel control was unregistered. 382 EINVAL - The kernel control reference was invalid. 383 EBUSY - The kernel control has clients still attached. 384 */ 385errno_t 386ctl_deregister(kern_ctl_ref kctlref); 387 388/*! 389 @function ctl_enqueuedata 390 @discussion Send data from the kernel control to the client. 391 @param kctlref The control reference of the kernel control. 392 @param unit The unit number of the kernel control instance. 393 @param data A pointer to the data to send. 394 @param len The length of data to send. 395 @param flags Send flags. CTL_DATA_NOWAKEUP is currently the only 396 supported flag. 397 @result 0 - Data was enqueued to be read by the client. 398 EINVAL - Invalid parameters. 399 EMSGSIZE - The buffer is too large. 400 ENOBUFS - The queue is full or there are no free mbufs. 401 */ 402errno_t 403ctl_enqueuedata(kern_ctl_ref kctlref, u_int32_t unit, void *data, size_t len, u_int32_t flags); 404 405/*! 406 @function ctl_enqueuembuf 407 @discussion Send data stored in an mbuf chain from the kernel 408 control to the client. The caller is responsible for freeing 409 the mbuf chain if ctl_enqueuembuf returns an error. 410 @param kctlref The control reference of the kernel control. 411 @param unit The unit number of the kernel control instance. 412 @param m An mbuf chain containing the data to send to the client. 413 @param flags Send flags. CTL_DATA_NOWAKEUP is currently the only 414 supported flag. 415 @result 0 - Data was enqueued to be read by the client. 416 EINVAL - Invalid parameters. 417 ENOBUFS - The queue is full. 418 */ 419errno_t 420ctl_enqueuembuf(kern_ctl_ref kctlref, u_int32_t unit, mbuf_t m, u_int32_t flags); 421 422 423/*! 424 @function ctl_getenqueuespace 425 @discussion Retrieve the amount of space currently available for data to be sent 426 from the kernel control to the client. 427 @param kctlref The control reference of the kernel control. 428 @param unit The unit number of the kernel control instance. 429 @param space The address where to return the current space available 430 @result 0 - Success; the amount of space is returned to caller. 431 EINVAL - Invalid parameters. 432 */ 433errno_t 434ctl_getenqueuespace(kern_ctl_ref kctlref, u_int32_t unit, size_t *space); 435 436__END_DECLS 437#endif /* KERNEL */ 438 439#endif /* KPI_KERN_CONTROL_H */ 440 441