test

Writing Device Drivers

Access Attributes Structure

A DDI_FM_ACCCHK_CAPABLE device driver must set its access attributes to indicate that it is capable of handling programmed I/O (PIO) access errors that occur during a register read or write. The devacc_attr_access field in the ddi_device_acc_attr(9S) structure should be set as an indicator to the system that the driver is capable of checking for and handling data path errors. The ddi_device_acc_attr structure contains the following members:

ushort_t devacc_attr_version;
uchar_t devacc_attr_endian_flags;
uchar_t devacc_attr_dataorder;
uchar_t devacc_attr_access;             /* access error protection */

Errors detected in the data path to or from a device can be processed by one or more of the device driver's nexus parents.

The devacc_attr_version field must be set to at least DDI_DEVICE_ATTR_V1. If the devacc_attr_version field is not set to at least DDI_DEVICE_ATTR_V1, the devacc_attr_access field is ignored.

The devacc_attr_access field can be set to the following values:

DDI_DEFAULT_ACC

This flag indicates the system will take the default action (panic if appropriate) when an error occurs. This attribute cannot be used by DDI_FM_ACCCHK_CAPABLE drivers.

DDI_FLAGERR_ACC

This flag indicates that the system will attempt to handle and recover from an error associated with the access handle. The driver should use the techniques described in Defensive Programming Techniques for Solaris Device Drivers and should use ddi_fm_acc_err_get(9F) to regularly check for errors before the driver allows data to be passed back to the calling application.

The DDI_FLAGERR_ACC flag provides:

  • Error notification via the driver callback

  • An error condition observable via ddi_fm_acc_err_get(9F)

DDI_CAUTIOUS_ACC

The DDI_CAUTIOUS_ACC flag provides a high level of protection for each Programmed I/O access made by the driver.

Note –

Use of this flag will cause a significant impact on the performance of the driver.

The DDI_CAUTIOUS_ACC flag signifies that an error is anticipated by the accessing driver. The system attempts to handle and recover from an error associated with this handle as gracefully as possible. No error reports are generated as a result, but the handle's fme_status flag is set to DDI_FM_NONFATAL. This flag is functionally equivalent to ddi_peek(9F) and ddi_poke(9F).

The use of the DDI_CAUTIOUS_ACC provides:

  • Exclusive access to the bus

  • On trap protection - (ddi_peek() and ddi_poke())

  • Error notification through the driver callback registered with ddi_fm_handler_register(9F)

  • An error condition observable through ddi_fm_acc_err_get(9F)

Generally, drivers should check for data path errors at appropriate junctures in the code path to guarantee consistent data and to ensure that proper error status is presented in the I/O software stack.

DDI_FM_ACCCHK_CAPABLE device drivers must set their devacc_attr_access field to DDI_FLAGERR_ACC or DDI_CAUTIOUS_ACC.