[PATCH v2 1/1] doc: button command

[PATCH v2 1/1] doc: button command

[Heinrich Schuchardt]

Provide a description of the 'button' command.

Signed-off-by: Heinrich Schuchardt <xypron.glpk@gmx.de>
---
v2:
	Replace ".. code-block::" by "::" as the build-system on Gitlab
	does not like code-block without language. The problem did not
	occur locally.
---
 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
--
2.29.2