Hi folks, The project team has resolved most issues offline with various parties. I have attached the updated versions of the specs reflecting the resolution. Please send me mail if you don't believe issues you raised have been addressed.
Scott Rotondo will be posting summary with regard to interaction between this project and PSARC 2008/195 "Validated Execution". Thanks much, Sherry -- Sherry Moore, Solaris Core Kernel http://blogs.sun.com/sherrym -------------- next part -------------- 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. -------------- next part -------------- Data Structures for Drivers dev_ops(9S) NAME dev_ops - device operations structure SYNOPSIS #include <sys/conf.h> #include <sys/devops.h> INTERFACE LEVEL Solaris DDI specific (Solaris DDI). DESCRIPTION dev_ops contains driver common fields and pointers to the bus_ops and cb_ops(9S). Following are the device functions provided in the device operations structure. All fields must be set at compile time. devo_rev Driver build version. Set this to DEVO_REV. devo_refcnt Driver reference count. Set this to 0. devo_getinfo Get device driver information (see getinfo(9E)). devo_identify This entry point is obsolete. Set to nulldev. devo_probe Probe device. See probe(9E). devo_attach Attach driver to dev_info. See attach(9E). devo_detach Detach/prepare driver to unload. See detach(9E). devo_reset Reset device. (Not supported in this release.) Set this to nodev. devo_cb_ops Pointer to cb_ops(9S) structure for leaf drivers. SunOS 5.11 Last change: 11 Apr 2003 1 Data Structures for Drivers dev_ops(9S) devo_bus_ops Pointer to bus operations structure for nexus drivers. Set this to NULL if this is for a leaf driver. devo_power Power a device attached to system. See power(9E). devo_quiesce Quiesce a device attached to system. See quiesce(9E). Can be set to ddi_quiesce_not_needed(9F) if the driver does not need to implement quiesce, or set to ddi_quiesce_not_supported(9F) if the driver cannot quiesce device to support fast-reboot. STRUCTURE MEMBERS int devo_rev; int devo_refcnt; int (*devo_getinfo)(dev_info_t *dip, ddi_info_cmd_t infocmd, void *arg, void **result); int (*devo_identify)(dev_info_t *dip); int (*devo_probe)(dev_info_t *dip); int (*devo_attach)(dev_info_t *dip, ddi_attach_cmd_t cmd); int (*devo_detach)(dev_info_t *dip, ddi_detach_cmd_t cmd); int (*devo_reset)(dev_info_t *dip, ddi_reset_cmd_t cmd); struct cb_ops *devo_cb_ops; struct bus_ops *devo_bus_ops; int (*devo_power)(dev_info_t *dip, int component, int level); int (*devo_quiesce)(dev_info_t *dip); SEE ALSO attach(9E), detach(9E), getinfo(9E), probe(9E), power(9E), quiesce(9E), nodev(9F), ddi_quiesce_not_needed(9F), ddi_quiesce_not_supported(9F) -------------- next part -------------- System Administration Commands reboot(1M) NAME reboot - restart the operating system SYNOPSIS /usr/sbin/reboot [-dlnqf] [-e BE] [boot_arguments] DESCRIPTION The reboot utility restarts the kernel. The kernel is loaded into memory by the PROM monitor, which transfers control to the loaded kernel. On x86 systems, when the -f flag is specified, the running kernel will load the next kernel into memory, then transfers control to the loaded kernel. Although reboot can be run by the super-user at any time, shutdown(1M) is normally used first to warn all users logged in of the impending loss of service. See shutdown(1M) for details. The reboot utility performs a sync(1M) operation on the disks, and then a multi-user reboot is initiated. See init(1M) for details. On x86 systems, reboot may also update the boot archive as needed to ensure a successful reboot. The reboot utility normally logs the reboot to the system log daemon, syslogd(1M), and places a shutdown record in the login accounting file /var/adm/wtmpx. These actions are inhibited if the -n or -q options are present. Normally, the system reboots itself at power-up or after crashes. OPTIONS The following options are supported: -d Force a system crash dump before rebooting. See dumpadm(1M) for information on configuring system crash dumps. -e If -f is present, reboot to the specified boot environment (BE) as specified by live_upgrade(5). -f Fast reboot bypassing firmware and boot loader. The new kernel will be loaded into memory by the running kernel, and control will be transferred to the loaded kernel. If disk or kernel arguments are specified, they must be specified before other boot arguments. When -f is present, reboot(1M) accepts a special argument "dryrun" to check whether all the drivers in the system have implemented quiesce(9E). Currently only available on x86 system. See Example 3 for details. -l Suppress sending a message to the system log daemon, syslogd(1M) about who executed reboot. -n Avoid calling sync(2) and do not log the reboot to syslogd(1M) or to /var/adm/wtmpx. The kernel still attempts to sync filesystems prior to reboot, except if the -d option is also present. If -d is used with -n, the kernel does not attempt to sync filesystems. SunOS 5.11 Last change: 11 Apr 2005 1 System Administration Commands reboot(1M) -q Quick. Reboot quickly and ungracefully, without shut- ting down running processes first. OPERANDS The following operands are supported: boot_arguments An optional boot_arguments specifies argu- ments to the uadmin(2) function that are passed to the boot program and kernel upon restart. The form and list of arguments is described in the boot(1M) and kernel(1M) man pages.. If the arguments are speci- fied, whitespace between them is replaced by single spaces unless the whitespace is quoted for the shell. If the boot_arguments begin with a hyphen, they must be preceded by the -- delimiter (two hyphens) to denote the end of the reboot argument list. EXAMPLES Example 1 Passing the -r and -v Arguments to boot In the following example, the delimiter -- (two hyphens) must be used to separate the options of reboot from the arguments of boot(1M). example# reboot -dl -- -rv Example 2 Rebooting Using a Specific Disk and Kernel The following example reboots using a specific disk and ker- nel. example# reboot disk1 kernel.test/unix Example 3 Fast reboot Check if all the drivers on the system are fast reboot capable. example# reboot -f dryrun Rebooting to another UFS root disk. example# reboot -f -- '/dev/dsk/c1d0s0' Rebooting to another ZFS root pool. example# reboot -f -- 'rootpool/root1' Rebooting to "mykernel" on the same disk with "-k" option. example# reboot -f -- '/platform/i86pc/mykernel/amd64/unix -k' Rebooting to "mykernel" off another root disk mounted on /mnt. example# reboot -f -- '/mnt/platform/i86pc/mykernel/amd64/unix -k' Rebooting to "/platform/i86pc/kernel/$ISADIR/unix" on another boot environment named "second_root". example# reboot -f -e second_root Rebooting to the same kernel with "-kv" options. example# reboot -f -- '-kv' FILES /var/adm/wtmpx login accounting file ATTRIBUTES SunOS 5.11 Last change: 11 Apr 2005 2 System Administration Commands reboot(1M) See attributes(5) for descriptions of the following attri- butes: ____________________________________________________________ | ATTRIBUTE TYPE | ATTRIBUTE VALUE | |_____________________________|_____________________________| | Availability | SUNWcsu | |_____________________________|_____________________________| SEE ALSO mdb(1), boot(1M), dumpadm(1M), fsck(1M), halt(1M), init(1M), kernel(1M), shutdown(1M), sync(1M), syslogd(1M), sync(2), uadmin(2), reboot(3C), attributes(5) NOTES The reboot utility does not execute the scripts in /etc/rcnum.d or execute shutdown actions in inittab(4). To ensure a complete shutdown of system services, use shutdown(1M) or init(1M) to reboot a Solaris system. SunOS 5.11 Last change: 11 Apr 2005 3
