usb_fm_error_log - generic USB client drivers error event report API
#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 */);
Pointer to the dev_info structure
Type of the driver error processing method
Type of the driver error event
Service impact of the error on the driver
Device subsystem that is being accessed when error occurs
Solaris architecture specific (Solaris DDI)
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:
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.
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.
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:
Log an error in a queue
Update the last queued logs or errors.
Post the last queued error immediately.
The possible values of the usb_fm_drv_err_t are:
Not a valid error event. This is a place for NULL.
Errors that are a direct result of memory allocation errors. This is a special version of external errors, with memory allocation specific information requested.
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.
Driver detected a feature that was not supported.
Protocol errors are always caused by device itself. Examples are endpoints are not found or invalid device data or description are returned.
Error situation that pipe is not in the state that it should be.
Error situation that device is not in the state that it should be.
Errors in the usb bus transfer, such as CTRL, INTR, BULK, ISOC transfer errors.
STALL errors in the USB bus transfer.
Errors that usb device send an invalid request to usba framework or some bad request to the device driver.
Power setting errors in device driver, such as an invalid power level.
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:
Not a valid service impact. This is a place holder for NULL.
There is no impact.
Driver still runs without some configuration.
Driver does not support this particular device.
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:
Not a valid sub-system. This is a place holder for NULL.
No device subsystem is being accessed.
USB Mass Storage Bulk-only transfer type.
USB Mass Storage CBI transfer type.
USB Mass Storage UAS transfer type.
#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);
}
This function can only be called from kernel context.
See attributes(7) for descriptions of the following attributes:
|
ddi_fm_init(9F), ddi_fm_ereport_post(9F), driver.conf(5), attributes(7)