[PATCH 19/21] doc: rework and unify documentation for gpio commands
Robert Schwebel
r.schwebel at pengutronix.de
Mon Nov 1 04:33:52 EDT 2010
Signed-off-by: Robert Schwebel <r.schwebel at pengutronix.de>
---
Documentation/commands.dox | 5 ++-
Documentation/users_manual.dox | 1 +
commands/gpio.c | 100 +++++++++++++++++++++------------------
3 files changed, 59 insertions(+), 47 deletions(-)
diff --git a/Documentation/commands.dox b/Documentation/commands.dox
index aa489e0..2b949f7 100644
--- a/Documentation/commands.dox
+++ b/Documentation/commands.dox
@@ -30,7 +30,10 @@ available in @a Barebox:
@li @subpage edit_command
@li @subpage erase_command
@li @subpage export_command
- at li @subpage gpio_for_users
+ at li @subpage gpio_get_value_command
+ at li @subpage gpio_set_value_command
+ at li @subpage gpio_direction_input_command
+ at li @subpage gpio_direction_output_command
@li @subpage tftp_command
@li @subpage loadenv_command
@li @subpage ls_command
diff --git a/Documentation/users_manual.dox b/Documentation/users_manual.dox
index bbc7911..ea47b18 100644
--- a/Documentation/users_manual.dox
+++ b/Documentation/users_manual.dox
@@ -7,6 +7,7 @@ you find a lot of nice tricks on these pages to make your life easier.
@li @subpage building
@li @subpage first_steps
@li @subpage command_reference
+ at li @subpage gpio_for_users
\todo Rework the following sections
@li @subpage shell_notes
diff --git a/commands/gpio.c b/commands/gpio.c
index 6a949f2..3fb5c63 100644
--- a/commands/gpio.c
+++ b/commands/gpio.c
@@ -36,12 +36,14 @@ static int do_gpio_get_value(struct command *cmdtp, int argc, char *argv[])
return value;
}
-static const __maybe_unused char cmd_gpio_get_value_help[] =
-"Usage: gpio_get_value <gpio>\n";
+BAREBOX_CMD_HELP_START(gpio_get_value)
+BAREBOX_CMD_HELP_USAGE("gpio_get_value <gpio>")
+BAREBOX_CMD_HELP_SHORT("get the value of an gpio input pin")
+BAREBOX_CMD_HELP_END
BAREBOX_CMD_START(gpio_get_value)
.cmd = do_gpio_get_value,
- .usage = "return a gpio's value",
+ .usage = "return value of a gpio pin",
BAREBOX_CMD_HELP(cmd_gpio_get_value_help)
BAREBOX_CMD_END
@@ -60,8 +62,10 @@ static int do_gpio_set_value(struct command *cmdtp, int argc, char *argv[])
return 0;
}
-static const __maybe_unused char cmd_gpio_set_value_help[] =
-"Usage: gpio_set_value <gpio> <value>\n";
+BAREBOX_CMD_HELP_START(gpio_set_value)
+BAREBOX_CMD_HELP_USAGE("gpio_set_value <gpio> <value>")
+BAREBOX_CMD_HELP_SHORT("set the value of an gpio output pin")
+BAREBOX_CMD_HELP_END
BAREBOX_CMD_START(gpio_set_value)
.cmd = do_gpio_set_value,
@@ -85,12 +89,14 @@ static int do_gpio_direction_input(struct command *cmdtp, int argc, char *argv[]
return 0;
}
-static const __maybe_unused char cmd_do_gpio_direction_input_help[] =
-"Usage: gpio_direction_input <gpio>\n";
+BAREBOX_CMD_HELP_START(gpio_direction_input)
+BAREBOX_CMD_HELP_USAGE("gpio_direction_input <gpio>")
+BAREBOX_CMD_HELP_SHORT("set direction of a gpio pin to input")
+BAREBOX_CMD_HELP_END
BAREBOX_CMD_START(gpio_direction_input)
.cmd = do_gpio_direction_input,
- .usage = "set a gpio as output",
+ .usage = "set direction of a gpio pin to input",
BAREBOX_CMD_HELP(cmd_do_gpio_direction_input_help)
BAREBOX_CMD_END
@@ -111,73 +117,75 @@ static int do_gpio_direction_output(struct command *cmdtp, int argc, char *argv[
return 0;
}
-static const __maybe_unused char cmd_gpio_direction_output_help[] =
-"Usage: gpio_direction_output <gpio> <value>\n";
+BAREBOX_CMD_HELP_START(gpio_direction_output)
+BAREBOX_CMD_HELP_USAGE("gpio_direction_output <gpio> <value>")
+BAREBOX_CMD_HELP_SHORT("set direction of a gpio pin to output")
+BAREBOX_CMD_HELP_END
BAREBOX_CMD_START(gpio_direction_output)
.cmd = do_gpio_direction_output,
- .usage = "set a gpio as output",
+ .usage = "set direction of a gpio pin to output",
BAREBOX_CMD_HELP(cmd_gpio_direction_output_help)
BAREBOX_CMD_END
/**
- at page gpio_for_users Runtime GPIO handling
+ * @page gpio_for_users GPIO Handling
@section regular_gpio General usage information
-These commands are available if the symbol @b CONFIG_GENERIC_GPIO and
- at b CONFIG_CMD_GPIO are enabled in the Kconfig.
+These commands are available if the symbol @b CONFIG_GENERIC_GPIO and @b
+CONFIG_CMD_GPIO are enabled in 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.
+number is architecture dependent and may not directly correlate with the
+pad numbers. Due to this, it is also possible that the numbers changes
+between @b barebox releases.
- at section gpio_dir_out Switch a pad into an output GPIO
+ at section gpio_dir_out Use Pad as GPIO Output
@verbatim
-gpio_direction_output <gpio_no> <initial_value>
+# gpio_direction_output <gpio_no> <initial_value>
@endverbatim
-- @b gpio_no Architecture dependent GPIO number
-- @b initial_value Output value the pad should emit
+- gpio_no: Architecture dependend GPIO number
+- initial_value: Output value
- at 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)
+<p> To avoid glitches on the pad the routines will first sett up the
+pad's value and afterwards switch the pad to output (if the silicon is
+able to do so). If the pad is already configured in non-GPIO mode (if
+available), this command may silently fail. </p>
- at note If the pad is already configured into a non GPIO mode (if available)
-this command may fail (silently)
-
- at section gpio_dir_in Switch a pad into an input GPIO
+ at section gpio_dir_in Use Pad as GPIO Input
@verbatim
-gpio_direction_input <gpio_no>
+# gpio_direction_input <gpio_no>
@endverbatim
-- @b gpio_no Architecture dependent GPIO number
+- gpio_no: Architecture dependent GPIO number
- at note If the pad is already configured into a non GPIO mode (if available)
-this command may fail (silently)
+<p> If the pad is already configured in non-GPIO mode (if available),
+this command may silently fail. </p>
- at section gpio_get_value Read in the value of an GPIO input pad
+ at section gpio_get_value Read Input Value from GPIO Pin
@verbatim
-gpio_get_value <gpio_no>
+# 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 $?"
+<p> Reads the current value of a GPIO pin and return the value as a
+shell return code. There is no visible output on stdout. You can check
+the return value by using "echo $?". </p>
- at note If the return code is not '0' or '1' it's meant as an error code.
+<p> A return code other than '0' or '1' specifies an error code. </p>
- at note If the pad is not configured for GPIO mode this command may fail
-(silently) and returns garbage
+<p> If the pad is not configured in GPIO mode, this command may silently
+fail and return garbage. </p>
- at section gpio_set_value Set a new value to a GPIO output pad
+ at section gpio_set_value Set Output Value on GPIO Pin
@verbatim
-gpio_set_value <gpio_no> <value>
+# gpio_set_value <gpio_no> <value>
@endverbatim
-- @b gpio_no Architecture dependent GPIO number
-- @b value Output value the pad should emit
+- gpio_no: Architecture dependent GPIO number
+- value: Output value
+
+<p> Set a new output value on pad with GPIO number \<gpio_no>. </p>
-Sets a new output @b value to the pad with GPIO number @b gpio_no
+<p> If the pad is not configured in GPIO-mode, this command may silently
+fail. </p>
- at note If the pad is not configured for GPIO mode this command may fail (silently)
*/
--
1.7.2.3
More information about the barebox
mailing list