bsd/sys/kern_control.h

   1 /*
   2  * Copyright (c) 2000 Apple Computer, Inc. All rights reserved.
   3  *
   4  * @APPLE_LICENSE_HEADER_START@
   5  *
   6  * Copyright (c) 1999-2003 Apple Computer, Inc.  All Rights Reserved.
   7  *
   8  * This file contains Original Code and/or Modifications of Original Code
   9  * as defined in and that are subject to the Apple Public Source License
  10  * Version 2.0 (the 'License'). You may not use this file except in
  11  * compliance with the License. Please obtain a copy of the License at
  12  * http://www.opensource.apple.com/apsl/ and read it before using this
  13  * file.
  14  *
  15  * The Original Code and all software distributed under the License are
  16  * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  17  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  18  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  19  * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  20  * Please see the License for the specific language governing rights and
  21  * limitations under the License.
  22  *
  23  * @APPLE_LICENSE_HEADER_END@
  24  */
  25
  26
  27 #ifndef SYS_KERN_CONTROL_H
  28 #define SYS_KERN_CONTROL_H
  29
  30 #include <sys/appleapiopts.h>
  31
  32 #ifdef __APPLE_API_UNSTABLE
  33 /*
  34  * Define Controller event subclass, and associated events.
  35  */
  36
  37 /* Subclass of KEV_SYSTEM_CLASS */
  38 #define KEV_CTL_SUBCLASS        1
  39
  40 #define KEV_CTL_REGISTERED      1       /* a new controller appears */
  41 #define KEV_CTL_DEREGISTERED    2       /* a controller disappears */
  42
  43 /* All KEV_CTL_SUBCLASS events share the same header */
  44 struct ctl_event_data {
  45     u_int32_t   ctl_id;
  46     u_int32_t   ctl_unit;
  47 };
  48
  49
  50 /*
  51  * Controls destined to the Controller Manager.
  52  */
  53
  54 #define CTLIOCGCOUNT    _IOR('N', 1, int)       /* get number of control structures registered */
  55
  56 /*
  57  * Controller address structure
  58  * used to establish contact between user client and kernel controller
  59  * sc_id/sc_unit uniquely identify each controller
  60  * sc_id is a 32-bit "signature" obtained by developers from Apple Computer
  61  * sc_unit is a unit number for this sc_id, and is privately used
  62  * by the developper to identify several instances to control
  63  */
  64
  65 struct sockaddr_ctl
  66 {
  67     u_char      sc_len;         /* sizeof(struct sockaddr_ctl) */
  68     u_char      sc_family;      /* AF_SYSTEM */
  69     u_int16_t   ss_sysaddr;     /* AF_SYS_CONTROL */
  70     u_int32_t   sc_id;          /* 32-bit "signature" managed by Apple */
  71     u_int32_t   sc_unit;        /* Developer private unit number */
  72     u_int32_t   sc_reserved[5];
  73 };
  74 #endif /* __APPLE_API_UNSTABLE */
  75
  76 #ifdef KERNEL
  77 #ifdef __APPLE_API_UNSTABLE
  78
  79 /* Reference to a controller object */
  80 typedef void * kern_ctl_ref;
  81
  82 /* Support flags for controllers */
  83 #define CTL_FLAG_PRIVILEGED     0x1     /* user must be root to contact controller */
  84
  85 /* Data flags for controllers */
  86 #define CTL_DATA_NOWAKEUP       0x1     /* don't wake up client yet */
  87
  88
  89 /*
  90  * Controller registration structure, given at registration time
  91  */
  92 struct kern_ctl_reg
  93 {
  94     /* control information */
  95     u_int32_t   ctl_id;                 /* unique id of the controller, provided by DTS */
  96     u_int32_t   ctl_unit;               /* unit number for the controller, for the specified id */
  97                                         /* a controller can be registered several times with the same id */
  98                                         /* but must have a different unit number */
  99
 100     /* control settings */
 101     u_int32_t   ctl_flags;              /* support flags */
 102     u_int32_t   ctl_sendsize;           /* override send/receive buffer size */
 103     u_int32_t   ctl_recvsize;           /* 0 = use default values */
 104
 105     /* Dispatch functions */
 106
 107     int         (*ctl_connect)
 108                     (kern_ctl_ref ctlref, void *userdata);
 109                                         /* Make contact, called when user client calls connect */
 110                                         /* the socket with the id/unit of the controller */
 111
 112     void        (*ctl_disconnect)
 113                     (kern_ctl_ref ctlref, void *userdata);
 114                                         /* Break contact, called when user client */
 115                                         /* closes the control socket */
 116
 117     int         (*ctl_write)
 118                     (kern_ctl_ref ctlref, void *userdata, struct mbuf *m);
 119                                         /* Send data to the controller, called when user client */
 120                                         /* writes data to the socket */
 121
 122     int         (*ctl_set)
 123                     (kern_ctl_ref ctlref, void *userdata, int opt, void *data, size_t len);
 124                                         /* set controller configuration, called when user client */
 125                                         /* calls setsockopt() for the socket */
 126                                         /* opt is the option number */
 127                                         /* data points to the data, already copied in kernel space */
 128                                         /* len is the lenght of the data buffer */
 129
 130     int         (*ctl_get)
 131                     (kern_ctl_ref ctlref, void *userdata, int opt, void *data, size_t *len);
 132                                         /* get controller configuration, called when user client */
 133                                         /* calls getsockopt() for the socket */
 134                                         /* opt is the option number */
 135                                         /* data points to the data buffer of max lenght len */
 136                                         /* the controller can directly copy data in the buffer space */
 137                                         /* and does not need to worry about copying out the data */
 138                                         /* as long as it respects the max buffer lenght */
 139                                         /* on input, len contains the maximum buffer length */
 140                                         /* on output, len contains the actual buffer lenght */
 141                                         /* if data is NULL on input, then, by convention, the controller */
 142                                         /* should return in len the lenght of the data it would like */
 143                                         /* to return in the subsequent call for that option */
 144
 145     /* prepare the future */
 146     u_int32_t   ctl_reserved[4];        /* for future use if needed */
 147 };
 148
 149
 150 /*
 151  * FUNCTION :
 152  * Register the controller to the controller manager
 153  * For example, can be called from a Kernel Extension Start routine
 154  *
 155  * PARAMETERS :
 156  * userctl :    Registration structure containing control information
 157  *              and callback functions for the controller.
 158  *              Callbacks are optional and can be null.
 159  *              A controller with all callbacks set to null would not be very useful.
 160  * userdata :   This parameter is for use by the controller and
 161  *              will be passed to every callback function
 162  *
 163  * RETURN CODE :
 164  * 0 :          No error
 165  *              ctlref will be filled with a control reference,
 166  *              to use in subsequent call to the controller manager
 167  * EINVAL :     Invalid registration structure
 168  * ENOMEM :     Not enough memory available to register the controller
 169  * EEXIST :     Controller id/unit already registered
 170  */
 171
 172 int
 173 ctl_register(struct kern_ctl_reg *userctl, void *userdata, kern_ctl_ref *ctlref);
 174
 175 /*
 176  * FUNCTION :
 177  * Deregister the controller
 178  * For example, can be called from a Kernel Extension Stop routine
 179  *
 180  * PARAMETERS :
 181  * ctlref :     Reference to the controller previously registered
 182  *
 183  * RETURN CODE :
 184  * 0 :          No error,
 185  *              The controller manager no longer knows about the controller
 186  * EINVAL :     Invalid reference
 187  */
 188
 189 int
 190 ctl_deregister(kern_ctl_ref ctlref);
 191
 192 /*
 193  * FUNCTION :
 194  * Send data to the application in contact with the controller
 195  * ctl_enqueuedata will allocate a mbuf, copy data and enqueue it.
 196  *
 197  * PARAMETERS :
 198  * ctlref :     Reference to the controller previously registered
 199  * data :       Data to send
 200  * len :        Length of the data (maximum lenght of MCLBYTES)
 201  * flags :      Flags used when enqueing
 202  *              CTL_DATA_NOWAKEUP = just enqueue, don't wake up client
 203  *
 204  * RETURN CODE :
 205  * 0 :          No error
 206  * EINVAL:      Invalid reference
 207  * EMSGSIZE:    The buffer is too large
 208  * ENOTCONN :   No user client is connected
 209  * ENOBUFS :    Socket buffer is full, or can't get a new mbuf
 210  *              The controller should re-enqueue later
 211  */
 212
 213 int
 214 ctl_enqueuedata(kern_ctl_ref ctlref, void *data, size_t len, u_int32_t flags);
 215
 216 /*
 217  * FUNCTION :
 218  * Send data to the application in contact with the controller
 219  *
 220  * PARAMETERS :
 221  * ctlref :     Reference to the controller previously registered
 222  * m :          mbuf containing the data to send
 223  * flags :      Flags used when enqueing
 224  *              CTL_DATA_NOWAKEUP = just enqueue, don't wake up client
 225  *
 226  * RETURN CODE :
 227  * 0 :          No error
 228  * EINVAL:      Invalid reference
 229  * ENOTCONN :   No user client is connected
 230  * ENOBUFS :    Socket buffer is full,
 231  *              The controller should either free the mbuf or re-enqueue later
 232  */
 233
 234 int
 235 ctl_enqueuembuf(kern_ctl_ref ctlref, struct mbuf *m, u_int32_t flags);
 236
 237 #endif /* __APPLE_API_UNSTABLE */
 238 #endif /* KERNEL */
 239
 240 #endif /* SYS_KERN_CONTROL_H */
 241