Add some help using the gpio commands at runtime

Last time I used the gpio commands I was somehow confused about the behaviour
of the 'gpio_get_value' command. So, I decided to add some doc for it. Here's
the result.

Signed-off-by: Juergen Beisert <jbe@pengutronix.de>
Signed-off-by: Sascha Hauer <s.hauer@pengutronix.de>

1 files changed, 61 insertions, 0 deletions

diff --git a/commands/gpio.c b/commands/gpio.c
index 2575c1e50e..2ae4cc6c9e 100644
--- a/commands/gpio.c
+++ b/commands/gpio.c
@@ -120,3 +120,64 @@ BAREBOX_CMD_START(gpio_direction_output)
 	BAREBOX_CMD_HELP(cmd_gpio_direction_output_help)
 BAREBOX_CMD_END
 
+/**
+@page gpio_for_users Runtime GPIO handling
+
+@section regular_gpio General usage information
+
+These commands are available if the symbol @b CONFIG_GENERIC_GPIO and
+@b CONFIG_CMD_GPIO are enabled in the Kconfig.
+
+@note All gpio related commands take a number to identify the pad. This
+number is architecture dependent. There may be no intuitional correlation
+between available pads and the GPIO numbers to be used in the commands. Due
+to this it's also possible the numbers change between @b barebox releases.
+
+@section gpio_dir_out Switch a pad into an output GPIO
+@verbatim
+gpio_direction_output <gpio_no> <initial_value>
+@endverbatim
+- @b gpio_no Architecture dependent GPIO number
+- @b initial_value Output value the pad should emit
+
+@note To avoid glitches on the pad's line, the routines will first setting up
+the pad's value and after that switching the pad itself to output (if the
+silicon is able to do so)
+
+@note If the pad is already configured into a non GPIO mode (if available)
+this command may fail (silently)
+
+@section gpio_dir_in Switch a pad into an input GPIO
+@verbatim
+gpio_direction_input <gpio_no>
+@endverbatim
+- @b gpio_no Architecture dependent GPIO number
+
+@note If the pad is already configured into a non GPIO mode (if available)
+this command may fail (silently)
+
+@section gpio_get_value Read in the value of an GPIO input pad
+@verbatim
+gpio_get_value <gpio_no>
+@endverbatim
+
+Reads in the current pad's line value from the given GPIO number. It returns
+the value as a shell return code. There is no visible output at stdout. You
+can check the return value by using "echo $?"
+
+@note If the return code is not '0' or '1' it's meant as an error code.
+
+@note If the pad is not configured for GPIO mode this command may fail
+(silently) and returns garbage
+
+@section gpio_set_value Set a new value to a GPIO output pad
+@verbatim
+gpio_set_value <gpio_no> <value>
+@endverbatim
+- @b gpio_no Architecture dependent GPIO number
+- @b value Output value the pad should emit
+
+Sets a new output @b value to the pad with GPIO number @b gpio_no
+
+@note If the pad is not configured for GPIO mode this command may fail (silently)
+*/