path: root/usr/src/man/man9f/ddi_log_sysevent.9f

'\" te
.\" Copyright (c) 2006, Sun Microsystems, Inc. All Rights Reserved.
.\" 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.
.\" 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.
.\" 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]
.TH DDI_LOG_SYSEVENT 9F "Jan 16, 2006"
.SH NAME
ddi_log_sysevent \- log system event for drivers
.SH SYNOPSIS
.LP
.nf
#include <sys/ddi.h>
#include <sys/sunddi.h>



\fBint\fR \fBddi_log_sysevent\fR(\fBdev_info_t *\fR\fIdip\fR, \fBchar *\fR\fIvendor\fR,
     \fBchar *\fR\fIclass\fR, \fBchar *\fR\fIsubclass\fR, \fBnvlist_t *\fR\fIattr_list\fR,
     \fBsysevent_id_t *\fR\fIeidp\fR, \fBint\fR \fIsleep_flag\fR);
.fi

.SH INTERFACE LEVEL
.sp
.LP
Solaris DDI specific (Solaris DDI).
.SH PARAMETERS
.sp
.ne 2
.na
\fB\fIdip\fR\fR
.ad
.RS 14n
A pointer to the \fBdev_info\fR node for this driver.
.RE

.sp
.ne 2
.na
\fB\fIvendor\fR\fR
.ad
.RS 14n
A pointer to a string defining the vendor. Third-party drivers should use their
company's stock symbol (or similarly enduring identifier). Sun-supplied drivers
should use \fBDDI_VENDOR_SUNW\fR.
.RE

.sp
.ne 2
.na
\fB\fIclass\fR\fR
.ad
.RS 14n
A pointer to a string defining the event class.
.RE

.sp
.ne 2
.na
\fB\fIsubclass\fR\fR
.ad
.RS 14n
A pointer to a string defining the event subclass.
.RE

.sp
.ne 2
.na
\fB\fIattr_list\fR\fR
.ad
.RS 14n
A pointer to an \fBnvlist_t\fR, listing the name-value attributes associated
with the event or NULL if there are no such attributes for this event.
.RE

.sp
.ne 2
.na
\fB\fIeidp\fR\fR
.ad
.RS 14n
The address of a \fBsysevent_id_t\fR structure in which the event's sequence
number and timestamp are returned if the event is successfully queued. May be
NULL if this information is not of interest. See below for the definition of
\fBsysevent_id_t\fR.
.RE

.sp
.ne 2
.na
\fB\fIsleep_flag\fR\fR
.ad
.RS 14n
Indicates how a caller wants to handle the possibility of resources not being
available. If \fIsleep_flag\fR is \fBDDI_NOSLEEP\fR, the caller does not care
if the allocation fails or the queue is full and can handle a failure
appropriately. If \fBsleep_flag\fR is \fBDDI_SLEEP\fR, the caller wishes to
have the allocation and queuing routines wait for resources to become
available.
.RE

.SH DESCRIPTION
.sp
.LP
The \fBddi_log_sysevent()\fR function causes a system event, of the specified
class and subclass, to be generated on behalf of the driver and queued for
delivery to \fBsyseventd\fR, the user-land \fBsysevent\fR daemon.
.sp
.LP
The publisher string for the event is constructed using the vendor name and
driver name, with the format:
.sp
.in +2
.nf
"\fI<vendor>\fR:kern:\fI<driver-name>\fR"
.fi
.in -2
.sp

.sp
.LP
The two fields of \fBeidp\fR, \fBeid_seq\fR and \fBeid_ts\fR, are sufficient to
uniquely identify an event.
.SH STRUCTURE MEMBERS
.sp
.LP
The structure members of \fBsysevent_id_t\fR are:
.sp
.in +2
.nf
     uint64_t   eid_seq;        /* sysevent sequence number */
     hrtime_t   eid_ts;         /* sysevent timestamp */
.fi
.in -2

.SH RETURN VALUES
.sp
.LP
The \fBddi_log_sysevent()\fR function returns:
.sp
.ne 2
.na
\fB\fBDDI_SUCCESS\fR\fR
.ad
.RS 18n
The event has been queued for delivery successfully.
.RE

.sp
.ne 2
.na
\fB\fBDDI_ENOMEM\fR\fR
.ad
.RS 18n
There is not enough memory to queue the system event at this time.
\fBDDI_ENOMEM\fR cannot be returned when \fIsleep_flag\fR is \fBDDI_SLEEP\fR.
.RE

.sp
.ne 2
.na
\fB\fBDDI_EBUSY\fR\fR
.ad
.RS 18n
The system event queue is full at this time. \fBDDI_EBUSY\fR cannot be returned
when \fIsleep_flag\fR is \fBDDI_SLEEP\fR.
.RE

.sp
.ne 2
.na
\fB\fBDDI_ETRANSPORT\fR\fR
.ad
.RS 18n
The \fBsyseventd\fR daemon is not responding and events cannot be queued or
delivered at this time. \fBDDI_ETRANSPORT\fR can be returned even when
\fIsleep_flag\fR is \fBDDI_SLEEP\fR.
.RE

.sp
.ne 2
.na
\fB\fBDDI_ECONTEXT\fR\fR
.ad
.RS 18n
\fIsleep_flag\fR is DDI_SLEEP and the driver is running in interrupt context.
.RE

.sp
.LP
\fBddi_log_sysevent\fR supports the following data types:
.br
.in +2
DATA_TYPE_BYTE
.in -2
.br
.in +2
DATA_TYPE_INT16
.in -2
.br
.in +2
DATA_TYPE_UINT16
.in -2
.br
.in +2
DATA_TYPE_INT32
.in -2
.br
.in +2
DATA_TYPE_UINT32
.in -2
.br
.in +2
DATA_TYPE_INT64
.in -2
.br
.in +2
DATA_TYPE_UINT64
.in -2
.br
.in +2
DATA_TYPE_STRING
.in -2
.br
.in +2
DATA_TYPE_BYTE_ARRAY
.in -2
.br
.in +2
DATA_TYPE_INT16_ARRAY
.in -2
.br
.in +2
DATA_TYPE_UINT16_ARRAY
.in -2
.br
.in +2
DATA_TYPE_INT32_ARRAY
.in -2
.br
.in +2
DATA_TYPE_UINT32_ARRAY
.in -2
.br
.in +2
DATA_TYPE_INT64_ARRAY
.in -2
.br
.in +2
DATA_TYPE_UINT64_ARRAY
.in -2
.SH CONTEXT
.sp
.LP
The \fBddi_log_sysevent()\fR function can be called from user, interrupt, or
kernel context, except when \fIsleep_flag\fR is \fBDDI_SLEEP\fR, in which case
it cannot be called from interrupt context.
.SH EXAMPLES
.LP
\fBExample 1 \fRLogging System Event with No Attributes
.sp
.in +2
.nf
    if (ddi_log_sysevent(dip, DDI_VENDOR_SUNW, "class", "subclass",
        NULL, NULL, DDI_SLEEP) != DDI_SUCCESS) {
        cmn_err(CE_WARN, "error logging system event\en");
    }
.fi
.in -2

.LP
\fBExample 2 \fRLogging System Event with Two Name/Value Attributes, an Integer
and a String
.sp
.in +2
.nf
nvlist_t    *attr_list;
sysevent_id_t   eid;

if (nvlist_alloc(&attr_list, NV_UNIQUE_NAME_TYPE, KM_SLEEP) == 0)
{
    err = nvlist_add_uint32(attr_list, int_name, int_value);
    if (err == 0)
        err = nvlist_add_string(attr_list, str_name, str_value);
    if (err == 0)
        err = ddi_log_sysevent(dip, DDI_VENDOR_SUNW,
          "class", "subclass", attr_list, &eid, DDI_SLEEP);
    if (err != DDI_SUCCESS)
        cmn_err(CE_WARN, "error logging system event\en");
    nvlist_free(attr_list);
    }
.fi
.in -2

.LP
\fBExample 3 \fRUse Timeout to Handle \fBnvlist\fR and System Event Resource
Allocation Failures
.sp
.LP
Since no blocking calls are made, this example would be useable from a driver
needing to generate an event from interrupt context.

.sp
.in +2
.nf
static int
    xx_se_timeout_handler(xx_state_t *xx)
    {
        xx->xx_timeoutid = (xx_generate_event(xx) ?
            timeout(xx_se_timeout_handler, xx, 4) : 0);
    }

    static int
    xx_generate_event(xx_state_t *xx)
    {
        int err;

        err = nvlist_alloc(&xx->xx_ev_attrlist, NV_UNIQUE_NAME_TYPE, 0);
        if (err != 0)
            return (1);
        err = nvlist_add_uint32(&xx->xx_ev_attrlist,
            xx->xx_ev_name, xx->xx_ev_value);
        if (err != 0) {
            nvlist_free(xx->xx_ev_attrlist);
            return(1);
        }

        err = ddi_log_sysevent(xx->xx_dip, DDI_VENDOR_SUNW,
            xx->xx_ev_class, xx->xx_ev_sbclass,
            xx->xx_ev_attrlist, NULL, DDI_NOSLEEP);
        nvlist_free(xx->xx_ev_attrlist);
        if (err == DDI_SUCCESS || err == DDI_ETRANSPORT) {
            if (err == DDI_ETRANSPORT)
                cmn_err(CE_WARN, "cannot log system event\en");
            return (0);
        }
        return (1);
    }
.fi
.in -2

.SH SEE ALSO
.sp
.LP
\fBsyseventd\fR(1M), \fBattributes\fR(5), \fBnvlist_add_boolean\fR(9F),
\fBnvlist_alloc\fR(9F)
.sp
.LP
\fIWriting Device Drivers\fR