bsd/sys/kern_event.h

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