NAME

envmon − Environment Monitor Board driver

DESCRIPTION

The envmon driver provides a character-device interface to the Environment Monitor Board (ENVMON).  Sometimes this board is also referred to as the EMB.  The ENVMON itself is responsible for the following:

—Monitoring and controlling the state of an external Uninterruptable Power Supply (UPS).  Monitoring of AC-FAIL and Low-Battery conditions is provided, along with control of AC output from the UPS. 

—Monitoring and controlling the state of one to four External Chassis’ (typically 3 plus a UPS).  Monitoring of AC-FAIL and Over-Temperature is provided, along with control of external chassis DC-power. 

—Monitoring the state of up to four Internal Chassis temperature sensors. 

—Monitoring and controlling the state of the Internal Power Supply (low-voltage, enable/disable). 

—Host notification, via VME Interrupt and VME-accessible status registers, of any AC-FAIL, Over-Temperature or UPS Low-battery conditions. 

—System reset, system power-off or UPS and external chassis power-off under host program control. 

—Automatic power-off of the system and/or UPS and external chassis, upon persistent Over Temperature condition. 

—Transition-module push-buttons and remotable contacts for system Reset and Abort interrupt. 

The envmon driver provides the following:

—Read access (via ioctl(2)) to the ENVMON status registers A and B, for determining UPS, External Chassis, and Temperature status. 

—Indirect or direct write access (via ioctl) to the ENVMON control register, for generating test interrupts, generating VME SYSRESET, signalling all external units (including UPS’) to turn off their power, or latching off internal and external power. 

—Synchronous notification (via select(2) and poll(2)) of exception conditions (first failure bit set in Status Register A). 

—Interface from uadmin(2) system call to ENVMON control register, to control system shutdown behavior. 

—Handling of ENVMON Abort switch interrupts, by trapping to the configured debugger (ROM or kdb). 

SYSTEM CALL INTERFACES

The following system calls and semantics are defined for the envmon interface:

Open/Close
Opening the device allows I/O from/to the resultant file descriptor. Only the super-user may open for write.

Upon success, open(2) returns a file descriptor.  On error, -1 is returned, and errno is set to indicate the error. 

[ENODEV]
The envmon driver is not configured. 

[ENXIO]
No envmon board is installed on the system. 

[EPERM]
Attempt to open for write by non super-user.

Issuing a close has no effect on the driver or the ENVMON, other than to disassociate the driver from the passed file descriptor. 

Read/Write
There is no direct read/write access provided by the driver. Such calls will return -1, with errno set to [ENODEV]. 

Ioctl

#include <sys/types.h>
#include <sys/envmon.h>
int ioctl (s, request, arg)
int s, request;
int ∗arg;
or
ushort ∗arg;
or
struct emb_stat ∗arg;

The following table shows the ioctl requests defined for the envmon driver; a description for each follows the table. 

For all commands other than EMBGETSTAT, the device must be open for writing. 

EMBGETSTAT
This request retrieves the current values of the A and B status registers (interrupt cause and external device type) into the emb_stat structure pointed to by arg.  The driver reads register A twice before returning its value, so any previously latched, but no longer existent failure bits are not presented.  Macros are provided, in envmon.h, to decode the bits of registers A and B.  The macros may be used as booleans, to determine the existence and nature of any failure conditions present, and/or to identify which devices are affected. 

EMBXTUOFF
This request causes the ENVMON to send the power-off signal to all attached external units.  If a UPS is attached, this should cause it to disengage its inverter and cease running on batteries, thus powering off the system and any other devices attached to the UPS. There may be no return from this operation.  It should only be used on a quiescent system.  It is recommended that this command be issued indirectly, via the EMBARM interface.  If an attached UPS was not running on batteries, the result of this command on the UPS is UPS-specific.  It may continue to run, until AC power is actually interrupted, at which time it would likely remove power to the system immediately.

EMBPWRDOWN
This request causes the ENVMON to turn off the system internal power supply, and also send the power-off signal to all attached external units.  The board latches itself in this state until physically reset by an operator. There is no return from this operation.  It should only be used on a quiescent system.  It is recommended that this command be issued indirectly, via the EMBARM interface.  See the CAVEATS section for other concerns regarding EMBPWRDOWN. 

EMBTESTINT
This request causes the ENVMON to generate a test interrupt to the system.  This should, in turn, cause any selecting or polling process to be awoken.  The copy of status register A returned by a subsequent EMBGETSTAT, however will not have the test interrupt bit set, as this will have been cleared by the interrupt service routine. 

EMBSYSRESET
This request causes the ENVMON to generate a VME SYSRESET signal on the VME bus. There is no return from this operation.  It should only be used in emergencies on a quiescent system. 

EMBARM
This request exploits a hook in the uadmin(2) interface in the kernel, causing it to call the envmon driver with the integer request pointed to by arg, just prior to entering its infinite loop.  This loop is normally entered when a system halt is requested with an invocation of the command:

uadmin  x  0
(or the equivalent system call uadmin(x, AD_HALT)).

If x is A_SHUTDOWN [2], all processes are killed, and the root filesystem unmounted before the envmon request is executed.  This indirect method of executing the EMBXTUOFF, EMBPWRDOWN, or EMBSYSRESET commands should be used to ensure that root is umounted prior to system power-down or reset.  It is primarily designed to be used after an automatic shutdown due to an over-temperature condition, or an AC power failure (when attached to a UPS).  If uadmin issues the EMBXTUOFF command when a UPS is attached (as indicated in status register B), it waits 10 seconds and then issues an EMBSYSRESET.  This is done in the event that an attached UPS ignores the power-off signal if AC power has returned.  By default, uadmin is not armed to execute any ENVMON command after an AD_HALT request, unless the emb_halt_pwrdown master.d parameter has been set (see the MASTER.D PARAMETERS section).  The EMBARM request has no affect on the uadmin behavior after an AD_BOOT or AD_IBOOT request.  This is controlled by the emb_boot_reset master.d parameter (see the MASTER.D PARAMETERS section). 

EMBDISARM
arg is unused and should be NULL.  This request causes uadmin to revert to the default response to an AD_HALT request, which is controlled by the emb_halt_pwrdown master.d parameter (see the MASTER.D PARAMETERS section). 

EMBWRTCMD
arg should be a pointer of type ushort.  This request writes the value pointed to by arg to the Command register of the ENVMON.  The value written must include the EMBENACMD bit if ENVMON interrupts are to be enabled. 

Upon success, ioctl(2) returns zero.  On error, -1 is returned, and errno is set to indicate the error. 

[EBADF]
A request other than EMBGETSTAT was made, but the device is not open for writing. 

[ENXIO]
An EMBXTUOFF or EMBPWRDOWN was requested, but the transition module was not connected. 

[EFAULT]
arg points to an invalid or protected part of the process address space. 

Select
It is possible to select on an envmon file descriptor for exception conditions.  As long as there are no bits set in Status Register A, select will sleep (the length is controlled by the timeout argument; see select(2)).  When the ENVMON interrupts due to a power, temperature, or test interrupt, select will return an FD_SET indicating that the envmon file descriptor has an exception condition pending, the nature of which can be read with the EMBGETSTAT ioctl request.  Whenever any bit is set in Status register A, select will return immediately.  Thus, select cannot be used to wait for new exception conditions (one bits), unless all previous exceptions have been cleared (and Register A has returned to 0).  Also, select cannot be used to wait for an exception condition to be cleared.  Once an exception condition has been raised, it is necessary to poll for status changes, using EMBGETSTAT.  NOTE:  On temperature-sensor conditions, the ENVMON can interrupt thousands of times while a sensor crosses through or hovers near its threshold temperature.  The driver attempts to de-bounce this effect by disabling ENVMON interrupts for 10 seconds whenever an interrupt is received.  It is possible, however, for a select to return an FD_SET indicating an exception condition, but for that condition to not exist when an EMBGETSTAT is performed, or to exist for random EMBGETSTAT requests.  This may continue indefinitely until the temperature rises sufficiently above the threshold value to stabilize the register A contents. 

Poll
It is also possible to poll an envmon file descriptor for out-of-band data similar to using select for exception conditions.  Use POLLRDBAND as the requested event. 

Driverinfo
The envmon driver includes a driverinfo(D2DK) routine that implements the DXGETEDT command.  Although, strictly speaking, the envmon driver does not support subdevices, it does report extended EDT information for the devices connected to the transition module.  The "devices" are numbered 1 through 4 corresponding to the connector numbers on the transition module.  The device types are determined by the state of pins 3 and 4 of the connectors.  If pin 3 is grounded then "external-disk-chassis" is returned in the xedt structure; if pin 4 is grounded then "UPS" is returned.  If both pins 3 and 4 are grounded then "problem-with-device" is returned.  The number of extended EDT entries is equal to the number of connected devices that either indicate "external-disk-chassis", "UPS" or "problem-with-device" based on the state of pins 3, 4 and 5. 

MASTER.D PARAMETERS

The following may be set in the /etc/master.d/envmon file. 

emb_boot_reset
When set to 1, the EMBSYSRESET command will be sent to the ENVMON whenever uadmin(1M) or uadmin(2) is invoked to do the BOOT or IBOOT function.  This parameter is set to 1 by default. 

emb_halt_pwrdown
When set to 1, the EMBPWRDOWN command will be sent to the ENVMON whenever uadmin(1M) or uadmin(2) is invoked to do the HALT function.  When set to 0, the ENVMON is not, by default, sent any command in response to the HALT request. This parameter is set to 0 by default.  The default behavior is overidden by invoking the EMBARM ioctl to specify the ENVMON command to be sent.  Invoking the EMBDISARM ioctl reverts to the default behavior as controlled by emb_halt_pwrdown. 

MESSAGES

The following messages are printed for the EMBSYSRESET, EMBXTUOFF, and the EMBPWRDOWN commands:

ENVMON: Asserting VME SYSRESET.
This message is printed when the EMBSYSRESET command is sent to the ENVMON. 

ENVMON: Shutting off external devices.
This message is printed when the EMBXTUOFF command is sent to the ENVMON. 

ENVMON: Shutting off internal power.
This message is printed when the EMBPWRDOWN command is sent to the ENVMON. 

CAVEATS

The driver disables ENVMON interrupts for 10 seconds following any interrupt (except ABORT).  During this 10 second interval all ENVMON interrupts are disabled, including ABORT.  The purpose of this delay is to compensate for the lack of any hysteresis in the temperature sensors. 

When executing a EMBPWRDOWN request, the ENVMON logic expects power to be removed; therefore it also asserts the VME AC-FAIL and SYSRESET lines.  Thus, this command will effect a system reset, even if the ENVMON is not connected to the internal power-supply or any external units.  This command should not be executed unless the ENVMON is properly connected to the internal power supply.  Otherwise, the system will reboot automatically with the external power-off signal asserted (and latched), and any connected disk-drive chassis would be inhibited from powering up.  Also, if a UPS were attached which ignored this signal while AC was present, it would remove system power immediately, when an AC failure occured. 

Once a UPS power-fail or Over-Temperature condition is raised, there is a finite amount of time available before the UPS or ENVMON will remove power from the system.  In the case of an AC-failure, the UPS will power down the system when its batteries are exhausted, or possibly earlier if so programmed.  Similarly, the ENVMON will cut power after a fixed timeout when Over-Temperature occurs. 

The AC-fail or Over-Temperature conditions may occur in any order, so user programs that detect one condition and set a grace-period timer must monitor ENVMON status during the timing interval, since the Over-Temp and battery life time constants will differ.  If the condition with the smaller timeout occurs second,  the UPS or ENVMON could unexpectedly and ungracefully cause a power-down. 

NOTES

The environmental monitor board is supported on the m88k architecture only. 

FILES

/dev/envmon_c0
/etc/master.d/envmon
/usr/include/sys/envmon.h

SEE ALSO

prtconf(1M), intro(2), poll(2), select(2), sysm88k(2)

Environment Monitor Board Set User Guide (ENVMON/D1)