DOC HOME SITE MAP MAN PAGES GNU INFO SEARCH PRINT BOOK
 
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:

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)
19 June 2005
© 2005 The SCO Group, Inc. All rights reserved.
OpenServer 5 HDK - June 2005