.\"     $OpenBSD: tctrl.4,v 1.9 2007/05/31 19:19:56 jmc Exp $
.\"
.\" Copyright (c) 1999 Jason L. Wright (jason@thought.net)
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
.\" DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT,
.\" INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
.\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
.\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
.\" ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
.\" 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 $Mdocdate: May 31 2007 $
.Dt TCTRL 4 sparc
.Os
.Sh NAME
.Nm tctrl
.Nd Tadpole Microcontroller Interface
.Sh SYNOPSIS
.Cd "tctrl0 at obio0"
.Sh DESCRIPTION
The
.Nm
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
or
.Xr pnozz 4
driver.
The
.Nm tctrl
is also used to power the laptop off when the
.Xr reboot 2
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 apm 8 ,
.Xr apmd 8
.Sh BUGS
Not all power management functions of the microcontroller are supported.