bsd/sys/kern_control.h

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