* [PATCH 01/21] doc: fix typo
2010-11-01 8:33 Unified Documentation Robert Schwebel
@ 2010-11-01 8:33 ` Robert Schwebel
2010-11-01 8:33 ` [PATCH 02/21] doc: add macros to unify command help with doxygen Robert Schwebel
` (19 subsequent siblings)
20 siblings, 0 replies; 24+ messages in thread
From: Robert Schwebel @ 2010-11-01 8:33 UTC (permalink / raw)
To: barebox
Remove a # which leads to this warning:
arch/arm/mach-s3c24xx/lowlevel-init.S:307: Warning: explicit link request to 'CALC_NFCONF_TIMING' could not be resolved
Signed-off-by: Robert Schwebel <r.schwebel@pengutronix.de>
---
arch/arm/mach-s3c24xx/lowlevel-init.S | 2 +-
1 files changed, 1 insertions(+), 1 deletions(-)
diff --git a/arch/arm/mach-s3c24xx/lowlevel-init.S b/arch/arm/mach-s3c24xx/lowlevel-init.S
index e8004e5..27f3a32 100644
--- a/arch/arm/mach-s3c24xx/lowlevel-init.S
+++ b/arch/arm/mach-s3c24xx/lowlevel-init.S
@@ -304,7 +304,7 @@ minimalistic. Setup the NAND access timing is done in a safe manner, what
means: Slowest possible values are used. If you want to increase the speed you
should define the BOARD_DEFAULT_NAND_TIMING to a valid setting into the
NFCONF register and add it to your board specific config.h. Refer S3C24x0's
-datasheet for further details. The macro #CALC_NFCONF_TIMING could help to
+datasheet for further details. The macro CALC_NFCONF_TIMING could help to
calculate the register setting in a hardware independent manner.
@note The regular NAND driver uses a platform data structure to define the
--
1.7.2.3
_______________________________________________
barebox mailing list
barebox@lists.infradead.org
http://lists.infradead.org/mailman/listinfo/barebox
^ permalink raw reply [flat|nested] 24+ messages in thread* [PATCH 02/21] doc: add macros to unify command help with doxygen
2010-11-01 8:33 Unified Documentation Robert Schwebel
2010-11-01 8:33 ` [PATCH 01/21] doc: fix typo Robert Schwebel
@ 2010-11-01 8:33 ` Robert Schwebel
2010-11-01 8:33 ` [PATCH 03/21] doc: add documentation for 'bmp' Robert Schwebel
` (18 subsequent siblings)
20 siblings, 0 replies; 24+ messages in thread
From: Robert Schwebel @ 2010-11-01 8:33 UTC (permalink / raw)
To: barebox
Currently we have duplicated all the information that appears online in
'help <command>' and in the doxygen documentation. This patch adds some
infrastructure to specify help texts only once and re-use them for the
integrated help as well as for the manual.
Signed-off-by: Robert Schwebel <r.schwebel@pengutronix.de>
---
Doxyfile | 2 +-
include/command.h | 9 ++++
scripts/doxy_filter.awk | 103 +++++++++++++++++++++++++++++++++++++++++++++++
3 files changed, 113 insertions(+), 1 deletions(-)
create mode 100644 scripts/doxy_filter.awk
diff --git a/Doxyfile b/Doxyfile
index 912abc1..23f3e43 100644
--- a/Doxyfile
+++ b/Doxyfile
@@ -575,7 +575,7 @@ IMAGE_PATH =
# to standard output. If FILTER_PATTERNS is specified, this tag will be
# ignored.
-INPUT_FILTER =
+INPUT_FILTER = "awk -f scripts/doxy_filter.awk"
# The FILTER_PATTERNS tag can be used to specify filters on a per file pattern
# basis. Doxygen will compare the file name with each pattern and apply the
diff --git a/include/command.h b/include/command.h
index 0be7a69..e221546 100644
--- a/include/command.h
+++ b/include/command.h
@@ -89,6 +89,15 @@ const struct command __barebox_cmd_##_name \
#define BAREBOX_CMD_END \
};
+#define BAREBOX_CMD_HELP_START(_name) \
+static const __maybe_unused char cmd_##_name##_help[] =
+
+#define BAREBOX_CMD_HELP_USAGE(_name) "Usage: " _name
+#define BAREBOX_CMD_HELP_SHORT(_text) _text
+#define BAREBOX_CMD_HELP_OPT(_opt, _desc) _opt "\t" _desc
+#define BAREBOX_CMD_HELP_TEXT(_text)
+#define BAREBOX_CMD_HELP_END ;
+
#ifdef CONFIG_LONGHELP
#define BAREBOX_CMD_HELP(text) .help = text,
#else
diff --git a/scripts/doxy_filter.awk b/scripts/doxy_filter.awk
new file mode 100644
index 0000000..5ec0406
--- /dev/null
+++ b/scripts/doxy_filter.awk
@@ -0,0 +1,103 @@
+#!/usr/bin/awk
+
+/BAREBOX_CMD_HELP_START[[:space:]]*\((.*)\)/ {
+
+ this_opt = 0;
+ my_usage = "";
+ my_short = "";
+ my_cmd = gensub("BAREBOX_CMD_HELP_START[[:space:]]*\\((.*)\\)", "\\1", "g");
+ this_text = 0;
+ delete(my_text);
+ delete(my_opts);
+ next;
+}
+
+/BAREBOX_CMD_HELP_USAGE[[:space:]]*\((.*)\)/ {
+
+ $0 = gensub("<", "\\<", "g");
+ $0 = gensub(">", "\\>", "g");
+ $0 = gensub("BAREBOX_CMD_HELP_USAGE[[:space:]]*\\((.*)\\)", "\\1", "g");
+ $0 = gensub("\\\\n", "", "g");
+ my_usage = gensub("\"", "", "g");
+ next;
+
+}
+
+/BAREBOX_CMD_HELP_SHORT[[:space:]]*\((.*)\)/ {
+
+ $0 = gensub("<", "\\<", "g");
+ $0 = gensub(">", "\\>", "g");
+ $0 = gensub("BAREBOX_CMD_HELP_SHORT[[:space:]]*\\((.*)\\)", "\\1", "g");
+ $0 = gensub("\\\\n", "", "g");
+ my_short = gensub("\"", "", "g");
+ next;
+
+}
+
+/BAREBOX_CMD_HELP_OPT[[:space:]]*\([[:space:]]*(.*)[[:space:]]*,[[:space:]]*(.*)[[:space:]]*\)/ {
+
+ $0 = gensub("<", "\\<", "g");
+ $0 = gensub(">", "\\>", "g");
+ $0 = gensub("@", "\\\\@", "g");
+ $0 = gensub("BAREBOX_CMD_HELP_OPT[[:space:]]*\\([[:space:]]*\"*(.*)\"[[:space:]]*,[[:space:]]*\"(.*)\"[[:space:]]*\\)", \
+ "<tr><td><tt> \\1 </tt></td><td>\\ \\ \\ </td><td> \\2 </td></tr>", "g");
+ $0 = gensub("\\\\n", "", "g");
+ my_opts[this_opt] = gensub("\"", "", "g");
+ this_opt ++;
+ next;
+}
+
+/BAREBOX_CMD_HELP_TEXT[[:space:]]*\((.*)\)/ {
+
+ $0 = gensub("<", "\\<", "g");
+ $0 = gensub(">", "\\>", "g");
+ $0 = gensub("BAREBOX_CMD_HELP_TEXT[[:space:]]*\\((.*)\\)", "\\1", "g");
+ $0 = gensub("\\\\n", "<br>", "g");
+ my_text[this_text] = gensub("\"", "", "g");
+ this_text ++;
+ next;
+}
+
+/BAREBOX_CMD_HELP_END/ {
+
+ printf "/**\n";
+ printf " * @page " my_cmd "_command " my_cmd "\n";
+ printf " *\n";
+ printf " * \\par Usage:\n";
+ printf " * " my_usage "\n";
+ printf " *\n";
+
+ if (this_opt != 0) {
+ printf " * \\par Options:\n";
+ printf " *\n";
+ printf " * <table border=\"0\" cellpadding=\"0\">\n";
+ n = asorti(my_opts, my_opts_sorted);
+ for (i=1; i<=n; i++) {
+ printf " * " my_opts[my_opts_sorted[i]] "\n";
+ }
+ printf " * </table>\n";
+ printf " *\n";
+ }
+
+ printf " * " my_short "\n";
+ printf " *\n";
+
+ n = asorti(my_text, my_text_sorted);
+ if (n > 0) {
+ for (i=1; i<=n; i++) {
+ printf " * " my_text[my_text_sorted[i]] "\n";
+ }
+ printf " *\n";
+ }
+
+ printf " */\n";
+
+ next;
+}
+
+/^.*$/ {
+
+ print $0;
+
+}
+
--
1.7.2.3
_______________________________________________
barebox mailing list
barebox@lists.infradead.org
http://lists.infradead.org/mailman/listinfo/barebox
^ permalink raw reply [flat|nested] 24+ messages in thread* [PATCH 03/21] doc: add documentation for 'bmp'
2010-11-01 8:33 Unified Documentation Robert Schwebel
2010-11-01 8:33 ` [PATCH 01/21] doc: fix typo Robert Schwebel
2010-11-01 8:33 ` [PATCH 02/21] doc: add macros to unify command help with doxygen Robert Schwebel
@ 2010-11-01 8:33 ` Robert Schwebel
2010-11-01 8:33 ` [PATCH 04/21] doc: add documentation for 'clear' Robert Schwebel
` (17 subsequent siblings)
20 siblings, 0 replies; 24+ messages in thread
From: Robert Schwebel @ 2010-11-01 8:33 UTC (permalink / raw)
To: barebox
Signed-off-by: Robert Schwebel <r.schwebel@pengutronix.de>
---
Documentation/commands.dox | 1 +
commands/bmp.c | 27 +++++++++++++++++++--------
2 files changed, 20 insertions(+), 8 deletions(-)
diff --git a/Documentation/commands.dox b/Documentation/commands.dox
index e8ad177..ac280d6 100644
--- a/Documentation/commands.dox
+++ b/Documentation/commands.dox
@@ -2,6 +2,7 @@
* @page command_reference Supported Shell Commands
@li @subpage addpart_command
+@li @subpage bmp_command
@li @subpage cat_command
@li @subpage cd_command
@li @subpage cp_command
diff --git a/commands/bmp.c b/commands/bmp.c
index 6e17200..9402c05 100644
--- a/commands/bmp.c
+++ b/commands/bmp.c
@@ -193,17 +193,28 @@ failed_memmap:
return 1;
}
-static const __maybe_unused char cmd_bmp_help[] =
-"Usage: bmp [OPTION]... FILE\n"
-"show bmp image FILE.\n"
-" -f <fb> framebuffer device (/dev/fb0)\n"
-" -x <xofs> x offset (default center)\n"
-" -y <yofs> y offset (default center)\n"
-" -o render offscreen\n";
+BAREBOX_CMD_HELP_START(bmp)
+BAREBOX_CMD_HELP_USAGE("bmp [OPTIONS] FILE")
+BAREBOX_CMD_HELP_SHORT("Show the bitmap FILE on the framebuffer.")
+BAREBOX_CMD_HELP_OPT ("-f <fb>", "framebuffer device (/dev/fb0)")
+BAREBOX_CMD_HELP_OPT ("-x <xofs>", "x offset (default center)")
+BAREBOX_CMD_HELP_OPT ("-y <yofs>", "y offset (default center)")
+BAREBOX_CMD_HELP_OPT ("-o", "render offscreen")
+BAREBOX_CMD_HELP_END
+
+/**
+ * @page bmp_command
+
+This command displays a graphics in the bitmap (.bmp) format on the
+framebuffer. Currently the bmp command supports images with 8 and 24 bit
+color depth.
+
+\todo What does the -o (offscreen) option do?
+
+ */
BAREBOX_CMD_START(bmp)
.cmd = do_bmp,
.usage = "show a bmp image",
BAREBOX_CMD_HELP(cmd_bmp_help)
BAREBOX_CMD_END
-
--
1.7.2.3
_______________________________________________
barebox mailing list
barebox@lists.infradead.org
http://lists.infradead.org/mailman/listinfo/barebox
^ permalink raw reply [flat|nested] 24+ messages in thread* [PATCH 04/21] doc: add documentation for 'clear'
2010-11-01 8:33 Unified Documentation Robert Schwebel
` (2 preceding siblings ...)
2010-11-01 8:33 ` [PATCH 03/21] doc: add documentation for 'bmp' Robert Schwebel
@ 2010-11-01 8:33 ` Robert Schwebel
2010-11-01 8:33 ` [PATCH 05/21] doc: add documentation for 'crc32' Robert Schwebel
` (16 subsequent siblings)
20 siblings, 0 replies; 24+ messages in thread
From: Robert Schwebel @ 2010-11-01 8:33 UTC (permalink / raw)
To: barebox
Signed-off-by: Robert Schwebel <r.schwebel@pengutronix.de>
---
Documentation/commands.dox | 1 +
commands/clear.c | 5 +++++
2 files changed, 6 insertions(+), 0 deletions(-)
diff --git a/Documentation/commands.dox b/Documentation/commands.dox
index ac280d6..b065ca4 100644
--- a/Documentation/commands.dox
+++ b/Documentation/commands.dox
@@ -5,6 +5,7 @@
@li @subpage bmp_command
@li @subpage cat_command
@li @subpage cd_command
+@li @subpage clear_command
@li @subpage cp_command
@li @subpage delpart_command
@li @subpage devinfo_command
diff --git a/commands/clear.c b/commands/clear.c
index 7589a0c..6a6b6c5 100644
--- a/commands/clear.c
+++ b/commands/clear.c
@@ -31,6 +31,11 @@ static int do_clear(struct command *cmdtp, int argc, char *argv[])
return 0;
}
+BAREBOX_CMD_HELP_START(clear)
+BAREBOX_CMD_HELP_USAGE("clear\n")
+BAREBOX_CMD_HELP_SHORT("Clear the screen.\n")
+BAREBOX_CMD_HELP_END
+
BAREBOX_CMD_START(clear)
.cmd = do_clear,
.usage = "clear screen",
--
1.7.2.3
_______________________________________________
barebox mailing list
barebox@lists.infradead.org
http://lists.infradead.org/mailman/listinfo/barebox
^ permalink raw reply [flat|nested] 24+ messages in thread* [PATCH 05/21] doc: add documentation for 'crc32'
2010-11-01 8:33 Unified Documentation Robert Schwebel
` (3 preceding siblings ...)
2010-11-01 8:33 ` [PATCH 04/21] doc: add documentation for 'clear' Robert Schwebel
@ 2010-11-01 8:33 ` Robert Schwebel
2010-11-01 8:33 ` [PATCH 06/21] doc: add documentation for 'dfu' Robert Schwebel
` (15 subsequent siblings)
20 siblings, 0 replies; 24+ messages in thread
From: Robert Schwebel @ 2010-11-01 8:33 UTC (permalink / raw)
To: barebox
Signed-off-by: Robert Schwebel <r.schwebel@pengutronix.de>
---
Documentation/commands.dox | 1 +
commands/crc.c | 15 +++++++--------
2 files changed, 8 insertions(+), 8 deletions(-)
diff --git a/Documentation/commands.dox b/Documentation/commands.dox
index b065ca4..bc1a428 100644
--- a/Documentation/commands.dox
+++ b/Documentation/commands.dox
@@ -7,6 +7,7 @@
@li @subpage cd_command
@li @subpage clear_command
@li @subpage cp_command
+@li @subpage crc_command
@li @subpage delpart_command
@li @subpage devinfo_command
@li @subpage edit_command
diff --git a/commands/crc.c b/commands/crc.c
index d3e0865..0873a1c 100644
--- a/commands/crc.c
+++ b/commands/crc.c
@@ -143,19 +143,18 @@ static int do_crc(struct command *cmdtp, int argc, char *argv[])
return err;
}
-static const __maybe_unused char cmd_crc_help[] =
-"Usage: crc32 [OPTION] [AREA]\n"
-"Calculate a crc32 checksum of a memory area\n"
-"Options:\n"
-" -f <file> Use file instead of memory\n"
+BAREBOX_CMD_HELP_START(crc)
+BAREBOX_CMD_HELP_USAGE("crc32 [OPTION] [AREA]\n")
+BAREBOX_CMD_HELP_SHORT("Calculate a crc32 checksum of a memory area.\n")
+BAREBOX_CMD_HELP_OPT ("-f <file>", "Use file instead of memory.\n")
#ifdef CONFIG_CMD_CRC_CMP
-" -F <file> Use file to compare\n"
+BAREBOX_CMD_HELP_OPT ("-F <file>", "Use file to compare.\n")
#endif
-" -v <crc> Verfify\n";
+BAREBOX_CMD_HELP_OPT ("-v <crc>", "Verfify\n")
+BAREBOX_CMD_HELP_END
BAREBOX_CMD_START(crc32)
.cmd = do_crc,
.usage = "crc32 checksum calculation",
BAREBOX_CMD_HELP(cmd_crc_help)
BAREBOX_CMD_END
-
--
1.7.2.3
_______________________________________________
barebox mailing list
barebox@lists.infradead.org
http://lists.infradead.org/mailman/listinfo/barebox
^ permalink raw reply [flat|nested] 24+ messages in thread* [PATCH 06/21] doc: add documentation for 'dfu'
2010-11-01 8:33 Unified Documentation Robert Schwebel
` (4 preceding siblings ...)
2010-11-01 8:33 ` [PATCH 05/21] doc: add documentation for 'crc32' Robert Schwebel
@ 2010-11-01 8:33 ` Robert Schwebel
2010-11-01 8:51 ` Baruch Siach
2010-11-01 8:33 ` [PATCH 07/21] doc: unify documentation for 'ls' Robert Schwebel
` (14 subsequent siblings)
20 siblings, 1 reply; 24+ messages in thread
From: Robert Schwebel @ 2010-11-01 8:33 UTC (permalink / raw)
To: barebox
Signed-off-by: Robert Schwebel <r.schwebel@pengutronix.de>
---
Documentation/commands.dox | 1 +
commands/dfu.c | 28 ++++++++++++++++++----------
2 files changed, 19 insertions(+), 10 deletions(-)
diff --git a/Documentation/commands.dox b/Documentation/commands.dox
index bc1a428..17e034a 100644
--- a/Documentation/commands.dox
+++ b/Documentation/commands.dox
@@ -10,6 +10,7 @@
@li @subpage crc_command
@li @subpage delpart_command
@li @subpage devinfo_command
+@li @subpage dfu_command
@li @subpage edit_command
@li @subpage erase_command
@li @subpage export_command
diff --git a/commands/dfu.c b/commands/dfu.c
index 66fd6ea..7043bd5 100644
--- a/commands/dfu.c
+++ b/commands/dfu.c
@@ -162,16 +162,24 @@ out:
return 1;
}
-static const __maybe_unused char cmd_dfu_help[] =
-"Usage: dfu [OPTION]... description\n"
-"start dfu firmware update\n"
-" -m <str> Manufacturer string (barebox)\n"
-" -p <str> product string (" CONFIG_BOARDINFO ")\n"
-" -V <id> vendor id\n"
-" -P <id> product id\n"
-"description has the form\n"
-"device1(name1)[sr],device2(name2)[sr]\n"
-"where s is for save mode and r for read back of firmware\n";
+BAREBOX_CMD_HELP_START(dfu)
+BAREBOX_CMD_HELP_USAGE("dfu [OPTIONS] <description>\n")
+BAREBOX_CMD_HELP_SHORT("Start firmware update with the Device Firmware Update (DFU) protocol.")
+BAREBOX_CMD_HELP_OPT ("-m <str>", "Manufacturer string (barebox)\n")
+BAREBOX_CMD_HELP_OPT ("-p <str>", "product string (" CONFIG_BOARDINFO ")\n")
+BAREBOX_CMD_HELP_OPT ("-V <id>", "vendor id\n")
+BAREBOX_CMD_HELP_OPT ("-P <id>", "product id\n")
+BAREBOX_CMD_HELP_END
+
+/**
+ * @page dfu_command
+\<description> has the following form:
+device1(name1)[sr],device2)[sr]
+'s' means 'safe mode' (download the complete image before flashing) and
+'r' that readback of the firmware is allowed.
+
+\todo Add example, how to use dfu from a Linux or Windows host.
+ */
BAREBOX_CMD_START(dfu)
.cmd = do_dfu,
--
1.7.2.3
_______________________________________________
barebox mailing list
barebox@lists.infradead.org
http://lists.infradead.org/mailman/listinfo/barebox
^ permalink raw reply [flat|nested] 24+ messages in thread* Re: [PATCH 06/21] doc: add documentation for 'dfu'
2010-11-01 8:33 ` [PATCH 06/21] doc: add documentation for 'dfu' Robert Schwebel
@ 2010-11-01 8:51 ` Baruch Siach
2010-11-01 10:03 ` Robert Schwebel
0 siblings, 1 reply; 24+ messages in thread
From: Baruch Siach @ 2010-11-01 8:51 UTC (permalink / raw)
To: Robert Schwebel; +Cc: barebox
Hi Robert,
On Mon, Nov 01, 2010 at 09:33:39AM +0100, Robert Schwebel wrote:
> Signed-off-by: Robert Schwebel <r.schwebel@pengutronix.de>
> ---
> Documentation/commands.dox | 1 +
> commands/dfu.c | 28 ++++++++++++++++++----------
> 2 files changed, 19 insertions(+), 10 deletions(-)
>
[snip]
> -static const __maybe_unused char cmd_dfu_help[] =
> -"Usage: dfu [OPTION]... description\n"
> -"start dfu firmware update\n"
> -" -m <str> Manufacturer string (barebox)\n"
> -" -p <str> product string (" CONFIG_BOARDINFO ")\n"
> -" -V <id> vendor id\n"
> -" -P <id> product id\n"
> -"description has the form\n"
> -"device1(name1)[sr],device2(name2)[sr]\n"
> -"where s is for save mode and r for read back of firmware\n";
> +BAREBOX_CMD_HELP_START(dfu)
> +BAREBOX_CMD_HELP_USAGE("dfu [OPTIONS] <description>\n")
> +BAREBOX_CMD_HELP_SHORT("Start firmware update with the Device Firmware Update (DFU) protocol.")
> +BAREBOX_CMD_HELP_OPT ("-m <str>", "Manufacturer string (barebox)\n")
> +BAREBOX_CMD_HELP_OPT ("-p <str>", "product string (" CONFIG_BOARDINFO ")\n")
> +BAREBOX_CMD_HELP_OPT ("-V <id>", "vendor id\n")
> +BAREBOX_CMD_HELP_OPT ("-P <id>", "product id\n")
> +BAREBOX_CMD_HELP_END
> +
> +/**
> + * @page dfu_command
> +\<description> has the following form:
> +device1(name1)[sr],device2)[sr]
Should probably be:
device1(name1)[sr],device2(name2)[sr]
baruch
> +'s' means 'safe mode' (download the complete image before flashing) and
> +'r' that readback of the firmware is allowed.
> +
> +\todo Add example, how to use dfu from a Linux or Windows host.
> + */
>
> BAREBOX_CMD_START(dfu)
> .cmd = do_dfu,
--
~. .~ Tk Open Systems
=}------------------------------------------------ooO--U--Ooo------------{=
- baruch@tkos.co.il - tel: +972.2.679.5364, http://www.tkos.co.il -
_______________________________________________
barebox mailing list
barebox@lists.infradead.org
http://lists.infradead.org/mailman/listinfo/barebox
^ permalink raw reply [flat|nested] 24+ messages in thread
* [PATCH 07/21] doc: unify documentation for 'ls'
2010-11-01 8:33 Unified Documentation Robert Schwebel
` (5 preceding siblings ...)
2010-11-01 8:33 ` [PATCH 06/21] doc: add documentation for 'dfu' Robert Schwebel
@ 2010-11-01 8:33 ` Robert Schwebel
2010-11-01 8:33 ` [PATCH 08/21] doc: unify documentation for 'cat' Robert Schwebel
` (13 subsequent siblings)
20 siblings, 0 replies; 24+ messages in thread
From: Robert Schwebel @ 2010-11-01 8:33 UTC (permalink / raw)
To: barebox
Signed-off-by: Robert Schwebel <r.schwebel@pengutronix.de>
---
Documentation/commands.dox | 1 +
commands/ls.c | 9 +++++----
2 files changed, 6 insertions(+), 4 deletions(-)
diff --git a/Documentation/commands.dox b/Documentation/commands.dox
index 17e034a..4bcf548 100644
--- a/Documentation/commands.dox
+++ b/Documentation/commands.dox
@@ -17,6 +17,7 @@
@li @subpage gpio_for_users
@li @subpage tftp_command
@li @subpage loadenv_command
+@li @subpage ls_command
@li @subpage mount_command
@li @subpage printenv_command
@li @subpage protect_command
diff --git a/commands/ls.c b/commands/ls.c
index a02ccfe..2005178 100644
--- a/commands/ls.c
+++ b/commands/ls.c
@@ -194,10 +194,11 @@ static int do_ls(struct command *cmdtp, int argc, char *argv[])
return 0;
}
-static const __maybe_unused char cmd_ls_help[] =
-"Usage: ls [OPTION]... [FILE]...\n"
-"List information about the FILEs (the current directory by default).\n"
-" -R list subdirectories recursively\n";
+BAREBOX_CMD_HELP_START(ls)
+BAREBOX_CMD_HELP_USAGE("ls [OPTION]... [FILE]...\n")
+BAREBOX_CMD_HELP_SHORT("List information about the FILEs (the current directory by default).\n")
+BAREBOX_CMD_HELP_OPT ("-R", "list subdirectories recursively\n")
+BAREBOX_CMD_HELP_END
BAREBOX_CMD_START(ls)
.cmd = do_ls,
--
1.7.2.3
_______________________________________________
barebox mailing list
barebox@lists.infradead.org
http://lists.infradead.org/mailman/listinfo/barebox
^ permalink raw reply [flat|nested] 24+ messages in thread* [PATCH 08/21] doc: unify documentation for 'cat'
2010-11-01 8:33 Unified Documentation Robert Schwebel
` (6 preceding siblings ...)
2010-11-01 8:33 ` [PATCH 07/21] doc: unify documentation for 'ls' Robert Schwebel
@ 2010-11-01 8:33 ` Robert Schwebel
2010-11-01 8:33 ` [PATCH 09/21] doc: unify documentation for 'cd' Robert Schwebel
` (12 subsequent siblings)
20 siblings, 0 replies; 24+ messages in thread
From: Robert Schwebel @ 2010-11-01 8:33 UTC (permalink / raw)
To: barebox
Signed-off-by: Robert Schwebel <r.schwebel@pengutronix.de>
---
commands/cat.c | 19 ++++++-------------
1 files changed, 6 insertions(+), 13 deletions(-)
diff --git a/commands/cat.c b/commands/cat.c
index 41b3324..37e6505 100644
--- a/commands/cat.c
+++ b/commands/cat.c
@@ -85,22 +85,15 @@ out:
return err;
}
-static const __maybe_unused char cmd_cat_help[] =
-"Usage: cat [FILES]\n"
-"Concatenate files on stdout. Currently only printable characters\n"
-"and \\n and \\t are printed, but this should be optional\n";
+BAREBOX_CMD_HELP_START(cat)
+BAREBOX_CMD_HELP_USAGE("cat [FILES]\n")
+BAREBOX_CMD_HELP_SHORT("Concatenate files on stdout.\n")
+BAREBOX_CMD_HELP_TEXT ("Currently only printable characters and \\ n and \\ t are printed,\n")
+BAREBOX_CMD_HELP_TEXT ("but this should be optional.\n")
+BAREBOX_CMD_HELP_END
BAREBOX_CMD_START(cat)
.cmd = do_cat,
.usage = "concatenate file(s)",
BAREBOX_CMD_HELP(cmd_cat_help)
BAREBOX_CMD_END
-
-/**
- * @page cat_command cat (concatenate)
- *
- * Usage is: cat \<file\> [\<file\> ...]
- *
- * Concatenate files to stdout. Currently only printable characters
- * and \\n and \\t are printed, but this should be optional
- */
--
1.7.2.3
_______________________________________________
barebox mailing list
barebox@lists.infradead.org
http://lists.infradead.org/mailman/listinfo/barebox
^ permalink raw reply [flat|nested] 24+ messages in thread* [PATCH 09/21] doc: unify documentation for 'cd'
2010-11-01 8:33 Unified Documentation Robert Schwebel
` (7 preceding siblings ...)
2010-11-01 8:33 ` [PATCH 08/21] doc: unify documentation for 'cat' Robert Schwebel
@ 2010-11-01 8:33 ` Robert Schwebel
2010-11-01 8:33 ` [PATCH 10/21] doc: add documentation for 'echo' Robert Schwebel
` (11 subsequent siblings)
20 siblings, 0 replies; 24+ messages in thread
From: Robert Schwebel @ 2010-11-01 8:33 UTC (permalink / raw)
To: barebox
Signed-off-by: Robert Schwebel <r.schwebel@pengutronix.de>
---
commands/cd.c | 17 +++++------------
1 files changed, 5 insertions(+), 12 deletions(-)
diff --git a/commands/cd.c b/commands/cd.c
index a842f4d..d73be32 100644
--- a/commands/cd.c
+++ b/commands/cd.c
@@ -47,21 +47,14 @@ static int do_cd(struct command *cmdtp, int argc, char *argv[])
return 0;
}
-static const __maybe_unused char cmd_cd_help[] =
-"Usage: cd [directory]\n"
-"change to directory. If called without argument, change to /\n";
+BAREBOX_CMD_HELP_START(cd)
+BAREBOX_CMD_HELP_USAGE("cd [directory]\n")
+BAREBOX_CMD_HELP_SHORT("Change to directory.\n")
+BAREBOX_CMD_HELP_TEXT ("If called without an argument, change to the root directory /.\n")
+BAREBOX_CMD_HELP_END
BAREBOX_CMD_START(cd)
.cmd = do_cd,
.usage = "change working directory",
BAREBOX_CMD_HELP(cmd_cd_help)
BAREBOX_CMD_END
-
-/**
- * @page cd_command cd (change working directory)
- *
- * Usage is: cd [\<directory name>]
- *
- * Change to \<directory name>. If called without argument, change to \b /
- * (root)
- */
--
1.7.2.3
_______________________________________________
barebox mailing list
barebox@lists.infradead.org
http://lists.infradead.org/mailman/listinfo/barebox
^ permalink raw reply [flat|nested] 24+ messages in thread* [PATCH 10/21] doc: add documentation for 'echo'
2010-11-01 8:33 Unified Documentation Robert Schwebel
` (8 preceding siblings ...)
2010-11-01 8:33 ` [PATCH 09/21] doc: unify documentation for 'cd' Robert Schwebel
@ 2010-11-01 8:33 ` Robert Schwebel
2010-11-01 8:33 ` [PATCH 11/21] doc: unify documentation for 'edit' Robert Schwebel
` (10 subsequent siblings)
20 siblings, 0 replies; 24+ messages in thread
From: Robert Schwebel @ 2010-11-01 8:33 UTC (permalink / raw)
To: barebox
Signed-off-by: Robert Schwebel <r.schwebel@pengutronix.de>
---
Documentation/commands.dox | 1 +
commands/echo.c | 17 +++++++++++++++++
2 files changed, 18 insertions(+), 0 deletions(-)
diff --git a/Documentation/commands.dox b/Documentation/commands.dox
index 4bcf548..38968b5 100644
--- a/Documentation/commands.dox
+++ b/Documentation/commands.dox
@@ -11,6 +11,7 @@
@li @subpage delpart_command
@li @subpage devinfo_command
@li @subpage dfu_command
+@li @subpage echo_command
@li @subpage edit_command
@li @subpage erase_command
@li @subpage export_command
diff --git a/commands/echo.c b/commands/echo.c
index dfa14d6..3e098df 100644
--- a/commands/echo.c
+++ b/commands/echo.c
@@ -111,8 +111,25 @@ no_optarg_out:
return 1;
}
+BAREBOX_CMD_HELP_START(echo)
+BAREBOX_CMD_HELP_USAGE("echo [OPTIONS] [STRING]\n")
+BAREBOX_CMD_HELP_SHORT("Display a line of text.\n")
+BAREBOX_CMD_HELP_OPT ("-n", "do not output the trailing newline\n")
+BAREBOX_CMD_HELP_OPT ("-a", "FIXME\n")
+BAREBOX_CMD_HELP_OPT ("-o", "FIXME\n")
+BAREBOX_CMD_HELP_OPT ("-e", "FIXME\n")
+BAREBOX_CMD_HELP_END
+
+/**
+ * @page echo_command
+
+\todo Add documentation for -a, -o and -e.
+
+ */
+
BAREBOX_CMD_START(echo)
.cmd = do_echo,
.usage = "echo args to console",
+ BAREBOX_CMD_HELP(cmd_echo_help)
BAREBOX_CMD_END
--
1.7.2.3
_______________________________________________
barebox mailing list
barebox@lists.infradead.org
http://lists.infradead.org/mailman/listinfo/barebox
^ permalink raw reply [flat|nested] 24+ messages in thread* [PATCH 11/21] doc: unify documentation for 'edit'
2010-11-01 8:33 Unified Documentation Robert Schwebel
` (9 preceding siblings ...)
2010-11-01 8:33 ` [PATCH 10/21] doc: add documentation for 'echo' Robert Schwebel
@ 2010-11-01 8:33 ` Robert Schwebel
2010-11-01 8:33 ` [PATCH 12/21] doc: add documentation for 'bootm' Robert Schwebel
` (9 subsequent siblings)
20 siblings, 0 replies; 24+ messages in thread
From: Robert Schwebel @ 2010-11-01 8:33 UTC (permalink / raw)
To: barebox
Signed-off-by: Robert Schwebel <r.schwebel@pengutronix.de>
---
commands/edit.c | 38 ++++++++++++++------------------------
1 files changed, 14 insertions(+), 24 deletions(-)
diff --git a/commands/edit.c b/commands/edit.c
index c2ab877..ca40d59 100644
--- a/commands/edit.c
+++ b/commands/edit.c
@@ -550,35 +550,25 @@ out:
static const char *edit_aliases[] = { "sedit", NULL};
-static const __maybe_unused char cmd_edit_help[] =
-"Usage: (s)edit <file>\n"
-"This is a very small editor. Its only features are moving the cursor with\n"
-"the usual keys and typing characters.\n"
-"<ctrl-c> quits the editor without saving,\n"
-"<ctrl-d> quits the editor with saving the current file.\n"
-"\n"
-"If called as sedit the editor uses ansi codes to scroll the screen.\n";
+BAREBOX_CMD_HELP_START(edit)
+BAREBOX_CMD_HELP_USAGE("(s)edit <file>\n")
+BAREBOX_CMD_HELP_SHORT("A small editor. <ctrl-c> is exit, <ctrl-d> exit-with-save.\n")
+BAREBOX_CMD_HELP_END
-static const __maybe_unused char cmd_edit_usage[] = "edit a file";
+/**
+ * @page edit_command
+
+<p> Barebox contains a small text editor which can be used to edit
+config files in /env. You can move the cursor around with the arrow keys
+and type characters. </p>
+
+If called as sedit, the editor uses ansi codes to scroll the screen.
+ */
BAREBOX_CMD_START(edit)
.cmd = do_edit,
.aliases = edit_aliases,
- .usage = cmd_edit_usage,
+ .usage = "Usage: (s)edit <file>",
BAREBOX_CMD_HELP(cmd_edit_help)
BAREBOX_CMD_END
-
-/**
- * @page edit_command edit (editor)
- *
- * Usage is: [s]edit \<file\>
- *
- * This is a very small editor. It's only features are moving the cursor with
- * the usual keys and typing characters.
- *
- * \b \<ctrl-c\> quits the editor without saving,\n
- * \b \<ctrl-d\> quits the editor with saving the current file.
- *
- * If called as \c sedit the editor uses ansi codes to scroll the screen.
- */
--
1.7.2.3
_______________________________________________
barebox mailing list
barebox@lists.infradead.org
http://lists.infradead.org/mailman/listinfo/barebox
^ permalink raw reply [flat|nested] 24+ messages in thread* [PATCH 12/21] doc: add documentation for 'bootm'
2010-11-01 8:33 Unified Documentation Robert Schwebel
` (10 preceding siblings ...)
2010-11-01 8:33 ` [PATCH 11/21] doc: unify documentation for 'edit' Robert Schwebel
@ 2010-11-01 8:33 ` Robert Schwebel
2010-11-01 8:33 ` [PATCH 13/21] doc: unify documentation for 'addpart' Robert Schwebel
` (8 subsequent siblings)
20 siblings, 0 replies; 24+ messages in thread
From: Robert Schwebel @ 2010-11-01 8:33 UTC (permalink / raw)
To: barebox
Signed-off-by: Robert Schwebel <r.schwebel@pengutronix.de>
---
Documentation/commands.dox | 1 +
commands/bootm.c | 38 ++++++++++++++++++++------------------
2 files changed, 21 insertions(+), 18 deletions(-)
diff --git a/Documentation/commands.dox b/Documentation/commands.dox
index 38968b5..2679ed7 100644
--- a/Documentation/commands.dox
+++ b/Documentation/commands.dox
@@ -3,6 +3,7 @@
@li @subpage addpart_command
@li @subpage bmp_command
+@li @subpage bootm_command
@li @subpage cat_command
@li @subpage cd_command
@li @subpage clear_command
diff --git a/commands/bootm.c b/commands/bootm.c
index 0d3649f..eab23d9 100644
--- a/commands/bootm.c
+++ b/commands/bootm.c
@@ -368,18 +368,18 @@ err_out:
return 1;
}
-static const __maybe_unused char cmd_bootm_help[] =
-"Usage: bootm [OPTION] image\n"
-"Boot application image\n"
-" -n do not verify the images (speeds up boot process)\n"
-" -h show advanced options\n";
+BAREBOX_CMD_HELP_START(bootm)
+BAREBOX_CMD_HELP_USAGE("bootm [-n] image\n")
+BAREBOX_CMD_HELP_SHORT("Boot an application image.\n")
+BAREBOX_CMD_HELP_OPT ("-n", "Do not verify the image (speeds up boot process)")
+BAREBOX_CMD_HELP_END
+/**
+ * @page bootm_command
-BAREBOX_CMD_START(bootm)
- .cmd = do_bootm,
- .usage = "boot application image",
- BAREBOX_CMD_HELP(cmd_bootm_help)
-BAREBOX_CMD_END
+\todo What does bootm do, what kind of image does it boot?
+
+ */
#ifdef CONFIG_CMD_IMI
static int do_iminfo(struct command *cmdtp, int argc, char *argv[])
@@ -440,14 +440,16 @@ static int image_info (ulong addr)
return 0;
}
-BAREBOX_CMD(
- iminfo, 1, do_iminfo,
- "iminfo - print header information for application image\n",
- "addr [addr ...]\n"
- " - print header information for application image starting at\n"
- " address 'addr' in memory; this includes verification of the\n"
- " image contents (magic number, header and payload checksums)\n"
-);
+BAREBOX_CMD_HELP_START(iminfo)
+BAREBOX_CMD_HELP_USAGE("iminfo")
+BAREBOX_CMD_HELP_SHORT("Print header information for an application image.")
+BAREBOX_CMD_HELP_END
+
+BAREBOX_CMD_START(iminfo)
+ .cmd = do_iminfo,
+ .usage = "print header information for an application image",
+ BAREBOX_CMD_HELP(cmd_iminfo_help)
+BAREBOX_CMD_END
#endif /* CONFIG_CMD_IMI */
--
1.7.2.3
_______________________________________________
barebox mailing list
barebox@lists.infradead.org
http://lists.infradead.org/mailman/listinfo/barebox
^ permalink raw reply [flat|nested] 24+ messages in thread* [PATCH 13/21] doc: unify documentation for 'addpart'
2010-11-01 8:33 Unified Documentation Robert Schwebel
` (11 preceding siblings ...)
2010-11-01 8:33 ` [PATCH 12/21] doc: add documentation for 'bootm' Robert Schwebel
@ 2010-11-01 8:33 ` Robert Schwebel
2010-11-01 8:33 ` [PATCH 14/21] doc: unify documentation for 'cp' Robert Schwebel
` (7 subsequent siblings)
20 siblings, 0 replies; 24+ messages in thread
From: Robert Schwebel @ 2010-11-01 8:33 UTC (permalink / raw)
To: barebox
Signed-off-by: Robert Schwebel <r.schwebel@pengutronix.de>
---
commands/partition.c | 50 +++++++++++++++++---------------------------------
1 files changed, 17 insertions(+), 33 deletions(-)
diff --git a/commands/partition.c b/commands/partition.c
index a1edcf6..dd37bc2 100644
--- a/commands/partition.c
+++ b/commands/partition.c
@@ -149,19 +149,23 @@ static int do_addpart(struct command * cmdtp, int argc, char *argv[])
return 0;
}
-static const __maybe_unused char cmd_addpart_help[] =
-"Usage: addpart <device> <partition description>\n"
-"\n"
-"addpart adds a partition description to a device. The partition description\n"
-"has the form\n"
-"size1[@offset1](name1)[ro],size2[@offset2](name2)[ro],...\n"
-"<device> is the device name under. Size and offset can be given in decimal\n"
-"or - if prefixed with 0x in hex. Both can have an optional suffix K,M,G.\n"
-"The size of the last partition can be specified as '-' for the remaining\n"
-"space of the device.\n"
-"This format is the same as used in the Linux kernel for cmdline mtd partitions.\n"
-"\n"
-"Note: That this command has to be reworked and will probably change it's API.";
+BAREBOX_CMD_HELP_START(addpart)
+BAREBOX_CMD_HELP_USAGE("addpart <device> <part_desc>\n")
+BAREBOX_CMD_HELP_SHORT("Add a partition description to a device.\n")
+BAREBOX_CMD_HELP_OPT ("<device>", "device being worked on\n")
+BAREBOX_CMD_HELP_OPT ("<part_desc>", "size1[@offset1](name1)[ro],size2[@offset2](name2)[ro],...\n")
+BAREBOX_CMD_HELP_END
+
+/**
+ * @page addpart_command
+Size and offset can be given in decimal hex (prefixed with 0x). Both
+can have an optional suffix K, M or G. The size of the last partition
+can be specified as '-' for the remaining space on the device. This
+format is the same as used by the Linux kernel or cmdline mtd
+partitions.
+
+\todo This command has to be reworked and will probably change it's API.
+*/
BAREBOX_CMD_START(addpart)
.cmd = do_addpart,
@@ -169,26 +173,6 @@ BAREBOX_CMD_START(addpart)
BAREBOX_CMD_HELP(cmd_addpart_help)
BAREBOX_CMD_END
-/** @page addpart_command addpart Add a partition to a device
- *
- * Usage is: addpart \<device> \<partition description>
- *
- * Adds a partition description to a device. The partition description has the
- * form
- *
- * size1[\@offset1](name1)[ro],size2[\@offset2](name2)[ro],...
- *
- * \<device> is the device name under. Size and offset can be given in decimal
- * or - if prefixed with 0x - in hex. Both can have an optional suffix K,M,G.
- * The size of the last partition can be specified as '-' for the remaining
- * space of the device.
- *
- * @note The format is the same as used in the Linux kernel for cmdline mtd
- * partitions.
- *
- * @note This command has to be reworked and will probably change it's API.
- */
-
static int do_delpart(struct command * cmdtp, int argc, char *argv[])
{
int i, err;
--
1.7.2.3
_______________________________________________
barebox mailing list
barebox@lists.infradead.org
http://lists.infradead.org/mailman/listinfo/barebox
^ permalink raw reply [flat|nested] 24+ messages in thread* [PATCH 14/21] doc: unify documentation for 'cp'
2010-11-01 8:33 Unified Documentation Robert Schwebel
` (12 preceding siblings ...)
2010-11-01 8:33 ` [PATCH 13/21] doc: unify documentation for 'addpart' Robert Schwebel
@ 2010-11-01 8:33 ` Robert Schwebel
2010-11-01 8:33 ` [PATCH 15/21] doc: unify documentation for 'delpart' Robert Schwebel
` (6 subsequent siblings)
20 siblings, 0 replies; 24+ messages in thread
From: Robert Schwebel @ 2010-11-01 8:33 UTC (permalink / raw)
To: barebox
Signed-off-by: Robert Schwebel <r.schwebel@pengutronix.de>
---
commands/cp.c | 30 ++++++++++++++----------------
1 files changed, 14 insertions(+), 16 deletions(-)
diff --git a/commands/cp.c b/commands/cp.c
index 2c35ba1..ae8719b 100644
--- a/commands/cp.c
+++ b/commands/cp.c
@@ -51,7 +51,7 @@ static int do_cp(struct command *cmdtp, int argc, char *argv[])
if (S_ISDIR(statbuf.st_mode))
last_is_dir = 1;
}
-
+
if (argc > 3 && !last_is_dir) {
printf("cp: target `%s' is not a directory\n", argv[argc - 1]);
return 1;
@@ -77,10 +77,19 @@ out:
return ret;
}
-static const __maybe_unused char cmd_cp_help[] =
-"Usage: cp <source> <destination>\n"
-"cp copies file <source> to <destination>.\n"
-"This command is file based only. See memcpy for memory copy\n";
+BAREBOX_CMD_HELP_START(cp)
+BAREBOX_CMD_HELP_USAGE("cp <source> <destination>\n")
+BAREBOX_CMD_HELP_SHORT("copy file from <source> to <destination>.\n")
+BAREBOX_CMD_HELP_END
+
+/**
+ * @page cp_command
+This command operates on files.
+
+If you want to copy between memory blocks, use 'memcpy'.
+
+\todo What does this mean? Add examples.
+ */
BAREBOX_CMD_START(cp)
.cmd = do_cp,
@@ -88,14 +97,3 @@ BAREBOX_CMD_START(cp)
BAREBOX_CMD_HELP(cmd_cp_help)
BAREBOX_CMD_END
-/**
- * @page cp_command cp: Copy file
- *
- * Usage: cp \<source> [\<source>] \<destination>
- *
- * \c cp copies file \<source> to \<destination>
- *
- * Currently only this form is supported and you have to specify the exact
- * target filename (not a target directory).\n
- * This command is file based only. See memcpy for generic memory copy
- */
--
1.7.2.3
_______________________________________________
barebox mailing list
barebox@lists.infradead.org
http://lists.infradead.org/mailman/listinfo/barebox
^ permalink raw reply [flat|nested] 24+ messages in thread* [PATCH 15/21] doc: unify documentation for 'delpart'
2010-11-01 8:33 Unified Documentation Robert Schwebel
` (13 preceding siblings ...)
2010-11-01 8:33 ` [PATCH 14/21] doc: unify documentation for 'cp' Robert Schwebel
@ 2010-11-01 8:33 ` Robert Schwebel
2010-11-01 8:33 ` [PATCH 16/21] doc: rework user manual Robert Schwebel
` (5 subsequent siblings)
20 siblings, 0 replies; 24+ messages in thread
From: Robert Schwebel @ 2010-11-01 8:33 UTC (permalink / raw)
To: barebox
Signed-off-by: Robert Schwebel <r.schwebel@pengutronix.de>
---
commands/partition.c | 35 +++++++++++++++++++++--------------
1 files changed, 21 insertions(+), 14 deletions(-)
diff --git a/commands/partition.c b/commands/partition.c
index dd37bc2..db9b9fb 100644
--- a/commands/partition.c
+++ b/commands/partition.c
@@ -158,11 +158,12 @@ BAREBOX_CMD_HELP_END
/**
* @page addpart_command
-Size and offset can be given in decimal hex (prefixed with 0x). Both
-can have an optional suffix K, M or G. The size of the last partition
-can be specified as '-' for the remaining space on the device. This
-format is the same as used by the Linux kernel or cmdline mtd
-partitions.
+
+The size and the offset can be given in decimal (without any prefix) and
+in hex (prefixed with 0x). Both can have an optional suffix K, M or G.
+The size of the last partition can be specified as '-' for the remaining
+space on the device. This format is the same as used by the Linux
+kernel or cmdline mtd partitions.
\todo This command has to be reworked and will probably change it's API.
*/
@@ -188,9 +189,21 @@ static int do_delpart(struct command * cmdtp, int argc, char *argv[])
return 1;
}
-static const __maybe_unused char cmd_delpart_help[] =
-"Usage: delpart FILE...\n"
-"Delete partitions previously added to a device with addpart.\n";
+BAREBOX_CMD_HELP_START(delpart)
+BAREBOX_CMD_HELP_USAGE("delpart <part 1> [<part n>] \n")
+BAREBOX_CMD_HELP_SHORT("Delete partitions previously added to a device with addpart.\n")
+BAREBOX_CMD_HELP_END
+
+/**
+ * @page delpart_command
+
+Partitions are created by adding their description with the addpart
+command. If you want to get rid of a partition again, use delpart. The
+argument list is taken as a list of partitions to be deleted.
+
+\todo Add an example
+
+ */
BAREBOX_CMD_START(delpart)
.cmd = do_delpart,
@@ -198,9 +211,3 @@ BAREBOX_CMD_START(delpart)
BAREBOX_CMD_HELP(cmd_delpart_help)
BAREBOX_CMD_END
-/** @page delpart_command delpart Delete a partition
- *
- * Usage is: delpart \<partions>
- *
- * Delete a partition previously added to a device with addpart.
- */
--
1.7.2.3
_______________________________________________
barebox mailing list
barebox@lists.infradead.org
http://lists.infradead.org/mailman/listinfo/barebox
^ permalink raw reply [flat|nested] 24+ messages in thread* [PATCH 16/21] doc: rework user manual
2010-11-01 8:33 Unified Documentation Robert Schwebel
` (14 preceding siblings ...)
2010-11-01 8:33 ` [PATCH 15/21] doc: unify documentation for 'delpart' Robert Schwebel
@ 2010-11-01 8:33 ` Robert Schwebel
2010-11-01 8:33 ` [PATCH 17/21] doc: unify documentation for 'devinfo' Robert Schwebel
` (4 subsequent siblings)
20 siblings, 0 replies; 24+ messages in thread
From: Robert Schwebel @ 2010-11-01 8:33 UTC (permalink / raw)
To: barebox
Signed-off-by: Robert Schwebel <r.schwebel@pengutronix.de>
---
Documentation/barebox-main.dox | 232 ++++++++++++----------------------------
Documentation/building.dox | 62 +++++++++++
Documentation/commands.dox | 17 +++-
Documentation/first_steps.dox | 61 +++++++++++
Documentation/users_manual.dox | 12 ++-
5 files changed, 216 insertions(+), 168 deletions(-)
create mode 100644 Documentation/building.dox
create mode 100644 Documentation/first_steps.dox
diff --git a/Documentation/barebox-main.dox b/Documentation/barebox-main.dox
index fb780e6..90fce8e 100644
--- a/Documentation/barebox-main.dox
+++ b/Documentation/barebox-main.dox
@@ -1,166 +1,74 @@
-/** @mainpage Universal Bootloader
-
-@section barebox_intro Introduction
-
-@a Barebox is a bootloader which follows the tradition of U-Boot. U-Boot
-offers an excellent choice as a bootloader for today's embedded systems,
-seen from a user's point of view. Nevertheless, there are quite some
-design flaws which turned out over the last years and we think that they
-cannot be solved in a production tree. So this tree tries to do several
-things right - without caring about losing support for old boards.
-
-@par General features include:
-
-- A posix based file API
- - inside @a barebox the usual open/close/read/write/lseek functions are used.
- This makes it familiar to everyone who has programmed under unix systems.
-
-- usual shell commands like ls/cd/mkdir/echo/cat,...
-
-- The environment is not a variable store anymore, but a file store. It has
- currently some limitations, of course. The environment is not a real
- read/write filesystem, it is more like a tar archive, or even more like
- an ar archive, because it cannot handle directories. The saveenv command
- saves the files under a certain directory (by default /env) in persistent
- storage (by default /dev/env0). There is a counterpart called loadenv, too.
+/** @mainpage Barebox
+
+Barebox is a bootloader that initializes a hardware and boots Linux and
+maybe other operating systems or bare metal code on a variety of
+processors. It was initialy derived from U-Boot and captures up with
+several of it's ideas, so users being familiar with U-Boot should come
+into production quickly with Barebox.
+
+However, as the Barebox developers are highly addicted to the Linux
+kernel, it's coding style and code quality, we try to stick as closely
+as possible to the methodologies and techniques developed in Linux. In
+addition we have a strong background in POSIX, so you'll find several
+good old Unix traditions realized in Barebox as well.
+
+@par Highlights:
+
+- <b>POSIX File API:</b><br>
+ @a Barebox uses the the well known open/close/read/write/lseek access
+ functions, together with a model of representing devices by files. This
+ makes the APIs familiar to everyone who has experience with Unix
+ systems.
+
+- <b>Shell:</b><br>
+ We have the standard shell commands like ls/cd/mkdir/echo/cat,...
+
+- <b>Environment Filesystem:</b><br>
+ In contrast to U-Boot, Barebox doesn't misuse the environment for
+ scripting. If you start the bootloader, it gives you a shell and
+ something that looks like a filesystem. In fact it isn't: it is a very
+ simple ar archive being extracted from flash into a ramdisk with 'loadenv'
+ and stored back with 'saveenv'.
+
+- <b>Filesystem Support:</b><br>
+ When starting up, the environment is mounted to /, followed by a
+ device filesytem being mounted to /dev in order to make it possible to
+ access devices. Other filesystems can be mounted on demand.
+
+- <b>Driver Model (borrowed from Linux):</b><br>
+ Barebox follows the Linux driver model: devices can be specified in a
+ hardware specific file, and drivers feel responsible for these devices
+ if they have the same name.
+
+- <b>Clocksource:</b><br>
+ We use the clocksource API knwon from Linux.
+
+- <b>Kconfig/Kbuild:</b><br>
+ This gives us parallel builds and removes the need for lots of ifdefs.
+
+- <b>Sandbox:</b><br>
+ If you develop features for @a Barebox, you can use the 'sandbox'
+ target which compiles @a Barebox as a POSIX application in the Linux
+ userspace: it can be started like a normal command and even has
+ network access (tun/tap). Files from the local filesytem can be used
+ to simulate devices.
+
+- <b>Device Parameters:</b><br>
+ There is a parameter model in @a Barebox: each device can specify it's
+ own parameters, which do exist for every instance. Parameters can be
+ changed on the command line with \<devid\>.\<param\>="...". For
+ example, if you want to access the IPv4 address for eth0, this is done
+ with 'eth0.ip=192.168.0.7' and 'echo $eth0.ip'.
+
+- <b>Getopt:</b><br>
+ @a Barebox has a lightweight getopt() implementation. This makes it
+ unnecessary to use positional parameters, which can be hard to read.
+
+- <b>Integrated Editor:</b><br>
+ Scripts can be edited with a small integrated fullscreen editor.
+ This editor has no features except the ones really needed: moving
+ the cursor around, typing characters, exiting and saving.
-- Real filesystem support
- - The loader starts up with mounting a ramdisk on /. Then a devfs is mounted
- on /dev allowing the user (or shell commands) to access devices. Apart from
- these two filesystems there is currently one filesystem ported: cramfs. One
- can mount it with the usual mount command.
-
-- device/driver model
- - Devices are no longer described by defines in the config file. Instead
- there are devices which can be registered in the board .c file or
- dynamically allocated. Drivers will match upon the devices automatically.
-
-- clocksource support
- - Timekeeping has been simplified by the use of the Linux clocksource API.
- Only one function is needed for a new board, no [gs]et_timer[masked]() or
- reset_timer[masked]() functions.
-
-- Kconfig and Kernel build system
- - Only targets which are really needed get recompiled. Parallel builds are
- no problem anymore. This also removes the need for many many ifdefs in
- the code.
-
-- simulation target
- - @a barebox can be compiled to run under Linux. While this is rather useless
- in real world this is a great debugging and development aid. New features
- can be easily developed and tested on long train journeys and started
- under gdb. There is a console driver for linux which emulates a serial
- device and a tap based ethernet driver. Linux files can be mapped to
- devices under @a barebox to emulate storage devices.
-
-- device parameter support
- - Each device can have a unlimited number of parameters. They can be accessed
- on the command line with \<devid\>.\<param\>="...", for example
- 'eth0.ip=192.168.0.7' or 'echo $eth0.ip'
-
-- initcalls
- - hooks in the startup process can be achieved with *_initcall() directives
- in each file.
-
-- getopt
- - There is a small getopt implementation. Some commands got really
- complicated (both in code and in usage) due to the fact that @a U-Boot only
- allowed positional parameters.
-
-- editor
- - Scripts can be edited with a small editor. This editor has no features
- except the ones really needed: moving the cursor and typing characters.
-
-@par Building barebox
-
-@a Barebox uses the Linux kernel's build system. It consists of two parts:
-the makefile infrastructure (kbuild), plus a configuration system
-(kconfig). So building @a barebox is very similar to building the Linux
-kernel.
-
-For the examples below, we use the User Mode @a barebox implementation, which
-is a port of @a barebox to the Linux userspace. This makes it possible to
-test drive the code without having real hardware. So for this test
-scenario, @p ARCH=sandbox is the valid architecture selection. This currently
-only works on ia32 hosts and partly on x86-64.
-
-Selection of the architecture and the cross compiler can be done in two
-ways. You can either specify it using the environment variables @p ARCH
-and @p CROSS_COMPILE, or you can create the soft links cross_arch and
-cross_compile pointing to your architecture and compiler. For @p ARCH=sandbox
-we do not need a cross compiler so it is sufficient to specify the
-architecture:
-
-@code # ln -s arch/sandbox cross_arch @endcode
-
-In order to configure the various aspects of @a barebox, start the @a barebox
-configuration system:
-
-@code # make menuconfig @endcode
-
-This command starts a menu box and lets you select all the different
-options available for your architecture. Once the configuration was
-finished (you can simulate this by using the standard demo config file
-with 'make sandbox_defconfig'), there is a .config file in the toplevel
-directory of the sourcecode.
-
-Once @a barebox is configured, we can start the compilation
-
-@code # make @endcode
-
-If everything goes well, the result is a file called @p barebox:
-
-@code
- # ls -l barebox
- -rwxr-xr-x 1 rsc ptx 114073 Jun 26 22:34 barebox
-@endcode
-
-@a barebox usually needs an environment for storing the configuration data.
-You can generate an environment using the example environment contained
-in arch/sanbox/board/env:
-
-@code # ./scripts/bareboxenv -s -p 0x10000 arch/sanbox/board/env/ env.bin @endcode
-
-To get some files to play with you can generate a cramfs image:
-
-@code # mkcramfs somedir/ cramfs.bin @endcode
-
-The @a barebox image is a normal Linux executable, so it can be started
-just like every other program:
-
-@code
- # ./barebox -e env.bin -i cramfs.bin
-
- barebox 2.0.0-trunk (Jun 26 2007 - 22:34:38)
-
- loading environment from /dev/env0
- barebox\> /
-@endcode
-
-Specifying -[ie] \<file\> tells @a barebox to map the file as a device
-under @p /dev. Files given with '-e' will appear as @p /dev/env[n]. Files
-given with '-i' will appear as @p /dev/fd[n].
-If @a barebox finds a valid configuration sector on @p /dev/env0 it will
-load it to @p /env. It then executes @p /env/init if it exists. If you have
-loaded the example environment @a barebox will show you a menu asking for
-your settings.
-
-If you have started @a barebox as root you will find a new tap device on your
-host which you can configure using ifconfig. Once you configured the
-network settings accordingly you can do a ping or tftpboot.
-
-If you have mapped a cramfs image try mounting it with
-
-@code
- # mkdir /cram
- # mount /dev/fd0 cramfs /cram
-@endcode
-
-Memory can be examined as usual using @p md/mw commands. They both understand
-the -f \<file\> option to tell the commands that they should work on the
-specified files instead of @p /dev/mem which holds the complete address space.
-Note that if you call 'md /dev/fd0' (without -f) @a barebox will segfault on
-the host, because it will interpret @p /dev/fd0 as a number.
@par Directory layout
diff --git a/Documentation/building.dox b/Documentation/building.dox
new file mode 100644
index 0000000..895e9ac
--- /dev/null
+++ b/Documentation/building.dox
@@ -0,0 +1,62 @@
+/** @page building Building
+
+<i>This section describes how to build the Barebox bootloader.</i>
+
+@a Barebox uses Kconfig/Kbuild from the Linux kernel to build it's
+sources. It consists of two parts: the makefile infrastructure (kbuild)
+and a configuration system (kconfig). So building @a barebox is very
+similar to building the Linux kernel.
+
+In the examples below we use the "sandbox" configuration, which is a
+port of @a Barebox to the Linux userspace. This makes it possible to
+test the code without having real hardware or even qemu. Note that the
+sandbox architecture does only work well on x86 and has some issues on
+x86_64.
+
+\todo Find out about issues on x86_64.
+
+Selecting the architecture and the corresponding cross compiler can be
+done with two methods: You can either specify it using the environment
+variables @p ARCH and @p CROSS_COMPILE or you can create the soft links
+<i>cross_arch</i> and <i>cross_compile</i>, pointing to your
+architecture and compiler.
+
+\todo How to use the links? This doesn't work!
+
+For @p ARCH=sandbox we do not need a cross compiler, so it is sufficient
+to specify the architecture:
+
+@code
+# ln -s arch/sandbox cross_arch
+@endcode
+
+In order to configure the various aspects of @a barebox, start the
+@a barebox configuration system:
+
+@code
+# make menuconfig
+@endcode
+
+This command starts a menu box and lets you select all the different
+options available for the selected architecture. Once the configuration
+is finished (you can simulate this by using the default config file with
+'make sandbox_defconfig'), there is a .config file in the toplevel
+directory of the sourcecode.
+
+After @a barebox is configured, we can start the compilation:
+
+@code
+# make
+@endcode
+
+You can use '-j \<n\>' in order to do a parallel build if you have more
+than one cpus.
+
+If everything goes well, the result is a file called @p barebox:
+
+@code
+# ls -l barebox
+-rwxr-xr-x 1 rsc ptx 114073 Jun 26 22:34 barebox
+@endcode
+
+*/
diff --git a/Documentation/commands.dox b/Documentation/commands.dox
index 2679ed7..aa489e0 100644
--- a/Documentation/commands.dox
+++ b/Documentation/commands.dox
@@ -1,5 +1,19 @@
/**
- * @page command_reference Supported Shell Commands
+ * @page command_reference Shell Commands
+
+<i>This section describes the commands which are available on the @a
+Barebox shell. </i>
+
+@a Barebox, as a bootloader, usually shall start the Linux kernel right
+away. However, there are several use cases around which make it
+necessary to have some (customizable) logic and interactive scripting
+possibilities. In order to achieve this, @a Barebox offers several
+commands on it's integrated commandline shell.
+
+The following alphabetically sorted list documents all commands
+available in @a Barebox:
+
+\todo Sort this by functionality?
@li @subpage addpart_command
@li @subpage bmp_command
@@ -28,4 +42,5 @@
@li @subpage sh_command
@li @subpage unprotect_command
@li @subpage linux16_command
+
*/
diff --git a/Documentation/first_steps.dox b/Documentation/first_steps.dox
new file mode 100644
index 0000000..edc612f
--- /dev/null
+++ b/Documentation/first_steps.dox
@@ -0,0 +1,61 @@
+/** @page first_steps First Steps
+
+<i>This section demonstrates the first steps with the 'sandbox'
+platform. </i>
+
+@a barebox usually needs an environment for storing it's configuration.
+You can generate an environment using the example-environment contained
+in arch/sanbox/board/env:
+
+@code
+# ./scripts/bareboxenv -s -p 0x10000 arch/sanbox/board/env/ env.bin
+@endcode
+
+To get some files to play with you can generate a cramfs image:
+
+@code
+# mkcramfs somedir/ cramfs.bin
+@endcode
+
+The @a barebox image is a normal Linux executable, so it can be started
+just like every other program:
+
+@code
+# ./barebox -e env.bin -i cramfs.bin
+
+barebox 2010.10.0 (Oct 29 2010 - 13:47:17)
+
+loading environment from /dev/env0
+barebox\> /
+@endcode
+
+Specifying -[ie] \<file\> tells @a barebox to map the file as a device
+under @p /dev. Files given with '-e' will appear as @p /dev/env[n]. Files
+given with '-i' will appear as @p /dev/fd[n].
+
+If @a barebox finds a valid configuration sector on @p /dev/env0, it
+will be loaded into @p /env and executes @p /env/init if existing.
+The default environment from the example above will show up a menu
+asking for the relevant settings.
+
+If you have started @a barebox as root you will find a new tap device on
+your host which you can configure using ifconfig. Once configured with
+valid network addresses, barebox can be used to ping the host machine or
+to fetch files with tftp.
+
+\todo Add more about tun/tap configuration
+
+If you have mapped a cramfs image, try mounting it with
+
+@code
+# mkdir /cram
+# mount /dev/fd0 cramfs /cram
+@endcode
+
+Memory can be examined using @p md/mw commands. They both understand the
+-f \<file\> option to tell the commands that they should work on the
+specified files instead of @p /dev/mem (which holds the complete address
+space). Note that if you call 'md /dev/fd0' (without -f), @a barebox will
+segfault on the host, because it will interpret @p /dev/fd0 as a number.
+
+*/
diff --git a/Documentation/users_manual.dox b/Documentation/users_manual.dox
index 0a0a13e..bbc7911 100644
--- a/Documentation/users_manual.dox
+++ b/Documentation/users_manual.dox
@@ -1,14 +1,16 @@
/** @page users_manual User's Manual
-Who should read this part?
+This manual provides help for working with @a Barebox from the user's
+point of view. So if you want to use @a Barebox for booting your target,
+you find a lot of nice tricks on these pages to make your life easier.
-Mostly everyone. The user needs it to find help for his daily work to manage
-his targets. The developer to find out all the new features that make his
-work easier.
+@li @subpage building
+@li @subpage first_steps
+@li @subpage command_reference
+\todo Rework the following sections
@li @subpage shell_notes
@li @subpage readline_parser
-@li @subpage command_reference
@li @subpage x86_bootloader
@li @subpage net_netconsole
--
1.7.2.3
_______________________________________________
barebox mailing list
barebox@lists.infradead.org
http://lists.infradead.org/mailman/listinfo/barebox
^ permalink raw reply [flat|nested] 24+ messages in thread* [PATCH 17/21] doc: unify documentation for 'devinfo'
2010-11-01 8:33 Unified Documentation Robert Schwebel
` (15 preceding siblings ...)
2010-11-01 8:33 ` [PATCH 16/21] doc: rework user manual Robert Schwebel
@ 2010-11-01 8:33 ` Robert Schwebel
2010-11-01 8:33 ` [PATCH 18/21] doc: unify documentation for 'erase' Robert Schwebel
` (3 subsequent siblings)
20 siblings, 0 replies; 24+ messages in thread
From: Robert Schwebel @ 2010-11-01 8:33 UTC (permalink / raw)
To: barebox
Signed-off-by: Robert Schwebel <r.schwebel@pengutronix.de>
---
Doxyfile | 4 +++-
lib/driver.c | 45 +++++++++++++++++++++++----------------------
2 files changed, 26 insertions(+), 23 deletions(-)
diff --git a/Doxyfile b/Doxyfile
index 23f3e43..f030584 100644
--- a/Doxyfile
+++ b/Doxyfile
@@ -1067,7 +1067,9 @@ INCLUDE_FILE_PATTERNS =
# undefined via #undef or recursively expanded use the := operator
# instead of the = operator.
-PREDEFINED = DOXYGEN_SHOULD_SKIP_THIS
+PREDEFINED = \
+ DOXYGEN_SHOULD_SKIP_THIS \
+ CONFIG_CMD_DEVINFO
# If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then
# this tag can be used to specify a list of macro names that should be expanded.
diff --git a/lib/driver.c b/lib/driver.c
index edde1dc..aba04e7 100644
--- a/lib/driver.c
+++ b/lib/driver.c
@@ -244,6 +244,7 @@ int dummy_probe(struct device_d *dev)
}
EXPORT_SYMBOL(dummy_probe);
+#ifdef CONFIG_CMD_DEVINFO
static int do_devinfo_subtree(struct device_d *dev, int depth, char edge)
{
struct device_d *child;
@@ -275,6 +276,7 @@ static int do_devinfo_subtree(struct device_d *dev, int depth, char edge)
return 0;
}
+#endif
const char *dev_id(const struct device_d *dev)
{
@@ -340,30 +342,22 @@ static int do_devinfo(struct command *cmdtp, int argc, char *argv[])
return 0;
}
-static const __maybe_unused char cmd_devinfo_help[] =
-"Usage: devinfo [DEVICE]\n"
-"If called without arguments devinfo shows a summary about known devices and\n"
-"drivers. If called with a device path as argument devinfo shows more detailed\n"
-"information about this device and its parameters.\n";
+BAREBOX_CMD_HELP_START(devinfo)
+BAREBOX_CMD_HELP_USAGE("devinfo [DEVICE]\n")
+BAREBOX_CMD_HELP_SHORT("Output device information.")
+BAREBOX_CMD_HELP_END
-BAREBOX_CMD_START(devinfo)
- .cmd = do_devinfo,
- .usage = "display info about devices and drivers",
- BAREBOX_CMD_HELP(cmd_devinfo_help)
-BAREBOX_CMD_END
+/**
+ * @page devinfo_command
-#endif
+If called without arguments, devinfo shows a summary of the known
+devices and drivers.
+
+If called with a device path being the argument, devinfo shows more
+default information about this device and its parameters.
+
+Example from an MPC5200 based system:
-/**
- * @page devinfo_command devinfo
- *
- * Usage is: devinfo /dev/\<device>
- *
- * If called without arguments devinfo shows a summary about known devices and
- * drivers. If called with a device path as argument devinfo shows more
- * detailed information about this device and its parameters.
- *
- * Example from an MPC5200 based system:
@verbatim
barebox:/ devinfo /dev/eth0
base : 0x1002b000
@@ -378,5 +372,12 @@ BAREBOX_CMD_END
netmask = 255.255.255.0
serverip = 192.168.23.2
@endverbatim
- *
*/
+
+BAREBOX_CMD_START(devinfo)
+ .cmd = do_devinfo,
+ .usage = "Show information about devices and drivers.\n",
+ BAREBOX_CMD_HELP(cmd_devinfo_help)
+BAREBOX_CMD_END
+#endif
+
--
1.7.2.3
_______________________________________________
barebox mailing list
barebox@lists.infradead.org
http://lists.infradead.org/mailman/listinfo/barebox
^ permalink raw reply [flat|nested] 24+ messages in thread* [PATCH 18/21] doc: unify documentation for 'erase'
2010-11-01 8:33 Unified Documentation Robert Schwebel
` (16 preceding siblings ...)
2010-11-01 8:33 ` [PATCH 17/21] doc: unify documentation for 'devinfo' Robert Schwebel
@ 2010-11-01 8:33 ` Robert Schwebel
2010-11-01 8:33 ` [PATCH 19/21] doc: rework and unify documentation for gpio commands Robert Schwebel
` (2 subsequent siblings)
20 siblings, 0 replies; 24+ messages in thread
From: Robert Schwebel @ 2010-11-01 8:33 UTC (permalink / raw)
To: barebox
Signed-off-by: Robert Schwebel <r.schwebel@pengutronix.de>
---
commands/flash.c | 30 ++++++++++++++++--------------
1 files changed, 16 insertions(+), 14 deletions(-)
diff --git a/commands/flash.c b/commands/flash.c
index 20f5cfc..c855c88 100644
--- a/commands/flash.c
+++ b/commands/flash.c
@@ -83,10 +83,10 @@ out:
return ret;
}
-static const __maybe_unused char cmd_erase_help[] =
-"Usage: erase <device> [area]\n"
-"Erase a flash device or parts of a device if an area specification\n"
-"is given\n";
+BAREBOX_CMD_HELP_START(erase)
+BAREBOX_CMD_HELP_USAGE("erase <device> [area]")
+BAREBOX_CMD_HELP_SHORT("Erase a flash device or parts of a device if an area specification is given.")
+BAREBOX_CMD_HELP_END
BAREBOX_CMD_START(erase)
.cmd = do_flerase,
@@ -94,16 +94,18 @@ BAREBOX_CMD_START(erase)
BAREBOX_CMD_HELP(cmd_erase_help)
BAREBOX_CMD_END
-/** @page erase_command erase Erase flash memory
- *
- * Usage is: erase \<devicee>
- *
- * Erase the flash memory behind the device. It depends on the device given,
- * what area will be erased. If the device represents the whole flash memory
- * the whole memory will be erased. If the device represents a partition on
- * a main flash memory, only this partition part will be erased.
- *
- * Refer \b addpart, \b delpart and \b devinfo for partition handling.
+/**
+ * @page erase_command
+
+<p> Erase the flash memory handled by this device. Which area will be
+erased depends on the device: If the device represents the whole flash
+memory, the whole memory will be erased. If the device represents a
+partition on a main flash memory, only this partition part will be
+erased. </p>
+
+Refer to \ref addpart_command, \ref delpart_command and \ref
+devinfo_command for partition handling.
+
*/
static int do_protect(struct command *cmdtp, int argc, char *argv[])
--
1.7.2.3
_______________________________________________
barebox mailing list
barebox@lists.infradead.org
http://lists.infradead.org/mailman/listinfo/barebox
^ permalink raw reply [flat|nested] 24+ messages in thread* [PATCH 19/21] doc: rework and unify documentation for gpio commands
2010-11-01 8:33 Unified Documentation Robert Schwebel
` (17 preceding siblings ...)
2010-11-01 8:33 ` [PATCH 18/21] doc: unify documentation for 'erase' Robert Schwebel
@ 2010-11-01 8:33 ` Robert Schwebel
2010-11-01 8:33 ` [PATCH 20/21] doc: unify documentation for 'export' Robert Schwebel
2010-11-01 8:33 ` [PATCH 21/21] doc: unify documentation for 'tftp' Robert Schwebel
20 siblings, 0 replies; 24+ messages in thread
From: Robert Schwebel @ 2010-11-01 8:33 UTC (permalink / raw)
To: barebox
Signed-off-by: Robert Schwebel <r.schwebel@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
-@li @subpage gpio_for_users
+@li @subpage gpio_get_value_command
+@li @subpage gpio_set_value_command
+@li @subpage gpio_direction_input_command
+@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
+@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
/**
-@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
-@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.
-@section gpio_dir_out Switch a pad into an output GPIO
+@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
-@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>
-@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
+@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
-@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>
-@section gpio_get_value Read in the value of an GPIO input pad
+@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>
-@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>
-@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>
-@section gpio_set_value Set a new value to a GPIO output pad
+@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>
-@note If the pad is not configured for GPIO mode this command may fail (silently)
*/
--
1.7.2.3
_______________________________________________
barebox mailing list
barebox@lists.infradead.org
http://lists.infradead.org/mailman/listinfo/barebox
^ permalink raw reply [flat|nested] 24+ messages in thread* [PATCH 20/21] doc: unify documentation for 'export'
2010-11-01 8:33 Unified Documentation Robert Schwebel
` (18 preceding siblings ...)
2010-11-01 8:33 ` [PATCH 19/21] doc: rework and unify documentation for gpio commands Robert Schwebel
@ 2010-11-01 8:33 ` Robert Schwebel
2010-11-01 8:33 ` [PATCH 21/21] doc: unify documentation for 'tftp' Robert Schwebel
20 siblings, 0 replies; 24+ messages in thread
From: Robert Schwebel @ 2010-11-01 8:33 UTC (permalink / raw)
To: barebox
Signed-off-by: Robert Schwebel <r.schwebel@pengutronix.de>
---
commands/export.c | 14 ++++----------
1 files changed, 4 insertions(+), 10 deletions(-)
diff --git a/commands/export.c b/commands/export.c
index 31259cc..ce8a61a 100644
--- a/commands/export.c
+++ b/commands/export.c
@@ -51,9 +51,10 @@ static int do_export(struct command *cmdtp, int argc, char *argv[])
return 0;
}
-static const __maybe_unused char cmd_export_help[] =
-"Usage: export <var>[=value]...\n"
-"export an environment variable to subsequently executed scripts\n";
+BAREBOX_CMD_HELP_START(export)
+BAREBOX_CMD_HELP_USAGE("export <var>[=value]")
+BAREBOX_CMD_HELP_SHORT("export an environment variable to subsequently executed scripts")
+BAREBOX_CMD_HELP_END
BAREBOX_CMD_START(export)
.cmd = do_export,
@@ -61,10 +62,3 @@ BAREBOX_CMD_START(export)
BAREBOX_CMD_HELP(cmd_export_help)
BAREBOX_CMD_END
-/**
- * @page export_command export: Export an environment variable
- *
- * Usage: export \<var>[=value]...
- *
- * Export an environment variable to subsequently executed scripts.
- */
--
1.7.2.3
_______________________________________________
barebox mailing list
barebox@lists.infradead.org
http://lists.infradead.org/mailman/listinfo/barebox
^ permalink raw reply [flat|nested] 24+ messages in thread* [PATCH 21/21] doc: unify documentation for 'tftp'
2010-11-01 8:33 Unified Documentation Robert Schwebel
` (19 preceding siblings ...)
2010-11-01 8:33 ` [PATCH 20/21] doc: unify documentation for 'export' Robert Schwebel
@ 2010-11-01 8:33 ` Robert Schwebel
20 siblings, 0 replies; 24+ messages in thread
From: Robert Schwebel @ 2010-11-01 8:33 UTC (permalink / raw)
To: barebox
Signed-off-by: Robert Schwebel <r.schwebel@pengutronix.de>
---
Doxyfile | 3 ++-
net/tftp.c | 49 +++++++++++++++++++++----------------------------
2 files changed, 23 insertions(+), 29 deletions(-)
diff --git a/Doxyfile b/Doxyfile
index f030584..d9ce22c 100644
--- a/Doxyfile
+++ b/Doxyfile
@@ -1069,7 +1069,8 @@ INCLUDE_FILE_PATTERNS =
PREDEFINED = \
DOXYGEN_SHOULD_SKIP_THIS \
- CONFIG_CMD_DEVINFO
+ CONFIG_CMD_DEVINFO \
+ CONFIG_NET_TFTP_PUSH
# If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then
# this tag can be used to specify a list of macro names that should be expanded.
diff --git a/net/tftp.c b/net/tftp.c
index 6345a72..c7f9b8c 100644
--- a/net/tftp.c
+++ b/net/tftp.c
@@ -364,15 +364,29 @@ out_close:
return tftp_err == 0 ? 0 : 1;
}
-static const __maybe_unused char cmd_tftp_help[] =
-"Usage: tftp <remotefile> [localfile]\n"
-"Load a file from a TFTP server.\n"
+BAREBOX_CMD_HELP_START(tftp)
#ifdef CONFIG_NET_TFTP_PUSH
-"or\n"
-" tftp -p <localfile> [remotefile]\n"
-"Upload a file to a TFTP server\n"
+BAREBOX_CMD_HELP_USAGE("tftp <remotefile> [localfile], tftp -p <localfile> [remotefile]\n")
+BAREBOX_CMD_HELP_SHORT("Load a file from or upload to TFTP server.")
+BAREBOX_CMD_HELP_END
+#else
+BAREBOX_CMD_HELP_USAGE("tftp <remotefile> [localfile]\n")
+BAREBOX_CMD_HELP_SHORT("Load a file from a TFTP server.")
+BAREBOX_CMD_HELP_END
#endif
-;
+
+/**
+ * @page tftp_command
+
+The second file argument can be skipped in which case the first filename
+is used (without the directory part).
+
+\<localfile> can be the local filename or a device file under /dev.
+This also works for flash memory. Refer to \ref erase_command and \ref
+unprotect_command for flash preparation.
+
+\note This command is available only if enabled in menuconfig.
+ */
BAREBOX_CMD_START(tftp)
.cmd = do_tftpb,
@@ -384,24 +398,3 @@ BAREBOX_CMD_START(tftp)
BAREBOX_CMD_HELP(cmd_tftp_help)
BAREBOX_CMD_END
-/**
- * @page tftp_command tftp
- *
- * Usage:
- * tftp \<remotefilename\> [\<localfilename\>]
- *
- * or
- *
- * tftp -p \<localfilename\> [\<remotefilename\>]
- *
- * Load a file from a tftp server or upload a file to a tftp server if
- * the -p option is given. The second file argument can be skipped in
- * which case the first filename is used (without the directory part).
- *
- * \<localfile> can be the local filename or a device file under /dev.
- * This also works for flash memory. Refer to \b erase, \b unprotect for
- * flash preparation.
- *
- * Note: This command is available only if enabled in menuconfig.
- */
-
--
1.7.2.3
_______________________________________________
barebox mailing list
barebox@lists.infradead.org
http://lists.infradead.org/mailman/listinfo/barebox
^ permalink raw reply [flat|nested] 24+ messages in thread