From e96bd7fd3509f01e35b4bb2b69084954afeff387 Mon Sep 17 00:00:00 2001
From: kn <kn@openbsd.org>
Date: Fri, 3 Sep 2021 12:11:15 +0000
Subject: [PATCH] Document sleep button, lid status and lidaction/pwraction
 support

landry added the sensor back in 2013 and suspend via sleep button also works
(at least on ThinkPads).

`machdep.{lid,pwr}action' are super useful but only mentioned in
/etc/examples/wsconsctl.conf providing poor discovery.

acpibtn(4) is the most prominent driver supporting them, so document their
behaviour here as a reference point (`man -k .=lidaction' now shows it).

suspend/hibernate wording is taken from apm(8).
sysctl value list style is taken from sysctl(2)'s KERN_POOL_DEBUG.

Feedback jmc
---
 share/man/man4/acpibtn.4 | 60 ++++++++++++++++++++++++++++++++++------
 1 file changed, 51 insertions(+), 9 deletions(-)

diff --git a/share/man/man4/acpibtn.4 b/share/man/man4/acpibtn.4
index 7429b7a64a9..550490223d0 100644
--- a/share/man/man4/acpibtn.4
+++ b/share/man/man4/acpibtn.4
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: acpibtn.4,v 1.5 2013/07/16 16:05:48 schwarze Exp $
+.\"	$OpenBSD: acpibtn.4,v 1.6 2021/09/03 12:11:15 kn Exp $
 .\"
 .\" Copyright (c) 2006 Michael Knudsen <mk@openbsd.org>
 .\"
@@ -14,7 +14,7 @@
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
-.Dd $Mdocdate: July 16 2013 $
+.Dd $Mdocdate: September 3 2021 $
 .Dt ACPIBTN 4
 .Os
 .Sh NAME
@@ -25,17 +25,59 @@
 .Sh DESCRIPTION
 The
 .Nm
-driver is used to handle the event triggered when the user presses an ACPI
-button.
-Currently, the only event handled is the press of a power button which
-causes the system to perform a regular system shutdown and power off the
-machine if the
+driver handles events triggered by ACPI buttons.
+Currently, only power button, sleep button and lid status events are supported.
+.Pp
+The power button event is handled according to the
+.Va machdep.pwraction
+.Xr sysctl 8 .
+Valid values are:
+.Pp
+.Bl -tag -width 3n -offset indent -compact
+.It 0
+Do nothing.
+.It 1
+Perform a regular system shutdown and power off the machine if the
 .Va hw.allowpowerdown
+sysctl is set to 1.
+.It 2
+Put the system into suspend (deep sleep) state.
+.El
+.Pp
+The sleep button event puts the system into suspend (deep sleep) state.
+.Pp
+The lid status event is handled according to the
+.Va machdep.lidaction
+sysctl.
+Valid values are:
+.Pp
+.Bl -tag -width 3n -offset indent -compact
+.It 0
+Do nothing.
+.It 1
+Put the system into suspend (deep sleep) state.
+.It 2
+Put the system into hibernation.
+System memory is saved to disk (swap space)
+and the machine is powered down.
+For machines supporting the
+.Xr acpi 4
+style hibernate functionality, on resume a full kernel
+boot will occur, followed by the reading of the saved
+memory image.
+The image will then be unpacked and the system resumed
+at the point immediately after the hibernation request.
+.El
+.Pp
+The lid status is set up as a sensor and can be monitored using
 .Xr sysctl 8
-is set to 1.
+or
+.Xr sensorsd 8 .
 .Sh SEE ALSO
 .Xr acpi 4 ,
-.Xr intro 4
+.Xr intro 4 ,
+.Xr sensorsd 8 ,
+.Xr sysctl 8
 .Sh HISTORY
 The
 .Nm
-- 
2.20.1