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