cpr (7)

Name

cpr -- Suspend and resume module.

Synopsis

/kernel/misc/cpr

Availability

SUNWcpr

Description

cpr is a loadable module which is used to suspend and resume the whole system. You may wish to suspend a system to save power, or to temporarily power off for transport. It should not be used in place of a normal shutdown when performing any hardware reconfiguration or replacement. In order for resume to succeed, it is important that the hardware configuration remain the same. When the system is suspended, the entire system state is preserved in nonvolatile storage until a resume operation is conducted.

The principle way to suspend the system using this module is through the sys-suspend(1M) command. There are other utilities which may be installed on your system which will also access this module (such as uadmin(1M), uadmin(2), or the Power key and the Shift+Power key on a type 5 keyboard).

The module performs the following actions when suspending the system. The signal SIGFREEZE is first sent to all user threads and then the threads are stopped. The system is brought down to a uniprocessor mode for multiprocessor systems. Next, dirty user pages are swapped out to their backing storage device and all file systems are synchronized. All devices are made quiescent and system interrupts are disabled. To complete the system suspend, the kernel memory pages and remaining user pages are written to the root file system in a compressed form.

When the system is powered on again, essentially the reverse of the suspend procedure occurs. The kernel image is restored from the root file system by the bootstrapper /cprboot, interrupts and devices are restored to their previous state. Finally the user threads are rescheduled and SIGTHAW is broadcast to notify any interested processes of system resumption. Additional processors, if available, are restored and brought online. The system is now back to exactly the state prior to suspension.

In some cases the cpr module may be unable to perform the suspend operation. If a system contains additional devices outside the standard shipped configuration, it is possible that these additional devices may not support cpr. In this case, the suspend will fail and an error message will be displayed to that effect. These devices must be removed or its device drivers unloaded for suspend to work. Contact the device manufacturer to obtain a new version of device driver that supports cpr. A suspend may also fail when devices or processes are performing critical or time sensitive operations (e.g., real time operations). In this case the system will remain in its current running state. Messages reporting the failure will be displayed on the console and status returned to the caller. Once the system is successfully suspended the resume operation will always succeed barring external influences such as hardware reconfiguration or the like.

Some network based applications may fail across a suspend and resume cycle. This largely depends on the underlying network protocol and the applications involved. In general, applications that retry and automatically reestablish connections will continue to operate transparently on resume, those applications that do not, will likely fail.

The speed of suspend and resume can range from 15 seconds to around a minute, depending on the system speed, memory size, and load.

Files

/cprboot

  Special bootstrapper for cpr.

/.CPR

System state file.

/.cpr_generic_info

  sys-suspend control file.

/.cpr_defaultboot_info

sys-suspend control file.

Bugs

The signals SIGFREEZE and SIGTHAW are not properly implemented for the Solaris 2.4 release; these will be available in a later release. This should only be a concern for specially customized applications that need to perform additional tasks at suspend or resume time, of which none exist at the present time.

In extremely rare occasion the system may fail during the early stages of a resume. In this small window, it is theoretically possible to be stuck in a loop that the system does not resume and it does not boot normally. If you are in such a loop, get to the prom ok prompt via L1+A and enter the following command:

set-default boot-file

This will reset the system and allow it to boot normally.

Notes

For suspend/resume to work on multiprocessor platforms, it must be able to control all CPUs. It is recommended that no MP tests (such as sundiag CPU tests) are running when suspend is initiated because the suspend may be rejected, if it cannot shut off all CPUs.

Certain device operations such as tape or floppy disk activities are not resumable due to the nature of removable media. These activities are detected at suspend time, and must be stopped before suspend will complete successfully.

See Also

sys-suspend(1M), uadmin(1M), uadmin(2)

Modified

5 Jul 1994

mic (7)

Name

mic -- Multi-interface Chip driver.

Synopsis

#include <fcntl.h>
#include <sys/termios.h>
#include <sys/micro.h>

open("/dev/term/mic/a", mode);
open("/dev/term/mic/b", mode);
open("/dev/term/mic/ir", mode);

Availability

SUNWmic

Platform

SPARCstation Voyager

Description

The Multi-interface Chip (MIC) provides two asynchronous serial input/output channels. These channels provide high speed buffered serial I/O, with optional hardware flow control support. Baud rates from 110 to 115200 are supported.

The first channel can either be routed through an infra-red port of the "a" serial port. If the device is opened using the "ir" device, then the driver routes the first channel through the infra-red port. If the device is opened using the "a" device, the first channel is routed through the "a" serial port. You cannot use both the "a" port and the "ir" port simultaneously. the second channel (the "b" serial port) has no infra-red capability and may be used independently of the first channel.

The mic module is a loadable STREAMS driver that provides basic support for the MIC hardware, together with basic asynchronous communication support. The driver supports those termio(7) device control functions specified by flags in the c_cflag word of the termios structure, excluding HUPCL, CLOCAL, CIBAUD, CRTSCTS, and PAREXT. The driver does not support device control functions specified by flags in the c_iflag word of the termios structure. Specifically, the driver assumes that IGNBRK and IGNPAR are always set. All other termio(7) functions must be performed by STREAMS modules pushed atop the driver. When a device is opened, the ldterm(7) and ttcompat(7) STREAMS modules are automatically pushed on top of the stream, providing the standard termio(7) interface.

The infra-red port provides access to two different modes of modulation. The default mode is called pulse mode and is compatible with the Infra-red Data Association (IrDA) modulation and the Hewlett-Packard Serial Infra-red (SIR) modulation. The second modulation is called high frequency mode and is compatible with the Sharp Amplitude Shift Keying (ASK) modulation. The default modulation when using high frequency mode is 500 KHz.

The character-special devices /dev/term/mic/a and /dev/term/mic/b are used to access the two serial ports on the MIC chip.

The character-special device /dev/term/mic/ir is used to access the infra-red port of the chip.

IOCTLS

The standard set of termio ioctl() calls are supported by the mic driver.

Breaks can be generated by the TCSBRK, TIOCSBRK, and TIOCCBRK ioctl() calls.

The input and output line speeds may be set to any of the speeds supported by termio. The speeds cannot be set independently; when the output speed is set, the input speed is set to the same speed. To support higher speeds than defined in termio the two lowest speeds, B50 and B75, have been remapped to 96000 and 115200 baud respectively.

There are six ioctl() calls which are specific to the infra-red port and can only be used when the device has been opened in infra-red mode:

MIOCGETM_IR

Returns the current IR mode defined in micio.h.

MIOCSETM_IR

Takes an additional argument of the desired IR mode (defined in micio.h) and sets the port to this mode.

MIOCGETD_IR

Returns the current IR carrier divisor. The carrier frequency can be calculated from the divisor and the formula:

carrier frequency = 19660 / (4 (divisor + 1)) KHz

MIOCSETD_IR

Sets the current IR carrier divisor. The desired frequency can be set by using a divisor calculated by the following formula, where the frequency is specified in KHz:

divisor = 19660 / frequency / 4 - 1

MIOCSLPBK_IR

Set IR loopback mode. This enables the receiver during transmit, so that sent messages are also received through the IR port.

MIOCCLPBK_IR

Clears IR loopback mode.

There are two mic-specific ioctl() calls:

MIOCSLPBK

Set SCC loopback mode. This internally loops back transmitted messages within the channel.

MIOCCLPBK

Clear SCC loopback mode.

Errors

An open() will fail if:

ENXIO

The unit being opened does not exist.

EBUSY

The channel is in use by another serial protocol. Remember that both the "a" and "ir" ports use the same channel.

Files

/dev/term/mic/a

Asynchronous serial line using port a

/dev/term/mic/b

Asynchronous serial line using port b

/dev/term/mic/ir

Asynchronous serial infra-red line using the infra-red port.

Diagnostics

mic: Rx FIFO overflow

The mic's internal 64 character buffer overflowed before it could be serviced.

mic: Rx buffer full - draining

The driver's character input buffer overflowed before it could be serviced.

Notes

Currently hardware flow control is not implemented. The state of DCD, CTS, RTS, and DTR interface signals cannot be queried, nor can hardware flow control be enabled using the CRTSCTS flag in the c_cflag word of the termios structure.

See Also

tip(1), ports(1M), ioctl(2), open(2), ldterm(7), termio(7),
ttcompat(7)

Modified

6 Sep 1994

pm (7)

Name

pm -- Power Management driver

Synopsis

#include <sys/pm.h>
int ioctl(int fildes, int command, int arg);

Availability

SUNWpmu

Description

The Power Management driver provides an interface for applications to configure the devices within the system for power management. The interface is provided through ioctl(2) commands. The pm driver may be accessed using /dev/pm.

fildes is an open file descriptor that refers to the pm driver.

command determines the control function to be performed as described below.

arg represents additional information that is needed by this command. The type of arg depends upon the command, but it is generally an integer or a pointer to a command-specific data structure.

Command Functions

Unless configured by using the commands below, pm does not power manage devices by default. Note, however, that the pmconfig(1M) program is typically run at boot time, and by reading the power.conf(4) file will use the commands below to configure pm. Any devices configured for power management by pm will have their drivers loaded (if not already) and locked into memory until that device is unmanaged. Some devices may be able to fully operate at non-full power levels. Using the command PM_SET_POWER on

such a device allows this low power mode to become the normal (on) power level for that device. This mode of operation is distinct from the power managed mode of operation.

pm periodically searches the system for devices which it can power manage. A device will only be power managed when it is not in use (explained further below). When a power managed device is subsequently used, it will be automatically returned to normal power.

The pm model of power management is to view the system as a collection of devices. Each device is a collection of components; a component is the smallest power manageable unit. The devices, and the components within those devices that are power manageable, are dependent upon the implementation of their respective device drivers. A power manageable component has three states. It may be busy (in use), it may be idle (not in use but using normal power), or it may be power managed (not in use and not using normal power). The pm driver manages the component transition from the second to the third state. pm uses two factors to determine this transition: the component must have been idle for at least the threshold time; and the device to which the component belongs must satisfy any dependencies requirements.

A dependency is when a device requires another device to be power managed before it can be power managed. A device is considered to be power managed when all of its components are power managed. Note that dependencies occur on a per device basis; when a dependency exists, no components of a device may be managed unless all the components it depends upon are first managed.

For more information, see the Guide to Writing Device Drivers manual, attach(9e), detach(9e), and power(9e).

Thus the configuration of a device for power management is the setting of the threshold for any component that is to be managed and defining any dependencies for that device.

For all commands excluding PM_SCHEDULE, arg points to a structure of type pm_request defined in sys/pm.h:

typedef struct {
          char      *who;          /*device to configure*/
          int       select;        /* selects the component or
                                       dependent of the device*/
          int       level;         /*power or threshold level */

          char     *dependent;     /*hold name or dependent */
          int       size;           /size of dependent buffer 8?
} pm_request

The fields should contain the following data:

who is a pointer to the name of the device to be configured. The name must be in the format described in power.conf(4).

select is a non-negative integer specifying the component or dependent being configured. the numbering starts at zero.

level is a non-negative integer giving the threshold level in seconds or the desired power level.

dependent is a pointer to a buffer which contains or receives the name of a device on which this device has a dependency. It uses the same format as the first field.

size is the size of the dependent buffer.

Not all fields are used in each command. Upon error the commands will return -1, and set errno to the error condition specified below. The following error codes are common to all commands:

EFAULT:

   Bad address passed in as argument

ENODEV:
   Device is not power manageable, or device is not configured (use
   PM_SET_THRESHOLD command first).

ENXIO:

Invalid instance number (device not attached).

EPERM:

Permission denied. You must be root or console owner.

Error codes specific to a command will follow that command's description.

PM_SCHEDULE:

arg sets the period in seconds of pm device scans. A value of zero inhibits scans which stops any further components from being managed. A negative value is ignored. The ioctl returns the new (or current) period.

PM_GET_IDLE_TIME:

Using the fields who and select, this command returns the time in seconds since the component was last busy.

Error codes:

     EINVAL:

          Device component out of range.

PM_GET_NUM_CMPTS:

Using the field who, this command returns the number of components defined for this device.

PM_GET_THRESHOLD:

Using the fields who and select, this command returns the threshold level of the component.

Error codes:

     EINVAL:

          Device component out of range.

PM_SET_THRESHOLD:

  Using the fields who, select, and level, this command sets the threshold level
  of the component. It returns zero on success.

  Error codes:

     EINVAL:

          Device component out of range, or threshold value < 0.

PM_GET_POWER

Using the fields who and select, this command returns the current normal power level of the component.

Error codes:

     EINVAL:

          Device component out of range.

     EIO:

          Non-power manageable device (or properties are removed).

PM_SET_POWER:

Using the fields who, select, and level, this command sets the current normal power level of the component to the given power level.

Error codes:

EINVAL:

Device component out of range, or power level <= 0.

EIO:

Failed to power device or its parent or its dependents.

PM_GET_CUR_PWR:

Using the fields who and select, this command returns the current power level of the component.

Error codes:

     EINVAL:

          Device component out of range.

PM_GET_NUM_DEPS:

Using the field who, this command returns the number of dependents configured for this device.

PM_GET_DEP:

Using the fields who, select, level, and dependent, this command writes the name of the dependent into the buffer supplied by the dependent field.

Error codes:

EINVAL:

Dependent component out of range, or user buffer is too small for dependent name.

     EFAULT:

          Bad buffer address was given.

PM_ADD_DEP:

Using the fields who and dependent, this command adds the dependent to the device.

Error codes

     ENODEV:

          Device is non-power manageable or is not configured.

PM_REM_DEP:

Using the fields who and dependent, this command removes the dependent from the device.

Error codes:

ENODEV:

Device is non-power manageable or is not configured, or the device has no dependents.

PM_REM_DEVICE:

Using the field who, this command unmanages the device and returns the device to normal power, if it is not already.

PM_REM_DEVICES:

This command unmanages all devices and returns them to normal power.

Notes

To unload a power managed driver, the driver must first be unmanaged using PM_REM_DEVICE or PM_REM_DEVICES.

Currently it is not an error to remove a nonexistent dependent or add a repeated dependent. The pseudo driver will silently ignore the redundant command.

See Also

intro(2), ioctl(2), pmconfig(1M), power.conf(4), attach(9e),
detach(9e), power(9e)

Modified

5 Jul 1994

pmc (7)

Name

pmc -- Platform Management Chip driver.

Synopsis

#include <sys/pmcio.h>
int ioctl(int fildes, int command, int arg);

Availability

SUNWpmc

Platform

SPARCstation Voyager

Description

The Platform Management Chip driver provides a number of miscellaneous platform specific functions. Principally these are to provide power control for devices which cannot manage their own power control (see ddi_power(9f)) and to provide information about the connection status of the machine. Not all functions are supported on all platforms.

The user interface is provided through ioctl(2) commands. The pmc driver may be accessed using /dev/pmc. The system interface (to power manage devices) is provided by registering its power function (using the "platform-pm" property of the root node).

fildes is an open file descriptor that refers to the pmc driver.

command determines the control function to be performed as described below.

arg is not used and may be any value.

Command Functions

These functions fall into three categories: connection status, power control, and miscellaneous. Connection status can be used to find out whether the following devices are plugged in: keyboard, ethernet, and ISDN.

The power control function fontrols the removal of the platform power. Miscellaneous functions enable the reading of the digital to analog converter.

PMC_GET_KBD:

This command returns the connection status of the keyboard. When the keyboard is connected it will return PMC_KB_STAT, and zero when it is not connected.

PMC_GET_ENET:

This command returns the connection status of the ethernet. When the ethernet is connected it will return PMC_ENET_STAT, and zero when it is not connected.

PMC_GET_ISDN:

This command returns the connection status of the ISDN channels. The return value is a bit map of the connected channels: PMC_ISDN_ST0 for NT and PMC_ISDN_ST1 for TE.

PCM_GET_A2D:

This command returns the result of an eight bit analog to digital conversion. The meaning of the reading is platform specific.

PMC_POWER_OFF:

This command is only available to the super-user. It turns off all power to the system. Note that critical data may be lost if proper preparation prior to power removal is not performed.

The poll(2) interface is supported. It may be used to poll for connection status changes. A process wishing to detect such connection changes should use the POLLIN event flag. When ANY connection status changes, the poll(2) mechanism will be notified. It is up to the user to verify whether the connection status change is of interest.

Errors

EPERM

Must be privileged user to use PMC_POWER_OFF.

See Also

ddi_power(9f), intro(2), ioctl(2), open(2), pm(7), poll(2)

Modified

5 Oct 1994