From c2067021556a623a56b931cf3975f0fe1e195cb7 Mon Sep 17 00:00:00 2001 From: Heinrich Schuchardt Date: Sun, 20 Sep 2020 12:01:30 +0200 Subject: doc/build/gcc.rst: required packages for SUSE Describe the packages required to build U-Boot on SUSE. Signed-off-by: Heinrich Schuchardt --- doc/build/gcc.rst | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/doc/build/gcc.rst b/doc/build/gcc.rst index 1ceba0b..c51b3e7 100644 --- a/doc/build/gcc.rst +++ b/doc/build/gcc.rst @@ -29,6 +29,26 @@ Depending on the build targets further packages maybe needed lzma-alone openssl python3 python3-coverage python3-pyelftools \ python3-pytest python3-sphinxcontrib.apidoc python3-sphinx-rtd-theme swig +SUSE based +~~~~~~~~~~ + +On suse based systems the cross compiler packages are named +cross--gcc. + +You could install GCC and the GCC 10 cross compiler for the ARMv8 architecture +with + +.. code-block:: bash + + sudo zypper install gcc cross-aarch64-gcc10 + +Depending on the build targets further packages maybe needed. + +.. code-block:: bash + + zypper install bc bison flex gcc libopenssl-devel libSDL2-devel make \ + ncurses-devel python3-devel python3-pytest swig + Prerequisites ------------- -- cgit v1.1 From b2107a4b77458424d60dda05e778319eadcde0ed Mon Sep 17 00:00:00 2001 From: Heinrich Schuchardt Date: Thu, 15 Oct 2020 07:40:57 +0200 Subject: doc: global data pointer on x86, x86_64 On x86 the global data pointer is stored in register fs. On x86_64 no register is used for the global data pointer. Signed-off-by: Heinrich Schuchardt Reviewed-by: Simon Glass --- doc/develop/global_data.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/doc/develop/global_data.rst b/doc/develop/global_data.rst index 9e7c8a2..230ebcd 100644 --- a/doc/develop/global_data.rst +++ b/doc/develop/global_data.rst @@ -33,8 +33,10 @@ On most architectures the global data pointer is stored in a register. +------------+----------+ | SuperH | r13 | +------------+----------+ +| x86 32bit | fs | ++------------+----------+ -The sandbox, x86, and Xtensa are notable exceptions. +The sandbox, x86_64, and Xtensa are notable exceptions. Clang for ARM does not support assigning a global register. When using Clang gd is defined as an inline function using assembly code. This adds a few bytes -- cgit v1.1 From ae2b48e84a6b954b56f3e68f5fd2cde3484422cd Mon Sep 17 00:00:00 2001 From: Heinrich Schuchardt Date: Mon, 30 Nov 2020 09:52:57 +0100 Subject: doc: allow building htmldoc with Sphinx 3+ Due to removed function c_funcptr_sig_re building with Sphinx 3 fails. With the patch building succeeds with a lot of warnings if the '-W' flag is removed from doc/Makefile. Most of the documentation is correct This follows the approach taken by the Linux kernel. Signed-off-by: Heinrich Schuchardt --- doc/conf.py | 29 ++++++++++++++++++++++++++++- 1 file changed, 28 insertions(+), 1 deletion(-) diff --git a/doc/conf.py b/doc/conf.py index 93250a6..ee7f201 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -36,7 +36,34 @@ latex_engine = 'xelatex' # Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. -extensions = ['kerneldoc', 'rstFlatTable', 'kernel_include', 'cdomain', 'kfigure'] +extensions = ['kerneldoc', 'rstFlatTable', 'kernel_include', 'kfigure'] + +# +# cdomain is badly broken in Sphinx 3+. Leaving it out generates *most* +# of the docs correctly, but not all. +# +if major >= 3: + if (major > 3) or (minor > 0 or patch >= 2): + sys.stderr.write('''The build process with Sphinx 3+ is broken. +You will have to remove -W in doc/Makefile. +''') + # Sphinx c function parser is more pedantic with regards to type + # checking. Due to that, having macros at c:function cause problems. + # Those needed to be escaped by using c_id_attributes[] array + c_id_attributes = [ + + # include/linux/compiler.h + "__maybe_unused", + + # include/efi.h + "EFIAPI", + + # include/efi_loader.h + "__efi_runtime", + ] + +else: + extensions.append('cdomain') # The name of the math extension changed on Sphinx 1.4 if (major == 1 and minor > 3) or (major > 1): -- cgit v1.1 From 380c6b94dae83463d8f0d737ec548ba90dabfc8a Mon Sep 17 00:00:00 2001 From: Heinrich Schuchardt Date: Sat, 12 Dec 2020 08:33:28 +0100 Subject: doc: move README.commands to HTML doc Reformat README.commands as reStructured text and add it to the HTML documentation as develop/commands.rst. Signed-off-by: Heinrich Schuchardt Reviewed-by: Simon Glass --- doc/README.commands | 186 -------------------------------------- doc/develop/commands.rst | 226 +++++++++++++++++++++++++++++++++++++++++++++++ doc/develop/index.rst | 1 + 3 files changed, 227 insertions(+), 186 deletions(-) delete mode 100644 doc/README.commands create mode 100644 doc/develop/commands.rst diff --git a/doc/README.commands b/doc/README.commands deleted file mode 100644 index 22ab063..0000000 --- a/doc/README.commands +++ /dev/null @@ -1,186 +0,0 @@ -Command definition ------------------- - -Commands are added to U-Boot by creating a new command structure. -This is done by first including command.h, then using the U_BOOT_CMD() or the -U_BOOT_CMD_COMPLETE macro to fill in a struct cmd_tbl struct. - -U_BOOT_CMD(name, maxargs, repeatable, command, "usage", "help") -U_BOOT_CMD_COMPLETE(name, maxargs, repeatable, command, "usage, "help", comp) - -name: The name of the command. THIS IS NOT a string. - -maxargs: The maximum number of arguments this function takes including - the command itself. - -repeatable: Either 0 or 1 to indicate if autorepeat is allowed. - -command: Pointer to the command function. This is the function that is - called when the command is issued. - -usage: Short description. This is a string. - -help: Long description. This is a string. The long description is - only available if CONFIG_SYS_LONGHELP is defined. - -comp: Pointer to the completion function. May be NULL. - This function is called if the user hits the TAB key while - entering the command arguments to complete the entry. Command - completion is only available if CONFIG_AUTO_COMPLETE is defined. - -Sub-command definition ----------------------- - -Likewise an array of struct cmd_tbl holding sub-commands can be created using either -of the following macros: - -* U_BOOT_CMD_MKENT(name, maxargs, repeatable, command, "usage", "help") -* U_BOOT_CMD_MKENTCOMPLETE(name, maxargs, repeatable, command, "usage, "help", - comp) - -This table has to be evaluated in the command function of the main command, e.g. - - static struct cmd_tbl cmd_sub[] = { - U_BOOT_CMD_MKENT(foo, CONFIG_SYS_MAXARGS, 1, do_foo, "", ""), - U_BOOT_CMD_MKENT(bar, CONFIG_SYS_MAXARGS, 1, do_bar, "", ""), - }; - - static int do_cmd(struct cmd_tbl *cmdtp, int flag, int argc, char *const argv[]) - { - struct cmd_tbl *cp; - - if (argc < 2) - return CMD_RET_USAGE; - - /* drop sub-command argument */ - argc--; - argv++; - - cp = find_cmd_tbl(argv[0], cmd_ut_sub, ARRAY_SIZE(cmd_sub)); - - if (cp) - return cp->cmd(cmdtp, flag, argc, argv); - - return CMD_RET_USAGE; - } - -Command function ----------------- - -The command function pointer has to be of type -int (*cmd)(struct cmd_tbl *cmdtp, int flag, int argc, const char *argv[]); - -cmdtp: Table entry describing the command (see above). - -flag: A bitmap which may contain the following bit: - CMD_FLAG_REPEAT - The last command is repeated. - CMD_FLAG_BOOTD - The command is called by the bootd command. - CMD_FLAG_ENV - The command is called by the run command. - -argc: Number of arguments including the command. - -argv: Arguments. - -Allowable return value are: - -CMD_RET_SUCCESS The command was successfully executed. - -CMD_RET_FAILURE The command failed. - -CMD_RET_USAGE The command was called with invalid parameters. This value - leads to the display of the usage string. - -Completion function -------------------- - -The completion function pointer has to be of type -int (*complete)(int argc, char *const argv[], char last_char, - int maxv, char *cmdv[]); - -argc: Number of arguments including the command. - -argv: Arguments. - -last_char: The last character in the command line buffer. - -maxv: Maximum number of possible completions that may be returned by - the function. - -cmdv: Used to return possible values for the last argument. The last - possible completion must be followed by NULL. - -The function returns the number of possible completions (without the terminating -NULL value). - -Behind the scene ----------------- - -The structure created is named with a special prefix and placed by -the linker in a special section using the linker lists mechanism -(see include/linker_lists.h) - -This makes it possible for the final link to extract all commands -compiled into any object code and construct a static array so the -command array can be iterated over using the linker lists macros. - -The linker lists feature ensures that the linker does not discard -these symbols when linking full U-Boot even though they are not -referenced in the source code as such. - -If a new board is defined do not forget to define the command section -by writing in u-boot.lds ($(srctree)/board/boardname/u-boot.lds) these -3 lines: - - .u_boot_list : { - KEEP(*(SORT(.u_boot_list*))); - } - -Writing tests -------------- - -All new commands should have tests. Tests for existing commands are very -welcome. - -It is fairly easy to write a test for a command. Enable it in sandbox, and -then add code that runs the command and checks the output. - -Here is an example: - -/* Test 'acpi items' command */ -static int dm_test_acpi_cmd_items(struct unit_test_state *uts) -{ - struct acpi_ctx ctx; - void *buf; - - buf = malloc(BUF_SIZE); - ut_assertnonnull(buf); - - ctx.current = buf; - ut_assertok(acpi_fill_ssdt(&ctx)); - console_record_reset(); - run_command("acpi items", 0); - ut_assert_nextline("dev 'acpi-test', type 1, size 2"); - ut_assert_nextline("dev 'acpi-test2', type 1, size 2"); - ut_assert_console_end(); - - ctx.current = buf; - ut_assertok(acpi_inject_dsdt(&ctx)); - console_record_reset(); - run_command("acpi items", 0); - ut_assert_nextline("dev 'acpi-test', type 2, size 2"); - ut_assert_nextline("dev 'acpi-test2', type 2, size 2"); - ut_assert_console_end(); - - console_record_reset(); - run_command("acpi items -d", 0); - ut_assert_nextline("dev 'acpi-test', type 2, size 2"); - ut_assert_nextlines_are_dump(2); - ut_assert_nextline("%s", ""); - ut_assert_nextline("dev 'acpi-test2', type 2, size 2"); - ut_assert_nextlines_are_dump(2); - ut_assert_nextline("%s", ""); - ut_assert_console_end(); - - return 0; -} -DM_TEST(dm_test_acpi_cmd_items, UT_TESTF_SCAN_PDATA | UT_TESTF_SCAN_FDT); diff --git a/doc/develop/commands.rst b/doc/develop/commands.rst new file mode 100644 index 0000000..c72d1b0 --- /dev/null +++ b/doc/develop/commands.rst @@ -0,0 +1,226 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +Implementing shell commands +=========================== + +Command definition +------------------ + +Commands are added to U-Boot by creating a new command structure. +This is done by first including command.h, then using the U_BOOT_CMD() or the +U_BOOT_CMD_COMPLETE macro to fill in a struct cmd_tbl structure. + +.. code-block:: c + + U_BOOT_CMD(name, maxargs, repeatable, command, "usage", "help") + U_BOOT_CMD_COMPLETE(name, maxargs, repeatable, command, "usage, "help", comp) + +name + The name of the command. This is **not** a string. + +maxargs + The maximum number of arguments this function takes including + the command itself. + +repeatable + Either 0 or 1 to indicate if autorepeat is allowed. + +command + Pointer to the command function. This is the function that is + called when the command is issued. + +usage + Short description. This is a string. + +help + Long description. This is a string. The long description is + only available if CONFIG_SYS_LONGHELP is defined. + +comp + Pointer to the completion function. May be NULL. + This function is called if the user hits the TAB key while + entering the command arguments to complete the entry. Command + completion is only available if CONFIG_AUTO_COMPLETE is defined. + +Sub-command definition +---------------------- + +Likewise an array of struct cmd_tbl holding sub-commands can be created using +either of the following macros: + +.. code-block:: c + + U_BOOT_CMD_MKENT(name, maxargs, repeatable, command, "usage", "help") + U_BOOT_CMD_MKENTCOMPLETE(name, maxargs, repeatable, command, "usage, "help", comp) + +This table has to be evaluated in the command function of the main command, e.g. + +.. code-block:: c + + static struct cmd_tbl cmd_sub[] = { + U_BOOT_CMD_MKENT(foo, CONFIG_SYS_MAXARGS, 1, do_foo, "", ""), + U_BOOT_CMD_MKENT(bar, CONFIG_SYS_MAXARGS, 1, do_bar, "", ""), + }; + + static int do_cmd(struct cmd_tbl *cmdtp, int flag, int argc, char *const argv[]) + { + struct cmd_tbl *cp; + + if (argc < 2) + return CMD_RET_USAGE; + + /* drop sub-command argument */ + argc--; + argv++; + + cp = find_cmd_tbl(argv[0], cmd_ut_sub, ARRAY_SIZE(cmd_sub)); + + if (cp) + return cp->cmd(cmdtp, flag, argc, argv); + + return CMD_RET_USAGE; + } + +Command function +---------------- + +The command function pointer has to be of type + +.. code-block:: c + + int (*cmd)(struct cmd_tbl *cmdtp, int flag, int argc, const char *argv[]); + +cmdtp + Table entry describing the command (see above). + +flag + A bitmap which may contain the following bits + + * CMD_FLAG_REPEAT - The last command is repeated. + * CMD_FLAG_BOOTD - The command is called by the bootd command. + * CMD_FLAG_ENV - The command is called by the run command. + +argc + Number of arguments including the command. + +argv + Arguments. + +Allowable return value are: + +CMD_RET_SUCCESS + The command was successfully executed. + +CMD_RET_FAILURE + The command failed. + +CMD_RET_USAGE + The command was called with invalid parameters. This value + leads to the display of the usage string. + +Completion function +------------------- + +The completion function pointer has to be of type + +.. code-block:: c + + int (*complete)(int argc, char *const argv[], char last_char, + int maxv, char *cmdv[]); + +argc + Number of arguments including the command. + +argv + Arguments. + +last_char + The last character in the command line buffer. + +maxv + Maximum number of possible completions that may be returned by + the function. + +cmdv + Used to return possible values for the last argument. The last + possible completion must be followed by NULL. + +The function returns the number of possible completions (without the terminating +NULL value). + +Behind the scene +---------------- + +The structure created is named with a special prefix and placed by +the linker in a special section using the linker lists mechanism +(see include/linker_lists.h) + +This makes it possible for the final link to extract all commands +compiled into any object code and construct a static array so the +command array can be iterated over using the linker lists macros. + +The linker lists feature ensures that the linker does not discard +these symbols when linking full U-Boot even though they are not +referenced in the source code as such. + +If a new board is defined do not forget to define the command section +by writing in u-boot.lds ($(srctree)/board/boardname/u-boot.lds) these +3 lines: + +.. code-block:: c + + .u_boot_list : { + KEEP(*(SORT(.u_boot_list*))); + } + +Writing tests +------------- + +All new commands should have tests. Tests for existing commands are very +welcome. + +It is fairly easy to write a test for a command. Enable it in sandbox, and +then add code that runs the command and checks the output. + +Here is an example: + +.. code-block:: c + + /* Test 'acpi items' command */ + static int dm_test_acpi_cmd_items(struct unit_test_state *uts) + { + struct acpi_ctx ctx; + void *buf; + + buf = malloc(BUF_SIZE); + ut_assertnonnull(buf); + + ctx.current = buf; + ut_assertok(acpi_fill_ssdt(&ctx)); + console_record_reset(); + run_command("acpi items", 0); + ut_assert_nextline("dev 'acpi-test', type 1, size 2"); + ut_assert_nextline("dev 'acpi-test2', type 1, size 2"); + ut_assert_console_end(); + + ctx.current = buf; + ut_assertok(acpi_inject_dsdt(&ctx)); + console_record_reset(); + run_command("acpi items", 0); + ut_assert_nextline("dev 'acpi-test', type 2, size 2"); + ut_assert_nextline("dev 'acpi-test2', type 2, size 2"); + ut_assert_console_end(); + + console_record_reset(); + run_command("acpi items -d", 0); + ut_assert_nextline("dev 'acpi-test', type 2, size 2"); + ut_assert_nextlines_are_dump(2); + ut_assert_nextline("%s", ""); + ut_assert_nextline("dev 'acpi-test2', type 2, size 2"); + ut_assert_nextlines_are_dump(2); + ut_assert_nextline("%s", ""); + ut_assert_console_end(); + + return 0; + } + DM_TEST(dm_test_acpi_cmd_items, UT_TESTF_SCAN_PDATA | UT_TESTF_SCAN_FDT); diff --git a/doc/develop/index.rst b/doc/develop/index.rst index 89e80ea..c95a8d6 100644 --- a/doc/develop/index.rst +++ b/doc/develop/index.rst @@ -8,6 +8,7 @@ Develop U-Boot :maxdepth: 2 coccinelle + commands crash_dumps global_data logging -- cgit v1.1 From d2472dedbd1682dfb618204ae289deee253506ad Mon Sep 17 00:00:00 2001 From: Heinrich Schuchardt Date: Sat, 12 Dec 2020 08:50:37 +0100 Subject: doc: move pstore.rst to usage/pstore.rst Let's have a separate chapter dedicated to using U-Boot. Signed-off-by: Heinrich Schuchardt --- doc/index.rst | 8 +---- doc/pstore.rst | 82 ---------------------------------------------------- doc/usage/index.rst | 12 ++++++++ doc/usage/pstore.rst | 82 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 95 insertions(+), 89 deletions(-) delete mode 100644 doc/pstore.rst create mode 100644 doc/usage/index.rst create mode 100644 doc/usage/pstore.rst diff --git a/doc/index.rst b/doc/index.rst index 68a083b..4c44955 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -25,6 +25,7 @@ trying to get it to work optimally on a given system. :maxdepth: 2 build/index + usage/index Developer-oriented documentation -------------------------------- @@ -109,13 +110,6 @@ Android-specific features available in U-Boot. android/index -Command line ------------- -.. toctree:: - :maxdepth: 2 - - pstore.rst - Indices and tables ================== diff --git a/doc/pstore.rst b/doc/pstore.rst deleted file mode 100644 index 8427d8f..0000000 --- a/doc/pstore.rst +++ /dev/null @@ -1,82 +0,0 @@ -.. SPDX-License-Identifier: GPL-2.0+ - -PStore command -============== - -Design ------- - -Linux PStore and Ramoops modules (Linux config options PSTORE and PSTORE_RAM) -allow to use memory to pass data from the dying breath of a crashing kernel to -its successor. This command allows to read those records from U-Boot command -line. - -Ramoops is an oops/panic logger that writes its logs to RAM before the system -crashes. It works by logging oopses and panics in a circular buffer. Ramoops -needs a system with persistent RAM so that the content of that area can survive -after a restart. - -Ramoops uses a predefined memory area to store the dump. - -Ramoops parameters can be passed as kernel parameters or through Device Tree, -i.e.:: - - ramoops.mem_address=0x30000000 ramoops.mem_size=0x100000 ramoops.record_size=0x2000 ramoops.console_size=0x2000 memmap=0x100000$0x30000000 - -The same values should be set in U-Boot to be able to retrieve the records. -This values can be set at build time in U-Boot configuration file, or at runtime. -U-Boot automatically patches the Device Tree to pass the Ramoops parameters to -the kernel. - -The PStore configuration parameters are: - -======================= ========== - Name Default -======================= ========== -CMD_PSTORE_MEM_ADDR -CMD_PSTORE_MEM_SIZE 0x10000 -CMD_PSTORE_RECORD_SIZE 0x1000 -CMD_PSTORE_CONSOLE_SIZE 0x1000 -CMD_PSTORE_FTRACE_SIZE 0x1000 -CMD_PSTORE_PMSG_SIZE 0x1000 -CMD_PSTORE_ECC_SIZE 0 -======================= ========== - -Records sizes should be a power of 2. -The memory size and the record/console size must be non-zero. - -Multiple 'dump' records can be stored in the memory reserved for PStore. -The memory size has to be larger than the sum of the record sizes, i.e.:: - - MEM_SIZE >= RECORD_SIZE * n + CONSOLE_SIZE + FTRACE_SIZE + PMSG_SIZE - -Usage ------ - -Generate kernel crash -~~~~~~~~~~~~~~~~~~~~~ - -For test purpose, you can generate a kernel crash by setting reboot timeout to -10 seconds and trigger a panic:: - - $ sudo sh -c "echo 1 > /proc/sys/kernel/sysrq" - $ sudo sh -c "echo 10 > /proc/sys/kernel/panic" - $ sudo sh -c "echo c > /proc/sysrq-trigger" - -Retrieve logs in U-Boot -~~~~~~~~~~~~~~~~~~~~~~~ - -First of all, unless PStore parameters as been set during U-Boot configuration -and match kernel ramoops parameters, it needs to be set using 'pstore set', e.g.:: - - => pstore set 0x30000000 0x100000 0x2000 0x2000 - -Then all available dumps can be displayed -using:: - - => pstore display - -Or saved to an existing directory in an Ext2 or Ext4 partition, e.g. on root -directory of 1st partition of the 2nd MMC:: - - => pstore save mmc 1:1 / diff --git a/doc/usage/index.rst b/doc/usage/index.rst new file mode 100644 index 0000000..af7d506 --- /dev/null +++ b/doc/usage/index.rst @@ -0,0 +1,12 @@ +Use U-Boot +========== + +.. toctree:: + +Shell commands +-------------- + +.. toctree:: + :maxdepth: 1 + + pstore diff --git a/doc/usage/pstore.rst b/doc/usage/pstore.rst new file mode 100644 index 0000000..8427d8f --- /dev/null +++ b/doc/usage/pstore.rst @@ -0,0 +1,82 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +PStore command +============== + +Design +------ + +Linux PStore and Ramoops modules (Linux config options PSTORE and PSTORE_RAM) +allow to use memory to pass data from the dying breath of a crashing kernel to +its successor. This command allows to read those records from U-Boot command +line. + +Ramoops is an oops/panic logger that writes its logs to RAM before the system +crashes. It works by logging oopses and panics in a circular buffer. Ramoops +needs a system with persistent RAM so that the content of that area can survive +after a restart. + +Ramoops uses a predefined memory area to store the dump. + +Ramoops parameters can be passed as kernel parameters or through Device Tree, +i.e.:: + + ramoops.mem_address=0x30000000 ramoops.mem_size=0x100000 ramoops.record_size=0x2000 ramoops.console_size=0x2000 memmap=0x100000$0x30000000 + +The same values should be set in U-Boot to be able to retrieve the records. +This values can be set at build time in U-Boot configuration file, or at runtime. +U-Boot automatically patches the Device Tree to pass the Ramoops parameters to +the kernel. + +The PStore configuration parameters are: + +======================= ========== + Name Default +======================= ========== +CMD_PSTORE_MEM_ADDR +CMD_PSTORE_MEM_SIZE 0x10000 +CMD_PSTORE_RECORD_SIZE 0x1000 +CMD_PSTORE_CONSOLE_SIZE 0x1000 +CMD_PSTORE_FTRACE_SIZE 0x1000 +CMD_PSTORE_PMSG_SIZE 0x1000 +CMD_PSTORE_ECC_SIZE 0 +======================= ========== + +Records sizes should be a power of 2. +The memory size and the record/console size must be non-zero. + +Multiple 'dump' records can be stored in the memory reserved for PStore. +The memory size has to be larger than the sum of the record sizes, i.e.:: + + MEM_SIZE >= RECORD_SIZE * n + CONSOLE_SIZE + FTRACE_SIZE + PMSG_SIZE + +Usage +----- + +Generate kernel crash +~~~~~~~~~~~~~~~~~~~~~ + +For test purpose, you can generate a kernel crash by setting reboot timeout to +10 seconds and trigger a panic:: + + $ sudo sh -c "echo 1 > /proc/sys/kernel/sysrq" + $ sudo sh -c "echo 10 > /proc/sys/kernel/panic" + $ sudo sh -c "echo c > /proc/sysrq-trigger" + +Retrieve logs in U-Boot +~~~~~~~~~~~~~~~~~~~~~~~ + +First of all, unless PStore parameters as been set during U-Boot configuration +and match kernel ramoops parameters, it needs to be set using 'pstore set', e.g.:: + + => pstore set 0x30000000 0x100000 0x2000 0x2000 + +Then all available dumps can be displayed +using:: + + => pstore display + +Or saved to an existing directory in an Ext2 or Ext4 partition, e.g. on root +directory of 1st partition of the 2nd MMC:: + + => pstore save mmc 1:1 / -- cgit v1.1 From 9ebb71f70d8367b7f5030d507a43acb34252a984 Mon Sep 17 00:00:00 2001 From: Heinrich Schuchardt Date: Sat, 12 Dec 2020 09:00:12 +0100 Subject: doc: use code-block in pstore.rst Use syntax highlighting for a Linux console session. Signed-off-by: Heinrich Schuchardt --- doc/usage/pstore.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/doc/usage/pstore.rst b/doc/usage/pstore.rst index 8427d8f..8c4e527 100644 --- a/doc/usage/pstore.rst +++ b/doc/usage/pstore.rst @@ -57,7 +57,9 @@ Generate kernel crash ~~~~~~~~~~~~~~~~~~~~~ For test purpose, you can generate a kernel crash by setting reboot timeout to -10 seconds and trigger a panic:: +10 seconds and trigger a panic + +.. code-block:: console $ sudo sh -c "echo 1 > /proc/sys/kernel/sysrq" $ sudo sh -c "echo 10 > /proc/sys/kernel/panic" -- cgit v1.1 From d0253f7e5ca1e1d79a6c42aea330cb9e2355211a Mon Sep 17 00:00:00 2001 From: Heinrich Schuchardt Date: Sat, 12 Dec 2020 09:37:47 +0100 Subject: doc: move README.NetConsole to HTML documentation Convert README.NetConsole to reStructured text and move it to doc/usage/netconsole.rst. Signed-off-by: Heinrich Schuchardt Reviewed-by: Simon Glass --- doc/README.NetConsole | 97 ----------------------------------------- doc/usage/index.rst | 2 + doc/usage/netconsole.rst | 109 +++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 111 insertions(+), 97 deletions(-) delete mode 100644 doc/README.NetConsole create mode 100644 doc/usage/netconsole.rst diff --git a/doc/README.NetConsole b/doc/README.NetConsole deleted file mode 100644 index af7fc60..0000000 --- a/doc/README.NetConsole +++ /dev/null @@ -1,97 +0,0 @@ - -In U-Boot, we implemented the networked console via the standard -"devices" mechanism, which means that you can switch between the -serial and network input/output devices by adjusting the 'stdin' and -'stdout' environment variables. To switch to the networked console, -set either of these variables to "nc". Input and output can be -switched independently. - -CONFIG_NETCONSOLE_BUFFER_SIZE - Override the default buffer size - -We use an environment variable 'ncip' to set the IP address and the -port of the destination. The format is :. If is -omitted, the value of 6666 is used. If the env var doesn't exist, the -broadcast address and port 6666 are used. If it is set to an IP -address of 0 (or 0.0.0.0) then no messages are sent to the network. -The source / listening port can be configured separately by setting -the 'ncinport' environment variable and the destination port can be -configured by setting the 'ncoutport' environment variable. - -For example, if your server IP is 192.168.1.1, you could use: - - => setenv nc 'setenv stdout nc;setenv stdin nc' - => setenv ncip 192.168.1.1 - => saveenv - => run nc - - -On the host side, please use this script to access the console: - - tools/netconsole [port] - -The script uses netcat to talk to the board over UDP. It requires you to -specify the target IP address (or host name, assuming DNS is working). The -script can be interrupted by pressing ^T (CTRL-T). - -Be aware that in some distributives (Fedora Core 5 at least) -usage of nc has been changed and -l and -p options are considered -as mutually exclusive. If nc complains about options provided, -you can just remove the -p option from the script. - -It turns out that 'netcat' cannot be used to listen to broadcast -packets. We developed our own tool 'ncb' (see tools directory) that -listens to broadcast packets on a given port and dumps them to the -standard output. It will be built when compiling for a board which -has CONFIG_NETCONSOLE defined. If the netconsole script can find it -in PATH or in the same directory, it will be used instead. - -For Linux, the network-based console needs special configuration. -Minimally, the host IP address needs to be specified. This can be -done either via the kernel command line, or by passing parameters -while loading the netconsole.o module (when used in a loadable module -configuration). Please refer to Documentation/networking/logging.txt -file for the original Ingo Molnar's documentation on how to pass -parameters to the loadable module. - -The format of the kernel command line parameter (for the static -configuration) is as follows: - - netconsole=[src-port]@[src-ip]/[],[tgt-port]@/[tgt-macaddr] - -where - - src-port source for UDP packets - (defaults to 6665) - src-ip source IP to use - (defaults to the interface's address) - dev network interface - (defaults to eth0) - tgt-port port for logging agent - (defaults to 6666) - tgt-ip IP address for logging agent - (this is the required parameter) - tgt-macaddr ethernet MAC address for logging agent - (defaults to broadcast) - -Examples: - - netconsole=4444@10.0.0.1/eth1,9353@10.0.0.2/12:34:56:78:9a:bc - -or - - netconsole=@/,@192.168.3.1/ - -Please note that for the Linux networked console to work, the -ethernet interface has to be up by the time the netconsole driver is -initialized. This means that in case of static kernel configuration, -the respective Ethernet interface has to be brought up using the "IP -Autoconfiguration" kernel feature, which is usually done by defaults -in the ELDK-NFS-based environment. - -To browse the Linux network console output, use the 'netcat' tool invoked -as follows: - - nc -u -l -p 6666 - -Note that unlike the U-Boot implementation the Linux netconsole is -unidirectional, i. e. you have console output only in Linux. diff --git a/doc/usage/index.rst b/doc/usage/index.rst index af7d506..063e970 100644 --- a/doc/usage/index.rst +++ b/doc/usage/index.rst @@ -3,6 +3,8 @@ Use U-Boot .. toctree:: + netconsole + Shell commands -------------- diff --git a/doc/usage/netconsole.rst b/doc/usage/netconsole.rst new file mode 100644 index 0000000..0156f02 --- /dev/null +++ b/doc/usage/netconsole.rst @@ -0,0 +1,109 @@ +Network console +=============== + +In U-Boot, we implemented the networked console via the standard +"devices" mechanism, which means that you can switch between the +serial and network input/output devices by adjusting the 'stdin' and +'stdout' environment variables. To switch to the networked console, +set either of these variables to "nc". Input and output can be +switched independently. + +The default buffer size can be overridden by setting +CONFIG_NETCONSOLE_BUFFER_SIZE. + +We use an environment variable 'ncip' to set the IP address and the +port of the destination. The format is :. If is +omitted, the value of 6666 is used. If the env var doesn't exist, the +broadcast address and port 6666 are used. If it is set to an IP +address of 0 (or 0.0.0.0) then no messages are sent to the network. +The source / listening port can be configured separately by setting +the 'ncinport' environment variable and the destination port can be +configured by setting the 'ncoutport' environment variable. + +For example, if your server IP is 192.168.1.1, you could use:: + + => setenv nc 'setenv stdout nc;setenv stdin nc' + => setenv ncip 192.168.1.1 + => saveenv + => run nc + +On the host side, please use this script to access the console + +.. code-block:: bash + + tools/netconsole [port] + +The script uses netcat to talk to the board over UDP. It requires you to +specify the target IP address (or host name, assuming DNS is working). The +script can be interrupted by pressing ^T (CTRL-T). + +Be aware that in some distributives (Fedora Core 5 at least) +usage of nc has been changed and -l and -p options are considered +as mutually exclusive. If nc complains about options provided, +you can just remove the -p option from the script. + +It turns out that 'netcat' cannot be used to listen to broadcast +packets. We developed our own tool 'ncb' (see tools directory) that +listens to broadcast packets on a given port and dumps them to the +standard output. It will be built when compiling for a board which +has CONFIG_NETCONSOLE defined. If the netconsole script can find it +in PATH or in the same directory, it will be used instead. + +For Linux, the network-based console needs special configuration. +Minimally, the host IP address needs to be specified. This can be +done either via the kernel command line, or by passing parameters +while loading the netconsole.o module (when used in a loadable module +configuration). Please refer to Documentation/networking/logging.txt +file for the original Ingo Molnar's documentation on how to pass +parameters to the loadable module. + +The format of the kernel command line parameter (for the static +configuration) is as follows + +.. code-block:: bash + + netconsole=[src-port]@[src-ip]/[],[tgt-port]@/[tgt-macaddr] + +where + +src-port + source for UDP packets (defaults to 6665) + +src-ip + source IP to use (defaults to the interface's address) + +dev + network interface (defaults to eth0) + +tgt-port + port for logging agent (defaults to 6666) + +tgt-ip + IP address for logging agent (this is the required parameter) + +tgt-macaddr + ethernet MAC address for logging agent (defaults to broadcast) + +Examples + +.. code-block:: bash + + netconsole=4444@10.0.0.1/eth1,9353@10.0.0.2/12:34:56:78:9a:bc + netconsole=@/,@192.168.3.1/ + +Please note that for the Linux networked console to work, the +ethernet interface has to be up by the time the netconsole driver is +initialized. This means that in case of static kernel configuration, +the respective Ethernet interface has to be brought up using the "IP +Autoconfiguration" kernel feature, which is usually done by defaults +in the ELDK-NFS-based environment. + +To browse the Linux network console output, use the 'netcat' tool invoked +as follows: + +.. code-block:: bash + + nc -u -l -p 6666 + +Note that unlike the U-Boot implementation the Linux netconsole is +unidirectional, i. e. you have console output only in Linux. -- cgit v1.1 From dce26c7d56ed26ba07e1da245c84690ec1edcf65 Mon Sep 17 00:00:00 2001 From: Heinrich Schuchardt Date: Sat, 12 Dec 2020 10:14:22 +0100 Subject: doc: move README.trace to HTML documentation Convert README.trace to reStructured text and move it to develop/trace.rst. Signed-off-by: Heinrich Schuchardt Reviewed-by: Simon Glass --- doc/README.trace | 346 ------------------------------------------------ doc/develop/index.rst | 1 + doc/develop/trace.rst | 355 ++++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 356 insertions(+), 346 deletions(-) delete mode 100644 doc/README.trace create mode 100644 doc/develop/trace.rst diff --git a/doc/README.trace b/doc/README.trace deleted file mode 100644 index 2e7ca33..0000000 --- a/doc/README.trace +++ /dev/null @@ -1,346 +0,0 @@ -# SPDX-License-Identifier: GPL-2.0+ -# -# Copyright (c) 2013 The Chromium OS Authors. - -Tracing in U-Boot -================= - -U-Boot supports a simple tracing feature which allows a record of excecution -to be collected and sent to a host machine for analysis. At present the -main use for this is to profile boot time. - - -Overview --------- - -The trace feature uses GCC's instrument-functions feature to trace all -function entry/exit points. These are then recorded in a memory buffer. -The memory buffer can be saved to the host over a network link using -tftpput or by writing to an attached memory device such as MMC. - -On the host, the file is first converted with a tool called 'proftool', -which extracts useful information from it. The resulting trace output -resembles that emitted by Linux's ftrace feature, so can be visually -displayed by pytimechart. - - -Quick-start using Sandbox -------------------------- - -Sandbox is a build of U-Boot that can run under Linux so it is a convenient -way of trying out tracing before you use it on your actual board. To do -this, follow these steps: - -Add the following to include/configs/sandbox.h (if not already there) - -#define CONFIG_TRACE -#define CONFIG_CMD_TRACE -#define CONFIG_TRACE_BUFFER_SIZE (16 << 20) -#define CONFIG_TRACE_EARLY_SIZE (8 << 20) -#define CONFIG_TRACE_EARLY -#define CONFIG_TRACE_EARLY_ADDR 0x00100000 - -Build sandbox U-Boot with tracing enabled: - -$ make FTRACE=1 O=sandbox sandbox_config -$ make FTRACE=1 O=sandbox - -Run sandbox, wait for a bit of trace information to appear, and then capture -a trace: - -$ ./sandbox/u-boot - - -U-Boot 2013.04-rc2-00100-ga72fcef (Apr 17 2013 - 19:25:24) - -DRAM: 128 MiB -trace: enabled -Using default environment - -In: serial -Out: serial -Err: serial -=>trace stats - 671,406 function sites - 69,712 function calls - 0 untracked function calls - 73,373 traced function calls - 16 maximum observed call depth - 15 call depth limit - 66,491 calls not traced due to depth -=>trace stats - 671,406 function sites - 1,279,450 function calls - 0 untracked function calls - 950,490 traced function calls (333217 dropped due to overflow) - 16 maximum observed call depth - 15 call depth limit - 1,275,767 calls not traced due to depth -=>trace calls 0 e00000 -Call list dumped to 00000000, size 0xae0a40 -=>print -baudrate=115200 -profbase=0 -profoffset=ae0a40 -profsize=e00000 -stderr=serial -stdin=serial -stdout=serial - -Environment size: 117/8188 bytes -=>host save host 0 trace 0 ${profoffset} -11405888 bytes written in 10 ms (1.1 GiB/s) -=>reset - - -Then run proftool to convert the trace information to ftrace format. - -$ ./sandbox/tools/proftool -m sandbox/System.map -p trace dump-ftrace >trace.txt - -Finally run pytimechart to display it: - -$ pytimechart trace.txt - -Using this tool you can zoom and pan across the trace, with the function -calls on the left and little marks representing the start and end of each -function. - - -CONFIG Options --------------- - -- CONFIG_TRACE - Enables the trace feature in U-Boot. - -- CONFIG_CMD_TRACE - Enables the trace command. - -- CONFIG_TRACE_BUFFER_SIZE - Size of trace buffer to allocate for U-Boot. This buffer is - used after relocation, as a place to put function tracing - information. The address of the buffer is determined by - the relocation code. - -- CONFIG_TRACE_EARLY - Define this to start tracing early, before relocation. - -- CONFIG_TRACE_EARLY_SIZE - Size of 'early' trace buffer. Before U-Boot has relocated - it doesn't have a proper trace buffer. On many boards - you can define an area of memory to use for the trace - buffer until the 'real' trace buffer is available after - relocation. The contents of this buffer are then copied to - the real buffer. - -- CONFIG_TRACE_EARLY_ADDR - Address of early trace buffer - - -Building U-Boot with Tracing Enabled ------------------------------------- - -Pass 'FTRACE=1' to the U-Boot Makefile to actually instrument the code. -This is kept as a separate option so that it is easy to enable/disable -instrumenting from the command line instead of having to change board -config files. - - -Collecting Trace Data ---------------------- - -When you run U-Boot on your board it will collect trace data up to the -limit of the trace buffer size you have specified. Once that is exhausted -no more data will be collected. - -Collecting trace data has an affect on execution time/performance. You -will notice this particularly with trvial functions - the overhead of -recording their execution may even exceed their normal execution time. -In practice this doesn't matter much so long as you are aware of the -effect. Once you have done your optimisations, turn off tracing before -doing end-to-end timing. - -The best time to start tracing is right at the beginning of U-Boot. The -best time to stop tracing is right at the end. In practice it is hard -to achieve these ideals. - -This implementation enables tracing early in board_init_f(). This means -that it captures most of the board init process, missing only the -early architecture-specific init. However, it also misses the entire -SPL stage if there is one. - -U-Boot typically ends with a 'bootm' command which loads and runs an -OS. There is useful trace data in the execution of that bootm -command. Therefore this implementation provides a way to collect trace -data after bootm has finished processing, but just before it jumps to -the OS. In practical terms, U-Boot runs the 'fakegocmd' environment -variable at this point. This variable should have a short script which -collects the trace data and writes it somewhere. - -Trace data collection relies on a microsecond timer, accesed through -timer_get_us(). So the first think you should do is make sure that -this produces sensible results for your board. Suitable sources for -this timer include high resolution timers, PWMs or profile timers if -available. Most modern SOCs have a suitable timer for this. Make sure -that you mark this timer (and anything it calls) with -__attribute__((no_instrument_function)) so that the trace library can -use it without causing an infinite loop. - - -Commands --------- - -The trace command has variable sub-commands: - -- stats - Display tracing statistics - -- pause - Pause tracing - -- resume - Resume tracing - -- funclist [ ] - Dump a list of functions into the buffer - -- calls [ ] - Dump function call trace into buffer - -If the address and size are not given, these are obtained from environment -variables (see below). In any case the environment variables are updated -after the command runs. - - -Environment Variables ---------------------- - -The following are used: - -- profbase - Base address of trace output buffer - -- profoffset - Offset of first unwritten byte in trace output buffer - -- profsize - Size of trace output buffer - -All of these are set by the 'trace calls' command. - -These variables keep track of the amount of data written to the trace -output buffer by the 'trace' command. The trace commands which write data -to the output buffer can use these to specify the buffer to write to, and -update profoffset each time. This allows successive commands to append data -to the same buffer, for example: - - trace funclist 10000 e00000 - trace calls - -(the latter command appends more data to the buffer). - - -- fakegocmd - Specifies commands to run just before booting the OS. This - is a useful time to write the trace data to the host for - processing. - - -Writing Out Trace Data ----------------------- - -Once the trace data is in an output buffer in memory there are various ways -to transmit it to the host. Notably you can use tftput to send the data -over a network link: - -fakegocmd=trace pause; usb start; set autoload n; bootp; - trace calls 10000000 1000000; - tftpput ${profbase} ${profoffset} 192.168.1.4:/tftpboot/calls - -This starts up USB (to talk to an attached USB Ethernet dongle), writes -a trace log to address 10000000 and sends it to a host machine using -TFTP. After this, U-Boot will boot the OS normally, albeit a little -later. - - -Converting Trace Output Data ----------------------------- - -The trace output data is kept in a binary format which is not documented -here. To convert it into something useful, you can use proftool. - -This tool must be given the U-Boot map file and the trace data received -from running that U-Boot. It produces a text output file. - -Options - -m - Specify U-Boot map file - - -p - Specifiy profile/trace file - -Commands: - -- dump-ftrace - Write a text dump of the file in Linux ftrace format to stdout - - -Viewing the Trace Data ----------------------- - -You can use pytimechart for this (sudo apt-get pytimechart might work on -your Debian-style machine, and use your favourite search engine to obtain -documentation). It expects the file to have a .txt extension. The program -has terse user interface but is very convenient for viewing U-Boot -profile information. - - -Workflow Suggestions --------------------- - -The following suggestions may be helpful if you are trying to reduce boot -time: - -1. Enable CONFIG_BOOTSTAGE and CONFIG_BOOTSTAGE_REPORT. This should get -you are helpful overall snapshot of the boot time. - -2. Build U-Boot with tracing and run it. Note the difference in boot time -(it is common for tracing to add 10% to the time) - -3. Collect the trace information as descibed above. Use this to find where -all the time is being spent. - -4. Take a look at that code and see if you can optimise it. Perhaps it is -possible to speed up the initialisation of a device, or remove an unused -feature. - -5. Rebuild, run and collect again. Compare your results. - -6. Keep going until you run out of steam, or your boot is fast enough. - - -Configuring Trace ------------------ - -There are a few parameters in the code that you may want to consider. -There is a function call depth limit (set to 15 by default). When the -stack depth goes above this then no tracing information is recorded. -The maximum depth reached is recorded and displayed by the 'trace stats' -command. - - -Future Work ------------ - -Tracing could be a little tidier in some areas, for example providing -run-time configuration options for trace. - -Some other features that might be useful: - -- Trace filter to select which functions are recorded -- Sample-based profiling using a timer interrupt -- Better control over trace depth -- Compression of trace information - - -Simon Glass -April 2013 diff --git a/doc/develop/index.rst b/doc/develop/index.rst index c95a8d6..0a7e204 100644 --- a/doc/develop/index.rst +++ b/doc/develop/index.rst @@ -12,3 +12,4 @@ Develop U-Boot crash_dumps global_data logging + trace diff --git a/doc/develop/trace.rst b/doc/develop/trace.rst new file mode 100644 index 0000000..7776c48 --- /dev/null +++ b/doc/develop/trace.rst @@ -0,0 +1,355 @@ +.. SPDX-License-Identifier: GPL-2.0+ +.. Copyright (c) 2013 The Chromium OS Authors. + +Tracing in U-Boot +================= + +U-Boot supports a simple tracing feature which allows a record of excecution +to be collected and sent to a host machine for analysis. At present the +main use for this is to profile boot time. + + +Overview +-------- + +The trace feature uses GCC's instrument-functions feature to trace all +function entry/exit points. These are then recorded in a memory buffer. +The memory buffer can be saved to the host over a network link using +tftpput or by writing to an attached memory device such as MMC. + +On the host, the file is first converted with a tool called 'proftool', +which extracts useful information from it. The resulting trace output +resembles that emitted by Linux's ftrace feature, so can be visually +displayed by pytimechart. + + +Quick-start using Sandbox +------------------------- + +Sandbox is a build of U-Boot that can run under Linux so it is a convenient +way of trying out tracing before you use it on your actual board. To do +this, follow these steps: + +Add the following to include/configs/sandbox.h (if not already there) + +.. code-block:: c + + #define CONFIG_TRACE + #define CONFIG_CMD_TRACE + #define CONFIG_TRACE_BUFFER_SIZE (16 << 20) + #define CONFIG_TRACE_EARLY_SIZE (8 << 20) + #define CONFIG_TRACE_EARLY + #define CONFIG_TRACE_EARLY_ADDR 0x00100000 + +Build sandbox U-Boot with tracing enabled: + +.. code-block:: console + + $ make FTRACE=1 O=sandbox sandbox_config + $ make FTRACE=1 O=sandbox + +Run sandbox, wait for a bit of trace information to appear, and then capture +a trace: + +.. code-block:: console + + $ ./sandbox/u-boot + + U-Boot 2013.04-rc2-00100-ga72fcef (Apr 17 2013 - 19:25:24) + + DRAM: 128 MiB + trace: enabled + Using default environment + + In: serial + Out: serial + Err: serial + =>trace stats + 671,406 function sites + 69,712 function calls + 0 untracked function calls + 73,373 traced function calls + 16 maximum observed call depth + 15 call depth limit + 66,491 calls not traced due to depth + =>trace stats + 671,406 function sites + 1,279,450 function calls + 0 untracked function calls + 950,490 traced function calls (333217 dropped due to overflow) + 16 maximum observed call depth + 15 call depth limit + 1,275,767 calls not traced due to depth + =>trace calls 0 e00000 + Call list dumped to 00000000, size 0xae0a40 + =>print + baudrate=115200 + profbase=0 + profoffset=ae0a40 + profsize=e00000 + stderr=serial + stdin=serial + stdout=serial + + Environment size: 117/8188 bytes + =>host save host 0 trace 0 ${profoffset} + 11405888 bytes written in 10 ms (1.1 GiB/s) + =>reset + + +Then run proftool to convert the trace information to ftrace format + +.. code-block:: console + + $ ./sandbox/tools/proftool -m sandbox/System.map -p trace dump-ftrace >trace.txt + +Finally run pytimechart to display it + +.. code-block:: console + + $ pytimechart trace.txt + +Using this tool you can zoom and pan across the trace, with the function +calls on the left and little marks representing the start and end of each +function. + + +CONFIG Options +-------------- + +CONFIG_TRACE + Enables the trace feature in U-Boot. + +CONFIG_CMD_TRACE + Enables the trace command. + +CONFIG_TRACE_BUFFER_SIZE + Size of trace buffer to allocate for U-Boot. This buffer is + used after relocation, as a place to put function tracing + information. The address of the buffer is determined by + the relocation code. + +CONFIG_TRACE_EARLY + Define this to start tracing early, before relocation. + +CONFIG_TRACE_EARLY_SIZE + Size of 'early' trace buffer. Before U-Boot has relocated + it doesn't have a proper trace buffer. On many boards + you can define an area of memory to use for the trace + buffer until the 'real' trace buffer is available after + relocation. The contents of this buffer are then copied to + the real buffer. + +CONFIG_TRACE_EARLY_ADDR + Address of early trace buffer + + +Building U-Boot with Tracing Enabled +------------------------------------ + +Pass 'FTRACE=1' to the U-Boot Makefile to actually instrument the code. +This is kept as a separate option so that it is easy to enable/disable +instrumenting from the command line instead of having to change board +config files. + + +Collecting Trace Data +--------------------- + +When you run U-Boot on your board it will collect trace data up to the +limit of the trace buffer size you have specified. Once that is exhausted +no more data will be collected. + +Collecting trace data has an affect on execution time/performance. You +will notice this particularly with trvial functions - the overhead of +recording their execution may even exceed their normal execution time. +In practice this doesn't matter much so long as you are aware of the +effect. Once you have done your optimisations, turn off tracing before +doing end-to-end timing. + +The best time to start tracing is right at the beginning of U-Boot. The +best time to stop tracing is right at the end. In practice it is hard +to achieve these ideals. + +This implementation enables tracing early in board_init_f(). This means +that it captures most of the board init process, missing only the +early architecture-specific init. However, it also misses the entire +SPL stage if there is one. + +U-Boot typically ends with a 'bootm' command which loads and runs an +OS. There is useful trace data in the execution of that bootm +command. Therefore this implementation provides a way to collect trace +data after bootm has finished processing, but just before it jumps to +the OS. In practical terms, U-Boot runs the 'fakegocmd' environment +variable at this point. This variable should have a short script which +collects the trace data and writes it somewhere. + +Trace data collection relies on a microsecond timer, accesed through +timer_get_us(). So the first think you should do is make sure that +this produces sensible results for your board. Suitable sources for +this timer include high resolution timers, PWMs or profile timers if +available. Most modern SOCs have a suitable timer for this. Make sure +that you mark this timer (and anything it calls) with +__attribute__((no_instrument_function)) so that the trace library can +use it without causing an infinite loop. + + +Commands +-------- + +The trace command has variable sub-commands: + +stats + Display tracing statistics + +pause + Pause tracing + +resume + Resume tracing + +funclist [ ] + Dump a list of functions into the buffer + +calls [ ] + Dump function call trace into buffer + +If the address and size are not given, these are obtained from environment +variables (see below). In any case the environment variables are updated +after the command runs. + + +Environment Variables +--------------------- + +The following are used: + +profbase + Base address of trace output buffer + +profoffset + Offset of first unwritten byte in trace output buffer + +profsize + Size of trace output buffer + +All of these are set by the 'trace calls' command. + +These variables keep track of the amount of data written to the trace +output buffer by the 'trace' command. The trace commands which write data +to the output buffer can use these to specify the buffer to write to, and +update profoffset each time. This allows successive commands to append data +to the same buffer, for example:: + + => trace funclist 10000 e00000 + => trace calls + +(the latter command appends more data to the buffer). + + +fakegocmd + Specifies commands to run just before booting the OS. This + is a useful time to write the trace data to the host for + processing. + + +Writing Out Trace Data +---------------------- + +Once the trace data is in an output buffer in memory there are various ways +to transmit it to the host. Notably you can use tftput to send the data +over a network link:: + + fakegocmd=trace pause; usb start; set autoload n; bootp; + trace calls 10000000 1000000; + tftpput ${profbase} ${profoffset} 192.168.1.4:/tftpboot/calls + +This starts up USB (to talk to an attached USB Ethernet dongle), writes +a trace log to address 10000000 and sends it to a host machine using +TFTP. After this, U-Boot will boot the OS normally, albeit a little +later. + + +Converting Trace Output Data +---------------------------- + +The trace output data is kept in a binary format which is not documented +here. To convert it into something useful, you can use proftool. + +This tool must be given the U-Boot map file and the trace data received +from running that U-Boot. It produces a text output file. + +Options + +-m + Specify U-Boot map file + +-p + Specifiy profile/trace file + +Commands: + +dump-ftrace + Write a text dump of the file in Linux ftrace format to stdout + + +Viewing the Trace Data +---------------------- + +You can use pytimechart for this (sudo apt-get pytimechart might work on +your Debian-style machine, and use your favourite search engine to obtain +documentation). It expects the file to have a .txt extension. The program +has terse user interface but is very convenient for viewing U-Boot +profile information. + + +Workflow Suggestions +-------------------- + +The following suggestions may be helpful if you are trying to reduce boot +time: + +1. Enable CONFIG_BOOTSTAGE and CONFIG_BOOTSTAGE_REPORT. This should get + you are helpful overall snapshot of the boot time. + +2. Build U-Boot with tracing and run it. Note the difference in boot time + (it is common for tracing to add 10% to the time) + +3. Collect the trace information as descibed above. Use this to find where + all the time is being spent. + +4. Take a look at that code and see if you can optimise it. Perhaps it is + possible to speed up the initialisation of a device, or remove an unused + feature. + +5. Rebuild, run and collect again. Compare your results. + +6. Keep going until you run out of steam, or your boot is fast enough. + + +Configuring Trace +----------------- + +There are a few parameters in the code that you may want to consider. +There is a function call depth limit (set to 15 by default). When the +stack depth goes above this then no tracing information is recorded. +The maximum depth reached is recorded and displayed by the 'trace stats' +command. + + +Future Work +----------- + +Tracing could be a little tidier in some areas, for example providing +run-time configuration options for trace. + +Some other features that might be useful: + +- Trace filter to select which functions are recorded +- Sample-based profiling using a timer interrupt +- Better control over trace depth +- Compression of trace information + + +Simon Glass +April 2013 -- cgit v1.1 From 4cf91c886dc266df0713dfd1bd48b6f82ce4411f Mon Sep 17 00:00:00 2001 From: Heinrich Schuchardt Date: Sat, 12 Dec 2020 10:53:17 +0100 Subject: doc: move README.bootmenu to HTML doc MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Convert README.bootmenu to reStructured text and move it to usage/bootmenu.rst. Adjust the text concerning configuration settings as these now are managed via Kconfig. Signed-off-by: Heinrich Schuchardt Reviewed-by: Pali Rohár --- doc/README.bootmenu | 98 -------------------------------------------------- doc/usage/bootmenu.rst | 95 ++++++++++++++++++++++++++++++++++++++++++++++++ doc/usage/index.rst | 1 + 3 files changed, 96 insertions(+), 98 deletions(-) delete mode 100644 doc/README.bootmenu create mode 100644 doc/usage/bootmenu.rst diff --git a/doc/README.bootmenu b/doc/README.bootmenu deleted file mode 100644 index 9ff89f2..0000000 --- a/doc/README.bootmenu +++ /dev/null @@ -1,98 +0,0 @@ -SPDX-License-Identifier: GPL-2.0+ -/* - * (C) Copyright 2011-2012 Pali Rohár - */ - -ANSI terminal bootmenu command - -The "bootmenu" command uses U-Boot menu interfaces and provides -a simple mechanism for creating menus with different boot items. -The cursor keys "Up" and "Down" are used for navigation through -the items. Current active menu item is highlighted and can be -selected using the "Enter" key. The selection of the highlighted -menu entry invokes an U-Boot command (or a list of commands) -associated with this menu entry. - -The "bootmenu" command interprets ANSI escape sequencies, so -an ANSI terminal is required for proper menu rendering and item -selection. - -The assembling of the menu is done via a set of environment variables -"bootmenu_" and "bootmenu_delay", i.e.: - - bootmenu_delay= - bootmenu_="=<commands>" - - <delay> is the autoboot delay in seconds, after which the first - menu entry will be selected automatically - - <num> is the boot menu entry number, starting from zero - - <title> is the text of the menu entry shown on the console - or on the boot screen - - <commands> are commands which will be executed when a menu - entry is selected - - (title and commands are separated by first appearance of '=' - character in the environment variable) - -First (optional) argument of the "bootmenu" command is a delay specifier -and it overrides the delay value defined by "bootmenu_delay" environment -variable. If the environment variable "bootmenu_delay" is not set or if -the argument of the "bootmenu" command is not specified, the default delay -will be CONFIG_BOOTDELAY. If delay is 0, no menu entries will be shown on -the console (or on the screen) and the command of the first menu entry will -be called immediately. If delay is less then 0, bootmenu will be shown and -autoboot will be disabled. - -Bootmenu always adds menu entry "U-Boot console" at the end of all menu -entries specified by environment variables. When selecting this entry -the bootmenu terminates and the usual U-Boot command prompt is presented -to the user. - -Example environment: - - setenv bootmenu_0 Boot 1. kernel=bootm 0x82000000 # Set first menu entry - setenv bootmenu_1 Boot 2. kernel=bootm 0x83000000 # Set second menu entry - setenv bootmenu_2 Reset board=reset # Set third menu entry - setenv bootmenu_3 U-Boot boot order=boot # Set fourth menu entry - bootmenu 20 # Run bootmenu with autoboot delay 20s - - -The above example will be rendered as below -(without decorating rectangle): - -┌──────────────────────────────────────────┐ -│ │ -│ *** U-Boot Boot Menu *** │ -│ │ -│ Boot 1. kernel │ -│ Boot 2. kernel │ -│ Reset board │ -│ U-Boot boot order │ -│ U-Boot console │ -│ │ -│ Hit any key to stop autoboot: 20 │ -│ Press UP/DOWN to move, ENTER to select │ -│ │ -└──────────────────────────────────────────┘ - -Selected menu entry will be highlighted - it will have inverted -background and text colors. - -To enable the "bootmenu" command add following definitions to the -board config file: - - #define CONFIG_CMD_BOOTMENU - #define CONFIG_MENU - -To run the bootmenu at startup add these additional definitions: - - #define CONFIG_AUTOBOOT_KEYED - #define CONFIG_BOOTDELAY 30 - #define CONFIG_AUTOBOOT_MENU_SHOW - -When you intend to use the bootmenu on color frame buffer console, -make sure to additionally define CONFIG_CFB_CONSOLE_ANSI in the -board config file. diff --git a/doc/usage/bootmenu.rst b/doc/usage/bootmenu.rst new file mode 100644 index 0000000..1f094ad --- /dev/null +++ b/doc/usage/bootmenu.rst @@ -0,0 +1,95 @@ +.. SPDX-License-Identifier: GPL-2.0+ +.. (C) Copyright 2011-2012 Pali Rohár <pali@kernel.org> + +bootmenu command +================ + +The "bootmenu" command uses U-Boot menu interfaces and provides +a simple mechanism for creating menus with different boot items. +The cursor keys "Up" and "Down" are used for navigation through +the items. Current active menu item is highlighted and can be +selected using the "Enter" key. The selection of the highlighted +menu entry invokes an U-Boot command (or a list of commands) +associated with this menu entry. + +The "bootmenu" command interprets ANSI escape sequencies, so +an ANSI terminal is required for proper menu rendering and item +selection. + +The assembling of the menu is done via a set of environment variables +"bootmenu_<num>" and "bootmenu_delay", i.e.:: + + bootmenu_delay=<delay> + bootmenu_<num>="<title>=<commands>" + +<delay> + is the autoboot delay in seconds, after which the first + menu entry will be selected automatically + +<num> + is the boot menu entry number, starting from zero + +<title> + is the text of the menu entry shown on the console + or on the boot screen + +<commands> + are commands which will be executed when a menu + entry is selected + +Title and commands are separated by the first appearance of a '=' +character in the value of the environment variable. + +The first (optional) argument of the "bootmenu" command is a delay specifier +and it overrides the delay value defined by "bootmenu_delay" environment +variable. If the environment variable "bootmenu_delay" is not set or if +the argument of the "bootmenu" command is not specified, the default delay +will be CONFIG_BOOTDELAY. If delay is 0, no menu entries will be shown on +the console (or on the screen) and the command of the first menu entry will +be called immediately. If delay is less then 0, bootmenu will be shown and +autoboot will be disabled. + +Bootmenu always adds menu entry "U-Boot console" at the end of all menu +entries specified by environment variables. When selecting this entry +the bootmenu terminates and the usual U-Boot command prompt is presented +to the user. + +Example environment:: + + setenv bootmenu_0 Boot 1. kernel=bootm 0x82000000 # Set first menu entry + setenv bootmenu_1 Boot 2. kernel=bootm 0x83000000 # Set second menu entry + setenv bootmenu_2 Reset board=reset # Set third menu entry + setenv bootmenu_3 U-Boot boot order=boot # Set fourth menu entry + bootmenu 20 # Run bootmenu with autoboot delay 20s + + +The above example will be rendered as below:: + + *** U-Boot Boot Menu *** + + Boot 1. kernel + Boot 2. kernel + Reset board + U-Boot boot order + U-Boot console + + Hit any key to stop autoboot: 20 + Press UP/DOWN to move, ENTER to select + +The selected menu entry will be highlighted - it will have inverted +background and text colors. + +The "bootmenu" cammand is enabled by:: + + CONFIG_CMD_BOOTMENU=y + +To run the bootmenu at startup add these additional settings:: + + CONFIG_AUTOBOOT_KEYED=y + CONFIG_BOOTDELAY=30 + CONFIG_AUTOBOOT_MENU_SHOW=y + +When you intend to use the bootmenu on a color frame buffer console, +make sure to additionally define:: + + CONFIG_CFB_CONSOLE_ANSI=y diff --git a/doc/usage/index.rst b/doc/usage/index.rst index 063e970..d0f5a9f 100644 --- a/doc/usage/index.rst +++ b/doc/usage/index.rst @@ -11,4 +11,5 @@ Shell commands .. toctree:: :maxdepth: 1 + bootmenu pstore -- cgit v1.1 From abd40a8f98ad546e34918f73865d7561a94bda44 Mon Sep 17 00:00:00 2001 From: Heinrich Schuchardt <xypron.glpk@gmx.de> Date: Sat, 12 Dec 2020 09:15:12 +0100 Subject: doc: uefi: remove leading $ from bash commands Use the same formatting for all bash commands. Signed-off-by: Heinrich Schuchardt <xypron.glpk@gmx.de> --- doc/uefi/uefi.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/uefi/uefi.rst b/doc/uefi/uefi.rst index 07eb3f0..dc930d9 100644 --- a/doc/uefi/uefi.rst +++ b/doc/uefi/uefi.rst @@ -156,11 +156,11 @@ The whitelist database .. code-block:: bash - $ openssl req -x509 -sha256 -newkey rsa:2048 -subj /CN=TEST_db/ \ + openssl req -x509 -sha256 -newkey rsa:2048 -subj /CN=TEST_db/ \ -keyout db.key -out db.crt -nodes -days 365 - $ cert-to-efi-sig-list -g 11111111-2222-3333-4444-123456789abc \ + cert-to-efi-sig-list -g 11111111-2222-3333-4444-123456789abc \ db.crt db.esl - $ sign-efi-sig-list -c KEK.crt -k KEK.key db db.esl db.auth + sign-efi-sig-list -c KEK.crt -k KEK.key db db.esl db.auth Copy the \*.auth files to media, say mmc, that is accessible from U-Boot. -- cgit v1.1