Unified Documentation

Unified Documentation

[Robert Schwebel]

This series contains the next round of documentation rework, in order to
avoid the duplication of several documentation sniplets between the
compiled-in documentation (help <command>) and the online documentation
managed by Doxygen.

Since these patches have been posted last time, I've reworked the awk
script that generates the Doxygen input slightly. It is now possible to
add long prosa text blocks which do only appear in the online manual.

The following changes since commit bd8db893bb65e32952f8389d37f868e2c6f82d21:

  doc: silence doxygen warnings (2010-10-22 20:47:03 +0200)

are available in the git repository at:
  http://git.pengutronix.de/git/rsc/barebox ..BRANCH.NOT.VERIFIED..

Robert Schwebel (21):
      doc: fix typo
      doc: add macros to unify command help with doxygen
      doc: add documentation for 'bmp'
      doc: add documentation for 'clear'
      doc: add documentation for 'crc32'
      doc: add documentation for 'dfu'
      doc: unify documentation for 'ls'
      doc: unify documentation for 'cat'
      doc: unify documentation for 'cd'
      doc: add documentation for 'echo'
      doc: unify documentation for 'edit'
      doc: add documentation for 'bootm'
      doc: unify documentation for 'addpart'
      doc: unify documentation for 'cp'
      doc: unify documentation for 'delpart'
      doc: rework user manual
      doc: unify documentation for 'devinfo'
      doc: unify documentation for 'erase'
      doc: rework and unify documentation for gpio commands
      doc: unify documentation for 'export'
      doc: unify documentation for 'tftp'

 Documentation/barebox-main.dox        |  232 ++++++++++-----------------------
 Documentation/building.dox            |   62 +++++++++
 Documentation/commands.dox            |   29 ++++-
 Documentation/first_steps.dox         |   61 +++++++++
 Documentation/users_manual.dox        |   13 +-
 Doxyfile                              |    7 +-
 arch/arm/mach-s3c24xx/lowlevel-init.S |    2 +-
 commands/bmp.c                        |   27 +++-
 commands/bootm.c                      |   38 +++---
 commands/cat.c                        |   19 +--
 commands/cd.c                         |   17 +--
 commands/clear.c                      |    5 +
 commands/cp.c                         |   30 ++---
 commands/crc.c                        |   15 +-
 commands/dfu.c                        |   28 +++--
 commands/echo.c                       |   17 +++
 commands/edit.c                       |   38 ++----
 commands/export.c                     |   14 +--
 commands/flash.c                      |   30 +++--
 commands/gpio.c                       |  100 ++++++++-------
 commands/ls.c                         |    9 +-
 commands/partition.c                  |   75 +++++------
 include/command.h                     |    9 ++
 lib/driver.c                          |   45 ++++---
 net/tftp.c                            |   49 +++----
 scripts/doxy_filter.awk               |  103 +++++++++++++++
 26 files changed, 627 insertions(+), 447 deletions(-)
 create mode 100644 Documentation/building.dox
 create mode 100644 Documentation/first_steps.dox
 create mode 100644 scripts/doxy_filter.awk


_______________________________________________
barebox mailing list
barebox@lists.infradead.org
http://lists.infradead.org/mailman/listinfo/barebox

[PATCH 01/21] doc: fix typo

[Robert Schwebel]

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

[PATCH 02/21] doc: add macros to unify command help with doxygen

[Robert Schwebel]

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("<", "\\&lt;", "g");
+	$0 = gensub(">", "\\&gt;", "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("<", "\\&lt;", "g");
+	$0 = gensub(">", "\\&gt;", "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("<", "\\&lt;", "g");
+	$0 = gensub(">", "\\&gt;", "g");
+	$0 = gensub("@", "\\\\@",    "g");	
+	$0 = gensub("BAREBOX_CMD_HELP_OPT[[:space:]]*\\([[:space:]]*\"*(.*)\"[[:space:]]*,[[:space:]]*\"(.*)\"[[:space:]]*\\)", \
+		"<tr><td><tt> \\1 </tt></td><td>\\&nbsp;\\&nbsp;\\&nbsp;</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("<", "\\&lt;", "g");
+	$0 = gensub(">", "\\&gt;", "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

[PATCH 03/21] doc: add documentation for 'bmp'

[Robert Schwebel]

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

[PATCH 04/21] doc: add documentation for 'clear'

[Robert Schwebel]

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

[PATCH 05/21] doc: add documentation for 'crc32'

[Robert Schwebel]

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

[PATCH 06/21] doc: add documentation for 'dfu'

[Robert Schwebel]

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

[PATCH 07/21] doc: unify documentation for 'ls'

[Robert Schwebel]

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

[PATCH 08/21] doc: unify documentation for 'cat'

[Robert Schwebel]

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

[PATCH 09/21] doc: unify documentation for 'cd'

[Robert Schwebel]

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

[PATCH 10/21] doc: add documentation for 'echo'

[Robert Schwebel]

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

[PATCH 11/21] doc: unify documentation for 'edit'

[Robert Schwebel]

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

[PATCH 12/21] doc: add documentation for 'bootm'

[Robert Schwebel]

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

[PATCH 13/21] doc: unify documentation for 'addpart'

[Robert Schwebel]

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

[PATCH 14/21] doc: unify documentation for 'cp'

[Robert Schwebel]

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

[PATCH 15/21] doc: unify documentation for 'delpart'

[Robert Schwebel]

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

[PATCH 16/21] doc: rework user manual

[Robert Schwebel]

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

[PATCH 17/21] doc: unify documentation for 'devinfo'

[Robert Schwebel]

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

[PATCH 18/21] doc: unify documentation for 'erase'

[Robert Schwebel]

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

[PATCH 19/21] doc: rework and unify documentation for gpio commands

[Robert Schwebel]

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

[PATCH 20/21] doc: unify documentation for 'export'

[Robert Schwebel]

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

[PATCH 21/21] doc: unify documentation for 'tftp'

[Robert Schwebel]

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

Re: [PATCH 06/21] doc: add documentation for 'dfu'

[Baruch Siach]

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

Re: [PATCH 06/21] doc: add documentation for 'dfu'

[Robert Schwebel]

On Mon, Nov 01, 2010 at 10:51:02AM +0200, Baruch Siach wrote:
> Should probably be:
> device1(name1)[sr],device2(name2)[sr]

Fixed and pushed, thanks.

rsc
-- 
Pengutronix e.K.                           |                             |
Industrial Linux Solutions                 | http://www.pengutronix.de/  |
Peiner Str. 6-8, 31137 Hildesheim, Germany | Phone: +49-5121-206917-0    |
Amtsgericht Hildesheim, HRA 2686           | Fax:   +49-5121-206917-5555 |

_______________________________________________
barebox mailing list
barebox@lists.infradead.org
http://lists.infradead.org/mailman/listinfo/barebox