Add an apm interface to the tctrl(4) device found on SPARCbooks; currently

limited to power change events and battery status retrieval.

ok deraadt@ mickey@

1 files changed, 221 insertions, 3 deletions

diff --git a/share/man/man4/man4.sparc/tctrl.4 b/share/man/man4/man4.sparc/tctrl.4
index 7cf62ab154a..d1240106b35 100644
--- a/share/man/man4/man4.sparc/tctrl.4
+++ b/share/man/man4/man4.sparc/tctrl.4
@@ -1,4 +1,4 @@
-.\"     $OpenBSD: tctrl.4,v 1.6 2003/06/23 09:34:53 miod Exp $
+.\"     $OpenBSD: tctrl.4,v 1.7 2005/03/29 16:26:43 miod Exp $
 .\"
 .\" Copyright (c) 1999 Jason L. Wright (jason@thought.net)
 .\" All rights reserved.
@@ -24,7 +24,17 @@
 .\" ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 .\" POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd June 22, 2003
+.\" APM description:
+.\"
+.\"	Copyright (c) 1998 Marco S. Hyman
+.\"
+.\"	Permission to copy all or part of this material for any purpose is
+.\"	granted provided that the above copyright notice and this paragraph
+.\"	are duplicated in all copies.  THIS SOFTWARE IS PROVIDED ``AS IS''
+.\"	AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, WITHOUT
+.\"	LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
+.\"	FOR A PARTICULAR PURPOSE.
+.Dd March 29, 2005
 .Dt TCTRL 4 sparc
 .Os
 .Sh NAME
@@ -38,6 +48,7 @@ The
 driver provides control over many functions on the
 .Tn Tadpole SPARCbook
 3 series laptops, via their TS102 chip.
+.Pp
 The microcontroller is used to power the TFT display down when the
 laptop lid is closed and when the screen is blanked by the
 .Xr pninek 4
@@ -51,12 +62,219 @@ is also used to power the laptop off when the
 system call is used with the
 .Ar RB_POWERDOWN
 flag is set.
+.Pp
 The PCMCIA part of the controller is managed by the
 .Xr tslot 4
 driver.
+.Sh POWER MANAGEMENT INTERFACE
+The
+.Nm
+driver provides an interface which simulates the Advanced Power Management
+.Pq Tn APM
+BIOS functions encountered on some x86 hardware.
+The BIOS functions are translated into the appropriate microcontroller requests.
+Currently only battery level, AC connection, and charging status are available
+from the
+.Nm
+device.
+Suspend/resume and other power events are not yet supported.
+.Pp
+The
+.Nm
+driver implements the following
+.Xr ioctl 2
+calls.
+They are defined in
+.Aq Pa machine/apmvar.h .
+.Bl -tag -width Ds
+.\" .It Dv APM_IOC_STANDBY
+.\" .Em NOT YET SUPPORTED on sparc
+.\" .Pq Li "no parameters"
+.\" Request
+.\" .Dq standby
+.\" mode.
+.\" .It Dv APM_IOC_SUSPEND
+.\" .Em NOT YET SUPPORTED on sparc
+.\" .Pq Li "no parameters"
+.\" Request
+.\" .Dq suspend
+.\" mode.
+.It Dv APM_IOC_GETPOWER
+.Pq Li "struct apm_power_info"
+Request the current power state.
+The argument structure is as follows:
+.Bd -literal -offset indent
+struct apm_power_info {
+	u_char battery_state;
+	u_char ac_state;
+	u_char battery_life;
+	u_char spare1;
+	u_int minutes_left;
+	u_int spare2[6];
+};
+.Ed
+.Pp
+The following values are defined for
+.Va battery_state :
+.Bl -tag -width Ds
+.It Dv APM_BATT_HIGH
+Battery has a high state of charge.
+.It Dv APM_BATT_LOW
+Battery has a low state of charge.
+.It Dv APM_BATT_CRITICAL
+Battery has a critical state of charge.
+.It Dv APM_BATT_CHARGING
+Battery is not high, low, or critical and is currently charging.
+.It Dv APM_BATT_UNKNOWN
+Can not read the current battery state.
+.\" .It Dv APM_BATTERY_ABSENT
+.\" No battery installed.
+.El
+.Pp
+The following values are defined for
+.Va ac_state :
+.Bl -tag -width Ds
+.It Dv APM_AC_OFF
+External power not detected.
+.It Dv APM_AC_ON
+External power detected.
+.\" .It Dv APM_AC_BACKUP
+.\" Backup power in use.
+.\" .It Dv APM_AC_UNKNOWN
+.\" External power state unknown.
+.El
+.Pp
+The
+.Va battery_life
+value contains the estimated percentage of battery life available.
+100% indicates a full charge.
+.Pp
+The
+.Va minutes_left
+value is always -1,
+as the hardware does not provide an estimated number of minutes of
+battery life remaining.
+.\" .It Dv APM_IOC_NEXTEVENT
+.\" .Em NOT YET SUPPORTED on sparc
+.\" .Pq Li "struct apm_event_info"
+.\" The
+.\" .Tn APM
+.\" driver stores up to
+.\" .Dv APM_NEVENTS
+.\" events.
+.\" This was defined as 16 at the time this documentation was written.
+.\" If the event list is full when a new event is detected the new event is lost.
+.\" .Dv APM_IOC_NEXTEVENT
+.\" ioctl returns the next event on the list or
+.\" .Er EAGAIN
+.\" if the event list is empty.
+.\" The format of the returned event is:
+.\" .Bd -literal -offset indent
+.\" struct apm_event_info {
+.\"	u_int type;
+.\"	u_int index;
+.\"	u_int spare[8];
+.\" };
+.\" .Ed
+.\" where
+.\" .Va index
+.\" is a sequential count of events that can be used to check if any
+.\" events were lost and
+.\" .Va type
+.\" is one of:
+.\" .Pp
+.\" .Bl -tag -width Ds -offset indent -compact
+.\" .It Dv APM_STANDBY_REQ
+.\" .It Dv APM_SUSPEND_REQ
+.\" .It Dv APM_NORMAL_RESUME
+.\" .It Dv APM_CRIT_RESUME
+.\" .It Dv APM_BATTERY_LOW
+.\" .It Dv APM_POWER_CHANGE
+.\" .It Dv APM_UPDATE_TIME
+.\" .It Dv APM_CRIT_SUSPEND_REQ
+.\" .It Dv APM_USER_STANDBY_REQ
+.\" .It Dv APM_USER_SUSPEND_REQ
+.\" .It Dv APM_SYS_STANDBY_RESUME
+.\" .El
+.\" .It Dv APM_IOC_DEV_CTL
+.\" .Em NOT YET SUPPORTED on sparc
+.\" .Pq Li "struct apm_ctl"
+.\" Allows an application to directly set the
+.\" .Tm APM
+.\" operating mode.
+.\" The argument structure is as follows:
+.\" .Bd -literal -offset indent
+.\" struct apm_ctl {
+.\"	u_int dev;
+.\"	u_int mode;
+.\" };
+.\" .Ed
+.\" .Pp
+.\" .Va dev
+.\" indicates the device, typically
+.\" .Dv APM_DEV_ALLDEVS .
+.\" .Pp
+.\" .Va mode
+.\" indicates the desired operating mode.
+.\" Possible values are
+.\" .Bl -tag -compact -offset indent
+.\" .It Dv APM_SYS_READY
+.\" .It Dv APM_SYS_STANDBY
+.\" .It Dv APM_SYS_SUSPEND
+.\" .It Dv APM_SYS_OFF
+.\" .It Dv APM_LASTREQ_INPROG
+.\" .It Dv APM_LASTREQ_REJECTED
+.\" .El
+.It Dv APM_IOC_PRN_CTL
+.Pq Li "int"
+This
+.Xr ioctl 2
+controls message output by the
+.Nm
+driver when a power change event is detected.
+The integer parameter is one of:
+.Bl -tag -width Ds
+.It Dv APM_PRINT_ON
+All power change events result in a message.
+This is the normal operating mode for the driver.
+.It Dv APM_PRINT_OFF
+Power change event messages are suppressed.
+.It Dv APM_PRINT_PCT
+Power change event messages are suppressed unless the estimated
+battery life percentage changes.
+.El
+.\" .Pp
+.\" However, in no case will power status messages be displayed until the
+.\" battery life goes below the percentage in the
+.\" .Xr sysctl 8
+.\" state variable
+.\" .Dv machdep.apmwarn .
+.\" Setting
+.\" .Dv machdep.apmwarn
+.\" to zero disables all warnings regardless of the
+.\" .Dv APM_IOC_PRN_CTL
+.\" setting.
+.El
+.Sh FILES
+.Bl -tag -width /dev/apmctl
+.It Pa /dev/apm
+APM data device.
+May only be opened read-only.
+May be opened by multiple concurrent users.
+.It Pa /dev/apmctl
+APM control device.
+May be opened read-write or write-only.
+May only be opened by one user at a time.
+An attempt to open the file when in use will fail, returning
+.Er EBUSY .
+.El
 .Sh SEE ALSO
 .Xr reboot 2 ,
 .Xr intro 4 ,
 .Xr pninek 4 ,
 .Xr pnozz 4 ,
-.Xr tslot 4
+.Xr tslot 4 ,
+.Xr apm 8 ,
+.Xr apmd 8
+.Sh BUGS
+Not all power management functions of the microcontroller are supported.