[U-Boot] [RFC 2/3] uboot-doc: Add example support for uboot-doc

John Schmoller
2009-07-28T16:34:02Z

Add support to a small subset of commands, environment
variables, and POSTs. These are meant to show the
syntax and capabilities of the uboot-doc parser.

Signed-off-by: John Schmoller <jschmoller@xes-inc.com>
---
common/cmd_i2c.c | 71 ++++++++++++++++++++++++++++++++++++++++++++++++++-
common/cmd_mem.c | 45 +++++++++++++++++++++++++++++++-
common/cmd_net.c | 30 ++++++++++++++++++++-
common/env_common.c | 35 +++++++++++++++++++++++++
post/tests.c | 16 +++++++++++
5 files changed, 192 insertions(+), 5 deletions(-)

diff --git a/common/cmd_i2c.c b/common/cmd_i2c.c
index 8f0fc9e..14d394c 100644
--- a/common/cmd_i2c.c
+++ b/common/cmd_i2c.c
@@ -1297,7 +1297,70 @@ int do_i2c(cmd_tbl_t * cmdtp, int flag, int argc, char *argv[])
}

/***************************************************/
-
+/**
+ * @cmd: i2c speed
+ * @sect: I2C
+ * @param[or]: speed - target I2C bus speed
+ * @desc: Show or set I2C bus speed
+ */
+/**
+ * @cmd: i2c dev
+ * @sect: I2C
+ * @param[or]: dev - I2C device to make current
+ * @desc: Show or set current I2C bus
+ */
+/**
+ * @cmd: i2c md
+ * @sect: I2C
+ * @param: chip - I2C address of desired device
+ * @param: address[.0, .1, .2] - Address into I2C device
+ * @param[or]: # of objects - Numer of bytes to read
+ * @desc: Read from I2C device
+ */
+/**
+ * @cmd: i2c mm
+ * @sect: I2C
+ * @param: chip - I2C address of desired device
+ * @param: address[.0, .1, .2] - Address into I2C device
+ * @desc: Write to I2C device (auto-incrementing)
+ */
+/**
+ * @cmd: i2c mw
+ * @sect: I2C
+ * @param: chip - I2C address of desired device
+ * @param: address[.0, .1, .2] - Address into I2C device
+ * @param: value - Value to write to I2C address
+ * @param[or]: count - Number of bytes to write
+ * @desc: Write to I2C device (fill)
+ */
+/**
+ * @cmd: i2c nm
+ * @sect: I2C
+ * @param: chip - I2C address of desired device
+ * @param: address[.0, .1, .2] - Address into I2C device
+ * @desc: Write to I2C device (constant address)
+ */
+/**
+ * @cmd: i2c crc32
+ * @sect: I2C
+ * @param: chip - I2C address of desired device
+ * @param: address[.0, .1, .2] - Address into I2C device
+ * @param: count - Number of bytes to CRC
+ * @desc: Computes the CRC32 checksum of an address range
+ */
+/**
+ * @cmd: i2c probe
+ * @sect: I2C
+ * @desc: Shows all the devices on the I2C bus
+ */
+/**
+ * @cmd: i2c loop
+ * @sect: I2C
+ * @param: chip - I2C address of desired device
+ * @param: address[.0, .1, .2] - Address into I2C device
+ * @param: # of objects - Number of bytes to loop over
+ * @desc: Looping read of device. Never returns.
+ */
U_BOOT_CMD(
i2c, 6, 1, do_i2c,
"I2C sub-system",
@@ -1317,6 +1380,12 @@ U_BOOT_CMD(
"i2c reset - re-init the I2C Controller\n"
"i2c loop chip address[.0, .1, .2] [# of objects] - looping read of device"
#if defined(CONFIG_CMD_SDRAM)
+/**
+ * @cmd: isdram
+ * @sect: I2C
+ * @param: chip - I2C address of desired device
+ * @desc: Prints SDRAM configuration information
+ */
"\n"
"i2c sdram chip - print SDRAM configuration information"
#endif
diff --git a/common/cmd_mem.c b/common/cmd_mem.c
index cdf8c79..2276a1a 100644
--- a/common/cmd_mem.c
+++ b/common/cmd_mem.c
@@ -1169,20 +1169,61 @@ int do_unzip ( cmd_tbl_t *cmdtp, int flag, int argc, char *argv[])

/**************************************************/
+/**
+ * @cmd: md
+ * @sect: Memory
+ * @param[or]: address - memory location to display
+ * @param[or]: objs - Number of objects to display
+ * @desc: The md command displays memory contents both as hexadecimal and
+ * ASCII data. The last displayed memory address and the value of the
+ * count argument are remembered, so when you enter md again without
+ * arguments it will automatically continue at the next address, and use
+ * the same count again.
+ *
+ * If invoked as md or md.l, data is displayed as 32-bit long words. If
+ * invoked as md.w or md.b instead, 16-bit words or 8-bit bytes are used,
+ * respectively.
+ */
U_BOOT_CMD(
md, 3, 1, do_mem_md,
"memory display",
"[.b, .w, .l] address [# of objects]"
);

-
+/**
+ * @cmd: mm
+ * @sect: Memory
+ * @param[or]: address - memory location to modify
+ * @desc: The mm command is a method to interactively modify memory contents.
+ * It will display the address and current contents and then prompt for
+ * user input. If you enter a legal hexadecimal number, this new value
+ * will be written to the address. Then, the next address will be
+ * prompted. If you don't enter any value and just press ENTER, then the
+ * contents of this address will remain unchanged. The command stops as
+ * soon as you enter any data that is not a hex number.
+ *
+ * If invoked as mm or mm.l, data is displayed as 32-bit long words. If
+ * invoked as mm.w or mm.b instead, 16-bit words or 8-bit bytes are used,
+ * respectively.
+ */
U_BOOT_CMD(
mm, 2, 1, do_mem_mm,
"memory modify (auto-incrementing address)",
"[.b, .w, .l] address"
);

-
+/**
+ * @cmd: nm
+ * @sect: Memory
+ * @param[or]: address - memory location to modify
+ * @desc: The nm command (non-incrementing memory modify) can be used to
+ * interactively write different data several times to the same address.
+ * This can be useful, for instance, to access and modify device registers.
+ *
+ * If invoked as nm or nm.l, data is modified as a 32-bit long word. If
+ * invoked as nm.w or nm.b instead, 16-bit words or 8-bit bytes are used,
+ * respectively.
+ */
U_BOOT_CMD(
nm, 2, 1, do_mem_nm,
"memory modify (constant address)",
diff --git a/common/cmd_net.c b/common/cmd_net.c
index 88f4e5b..7760230 100644
--- a/common/cmd_net.c
+++ b/common/cmd_net.c
@@ -47,7 +47,24 @@ int do_tftpb (cmd_tbl_t *cmdtp, int flag, int argc, char *argv[])
{
return netboot_common (TFTP, cmdtp, argc, argv);
}
-
+/**
+ * @cmd: tftpboot
+ * @sect: Networking
+ * @param[r]: loadAddress - address to store downloaded file
+ * @param[or]: [hostIPaddr:]bootfilename - file to download from specified IP
+ * @desc: The tftpboot command downloads a file from the
+ * network using the TFTP protocol. @eipaddr, @eserverip,
+ * @egatewayip, and @enetmask must be set prior to
+ * calling tftpboot.
+ * If loadAddress is specified, the file will be
+ * downloaded to this address. If not specified, the
+ * file will be downloaded to the address specified by the
+ * @eloadaddr environment varaible. A load file can
+ * either be specified by the bootfilename or by the
+ * @efileaddr. A host IP address can be specified when
+ * a bootfilename is specified by prepending it to
+ * bootfilename (ie XX.XX.XX.XX:file).
+ */
U_BOOT_CMD(
tftpboot, 3, 1, do_tftpb,
"boot image via network using TFTP protocol",
@@ -265,7 +282,16 @@ int do_ping (cmd_tbl_t *cmdtp, int flag, int argc, char *argv[])

return 0;
}
-
+/**
+ * @cmd: ping
+ * @sect: Networking
+ * @param[r]: addr - IP address to send Echo Request packet
+ * @desc: The ping command checks to see if a specific
+ * IP address is alive by sending an ICMP Echo
+ * Request packet. If the device specified by
+ * addr responds before a timeout occurs, ping
+ * reports that the board is alive.
+ */
U_BOOT_CMD(
ping, 2, 1, do_ping,
"send ICMP ECHO_REQUEST to network host",
diff --git a/common/env_common.c b/common/env_common.c
index 6be3bb0..e55ebce 100644
--- a/common/env_common.c
+++ b/common/env_common.c
@@ -97,9 +97,23 @@ uchar default_environment[] = {
#ifdef CONFIG_ETH5ADDR
"eth5addr=" MK_STR(CONFIG_ETH5ADDR) "\0"
#endif
+#ifdef CONFIG_CMD_NET
+ /**
+ * @env: ipaddr
+ * @sect: Networking
+ * @desc: IP address of this board
+ */
+#endif
#ifdef CONFIG_IPADDR
"ipaddr=" MK_STR(CONFIG_IPADDR) "\0"
#endif
+#ifdef CONFIG_CMD_NET
+ /**
+ * @env: serverip
+ * @sect: Networking
+ * @desc: IP address of the server
+ */
+#endif
#ifdef CONFIG_SERVERIP
"serverip=" MK_STR(CONFIG_SERVERIP) "\0"
#endif
@@ -112,9 +126,23 @@ uchar default_environment[] = {
#ifdef CONFIG_ROOTPATH
"rootpath=" MK_STR(CONFIG_ROOTPATH) "\0"
#endif
+#ifdef CONFIG_CMD_NET
+ /**
+ * @env: gatewayip
+ * @sect: Networking
+ * @desc: IP address of the next hop gateway
+ */
+#endif
#ifdef CONFIG_GATEWAYIP
"gatewayip=" MK_STR(CONFIG_GATEWAYIP) "\0"
#endif
+#ifdef CONFIG_CMD_NET
+ /**
+ * @env: netmask
+ * @sect: Networking
+ * @desc: Network mask to reach gateway
+ */
+#endif
#ifdef CONFIG_NETMASK
"netmask=" MK_STR(CONFIG_NETMASK) "\0"
#endif
@@ -124,6 +152,13 @@ uchar default_environment[] = {
#ifdef CONFIG_BOOTFILE
"bootfile=" MK_STR(CONFIG_BOOTFILE) "\0"
#endif
+#ifdef CONFIG_CMD_NET
+ /**
+ * @env: loadaddr
+ * @sect: Networking
+ * @desc: Address in memory to store downloaded files
+ */
+#endif
#ifdef CONFIG_LOADADDR
"loadaddr=" MK_STR(CONFIG_LOADADDR) "\0"
#endif
diff --git a/post/tests.c b/post/tests.c
index 3224f00..1bee185 100644
--- a/post/tests.c
+++ b/post/tests.c
@@ -102,6 +102,14 @@ struct post_test post_list[] =
#endif
#endif
#if CONFIG_POST & CONFIG_SYS_POST_I2C
+ /**
+ * @post: I2C Post
+ * @desc: The I2C POST verifies that a pre-assembled list of devices and
+ * only those devices respond to an I2C bus scan. This list is assembled
+ * in the board-specific config file as the board is developed. If a
+ * device doesn't respond, or a device which is not in the list responds,
+ * the POST will fail.
+ */
{
"I2C test",
"i2c",
@@ -126,6 +134,14 @@ struct post_test post_list[] =
},
#endif
#if CONFIG_POST & CONFIG_SYS_POST_MEMORY
+ /**
+ * @post: Memory Post
+ * @desc:The Memory POST verifies RAM by performing the following tests:
+ * pattern(zeros, ones, 0x5 checkerboard, 0xa checkerboard), bit-flip
+ * pattern, address pattern (offset), and address pattern (~offset).
+ * The POST verifies only small 4Kb regions of RAM around each 1Mb
+ * boundary.
+ */
{
"Memory test",
"memory",
--
1.6.0.4