include/sys/sysevent.h

   1 /*
   2  * CDDL HEADER START
   3  *
   4  * The contents of this file are subject to the terms of the
   5  * Common Development and Distribution License (the "License").
   6  * You may not use this file except in compliance with the License.
   7  *
   8  * You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
   9  * or http://www.opensolaris.org/os/licensing.
  10  * See the License for the specific language governing permissions
  11  * and limitations under the License.
  12  *
  13  * When distributing Covered Code, include this CDDL HEADER in each
  14  * file and include the License file at usr/src/OPENSOLARIS.LICENSE.
  15  * If applicable, add the following below this CDDL HEADER, with the
  16  * fields enclosed by brackets "[]" replaced with your own identifying
  17  * information: Portions Copyright [yyyy] [name of copyright owner]
  18  *
  19  * CDDL HEADER END
  20  */
  21
  22 /*
  23  * Copyright (c) 2000, 2010, Oracle and/or its affiliates. All rights reserved.
  24  */
  25
  26 #ifndef _SYS_SYSEVENT_H
  27 #define _SYS_SYSEVENT_H
  28
  29 #include <sys/nvpair.h>
  30 #include <sys/null.h>
  31
  32 #ifdef  __cplusplus
  33 extern "C" {
  34 #endif
  35
  36 /* Internal registration class and subclass */
  37 #define EC_ALL          "register_all_classes"
  38 #define EC_SUB_ALL      "register_all_subclasses"
  39
  40 /*
  41  * Event allocation/enqueuing sleep/nosleep flags
  42  */
  43 #define SE_SLEEP                0
  44 #define SE_NOSLEEP              1
  45
  46 /* Framework error codes */
  47 #define SE_EINVAL               1       /* Invalid argument */
  48 #define SE_ENOMEM               2       /* Unable to allocate memory */
  49 #define SE_EQSIZE               3       /* Maximum event q size exceeded */
  50 #define SE_EFAULT               4       /* Copy fault */
  51 #define SE_NOTFOUND             5       /* Attribute not found */
  52 #define SE_NO_TRANSPORT         6       /* sysevent transport down */
  53
  54 /* Internal data types */
  55
  56 #define SE_DATA_TYPE_BYTE       DATA_TYPE_BYTE
  57 #define SE_DATA_TYPE_INT16      DATA_TYPE_INT16
  58 #define SE_DATA_TYPE_UINT16     DATA_TYPE_UINT16
  59 #define SE_DATA_TYPE_INT32      DATA_TYPE_INT32
  60 #define SE_DATA_TYPE_UINT32     DATA_TYPE_UINT32
  61 #define SE_DATA_TYPE_INT64      DATA_TYPE_INT64
  62 #define SE_DATA_TYPE_UINT64     DATA_TYPE_UINT64
  63 #define SE_DATA_TYPE_STRING     DATA_TYPE_STRING
  64 #define SE_DATA_TYPE_BYTES      DATA_TYPE_BYTE_ARRAY
  65 #define SE_DATA_TYPE_TIME       DATA_TYPE_HRTIME
  66
  67 #define SE_KERN_PID     0
  68
  69 #define SUNW_VENDOR     "SUNW"
  70 #define SE_USR_PUB      "usr:"
  71 #define SE_KERN_PUB     "kern:"
  72 #define SUNW_KERN_PUB   SUNW_VENDOR ":" SE_KERN_PUB
  73 #define SUNW_USR_PUB    SUNW_VENDOR ":" SE_USR_PUB
  74
  75 /*
  76  * Event header and attribute value limits
  77  */
  78 #define MAX_ATTR_NAME   1024
  79 #define MAX_STRING_SZ   1024
  80 #define MAX_BYTE_ARRAY  1024
  81
  82 #define MAX_CLASS_LEN           64
  83 #define MAX_SUBCLASS_LEN        64
  84 #define MAX_PUB_LEN             128
  85 #define MAX_CHNAME_LEN          128
  86 #define MAX_SUBID_LEN           16
  87
  88 /*
  89  * Limit for the event payload size
  90  */
  91 #define MAX_EV_SIZE_LEN         (SHRT_MAX/4)
  92
  93 /* Opaque sysevent_t data type */
  94 typedef void *sysevent_t;
  95
  96 /* Opaque channel bind data type */
  97 typedef void evchan_t;
  98
  99 /* sysevent attribute list */
 100 typedef nvlist_t sysevent_attr_list_t;
 101
 102 /* sysevent attribute name-value pair */
 103 typedef nvpair_t sysevent_attr_t;
 104
 105 /* Unique event identifier */
 106 typedef struct sysevent_id {
 107         uint64_t eid_seq;
 108         hrtime_t eid_ts;
 109 } sysevent_id_t;
 110
 111 /* Event attribute value structures */
 112 typedef struct sysevent_bytes {
 113         int32_t size;
 114         uchar_t *data;
 115 } sysevent_bytes_t;
 116
 117 typedef struct sysevent_value {
 118         int32_t         value_type;             /* data type */
 119         union {
 120                 uchar_t         sv_byte;
 121                 int16_t         sv_int16;
 122                 uint16_t        sv_uint16;
 123                 int32_t         sv_int32;
 124                 uint32_t        sv_uint32;
 125                 int64_t         sv_int64;
 126                 uint64_t        sv_uint64;
 127                 hrtime_t        sv_time;
 128                 char            *sv_string;
 129                 sysevent_bytes_t        sv_bytes;
 130         } value;
 131 } sysevent_value_t;
 132
 133 /*
 134  * The following flags determine the memory allocation semantics to use for
 135  * kernel event buffer allocation by userland and kernel versions of
 136  * sysevent_evc_publish().
 137  *
 138  * EVCH_SLEEP and EVCH_NOSLEEP respectively map to KM_SLEEP and KM_NOSLEEP.
 139  * EVCH_TRYHARD is a kernel-only publish flag that allow event allocation
 140  * routines to use use alternate kmem caches in situations where free memory
 141  * may be low.  Kernel callers of sysevent_evc_publish() must set flags to
 142  * one of EVCH_SLEEP, EVCH_NOSLEEP or EVCH_TRYHARD.  Userland callers of
 143  * sysevent_evc_publish() must set flags to one of EVCH_SLEEP or EVCH_NOSLEEP.
 144  *
 145  * EVCH_QWAIT determines whether or not we should wait for slots in the event
 146  * queue at publication time.  EVCH_QWAIT may be used by kernel and userland
 147  * publishers and must be used in conjunction with any of one of EVCH_SLEEP,
 148  * EVCH_NOSLEEP or EVCH_TRYHARD (kernel-only).
 149  */
 150
 151 #define EVCH_NOSLEEP    0x0001  /* No sleep on kmem_alloc() */
 152 #define EVCH_SLEEP      0x0002  /* Sleep on kmem_alloc() */
 153 #define EVCH_TRYHARD    0x0004  /* May use alternate kmem cache for alloc */
 154 #define EVCH_QWAIT      0x0008  /* Wait for slot in event queue */
 155
 156 /*
 157  * Meaning of flags for subscribe. Bits 8 to 15 are dedicated to
 158  * the consolidation private interface, so flags defined here are restricted
 159  * to the LSB.
 160  *
 161  * EVCH_SUB_KEEP indicates that this subscription should persist even if
 162  * this subscriber id should die unexpectedly; matching events will be
 163  * queued (up to a limit) and will be delivered if/when we restart again
 164  * with the same subscriber id.
 165  */
 166 #define EVCH_SUB_KEEP           0x01
 167
 168 /*
 169  * Subscriptions may be wildcarded, but we limit the number of
 170  * wildcards permitted.
 171  */
 172 #define EVCH_WILDCARD_MAX       10
 173
 174 /*
 175  * Used in unsubscribe to indicate all subscriber ids for a channel.
 176  */
 177 #define EVCH_ALLSUB             "all_subs"
 178
 179 /*
 180  * Meaning of flags parameter of channel bind function
 181  *
 182  * EVCH_CREAT indicates to create a channel if not already present.
 183  *
 184  * EVCH_HOLD_PEND indicates that events should be published to this
 185  * channel even if there are no matching subscribers present; when
 186  * a subscriber belatedly binds to the channel and registers their
 187  * subscriptions they will receive events that predate their bind.
 188  * If the channel is closed, however, with no remaining bindings then
 189  * the channel is destroyed.
 190  *
 191  * EVCH_HOLD_PEND_INDEF is a stronger version of EVCH_HOLD_PEND -
 192  * even if the channel has no remaining bindings it will not be
 193  * destroyed so long as events remain unconsumed.  This is suitable for
 194  * use with short-lived event producers that may bind to (create) the
 195  * channel and exit before the intended consumer has started.
 196  */
 197 #define EVCH_CREAT              0x0001
 198 #define EVCH_HOLD_PEND          0x0002
 199 #define EVCH_HOLD_PEND_INDEF    0x0004
 200 #define EVCH_B_FLAGS            0x0007  /* All valid bits */
 201
 202 /*
 203  * Meaning of commands of evc_control function
 204  */
 205 #define EVCH_GET_CHAN_LEN_MAX    1      /* Get event queue length limit */
 206 #define EVCH_GET_CHAN_LEN        2      /* Get event queue length */
 207 #define EVCH_SET_CHAN_LEN        3      /* Set event queue length */
 208 #define EVCH_CMD_LAST            EVCH_SET_CHAN_LEN      /* Last command */
 209
 210 /*
 211  * Shared user/kernel event channel interface definitions
 212  */
 213 extern int sysevent_evc_bind(const char *, evchan_t **, uint32_t);
 214 extern int sysevent_evc_unbind(evchan_t *);
 215 extern int sysevent_evc_subscribe(evchan_t *, const char *, const char *,
 216     int (*)(sysevent_t *, void *), void *, uint32_t);
 217 extern int sysevent_evc_unsubscribe(evchan_t *, const char *);
 218 extern int sysevent_evc_publish(evchan_t *, const char *, const char *,
 219     const char *, const char *, nvlist_t *, uint32_t);
 220 extern int sysevent_evc_control(evchan_t *, int, ...);
 221 extern int sysevent_evc_setpropnvl(evchan_t *, nvlist_t *);
 222 extern int sysevent_evc_getpropnvl(evchan_t *, nvlist_t **);
 223
 224 #ifndef _KERNEL
 225
 226 /*
 227  * Userland-only event channel interfaces
 228  */
 229
 230 #include <door.h>
 231
 232 typedef struct sysevent_subattr sysevent_subattr_t;
 233
 234 extern sysevent_subattr_t *sysevent_subattr_alloc(void);
 235 extern void sysevent_subattr_free(sysevent_subattr_t *);
 236
 237 extern void sysevent_subattr_thrattr(sysevent_subattr_t *, pthread_attr_t *);
 238 extern void sysevent_subattr_sigmask(sysevent_subattr_t *, sigset_t *);
 239
 240 extern void sysevent_subattr_thrcreate(sysevent_subattr_t *,
 241     door_xcreate_server_func_t *, void *);
 242 extern void sysevent_subattr_thrsetup(sysevent_subattr_t *,
 243     door_xcreate_thrsetup_func_t *, void *);
 244
 245 extern int sysevent_evc_xsubscribe(evchan_t *, const char *, const char *,
 246     int (*)(sysevent_t *, void *), void *, uint32_t, sysevent_subattr_t *);
 247
 248 #else
 249
 250 /*
 251  * Kernel log_event interfaces.
 252  */
 253 extern int log_sysevent(sysevent_t *, int, sysevent_id_t *);
 254
 255 extern sysevent_t *sysevent_alloc(char *, char *, char *, int);
 256 extern void sysevent_free(sysevent_t *);
 257 extern int sysevent_add_attr(sysevent_attr_list_t **, char *,
 258     sysevent_value_t *, int);
 259 extern void sysevent_free_attr(sysevent_attr_list_t *);
 260 extern int sysevent_attach_attributes(sysevent_t *, sysevent_attr_list_t *);
 261 extern void sysevent_detach_attributes(sysevent_t *);
 262 extern char *sysevent_get_class_name(sysevent_t *);
 263 extern char *sysevent_get_subclass_name(sysevent_t *);
 264 extern uint64_t sysevent_get_seq(sysevent_t *);
 265 extern void sysevent_get_time(sysevent_t *, hrtime_t *);
 266 extern size_t sysevent_get_size(sysevent_t *);
 267 extern char *sysevent_get_pub(sysevent_t *);
 268 extern int sysevent_get_attr_list(sysevent_t *, nvlist_t **);
 269
 270 #endif  /* _KERNEL */
 271
 272 #ifdef  __cplusplus
 273 }
 274 #endif
 275
 276 #endif  /* _SYS_SYSEVENT_H */