[PATCH v4 6/8] docs/specs: Introduce the QEMU lid button documentation

[Leonid Bloch <lb.workbox@gmail.com>]

Signed-off-by: Leonid Bloch <lb.workbox@gmail.com>
---
 MAINTAINERS           |   5 ++
 docs/specs/button.rst | 131 ++++++++++++++++++++++++++++++++++++++++++
 docs/specs/index.rst  |   1 +
 3 files changed, 137 insertions(+)
 create mode 100644 docs/specs/button.rst

diff --git a/MAINTAINERS b/MAINTAINERS
index 90941519e3..42179aba95 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -3050,6 +3050,11 @@ F: docs/specs/acad.rst
 F: hw/acpi/acad*
 F: include/hw/acpi/acad.h
 
+Button
+M: Leonid Bloch <lb.workbox@gmail.com>
+S: Maintained
+F: docs/specs/button.rst
+
 Subsystems
 ----------
 Overall Audio backends
diff --git a/docs/specs/button.rst b/docs/specs/button.rst
new file mode 100644
index 0000000000..10e57a380e
--- /dev/null
+++ b/docs/specs/button.rst
@@ -0,0 +1,131 @@
+.. SPDX-License-Identifier: GPL-2.0-or-later
+
+========================
+Laptop Lid Button Device
+========================
+
+The button device provides laptop lid button state information to the guest via
+ACPI. Lid state is controlled via QMP commands, providing deterministic control
+for testing and migration safety.
+
+Configuration
+-------------
+
+The lid button device is created as an ISA device using ``-device button``.
+
+Properties
+~~~~~~~~~~
+
+``ioport`` (default: 0x53d)
+  I/O port base address for the lid button device register.
+
+ACPI Interface
+--------------
+
+The lid button device is exposed to the guest as an ACPI device with:
+
+* **HID**: ``PNP0C0D`` (Lid Device)
+* **Device Path**: ``\_SB.LID0``
+* **Notification Values**:
+
+  * ``0x80``: Status change (lid opened/closed)
+
+ACPI Methods
+~~~~~~~~~~~~
+
+``_LID`` (Lid Status)
+  Returns the current lid state (0 = closed, 1 = open).
+
+I/O Interface
+-------------
+
+The device uses a single I/O port register:
+
+* **Port**: ``ioport`` property value (default 0x53d)
+* **Size**: 1 byte
+* **Access**: Read-only
+
+Register Layout
+~~~~~~~~~~~~~~~
+
+**LIDS** (offset 0x00, 1 byte)
+  Current lid state:
+
+  * ``0x00``: Lid closed
+  * ``0x01``: Lid open
+
+QMP Commands
+------------
+
+The following QMP commands control the lid button state:
+
+``lid-button-set-state``
+  Set the lid button state.
+
+  * ``open``: Whether the lid is open (boolean)
+
+  Example::
+
+    -> { "execute": "lid-button-set-state",
+         "arguments": { "open": true }}
+    <- { "return": {} }
+
+``query-lid-button``
+  Query the current lid button state.
+
+  Example::
+
+    -> { "execute": "query-lid-button" }
+    <- { "return": { "open": true }}
+
+Examples
+--------
+
+Basic usage::
+
+  # Start VM with lid button
+  qemu-system-x86_64 -device button -qmp tcp:localhost:4444,server,wait=off
+
+  # From another terminal, set lid state via QMP:
+  echo '{"execute":"qmp_capabilities"}
+        {"execute":"lid-button-set-state",
+         "arguments":{"open":false}}' | \
+  nc -N localhost 4444
+
+Simulate closing lid::
+
+  # Start with lid open (default)
+  # Close the lid
+  echo '{"execute":"lid-button-set-state",
+         "arguments":{"open":false}}' | nc -N localhost 4444
+
+  # Later, open the lid
+  echo '{"execute":"lid-button-set-state",
+         "arguments":{"open":true}}' | nc -N localhost 4444
+
+Test suspend on lid close::
+
+  # Start VM with ACPI support
+  qemu-system-x86_64 -device button
+
+  # Close lid - guest OS should detect this and may suspend
+  echo '{"execute":"lid-button-set-state",
+         "arguments":{"open":false}}' | nc -N localhost 4444
+
+  # Open lid - guest OS should wake or detect lid open
+  echo '{"execute":"lid-button-set-state",
+         "arguments":{"open":true}}' | nc -N localhost 4444
+
+Combined with other laptop devices::
+
+  # Create a complete laptop environment
+  qemu-system-x86_64 -device battery -device acad -device button
+
+  # Simulate closing lid while on battery power
+  echo '{"execute":"battery-set-state",
+         "arguments":{"state":{"present":true,"charging":false,
+                               "discharging":true,"charge-percent":60}}}
+        {"execute":"ac-adapter-set-state",
+         "arguments":{"connected":false}}
+        {"execute":"lid-button-set-state",
+         "arguments":{"open":false}}' | nc -N localhost 4444
diff --git a/docs/specs/index.rst b/docs/specs/index.rst
index a19c75384c..54d8f5f7c5 100644
--- a/docs/specs/index.rst
+++ b/docs/specs/index.rst
@@ -24,6 +24,7 @@ guest hardware that is specific to QEMU.
    acpi_erst
    acad
    battery
+   button
    sev-guest-firmware
    fw_cfg
    fsi
-- 
2.54.0