[U-Boot] [PATCH 7/7] Add documentation for bootgraph.pl

[Andrew Murray]

From: Andrew Murray <amurray at mpcdata.com>

Documentation for the CONFIG_BOOT_TRACE option.

Signed-off-by: Andrew Murray <amurray at theiet.org>
---
 doc/README.bootgraph |   57 ++++++++++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 57 insertions(+), 0 deletions(-)
 create mode 100644 doc/README.bootgraph

diff --git a/doc/README.bootgraph b/doc/README.bootgraph
new file mode 100644
index 0000000..af8d9e4
--- /dev/null
+++ b/doc/README.bootgraph
@@ -0,0 +1,57 @@
+Bootgraph Instrumentation
+-------------------------
+
+The CONFIG_BOOT_TRACE configuration option can be defined to output extensive
+instrumentation to assist in boot time reduction. The tools/bootgraph.pl script
+can utilise this instrumentation to generate an SVG graph showing where UBoot
+spends its time.
+
+When enabled all printf output is prefixed with timing information similar
+to the Linux kernel's CONFIG_PRINTK_TIME option. This allows you to measure the
+interval between operations which is useful for identifying long delays during
+UBoot operation. For example:
+
+[    3.133000] ## Booting kernel from Legacy Image at 82000000 ...
+[    3.139000]    Image Name:   Angstrom/2.6.32/beagleboard
+
+When enabled additional console output will be generated - this output includes
+the addresses of executed commands and instrumented functions. For example:
+
+[    2.456000] initcall 0x9ff86814 returned
+[    2.460000] calling  0x9ff7c338
+[    2.590000] initcall 0x9ff7c338 returned
+[    2.594000] calling  0x9ff864ac
+
+At present executed commands are only displayed when the HUSH parser
+(CONFIG_SYS_HUSH_PARSER) is not being used.
+
+Functions such as initialisation code can be instrumented by using the
+DO_INITCALLXXX macros found in include/common.h (see arch/arm/lib/board.c) for
+examples). For example:
+
+@@ -508,7 +518,7 @@ void board_init_r (gd_t *id, ulong dest_addr)
+
+ #ifdef CONFIG_GENERIC_MMC
+        puts("MMC:   ");
+-       mmc_initialize(bd);
++       DO_INITCALL(mmc_initialize, bd);
+ #endif
+
+For functions that do not return such as do_bootm function, the DO_INITCALL_END
+macro can be used to mark the latest point of the function.
+
+When CONFIG_BOOT_TIME is not defined the DO_INITCALLXXX macros continue to call
+the intended function and should not add overhead.
+
+An SVG graph can be generated which allows for the visualisation of UBoot boot
+time by using the tools/bootgraph.pl script. This script has been ported from
+the Linux kernel (scripts/bootgraph.pl) and is used in a similar way. For
+example:
+
+cat console_output | perl ./tools/bootgraph.pl > graph.svg
+
+Assuming console_output is a file containing the console output of UBoot with
+CONFIG_BOOT_TRACE enabled - the graph.svg file should provide a graphical
+representation of boot time with resolved function addresses.
+
+Andrew Murray <amurray at theiet.org>
-- 
1.7.4.1