David, Jerry and the project team worked offline and we have revised
the man pages for quiesce(9E).
============================================================================
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_no_quiesce(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() 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 the ddi_get*(9F) and ddi_put*(9F) functions.
The driver must not create or tear down mappings, or call FMA
functions, or create/cancel callbacks.
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_no_quiesce() always returns DDI_SUCCESS. A driver can set its
devo_quiesce device function to ddi_no_quiesce() 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), ddi_get8(9F), ddi_put8(9F),
ddi_no_quiesce(9F), ddi_quiesce_not_supported(9F), dev_ops(9S),
timeout(9F), reboot(1M), uadmin(1M), uadmin(2),
============================================================================
Please review and send me additional comments, and I will revise it
further.
Thanks,
Sherry
--
Sherry Moore, Solaris Core Kernel http://blogs.sun.com/sherrym
