bsd/sys/kern_event.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 /* Copyright (c) 1998, 1999 Apple Computer, Inc. All Rights Reserved */
  23 /*!
  24         @header kern_event.h
  25         This header defines in-kernel functions for generating kernel events as well
  26         as functions for receiving kernel events using a kernel event socket.
  27  */
  28
  29 #ifndef SYS_KERN_EVENT_H
  30 #define SYS_KERN_EVENT_H
  31
  32 #include <sys/appleapiopts.h>
  33 #include <sys/ioccom.h>
  34 #include <sys/sys_domain.h>
  35
  36 #define KEVENTS_ON  1
  37 #define KEV_SNDSPACE (4 * 1024)
  38 #define KEV_RECVSPACE (8 * 1024)
  39
  40 #define KEV_ANY_VENDOR    0
  41 #define KEV_ANY_CLASS     0
  42 #define KEV_ANY_SUBCLASS  0
  43
  44 /*
  45  * Vendor Code
  46  */
  47
  48 /*!
  49         @defined KEV_VENDOR_APPLE
  50     @discussion Apple generated kernel events use the hard coded vendor code
  51         value of 1. Third party kernel events use a dynamically allocated vendor
  52         code. The vendor code can be found using the SIOCGKEVVENDOR ioctl.
  53 */
  54 #define KEV_VENDOR_APPLE        1
  55
  56
  57 /*
  58  * Definition of top-level classifications for KEV_VENDOR_APPLE
  59  */
  60
  61 /*!
  62         @defined KEV_NETWORK_CLASS
  63     @discussion Network kernel event class.
  64 */
  65 #define KEV_NETWORK_CLASS       1
  66
  67 /*!
  68         @defined KEV_IOKIT_CLASS
  69     @discussion IOKit kernel event class.
  70 */
  71 #define KEV_IOKIT_CLASS         2
  72
  73 /*!
  74         @defined KEV_IOKIT_CLASS
  75     @discussion System kernel event class.
  76 */
  77 #define KEV_SYSTEM_CLASS        3
  78
  79 /*!
  80         @defined KEV_APPLESHARE_CLASS
  81     @discussion AppleShare kernel event class.
  82 */
  83 #define KEV_APPLESHARE_CLASS    4
  84
  85 /*!
  86         @struct kern_event_msg
  87         @discussion This structure is prepended to all kernel events. This structure
  88                 is used to determine the format of the remainder of the kernel event.
  89                 This structure will appear on all messages received on a kernel event
  90                 socket. To post a kernel event, a slightly different structure is used.
  91         @field total_size Total size of the kernel event message including the
  92                 header.
  93         @field vendor_code The vendor code indicates which vendor generated the
  94                 kernel event. This gives every vendor a unique set of classes and
  95                 subclasses to use. Use the SIOCGKEVVENDOR ioctl to look up vendor codes
  96                 for vendors other than Apple. Apple uses KEV_VENDOR_APPLE.
  97         @field kev_class The class of the kernel event.
  98         @field kev_subclass The subclass of the kernel event.
  99         @field id Monotonically increasing value.
 100         @field event_code The event code.
 101         @field event_data Any additional data about this event. Format will depend
 102                 on the vendor_code, kev_class, kev_subclass, and event_code. The length
 103                 of the event_data can be determined using total_size -
 104                 KEV_MSG_HEADER_SIZE.
 105 */
 106 struct kern_event_msg {
 107      u_long     total_size;             /* Size of entire event msg */
 108      u_long     vendor_code;    /* For non-Apple extensibility */
 109      u_long     kev_class;              /* Layer of event source */
 110      u_long     kev_subclass;   /* Component within layer */
 111      u_long     id;                             /* Monotonically increasing value */
 112      u_long     event_code;             /* unique code */
 113      u_long     event_data[1];  /* One or more data longwords */
 114
 115 };
 116
 117 /*!
 118         @defined KEV_MSG_HEADER_SIZE
 119     @discussion Size of the header portion of the kern_event_msg structure. This
 120         accounts for everything right up to event_data. The size of the data can
 121         be found by subtracting KEV_MSG_HEADER_SIZE from the total size from the
 122         kern_event_msg.
 123 */
 124 #define KEV_MSG_HEADER_SIZE (offsetof(struct kern_event_msg, event_data[0]))
 125
 126 /*!
 127         @struct kev_request
 128         @discussion This structure is used with the SIOCSKEVFILT and SIOCGKEVFILT to
 129                 set and get the control filter setting for a kernel control socket.
 130         @field total_size Total size of the kernel event message including the
 131                 header.
 132         @field vendor_code All kernel events that don't match this vendor code will
 133                 be ignored. KEV_ANY_VENDOR can be used to receive kernel events with any
 134                 vendor code.
 135         @field kev_class All kernel events that don't match this class will be
 136                 ignored. KEV_ANY_CLASS can be used to receive kernel events with any
 137                 class.
 138         @field kev_subclass All kernel events that don't match this subclass will be
 139                 ignored. KEV_ANY_SUBCLASS can be used to receive kernel events with any
 140                 subclass.
 141 */
 142 struct kev_request {
 143      u_long     vendor_code;
 144      u_long     kev_class;
 145      u_long     kev_subclass;
 146 };
 147
 148 /*!
 149         @defined KEV_VENDOR_CODE_MAX_STR_LEN
 150         @discussion This define sets the maximum length of a string that can be used
 151                 to identify a vendor or kext when looking up a vendor code.
 152 */
 153 #define KEV_VENDOR_CODE_MAX_STR_LEN     200
 154
 155 /*!
 156         @struct kev_vendor_code
 157         @discussion This structure is used with the SIOCGKEVVENDOR ioctl to convert
 158                 from a string identifying a kext or vendor, in the form of a bundle
 159                 identifier, to a vendor code.
 160         @field vendor_code After making the SIOCGKEVVENDOR ioctl call, this will
 161                 be filled in with the vendor code if there is one.
 162         @field vendor_string A bundle style identifier.
 163 */
 164 struct kev_vendor_code {
 165      u_long     vendor_code;
 166      char       vendor_string[KEV_VENDOR_CODE_MAX_STR_LEN];
 167 };
 168
 169
 170 /*!
 171         @defined SIOCGKEVID
 172         @discussion Retrieve the current event id. Each event generated will have
 173                 a new idea. The next event to be generated will have an id of id+1.
 174 */
 175 #define SIOCGKEVID      _IOR('e', 1, u_long)
 176
 177 /*!
 178         @defined SIOCSKEVFILT
 179         @discussion Set the kernel event filter for this socket. Kernel events not
 180                 matching this filter will not be received on this socket.
 181 */
 182 #define SIOCSKEVFILT    _IOW('e', 2, struct kev_request)
 183
 184 /*!
 185         @defined SIOCGKEVFILT
 186         @discussion Retrieve the kernel event filter for this socket. Kernel events
 187                 not matching this filter will not be received on this socket.
 188 */
 189 #define SIOCGKEVFILT    _IOR('e', 3, struct kev_request)
 190
 191 /*!
 192         @defined SIOCGKEVVENDOR
 193         @discussion Lookup the vendor code for the specified vendor. ENOENT will be
 194                 returned if a vendor code for that vendor string does not exist.
 195 */
 196 #define SIOCGKEVVENDOR  _IOWR('e', 4, struct kev_vendor_code)
 197
 198 #ifdef KERNEL
 199 /*!
 200         @define N_KEV_VECTORS
 201         @discussion The maximum number of kev_d_vectors for a kernel event.
 202 */
 203 #define N_KEV_VECTORS     5
 204
 205 /*!
 206         @struct kev_d_vectors
 207         @discussion This structure is used to append some data to a kernel event.
 208         @field data_length The length of data.
 209         @field data_ptr A pointer to data.
 210 */
 211 struct kev_d_vectors {
 212      u_long     data_length;    /* Length of the event data */
 213      void       *data_ptr;    /* Pointer to event data */
 214 };
 215
 216 /*!
 217         @struct kev_d_vectors
 218         @discussion This structure is used when posting a kernel event.
 219         @field vendor_code The vendor code assigned by kev_vendor_code_find.
 220         @field kev_class The event's class.
 221         @field kev_class The event's subclass.
 222         @field kev_class The event's code.
 223         @field dv An array of vectors describing additional data to be appended to
 224                 the kernel event.
 225 */
 226 struct kev_msg {
 227      u_long            vendor_code;     /* For non-Apple extensibility */
 228      u_long            kev_class;       /* Layer of event source */
 229      u_long            kev_subclass;    /* Component within layer    */
 230      u_long            event_code;      /* The event code        */
 231      struct kev_d_vectors  dv[N_KEV_VECTORS];      /* Up to n data vectors  */
 232 };
 233
 234 /*!
 235         @function kev_vendor_code_find
 236         @discussion Lookup a vendor_code given a unique string. If the vendor code
 237                 has not been used since launch, a unique integer will be assigned for
 238                 that string. Vendor codes will remain the same until the machine is
 239                 rebooted.
 240         @param vendor_string A bundle style vendor identifier (i.e. com.apple).
 241         @param vender_code Upon return, a unique vendor code for use when posting
 242                 kernel events.
 243         @result May return ENOMEM if memory constraints prevent allocation of a new
 244                 vendor code.
 245  */
 246 errno_t kev_vendor_code_find(const char *vendor_string, u_long *vender_code);
 247
 248 /*!
 249         @function kev_msg_post
 250         @discussion Post a kernel event message.
 251         @param event_msg A structure defining the kernel event message to post.
 252         @result Will return zero upon success. May return a number of errors
 253                 depending on the type of failure. EINVAL indicates that there was
 254                 something wrong with the kerne event. The vendor code of the kernel
 255                 event must be assigned using kev_vendor_code_find. If the message is
 256                 too large, EMSGSIZE will be returned.
 257  */
 258 errno_t kev_msg_post(struct kev_msg *event_msg);
 259
 260 #ifdef PRIVATE
 261 /*
 262  * Internal version of kev_post_msg. Allows posting Apple vendor code kernel
 263  * events.
 264  */
 265 int             kev_post_msg(struct kev_msg *event);
 266
 267 LIST_HEAD(kern_event_head, kern_event_pcb);
 268
 269 struct  kern_event_pcb {
 270      LIST_ENTRY(kern_event_pcb) ev_link;     /* glue on list of all PCBs */
 271      struct  socket *ev_socket;     /* pointer back to socket */
 272      u_long         vendor_code_filter;
 273      u_long         class_filter;
 274      u_long         subclass_filter;
 275 };
 276
 277 #define sotoevpcb(so)   ((struct kern_event_pcb *)((so)->so_pcb))
 278
 279
 280 #endif /* PRIVATE */
 281 #endif /* KERNEL */
 282 #endif /* SYS_KERN_EVENT_H */