1 /* 2 * Copyright (c) 2000-2004, 2012-2016 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 43 /* 44 * Define Controller event subclass, and associated events. 45 * Subclass of KEV_SYSTEM_CLASS 46 */ 47 48 /*! 49 * @defined KEV_CTL_SUBCLASS 50 * @discussion The kernel event subclass for kernel control events. 51 */ 52 #define KEV_CTL_SUBCLASS 2 53 54 /*! 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 */ 59 #define KEV_CTL_REGISTERED 1 /* a new controller appears */ 60 61 /*! 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 */ 66 #define KEV_CTL_DEREGISTERED 2 /* a controller disappears */ 67 68 /*! 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 */ 75 struct ctl_event_data { 76 u_int32_t ctl_id; /* Kernel Controller ID */ 77 u_int32_t ctl_unit; 78 }; 79 80 /* 81 * Controls destined to the Controller Manager. 82 */ 83 84 /*! 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 */ 90 91 /*! 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 */ 97 98 99 /*! 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 105 106 /* 107 * Controls destined to the Controller Manager. 108 */ 109 110 /*! 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 */ 117 struct ctl_info { 118 u_int32_t ctl_id; /* Kernel Controller ID */ 119 char ctl_name[MAX_KCTL_NAME]; /* Kernel Controller Name (a C string) */ 120 }; 121 122 123 /*! 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 */ 140 struct sockaddr_ctl { 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]; 147 }; 148 149 #ifdef PRIVATE 150 151 struct xkctl_reg { 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]; 170 }; 171 172 struct xkctlpcb { 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]; 180 }; 181 182 struct kctlstat { 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))); 197 }; 198 199 #endif /* PRIVATE */ 200 201 #ifdef KERNEL 202 203 #include <sys/kpi_mbuf.h> 204 205 /*! 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 */ 213 typedef void * kern_ctl_ref; 214 215 /*! 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 239 240 #ifdef KERNEL_PRIVATE 241 /*! 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 247 248 /*! 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 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 261 #endif /* KERNEL_PRIVATE */ 262 263 /* Data flags for controllers */ 264 /*! 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 273 274 /*! 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 280 281 #ifdef KERNEL_PRIVATE 282 /*! 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 289 #endif /* KERNEL_PRIVATE */ 290 291 __BEGIN_DECLS 292 293 /*! 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 */ 314 typedef 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. 331 */ 332 typedef errno_t (*ctl_disconnect_func)(kern_ctl_ref kctlref, u_int32_t unit, void *unitinfo); 333 334 /*! 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). 348 */ 349 typedef errno_t (*ctl_send_func)(kern_ctl_ref kctlref, u_int32_t unit, void *unitinfo, 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. 364 */ 365 typedef errno_t (*ctl_setopt_func)(kern_ctl_ref kctlref, u_int32_t unit, void *unitinfo, 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. 387 */ 388 typedef errno_t (*ctl_getopt_func)(kern_ctl_ref kctlref, u_int32_t unit, void *unitinfo, 389 int opt, void *data, size_t *len); 390 391 #ifdef KERNEL_PRIVATE 392 /*! 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. 406 */ 407 typedef void (*ctl_rcvd_func)(kern_ctl_ref kctlref, u_int32_t unit, void *unitinfo, 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). 424 */ 425 typedef errno_t (*ctl_send_list_func)(kern_ctl_ref kctlref, u_int32_t unit, void *unitinfo, 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. 448 */ 449 typedef errno_t (*ctl_bind_func)(kern_ctl_ref kctlref, 450 struct sockaddr_ctl *sac, 451 void **unitinfo); 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 */ 467 typedef errno_t (*ctl_setup_func)(u_int32_t *unit, void **unitinfo); 468 #endif /* KERNEL_PRIVATE */ 469 470 /*! 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 */ 504 struct kern_ctl_reg { 505 /* control information */ 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; 521 #ifdef KERNEL_PRIVATE 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; 525 ctl_setup_func ctl_setup; 526 #endif /* KERNEL_PRIVATE */ 527 }; 528 529 /*! 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 */ 546 errno_t 547 ctl_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 */ 559 errno_t 560 ctl_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. 575 */ 576 errno_t 577 ctl_enqueuedata(kern_ctl_ref kctlref, u_int32_t unit, void *data, size_t len, u_int32_t flags); 578 579 /*! 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 */ 593 errno_t 594 ctl_enqueuembuf(kern_ctl_ref kctlref, u_int32_t unit, mbuf_t m, u_int32_t flags); 595 596 #ifdef PRIVATE 597 /*! 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 */ 614 errno_t 615 ctl_enqueuembuf_list(kern_ctl_ref kctlref, u_int32_t unit, mbuf_t m_list, 616 u_int32_t flags, mbuf_t *m_remain); 617 618 /*! 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. 627 */ 628 errno_t 629 ctl_getenqueuepacketcount(kern_ctl_ref kctlref, u_int32_t unit, u_int32_t *pcnt); 630 631 #endif /* PRIVATE */ 632 633 /*! 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. 642 */ 643 errno_t 644 ctl_getenqueuespace(kern_ctl_ref kctlref, u_int32_t unit, size_t *space); 645 646 /*! 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. 658 */ 659 errno_t 660 ctl_getenqueuereadable(kern_ctl_ref kctlref, u_int32_t unit, u_int32_t *difference); 661 662 #ifdef KERNEL_PRIVATE 663 664 #include <sys/queue.h> 665 #include <libkern/locks.h> 666 667 /* 668 * internal structure maintained for each register controller 669 */ 670 struct ctl_cb; 671 struct kctl; 672 struct socket; 673 struct socket_info; 674 675 void kctl_fill_socketinfo(struct socket *, struct socket_info *); 676 677 u_int32_t ctl_id_by_name(const char *name); 678 errno_t ctl_name_by_id(u_int32_t id, char *out_name, size_t maxsize); 679 680 extern const u_int32_t ctl_maxunit; 681 #endif /* KERNEL_PRIVATE */ 682 683 __END_DECLS 684 #endif /* KERNEL */ 685 686 #endif /* KPI_KERN_CONTROL_H */ 687