bsd/sys/kern_control.h

   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 */