ddi_get_devstate(9F)

NAME

     ddi_get_devstate - Check device state

SYNOPSIS

     #include <sys/ddi.h>
     #include <sys/sunddi.h>

     ddi_devstate_t ddi_get_devstate(dev_info_t *dip);

INTERFACE LEVEL

     Solaris DDI specific (Solaris DDI)

PARAMETERS

     dip   Pointer to the device's dev_info structure

DESCRIPTION

     The ddi_get_devstate() function returns a  value  indicating
     the  state  of the device specified by  dip, as derived from
     the configuration operations that have been performed on  it
     (or  on  the  bus on which it resides) and any fault reports
     relating to it.

RETURN VALUES

     DDI_DEVSTATE_OFFLINE
           The device is offline.   In  this  state,  the  device
           driver  is  not  attached,  nor  will  it  be attached
           automatically. The device cannot be used until  it  is
           brought online.

     DDI_DEVSTATE_DOWN
            The device is online but unusable due to a fault.

     DDI_DEVSTATE_QUIESCED
            The  bus  on  which  the  device  resides  has   been
           quiesced.  This  is  not a fault, but no operations on
           the device should be performed while the  bus  remains
           quiesced.

     DDI_DEVSTATE_DEGRADED
            The device is online but only able to provide a  par-
           tial or degraded service, due to a fault.

     DDI_DEVSTATE_UP
            The device is online and fully operational.

CONTEXT

     The ddi_get_devstate() function may  be  called  from  user,
     kernel, or interrupt context.

NOTES

     A device driver should call this function to check  its  own
     state  at  each  major  entry  point,  and before committing
     resources to a requested operation.  If a  driver  discovers
     that  its device is already down, it should perform required
     cleanup  actions  and  return  as  soon  as  possible.    If
     appropriate,  it should return an error to its caller, indi-
     cating that the device has failed (for example,  a  driver's
     read(9E) routine would return EIO).

     Depending on the driver, some non-I/O operations (for  exam-
     ple,  calls  to  the  driver's  ioctl(9E) routine) may still
     succeed; only functions which would require fully accessible
     and  operational  hardware will necessarily fail. If the bus
     on which the device resides  is  quiesced,  the  driver  may
     return  a  value  indicating the operation should be retried
     later  (for  example,  EAGAIN).   Alternatively,  for   some
     classes  of  device, it may be appropriate for the driver to
     enqueue the operation and service it once the bus  has  been
     unquiesced.    Note   that   not   all  busses  support  the
     quiesce/unquiesce operations, so this  value  may  never  be
     seen by some drivers.

SEE ALSO

     attach(9E),  ioctl(9E),  open(9E),  read(9E),  strategy(9E),
     write(9E), ddi_dev_report_fault(9F)