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