Difuse/u-boot
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Documentation fixes for v2020.01-rc4

Browse source 
Move several README files to reStructured text for the HTML documentation.
 Describe register for global data on x86.
 Allow building HTML documentation with Sphinx 3
 -----BEGIN PGP SIGNATURE-----
 
 iQIzBAABCAAdFiEEbcT5xx8ppvoGt20zxIHbvCwFGsQFAl/YnHIACgkQxIHbvCwF
 GsTrSw/9F0CJGd5j9ZLgTJ8j5/M43bJRbYqDDVXAvVAbruNIYkAnKecK/AVoSfAu
 Q607nYDNExFo/IgSSt/m0x/F4zwf065WzfsszVFL7AoLTnlyWnTujxxpyTSI4cU1
 B0FV3PqxkbA2IUwa4obJYeZUUT0+TFP/TsRYdU/OKI/nBJofxN6roPAlO0XIUvO4
 1BHiyrbrg6/nmER/LgwQi3VdcNQ9KXtQVT3qGgaM0ddvp024aJQhVxoFC4j/kTcA
 o2Tm0x4C8XQCto7r6/noARBmkgV67ll6L5ADr1J9v59Evj6VaVYZXgmm4pOnPMDN
 I7PXnDRr6W31G2T8QXR3bxtDJ+7MNV0Lg+6ESNbvDfbHZRa0daWXGImPz98WyiqV
 +ktZPM/vVyboGFH1SMXnIjR2UeJF90fIIZkOdWoAbSEn4oGcnvv6tmuWHyFdNiXf
 RZ+wW3ST9k6SeJEMq5O1XB9fU6n5V9B/AYzUdNiGt3B5hHdcZB4AL4TkFqKYAg+l
 XbolUp06B3zdcPz1fn9u0pbKaOOzdmmOvcH0Abfc37O5bHlv/fR7JJLDKB0QPKon
 P+Mk4cXzfh7LFJX0o7J8A79y3iiG22iPqA1le/OhkK629usiicV5CmPgAmjRFMjO
 am9Vg9fKgj7P3c2Ia/qA6qO0RKD5TCE6p0sVh0ntD2cDynFcDjQ=
 =dRaN
 -----END PGP SIGNATURE-----

Merge tag 'doc-2021-01-rc4' of https://gitlab.denx.de/u-boot/custodians/u-boot-efi

Documentation fixes for v2020.01-rc4

Move several README files to reStructured text for the HTML documentation.
Describe register for global data on x86.
Allow building HTML documentation with Sphinx 3
This commit is contained in:
Tom Rini 2020-12-15 13:57:03 -05:00
commit af22790a3b
14 changed files with 548 additions and 428 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

98
doc/README.bootmenu
View file

@ -1,98 +0,0 @@
SPDX-License-Identifier: GPL-2.0+
/*
* (C) Copyright 2011-2012 Pali Rohár <pali@kernel.org>
*/
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_<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 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.

186
doc/README.commands
View file

@ -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);

20
doc/build/gcc.rst vendored
View file

@ -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-<architecture>-gcc<version>.
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
-------------

29
doc/conf.py
View file

@ -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):

226
doc/develop/commands.rst Normal file
View file

@ -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);

4
doc/develop/global_data.rst
View file

@ -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

2
doc/develop/index.rst
View file

@ -8,6 +8,8 @@ Develop U-Boot
:maxdepth: 2
coccinelle
commands
crash_dumps
global_data
logging
trace

229
doc/README.trace → doc/develop/trace.rst
View file

@ -1,6 +1,5 @@
# SPDX-License-Identifier: GPL-2.0+
#
# Copyright (c) 2013 The Chromium OS Authors.
.. SPDX-License-Identifier: GPL-2.0+
.. Copyright (c) 2013 The Chromium OS Authors.
Tracing in U-Boot
=================
@ -33,73 +32,82 @@ 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
.. 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:
$ make FTRACE=1 O=sandbox sandbox_config
$ make FTRACE=1 O=sandbox
.. 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:
$ ./sandbox/u-boot
.. code-block:: console
$ ./sandbox/u-boot
U-Boot 2013.04-rc2-00100-ga72fcef (Apr 17 2013 - 19:25:24)
U-Boot 2013.04-rc2-00100-ga72fcef (Apr 17 2013 - 19:25:24)
DRAM: 128 MiB
trace: enabled
Using default environment
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
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
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
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.
Then run proftool to convert the trace information to ftrace format
$ ./sandbox/tools/proftool -m sandbox/System.map -p trace dump-ftrace >trace.txt
.. code-block:: console
Finally run pytimechart to display it:
$ ./sandbox/tools/proftool -m sandbox/System.map -p trace dump-ftrace >trace.txt
$ pytimechart 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
@ -109,31 +117,31 @@ function.
CONFIG Options
--------------
- CONFIG_TRACE
Enables the trace feature in U-Boot.
CONFIG_TRACE
Enables the trace feature in U-Boot.
- CONFIG_CMD_TRACE
Enables the trace command.
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_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
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_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
CONFIG_TRACE_EARLY_ADDR
Address of early trace buffer
Building U-Boot with Tracing Enabled
@ -191,20 +199,20 @@ Commands
The trace command has variable sub-commands:
- stats
Display tracing statistics
stats
Display tracing statistics
- pause
Pause tracing
pause
Pause tracing
- resume
Resume tracing
resume
Resume tracing
- funclist [<addr> <size>]
Dump a list of functions into the buffer
funclist [<addr> <size>]
Dump a list of functions into the buffer
- calls [<addr> <size>]
Dump function call trace into buffer
calls [<addr> <size>]
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
@ -216,14 +224,14 @@ Environment Variables
The following are used:
- profbase
Base address of trace output buffer
profbase
Base address of trace output buffer
- profoffset
Offset of first unwritten byte in trace output buffer
profoffset
Offset of first unwritten byte in trace output buffer
- profsize
Size of trace output buffer
profsize
Size of trace output buffer
All of these are set by the 'trace calls' command.
@ -231,18 +239,18 @@ 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:
to the same buffer, for example::
trace funclist 10000 e00000
trace calls
=> 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.
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
@ -250,11 +258,11 @@ 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:
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
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
@ -272,16 +280,17 @@ 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 <map_file>
Specify U-Boot map file
-p <trace_file>
Specifiy profile/trace file
-m <map_file>
Specify U-Boot map file
-p <trace_file>
Specifiy profile/trace file
Commands:
- dump-ftrace
Write a text dump of the file in Linux ftrace format to stdout
dump-ftrace
Write a text dump of the file in Linux ftrace format to stdout
Viewing the Trace Data
@ -301,17 +310,17 @@ 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.
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)
(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.
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.
possible to speed up the initialisation of a device, or remove an unused
feature.
5. Rebuild, run and collect again. Compare your results.

8
doc/index.rst
View file

@ -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
==================

6
doc/uefi/uefi.rst
View file

@ -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.

95
doc/usage/bootmenu.rst Normal file
View file

@ -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

15
doc/usage/index.rst Normal file
View file

@ -0,0 +1,15 @@
Use U-Boot
==========
.. toctree::
netconsole
Shell commands
--------------
.. toctree::
:maxdepth: 1
bootmenu
pstore

54
doc/README.NetConsole → doc/usage/netconsole.rst
View file

@ -1,3 +1,5 @@
Network console
===============
In U-Boot, we implemented the networked console via the standard
"devices" mechanism, which means that you can switch between the
@ -6,7 +8,8 @@ serial and network input/output devices by adjusting the 'stdin' and
set either of these variables to "nc". Input and output can be
switched independently.
CONFIG_NETCONSOLE_BUFFER_SIZE - Override the default buffer size
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 <ip_addr>:<port>. If <port> is
@ -17,15 +20,16 @@ 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:
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
On the host side, please use this script to access the console:
.. code-block:: bash
tools/netconsole <ip> [port]
@ -54,31 +58,37 @@ 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:
configuration) is as follows
netconsole=[src-port]@[src-ip]/[<dev>],[tgt-port]@<tgt-ip>/[tgt-macaddr]
.. code-block:: bash
netconsole=[src-port]@[src-ip]/[<dev>],[tgt-port]@<tgt-ip>/[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)
src-port
source for UDP packets (defaults to 6665)
Examples:
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
or
netconsole=@/,@192.168.3.1/
Please note that for the Linux networked console to work, the
@ -91,6 +101,8 @@ 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

4
doc/pstore.rst → doc/usage/pstore.rst
View file

@ -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"