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 #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 PRIVATE 151 152 struct xkctl_reg { 153 u_int32_t xkr_len; 154 u_int32_t xkr_kind; 155 u_int32_t xkr_id; 156 u_int32_t xkr_reg_unit; 157 u_int32_t xkr_flags; 158 u_int64_t xkr_kctlref; 159 u_int32_t xkr_recvbufsize; 160 u_int32_t xkr_sendbufsize; 161 u_int32_t xkr_lastunit; 162 u_int32_t xkr_pcbcount; 163 u_int64_t xkr_connect; 164 u_int64_t xkr_disconnect; 165 u_int64_t xkr_send; 166 u_int64_t xkr_send_list; 167 u_int64_t xkr_setopt; 168 u_int64_t xkr_getopt; 169 u_int64_t xkr_rcvd; 170 char xkr_name[MAX_KCTL_NAME]; 171 }; 172 173 struct xkctlpcb { 174 u_int32_t xkp_len; 175 u_int32_t xkp_kind; 176 u_int64_t xkp_kctpcb; 177 u_int32_t xkp_unit; 178 u_int32_t xkp_kctlid; 179 u_int64_t xkp_kctlref; 180 char xkp_kctlname[MAX_KCTL_NAME]; 181 }; 182 183 struct kctlstat { 184 u_int64_t kcs_reg_total __attribute__((aligned(8))); 185 u_int64_t kcs_reg_count __attribute__((aligned(8))); 186 u_int64_t kcs_pcbcount __attribute__((aligned(8))); 187 u_int64_t kcs_gencnt __attribute__((aligned(8))); 188 u_int64_t kcs_connections __attribute__((aligned(8))); 189 u_int64_t kcs_conn_fail __attribute__((aligned(8))); 190 u_int64_t kcs_send_fail __attribute__((aligned(8))); 191 u_int64_t kcs_send_list_fail __attribute__((aligned(8))); 192 u_int64_t kcs_enqueue_fail __attribute__((aligned(8))); 193 u_int64_t kcs_enqueue_fullsock __attribute__((aligned(8))); 194 u_int64_t kcs_bad_kctlref __attribute__((aligned(8))); 195 u_int64_t kcs_tbl_size_too_big __attribute__((aligned(8))); 196 u_int64_t kcs_enqdata_mb_alloc_fail __attribute__((aligned(8))); 197 u_int64_t kcs_enqdata_sbappend_fail __attribute__((aligned(8))); 198 }; 199 200 #endif /* PRIVATE */ 201 202 #ifdef KERNEL 203 204 #include <sys/kpi_mbuf.h> 205 206 /*! 207 * @typedef kern_ctl_ref 208 * @discussion A control reference is used to track an attached kernel 209 * control. Registering a kernel control will create a kernel 210 * control reference. This reference is required for sending data 211 * or removing the kernel control. This reference will be passed to 212 * callbacks for that kernel control. 213 */ 214 typedef void * kern_ctl_ref; 215 216 /*! 217 * @defined CTL_FLAG_PRIVILEGED 218 * @discussion The CTL_FLAG_PRIVILEGED flag is passed in ctl_flags. If 219 * this flag is set, only privileged processes may attach to this 220 * kernel control. 221 */ 222 #define CTL_FLAG_PRIVILEGED 0x1 223 /*! 224 * @defined CTL_FLAG_REG_ID_UNIT 225 * @discussion The CTL_FLAG_REG_ID_UNIT flag is passed to indicate that 226 * the ctl_id specified should be used. If this flag is not 227 * present, a unique ctl_id will be dynamically assigned to your 228 * kernel control. The CTLIOCGINFO ioctl can be used by the client 229 * to find the dynamically assigned id based on the control name 230 * specified in ctl_name. 231 */ 232 #define CTL_FLAG_REG_ID_UNIT 0x2 233 /*! 234 * @defined CTL_FLAG_REG_SOCK_STREAM 235 * @discussion Use the CTL_FLAG_REG_SOCK_STREAM flag when client need to open 236 * socket of type SOCK_STREAM to communicate with the kernel control. 237 * By default kernel control sockets are of type SOCK_DGRAM. 238 */ 239 #define CTL_FLAG_REG_SOCK_STREAM 0x4 240 241 #ifdef KERNEL_PRIVATE 242 /*! 243 * @defined CTL_FLAG_REG_EXTENDED 244 * @discussion This flag indicates that this kernel control utilizes the 245 * the extended fields within the kern_ctl_reg structure. 246 */ 247 #define CTL_FLAG_REG_EXTENDED 0x8 248 249 /*! 250 * @defined CTL_FLAG_REG_CRIT 251 * @discussion This flag indicates that this kernel control utilizes the 252 * the extended fields within the kern_ctl_reg structure. 253 */ 254 #define CTL_FLAG_REG_CRIT 0x10 255 256 /*! 257 * @defined CTL_FLAG_REG_SETUP 258 * @discussion This flag indicates that this kernel control utilizes the 259 * the setup callback field within the kern_ctl_reg structure. 260 */ 261 #define CTL_FLAG_REG_SETUP 0x20 262 #endif /* KERNEL_PRIVATE */ 263 264 /* Data flags for controllers */ 265 /*! 266 * @defined CTL_DATA_NOWAKEUP 267 * @discussion The CTL_DATA_NOWAKEUP flag can be used for the enqueue 268 * data and enqueue mbuf functions to indicate that the process 269 * should not be woken up yet. This is useful when you want to 270 * enqueue data using more than one call but only want to wake up 271 * the client after all of the data has been enqueued. 272 */ 273 #define CTL_DATA_NOWAKEUP 0x1 274 275 /*! 276 * @defined CTL_DATA_EOR 277 * @discussion The CTL_DATA_EOR flag can be used for the enqueue 278 * data and enqueue mbuf functions to mark the end of a record. 279 */ 280 #define CTL_DATA_EOR 0x2 281 282 #ifdef KERNEL_PRIVATE 283 /*! 284 * @defined CTL_DATA_CRIT 285 * @discussion This flag indicates the data is critical to the client 286 * and that it needs to be forced into the socket buffer 287 * by resizing it if needed. 288 */ 289 #define CTL_DATA_CRIT 0x4 290 #endif /* KERNEL_PRIVATE */ 291 292 __BEGIN_DECLS 293 294 /*! 295 * @typedef ctl_connect_func 296 * @discussion The ctl_connect_func is used to receive 297 * notification of a client connecting to the kernel control. 298 * @param kctlref The control ref for the kernel control the client is 299 * connecting to. 300 * @param sac The address used to connect to this control. The field sc_unit 301 * contains the unit number of the kernel control instance the client is 302 * connecting to. If CTL_FLAG_REG_ID_UNIT was set when the kernel control 303 * was registered, sc_unit is the ctl_unit of the kern_ctl_reg structure. 304 * If CTL_FLAG_REG_ID_UNIT was not set when the kernel control was 305 * registered, sc_unit is the dynamically allocated unit number of 306 * the new kernel control instance that is used for this connection. 307 * @param unitinfo A placeholder for a pointer to the optional user-defined 308 * private data associated with this kernel control instance. This 309 * opaque info will be provided to the user when the rest of the 310 * callback routines are executed. For example, it can be used 311 * to pass a pointer to an instance-specific data structure in 312 * order for the user to keep track of the states related to this 313 * kernel control instance. 314 */ 315 typedef errno_t (*ctl_connect_func)(kern_ctl_ref kctlref, 316 struct sockaddr_ctl *sac, 317 void **unitinfo); 318 319 /*! 320 * @typedef ctl_disconnect_func 321 * @discussion The ctl_disconnect_func is used to receive notification 322 * that a client has disconnected from the kernel control. This 323 * usually happens when the socket is closed. If this is the last 324 * socket attached to your kernel control, you may unregister your 325 * kernel control from this callback. 326 * @param kctlref The control ref for the kernel control instance the client has 327 * disconnected from. 328 * @param unit The unit number of the kernel control instance the client has 329 * disconnected from. 330 * @param unitinfo The user-defined private data initialized by the 331 * ctl_connect_func callback. 332 */ 333 typedef errno_t (*ctl_disconnect_func)(kern_ctl_ref kctlref, u_int32_t unit, void *unitinfo); 334 335 /*! 336 * @typedef ctl_send_func 337 * @discussion The ctl_send_func is used to receive data sent from 338 * the client to the kernel control. 339 * @param kctlref The control ref of the kernel control. 340 * @param unit The unit number of the kernel control instance the client has 341 * connected to. 342 * @param unitinfo The user-defined private data initialized by the 343 * ctl_connect_func callback. 344 * @param m The data sent by the client to the kernel control in an 345 * mbuf chain. Your function is responsible for releasing the 346 * mbuf chain. 347 * @param flags The flags specified by the client when calling 348 * send/sendto/sendmsg (MSG_OOB/MSG_DONTROUTE). 349 */ 350 typedef errno_t (*ctl_send_func)(kern_ctl_ref kctlref, u_int32_t unit, void *unitinfo, 351 mbuf_t m, int flags); 352 353 /*! 354 * @typedef ctl_setopt_func 355 * @discussion The ctl_setopt_func is used to handle set socket option 356 * calls for the SYSPROTO_CONTROL option level. 357 * @param kctlref The control ref of the kernel control. 358 * @param unit The unit number of the kernel control instance. 359 * @param unitinfo The user-defined private data initialized by the 360 * ctl_connect_func callback. 361 * @param opt The socket option. 362 * @param data A pointer to the socket option data. The data has 363 * already been copied in to the kernel for you. 364 * @param len The length of the socket option data. 365 */ 366 typedef errno_t (*ctl_setopt_func)(kern_ctl_ref kctlref, u_int32_t unit, void *unitinfo, 367 int opt, void *data, size_t len); 368 369 /*! 370 * @typedef ctl_getopt_func 371 * @discussion The ctl_getopt_func is used to handle client get socket 372 * option requests for the SYSPROTO_CONTROL option level. A buffer 373 * is allocated for storage and passed to your function. The length 374 * of that buffer is also passed. Upon return, you should set *len 375 * to length of the buffer used. In some cases, data may be NULL. 376 * When this happens, *len should be set to the length you would 377 * have returned had data not been NULL. If the buffer is too small, 378 * return an error. 379 * @param kctlref The control ref of the kernel control. 380 * @param unit The unit number of the kernel control instance. 381 * @param unitinfo The user-defined private data initialized by the 382 * ctl_connect_func callback. 383 * @param opt The socket option. 384 * @param data A buffer to copy the results in to. May be NULL, see 385 * discussion. 386 * @param len A pointer to the length of the buffer. This should be set 387 * to the length of the buffer used before returning. 388 */ 389 typedef errno_t (*ctl_getopt_func)(kern_ctl_ref kctlref, u_int32_t unit, void *unitinfo, 390 int opt, void *data, size_t *len); 391 392 #ifdef KERNEL_PRIVATE 393 /*! 394 * @typedef ctl_rcvd_func 395 * @discussion The ctl_rcvd_func is called when the client reads data from 396 * the kernel control socket. The kernel control can use this callback 397 * in combination with ctl_getenqueuespace() to avoid overflowing 398 * the socket's receive buffer. When ctl_getenqueuespace() returns 399 * 0 or ctl_enqueuedata()/ctl_enqueuembuf() return ENOBUFS, the 400 * kernel control can wait until this callback is called before 401 * trying to enqueue the data again. 402 * @param kctlref The control ref of the kernel control. 403 * @param unit The unit number of the kernel control instance. 404 * @param unitinfo The user-defined private data initialized by the 405 * ctl_connect_func callback. 406 * @param flags The recv flags. See the recv(2) man page. 407 */ 408 typedef void (*ctl_rcvd_func)(kern_ctl_ref kctlref, u_int32_t unit, void *unitinfo, 409 int flags); 410 411 /*! 412 * @typedef ctl_send_list_func 413 * @discussion The ctl_send_list_func is used to receive data sent from 414 * the client to the kernel control. 415 * @param kctlref The control ref of the kernel control. 416 * @param unit The unit number of the kernel control instance the client has 417 * connected to. 418 * @param unitinfo The user-defined private data initialized by the 419 * ctl_connect_func callback. 420 * @param m The data sent by the client to the kernel control in an 421 * mbuf packet chain. Your function is responsible for releasing 422 * mbuf packet chain. 423 * @param flags The flags specified by the client when calling 424 * send/sendto/sendmsg (MSG_OOB/MSG_DONTROUTE). 425 */ 426 typedef errno_t (*ctl_send_list_func)(kern_ctl_ref kctlref, u_int32_t unit, void *unitinfo, 427 mbuf_t m, int flags); 428 429 /*! 430 * @typedef ctl_bind_func 431 * @discussion The ctl_bind_func is an optional function that allows the client 432 * to set up their unitinfo prior to connecting. 433 * @param kctlref The control ref for the kernel control the client is 434 * binding to. 435 * @param sac The address used to connect to this control. The field sc_unit 436 * contains the unit number of the kernel control instance the client is 437 * binding to. If CTL_FLAG_REG_ID_UNIT was set when the kernel control 438 * was registered, sc_unit is the ctl_unit of the kern_ctl_reg structure. 439 * If CTL_FLAG_REG_ID_UNIT was not set when the kernel control was 440 * registered, sc_unit is the dynamically allocated unit number of 441 * the new kernel control instance that is used for this connection. 442 * @param unitinfo A placeholder for a pointer to the optional user-defined 443 * private data associated with this kernel control instance. This 444 * opaque info will be provided to the user when the rest of the 445 * callback routines are executed. For example, it can be used 446 * to pass a pointer to an instance-specific data structure in 447 * order for the user to keep track of the states related to this 448 * kernel control instance. 449 */ 450 typedef errno_t (*ctl_bind_func)(kern_ctl_ref kctlref, 451 struct sockaddr_ctl *sac, 452 void **unitinfo); 453 454 /*! 455 * @typedef ctl_setup_func 456 * @discussion The ctl_setup_func is an optional function that allows the client 457 * to pick a unit number in the case that the caller hasn't specified one 458 * @param unit A placeholder for a pointer to the unit number that is selected with 459 * this kernel control instance 460 * @param unitinfo A placeholder for a pointer to the optional user-defined 461 * private data associated with this kernel control instance. This 462 * opaque info will be provided to the user when the rest of the 463 * callback routines are executed. For example, it can be used 464 * to pass a pointer to an instance-specific data structure in 465 * order for the user to keep track of the states related to this 466 * kernel control instance. 467 */ 468 typedef errno_t (*ctl_setup_func)(u_int32_t *unit, void **unitinfo); 469 #endif /* KERNEL_PRIVATE */ 470 471 /*! 472 * @struct kern_ctl_reg 473 * @discussion This structure defines the properties of a kernel 474 * control being registered. 475 * @field ctl_name A Bundle ID string of up to MAX_KCTL_NAME bytes (including the ending zero). 476 * This string should not be empty. 477 * @field ctl_id The control ID may be dynamically assigned or it can be a 478 * 32-bit creator code assigned by DTS. 479 * For a DTS assigned creator code the CTL_FLAG_REG_ID_UNIT flag must be set. 480 * For a dynamically assigned control ID, do not set the CTL_FLAG_REG_ID_UNIT flag. 481 * The value of the dynamically assigned control ID is set to this field 482 * when the registration succeeds. 483 * @field ctl_unit A separate unit number to register multiple units that 484 * share the same control ID with DTS assigned creator code when 485 * the CTL_FLAG_REG_ID_UNIT flag is set. 486 * This field is ignored for a dynamically assigned control ID. 487 * @field ctl_flags CTL_FLAG_PRIVILEGED and/or CTL_FLAG_REG_ID_UNIT. 488 * @field ctl_sendsize Override the default send size. If set to zero, 489 * the default send size will be used, and this default value 490 * is set to this field to be retrieved by the caller. 491 * @field ctl_recvsize Override the default receive size. If set to 492 * zero, the default receive size will be used, and this default value 493 * is set to this field to be retrieved by the caller. 494 * @field ctl_connect Specify the function to be called whenever a client 495 * connects to the kernel control. This field must be specified. 496 * @field ctl_disconnect Specify a function to be called whenever a 497 * client disconnects from the kernel control. 498 * @field ctl_send Specify a function to handle data send from the 499 * client to the kernel control. 500 * @field ctl_setopt Specify a function to handle set socket option 501 * operations for the kernel control. 502 * @field ctl_getopt Specify a function to handle get socket option 503 * operations for the kernel control. 504 */ 505 struct kern_ctl_reg { 506 /* control information */ 507 char ctl_name[MAX_KCTL_NAME]; 508 u_int32_t ctl_id; 509 u_int32_t ctl_unit; 510 511 /* control settings */ 512 u_int32_t ctl_flags; 513 u_int32_t ctl_sendsize; 514 u_int32_t ctl_recvsize; 515 516 /* Dispatch functions */ 517 ctl_connect_func ctl_connect; 518 ctl_disconnect_func ctl_disconnect; 519 ctl_send_func ctl_send; 520 ctl_setopt_func ctl_setopt; 521 ctl_getopt_func ctl_getopt; 522 #ifdef KERNEL_PRIVATE 523 ctl_rcvd_func ctl_rcvd; /* Only valid if CTL_FLAG_REG_EXTENDED is set */ 524 ctl_send_list_func ctl_send_list;/* Only valid if CTL_FLAG_REG_EXTENDED is set */ 525 ctl_bind_func ctl_bind; 526 ctl_setup_func ctl_setup; 527 #endif /* KERNEL_PRIVATE */ 528 }; 529 530 /*! 531 * @function ctl_register 532 * @discussion Register a kernel control. This will enable clients to 533 * connect to the kernel control using a PF_SYSTEM socket. 534 * @param userkctl A structure defining the kernel control to be 535 * attached. The ctl_connect callback must be specified, the other callbacks 536 * are optional. If ctl_connect is set to zero, ctl_register fails with 537 * the error code EINVAL. 538 * @param kctlref Upon successful return, the kctlref will contain a 539 * reference to the attached kernel control. This reference is used 540 * to unregister the kernel control. This reference will also be 541 * passed in to the callbacks each time they are called. 542 * @result 0 - Kernel control was registered. 543 * EINVAL - The registration structure was not valid. 544 * ENOMEM - There was insufficient memory. 545 * EEXIST - A controller with that id/unit is already registered. 546 */ 547 errno_t 548 ctl_register(struct kern_ctl_reg *userkctl, kern_ctl_ref *kctlref); 549 550 /*! 551 * @function ctl_deregister 552 * @discussion Unregister a kernel control. A kernel extension must 553 * unregister it's kernel control(s) before unloading. If a kernel 554 * control has clients attached, this call will fail. 555 * @param kctlref The control reference of the control to unregister. 556 * @result 0 - Kernel control was unregistered. 557 * EINVAL - The kernel control reference was invalid. 558 * EBUSY - The kernel control has clients still attached. 559 */ 560 errno_t 561 ctl_deregister(kern_ctl_ref kctlref); 562 563 /*! 564 * @function ctl_enqueuedata 565 * @discussion Send data from the kernel control to the client. 566 * @param kctlref The control reference of the kernel control. 567 * @param unit The unit number of the kernel control instance. 568 * @param data A pointer to the data to send. 569 * @param len The length of data to send. 570 * @param flags Send flags. CTL_DATA_NOWAKEUP and CTL_DATA_EOR are currently 571 * the only supported flags. 572 * @result 0 - Data was enqueued to be read by the client. 573 * EINVAL - Invalid parameters. 574 * EMSGSIZE - The buffer is too large. 575 * ENOBUFS - The queue is full or there are no free mbufs. 576 */ 577 errno_t 578 ctl_enqueuedata(kern_ctl_ref kctlref, u_int32_t unit, void *data, size_t len, u_int32_t flags); 579 580 /*! 581 * @function ctl_enqueuembuf 582 * @discussion Send data stored in an mbuf chain from the kernel 583 * control to the client. The caller is responsible for freeing 584 * the mbuf chain if ctl_enqueuembuf returns an error. 585 * @param kctlref The control reference of the kernel control. 586 * @param unit The unit number of the kernel control instance. 587 * @param m An mbuf chain containing the data to send to the client. 588 * @param flags Send flags. CTL_DATA_NOWAKEUP and CTL_DATA_EOR are currently 589 * the only supported flags. 590 * @result 0 - Data was enqueued to be read by the client. 591 * EINVAL - Invalid parameters. 592 * ENOBUFS - The queue is full. 593 */ 594 errno_t 595 ctl_enqueuembuf(kern_ctl_ref kctlref, u_int32_t unit, mbuf_t m, u_int32_t flags); 596 597 #ifdef PRIVATE 598 /*! 599 * @function ctl_enqueuembuf_list 600 * @discussion Send data stored in an mbuf packet chain from the kernel 601 * control to the client. The caller is responsible for freeing 602 * the mbuf chain if ctl_enqueuembuf returns an error. 603 * Not valid if ctl_flags contains CTL_FLAG_REG_SOCK_STREAM. 604 * @param kctlref The control reference of the kernel control. 605 * @param unit The unit number of the kernel control instance. 606 * @param m_list An mbuf chain containing the data to send to the client. 607 * @param flags Send flags. CTL_DATA_NOWAKEUP is 608 * the only supported flags. 609 * @param m_remain A pointer to the list of mbuf packets in the chain that 610 * could not be enqueued. 611 * @result 0 - Data was enqueued to be read by the client. 612 * EINVAL - Invalid parameters. 613 * ENOBUFS - The queue is full. 614 */ 615 errno_t 616 ctl_enqueuembuf_list(kern_ctl_ref kctlref, u_int32_t unit, mbuf_t m_list, 617 u_int32_t flags, mbuf_t *m_remain); 618 619 /*! 620 * @function ctl_getenqueuepacketcount 621 * @discussion Retrieve the number of packets in the socket 622 * receive buffer. 623 * @param kctlref The control reference of the kernel control. 624 * @param unit The unit number of the kernel control instance. 625 * @param pcnt The address where to return the current count. 626 * @result 0 - Success; the packet count is returned to caller. 627 * EINVAL - Invalid parameters. 628 */ 629 errno_t 630 ctl_getenqueuepacketcount(kern_ctl_ref kctlref, u_int32_t unit, u_int32_t *pcnt); 631 632 #endif /* PRIVATE */ 633 634 /*! 635 * @function ctl_getenqueuespace 636 * @discussion Retrieve the amount of space currently available for data to be sent 637 * from the kernel control to the client. 638 * @param kctlref The control reference of the kernel control. 639 * @param unit The unit number of the kernel control instance. 640 * @param space The address where to return the current space available 641 * @result 0 - Success; the amount of space is returned to caller. 642 * EINVAL - Invalid parameters. 643 */ 644 errno_t 645 ctl_getenqueuespace(kern_ctl_ref kctlref, u_int32_t unit, size_t *space); 646 647 /*! 648 * @function ctl_getenqueuereadable 649 * @discussion Retrieve the difference between enqueued bytes and 650 * low-water mark for the socket receive buffer. 651 * @param kctlref The control reference of the kernel control. 652 * @param unit The unit number of the kernel control instance. 653 * @param difference The address at which to return the current difference 654 * between the low-water mark for the socket and the number of bytes 655 * enqueued. 0 indicates that the socket is readable by the client 656 * (the number of bytes in the buffer is above the low-water mark). 657 * @result 0 - Success; the difference is returned to caller. 658 * EINVAL - Invalid parameters. 659 */ 660 errno_t 661 ctl_getenqueuereadable(kern_ctl_ref kctlref, u_int32_t unit, u_int32_t *difference); 662 663 #ifdef KERNEL_PRIVATE 664 665 #include <sys/queue.h> 666 #include <libkern/locks.h> 667 668 /* 669 * internal structure maintained for each register controller 670 */ 671 struct ctl_cb; 672 struct kctl; 673 struct socket; 674 struct socket_info; 675 676 void kctl_fill_socketinfo(struct socket *, struct socket_info *); 677 678 u_int32_t ctl_id_by_name(const char *name); 679 errno_t ctl_name_by_id(u_int32_t id, char *out_name, size_t maxsize); 680 681 extern const u_int32_t ctl_maxunit; 682 #endif /* KERNEL_PRIVATE */ 683 684 __END_DECLS 685 #endif /* KERNEL */ 686 687 #endif /* KPI_KERN_CONTROL_H */ 688