1ddi_log_sysevent(9F) Kernel Functions for Drivers ddi_log_sysevent(9F)
2
6 ddi_log_sysevent - log system event for drivers
7
9 #include <sys/ddi.h>
10 #include <sys/sunddi.h>
11 int ddi_log_sysevent(dev_info_t *dip, char *vendor,
15 char *class, char *subclass, nvlist_t *attr_list,
16 sysevent_id_t *eidp, int sleep_flag);
17
20 Solaris DDI specific (Solaris DDI).
21
23 dip A pointer to the dev_info node for this driver.
24 vendor A pointer to a string defining the vendor. Third-party
27 drivers should use their company's stock symbol (or simi‐
28 larly enduring identifier). Sun-supplied drivers should
29 use DDI_VENDOR_SUNW.
30 class A pointer to a string defining the event class.
33 subclass A pointer to a string defining the event subclass.
36 attr_list A pointer to an nvlist_t, listing the name-value
39 attributes associated with the event or NULL if there are
40 no such attributes for this event.
41 eidp The address of a sysevent_id_t structure in which the
44 event's sequence number and timestamp are returned if the
45 event is successfully queued. May be NULL if this infor‐
46 mation is not of interest. See below for the definition
47 of sysevent_id_t.
48 sleep_flag Indicates how a caller wants to handle the possibility of
51 resources not being available. If sleep_flag is
52 DDI_NOSLEEP, the caller does not care if the allocation
53 fails or the queue is full and can handle a failure
54 appropriately. If sleep_flag is DDI_SLEEP, the caller
55 wishes to have the allocation and queuing routines wait
56 for resources to become available.
57
60 The ddi_log_sysevent() function causes a system event, of the specified
61 class and subclass, to be generated on behalf of the driver and queued
62 for delivery to syseventd, the user-land sysevent daemon.
63 The publisher string for the event is constructed using the vendor name
66 and driver name, with the format:
67 "<vendor>:kern:<driver-name>"
69 The two fields of eidp, eid_seq and eid_ts, are sufficient to uniquely
74 identify an event.
75
77 The structure members of sysevent_id_t are:
78 uint64_t eid_seq; /* sysevent sequence number */
80 hrtime_t eid_ts; /* sysevent timestamp */
81
84 The ddi_log_sysevent() function returns:
85 DDI_SUCCESS The event has been queued for delivery successfully.
87 DDI_ENOMEM There is not enough memory to queue the system event
90 at this time. DDI_ENOMEM cannot be returned when
91 sleep_flag is DDI_SLEEP.
92 DDI_EBUSY The system event queue is full at this time.
95 DDI_EBUSY cannot be returned when sleep_flag is
96 DDI_SLEEP.
97 DDI_ETRANSPORT The syseventd daemon is not responding and events
100 cannot be queued or delivered at this time.
101 DDI_ETRANSPORT can be returned even when sleep_flag
102 is DDI_SLEEP.
103 DDI_ECONTEXT sleep_flag is DDI_SLEEP and the driver is running in
106 interrupt context.
107 ddi_log_sysevent supports the following data types:
111 DATA_TYPE_BYTE
112 DATA_TYPE_INT16
113 DATA_TYPE_UINT16
114 DATA_TYPE_INT32
115 DATA_TYPE_UINT32
116 DATA_TYPE_INT64
117 DATA_TYPE_UINT64
118 DATA_TYPE_STRING
119 DATA_TYPE_BYTE_ARRAY
120 DATA_TYPE_INT16_ARRAY
121 DATA_TYPE_UINT16_ARRAY
122 DATA_TYPE_INT32_ARRAY
123 DATA_TYPE_UINT32_ARRAY
124 DATA_TYPE_INT64_ARRAY
125 DATA_TYPE_UINT64_ARRAY
126
128 The ddi_log_sysevent() function can be called from user, interrupt, or
129 kernel context, except when sleep_flag is DDI_SLEEP, in which case it
130 cannot be called from interrupt context.
131
133 Example 1 Logging System Event with No Attributes
134 if (ddi_log_sysevent(dip, DDI_VENDOR_SUNW, "class", "subclass",
136 NULL, NULL, DDI_SLEEP) != DDI_SUCCESS) {
137 cmn_err(CE_WARN, "error logging system event\n");
138 }
139 Example 2 Logging System Event with Two Name/Value Attributes, an Inte‐
142 ger and a String
143 nvlist_t *attr_list;
145 sysevent_id_t eid;
146 if (nvlist_alloc(&attr_list, NV_UNIQUE_NAME_TYPE, KM_SLEEP) == 0)
148 {
149 err = nvlist_add_uint32(attr_list, int_name, int_value);
150 if (err == 0)
151 err = nvlist_add_string(attr_list, str_name, str_value);
152 if (err == 0)
153 err = ddi_log_sysevent(dip, DDI_VENDOR_SUNW,
154 "class", "subclass", attr_list, &eid, DDI_SLEEP);
155 if (err != DDI_SUCCESS)
156 cmn_err(CE_WARN, "error logging system event\n");
157 nvlist_free(attr_list);
158 }
159 Example 3 Use Timeout to Handle nvlist and System Event Resource Allo‐
162 cation Failures
163 Since no blocking calls are made, this example would be useable from a
166 driver needing to generate an event from interrupt context.
167 static int
170 xx_se_timeout_handler(xx_state_t *xx)
171 {
172 xx->xx_timeoutid = (xx_generate_event(xx) ?
173 timeout(xx_se_timeout_handler, xx, 4) : 0);
174 }
175 static int
177 xx_generate_event(xx_state_t *xx)
178 {
179 int err;
180 err = nvlist_alloc(&xx->xx_ev_attrlist, NV_UNIQUE_NAME_TYPE, 0);
182 if (err != 0)
183 return (1);
184 err = nvlist_add_uint32(&xx->xx_ev_attrlist,
185 xx->xx_ev_name, xx->xx_ev_value);
186 if (err != 0) {
187 nvlist_free(xx->xx_ev_attrlist);
188 return(1);
189 }
190 err = ddi_log_sysevent(xx->xx_dip, DDI_VENDOR_SUNW,
192 xx->xx_ev_class, xx->xx_ev_sbclass,
193 xx->xx_ev_attrlist, NULL, DDI_NOSLEEP);
194 nvlist_free(xx->xx_ev_attrlist);
195 if (err == DDI_SUCCESS || err == DDI_ETRANSPORT) {
196 if (err == DDI_ETRANSPORT)
197 cmn_err(CE_WARN, "cannot log system event\n");
198 return (0);
199 }
200 return (1);
201 }
202
205 syseventd(1M), attributes(5), nvlist_add_boolean(9F), nvlist_alloc(9F)
206 Writing Device Drivers
209SunOS 5.11 16 Jan 2006 ddi_log_sysevent(9F)