Driver Entry Points                                   quiesce(9E)



NAME
     quiesce - quiesce a device

SYNOPSIS
     #include 
     #include 

     int prefixquiesce(devinfot *dip);


     int ddiquiescenotneeded(devinfot *dip);


INTERFACE LEVEL
     Solaris DI specific (Solaris DI)

PARAMETERS
     dip    A pointer to the device's devinfo structure.


DESCRIPTION
     The quiesce() function quiesces a device so that the  device
     no longer generates interrupts, modifies or accesses memory.
     The driver should reset the device to a hardware state  from
     which the device can be correctly configured by the driver's
     attach() routine without a system power cycle or being  con-
     figured  by  the  firmware. For devices with a defined reset
     state configuration, the driver should return that device to
     that  state  as  part of the quiesce operation. Fast Reboot,
     where firmware is bypassed when booting to a new  OS  image,
     is such a case.


     quiesce() is only called for an attached device instance  as
     one  of  the  final  operations of a reboot sequence, and no
     other thread can be  active  for  this  device.  The  system
     guarantees  that  no  other  driver entry point is active or
     invoked while quiesce() is invoked. The system also  guaran-
     tees  that  no  timeout  or  taskq is invoked. The system is
     single-threaded and can not be interrupted.  Therefore,  the
     driver's  quiesce()  implementation  must  not  use locks or
     timeouts, or rely on them being called. The driver must dis-
     card  all outstanding I/O instead of waiting for completion.
     At the conclusion of the  quiesce()  operation,  the  driver
     must  guarantee  that  the  device  no  longer has access to
     memory or interrupts.


     The only DI interfaces that can be called by the  quiesce()
     implementation  are  non-blocking  functions,  such  as  the
     ddiget*() and ddiput*() functions.




SunOS 5.11          Last change: 16 Sep 2008                    1






Driver Entry Points                                   quiesce(9E)



     If quiesce() determines a particular instance of the  device
     cannot  be  quiesced  when  requested because of some excep-
     tional condition, quiesce() returns DIFAILURE. This rarely
     happens.


     If a driver has previously implemented the obsolete  reset()
     interface,  its functionality must be merged into quiesce().
     The driver's reset() routine  is  no  longer  called  if  an
     implementation of quiesce() is present.


     ddiquiescenotneeded()  always  returns   DISUCES.   A
     driver   can   set   its  devoquiesce  device  function  to
     ddiquiescenotneeded() to  indicate  that  the  device  it
     manages does not need to be quiesced.

RETURN VALUES
     quiesce() returns the following:

     DISUCES    The device has been successfully quiesced.


     DIFAILURE    The operation failed.


CONTEXT
     This function is called from kernel context only.

SEE ALSO
     reboot(1M), uadmin(1M), uadmin(2),  attach(9E),  detach(9E),
     ddiaddintr(9F),   ddimapregs(9F),  pciconfigsetup(9F),
     timeout(9F), devops(9S)

NOTES
     When quiesce() is called,  the  system  is  single-threaded,
     therefore  the driver's quiesce() implementation must not be
     blocked. For example, the implementation must not create  or
     tear  down mappings, call FMA functions, or create or cancel
     callbacks.















SunOS 5.11          Last change: 16 Sep 2008                    2