usr/src/man/man9f/ddi_log_sysevent.9f

   1 '\" te
   2 .\" Copyright (c) 2006, Sun Microsystems, Inc. All Rights Reserved.
   3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   6 .TH DDI_LOG_SYSEVENT 9F "Jan 16, 2006"
   7 .SH NAME
   8 ddi_log_sysevent \- log system event for drivers
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 #include <sys/ddi.h>
  13 #include <sys/sunddi.h>
  14
  15
  16
  17 \fBint\fR \fBddi_log_sysevent\fR(\fBdev_info_t *\fR\fIdip\fR, \fBchar *\fR\fIvendor\fR,
  18      \fBchar *\fR\fIclass\fR, \fBchar *\fR\fIsubclass\fR, \fBnvlist_t *\fR\fIattr_list\fR,
  19      \fBsysevent_id_t *\fR\fIeidp\fR, \fBint\fR \fIsleep_flag\fR);
  20 .fi
  21
  22 .SH INTERFACE LEVEL
  23 .sp
  24 .LP
  25 Solaris DDI specific (Solaris DDI).
  26 .SH PARAMETERS
  27 .sp
  28 .ne 2
  29 .na
  30 \fB\fIdip\fR\fR
  31 .ad
  32 .RS 14n
  33 A pointer to the \fBdev_info\fR node for this driver.
  34 .RE
  35
  36 .sp
  37 .ne 2
  38 .na
  39 \fB\fIvendor\fR\fR
  40 .ad
  41 .RS 14n
  42 A pointer to a string defining the vendor. Third-party drivers should use their
  43 company's stock symbol (or similarly enduring identifier). Sun-supplied drivers
  44 should use \fBDDI_VENDOR_SUNW\fR.
  45 .RE
  46
  47 .sp
  48 .ne 2
  49 .na
  50 \fB\fIclass\fR\fR
  51 .ad
  52 .RS 14n
  53 A pointer to a string defining the event class.
  54 .RE
  55
  56 .sp
  57 .ne 2
  58 .na
  59 \fB\fIsubclass\fR\fR
  60 .ad
  61 .RS 14n
  62 A pointer to a string defining the event subclass.
  63 .RE
  64
  65 .sp
  66 .ne 2
  67 .na
  68 \fB\fIattr_list\fR\fR
  69 .ad
  70 .RS 14n
  71 A pointer to an \fBnvlist_t\fR, listing the name-value attributes associated
  72 with the event or NULL if there are no such attributes for this event.
  73 .RE
  74
  75 .sp
  76 .ne 2
  77 .na
  78 \fB\fIeidp\fR\fR
  79 .ad
  80 .RS 14n
  81 The address of a \fBsysevent_id_t\fR structure in which the event's sequence
  82 number and timestamp are returned if the event is successfully queued. May be
  83 NULL if this information is not of interest. See below for the definition of
  84 \fBsysevent_id_t\fR.
  85 .RE
  86
  87 .sp
  88 .ne 2
  89 .na
  90 \fB\fIsleep_flag\fR\fR
  91 .ad
  92 .RS 14n
  93 Indicates how a caller wants to handle the possibility of resources not being
  94 available. If \fIsleep_flag\fR is \fBDDI_NOSLEEP\fR, the caller does not care
  95 if the allocation fails or the queue is full and can handle a failure
  96 appropriately. If \fBsleep_flag\fR is \fBDDI_SLEEP\fR, the caller wishes to
  97 have the allocation and queuing routines wait for resources to become
  98 available.
  99 .RE
 100
 101 .SH DESCRIPTION
 102 .sp
 103 .LP
 104 The \fBddi_log_sysevent()\fR function causes a system event, of the specified
 105 class and subclass, to be generated on behalf of the driver and queued for
 106 delivery to \fBsyseventd\fR, the user-land \fBsysevent\fR daemon.
 107 .sp
 108 .LP
 109 The publisher string for the event is constructed using the vendor name and
 110 driver name, with the format:
 111 .sp
 112 .in +2
 113 .nf
 114 "\fI<vendor>\fR:kern:\fI<driver-name>\fR"
 115 .fi
 116 .in -2
 117 .sp
 118
 119 .sp
 120 .LP
 121 The two fields of \fBeidp\fR, \fBeid_seq\fR and \fBeid_ts\fR, are sufficient to
 122 uniquely identify an event.
 123 .SH STRUCTURE MEMBERS
 124 .sp
 125 .LP
 126 The structure members of \fBsysevent_id_t\fR are:
 127 .sp
 128 .in +2
 129 .nf
 130      uint64_t   eid_seq;        /* sysevent sequence number */
 131      hrtime_t   eid_ts;         /* sysevent timestamp */
 132 .fi
 133 .in -2
 134
 135 .SH RETURN VALUES
 136 .sp
 137 .LP
 138 The \fBddi_log_sysevent()\fR function returns:
 139 .sp
 140 .ne 2
 141 .na
 142 \fB\fBDDI_SUCCESS\fR\fR
 143 .ad
 144 .RS 18n
 145 The event has been queued for delivery successfully.
 146 .RE
 147
 148 .sp
 149 .ne 2
 150 .na
 151 \fB\fBDDI_ENOMEM\fR\fR
 152 .ad
 153 .RS 18n
 154 There is not enough memory to queue the system event at this time.
 155 \fBDDI_ENOMEM\fR cannot be returned when \fIsleep_flag\fR is \fBDDI_SLEEP\fR.
 156 .RE
 157
 158 .sp
 159 .ne 2
 160 .na
 161 \fB\fBDDI_EBUSY\fR\fR
 162 .ad
 163 .RS 18n
 164 The system event queue is full at this time. \fBDDI_EBUSY\fR cannot be returned
 165 when \fIsleep_flag\fR is \fBDDI_SLEEP\fR.
 166 .RE
 167
 168 .sp
 169 .ne 2
 170 .na
 171 \fB\fBDDI_ETRANSPORT\fR\fR
 172 .ad
 173 .RS 18n
 174 The \fBsyseventd\fR daemon is not responding and events cannot be queued or
 175 delivered at this time. \fBDDI_ETRANSPORT\fR can be returned even when
 176 \fIsleep_flag\fR is \fBDDI_SLEEP\fR.
 177 .RE
 178
 179 .sp
 180 .ne 2
 181 .na
 182 \fB\fBDDI_ECONTEXT\fR\fR
 183 .ad
 184 .RS 18n
 185 \fIsleep_flag\fR is DDI_SLEEP and the driver is running in interrupt context.
 186 .RE
 187
 188 .sp
 189 .LP
 190 \fBddi_log_sysevent\fR supports the following data types:
 191 .br
 192 .in +2
 193 DATA_TYPE_BYTE
 194 .in -2
 195 .br
 196 .in +2
 197 DATA_TYPE_INT16
 198 .in -2
 199 .br
 200 .in +2
 201 DATA_TYPE_UINT16
 202 .in -2
 203 .br
 204 .in +2
 205 DATA_TYPE_INT32
 206 .in -2
 207 .br
 208 .in +2
 209 DATA_TYPE_UINT32
 210 .in -2
 211 .br
 212 .in +2
 213 DATA_TYPE_INT64
 214 .in -2
 215 .br
 216 .in +2
 217 DATA_TYPE_UINT64
 218 .in -2
 219 .br
 220 .in +2
 221 DATA_TYPE_STRING
 222 .in -2
 223 .br
 224 .in +2
 225 DATA_TYPE_BYTE_ARRAY
 226 .in -2
 227 .br
 228 .in +2
 229 DATA_TYPE_INT16_ARRAY
 230 .in -2
 231 .br
 232 .in +2
 233 DATA_TYPE_UINT16_ARRAY
 234 .in -2
 235 .br
 236 .in +2
 237 DATA_TYPE_INT32_ARRAY
 238 .in -2
 239 .br
 240 .in +2
 241 DATA_TYPE_UINT32_ARRAY
 242 .in -2
 243 .br
 244 .in +2
 245 DATA_TYPE_INT64_ARRAY
 246 .in -2
 247 .br
 248 .in +2
 249 DATA_TYPE_UINT64_ARRAY
 250 .in -2
 251 .SH CONTEXT
 252 .sp
 253 .LP
 254 The \fBddi_log_sysevent()\fR function can be called from user, interrupt, or
 255 kernel context, except when \fIsleep_flag\fR is \fBDDI_SLEEP\fR, in which case
 256 it cannot be called from interrupt context.
 257 .SH EXAMPLES
 258 .LP
 259 \fBExample 1 \fRLogging System Event with No Attributes
 260 .sp
 261 .in +2
 262 .nf
 263     if (ddi_log_sysevent(dip, DDI_VENDOR_SUNW, "class", "subclass",
 264         NULL, NULL, DDI_SLEEP) != DDI_SUCCESS) {
 265         cmn_err(CE_WARN, "error logging system event\en");
 266     }
 267 .fi
 268 .in -2
 269
 270 .LP
 271 \fBExample 2 \fRLogging System Event with Two Name/Value Attributes, an Integer
 272 and a String
 273 .sp
 274 .in +2
 275 .nf
 276 nvlist_t    *attr_list;
 277 sysevent_id_t   eid;
 278
 279 if (nvlist_alloc(&attr_list, NV_UNIQUE_NAME_TYPE, KM_SLEEP) == 0)
 280 {
 281     err = nvlist_add_uint32(attr_list, int_name, int_value);
 282     if (err == 0)
 283         err = nvlist_add_string(attr_list, str_name, str_value);
 284     if (err == 0)
 285         err = ddi_log_sysevent(dip, DDI_VENDOR_SUNW,
 286           "class", "subclass", attr_list, &eid, DDI_SLEEP);
 287     if (err != DDI_SUCCESS)
 288         cmn_err(CE_WARN, "error logging system event\en");
 289     nvlist_free(attr_list);
 290     }
 291 .fi
 292 .in -2
 293
 294 .LP
 295 \fBExample 3 \fRUse Timeout to Handle \fBnvlist\fR and System Event Resource
 296 Allocation Failures
 297 .sp
 298 .LP
 299 Since no blocking calls are made, this example would be useable from a driver
 300 needing to generate an event from interrupt context.
 301
 302 .sp
 303 .in +2
 304 .nf
 305 static int
 306     xx_se_timeout_handler(xx_state_t *xx)
 307     {
 308         xx->xx_timeoutid = (xx_generate_event(xx) ?
 309             timeout(xx_se_timeout_handler, xx, 4) : 0);
 310     }
 311
 312     static int
 313     xx_generate_event(xx_state_t *xx)
 314     {
 315         int err;
 316
 317         err = nvlist_alloc(&xx->xx_ev_attrlist, NV_UNIQUE_NAME_TYPE, 0);
 318         if (err != 0)
 319             return (1);
 320         err = nvlist_add_uint32(&xx->xx_ev_attrlist,
 321             xx->xx_ev_name, xx->xx_ev_value);
 322         if (err != 0) {
 323             nvlist_free(xx->xx_ev_attrlist);
 324             return(1);
 325         }
 326
 327         err = ddi_log_sysevent(xx->xx_dip, DDI_VENDOR_SUNW,
 328             xx->xx_ev_class, xx->xx_ev_sbclass,
 329             xx->xx_ev_attrlist, NULL, DDI_NOSLEEP);
 330         nvlist_free(xx->xx_ev_attrlist);
 331         if (err == DDI_SUCCESS || err == DDI_ETRANSPORT) {
 332             if (err == DDI_ETRANSPORT)
 333                 cmn_err(CE_WARN, "cannot log system event\en");
 334             return (0);
 335         }
 336         return (1);
 337     }
 338 .fi
 339 .in -2
 340
 341 .SH SEE ALSO
 342 .sp
 343 .LP
 344 \fBsyseventd\fR(1M), \fBattributes\fR(5), \fBnvlist_add_boolean\fR(9F),
 345 \fBnvlist_alloc\fR(9F)
 346 .sp
 347 .LP
 348 \fIWriting Device Drivers\fR