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, ddi_quiesce_cmd_t cmd, void *arg);

     int ddi_no_quiesce(dev_info_t *dip, ddi_quiesce_cmd_t cmd, void *arg);

     int ddi_quiesce_not_supported(dev_info_t *dip, ddi_quiesce_cmd_t cmd,
	void *arg);


INTERFACE LEVEL
     Solaris DDI specific (Solaris DDI)

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


     cmd    Type of quiesce operation.  Currently only DDI_QUIESCE
	    is supported.

    
     arg    Argument to the quiesce routine if needed.  Can be set
	    to NULL.


DESCRIPTION
     The quiesce() function quiesces a device so that it will no longer
     generate interrupts or modify or access memory.  It should reset
     the device to a hardware state from which it can be correctly
     configured by the driver's attach() routine without a system power
     cycle or being configured by the firmware.  For devices that come
     with factory default settings, drivers must also restore such
     settings in its quiesce() routine.

  DDI_QUIESCE
     If cmd is set to DDI_QUIESCE, quiesce() is used to stop devices
     from generating interrupts or modify or access memory.  One such
     use case is Fast Reboot where firmware is bypassed when booting to
     a new OS image.

     The quiesce() function will be called once for each instance of
     the device for which there has been a successful attach().  The
     system guarantees that the function will only be called for a
     particular dev_info node after a successful attach(9E) of that
     device.  The system is not single-threaded when quiesce() is
     called, so the driver must ensure that concurrent accesses to the
     device when quiesce() is invoked is correctly coordinated.  The
     driver can choose to drop outstanding I/O instead of waiting for
     them to complete as long as it can guarantee on disk data
     integrity.  The driver must cancel any outstanding timeouts and
     remove outstanding tasks from taskqs before returning successfully
     from quiesce().

     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.

     For the fast reboot case, if DDI_FAILURE is returned for the
     DDI_QUIESCE cmd, regular reboot path will be taken.

     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.

RETURN VALUES
     DDI_SUCCESS    For DDI_QUIESCE, the device has been successfully
		    quiesced.

     DDI_FAILURE    The operation failed or the request  was  not
                    understood.


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)