From 24ceb441c7c04cee6f3fd3faad4b875a7e09eafe Mon Sep 17 00:00:00 2001
From: Heinrich Schuchardt <xypron.glpk@gmx.de>
Date: Wed, 16 Dec 2020 12:15:49 +0100
Subject: [PATCH] doc: button command

Provide a description of the 'button' command.

Signed-off-by: Heinrich Schuchardt <xypron.glpk@gmx.de>
---
 doc/usage/button.rst | 64 ++++++++++++++++++++++++++++++++++++++++++++
 doc/usage/index.rst  |  1 +
 2 files changed, 65 insertions(+)
 create mode 100644 doc/usage/button.rst

diff --git a/doc/usage/button.rst b/doc/usage/button.rst
new file mode 100644
index 0000000000..ea41762757
--- /dev/null
+++ b/doc/usage/button.rst
@@ -0,0 +1,64 @@
+.. SPDX-License-Identifier: GPL-2.0+
+
+button command
+==============
+
+Synopsis
+--------
+
+::
+
+    button list
+    button <name>
+
+Description
+-----------
+
+The button command is used to retrieve the status of a button. To show the
+status of a button with name 'button1' you would issue the command
+
+::
+
+    button button1
+
+The status of the button is both written to the console as *ON* or *OFF* and
+set in the return value variable *$?* as 0 (true) or 1 (false). To retrieve
+the status of a button with name *button1* and to write it to environment
+variable *status1* you would execute the commands
+
+::
+
+    button button1
+    setenv status1 $?
+
+A list of all available buttons and their status can be displayed using
+
+::
+
+    button list
+
+If a button device has not been probed yet, its status will be shown as
+*<inactive>* in the list.
+
+Configuration
+-------------
+
+To use the button command you must specify CONFIG_CMD_BUTTON=y and enable a
+button driver. The available buttons are defined in the device-tree.
+
+Return value
+------------
+
+The variable *$?* takes the following values
+
++---+-----------------------------+
+| 0 | ON, the button is pressed   |
++---+-----------------------------+
+| 1 | OFF, the button is released |
++---+-----------------------------+
+| 0 | button list was shown       |
++---+-----------------------------+
+| 1 | button not found            |
++---+-----------------------------+
+| 1 | invalid arguments           |
++---+-----------------------------+
diff --git a/doc/usage/index.rst b/doc/usage/index.rst
index d0f5a9f26e..6c4b5b9240 100644
--- a/doc/usage/index.rst
+++ b/doc/usage/index.rst
@@ -12,4 +12,5 @@ Shell commands
    :maxdepth: 1
 
    bootmenu
+   button
    pstore