Go to main content

man pages section 9: DDI and DKI Kernel Functions

Exit Print View

Updated: Thursday, June 13, 2019
 
 

usb_fm_error_log (9F)

Name

usb_fm_error_log - generic USB client drivers error event report API

Synopsis

#include <sys/fm/io/usb.h>

void usb_fm_error_log(dev_info_t *dip, usb_fm_process_type_t md,
     usb_fm_drv_err_t drv_err, usb_fm_svc_imp_t svc_imp,
     usb_fm_sub_sys_t sub_sys, ... /* name-value pair args */);

Parameters

dip

Pointer to the dev_info structure

md

Type of the driver error processing method

drv_err

Type of the driver error event

svc_imp

Service impact of the error on the driver

sub_sys

Device subsystem that is being accessed when error occurs

Interface Level

Solaris architecture specific (Solaris DDI)

Description

The name-value pair args variable argument list contains one or more (names, type, value pointer) nvpair tuples for non-array data_type_t types or one or more (name, type, number of elements, value pointer) tuples for data_type_t array types. The end of the argument list is specified by NULL.

The nvpair tuples should describe the error conditions for logging purposes. These are any information that will be useful for developers to quickly root cause and fix customer issues. The nvpair names do not need to be unique.

The svc_imp and sub_sys can be NULL if the value is not known or not applicable. dip and drv_err are required values.

Following are the three calling methods for processing an error:

USB_FM_LOG_ERROR

This method causes the USB framework to queue an encoded error for later processing in a thread safe manner. This function should be called right at the source where the error happens.

USB_FM_UPDATE_ERROR

This method updates the error information for the last error logged by the same thread. It is not possible to update earlier queued logs or errors from another thread.

USB_FM_POST_ERROR

This method immediately processes the last error queued in the same thread. It is not necessary to call this function for errors to be processed, but is recommended when errors need to be processed immediately. Uncorrectable errors are such examples. Logging any UNRECOVERABLE errors will be automatically set the driver health to UNHEALTHY.

The svc_imp and sub_sys values will override the corresponding information of the last logged error, unless NULL was passed in UPDATE or POST method. Any additional error information provided with the variable argument list will be appended to the last logged error. If svc_imp is NULL at the time of processing, the value will be inferred by the health of the driver. If the driver is HEALTHY, the default service impact is CORRECTABLE. Otherwise, it is UNCORRECTABLE.

Any queued error logged that was not processed by POST method will be automatically processed by an error reaper. The reaper will process the queued errors using the health of driver and other conditions to determine the svc_imp, if svc_imp is NULL.

The possible values of usb_fm_process_type_t are:

USB_FM_LOG_ERROR

Log an error in a queue

USB_FM_UPDATE_ERROR

Update the last queued logs or errors.

USB_FM_POST_ERROR

Post the last queued error immediately.

The possible values of the usb_fm_drv_err_t are:

USB_FM_DRV_ERR_UNKNOWN

Not a valid error event. This is a place for NULL.

USB_FM_DRV_ERR_ALLOC

Errors that are a direct result of memory allocation errors. This is a special version of external errors, with memory allocation specific information requested.

USB_FM_DRV_ERR_EXTERNAL

Errors of external functions. The external functions are typically DDI functions or driver class framework functions. The return error itself is not important unless it causes the driver an undesirable impact, such as failing to attach.

USB_FM_DRV_ERR_UNSUPPORTED

Driver detected a feature that was not supported.

USB_FM_DRV_ERR_PROTOCOL

Protocol errors are always caused by device itself. Examples are endpoints are not found or invalid device data or description are returned.

USB_FM_DRV_ERR_PIPE_STATE

Error situation that pipe is not in the state that it should be.

USB_FM_DRV_ERR_DEV_STATE

Error situation that device is not in the state that it should be.

USB_FM_DRV_ERR_TRANSFER

Errors in the usb bus transfer, such as CTRL, INTR, BULK, ISOC transfer errors.

USB_FM_DRV_ERR_STALL

STALL errors in the USB bus transfer.

USB_FM_DRV_ERR_REQUEST

Errors that usb device send an invalid request to usba framework or some bad request to the device driver.

USB_FM_DRV_ERR_POWER

Power setting errors in device driver, such as an invalid power level.

USB_FM_DRV_ERR_SOFTWARE

Errors are specifically due to software programming or configuration such as an invalid argument.

The possible values of the usb_fm_svc_imp_t are:

USB_FM_SVC_IMP_UNKNOWN

Not a valid service impact. This is a place holder for NULL.

USB_FM_SVC_IMP_CORRECTABLE

There is no impact.

USB_FM_SVC_IMP_CONFIG

Driver still runs without some configuration.

USB_FM_SVC_IMP_NONSUPPORT

Driver does not support this particular device.

USB_FM_SVC_IMP_UNCORRECTABLE

Service is unrecoverable and lost, which may cause data corruption. Driver health is set to unhealthy.

The possible values of the usb_fm_sub_sys_t are:

USB_FM_SUB_SYS_UNKNOWN

Not a valid sub-system. This is a place holder for NULL.

USB_FM_SUB_SYS_NONE

No device subsystem is being accessed.

USB_FM_SUB_SYS_DISK_BOT

USB Mass Storage Bulk-only transfer type.

USB_FM_SUB_SYS_DISK_CBI

USB Mass Storage CBI transfer type.

USB_FM_SUB_SYS_DISK_UAS

USB Mass Storage UAS transfer type.

Examples

Example 1 Log and Post Error
#include <sys/fm/io/usb.h>

attach(dev_info_t *dip, ddi_attach_cmd_t cmd)
{
   ...
   /*
    * Always log the error at the source. Optionally update
    * the error log if there is more useful information.
    */
   if (usb_get_dev_data(dip, &data) != 0) {
        usb_fm_err_log(dip, USB_FM_LOG_ERROR, USB_FM_DRV_ERR_EXTERNAL,
        USB_FM_SVC_IMP_CORRECTABLE, USB_FM_SUB_SYS_NONE,
        "Description", DATA_TYPE_STRING,
        "Unable to get the usb dev data"
        NULL);

      goto fail_attach;
   }
   ...
   fail_attach:
   /*
    * Update the "service impact" of the error if it is needed
    */
   usb_fm_err_log(dip, USB_FM_POST_ERROR, 0,
   USB_FM_SVC_IMP_UNCORRECTABLE, USB_FM_SUB_SYS_NONE,
      NULL);
   return (DDI_FAILURE);
}

Context

This function can only be called from kernel context.

Attributes

See attributes(7) for descriptions of the following attributes:

ATTRIBUTE TYPE
ATTRIBUTE VALUE
Interface Stability
Project Private

See Also

ddi_fm_init(9F), ddi_fm_ereport_post(9F), driver.conf(5), attributes(7)