Driver Entry Points                                    quiesce(9E)



NAME
     quiesce - quiesce a device

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

     int prefix quiesce(dev_info_t dip);

     int ddi_quiesce_not_needed(dev_info_t *dip);

     int ddi_quiesce_not_supported(dev_info_t *dip);


INTERFACE LEVEL
     Solaris DDI specific (Solaris DDI)

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

DESCRIPTION
     The quiesce() function quiesces a device so that the device will
     no longer generate interrupts or modify or access 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 configured 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.  One such use case is Fast Reboot where
     firmware is bypassed when booting to a new OS image.

     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 will be active or invoked quiesce(9E) is
     invoked.  The system also guarantees that no timeout or taskq will
     be invoked.  The system is single-threaded and not preemptable or
     interrupted, therefore the driver's quiesce() implementation must
     not use locks or timeouts or rely on them being called.  The
     driver must discard all outstanding I/O instead of waiting for
     completion.  By conclusion of the quiesce() operation, the driver
     must guarantee that device will not generate further access to
     memory or interrupts.

     The only DDI interfaces that can be called by the quiesce()
     implementation are non-blocking functions, such as ddi_get*(9F)
     and ddi_put*(9F).

     If quiesce() determines a particular instance of the device cannot
     be quiesced when requested because of some exceptional condition,
     quiesce() must return DDI_FAILURE.  This should almost never
     happen.

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

     ddi_quiesce_not_needed() always returns DDI_SUCCESS.  A driver can
     set its devo_quiesce device function to ddi_quiesce_not_needed()
     to indicate that the device it manages does not need to be
     quiesced.

     ddi_quiesce_not_supported() always returns DDI_FAILURE.  A driver
     can set its devo_quiesce device function to
     ddi_quiesce_not_supported() to indicate that either the device
     cannot be quiesced, or quiesce() has not been implemented.

RETURN VALUES
     DDI_SUCCESS    For quiesce(), the device has been successfully
		    quiesced.

     DDI_FAILURE    The operation failed.


CONTEXT
     This function is called from kernel context only.

ATTRIBUTES
     See attributes(5) for descriptions of the  following  attri-
     butes:



     ____________________________________________________________
    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    |_____________________________|_____________________________|
    | Interface Stability         | Committed                   |
    |_____________________________|_____________________________|


SEE ALSO
     attach(9E), detach(9E), ddi_add_intr(9F), ddi_map_regs(9F),
     pci_config_setup(9F), timeout(9F), reboot(1M), uadmin(1M),
     uadmin(2), ddi_quiesce_not_needed(9F),
     ddi_quiesce_not_supported(9F), dev_ops(9S)


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