bsd/sys/kern_control.h

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