SCO OpenServer

ups(D3oddi)

ups -- generic Uninterruptable Power Supply (UPS) driver

Synopsis

   #include <sys/ups.h>
   
   struct upssw {
   	void (LinePowerOK)(void);
   	void (LinePowerFailed)(int batteryLifeTime);
   	void (BatteriesCritical)(void);
   };
   

   extern void ()() ups_get_pwrdwn( void );
   extern void ()() ups_set_pwrdwn( void (user_pwrdwn)() );
   

   extern struct upssw upssw;
   extern struct upssw defupssw;

Description

The ups driver provides kernel functions for the three events that a UPS hardware-specific driver must handle:

LinePowerFailed: AC power is interrupted, and the UPS switches to batteries
LinePowerOK: AC power returns after a period of absence
BatteriesCritical: the UPS detects that there is only a short period of battery life available

A UPS driver must call the handler routines to inform the system of the state of the UPS. When one of these functions is called, it generates a Power Management (PM) event which is interpreted by the PM daemon, pwrd(ADM) under the control of the pwrevents(F) file. (The classname for these events is ups).

Two other functions handle notification that the operating system is ready to be powered off:

ups_get_pwrdwn: Define UPS callback routine to be called after every shutdown process.
ups_set_pwrdwn: Return address of currently defined UPS callback routine to be called at system shutdown"

Arguments

batteryLifeTime: Number of minutes of remaining battery life. Set to -1 if the lifetime is unknown.
user_pwrdwn: Pointer to the UPS callback function. This routine contains code to be called when AC power has failed and the system is running on batteries. The UPS is told when the system is ready to be powered off so that it can arrange to cut the power itself. Note that the operating system calls this routine during every shutdown process, not just during UPS shutdowns.

Return values

LinePowerOK( ), LinePowerFailed( ), and BatteriesCritical( ) do not return a value.

ups_set_pwrdwn( ) and ups_get_pwrdwn( ) return the address of the user_pwrdwn callback function. Exercise caution if this function returns a non-null value; this means that another driver is also trying to use this interface.

Usage

The routines are pointed to by members of the global upssw structure (defined in <sys/ups.h>): The ups switch table members address the following functions:

LinePowerOK: The UPS driver should call this routine when AC power has returned after a period of absence (that is, sometime after a call to LinePowerFailed). This call should also be made by the UPS driver from its init(D2oddi) routine to let the operating system know that the UPS is present.
LinePowerFailed: The UPS driver should call this routine when AC power is interrupted and the UPS switches to batteries.
The driver cannot depend on the operating system to shut down within the number of minutes specified. That is the responsibility of the BatteriesCritical routine.
BatteriesCritical: The UPS driver should call this routine when there is only a short period of battery life available. There should be sufficient time remaining for a graceful shutdown, so it should be called when there are approximately five minutes of battery life remaining. Note that this function can be called out of sequence: it is not necessary to call LinePowerFailed first. The driver can depend on the operating system to shut the system down in response to this call.
ups_set_pwrdwn: takes a pointer to a function, user_pwrdwn, as its only argument and returns the address of the function that was assigned in a previous call.

The upsstate global variable always contains a constant representing the current state of the UPS. The operating system will call the callback routine specified by user_pwrdwn during every shutdown process (not just during UPS shutdowns). This occurs after all disk activity has ceased so that power can be removed safely.

user_pwrdwn is called when AC power has failed and the system is running on batteries. The UPS is told when the system is ready to be powered off so that it can arrange to cut the power itself.

A UPS driver might perform the following actions in its user_pwrdwn routine:

If AC power is available, that is, the UPS is not running on batteries, user_pwrdwn takes no action. Instead, it returns and lets the system software continue the shutdown in the normal manner.
If AC power is down, that is, the UPS is running on batteries, user_pwrdwn shuts down the UPS. When the power supply is restored, the UPS automatically powers on, and the computer autoboots.
Any other necessary actions to take.

You must enable Power Management in the kernel, using mkdev pm, before this driver can be used.

Context and synchronization

LinePowerOK: Initialization
LinePowerFailed, BatteriesCritical: Interrupt context
UPS callback routine: Interrupt context in HDK Technical Reference

Hardware applicability

Systems cofigured with an APM BIOS.

Version applicability

oddi: 3, 3mp, 4, 4mp, 5, 5mp, 6, 6mp

References

pwr(HW), pwrd(ADM), pwrevents(F)