diff options
Diffstat (limited to 'roms/u-boot/doc/develop')
40 files changed, 9359 insertions, 0 deletions
diff --git a/roms/u-boot/doc/develop/coccinelle.rst b/roms/u-boot/doc/develop/coccinelle.rst new file mode 100644 index 000000000..70274c3f5 --- /dev/null +++ b/roms/u-boot/doc/develop/coccinelle.rst @@ -0,0 +1,505 @@ +.. Copyright 2010 Nicolas Palix <npalix@diku.dk> +.. Copyright 2010 Julia Lawall <julia@diku.dk> +.. Copyright 2010 Gilles Muller <Gilles.Muller@lip6.fr> + +.. highlight:: none + +.. _devtools_coccinelle: + +Coccinelle +========== + +Coccinelle is a tool for pattern matching and text transformation that has +many uses in kernel development, including the application of complex, +tree-wide patches and detection of problematic programming patterns. + +Getting Coccinelle +------------------ + +The semantic patches included in the kernel use features and options +which are provided by Coccinelle version 1.0.0-rc11 and above. +Using earlier versions will fail as the option names used by +the Coccinelle files and coccicheck have been updated. + +Coccinelle is available through the package manager +of many distributions, e.g. : + + - Debian + - Fedora + - Ubuntu + - OpenSUSE + - Arch Linux + - NetBSD + - FreeBSD + +Some distribution packages are obsolete and it is recommended +to use the latest version released from the Coccinelle homepage at +http://coccinelle.lip6.fr/ + +Or from Github at: + +https://github.com/coccinelle/coccinelle + +Once you have it, run the following commands:: + + ./autogen + ./configure + make + +as a regular user, and install it with:: + + sudo make install + +More detailed installation instructions to build from source can be +found at: + +https://github.com/coccinelle/coccinelle/blob/master/install.txt + +Supplemental documentation +-------------------------- + +For supplemental documentation refer to the wiki: + +https://bottest.wiki.kernel.org/coccicheck + +The wiki documentation always refers to the linux-next version of the script. + +For Semantic Patch Language(SmPL) grammar documentation refer to: + +http://coccinelle.lip6.fr/documentation.php + +Using Coccinelle on the Linux kernel +------------------------------------ + +A Coccinelle-specific target is defined in the top level +Makefile. This target is named ``coccicheck`` and calls the ``coccicheck`` +front-end in the ``scripts`` directory. + +Four basic modes are defined: ``patch``, ``report``, ``context``, and +``org``. The mode to use is specified by setting the MODE variable with +``MODE=<mode>``. + +- ``patch`` proposes a fix, when possible. + +- ``report`` generates a list in the following format: + file:line:column-column: message + +- ``context`` highlights lines of interest and their context in a + diff-like style.Lines of interest are indicated with ``-``. + +- ``org`` generates a report in the Org mode format of Emacs. + +Note that not all semantic patches implement all modes. For easy use +of Coccinelle, the default mode is "report". + +Two other modes provide some common combinations of these modes. + +- ``chain`` tries the previous modes in the order above until one succeeds. + +- ``rep+ctxt`` runs successively the report mode and the context mode. + It should be used with the C option (described later) + which checks the code on a file basis. + +Examples +~~~~~~~~ + +To make a report for every semantic patch, run the following command:: + + make coccicheck MODE=report + +To produce patches, run:: + + make coccicheck MODE=patch + + +The coccicheck target applies every semantic patch available in the +sub-directories of ``scripts/coccinelle`` to the entire Linux kernel. + +For each semantic patch, a commit message is proposed. It gives a +description of the problem being checked by the semantic patch, and +includes a reference to Coccinelle. + +As any static code analyzer, Coccinelle produces false +positives. Thus, reports must be carefully checked, and patches +reviewed. + +To enable verbose messages set the V= variable, for example:: + + make coccicheck MODE=report V=1 + +Coccinelle parallelization +-------------------------- + +By default, coccicheck tries to run as parallel as possible. To change +the parallelism, set the J= variable. For example, to run across 4 CPUs:: + + make coccicheck MODE=report J=4 + +As of Coccinelle 1.0.2 Coccinelle uses Ocaml parmap for parallelization, +if support for this is detected you will benefit from parmap parallelization. + +When parmap is enabled coccicheck will enable dynamic load balancing by using +``--chunksize 1`` argument, this ensures we keep feeding threads with work +one by one, so that we avoid the situation where most work gets done by only +a few threads. With dynamic load balancing, if a thread finishes early we keep +feeding it more work. + +When parmap is enabled, if an error occurs in Coccinelle, this error +value is propagated back, the return value of the ``make coccicheck`` +captures this return value. + +Using Coccinelle with a single semantic patch +--------------------------------------------- + +The optional make variable COCCI can be used to check a single +semantic patch. In that case, the variable must be initialized with +the name of the semantic patch to apply. + +For instance:: + + make coccicheck COCCI=<my_SP.cocci> MODE=patch + +or:: + + make coccicheck COCCI=<my_SP.cocci> MODE=report + + +Controlling Which Files are Processed by Coccinelle +--------------------------------------------------- + +By default the entire kernel source tree is checked. + +To apply Coccinelle to a specific directory, ``M=`` can be used. +For example, to check drivers/net/wireless/ one may write:: + + make coccicheck M=drivers/net/wireless/ + +To apply Coccinelle on a file basis, instead of a directory basis, the +following command may be used:: + + make C=1 CHECK="scripts/coccicheck" + +To check only newly edited code, use the value 2 for the C flag, i.e.:: + + make C=2 CHECK="scripts/coccicheck" + +In these modes, which works on a file basis, there is no information +about semantic patches displayed, and no commit message proposed. + +This runs every semantic patch in scripts/coccinelle by default. The +COCCI variable may additionally be used to only apply a single +semantic patch as shown in the previous section. + +The "report" mode is the default. You can select another one with the +MODE variable explained above. + +Debugging Coccinelle SmPL patches +--------------------------------- + +Using coccicheck is best as it provides in the spatch command line +include options matching the options used when we compile the kernel. +You can learn what these options are by using V=1, you could then +manually run Coccinelle with debug options added. + +Alternatively you can debug running Coccinelle against SmPL patches +by asking for stderr to be redirected to stderr, by default stderr +is redirected to /dev/null, if you'd like to capture stderr you +can specify the ``DEBUG_FILE="file.txt"`` option to coccicheck. For +instance:: + + rm -f cocci.err + make coccicheck COCCI=scripts/coccinelle/free/kfree.cocci MODE=report DEBUG_FILE=cocci.err + cat cocci.err + +You can use SPFLAGS to add debugging flags, for instance you may want to +add both --profile --show-trying to SPFLAGS when debugging. For instance +you may want to use:: + + rm -f err.log + export COCCI=scripts/coccinelle/misc/irqf_oneshot.cocci + make coccicheck DEBUG_FILE="err.log" MODE=report SPFLAGS="--profile --show-trying" M=./drivers/mfd/arizona-irq.c + +err.log will now have the profiling information, while stdout will +provide some progress information as Coccinelle moves forward with +work. + +DEBUG_FILE support is only supported when using coccinelle >= 1.0.2. + +.cocciconfig support +-------------------- + +Coccinelle supports reading .cocciconfig for default Coccinelle options that +should be used every time spatch is spawned, the order of precedence for +variables for .cocciconfig is as follows: + +- Your current user's home directory is processed first +- Your directory from which spatch is called is processed next +- The directory provided with the --dir option is processed last, if used + +Since coccicheck runs through make, it naturally runs from the kernel +proper dir, as such the second rule above would be implied for picking up a +.cocciconfig when using ``make coccicheck``. + +``make coccicheck`` also supports using M= targets. If you do not supply +any M= target, it is assumed you want to target the entire kernel. +The kernel coccicheck script has:: + + if [ "$KBUILD_EXTMOD" = "" ] ; then + OPTIONS="--dir $srctree $COCCIINCLUDE" + else + OPTIONS="--dir $KBUILD_EXTMOD $COCCIINCLUDE" + fi + +KBUILD_EXTMOD is set when an explicit target with M= is used. For both cases +the spatch --dir argument is used, as such third rule applies when whether M= +is used or not, and when M= is used the target directory can have its own +.cocciconfig file. When M= is not passed as an argument to coccicheck the +target directory is the same as the directory from where spatch was called. + +If not using the kernel's coccicheck target, keep the above precedence +order logic of .cocciconfig reading. If using the kernel's coccicheck target, +override any of the kernel's .coccicheck's settings using SPFLAGS. + +We help Coccinelle when used against Linux with a set of sensible defaults +options for Linux with our own Linux .cocciconfig. This hints to coccinelle +git can be used for ``git grep`` queries over coccigrep. A timeout of 200 +seconds should suffice for now. + +The options picked up by coccinelle when reading a .cocciconfig do not appear +as arguments to spatch processes running on your system, to confirm what +options will be used by Coccinelle run:: + + spatch --print-options-only + +You can override with your own preferred index option by using SPFLAGS. Take +note that when there are conflicting options Coccinelle takes precedence for +the last options passed. Using .cocciconfig is possible to use idutils, however +given the order of precedence followed by Coccinelle, since the kernel now +carries its own .cocciconfig, you will need to use SPFLAGS to use idutils if +desired. See below section "Additional flags" for more details on how to use +idutils. + +Additional flags +---------------- + +Additional flags can be passed to spatch through the SPFLAGS +variable. This works as Coccinelle respects the last flags +given to it when options are in conflict. :: + + make SPFLAGS=--use-glimpse coccicheck + +Coccinelle supports idutils as well but requires coccinelle >= 1.0.6. +When no ID file is specified coccinelle assumes your ID database file +is in the file .id-utils.index on the top level of the kernel, coccinelle +carries a script scripts/idutils_index.sh which creates the database with:: + + mkid -i C --output .id-utils.index + +If you have another database filename you can also just symlink with this +name. :: + + make SPFLAGS=--use-idutils coccicheck + +Alternatively you can specify the database filename explicitly, for +instance:: + + make SPFLAGS="--use-idutils /full-path/to/ID" coccicheck + +See ``spatch --help`` to learn more about spatch options. + +Note that the ``--use-glimpse`` and ``--use-idutils`` options +require external tools for indexing the code. None of them is +thus active by default. However, by indexing the code with +one of these tools, and according to the cocci file used, +spatch could proceed the entire code base more quickly. + +SmPL patch specific options +--------------------------- + +SmPL patches can have their own requirements for options passed +to Coccinelle. SmPL patch specific options can be provided by +providing them at the top of the SmPL patch, for instance:: + + // Options: --no-includes --include-headers + +SmPL patch Coccinelle requirements +---------------------------------- + +As Coccinelle features get added some more advanced SmPL patches +may require newer versions of Coccinelle. If an SmPL patch requires +at least a version of Coccinelle, this can be specified as follows, +as an example if requiring at least Coccinelle >= 1.0.5:: + + // Requires: 1.0.5 + +Proposing new semantic patches +------------------------------ + +New semantic patches can be proposed and submitted by kernel +developers. For sake of clarity, they should be organized in the +sub-directories of ``scripts/coccinelle/``. + + +Detailed description of the ``report`` mode +------------------------------------------- + +``report`` generates a list in the following format:: + + file:line:column-column: message + +Example +~~~~~~~ + +Running:: + + make coccicheck MODE=report COCCI=scripts/coccinelle/api/err_cast.cocci + +will execute the following part of the SmPL script:: + + <smpl> + @r depends on !context && !patch && (org || report)@ + expression x; + position p; + @@ + + ERR_PTR@p(PTR_ERR(x)) + + @script:python depends on report@ + p << r.p; + x << r.x; + @@ + + msg="ERR_CAST can be used with %s" % (x) + coccilib.report.print_report(p[0], msg) + </smpl> + +This SmPL excerpt generates entries on the standard output, as +illustrated below:: + + /home/user/linux/crypto/ctr.c:188:9-16: ERR_CAST can be used with alg + /home/user/linux/crypto/authenc.c:619:9-16: ERR_CAST can be used with auth + /home/user/linux/crypto/xts.c:227:9-16: ERR_CAST can be used with alg + + +Detailed description of the ``patch`` mode +------------------------------------------ + +When the ``patch`` mode is available, it proposes a fix for each problem +identified. + +Example +~~~~~~~ + +Running:: + + make coccicheck MODE=patch COCCI=scripts/coccinelle/api/err_cast.cocci + +will execute the following part of the SmPL script:: + + <smpl> + @ depends on !context && patch && !org && !report @ + expression x; + @@ + + - ERR_PTR(PTR_ERR(x)) + + ERR_CAST(x) + </smpl> + +This SmPL excerpt generates patch hunks on the standard output, as +illustrated below:: + + diff -u -p a/crypto/ctr.c b/crypto/ctr.c + --- a/crypto/ctr.c 2010-05-26 10:49:38.000000000 +0200 + +++ b/crypto/ctr.c 2010-06-03 23:44:49.000000000 +0200 + @@ -185,7 +185,7 @@ static struct crypto_instance *crypto_ct + alg = crypto_attr_alg(tb[1], CRYPTO_ALG_TYPE_CIPHER, + CRYPTO_ALG_TYPE_MASK); + if (IS_ERR(alg)) + - return ERR_PTR(PTR_ERR(alg)); + + return ERR_CAST(alg); + + /* Block size must be >= 4 bytes. */ + err = -EINVAL; + +Detailed description of the ``context`` mode +-------------------------------------------- + +``context`` highlights lines of interest and their context +in a diff-like style. + + **NOTE**: The diff-like output generated is NOT an applicable patch. The + intent of the ``context`` mode is to highlight the important lines + (annotated with minus, ``-``) and gives some surrounding context + lines around. This output can be used with the diff mode of + Emacs to review the code. + +Example +~~~~~~~ + +Running:: + + make coccicheck MODE=context COCCI=scripts/coccinelle/api/err_cast.cocci + +will execute the following part of the SmPL script:: + + <smpl> + @ depends on context && !patch && !org && !report@ + expression x; + @@ + + * ERR_PTR(PTR_ERR(x)) + </smpl> + +This SmPL excerpt generates diff hunks on the standard output, as +illustrated below:: + + diff -u -p /home/user/linux/crypto/ctr.c /tmp/nothing + --- /home/user/linux/crypto/ctr.c 2010-05-26 10:49:38.000000000 +0200 + +++ /tmp/nothing + @@ -185,7 +185,6 @@ static struct crypto_instance *crypto_ct + alg = crypto_attr_alg(tb[1], CRYPTO_ALG_TYPE_CIPHER, + CRYPTO_ALG_TYPE_MASK); + if (IS_ERR(alg)) + - return ERR_PTR(PTR_ERR(alg)); + + /* Block size must be >= 4 bytes. */ + err = -EINVAL; + +Detailed description of the ``org`` mode +---------------------------------------- + +``org`` generates a report in the Org mode format of Emacs. + +Example +~~~~~~~ + +Running:: + + make coccicheck MODE=org COCCI=scripts/coccinelle/api/err_cast.cocci + +will execute the following part of the SmPL script:: + + <smpl> + @r depends on !context && !patch && (org || report)@ + expression x; + position p; + @@ + + ERR_PTR@p(PTR_ERR(x)) + + @script:python depends on org@ + p << r.p; + x << r.x; + @@ + + msg="ERR_CAST can be used with %s" % (x) + msg_safe=msg.replace("[","@(").replace("]",")") + coccilib.org.print_todo(p[0], msg_safe) + </smpl> + +This SmPL excerpt generates Org entries on the standard output, as +illustrated below:: + + * TODO [[view:/home/user/linux/crypto/ctr.c::face=ovl-face1::linb=188::colb=9::cole=16][ERR_CAST can be used with alg]] + * TODO [[view:/home/user/linux/crypto/authenc.c::face=ovl-face1::linb=619::colb=9::cole=16][ERR_CAST can be used with auth]] + * TODO [[view:/home/user/linux/crypto/xts.c::face=ovl-face1::linb=227::colb=9::cole=16][ERR_CAST can be used with alg]] diff --git a/roms/u-boot/doc/develop/commands.rst b/roms/u-boot/doc/develop/commands.rst new file mode 100644 index 000000000..c72d1b0aa --- /dev/null +++ b/roms/u-boot/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/roms/u-boot/doc/develop/crash_dumps.rst b/roms/u-boot/doc/develop/crash_dumps.rst new file mode 100644 index 000000000..85030b4e3 --- /dev/null +++ b/roms/u-boot/doc/develop/crash_dumps.rst @@ -0,0 +1,124 @@ +.. SPDX-License-Identifier: GPL-2.0+ +.. Copyright (c) 2020 Heinrich Schuchardt + +Analyzing crash dumps +===================== + +When the CPU detects an instruction that it cannot execute it raises an +interrupt. U-Boot then writes a crash dump. This chapter describes how such +dump can be analyzed. + +Creating a crash dump voluntarily +--------------------------------- + +For describing the analysis of a crash dump we need an example. U-Boot comes +with a command 'exception' that comes in handy here. The command is enabled +by:: + + CONFIG_CMD_EXCEPTION=y + +The example output below was recorded when running qemu\_arm64\_defconfig on +QEMU:: + + => exception undefined + "Synchronous Abort" handler, esr 0x02000000 + elr: 00000000000101fc lr : 00000000000214ec (reloc) + elr: 000000007ff291fc lr : 000000007ff3a4ec + x0 : 000000007ffbd7f8 x1 : 0000000000000000 + x2 : 0000000000000001 x3 : 000000007eedce18 + x4 : 000000007ff291fc x5 : 000000007eedce50 + x6 : 0000000000000064 x7 : 000000007eedce10 + x8 : 0000000000000000 x9 : 0000000000000004 + x10: 6db6db6db6db6db7 x11: 000000000000000d + x12: 0000000000000006 x13: 000000000001869f + x14: 000000007edd7dc0 x15: 0000000000000002 + x16: 000000007ff291fc x17: 0000000000000000 + x18: 000000007eed8dc0 x19: 0000000000000000 + x20: 000000007ffbd7f8 x21: 0000000000000000 + x22: 000000007eedce10 x23: 0000000000000002 + x24: 000000007ffd4c80 x25: 0000000000000000 + x26: 0000000000000000 x27: 0000000000000000 + x28: 000000007eedce70 x29: 000000007edd7b40 + + Code: b00003c0 912ad000 940029d6 17ffff52 (e7f7defb) + Resetting CPU ... + + resetting ... + +The first line provides us with the type of interrupt that occurred. +On ARMv8 a synchronous abort is an exception thrown when hitting an unallocated +instruction. The exception syndrome register ESR register contains information +describing the reason for the exception. Bit 25 set here indicates that a 32 bit +instruction led to the exception. + +The second line provides the contents of the elr and the lr register after +subtracting the relocation offset. - U-Boot relocates itself after being +loaded. - The relocation offset can also be displayed using the bdinfo command. + +After the contents of the registers we get a line indicating the machine +code of the instructions preceding the crash and in parentheses the instruction +leading to the dump. + +Analyzing the code location +--------------------------- + +We can convert the instructions in the line starting with 'Code:' into mnemonics +using the objdump command. To make things easier scripts/decodecode is +supplied:: + + $echo 'Code: b00003c0 912ad000 940029d6 17ffff52 (e7f7defb)' | \ + CROSS_COMPILE=aarch64-linux-gnu- ARCH=arm64 scripts/decodecode + Code: b00003c0 912ad000 940029d6 17ffff52 (e7f7defb) + All code + ======== + 0: b00003c0 adrp x0, 0x79000 + 4: 912ad000 add x0, x0, #0xab4 + 8: 940029d6 bl 0xa760 + c: 17ffff52 b 0xfffffffffffffd54 + 10:* e7f7defb .inst 0xe7f7defb ; undefined <-- trapping instruction + + Code starting with the faulting instruction + =========================================== + 0: e7f7defb .inst 0xe7f7defb ; undefined + +Now lets use the locations provided by the elr and lr registers after +subtracting the relocation offset to find out where in the code the crash +occurred and from where it was invoked. + +File u-boot.map contains the memory layout of the U-Boot binary. Here we find +these lines:: + + .text.do_undefined + 0x00000000000101fc 0xc cmd/built-in.o + .text.exception_complete + 0x0000000000010208 0x90 cmd/built-in.o + ... + .text.cmd_process + 0x00000000000213b8 0x164 common/built-in.o + 0x00000000000213b8 cmd_process + .text.cmd_process_error + 0x000000000002151c 0x40 common/built-in.o + 0x000000000002151c cmd_process_error + +So the error occurred at the start of function do\_undefined() and this +function was invoked from somewhere inside function cmd\_process(). + +If we want to dive deeper, we can disassemble the U-Boot binary:: + + $ aarch64-linux-gnu-objdump -S -D u-boot | less + + 00000000000101fc <do_undefined>: + { + /* + * 0xe7f...f. is undefined in ARM mode + * 0xde.. is undefined in Thumb mode + */ + asm volatile (".word 0xe7f7defb\n"); + 101fc: e7f7defb .inst 0xe7f7defb ; undefined + return CMD_RET_FAILURE; + } + 10200: 52800020 mov w0, #0x1 // #1 + 10204: d65f03c0 ret + +This example is based on the ARMv8 architecture but the same procedures can be +used on other architectures as well. diff --git a/roms/u-boot/doc/develop/driver-model/bind.rst b/roms/u-boot/doc/develop/driver-model/bind.rst new file mode 100644 index 000000000..b19661b5f --- /dev/null +++ b/roms/u-boot/doc/develop/driver-model/bind.rst @@ -0,0 +1,49 @@ +.. SPDX-License-Identifier: GPL-2.0+ +.. sectionauthor:: Patrice Chotard <patrice.chotard@foss.st.com> + +Binding/unbinding a driver +========================== + +This document aims to describe the bind and unbind commands. + +For debugging purpose, it should be useful to bind or unbind a driver from +the U-boot command line. + +The unbind command calls the remove device driver callback and unbind the +device from its driver. + +The bind command binds a device to its driver. + +In some cases it can be useful to be able to bind a device to a driver from +the command line. +The obvious example is for versatile devices such as USB gadget. +Another use case is when the devices are not yet ready at startup and +require some setup before the drivers are bound (ex: FPGA which bitsream is +fetched from a mass storage or ethernet) + +usage: + +bind <node path> <driver> +bind <class> <index> <driver> + +unbind <node path> +unbind <class> <index> +unbind <class> <index> <driver> + +Where: + - <node path> is the node's device tree path + - <class> is one of the class available in the list given by the "dm uclass" + command or first column of "dm tree" command. + - <index> is the index of the parent's node (second column of "dm tree" output). + - <driver> is the driver name to bind given by the "dm drivers" command or the by + the fourth column of "dm tree" output. + +example: + +bind usb_dev_generic 0 usb_ether +unbind usb_dev_generic 0 usb_ether +or +unbind eth 1 + +bind /ocp/omap_dwc3@48380000/usb@48390000 usb_ether +unbind /ocp/omap_dwc3@48380000/usb@48390000 diff --git a/roms/u-boot/doc/develop/driver-model/debugging.rst b/roms/u-boot/doc/develop/driver-model/debugging.rst new file mode 100644 index 000000000..bbb279434 --- /dev/null +++ b/roms/u-boot/doc/develop/driver-model/debugging.rst @@ -0,0 +1,62 @@ +.. SPDX-License-Identifier: GPL-2.0+ +.. sectionauthor:: Simon Glass <sjg@chromium.org> + +Debugging driver model +====================== + +This document aims to provide help when you cannot work out why driver model is +not doing what you expect. + + +Useful techniques in general +---------------------------- + +Here are some useful debugging features generally. + + - If you are writing a new feature, consider doing it in sandbox instead of + on your board. Sandbox has no limits, allows easy debugging (e.g. gdb) and + you can write emulators for most common devices. + - Put '#define DEBUG' at the top of a file, to activate all the debug() and + log_debug() statements in that file. + - Where logging is used, change the logging level, e.g. in SPL with + CONFIG_SPL_LOG_MAX_LEVEL=7 (which is LOGL_DEBUG) and + CONFIG_LOG_DEFAULT_LEVEL=7 + - Where logging of return values is implemented with log_msg_ret(), set + CONFIG_LOG_ERROR_RETURN=y to see exactly where the error is happening + - Make sure you have a debug UART enabled - see CONFIG_DEBUG_UART. With this + you can get serial output (printf(), etc.) before the serial driver is + running. + - Use a JTAG emulator to set breakpoints and single-step through code + +Not that most of these increase code/data size somewhat when enabled. + + +Failure to locate a device +-------------------------- + +Let's say you have uclass_first_device_err() and it is not finding anything. + +If it is returning an error, then that gives you a clue. Look up linux/errno.h +to see errors. Common ones are: + + - -ENOMEM which indicates that memory is short. If it happens in SPL or + before relocation in U-Boot, check CONFIG_SPL_SYS_MALLOC_F_LEN and + CONFIG_SYS_MALLOC_F_LEN as they may need to be larger. Add '#define DEBUG' + at the very top of malloc_simple.c to get an idea of where your memory is + going. + - -EINVAL which typically indicates that something was missing or wrong in + the device tree node. Check that everything is correct and look at the + of_to_plat() method in the driver. + +If there is no error, you should check if the device is actually bound. Call +dm_dump_all() just before you locate the device to make sure it exists. + +If it does not exist, check your device tree compatible strings match up with +what the driver expects (in the struct udevice_id array). + +If you are using of-platdata (e.g. CONFIG_SPL_OF_PLATDATA), check that the +driver name is the same as the first compatible string in the device tree (with +invalid-variable characters converted to underscore). + +If you are really stuck, putting '#define LOG_DEBUG' at the top of +drivers/core/lists.c should show you what is going on. diff --git a/roms/u-boot/doc/develop/driver-model/design.rst b/roms/u-boot/doc/develop/driver-model/design.rst new file mode 100644 index 000000000..b0e633703 --- /dev/null +++ b/roms/u-boot/doc/develop/driver-model/design.rst @@ -0,0 +1,1149 @@ +.. SPDX-License-Identifier: GPL-2.0+ +.. sectionauthor:: Simon Glass <sjg@chromium.org> + +Design Details +============== + +This README contains high-level information about driver model, a unified +way of declaring and accessing drivers in U-Boot. The original work was done +by: + + * Marek Vasut <marex@denx.de> + * Pavel Herrmann <morpheus.ibis@gmail.com> + * Viktor KÅ™ivák <viktor.krivak@gmail.com> + * Tomas Hlavacek <tmshlvck@gmail.com> + +This has been both simplified and extended into the current implementation +by: + + * Simon Glass <sjg@chromium.org> + + +Terminology +----------- + +Uclass + a group of devices which operate in the same way. A uclass provides + a way of accessing individual devices within the group, but always + using the same interface. For example a GPIO uclass provides + operations for get/set value. An I2C uclass may have 10 I2C ports, + 4 with one driver, and 6 with another. + +Driver + some code which talks to a peripheral and presents a higher-level + interface to it. + +Device + an instance of a driver, tied to a particular port or peripheral. + + +How to try it +------------- + +Build U-Boot sandbox and run it:: + + make sandbox_defconfig + make + ./u-boot -d u-boot.dtb + + (type 'reset' to exit U-Boot) + + +There is a uclass called 'demo'. This uclass handles +saying hello, and reporting its status. There are two drivers in this +uclass: + + - simple: Just prints a message for hello, doesn't implement status + - shape: Prints shapes and reports number of characters printed as status + +The demo class is pretty simple, but not trivial. The intention is that it +can be used for testing, so it will implement all driver model features and +provide good code coverage of them. It does have multiple drivers, it +handles parameter data and plat (data which tells the driver how +to operate on a particular platform) and it uses private driver data. + +To try it, see the example session below:: + + =>demo hello 1 + Hello '@' from 07981110: red 4 + =>demo status 2 + Status: 0 + =>demo hello 2 + g + r@ + e@@ + e@@@ + n@@@@ + g@@@@@ + =>demo status 2 + Status: 21 + =>demo hello 4 ^ + y^^^ + e^^^^^ + l^^^^^^^ + l^^^^^^^ + o^^^^^ + w^^^ + =>demo status 4 + Status: 36 + => + + +Running the tests +----------------- + +The intent with driver model is that the core portion has 100% test coverage +in sandbox, and every uclass has its own test. As a move towards this, tests +are provided in test/dm. To run them, try:: + + ./test/py/test.py --bd sandbox --build -k ut_dm -v + +You should see something like this:: + + (venv)$ ./test/py/test.py --bd sandbox --build -k ut_dm -v + +make O=/root/u-boot/build-sandbox -s sandbox_defconfig + +make O=/root/u-boot/build-sandbox -s -j8 + ============================= test session starts ============================== + platform linux2 -- Python 2.7.5, pytest-2.9.0, py-1.4.31, pluggy-0.3.1 -- /root/u-boot/venv/bin/python + cachedir: .cache + rootdir: /root/u-boot, inifile: + collected 199 items + + test/py/tests/test_ut.py::test_ut_dm_init PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_adc_bind] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_adc_multi_channel_conversion] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_adc_multi_channel_shot] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_adc_single_channel_conversion] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_adc_single_channel_shot] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_adc_supply] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_adc_wrong_channel_selection] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_autobind] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_autobind_uclass_pdata_alloc] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_autobind_uclass_pdata_valid] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_autoprobe] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_bus_child_post_bind] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_bus_child_post_bind_uclass] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_bus_child_pre_probe_uclass] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_bus_children] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_bus_children_funcs] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_bus_children_iterators] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_bus_parent_data] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_bus_parent_data_uclass] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_bus_parent_ops] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_bus_parent_platdata] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_bus_parent_platdata_uclass] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_children] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_clk_base] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_clk_periph] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_device_get_uclass_id] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_eth] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_eth_act] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_eth_alias] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_eth_prime] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_eth_rotate] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_fdt] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_fdt_offset] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_fdt_pre_reloc] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_fdt_uclass_seq] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_gpio] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_gpio_anon] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_gpio_copy] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_gpio_leak] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_gpio_phandles] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_gpio_requestf] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_i2c_bytewise] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_i2c_find] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_i2c_offset] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_i2c_offset_len] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_i2c_probe_empty] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_i2c_read_write] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_i2c_speed] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_leak] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_led_base] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_led_gpio] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_led_label] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_lifecycle] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_mmc_base] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_net_retry] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_operations] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_ordering] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_pci_base] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_pci_busnum] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_pci_swapcase] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_platdata] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_power_pmic_get] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_power_pmic_io] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_power_regulator_autoset] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_power_regulator_autoset_list] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_power_regulator_get] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_power_regulator_set_get_current] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_power_regulator_set_get_enable] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_power_regulator_set_get_mode] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_power_regulator_set_get_voltage] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_pre_reloc] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_ram_base] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_regmap_base] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_regmap_syscon] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_remoteproc_base] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_remove] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_reset_base] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_reset_walk] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_rtc_base] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_rtc_dual] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_rtc_reset] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_rtc_set_get] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_spi_find] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_spi_flash] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_spi_xfer] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_syscon_base] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_syscon_by_driver_data] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_timer_base] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_uclass] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_uclass_before_ready] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_uclass_devices_find] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_uclass_devices_find_by_name] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_uclass_devices_get] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_uclass_devices_get_by_name] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_usb_base] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_usb_flash] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_usb_keyb] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_usb_multi] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_usb_remove] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_usb_tree] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_usb_tree_remove] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_usb_tree_reorder] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_video_base] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_video_bmp] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_video_bmp_comp] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_video_chars] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_video_context] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_video_rotation1] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_video_rotation2] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_video_rotation3] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_video_text] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_video_truetype] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_video_truetype_bs] PASSED + test/py/tests/test_ut.py::test_ut[ut_dm_video_truetype_scroll] PASSED + + ======================= 84 tests deselected by '-kut_dm' ======================= + ================== 115 passed, 84 deselected in 3.77 seconds =================== + +What is going on? +----------------- + +Let's start at the top. The demo command is in cmd/demo.c. It does +the usual command processing and then: + +.. code-block:: c + + struct udevice *demo_dev; + + ret = uclass_get_device(UCLASS_DEMO, devnum, &demo_dev); + +UCLASS_DEMO means the class of devices which implement 'demo'. Other +classes might be MMC, or GPIO, hashing or serial. The idea is that the +devices in the class all share a particular way of working. The class +presents a unified view of all these devices to U-Boot. + +This function looks up a device for the demo uclass. Given a device +number we can find the device because all devices have registered with +the UCLASS_DEMO uclass. + +The device is automatically activated ready for use by uclass_get_device(). + +Now that we have the device we can do things like: + +.. code-block:: c + + return demo_hello(demo_dev, ch); + +This function is in the demo uclass. It takes care of calling the 'hello' +method of the relevant driver. Bearing in mind that there are two drivers, +this particular device may use one or other of them. + +The code for demo_hello() is in drivers/demo/demo-uclass.c: + +.. code-block:: c + + int demo_hello(struct udevice *dev, int ch) + { + const struct demo_ops *ops = device_get_ops(dev); + + if (!ops->hello) + return -ENOSYS; + + return ops->hello(dev, ch); + } + +As you can see it just calls the relevant driver method. One of these is +in drivers/demo/demo-simple.c: + +.. code-block:: c + + static int simple_hello(struct udevice *dev, int ch) + { + const struct dm_demo_pdata *pdata = dev_get_plat(dev); + + printf("Hello from %08x: %s %d\n", map_to_sysmem(dev), + pdata->colour, pdata->sides); + + return 0; + } + + +So that is a trip from top (command execution) to bottom (driver action) +but it leaves a lot of topics to address. + + +Declaring Drivers +----------------- + +A driver declaration looks something like this (see +drivers/demo/demo-shape.c): + +.. code-block:: c + + static const struct demo_ops shape_ops = { + .hello = shape_hello, + .status = shape_status, + }; + + U_BOOT_DRIVER(demo_shape_drv) = { + .name = "demo_shape_drv", + .id = UCLASS_DEMO, + .ops = &shape_ops, + .priv_data_size = sizeof(struct shape_data), + }; + + +This driver has two methods (hello and status) and requires a bit of +private data (accessible through dev_get_priv(dev) once the driver has +been probed). It is a member of UCLASS_DEMO so will register itself +there. + +In U_BOOT_DRIVER it is also possible to specify special methods for bind +and unbind, and these are called at appropriate times. For many drivers +it is hoped that only 'probe' and 'remove' will be needed. + +The U_BOOT_DRIVER macro creates a data structure accessible from C, +so driver model can find the drivers that are available. + +The methods a device can provide are documented in the device.h header. +Briefly, they are: + + * bind - make the driver model aware of a device (bind it to its driver) + * unbind - make the driver model forget the device + * of_to_plat - convert device tree data to plat - see later + * probe - make a device ready for use + * remove - remove a device so it cannot be used until probed again + +The sequence to get a device to work is bind, of_to_plat (if using +device tree) and probe. + + +Platform Data +------------- + +Note: platform data is the old way of doing things. It is +basically a C structure which is passed to drivers to tell them about +platform-specific settings like the address of its registers, bus +speed, etc. Device tree is now the preferred way of handling this. +Unless you have a good reason not to use device tree (the main one +being you need serial support in SPL and don't have enough SRAM for +the cut-down device tree and libfdt libraries) you should stay away +from platform data. + +Platform data is like Linux platform data, if you are familiar with that. +It provides the board-specific information to start up a device. + +Why is this information not just stored in the device driver itself? The +idea is that the device driver is generic, and can in principle operate on +any board that has that type of device. For example, with modern +highly-complex SoCs it is common for the IP to come from an IP vendor, and +therefore (for example) the MMC controller may be the same on chips from +different vendors. It makes no sense to write independent drivers for the +MMC controller on each vendor's SoC, when they are all almost the same. +Similarly, we may have 6 UARTs in an SoC, all of which are mostly the same, +but lie at different addresses in the address space. + +Using the UART example, we have a single driver and it is instantiated 6 +times by supplying 6 lots of platform data. Each lot of platform data +gives the driver name and a pointer to a structure containing information +about this instance - e.g. the address of the register space. It may be that +one of the UARTS supports RS-485 operation - this can be added as a flag in +the platform data, which is set for this one port and clear for the rest. + +Think of your driver as a generic piece of code which knows how to talk to +a device, but needs to know where it is, any variant/option information and +so on. Platform data provides this link between the generic piece of code +and the specific way it is bound on a particular board. + +Examples of platform data include: + + - The base address of the IP block's register space + - Configuration options, like: + - the SPI polarity and maximum speed for a SPI controller + - the I2C speed to use for an I2C device + - the number of GPIOs available in a GPIO device + +Where does the platform data come from? It is either held in a structure +which is compiled into U-Boot, or it can be parsed from the Device Tree +(see 'Device Tree' below). + +For an example of how it can be compiled in, see demo-pdata.c which +sets up a table of driver names and their associated platform data. +The data can be interpreted by the drivers however they like - it is +basically a communication scheme between the board-specific code and +the generic drivers, which are intended to work on any board. + +Drivers can access their data via dev->info->plat. Here is +the declaration for the platform data, which would normally appear +in the board file. + +.. code-block:: c + + static const struct dm_demo_pdata red_square = { + .colour = "red", + .sides = 4. + }; + + static const struct driver_info info[] = { + { + .name = "demo_shape_drv", + .plat = &red_square, + }, + }; + + demo1 = driver_bind(root, &info[0]); + + +Device Tree +----------- + +While plat is useful, a more flexible way of providing device data is +by using device tree. In U-Boot you should use this where possible. Avoid +sending patches which make use of the U_BOOT_DRVINFO() macro unless strictly +necessary. + +With device tree we replace the above code with the following device tree +fragment: + +.. code-block:: c + + red-square { + compatible = "demo-shape"; + colour = "red"; + sides = <4>; + }; + +This means that instead of having lots of U_BOOT_DRVINFO() declarations in +the board file, we put these in the device tree. This approach allows a lot +more generality, since the same board file can support many types of boards +(e,g. with the same SoC) just by using different device trees. An added +benefit is that the Linux device tree can be used, thus further simplifying +the task of board-bring up either for U-Boot or Linux devs (whoever gets to +the board first!). + +The easiest way to make this work it to add a few members to the driver: + +.. code-block:: c + + .plat_auto = sizeof(struct dm_test_pdata), + .of_to_plat = testfdt_of_to_plat, + +The 'auto' feature allowed space for the plat to be allocated +and zeroed before the driver's of_to_plat() method is called. The +of_to_plat() method, which the driver write supplies, should parse +the device tree node for this device and place it in dev->plat. Thus +when the probe method is called later (to set up the device ready for use) +the platform data will be present. + +Note that both methods are optional. If you provide an of_to_plat +method then it will be called first (during activation). If you provide a +probe method it will be called next. See Driver Lifecycle below for more +details. + +If you don't want to have the plat automatically allocated then you +can leave out plat_auto. In this case you can use malloc +in your of_to_plat (or probe) method to allocate the required memory, +and you should free it in the remove method. + +The driver model tree is intended to mirror that of the device tree. The +root driver is at device tree offset 0 (the root node, '/'), and its +children are the children of the root node. + +In order for a device tree to be valid, the content must be correct with +respect to either device tree specification +(https://www.devicetree.org/specifications/) or the device tree bindings that +are found in the doc/device-tree-bindings directory. When not U-Boot specific +the bindings in this directory tend to come from the Linux Kernel. As such +certain design decisions may have been made already for us in terms of how +specific devices are described and bound. In most circumstances we wish to +retain compatibility without additional changes being made to the device tree +source files. + +Declaring Uclasses +------------------ + +The demo uclass is declared like this: + +.. code-block:: c + + UCLASS_DRIVER(demo) = { + .id = UCLASS_DEMO, + }; + +It is also possible to specify special methods for probe, etc. The uclass +numbering comes from include/dm/uclass-id.h. To add a new uclass, add to the +end of the enum there, then declare your uclass as above. + + +Device Sequence Numbers +----------------------- + +U-Boot numbers devices from 0 in many situations, such as in the command +line for I2C and SPI buses, and the device names for serial ports (serial0, +serial1, ...). Driver model supports this numbering and permits devices +to be locating by their 'sequence'. This numbering uniquely identifies a +device in its uclass, so no two devices within a particular uclass can have +the same sequence number. + +Sequence numbers start from 0 but gaps are permitted. For example, a board +may have I2C buses 1, 4, 5 but no 0, 2 or 3. The choice of how devices are +numbered is up to a particular board, and may be set by the SoC in some +cases. While it might be tempting to automatically renumber the devices +where there are gaps in the sequence, this can lead to confusion and is +not the way that U-Boot works. + +Where a device gets its sequence number is controlled by the DM_SEQ_ALIAS +Kconfig option, which can have a different value in U-Boot proper and SPL. +If this option is not set, aliases are ignored. + +Even if CONFIG_DM_SEQ_ALIAS is enabled, the uclass must still have the +DM_UC_FLAG_SEQ_ALIAS flag set, for its devices to be sequenced by aliases. + +With those options set, devices with an alias (e.g. "serial2") will get that +sequence number (e.g. 2). Other devices get the next available number after all +aliases and all existing numbers. This means that if there is just a single +alias "serial2", unaliased serial devices will be assigned 3 or more, with 0 and +1 being unused. + +If CONFIG_DM_SEQ_ALIAS or DM_UC_FLAG_SEQ_ALIAS are not set, all devices will get +sequence numbers in a simple ordering starting from 0. To find the next number +to allocate, driver model scans through to find the maximum existing number, +then uses the next one. It does not attempt to fill in gaps. + +.. code-block:: none + + aliases { + serial2 = "/serial@22230000"; + }; + +This indicates that in the uclass called "serial", the named node +("/serial@22230000") will be given sequence number 2. Any command or driver +which requests serial device 2 will obtain this device. + +More commonly you can use node references, which expand to the full path: + +.. code-block:: none + + aliases { + serial2 = &serial_2; + }; + ... + serial_2: serial@22230000 { + ... + }; + +The alias resolves to the same string in this case, but this version is +easier to read. + +Device sequence numbers are resolved when a device is bound and the number does +not change for the life of the device. + +There are some situations where the uclass must allocate sequence numbers, +since a strictly increase sequence (with devicetree nodes bound first) is not +suitable. An example of this is the PCI bus. In this case, you can set the +uclass DM_UC_FLAG_NO_AUTO_SEQ flag. With this flag set, only devices with an +alias will be assigned a number by driver model. The rest is left to the uclass +to sort out, e.g. when enumerating the bus. + +Note that changing the sequence number for a device (e.g. in a driver) is not +permitted. If it is felt to be necessary, ask on the mailing list. + +Bus Drivers +----------- + +A common use of driver model is to implement a bus, a device which provides +access to other devices. Example of buses include SPI and I2C. Typically +the bus provides some sort of transport or translation that makes it +possible to talk to the devices on the bus. + +Driver model provides some useful features to help with implementing buses. +Firstly, a bus can request that its children store some 'parent data' which +can be used to keep track of child state. Secondly, the bus can define +methods which are called when a child is probed or removed. This is similar +to the methods the uclass driver provides. Thirdly, per-child platform data +can be provided to specify things like the child's address on the bus. This +persists across child probe()/remove() cycles. + +For consistency and ease of implementation, the bus uclass can specify the +per-child platform data, so that it can be the same for all children of buses +in that uclass. There are also uclass methods which can be called when +children are bound and probed. + +Here an explanation of how a bus fits with a uclass may be useful. Consider +a USB bus with several devices attached to it, each from a different (made +up) uclass:: + + xhci_usb (UCLASS_USB) + eth (UCLASS_ETH) + camera (UCLASS_CAMERA) + flash (UCLASS_FLASH_STORAGE) + +Each of the devices is connected to a different address on the USB bus. +The bus device wants to store this address and some other information such +as the bus speed for each device. + +To achieve this, the bus device can use dev->parent_plat in each of its +three children. This can be auto-allocated if the bus driver (or bus uclass) +has a non-zero value for per_child_plat_auto. If not, then +the bus device or uclass can allocate the space itself before the child +device is probed. + +Also the bus driver can define the child_pre_probe() and child_post_remove() +methods to allow it to do some processing before the child is activated or +after it is deactivated. + +Similarly the bus uclass can define the child_post_bind() method to obtain +the per-child platform data from the device tree and set it up for the child. +The bus uclass can also provide a child_pre_probe() method. Very often it is +the bus uclass that controls these features, since it avoids each driver +having to do the same processing. Of course the driver can still tweak and +override these activities. + +Note that the information that controls this behaviour is in the bus's +driver, not the child's. In fact it is possible that child has no knowledge +that it is connected to a bus. The same child device may even be used on two +different bus types. As an example. the 'flash' device shown above may also +be connected on a SATA bus or standalone with no bus:: + + xhci_usb (UCLASS_USB) + flash (UCLASS_FLASH_STORAGE) - parent data/methods defined by USB bus + + sata (UCLASS_AHCI) + flash (UCLASS_FLASH_STORAGE) - parent data/methods defined by SATA bus + + flash (UCLASS_FLASH_STORAGE) - no parent data/methods (not on a bus) + +Above you can see that the driver for xhci_usb/sata controls the child's +bus methods. In the third example the device is not on a bus, and therefore +will not have these methods at all. Consider the case where the flash +device defines child methods. These would be used for *its* children, and +would be quite separate from the methods defined by the driver for the bus +that the flash device is connetced to. The act of attaching a device to a +parent device which is a bus, causes the device to start behaving like a +bus device, regardless of its own views on the matter. + +The uclass for the device can also contain data private to that uclass. +But note that each device on the bus may be a member of a different +uclass, and this data has nothing to do with the child data for each child +on the bus. It is the bus' uclass that controls the child with respect to +the bus. + + +Driver Lifecycle +---------------- + +Here are the stages that a device goes through in driver model. Note that all +methods mentioned here are optional - e.g. if there is no probe() method for +a device then it will not be called. A simple device may have very few +methods actually defined. + +Bind stage +^^^^^^^^^^ + +U-Boot discovers devices using one of these two methods: + +- Scan the U_BOOT_DRVINFO() definitions. U-Boot looks up the name specified + by each, to find the appropriate U_BOOT_DRIVER() definition. In this case, + there is no path by which driver_data may be provided, but the U_BOOT_DRVINFO() + may provide plat. + +- Scan through the device tree definitions. U-Boot looks at top-level + nodes in the the device tree. It looks at the compatible string in each node + and uses the of_match table of the U_BOOT_DRIVER() structure to find the + right driver for each node. In this case, the of_match table may provide a + driver_data value, but plat cannot be provided until later. + +For each device that is discovered, U-Boot then calls device_bind() to create a +new device, initializes various core fields of the device object such as name, +uclass & driver, initializes any optional fields of the device object that are +applicable such as of_offset, driver_data & plat, and finally calls the +driver's bind() method if one is defined. + +At this point all the devices are known, and bound to their drivers. There +is a 'struct udevice' allocated for all devices. However, nothing has been +activated (except for the root device). Each bound device that was created +from a U_BOOT_DRVINFO() declaration will hold the plat pointer specified +in that declaration. For a bound device created from the device tree, +plat will be NULL, but of_offset will be the offset of the device tree +node that caused the device to be created. The uclass is set correctly for +the device. + +The device's sequence number is assigned, either the requested one or the next +available one (after all aliases are processed) if nothing particular is +requested. + +The device's bind() method is permitted to perform simple actions, but +should not scan the device tree node, not initialise hardware, nor set up +structures or allocate memory. All of these tasks should be left for +the probe() method. + +Note that compared to Linux, U-Boot's driver model has a separate step of +probe/remove which is independent of bind/unbind. This is partly because in +U-Boot it may be expensive to probe devices and we don't want to do it until +they are needed, or perhaps until after relocation. + +Reading ofdata +^^^^^^^^^^^^^^ + +Most devices have data in the device tree which they can read to find out the +base address of hardware registers and parameters relating to driver +operation. This is called 'ofdata' (Open-Firmware data). + +The device's of_to_plat() implemnents allocation and reading of +plat. A parent's ofdata is always read before a child. + +The steps are: + + 1. If priv_auto is non-zero, then the device-private space + is allocated for the device and zeroed. It will be accessible as + dev->priv. The driver can put anything it likes in there, but should use + it for run-time information, not platform data (which should be static + and known before the device is probed). + + 2. If plat_auto is non-zero, then the platform data space + is allocated. This is only useful for device tree operation, since + otherwise you would have to specify the platform data in the + U_BOOT_DRVINFO() declaration. The space is allocated for the device and + zeroed. It will be accessible as dev->plat. + + 3. If the device's uclass specifies a non-zero per_device_auto, + then this space is allocated and zeroed also. It is allocated for and + stored in the device, but it is uclass data. owned by the uclass driver. + It is possible for the device to access it. + + 4. If the device's immediate parent specifies a per_child_auto + then this space is allocated. This is intended for use by the parent + device to keep track of things related to the child. For example a USB + flash stick attached to a USB host controller would likely use this + space. The controller can hold information about the USB state of each + of its children. + + 5. If the driver provides an of_to_plat() method, then this is + called to convert the device tree data into platform data. This should + do various calls like dev_read_u32(dev, ...) to access the node and store + the resulting information into dev->plat. After this point, the device + works the same way whether it was bound using a device tree node or + U_BOOT_DRVINFO() structure. In either case, the platform data is now stored + in the plat structure. Typically you will use the + plat_auto feature to specify the size of the platform data + structure, and U-Boot will automatically allocate and zero it for you before + entry to of_to_plat(). But if not, you can allocate it yourself in + of_to_plat(). Note that it is preferable to do all the device tree + decoding in of_to_plat() rather than in probe(). (Apart from the + ugliness of mixing configuration and run-time data, one day it is possible + that U-Boot will cache platform data for devices which are regularly + de/activated). + + 6. The device is marked 'plat valid'. + +Note that ofdata reading is always done (for a child and all its parents) +before probing starts. Thus devices go through two distinct states when +probing: reading platform data and actually touching the hardware to bring +the device up. + +Having probing separate from ofdata-reading helps deal with of-platdata, where +the probe() method is common to both DT/of-platdata operation, but the +of_to_plat() method is implemented differently. + +Another case has come up where this separate is useful. Generation of ACPI +tables uses the of-platdata but does not want to probe the device. Probing +would cause U-Boot to violate one of its design principles, viz that it +should only probe devices that are used. For ACPI we want to generate a +table for each device, even if U-Boot does not use it. In fact it may not +even be possible to probe the device - e.g. an SD card which is not +present will cause an error on probe, yet we still must tell Linux about +the SD card connector in case it is used while Linux is running. + +It is important that the of_to_plat() method does not actually probe +the device itself. However there are cases where other devices must be probed +in the of_to_plat() method. An example is where a device requires a +GPIO for it to operate. To select a GPIO obviously requires that the GPIO +device is probed. This is OK when used by common, core devices such as GPIO, +clock, interrupts, reset and the like. + +If your device relies on its parent setting up a suitable address space, so +that dev_read_addr() works correctly, then make sure that the parent device +has its setup code in of_to_plat(). If it has it in the probe method, +then you cannot call dev_read_addr() from the child device's +of_to_plat() method. Move it to probe() instead. Buses like PCI can +fall afoul of this rule. + +Activation/probe +^^^^^^^^^^^^^^^^ + +When a device needs to be used, U-Boot activates it, by first reading ofdata +as above and then following these steps (see device_probe()): + + 1. All parent devices are probed. It is not possible to activate a device + unless its predecessors (all the way up to the root device) are activated. + This means (for example) that an I2C driver will require that its bus + be activated. + + 2. The device's probe() method is called. This should do anything that + is required by the device to get it going. This could include checking + that the hardware is actually present, setting up clocks for the + hardware and setting up hardware registers to initial values. The code + in probe() can access: + + - platform data in dev->plat (for configuration) + - private data in dev->priv (for run-time state) + - uclass data in dev->uclass_priv (for things the uclass stores + about this device) + + Note: If you don't use priv_auto then you will need to + allocate the priv space here yourself. The same applies also to + plat_auto. Remember to free them in the remove() method. + + 3. The device is marked 'activated' + + 4. The uclass's post_probe() method is called, if one exists. This may + cause the uclass to do some housekeeping to record the device as + activated and 'known' by the uclass. + +Running stage +^^^^^^^^^^^^^ + +The device is now activated and can be used. From now until it is removed +all of the above structures are accessible. The device appears in the +uclass's list of devices (so if the device is in UCLASS_GPIO it will appear +as a device in the GPIO uclass). This is the 'running' state of the device. + +Removal stage +^^^^^^^^^^^^^ + +When the device is no-longer required, you can call device_remove() to +remove it. This performs the probe steps in reverse: + + 1. The uclass's pre_remove() method is called, if one exists. This may + cause the uclass to do some housekeeping to record the device as + deactivated and no-longer 'known' by the uclass. + + 2. All the device's children are removed. It is not permitted to have + an active child device with a non-active parent. This means that + device_remove() is called for all the children recursively at this point. + + 3. The device's remove() method is called. At this stage nothing has been + deallocated so platform data, private data and the uclass data will all + still be present. This is where the hardware can be shut down. It is + intended that the device be completely inactive at this point, For U-Boot + to be sure that no hardware is running, it should be enough to remove + all devices. + + 4. The device memory is freed (platform data, private data, uclass data, + parent data). + + Note: Because the platform data for a U_BOOT_DRVINFO() is defined with a + static pointer, it is not de-allocated during the remove() method. For + a device instantiated using the device tree data, the platform data will + be dynamically allocated, and thus needs to be deallocated during the + remove() method, either: + + - if the plat_auto is non-zero, the deallocation happens automatically + within the driver model core in the unbind stage; or + + - when plat_auto is 0, both the allocation (in probe() + or preferably of_to_plat()) and the deallocation in remove() + are the responsibility of the driver author. + + 5. The device is marked inactive. Note that it is still bound, so the + device structure itself is not freed at this point. Should the device be + activated again, then the cycle starts again at step 2 above. + +Unbind stage +^^^^^^^^^^^^ + +The device is unbound. This is the step that actually destroys the device. +If a parent has children these will be destroyed first. After this point +the device does not exist and its memory has be deallocated. + + +Special cases for removal +------------------------- + +Some devices need to do clean-up before the OS is called. For example, a USB +driver may want to stop the bus. This can be done in the remove() method. +Some special flags are used to determine whether to remove the device: + + DM_FLAG_OS_PREPARE - indicates that the device needs to get ready for OS + boot. The device will be removed just before the OS is booted + DM_REMOVE_ACTIVE_DMA - indicates that the device uses DMA. This is + effectively the same as DM_FLAG_OS_PREPARE, so the device is removed + before the OS is booted + DM_FLAG_VITAL - indicates that the device is 'vital' to the operation of + other devices. It is possible to remove this device after all regular + devices are removed. This is useful e.g. for a clock, which need to + be active during the device-removal phase. + +The dm_remove_devices_flags() function can be used to remove devices based on +their driver flags. + + +Error codes +----------- + +Driver model tries to use errors codes in a consistent way, as follows: + +\-EAGAIN + Try later, e.g. dependencies not ready + +\-EINVAL + Invalid argument, such as `dev_read_...()` failed or any other + devicetree-related access. Also used when a driver method is passed an + argument it considers invalid or does not support. + +\-EIO + Failed to perform an I/O operation. This is used when a local device + (i.e. part of the SOC) does not work as expected. Use -EREMOTEIO for + failures to talk to a separate device, e.g. over an I2C or SPI + channel. + +\-ENODEV + Do not bind the device. This should not be used to indicate an + error probing the device or for any other purpose, lest driver model get + confused. Using `-ENODEV` inside a driver method makes no sense, since + clearly there is a device. + +\-ENOENT + Entry or object not found. This is used when a device, file or directory + cannot be found (e.g. when looked up by name), It can also indicate a + missing devicetree subnode. + +\-ENOMEM + Out of memory + +\-ENOSPC + Ran out of space (e.g. in a buffer or limited-size array) + +\-ENOSYS + Function not implemented. This is returned by uclasses where the driver does + not implement a particular method. It can also be returned by drivers when + a particular sub-method is not implemented. This is widely checked in the + wider code base, where a feature may or may not be compiled into U-Boot. It + indicates that the feature is not available, but this is often just normal + operation. Please do not use -ENOSUPP. If an incorrect or unknown argument + is provided to a method (e.g. an unknown clock ID), return -EINVAL. + +\-ENXIO + Couldn't find device/address. This is used when a device or address + could not be obtained or is not valid. It is often used to indicate a + different type of problem, if -ENOENT is already used for something else in + the driver. + +\-EPERM + This is -1 so some older code may use it as a generic error. This indicates + that an operation is not permitted, e.g. a security violation or policy + constraint. It is returned internally when binding devices before relocation, + if the device is not marked for pre-relocation use. + +\-EPFNOSUPPORT + Missing uclass. This is deliberately an uncommon error code so that it can + easily be distinguished. If you see this very early in U-Boot, it means that + a device exists with a particular uclass but the uclass does not (mostly + likely because it is not compiled in). Enable DEBUG in uclass.c or lists.c + to see which uclass ID or driver is causing the problem. + +\-EREMOTEIO + This indicates an error in talking to a peripheral over a comms link, such + as I2C or SPI. It might indicate that the device is not present or is not + responding as expected. + +\-ETIMEDOUT + Hardware access or some other operation has timed out. This is used where + there is an expected time of response and that was exceeded by enough of + a margin that there is probably something wrong. + + +Less common ones: + +\-ECOMM + Not widely used, but similar to -EREMOTEIO. Can be useful as a secondary + error to distinguish the problem from -EREMOTEIO. + +\-EKEYREJECTED + Attempt to remove a device which does not match the removal flags. See + device_remove(). + +\-EILSEQ + Devicetree read failure, specifically trying to read a string index which + does not exist, in a string-listg property + +\-ENOEXEC + Attempt to use a uclass method on a device not in that uclass. This is + seldom checked at present, since it is generally a programming error and a + waste of code space. A DEBUG-only check would be useful here. + +\-ENODATA + Devicetree read error, where a property exists but has no data associated + with it + +\-EOVERFLOW + Devicetree read error, where the property is longer than expected + +\-EPROBE_DEFER + Attempt to remove a non-vital device when the removal flags indicate that + only vital devices should be removed + +\-ERANGE + Returned by regmap functions when arguments are out of range. This can be + useful for disinguishing regmap errors from other errors obtained while + probing devices. + +Drivers should use the same conventions so that things function as expected. +In particular, if a driver fails to probe, or a uclass operation fails, the +error code is the primary way to indicate what actually happened. + +Printing error messages in drivers is discouraged due to code size bloat and +since it can result in messages appearing in normal operation. For example, if +a command tries two different devices and uses whichever one probes correctly, +we don't want an error message displayed, even if the command itself might show +a warning or informational message. Ideally, messages in drivers should only be +displayed when debugging, e.g. by using log_debug() although in extreme cases +log_warning() or log_error() may be used. + +Error messages can be logged using `log_msg_ret()`, so that enabling +`CONFIG_LOG` and `CONFIG_LOG_ERROR_RETURN` shows a trace of error codes returned +through the call stack. That can be a handy way of quickly figuring out where +an error occurred. Get into the habit of return errors with +`return log_msg_ret("here", ret)` instead of just `return ret`. The string +just needs to be long enough to find in a single function, since a log record +stores (and can print with `CONFIG_LOGF_FUNC`) the function where it was +generated. + + +Data Structures +--------------- + +Driver model uses a doubly-linked list as the basic data structure. Some +nodes have several lists running through them. Creating a more efficient +data structure might be worthwhile in some rare cases, once we understand +what the bottlenecks are. + + +Changes since v1 +---------------- + +For the record, this implementation uses a very similar approach to the +original patches, but makes at least the following changes: + +- Tried to aggressively remove boilerplate, so that for most drivers there + is little or no 'driver model' code to write. +- Moved some data from code into data structure - e.g. store a pointer to + the driver operations structure in the driver, rather than passing it + to the driver bind function. +- Rename some structures to make them more similar to Linux (struct udevice + instead of struct instance, struct plat, etc.) +- Change the name 'core' to 'uclass', meaning U-Boot class. It seems that + this concept relates to a class of drivers (or a subsystem). We shouldn't + use 'class' since it is a C++ reserved word, so U-Boot class (uclass) seems + better than 'core'. +- Remove 'struct driver_instance' and just use a single 'struct udevice'. + This removes a level of indirection that doesn't seem necessary. +- Built in device tree support, to avoid the need for plat +- Removed the concept of driver relocation, and just make it possible for + the new driver (created after relocation) to access the old driver data. + I feel that relocation is a very special case and will only apply to a few + drivers, many of which can/will just re-init anyway. So the overhead of + dealing with this might not be worth it. +- Implemented a GPIO system, trying to keep it simple + + +Pre-Relocation Support +---------------------- + +For pre-relocation we simply call the driver model init function. Only +drivers marked with DM_FLAG_PRE_RELOC or the device tree 'u-boot,dm-pre-reloc' +property are initialised prior to relocation. This helps to reduce the driver +model overhead. This flag applies to SPL and TPL as well, if device tree is +enabled (CONFIG_OF_CONTROL) there. + +Note when device tree is enabled, the device tree 'u-boot,dm-pre-reloc' +property can provide better control granularity on which device is bound +before relocation. While with DM_FLAG_PRE_RELOC flag of the driver all +devices with the same driver are bound, which requires allocation a large +amount of memory. When device tree is not used, DM_FLAG_PRE_RELOC is the +only way for statically declared devices via U_BOOT_DRVINFO() to be bound +prior to relocation. + +It is possible to limit this to specific relocation steps, by using +the more specialized 'u-boot,dm-spl' and 'u-boot,dm-tpl' flags +in the device tree node. For U-Boot proper you can use 'u-boot,dm-pre-proper' +which means that it will be processed (and a driver bound) in U-Boot proper +prior to relocation, but will not be available in SPL or TPL. + +To reduce the size of SPL and TPL, only the nodes with pre-relocation properties +('u-boot,dm-pre-reloc', 'u-boot,dm-spl' or 'u-boot,dm-tpl') are keept in their +device trees (see README.SPL for details); the remaining nodes are always bound. + +Then post relocation we throw that away and re-init driver model again. +For drivers which require some sort of continuity between pre- and +post-relocation devices, we can provide access to the pre-relocation +device pointers, but this is not currently implemented (the root device +pointer is saved but not made available through the driver model API). + + +SPL Support +----------- + +Driver model can operate in SPL. Its efficient implementation and small code +size provide for a small overhead which is acceptable for all but the most +constrained systems. + +To enable driver model in SPL, define CONFIG_SPL_DM. You might want to +consider the following option also. See the main README for more details. + + - CONFIG_SYS_MALLOC_SIMPLE + - CONFIG_DM_WARN + - CONFIG_DM_DEVICE_REMOVE + - CONFIG_DM_STDIO + + +Enabling Driver Model +--------------------- + +Driver model is being brought into U-Boot gradually. As each subsystems gets +support, a uclass is created and a CONFIG to enable use of driver model for +that subsystem. + +For example CONFIG_DM_SERIAL enables driver model for serial. With that +defined, the old serial support is not enabled, and your serial driver must +conform to driver model. With that undefined, the old serial support is +enabled and driver model is not available for serial. This means that when +you convert a driver, you must either convert all its boards, or provide for +the driver to be compiled both with and without driver model (generally this +is not very hard). + +See the main README for full details of the available driver model CONFIG +options. + + +Things to punt for later +------------------------ + +Uclasses are statically numbered at compile time. It would be possible to +change this to dynamic numbering, but then we would require some sort of +lookup service, perhaps searching by name. This is slightly less efficient +so has been left out for now. One small advantage of dynamic numbering might +be fewer merge conflicts in uclass-id.h. diff --git a/roms/u-boot/doc/develop/driver-model/ethernet.rst b/roms/u-boot/doc/develop/driver-model/ethernet.rst new file mode 100644 index 000000000..cdbccca34 --- /dev/null +++ b/roms/u-boot/doc/develop/driver-model/ethernet.rst @@ -0,0 +1,321 @@ +Ethernet Driver Guide +======================= + +The networking stack in Das U-Boot is designed for multiple network devices +to be easily added and controlled at runtime. This guide is meant for people +who wish to review the net driver stack with an eye towards implementing your +own ethernet device driver. Here we will describe a new pseudo 'APE' driver. + +Most existing drivers do already - and new network driver MUST - use the +U-Boot core driver model. Generic information about this can be found in +doc/driver-model/design.rst, this document will thus focus on the network +specific code parts. +Some drivers are still using the old Ethernet interface, differences between +the two and hints about porting will be handled at the end. + +Driver framework +------------------ + +A network driver following the driver model must declare itself using +the UCLASS_ETH .id field in the U-Boot driver struct: + +.. code-block:: c + + U_BOOT_DRIVER(eth_ape) = { + .name = "eth_ape", + .id = UCLASS_ETH, + .of_match = eth_ape_ids, + .of_to_plat = eth_ape_of_to_plat, + .probe = eth_ape_probe, + .ops = ð_ape_ops, + .priv_auto = sizeof(struct eth_ape_priv), + .plat_auto = sizeof(struct eth_ape_pdata), + .flags = DM_FLAG_ALLOC_PRIV_DMA, + }; + +struct eth_ape_priv contains runtime per-instance data, like buffers, pointers +to current descriptors, current speed settings, pointers to PHY related data +(like struct mii_dev) and so on. Declaring its size in .priv_auto +will let the driver framework allocate it at the right time. +It can be retrieved using a dev_get_priv(dev) call. + +struct eth_ape_pdata contains static platform data, like the MMIO base address, +a hardware variant, the MAC address. ``struct eth_pdata eth_pdata`` +as the first member of this struct helps to avoid duplicated code. +If you don't need any more platform data beside the standard member, +just use sizeof(struct eth_pdata) for the plat_auto. + +PCI devices add a line pointing to supported vendor/device ID pairs: + +.. code-block:: c + + static struct pci_device_id supported[] = { + { PCI_DEVICE(PCI_VENDOR_ID_APE, 0x4223) }, + {} + }; + + U_BOOT_PCI_DEVICE(eth_ape, supported); + +It is also possible to declare support for a whole class of PCI devices:: + + { PCI_DEVICE_CLASS(PCI_CLASS_SYSTEM_SDHCI << 8, 0xffff00) }, + +Device probing and instantiation will be handled by the driver model framework, +so follow the guidelines there. The probe() function would initialise the +platform specific parts of the hardware, like clocks, resets, GPIOs, the MDIO +bus. Also it would take care of any special PHY setup (power rails, enable +bits for internal PHYs, etc.). + +Driver methods +---------------- + +The real work will be done in the driver method functions the driver provides +by defining the members of struct eth_ops: + +.. code-block:: c + + struct eth_ops { + int (*start)(struct udevice *dev); + int (*send)(struct udevice *dev, void *packet, int length); + int (*recv)(struct udevice *dev, int flags, uchar **packetp); + int (*free_pkt)(struct udevice *dev, uchar *packet, int length); + void (*stop)(struct udevice *dev); + int (*mcast)(struct udevice *dev, const u8 *enetaddr, int join); + int (*write_hwaddr)(struct udevice *dev); + int (*read_rom_hwaddr)(struct udevice *dev); + }; + +An up-to-date version of this struct together with more information can be +found in include/net.h. + +Only start, stop, send and recv are required, the rest are optional and are +handled by generic code or ignored if not provided. + +The **start** function initialises the hardware and gets it ready for send/recv +operations. You often do things here such as resetting the MAC +and/or PHY, and waiting for the link to autonegotiate. You should also take +the opportunity to program the device's MAC address with the enetaddr member +of the generic struct eth_pdata (which would be the first member of your +own plat struct). This allows the rest of U-Boot to dynamically change +the MAC address and have the new settings be respected. + +The **send** function does what you think -- transmit the specified packet +whose size is specified by length (in bytes). The packet buffer can (and +will!) be reused for subsequent calls to send(), so it must be no longer +used when the send() function returns. The easiest way to achieve this is +to wait until the transmission is complete. Alternatively, if supported by +the hardware, just waiting for the buffer to be consumed (by some DMA engine) +might be an option as well. +Another way of consuming the buffer could be to copy the data to be send, +then just queue the copied packet (for instance handing it over to a DMA +engine), and return immediately afterwards. +In any case you should leave the state such that the send function can be +called multiple times in a row. + +The **recv** function polls for availability of a new packet. If none is +available, it must return with -EAGAIN. +If a packet has been received, make sure it is accessible to the CPU +(invalidate caches if needed), then write its address to the packetp pointer, +and return the length. If there is an error (receive error, too short or too +long packet), return 0 if you require the packet to be cleaned up normally, +or a negative error code otherwise (cleanup not necessary or already done). +The U-Boot network stack will then process the packet. + +If **free_pkt** is defined, U-Boot will call it after a received packet has +been processed, so the packet buffer can be freed or recycled. Typically you +would hand it back to the hardware to acquire another packet. free_pkt() will +be called after recv(), for the same packet, so you don't necessarily need +to infer the buffer to free from the ``packet`` pointer, but can rely on that +being the last packet that recv() handled. +The common code sets up packet buffers for you already in the .bss +(net_rx_packets), so there should be no need to allocate your own. This doesn't +mean you must use the net_rx_packets array however; you're free to use any +buffer you wish. + +The **stop** function should turn off / disable the hardware and place it back +in its reset state. It can be called at any time (before any call to the +related start() function), so make sure it can handle this sort of thing. + +The (optional) **write_hwaddr** function should program the MAC address stored +in pdata->enetaddr into the Ethernet controller. + +So the call graph at this stage would look something like: + +.. code-block:: c + + (some net operation (ping / tftp / whatever...)) + eth_init() + ops->start() + eth_send() + ops->send() + eth_rx() + ops->recv() + (process packet) + if (ops->free_pkt) + ops->free_pkt() + eth_halt() + ops->stop() + + +CONFIG_PHYLIB / CONFIG_CMD_MII +-------------------------------- + +If your device supports banging arbitrary values on the MII bus (pretty much +every device does), you should add support for the mii command. Doing so is +fairly trivial and makes debugging mii issues a lot easier at runtime. + +In your driver's ``probe()`` function, add a call to mdio_alloc() and +mdio_register() like so: + +.. code-block:: c + + bus = mdio_alloc(); + if (!bus) { + ... + return -ENOMEM; + } + + bus->read = ape_mii_read; + bus->write = ape_mii_write; + mdio_register(bus); + +And then define the mii_read and mii_write functions if you haven't already. +Their syntax is straightforward:: + + int mii_read(struct mii_dev *bus, int addr, int devad, int reg); + int mii_write(struct mii_dev *bus, int addr, int devad, int reg, + u16 val); + +The read function should read the register 'reg' from the phy at address 'addr' +and return the result to its caller. The implementation for the write function +should logically follow. + +................................................................ + +Legacy network drivers +------------------------ + +!!! WARNING !!! + +This section below describes the old way of doing things. No new Ethernet +drivers should be implemented this way. All new drivers should be written +against the U-Boot core driver model, as described above. + +The actual callback functions are fairly similar, the differences are: + +- ``start()`` is called ``init()`` +- ``stop()`` is called ``halt()`` +- The ``recv()`` function must loop until all packets have been received, for + each packet it must call the net_process_received_packet() function, + handing it over the pointer and the length. Afterwards it should free + the packet, before checking for new data. + +For porting an old driver to the new driver model, split the existing recv() +function into the actual new recv() function, just fetching **one** packet, +remove the call to net_process_received_packet(), then move the packet +cleanup into the ``free_pkt()`` function. + +Registering the driver and probing a device is handled very differently, +follow the recommendations in the driver model design documentation for +instructions on how to port this over. For the records, the old way of +initialising a network driver is as follows: + +Old network driver registration +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +When U-Boot initializes, it will call the common function eth_initialize(). +This will in turn call the board-specific board_eth_init() (or if that fails, +the cpu-specific cpu_eth_init()). These board-specific functions can do random +system handling, but ultimately they will call the driver-specific register +function which in turn takes care of initializing that particular instance. + +Keep in mind that you should code the driver to avoid storing state in global +data as someone might want to hook up two of the same devices to one board. +Any such information that is specific to an interface should be stored in a +private, driver-defined data structure and pointed to by eth->priv (see below). + +So the call graph at this stage would look something like: + +.. code-block:: c + + board_init() + eth_initialize() + board_eth_init() / cpu_eth_init() + driver_register() + initialize eth_device + eth_register() + +At this point in time, the only thing you need to worry about is the driver's +register function. The pseudo code would look something like: + +.. code-block:: c + + int ape_register(struct bd_info *bis, int iobase) + { + struct ape_priv *priv; + struct eth_device *dev; + struct mii_dev *bus; + + priv = malloc(sizeof(*priv)); + if (priv == NULL) + return -ENOMEM; + + dev = malloc(sizeof(*dev)); + if (dev == NULL) { + free(priv); + return -ENOMEM; + } + + /* setup whatever private state you need */ + + memset(dev, 0, sizeof(*dev)); + sprintf(dev->name, "APE"); + + /* + * if your device has dedicated hardware storage for the + * MAC, read it and initialize dev->enetaddr with it + */ + ape_mac_read(dev->enetaddr); + + dev->iobase = iobase; + dev->priv = priv; + dev->init = ape_init; + dev->halt = ape_halt; + dev->send = ape_send; + dev->recv = ape_recv; + dev->write_hwaddr = ape_write_hwaddr; + + eth_register(dev); + + #ifdef CONFIG_PHYLIB + bus = mdio_alloc(); + if (!bus) { + free(priv); + free(dev); + return -ENOMEM; + } + + bus->read = ape_mii_read; + bus->write = ape_mii_write; + mdio_register(bus); + #endif + + return 1; + } + +The exact arguments needed to initialize your device are up to you. If you +need to pass more/less arguments, that's fine. You should also add the +prototype for your new register function to include/netdev.h. + +The return value for this function should be as follows: +< 0 - failure (hardware failure, not probe failure) +>=0 - number of interfaces detected + +You might notice that many drivers seem to use xxx_initialize() rather than +xxx_register(). This is the old naming convention and should be avoided as it +causes confusion with the driver-specific init function. + +Other than locating the MAC address in dedicated hardware storage, you should +not touch the hardware in anyway. That step is handled in the driver-specific +init function. Remember that we are only registering the device here, we are +not checking its state or doing random probing. diff --git a/roms/u-boot/doc/develop/driver-model/fdt-fixup.rst b/roms/u-boot/doc/develop/driver-model/fdt-fixup.rst new file mode 100644 index 000000000..974c09031 --- /dev/null +++ b/roms/u-boot/doc/develop/driver-model/fdt-fixup.rst @@ -0,0 +1,132 @@ +.. SPDX-License-Identifier: GPL-2.0+ +.. 2017-01-06, Mario Six <mario.six@gdsys.cc> + +Pre-relocation device tree manipulation +======================================= + +Purpose +------- + +In certain markets, it is beneficial for manufacturers of embedded devices to +offer certain ranges of products, where the functionality of the devices within +one series either don't differ greatly from another, or can be thought of as +"extensions" of each other, where one device only differs from another in the +addition of a small number of features (e.g. an additional output connector). + +To realize this in hardware, one method is to have a motherboard, and several +possible daughter boards that can be attached to this mother board. Different +daughter boards then either offer the slightly different functionality, or the +addition of the daughter board to the device realizes the "extension" of +functionality to the device described previously. + +For the software, we obviously want to reuse components for all these +variations of the device. This means that the software somehow needs to cope +with the situation that certain ICs may or may not be present on any given +system, depending on which daughter boards are connected to the motherboard. + +In the Linux kernel, one possible solution to this problem is to employ the +device tree overlay mechanism: There exists one "base" device tree, which +features only the components guaranteed to exist in all varieties of the +device. At the start of the kernel, the presence and type of the daughter +boards is then detected, and the corresponding device tree overlays are applied +to support the components on the daughter boards. + +Note that the components present on every variety of the board must, of course, +provide a way to find out if and which daughter boards are installed for this +mechanism to work. + +In the U-Boot boot loader, support for device tree overlays has recently been +integrated, and is used on some boards to alter the device tree that is later +passed to Linux. But since U-Boot's driver model, which is device tree-based as +well, is being used in more and more drivers, the same problem of altering the +device tree starts cropping up in U-Boot itself as well. + +An additional problem with the device tree in U-Boot is that it is read-only, +and the current mechanisms don't allow easy manipulation of the device tree +after the driver model has been initialized. While migrating to a live device +tree (at least after the relocation) would greatly simplify the solution of +this problem, it is a non-negligible task to implement it, an a interim +solution is needed to address the problem at least in the medium-term. + +Hence, we propose a solution to this problem by offering a board-specific +call-back function, which is passed a writeable pointer to the device tree. +This function is called before the device tree is relocated, and specifically +before the main U-Boot's driver model is instantiated, hence the main U-Boot +"sees" all modifications to the device tree made in this function. Furthermore, +we have the pre-relocation driver model at our disposal at this stage, which +means that we can query the hardware for the existence and variety of the +components easily. + +Implementation +-------------- + +To take advantage of the pre-relocation device tree manipulation mechanism, +boards have to implement the function board_fix_fdt, which has the following +signature: + +.. code-block:: c + + int board_fix_fdt (void *rw_fdt_blob) + +The passed-in void pointer is a writeable pointer to the device tree, which can +be used to manipulate the device tree using e.g. functions from +include/fdt_support.h. The return value should either be 0 in case of +successful execution of the device tree manipulation or something else for a +failure. Note that returning a non-null value from the function will +unrecoverably halt the boot process, as with any function from init_sequence_f +(in common/board_f.c). + +Furthermore, the Kconfig option OF_BOARD_FIXUP has to be set for the function +to be called:: + + Device Tree Control + -> [*] Board-specific manipulation of Device Tree + ++----------------------------------------------------------+ +| WARNING: The actual manipulation of the device tree has | +| to be the _last_ set of operations in board_fix_fdt! | +| Since the pre-relocation driver model does not adapt to | +| changes made to the device tree either, its references | +| into the device tree will be invalid after manipulating | +| it, and unpredictable behavior might occur when | +| functions that rely on them are executed! | ++----------------------------------------------------------+ + +Hence, the recommended layout of the board_fixup_fdt call-back function is the +following: + +.. code-block:: c + + int board_fix_fdt(void *rw_fdt_blob) + { + /* + * Collect information about device's hardware and store + * them in e.g. local variables + */ + + /* Do device tree manipulation using the values previously collected */ + + /* Return 0 on successful manipulation and non-zero otherwise */ + } + +If this convention is kept, both an "additive" approach, meaning that nodes for +detected components are added to the device tree, as well as a "subtractive" +approach, meaning that nodes for absent components are removed from the tree, +as well as a combination of both approaches should work. + +Example +------- + +The controlcenterdc board (board/gdsys/a38x/controlcenterdc.c) features a +board_fix_fdt function, in which six GPIO expanders (which might be present or +not, since they are on daughter boards) on a I2C bus are queried for, and +subsequently deactivated in the device tree if they are not present. + +Note that the dm_i2c_simple_probe function does not use the device tree, hence +it is safe to call it after the tree has already been manipulated. + +Work to be done +--------------- + +* The application of device tree overlay should be possible in board_fixup_fdt, + but has not been tested at this stage. diff --git a/roms/u-boot/doc/develop/driver-model/fs_firmware_loader.rst b/roms/u-boot/doc/develop/driver-model/fs_firmware_loader.rst new file mode 100644 index 000000000..a44708cb4 --- /dev/null +++ b/roms/u-boot/doc/develop/driver-model/fs_firmware_loader.rst @@ -0,0 +1,154 @@ +.. SPDX-License-Identifier: GPL-2.0+ +.. Copyright (C) 2018-2019 Intel Corporation <www.intel.com> + +File System Firmware Loader +=========================== + +This is file system firmware loader for U-Boot framework, which has very close +to some Linux Firmware API. For the details of Linux Firmware API, you can refer +to https://01.org/linuxgraphics/gfx-docs/drm/driver-api/firmware/index.html. + +File system firmware loader can be used to load whatever(firmware, image, +and binary) from the storage device in file system format into target location +such as memory, then consumer driver such as FPGA driver can program FPGA image +from the target location into FPGA. + +To enable firmware loader, CONFIG_FS_LOADER need to be set at +<board_name>_defconfig such as "CONFIG_FS_LOADER=y". + +Firmware Loader API core features +--------------------------------- + +Firmware storage device described in device tree source +------------------------------------------------------- +For passing data like storage device phandle and partition where the +firmware loading from to the firmware loader driver, those data could be +defined in fs-loader node as shown in below: + +Example for block device:: + + fs_loader0: fs-loader { + u-boot,dm-pre-reloc; + compatible = "u-boot,fs-loader"; + phandlepart = <&mmc 1>; + }; + +<&mmc 1> means block storage device pointer and its partition. + +Above example is a description for block storage, but for UBI storage +device, it can be described in FDT as shown in below: + +Example for ubi:: + + fs_loader1: fs-loader { + u-boot,dm-pre-reloc; + compatible = "u-boot,fs-loader"; + mtdpart = "UBI", + ubivol = "ubi0"; + }; + +Then, firmware-loader property can be added with any device node, which +driver would use the firmware loader for loading. + +The value of the firmware-loader property should be set with phandle +of the fs-loader node. For example:: + + firmware-loader = <&fs_loader0>; + +If there are majority of devices using the same fs-loader node, then +firmware-loader property can be added under /chosen node instead of +adding to each of device node. + +For example:: + + /{ + chosen { + firmware-loader = <&fs_loader0>; + }; + }; + +In each respective driver of devices using firmware loader, the firmware +loaded instance should be created by DT phandle. + +For example of getting DT phandle from /chosen and creating instance: + +.. code-block:: c + + chosen_node = ofnode_path("/chosen"); + if (!ofnode_valid(chosen_node)) { + debug("/chosen node was not found.\n"); + return -ENOENT; + } + + phandle_p = ofnode_get_property(chosen_node, "firmware-loader", &size); + if (!phandle_p) { + debug("firmware-loader property was not found.\n"); + return -ENOENT; + } + + phandle = fdt32_to_cpu(*phandle_p); + ret = uclass_get_device_by_phandle_id(UCLASS_FS_FIRMWARE_LOADER, + phandle, &dev); + if (ret) + return ret; + +Firmware loader driver is also designed to support U-boot environment +variables, so all these data from FDT can be overwritten +through the U-boot environment variable during run time. + +For examples: + +storage_interface: + Storage interface, it can be "mmc", "usb", "sata" or "ubi". +fw_dev_part: + Block device number and its partition, it can be "0:1". +fw_ubi_mtdpart: + UBI device mtd partition, it can be "UBI". +fw_ubi_volume: + UBI volume, it can be "ubi0". + +When above environment variables are set, environment values would be +used instead of data from FDT. +The benefit of this design allows user to change storage attribute data +at run time through U-boot console and saving the setting as default +environment values in the storage for the next power cycle, so no +compilation is required for both driver and FDT. + +File system firmware Loader API +------------------------------- + +.. code-block:: c + + int request_firmware_into_buf(struct udevice *dev, + const char *name, + void *buf, size_t size, u32 offset) + +Load firmware into a previously allocated buffer + +Parameters: + +* struct udevice \*dev: An instance of a driver +* const char \*name: name of firmware file +* void \*buf: address of buffer to load firmware into +* size_t size: size of buffer +* u32 offset: offset of a file for start reading into buffer + +Returns: + size of total read + -ve when error + +Description: + The firmware is loaded directly into the buffer pointed to by buf + +Example of calling request_firmware_into_buf API after creating firmware loader +instance: + +.. code-block:: c + + ret = uclass_get_device_by_phandle_id(UCLASS_FS_FIRMWARE_LOADER, + phandle, &dev); + if (ret) + return ret; + + request_firmware_into_buf(dev, filename, buffer_location, buffer_size, + offset_ofreading); diff --git a/roms/u-boot/doc/develop/driver-model/i2c-howto.rst b/roms/u-boot/doc/develop/driver-model/i2c-howto.rst new file mode 100644 index 000000000..27e7440cd --- /dev/null +++ b/roms/u-boot/doc/develop/driver-model/i2c-howto.rst @@ -0,0 +1,56 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +How to port an I2C driver to driver model +========================================= + +Over half of the I2C drivers have been converted as at November 2016. These +ones remain: + + * adi_i2c + * davinci_i2c + * fti2c010 + * ihs_i2c + * kona_i2c + * lpc32xx_i2c + * pca9564_i2c + * ppc4xx_i2c + * rcar_i2c + * sh_i2c + * soft_i2c + * zynq_i2c + +The deadline for this work is the end of June 2017. If no one steps +forward to convert these, at some point there may come a patch to remove them! + +Here is a suggested approach for converting your I2C driver over to driver +model. Please feel free to update this file with your ideas and suggestions. + +- #ifdef out all your own I2C driver code (#if !CONFIG_IS_ENABLED(DM_I2C)) +- Define CONFIG_DM_I2C for your board, vendor or architecture +- If the board does not already use driver model, you need CONFIG_DM also +- Your board should then build, but will not work fully since there will be + no I2C driver +- Add the U_BOOT_DRIVER piece at the end (e.g. copy tegra_i2c.c for example) +- Add a private struct for the driver data - avoid using static variables +- Implement each of the driver methods, perhaps by calling your old methods +- You may need to adjust the function parameters so that the old and new + implementations can share most of the existing code +- If you convert all existing users of the driver, remove the pre-driver-model + code + +In terms of patches a conversion series typically has these patches: +- clean up / prepare the driver for conversion +- add driver model code +- convert at least one existing board to use driver model serial +- (if no boards remain that don't use driver model) remove the old code + +This may be a good time to move your board to use device tree also. Mostly +this involves these steps: + +- define CONFIG_OF_CONTROL and CONFIG_OF_SEPARATE +- add your device tree files to arch/<arch>/dts +- update the Makefile there +- Add stdout-path to your /chosen device tree node if it is not already there +- build and get u-boot-dtb.bin so you can test it +- Your drivers can now use device tree +- For device tree in SPL, define CONFIG_SPL_OF_CONTROL diff --git a/roms/u-boot/doc/develop/driver-model/index.rst b/roms/u-boot/doc/develop/driver-model/index.rst new file mode 100644 index 000000000..7366ef818 --- /dev/null +++ b/roms/u-boot/doc/develop/driver-model/index.rst @@ -0,0 +1,31 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +Driver Model +============ + +The following holds information on the U-Boot device driver framework: +driver-model, including the design details of itself and several driver +subsystems + +.. toctree:: + :maxdepth: 2 + + bind + debugging + design + ethernet + fdt-fixup + fs_firmware_loader + i2c-howto + livetree + migration + nvme + of-plat + pci-info + pmic-framework + remoteproc-framework + serial-howto + soc-framework + spi-howto + usb-info + virtio diff --git a/roms/u-boot/doc/develop/driver-model/livetree.rst b/roms/u-boot/doc/develop/driver-model/livetree.rst new file mode 100644 index 000000000..9f654f3b8 --- /dev/null +++ b/roms/u-boot/doc/develop/driver-model/livetree.rst @@ -0,0 +1,286 @@ +.. SPDX-License-Identifier: GPL-2.0+ +.. sectionauthor:: Simon Glass <sjg@chromium.org> + +Live Device Tree +================ + + +Introduction +------------ + +Traditionally U-Boot has used a 'flat' device tree. This means that it +reads directly from the device tree binary structure. It is called a flat +device tree because nodes are listed one after the other, with the +hierarchy detected by tags in the format. + +This document describes U-Boot's support for a 'live' device tree, meaning +that the tree is loaded into a hierarchical data structure within U-Boot. + + +Motivation +---------- + +The flat device tree has several advantages: + +- it is the format produced by the device tree compiler, so no translation + is needed + +- it is fairly compact (e.g. there is no need for pointers) + +- it is accessed by the libfdt library, which is well tested and stable + + +However the flat device tree does have some limitations. Adding new +properties can involve copying large amounts of data around to make room. +The overall tree has a fixed maximum size so sometimes the tree must be +rebuilt in a new location to create more space. Even if not adding new +properties or nodes, scanning the tree can be slow. For example, finding +the parent of a node is a slow process. Reading from nodes involves a +small amount parsing which takes a little time. + +Driver model scans the entire device tree sequentially on start-up which +avoids the worst of the flat tree's limitations. But if the tree is to be +modified at run-time, a live tree is much faster. Even if no modification +is necessary, parsing the tree once and using a live tree from then on +seems to save a little time. + + +Implementation +-------------- + +In U-Boot a live device tree ('livetree') is currently supported only +after relocation. Therefore we need a mechanism to specify a device +tree node regardless of whether it is in the flat tree or livetree. + +The 'ofnode' type provides this. An ofnode can point to either a flat tree +node (when the live tree node is not yet set up) or a livetree node. The +caller of an ofnode function does not need to worry about these details. + +The main users of the information in a device tree are drivers. These have +a 'struct udevice \*' which is attached to a device tree node. Therefore it +makes sense to be able to read device tree properties using the +'struct udevice \*', rather than having to obtain the ofnode first. + +The 'dev_read\_...()' interface provides this. It allows properties to be +easily read from the device tree using only a device pointer. Under the +hood it uses ofnode so it works with both flat and live device trees. + + +Enabling livetree +----------------- + +CONFIG_OF_LIVE enables livetree. When this option is enabled, the flat +tree will be used in SPL and before relocation in U-Boot proper. Just +before relocation a livetree is built, and this is used for U-Boot proper +after relocation. + +Most checks for livetree use CONFIG_IS_ENABLED(OF_LIVE). This means that +for SPL, the CONFIG_SPL_OF_LIVE option is checked. At present this does +not exist, since SPL does not support livetree. + + +Porting drivers +--------------- + +Many existing drivers use the fdtdec interface to read device tree +properties. This only works with a flat device tree. The drivers should be +converted to use the dev_read_() interface. + +For example, the old code may be like this: + +.. code-block:: c + + struct udevice *bus; + const void *blob = gd->fdt_blob; + int node = dev_of_offset(bus); + + i2c_bus->regs = (struct i2c_ctlr *)devfdt_get_addr(dev); + plat->frequency = fdtdec_get_int(blob, node, "spi-max-frequency", 500000); + +The new code is: + +.. code-block:: c + + struct udevice *bus; + + i2c_bus->regs = (struct i2c_ctlr *)dev_read_addr(dev); + plat->frequency = dev_read_u32_default(bus, "spi-max-frequency", 500000); + +The dev_read\_...() interface is more convenient and works with both the +flat and live device trees. See include/dm/read.h for a list of functions. + +Where properties must be read from sub-nodes or other nodes, you must fall +back to using ofnode. For example, for old code like this: + +.. code-block:: c + + const void *blob = gd->fdt_blob; + int subnode; + + fdt_for_each_subnode(subnode, blob, dev_of_offset(dev)) { + freq = fdtdec_get_int(blob, node, "spi-max-frequency", 500000); + ... + } + +you should use: + +.. code-block:: c + + ofnode subnode; + + ofnode_for_each_subnode(subnode, dev_ofnode(dev)) { + freq = ofnode_read_u32(node, "spi-max-frequency", 500000); + ... + } + + +Useful ofnode functions +----------------------- + +The internal data structures of the livetree are defined in include/dm/of.h : + + :struct device_node: holds information about a device tree node + :struct property: holds information about a property within a node + +Nodes have pointers to their first property, their parent, their first child +and their sibling. This allows nodes to be linked together in a hierarchical +tree. + +Properties have pointers to the next property. This allows all properties of +a node to be linked together in a chain. + +It should not be necessary to use these data structures in normal code. In +particular, you should refrain from using functions which access the livetree +directly, such as of_read_u32(). Use ofnode functions instead, to allow your +code to work with a flat tree also. + +Some conversion functions are used internally. Generally these are not needed +for driver code. Note that they will not work if called in the wrong context. +For example it is invalid to call ofnode_to_no() when a flat tree is being +used. Similarly it is not possible to call ofnode_to_offset() on a livetree +node. + +ofnode_to_np(): + converts ofnode to struct device_node * +ofnode_to_offset(): + converts ofnode to offset + +no_to_ofnode(): + converts node pointer to ofnode +offset_to_ofnode(): + converts offset to ofnode + + +Other useful functions: + +of_live_active(): + returns true if livetree is in use, false if flat tree +ofnode_valid(): + return true if a given node is valid +ofnode_is_np(): + returns true if a given node is a livetree node +ofnode_equal(): + compares two ofnodes +ofnode_null(): + returns a null ofnode (for which ofnode_valid() returns false) + + +Phandles +-------- + +There is full phandle support for live tree. All functions make use of +struct ofnode_phandle_args, which has an ofnode within it. This supports both +livetree and flat tree transparently. See for example +ofnode_parse_phandle_with_args(). + + +Reading addresses +----------------- + +You should use dev_read_addr() and friends to read addresses from device-tree +nodes. + + +fdtdec +------ + +The existing fdtdec interface will eventually be retired. Please try to avoid +using it in new code. + + +Modifying the livetree +---------------------- + +This is not currently supported. Once implemented it should provide a much +more efficient implementation for modification of the device tree than using +the flat tree. + + +Internal implementation +----------------------- + +The dev_read\_...() functions have two implementations. When +CONFIG_DM_DEV_READ_INLINE is enabled, these functions simply call the ofnode +functions directly. This is useful when livetree is not enabled. The ofnode +functions call ofnode_is_np(node) which will always return false if livetree +is disabled, just falling back to flat tree code. + +This optimisation means that without livetree enabled, the dev_read\_...() and +ofnode interfaces do not noticeably add to code size. + +The CONFIG_DM_DEV_READ_INLINE option defaults to enabled when livetree is +disabled. + +Most livetree code comes directly from Linux and is modified as little as +possible. This is deliberate since this code is fairly stable and does what +we want. Some features (such as get/put) are not supported. Internal macros +take care of removing these features silently. + +Within the of_access.c file there are pointers to the alias node, the chosen +node and the stdout-path alias. + + +Errors +------ + +With a flat device tree, libfdt errors are returned (e.g. -FDT_ERR_NOTFOUND). +For livetree normal 'errno' errors are returned (e.g. -ENOTFOUND). At present +the ofnode and dev_read\_...() functions return either one or other type of +error. This is clearly not desirable. Once tests are added for all the +functions this can be tidied up. + + +Adding new access functions +--------------------------- + +Adding a new function for device-tree access involves the following steps: + + - Add two dev_read() functions: + - inline version in the read.h header file, which calls an ofnode function + - standard version in the read.c file (or perhaps another file), which + also calls an ofnode function + + The implementations of these functions can be the same. The purpose + of the inline version is purely to reduce code size impact. + + - Add an ofnode function. This should call ofnode_is_np() to work out + whether a livetree or flat tree is used. For the livetree it should + call an of\_...() function. For the flat tree it should call an + fdt\_...() function. The livetree version will be optimised out at + compile time if livetree is not enabled. + + - Add an of\_...() function for the livetree implementation. If a similar + function is available in Linux, the implementation should be taken + from there and modified as little as possible (generally not at all). + + +Future work +----------- + +Live tree support was introduced in U-Boot 2017.07. There is still quite a bit +of work to do to flesh this out: + +- tests for all access functions +- support for livetree modification +- addition of more access functions as needed +- support for livetree in SPL and before relocation (if desired) diff --git a/roms/u-boot/doc/develop/driver-model/migration.rst b/roms/u-boot/doc/develop/driver-model/migration.rst new file mode 100644 index 000000000..8d0bb7635 --- /dev/null +++ b/roms/u-boot/doc/develop/driver-model/migration.rst @@ -0,0 +1,109 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +Migration Schedule +================== + +U-Boot has been migrating to a new driver model since its introduction in +2014. This file describes the schedule for deprecation of pre-driver-model +features. + +CONFIG_DM +--------- + +* Status: In progress +* Deadline: 2020.01 + +Starting with the 2010.01 release CONFIG_DM will be enabled for all boards. +This does not concern CONFIG_DM_SPL and CONFIG_DM_TPL. The conversion date for +these configuration items still needs to be defined. + +CONFIG_DM_MMC +------------- + +* Status: In progress +* Deadline: 2019.04 + +The subsystem itself has been converted and maintainers should submit patches +switching over to using CONFIG_DM_MMC and other base driver model options in +time for inclusion in the 2019.04 rerelease. + +CONFIG_DM_USB +------------- + +* Status: In progress +* Deadline: 2019.07 + +The subsystem itself has been converted along with many of the host controller +and maintainers should submit patches switching over to using CONFIG_DM_USB and +other base driver model options in time for inclusion in the 2019.07 rerelease. + +CONFIG_SATA +----------- + +* Status: In progress +* Deadline: 2019.07 + +The subsystem itself has been converted along with many of the host controller +and maintainers should submit patches switching over to using CONFIG_AHCI and +other base driver model options in time for inclusion in the 2019.07 rerelease. + +CONFIG_BLK +---------- + +* Status: In progress +* Deadline: 2019.07 + +In concert with maintainers migrating their block device usage to the +appropriate DM driver, CONFIG_BLK needs to be set as well. The final deadline +here coincides with the final deadline for migration of the various block +subsystems. At this point we will be able to audit and correct the logic in +Kconfig around using CONFIG_PARTITIONS and CONFIG_HAVE_BLOCK_DEVICE and make +use of CONFIG_BLK / CONFIG_SPL_BLK as needed. + +CONFIG_DM_SPI / CONFIG_DM_SPI_FLASH +----------------------------------- + +Board Maintainers should submit the patches for enabling DM_SPI and DM_SPI_FLASH +to move the migration with in the deadline. + +Partially converted:: + + drivers/spi/fsl_espi.c + drivers/spi/mxc_spi.c + drivers/spi/sh_qspi.c + +* Status: In progress +* Deadline: 2019.07 + +CONFIG_DM_PCI +------------- +Deadline: 2019.07 + +The PCI subsystem has supported driver model since mid 2015. Maintainers should +submit patches switching over to using CONFIG_DM_PCI and other base driver +model options in time for inclusion in the 2019.07 release. + + +CONFIG_DM_VIDEO +--------------- +Deadline: 2019.07 + +The video subsystem has supported driver model since early 2016. Maintainers +should submit patches switching over to using CONFIG_DM_VIDEO and other base +driver model options in time for inclusion in the 2019.07 release. + +CONFIG_DM_ETH +------------- +Deadline: 2020.07 + +The network subsystem has supported the driver model since early 2015. +Maintainers should submit patches switching over to using CONFIG_DM_ETH and +other base driver model options in time for inclusion in the 2020.07 release. + +CONFIG_DM_I2C +------------- +Deadline: 2021.10 + +The I2C subsystem has supported the driver model since early 2015. +Maintainers should submit patches switching over to using CONFIG_DM_I2C and +other base driver model options in time for inclusion in the 2021.10 release. diff --git a/roms/u-boot/doc/develop/driver-model/nvme.rst b/roms/u-boot/doc/develop/driver-model/nvme.rst new file mode 100644 index 000000000..736c0a063 --- /dev/null +++ b/roms/u-boot/doc/develop/driver-model/nvme.rst @@ -0,0 +1,97 @@ +.. SPDX-License-Identifier: GPL-2.0+ +.. Copyright (C) 2017 NXP Semiconductors +.. Copyright (C) 2017 Bin Meng <bmeng.cn@gmail.com> + +NVMe Support +============ + +What is NVMe +------------ + +NVM Express (NVMe) is a register level interface that allows host software to +communicate with a non-volatile memory subsystem. This interface is optimized +for enterprise and client solid state drives, typically attached to the PCI +express interface. It is a scalable host controller interface designed to +address the needs of enterprise and client systems that utilize PCI express +based solid state drives (SSD). The interface provides optimized command +submission and completion paths. It includes support for parallel operation by +supporting up to 64K I/O queues with up to 64K commands per I/O queue. + +The device is comprised of some number of controllers, where each controller +is comprised of some number of namespaces, where each namespace is comprised +of some number of logical blocks. A namespace is a quantity of non-volatile +memory that is formatted into logical blocks. An NVMe namespace is equivalent +to a SCSI LUN. Each namespace is operated as an independent "device". + +How it works +------------ +There is an NVMe uclass driver (driver name "nvme"), an NVMe host controller +driver (driver name "nvme") and an NVMe namespace block driver (driver name +"nvme-blk"). The host controller driver is supposed to probe the hardware and +do necessary initialization to put the controller into a ready state at which +it is able to scan all available namespaces attached to it. Scanning namespace +is triggered by the NVMe uclass driver and the actual work is done in the NVMe +namespace block driver. + +Status +------ +It only support basic block read/write functions in the NVMe driver. + +Config options +-------------- +CONFIG_NVME Enable NVMe device support +CONFIG_CMD_NVME Enable basic NVMe commands + +Usage in U-Boot +--------------- +To use an NVMe hard disk from U-Boot shell, a 'nvme scan' command needs to +be executed for all NVMe hard disks attached to the NVMe controller to be +identified. + +To list all of the NVMe hard disks, try: + +.. code-block:: none + + => nvme info + Device 0: Vendor: 0x8086 Rev: 8DV10131 Prod: CVFT535600LS400BGN + Type: Hard Disk + Capacity: 381554.0 MB = 372.6 GB (781422768 x 512) + +and print out detailed information for controller and namespaces via: + +.. code-block:: none + + => nvme detail + +Raw block read/write to can be done via the 'nvme read/write' commands: + +.. code-block:: none + + => nvme read a0000000 0 11000 + + => tftp 80000000 /tftpboot/kernel.itb + => nvme write 80000000 0 11000 + +Of course, file system command can be used on the NVMe hard disk as well: + +.. code-block:: none + + => fatls nvme 0:1 + 32376967 kernel.itb + 22929408 100m + + 2 file(s), 0 dir(s) + + => fatload nvme 0:1 a0000000 /kernel.itb + => bootm a0000000 + +Testing NVMe with QEMU x86 +-------------------------- +QEMU supports NVMe emulation and we can test NVMe driver with QEMU x86 running +U-Boot. Please see README.x86 for how to build u-boot.rom image for QEMU x86. + +Example command line to call QEMU x86 below with emulated NVMe device: + +.. code-block:: bash + + $ ./qemu-system-i386 -drive file=nvme.img,if=none,id=drv0 -device nvme,drive=drv0,serial=QEMUNVME0001 -bios u-boot.rom diff --git a/roms/u-boot/doc/develop/driver-model/of-plat.rst b/roms/u-boot/doc/develop/driver-model/of-plat.rst new file mode 100644 index 000000000..74f193247 --- /dev/null +++ b/roms/u-boot/doc/develop/driver-model/of-plat.rst @@ -0,0 +1,913 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +Compiled-in Device Tree / Platform Data +======================================= + + +Introduction +------------ + +Device tree is the standard configuration method in U-Boot. It is used to +define what devices are in the system and provide configuration information +to these devices. + +The overhead of adding devicetree access to U-Boot is fairly modest, +approximately 3KB on Thumb 2 (plus the size of the DT itself). This means +that in most cases it is best to use devicetree for configuration. + +However there are some very constrained environments where U-Boot needs to +work. These include SPL with severe memory limitations. For example, some +SoCs require a 16KB SPL image which must include a full MMC stack. In this +case the overhead of devicetree access may be too great. + +It is possible to create platform data manually by defining C structures +for it, and reference that data in a `U_BOOT_DRVINFO()` declaration. This +bypasses the use of devicetree completely, effectively creating a parallel +configuration mechanism. But it is an available option for SPL. + +As an alternative, the 'of-platdata' feature is provided. This converts the +devicetree contents into C code which can be compiled into the SPL binary. +This saves the 3KB of code overhead and perhaps a few hundred more bytes due +to more efficient storage of the data. + + +How it works +------------ + +The feature is enabled by CONFIG OF_PLATDATA. This is only available in +SPL/TPL and should be tested with: + +.. code-block:: c + + #if CONFIG_IS_ENABLED(OF_PLATDATA) + +A tool called 'dtoc' converts a devicetree file either into a set of +struct declarations, one for each compatible node, and a set of +`U_BOOT_DRVINFO()` declarations along with the actual platform data for each +device. As an example, consider this MMC node: + +.. code-block:: none + + sdmmc: dwmmc@ff0c0000 { + compatible = "rockchip,rk3288-dw-mshc"; + clock-freq-min-max = <400000 150000000>; + clocks = <&cru HCLK_SDMMC>, <&cru SCLK_SDMMC>, + <&cru SCLK_SDMMC_DRV>, <&cru SCLK_SDMMC_SAMPLE>; + clock-names = "biu", "ciu", "ciu_drv", "ciu_sample"; + fifo-depth = <0x100>; + interrupts = <GIC_SPI 32 IRQ_TYPE_LEVEL_HIGH>; + reg = <0xff0c0000 0x4000>; + bus-width = <4>; + cap-mmc-highspeed; + cap-sd-highspeed; + card-detect-delay = <200>; + disable-wp; + num-slots = <1>; + pinctrl-names = "default"; + pinctrl-0 = <&sdmmc_clk>, <&sdmmc_cmd>, <&sdmmc_cd>, <&sdmmc_bus4>; + vmmc-supply = <&vcc_sd>; + status = "okay"; + u-boot,dm-pre-reloc; + }; + + +Some of these properties are dropped by U-Boot under control of the +CONFIG_OF_SPL_REMOVE_PROPS option. The rest are processed. This will produce +the following C struct declaration: + +.. code-block:: c + + struct dtd_rockchip_rk3288_dw_mshc { + fdt32_t bus_width; + bool cap_mmc_highspeed; + bool cap_sd_highspeed; + fdt32_t card_detect_delay; + fdt32_t clock_freq_min_max[2]; + struct phandle_1_arg clocks[4]; + bool disable_wp; + fdt32_t fifo_depth; + fdt32_t interrupts[3]; + fdt32_t num_slots; + fdt32_t reg[2]; + fdt32_t vmmc_supply; + }; + +and the following device declarations: + +.. code-block:: c + + /* Node /clock-controller@ff760000 index 0 */ + ... + + /* Node /dwmmc@ff0c0000 index 2 */ + static struct dtd_rockchip_rk3288_dw_mshc dtv_dwmmc_at_ff0c0000 = { + .fifo_depth = 0x100, + .cap_sd_highspeed = true, + .interrupts = {0x0, 0x20, 0x4}, + .clock_freq_min_max = {0x61a80, 0x8f0d180}, + .vmmc_supply = 0xb, + .num_slots = 0x1, + .clocks = {{0, 456}, + {0, 68}, + {0, 114}, + {0, 118}}, + .cap_mmc_highspeed = true, + .disable_wp = true, + .bus_width = 0x4, + .u_boot_dm_pre_reloc = true, + .reg = {0xff0c0000, 0x4000}, + .card_detect_delay = 0xc8, + }; + + U_BOOT_DRVINFO(dwmmc_at_ff0c0000) = { + .name = "rockchip_rk3288_dw_mshc", + .plat = &dtv_dwmmc_at_ff0c0000, + .plat_size = sizeof(dtv_dwmmc_at_ff0c0000), + .parent_idx = -1, + }; + +The device is then instantiated at run-time and the platform data can be +accessed using: + +.. code-block:: c + + struct udevice *dev; + struct dtd_rockchip_rk3288_dw_mshc *plat = dev_get_plat(dev); + +This avoids the code overhead of converting the devicetree data to +platform data in the driver. The `of_to_plat()` method should +therefore do nothing in such a driver. + +Note that for the platform data to be matched with a driver, the 'name' +property of the `U_BOOT_DRVINFO()` declaration has to match a driver declared +via `U_BOOT_DRIVER()`. This effectively means that a `U_BOOT_DRIVER()` with a +'name' corresponding to the devicetree 'compatible' string (after converting +it to a valid name for C) is needed, so a dedicated driver is required for +each 'compatible' string. + +In order to make this a bit more flexible, the `DM_DRIVER_ALIAS()` macro can be +used to declare an alias for a driver name, typically a 'compatible' string. +This macro produces no code, but is used by dtoc tool. It must be located in the +same file as its associated driver, ideally just after it. + +The parent_idx is the index of the parent `driver_info` structure within its +linker list (instantiated by the `U_BOOT_DRVINFO()` macro). This is used to +support `dev_get_parent()`. + +During the build process dtoc parses both `U_BOOT_DRIVER()` and +`DM_DRIVER_ALIAS()` to build a list of valid driver names and driver aliases. +If the 'compatible' string used for a device does not not match a valid driver +name, it will be checked against the list of driver aliases in order to get the +right driver name to use. If in this step there is no match found a warning is +issued to avoid run-time failures. + +Where a node has multiple compatible strings, dtoc generates a `#define` to +make them equivalent, e.g.: + +.. code-block:: c + + #define dtd_rockchip_rk3299_dw_mshc dtd_rockchip_rk3288_dw_mshc + + +Converting of-platdata to a useful form +--------------------------------------- + +Of course it would be possible to use the of-platdata directly in your driver +whenever configuration information is required. However this means that the +driver will not be able to support devicetree, since the of-platdata +structure is not available when devicetree is used. It would make no sense +to use this structure if devicetree were available, since the structure has +all the limitations metioned in caveats below. + +Therefore it is recommended that the of-platdata structure should be used +only in the `probe()` method of your driver. It cannot be used in the +`of_to_plat()` method since this is not called when platform data is +already present. + + +How to structure your driver +---------------------------- + +Drivers should always support devicetree as an option. The of-platdata +feature is intended as a add-on to existing drivers. + +Your driver should convert the plat struct in its `probe()` method. The +existing devicetree decoding logic should be kept in the +`of_to_plat()` method and wrapped with `#if`. + +For example: + +.. code-block:: c + + #include <dt-structs.h> + + struct mmc_plat { + #if CONFIG_IS_ENABLED(OF_PLATDATA) + /* Put this first since driver model will copy the data here */ + struct dtd_mmc dtplat; + #endif + /* + * Other fields can go here, to be filled in by decoding from + * the devicetree (or the C structures when of-platdata is used). + */ + int fifo_depth; + }; + + static int mmc_of_to_plat(struct udevice *dev) + { + #if !CONFIG_IS_ENABLED(OF_PLATDATA) + /* Decode the devicetree data */ + struct mmc_plat *plat = dev_get_plat(dev); + const void *blob = gd->fdt_blob; + int node = dev_of_offset(dev); + + plat->fifo_depth = fdtdec_get_int(blob, node, "fifo-depth", 0); + #endif + + return 0; + } + + static int mmc_probe(struct udevice *dev) + { + struct mmc_plat *plat = dev_get_plat(dev); + + #if CONFIG_IS_ENABLED(OF_PLATDATA) + /* Decode the of-platdata from the C structures */ + struct dtd_mmc *dtplat = &plat->dtplat; + + plat->fifo_depth = dtplat->fifo_depth; + #endif + /* Set up the device from the plat data */ + writel(plat->fifo_depth, ...) + } + + static const struct udevice_id mmc_ids[] = { + { .compatible = "vendor,mmc" }, + { } + }; + + U_BOOT_DRIVER(mmc_drv) = { + .name = "mmc_drv", + .id = UCLASS_MMC, + .of_match = mmc_ids, + .of_to_plat = mmc_of_to_plat, + .probe = mmc_probe, + .priv_auto = sizeof(struct mmc_priv), + .plat_auto = sizeof(struct mmc_plat), + }; + + DM_DRIVER_ALIAS(mmc_drv, vendor_mmc) /* matches compatible string */ + +Note that `struct mmc_plat` is defined in the C file, not in a header. This +is to avoid needing to include dt-structs.h in a header file. The idea is to +keep the use of each of-platdata struct to the smallest possible code area. +There is just one driver C file for each struct, that can convert from the +of-platdata struct to the standard one used by the driver. + +In the case where SPL_OF_PLATDATA is enabled, `plat_auto` is +still used to allocate space for the platform data. This is different from +the normal behaviour and is triggered by the use of of-platdata (strictly +speaking it is a non-zero `plat_size` which triggers this). + +The of-platdata struct contents is copied from the C structure data to the +start of the newly allocated area. In the case where devicetree is used, +the platform data is allocated, and starts zeroed. In this case the +`of_to_plat()` method should still set up the platform data (and the +of-platdata struct will not be present). + +SPL must use either of-platdata or devicetree. Drivers cannot use both at +the same time, but they must support devicetree. Supporting of-platdata is +optional. + +The devicetree becomes inaccessible when CONFIG_SPL_OF_PLATDATA is enabled, +since the devicetree access code is not compiled in. A corollary is that +a board can only move to using of-platdata if all the drivers it uses support +it. There would be little point in having some drivers require the device +tree data, since then libfdt would still be needed for those drivers and +there would be no code-size benefit. + + +Build-time instantiation +------------------------ + +Even with of-platdata there is a fair amount of code required in driver model. +It is possible to have U-Boot handle the instantiation of devices at build-time, +so avoiding the need for the `device_bind()` code and some parts of +`device_probe()`. + +The feature is enabled by CONFIG_OF_PLATDATA_INST. + +Here is an example device, as generated by dtoc:: + + /* + * Node /serial index 6 + * driver sandbox_serial parent root_driver + */ + + #include <asm/serial.h> + struct sandbox_serial_plat __attribute__ ((section (".priv_data"))) + _sandbox_serial_plat_serial = { + .dtplat = { + .sandbox_text_colour = "cyan", + }, + }; + #include <asm/serial.h> + u8 _sandbox_serial_priv_serial[sizeof(struct sandbox_serial_priv)] + __attribute__ ((section (".priv_data"))); + #include <serial.h> + u8 _sandbox_serial_uc_priv_serial[sizeof(struct serial_dev_priv)] + __attribute__ ((section (".priv_data"))); + + DM_DEVICE_INST(serial) = { + .driver = DM_DRIVER_REF(sandbox_serial), + .name = "sandbox_serial", + .plat_ = &_sandbox_serial_plat_serial, + .priv_ = _sandbox_serial_priv_serial, + .uclass = DM_UCLASS_REF(serial), + .uclass_priv_ = _sandbox_serial_uc_priv_serial, + .uclass_node = { + .prev = &DM_UCLASS_REF(serial)->dev_head, + .next = &DM_UCLASS_REF(serial)->dev_head, + }, + .child_head = { + .prev = &DM_DEVICE_REF(serial)->child_head, + .next = &DM_DEVICE_REF(serial)->child_head, + }, + .sibling_node = { + .prev = &DM_DEVICE_REF(i2c_at_0)->sibling_node, + .next = &DM_DEVICE_REF(spl_test)->sibling_node, + }, + .seq_ = 0, + }; + +Here is part of the driver, for reference:: + + static const struct udevice_id sandbox_serial_ids[] = { + { .compatible = "sandbox,serial" }, + { } + }; + + U_BOOT_DRIVER(sandbox_serial) = { + .name = "sandbox_serial", + .id = UCLASS_SERIAL, + .of_match = sandbox_serial_ids, + .of_to_plat = sandbox_serial_of_to_plat, + .plat_auto = sizeof(struct sandbox_serial_plat), + .priv_auto = sizeof(struct sandbox_serial_priv), + .probe = sandbox_serial_probe, + .remove = sandbox_serial_remove, + .ops = &sandbox_serial_ops, + .flags = DM_FLAG_PRE_RELOC, + }; + + +The `DM_DEVICE_INST()` macro declares a struct udevice so you can see that the +members are from that struct. The private data is declared immediately above, +as `_sandbox_serial_priv_serial`, so there is no need for run-time memory +allocation. The #include lines are generated as well, since dtoc searches the +U-Boot source code for the definition of `struct sandbox_serial_priv` and adds +the relevant header so that the code will compile without errors. + +The `plat_` member is set to the dtv data which is declared immediately above +the device. This is similar to how it would look without of-platdata-inst, but +node that the `dtplat` member inside is part of the wider +`_sandbox_serial_plat_serial` struct. This is because the driver declares its +own platform data, and the part generated by dtoc can only be a portion of it. +The `dtplat` part is always first in the struct. If the device has no +`.plat_auto` field, then a simple dtv struct can be used as with this example:: + + static struct dtd_sandbox_clk dtv_clk_sbox = { + .assigned_clock_rates = 0x141, + .assigned_clocks = {0x7, 0x3}, + }; + + #include <asm/clk.h> + u8 _sandbox_clk_priv_clk_sbox[sizeof(struct sandbox_clk_priv)] + __attribute__ ((section (".priv_data"))); + + DM_DEVICE_INST(clk_sbox) = { + .driver = DM_DRIVER_REF(sandbox_clk), + .name = "sandbox_clk", + .plat_ = &dtv_clk_sbox, + +Here is part of the driver, for reference:: + + static const struct udevice_id sandbox_clk_ids[] = { + { .compatible = "sandbox,clk" }, + { } + }; + + U_BOOT_DRIVER(sandbox_clk) = { + .name = "sandbox_clk", + .id = UCLASS_CLK, + .of_match = sandbox_clk_ids, + .ops = &sandbox_clk_ops, + .probe = sandbox_clk_probe, + .priv_auto = sizeof(struct sandbox_clk_priv), + }; + + +You can see that `dtv_clk_sbox` just has the devicetree contents and there is +no need for the `dtplat` separation, since the driver has no platform data of +its own, besides that provided by the devicetree (i.e. no `.plat_auto` field). + +The doubly linked lists are handled by explicitly declaring the value of each +node, as you can see with the `.prev` and `.next` values in the example above. +Since dtoc knows the order of devices it can link them into the appropriate +lists correctly. + +One of the features of driver model is the ability for a uclass to have a +small amount of private data for each device in that uclass. This is used to +provide a generic data structure that the uclass can use for all devices, thus +allowing generic features to be implemented in common code. An example is I2C, +which stores the bus speed there. + +Similarly, parent devices can have data associated with each of their children. +This is used to provide information common to all children of a particular bus. +For an I2C bus, this is used to store the I2C address of each child on the bus. + +This is all handled automatically by dtoc:: + + #include <asm/i2c.h> + u8 _sandbox_i2c_priv_i2c_at_0[sizeof(struct sandbox_i2c_priv)] + __attribute__ ((section (".priv_data"))); + #include <i2c.h> + u8 _sandbox_i2c_uc_priv_i2c_at_0[sizeof(struct dm_i2c_bus)] + __attribute__ ((section (".priv_data"))); + + DM_DEVICE_INST(i2c_at_0) = { + .driver = DM_DRIVER_REF(sandbox_i2c), + .name = "sandbox_i2c", + .plat_ = &dtv_i2c_at_0, + .priv_ = _sandbox_i2c_priv_i2c_at_0, + .uclass = DM_UCLASS_REF(i2c), + .uclass_priv_ = _sandbox_i2c_uc_priv_i2c_at_0, + ... + +Part of driver, for reference:: + + static const struct udevice_id sandbox_i2c_ids[] = { + { .compatible = "sandbox,i2c" }, + { } + }; + + U_BOOT_DRIVER(sandbox_i2c) = { + .name = "sandbox_i2c", + .id = UCLASS_I2C, + .of_match = sandbox_i2c_ids, + .ops = &sandbox_i2c_ops, + .priv_auto = sizeof(struct sandbox_i2c_priv), + }; + +Part of I2C uclass, for reference:: + + UCLASS_DRIVER(i2c) = { + .id = UCLASS_I2C, + .name = "i2c", + .flags = DM_UC_FLAG_SEQ_ALIAS, + .post_bind = i2c_post_bind, + .pre_probe = i2c_pre_probe, + .post_probe = i2c_post_probe, + .per_device_auto = sizeof(struct dm_i2c_bus), + .per_child_plat_auto = sizeof(struct dm_i2c_chip), + .child_post_bind = i2c_child_post_bind, + }; + +Here, `_sandbox_i2c_uc_priv_i2c_at_0` is required by the uclass but is declared +in the device, as required by driver model. The required header file is included +so that the code will compile without errors. A similar mechanism is used for +child devices, but is not shown by this example. + +It would not be that useful to avoid binding devices but still need to allocate +uclasses at runtime. So dtoc generates uclass instances as well:: + + struct list_head uclass_head = { + .prev = &DM_UCLASS_REF(serial)->sibling_node, + .next = &DM_UCLASS_REF(clk)->sibling_node, + }; + + DM_UCLASS_INST(clk) = { + .uc_drv = DM_UCLASS_DRIVER_REF(clk), + .sibling_node = { + .prev = &uclass_head, + .next = &DM_UCLASS_REF(i2c)->sibling_node, + }, + .dev_head = { + .prev = &DM_DEVICE_REF(clk_sbox)->uclass_node, + .next = &DM_DEVICE_REF(clk_fixed)->uclass_node, + }, + }; + +At the top is the list head. Driver model uses this on start-up, instead of +creating its own. + +Below that are a set of `DM_UCLASS_INST()` macros, each declaring a +`struct uclass`. The doubly linked lists work as for devices. + +All private data is placed into a `.priv_data` section so that it is contiguous +in the resulting output binary. + + +Indexes +------- + +U-Boot stores drivers, devices and many other things in linker_list structures. +These are sorted by name, so dtoc knows the order that they will appear when +the linker runs. Each driver_info / udevice is referenced by its index in the +linker_list array, called 'idx' in the code. + +When CONFIG_OF_PLATDATA_INST is enabled, idx is the udevice index, otherwise it +is the driver_info index. In either case, indexes are used to reference devices +using device_get_by_ofplat_idx(). This allows phandles to work as expected. + + +Phases +------ + +U-Boot operates in several phases, typically TPL, SPL and U-Boot proper. +The latter does not use dtoc. + +In some rare cases different drivers are used for two phases. For example, +in TPL it may not be necessary to use the full PCI subsystem, so a simple +driver can be used instead. + +This works in the build system simply by compiling in one driver or the +other (e.g. PCI driver + uclass for SPL; simple_bus for TPL). But dtoc has +no way of knowing which code is compiled in for which phase, since it does +not inspect Makefiles or dependency graphs. + +So to make this work for dtoc, we need to be able to explicitly mark +drivers with their phase. This is done by adding a macro to the driver:: + + /* code in tpl.c only compiled into TPL */ + U_BOOT_DRIVER(pci_x86) = { + .name = "pci_x86", + .id = UCLASS_SIMPLE_BUS, + .of_match = of_match_ptr(tpl_fake_pci_ids), + DM_PHASE(tpl) + }; + + + /* code in pci_x86.c compiled into SPL and U-Boot proper */ + U_BOOT_DRIVER(pci_x86) = { + .name = "pci_x86", + .id = UCLASS_PCI, + .of_match = pci_x86_ids, + .ops = &pci_x86_ops, + }; + + +Notice that the second driver has the same name but no DM_PHASE(), so it will be +used for SPL and U-Boot. + +Note also that this only affects the code generated by dtoc. You still need to +make sure that only the required driver is build into each phase. + + +Header files +------------ + +With OF_PLATDATA_INST, dtoc must include the correct header file in the +generated code for any structs that are used, so that the code will compile. +For example, if `struct ns16550_plat` is used, the code must include the +`ns16550.h` header file. + +Typically dtoc can detect the header file needed for a driver by looking +for the structs that it uses. For example, if a driver as a `.priv_auto` +that uses `struct ns16550_plat`, then dtoc can search header files for the +definition of that struct and use the file. + +In some cases, enums are used in drivers, typically with the `.data` field +of `struct udevice_id`. Since dtoc does not support searching for these, +you must use the `DM_HDR()` macro to tell dtoc which header to use. This works +as a macro included in the driver definition:: + + static const struct udevice_id apl_syscon_ids[] = { + { .compatible = "intel,apl-punit", .data = X86_SYSCON_PUNIT }, + { } + }; + + U_BOOT_DRIVER(intel_apl_punit) = { + .name = "intel_apl_punit", + .id = UCLASS_SYSCON, + .of_match = apl_syscon_ids, + .probe = apl_punit_probe, + DM_HEADER(<asm/cpu.h>) /* for X86_SYSCON_PUNIT */ + }; + + + +Caveats +------- + +There are various complications with this feature which mean it should only +be used when strictly necessary, i.e. in SPL with limited memory. Notable +caveats include: + + - Device tree does not describe data types. But the C code must define a + type for each property. These are guessed using heuristics which + are wrong in several fairly common cases. For example an 8-byte value + is considered to be a 2-item integer array, and is byte-swapped. A + boolean value that is not present means 'false', but cannot be + included in the structures since there is generally no mention of it + in the devicetree file. + + - Naming of nodes and properties is automatic. This means that they follow + the naming in the devicetree, which may result in C identifiers that + look a bit strange. + + - It is not possible to find a value given a property name. Code must use + the associated C member variable directly in the code. This makes + the code less robust in the face of devicetree changes. To avoid having + a second struct with similar members and names you need to explicitly + declare it as an alias with `DM_DRIVER_ALIAS()`. + + - The platform data is provided to drivers as a C structure. The driver + must use the same structure to access the data. Since a driver + normally also supports devicetree it must use `#ifdef` to separate + out this code, since the structures are only available in SPL. This could + be fixed fairly easily by making the structs available outside SPL, so + that `IS_ENABLED()` could be used. + + - With CONFIG_OF_PLATDATA_INST all binding happens at build-time, meaning + that (by default) it is not possible to call `device_bind()` from C code. + This means that all devices must have an associated devicetree node and + compatible string. For example if a GPIO device currently creates child + devices in its `bind()` method, it will not work with + CONFIG_OF_PLATDATA_INST. Arguably this is bad practice anyway and the + devicetree binding should be updated to declare compatible strings for + the child devices. It is possible to disable OF_PLATDATA_NO_BIND but this + is not recommended since it increases code size. + + +Internals +--------- + +Generated files +``````````````` + +When enabled, dtoc generates the following five files: + +include/generated/dt-decl.h (OF_PLATDATA_INST only) + Contains declarations for all drivers, devices and uclasses. This allows + any `struct udevice`, `struct driver` or `struct uclass` to be located by its + name + +include/generated/dt-structs-gen.h + Contains the struct definitions for the devicetree nodes that are used. This + is the same as without OF_PLATDATA_INST + +spl/dts/dt-plat.c (only with !OF_PLATDATA_INST) + Contains the `U_BOOT_DRVINFO()` declarations that U-Boot uses to bind devices + at start-up. See above for an example + +spl/dts/dt-device.c (only with OF_PLATDATA_INST) + Contains `DM_DEVICE_INST()` declarations for each device that can be used at + run-time. These are declared in the file along with any private/platform data + that they use. Every device has an idx, as above. Since each device must be + part of a double-linked list, the nodes are declared in the code as well. + +spl/dts/dt-uclass.c (only with OF_PLATDATA_INST) + Contains `DM_UCLASS_INST()` declarations for each uclass that can be used at + run-time. These are declared in the file along with any private data + associated with the uclass itself (the `.priv_auto` member). Since each + uclass must be part of a double-linked list, the nodes are declared in the + code as well. + +The dt-structs.h file includes the generated file +`(include/generated/dt-structs.h`) if CONFIG_SPL_OF_PLATDATA is enabled. +Otherwise (such as in U-Boot proper) these structs are not available. This +prevents them being used inadvertently. All usage must be bracketed with +`#if CONFIG_IS_ENABLED(OF_PLATDATA)`. + +The dt-plat.c file contains the device declarations and is is built in +spl/dt-plat.c. + + +CONFIG options +`````````````` + +Several CONFIG options are used to control the behaviour of of-platdata, all +available for both SPL and TPL: + +OF_PLATDATA + This is the main option which enables the of-platdata feature + +OF_PLATDATA_PARENT + This allows `device_get_parent()` to work. Without this, all devices exist as + direct children of the root node. This option is highly desirable (if not + always absolutely essential) for buses such as I2C. + +OF_PLATDATA_INST + This controls the instantiation of devices at build time. With it disabled, + only `U_BOOT_DRVINFO()` records are created, with U-Boot handling the binding + in `device_bind()` on start-up. With it enabled, only `DM_DEVICE_INST()` and + `DM_UCLASS_INST()` records are created, and `device_bind()` is not needed at + runtime. + +OF_PLATDATA_NO_BIND + This controls whether `device_bind()` is supported. It is enabled by default + with OF_PLATDATA_INST since code-size reduction is really the main point of + the feature. It can be disabled if needed but is not likely to be supported + in the long term. + +OF_PLATDATA_DRIVER_RT + This controls whether the `struct driver_rt` records are used by U-Boot. + Normally when a device is bound, U-Boot stores the device pointer in one of + these records. There is one for every `struct driver_info` in the system, + i.e. one for every device that is bound from those records. It provides a + way to locate a device in the code and is used by + `device_get_by_ofplat_idx()`. This option is always enabled with of-platdata, + provided OF_PLATDATA_INST is not. In that case the records are useless since + we don't have any `struct driver_info` records. + +OF_PLATDATA_RT + This controls whether the `struct udevice_rt` records are used by U-Boot. + It moves the updatable fields from `struct udevice` (currently only `flags`) + into a separate structure, allowing the records to be kept in read-only + memory. It is generally enabled if OF_PLATDATA_INST is enabled. This option + also controls whether the private data is used in situ, or first copied into + an allocated region. Again this is to allow the private data declared by + dtoc-generated code to be in read-only memory. Note that access to private + data must be done via accessor functions, such as `dev_get_priv()`, so that + the relocation is handled. + +READ_ONLY + This indicates that the data generated by dtoc should not be modified. Only + a few fields actually do get changed in U-Boot, such as device flags. This + option causes those to move into an allocated space (see OF_PLATDATA_RT). + Also, since updating doubly linked lists is generally impossible when some of + the nodes cannot be updated, OF_PLATDATA_NO_BIND is enabled. + +Data structures +``````````````` + +A few extra data structures are used with of-platdata: + +`struct udevice_rt` + Run-time information for devices. When OF_PLATDATA_RT is enabled, this holds + the flags for each device, so that `struct udevice` can remain unchanged by + U-Boot, and potentially reside in read-only memory. Access to flags is then + via functions like `dev_get_flags()` and `dev_or_flags()`. This data + structure is allocated on start-up, where the private data is also copied. + All flags values start at 0 and any changes are handled by `dev_or_flags()` + and `dev_bic_flags()`. It would be more correct for the flags to be set to + `DM_FLAG_BOUND`, or perhaps `DM_FLAG_BOUND | DM_FLAG_ALLOC_PDATA`, but since + there is no code to bind/unbind devices and no code to allocate/free + private data / platform data, it doesn't matter. + +`struct driver_rt` + Run-time information for `struct driver_info` records. When + OF_PLATDATA_DRIVER_RT is enabled, this holds a pointer to the device + created by each record. This is needed so that is it possible to locate a + device from C code. Specifically, the code can use `DM_DRVINFO_GET(name)` to + get a reference to a particular `struct driver_info`, with `name` being the + name of the devicetree node. This is very convenient. It is also fast, since + no searching or string comparison is needed. This data structure is + allocated on start-up, filled out by `device_bind()` and used by + `device_get_by_ofplat_idx()`. + +Other changes +````````````` + +Some other changes are made with of-platdata: + +Accessor functions + Accessing private / platform data via functions such as `dev_get_priv()` has + always been encouraged. With OF_PLATDATA_RT this is essential, since the + `priv_` and `plat_` (etc.) values point to the data generated by dtoc, not + the read-write copy that is sometimes made on start-up. Changing the + private / platform data pointers has always been discouraged (the API is + marked internal) but with OF_PLATDATA_RT this is not currently supported in + general, since it assumes that all such pointers point to the relocated data. + Note also that the renaming of struct members to have a trailing underscore + was partly done to make people aware that they should not be accessed + directly. + +`gd->uclass_root_s` + Normally U-Boot sets up the head of the uclass list here and makes + `gd->uclass_root` point to it. With OF_PLATDATA_INST, dtoc generates a + declaration of `uclass_head` in `dt-uclass.c` since it needs to link the + head node into the list. In that case, `gd->uclass_root_s` is not used and + U-Boot just makes `gd->uclass_root` point to `uclass_head`. + +`gd->dm_driver_rt` + This holds a pointer to a list of `struct driver_rt` records, one for each + `struct driver_info`. The list is in alphabetical order by the name used + in `U_BOOT_DRVINFO(name)` and indexed by idx, with the first record having + an index of 0. It is only used if OF_PLATDATA_INST is not enabled. This is + accessed via macros so that it can be used inside IS_ENABLED(), rather than + requiring #ifdefs in the C code when it is not present. + +`gd->dm_udevice_rt` + This holds a pointer to a list of `struct udevice_rt` records, one for each + `struct udevice`. The list is in alphabetical order by the name used + in `DM_DEVICE_INST(name)` (a C version of the devicetree node) and indexed by + idx, with the first record having an index of 0. It is only used if + OF_PLATDATA_INST is enabled. This is accessed via macros so that it can be + used inside `IS_ENABLED()`, rather than requiring #ifdefs in the C code when + it is not present. + +`gd->dm_priv_base` + When OF_PLATDATA_RT is enabled, the private/platform data for each device is + copied into an allocated region by U-Boot on start-up. This points to that + region. All calls to accessor functions (e.g. `dev_get_priv()`) then + translate from the pointer provided by the caller (assumed to lie between + `__priv_data_start` and `__priv_data_end`) to the new allocated region. This + member is accessed via macros so that it can be used inside IS_ENABLED(), + rather than required #ifdefs in the C code when it is not present. + +`struct udevice->flags_` + When OF_PLATDATA_RT is enabled, device flags are no-longer part of + `struct udevice`, but are instead kept in `struct udevice_rt`, as described + above. Flags are accessed via functions, such as `dev_get_flags()` and + `dev_or_flags()`. + +`struct udevice->node_` + When OF_PLATDATA is enabled, there is no devicetree at runtime, so no need + for this field. It is removed, just to save space. + +`DM_PHASE` + This macro is used to indicate which phase of U-Boot a driver is intended + for. See above for details. + +`DM_HDR` + This macro is used to indicate which header file dtoc should use to allow + a driver declaration to compile correctly. See above for details. + +`device_get_by_ofplat_idx()` + There used to be a function called `device_get_by_driver_info()` which + looked up a `struct driver_info` pointer and returned the `struct udevice` + that was created from it. It was only available for use with of-platdata. + This has been removed in favour of `device_get_by_ofplat_idx()` which uses + `idx`, the index of the `struct driver_info` or `struct udevice` in the + linker_list. Similarly, the `struct phandle_0_arg` (etc.) structs have been + updated to use this index instead of a pointer to `struct driver_info`. + +`DM_DRVINFO_GET` + This has been removed since we now use indexes to obtain a driver from + `struct phandle_0_arg` and the like. + +Two-pass binding + The original of-platdata tried to order `U_BOOT_DRVINFO()` in the generated + files so as to have parents declared ahead of children. This was convenient + as it avoided any special code in U-Boot. With OF_PLATDATA_INST this does + not work as the idx value relies on using alphabetical order for everything, + so that dtoc and U-Boot's linker_lists agree on the idx value. Devices are + then bound in order of idx, having no regard to parent/child relationships. + For this reason, device binding now hapens in multiple passes, with parents + being bound before their children. This is important so that children can + find their parents in the bind() method if needed. + +Root device + The root device is generally bound by U-Boot but with OF_PLATDATA_INST it + cannot be, since binding needs to be done at build time. So in this case + dtoc sets up a root device using `DM_DEVICE_INST()` in `dt-device.c` and + U-Boot makes use of that. When OF_PLATDATA_INST is not enabled, U-Boot + generally ignores the root node and does not create a `U_BOOT_DRVINFO()` + record for it. This means that the idx numbers used by `struct driver_info` + (when OF_PLATDATA_INST is disabled) and the idx numbers used by + `struct udevice` (when OF_PLATDATA_INST is enabled) differ, since one has a + root node and the other does not. This does not actually matter, since only + one of them is actually used for any particular build, but it is worth + keeping in mind if comparing index values and switching OF_PLATDATA_INST on + and off. + +`__priv_data_start` and `__priv_data_end` + The private/platform data declared by dtoc is all collected together in + a linker section and these symbols mark the start and end of it. This allows + U-Boot to relocate the area to a new location if needed (with + OF_PLATDATA_RT) + +`dm_priv_to_rw()` + This function converts a private- or platform-data pointer value generated by + dtoc into one that can be used by U-Boot. It is a NOP unless OF_PLATDATA_RT + is enabled, in which case it translates the address to the relocated + region. See above for more information. + +The dm_populate_phandle_data() function that was previous needed has now been +removed, since dtoc can address the drivers directly from dt-plat.c and does +not need to fix up things at runtime. + +The pylibfdt Python module is used to access the devicetree. + + +Credits +------- + +This is an implementation of an idea by Tom Rini <trini@konsulko.com>. + + +Future work +----------- +- Consider programmatically reading binding files instead of devicetree + contents +- Allow IS_ENABLED() to be used in the C code instead of #if + + +.. Simon Glass <sjg@chromium.org> +.. Google, Inc +.. 6/6/16 +.. Updated Independence Day 2016 +.. Updated 1st October 2020 +.. Updated 5th February 2021 diff --git a/roms/u-boot/doc/develop/driver-model/pci-info.rst b/roms/u-boot/doc/develop/driver-model/pci-info.rst new file mode 100644 index 000000000..251601a51 --- /dev/null +++ b/roms/u-boot/doc/develop/driver-model/pci-info.rst @@ -0,0 +1,172 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +PCI with Driver Model +===================== + +How busses are scanned +---------------------- + +Any config read will end up at pci_read_config(). This uses +uclass_get_device_by_seq() to get the PCI bus for a particular bus number. +Bus number 0 will need to be requested first, and the alias in the device +tree file will point to the correct device:: + + aliases { + pci0 = &pcic; + }; + + pcic: pci@0 { + compatible = "sandbox,pci"; + ... + }; + + +If there is no alias the devices will be numbered sequentially in the device +tree. + +The call to uclass_get_device() will cause the PCI bus to be probed. +This does a scan of the bus to locate available devices. These devices are +bound to their appropriate driver if available. If there is no driver, then +they are bound to a generic PCI driver which does nothing. + +After probing a bus, the available devices will appear in the device tree +under that bus. + +Note that this is all done on a lazy basis, as needed, so until something is +touched on PCI (eg: a call to pci_find_devices()) it will not be probed. + +PCI devices can appear in the flattened device tree. If they do, their node +often contains extra information which cannot be derived from the PCI IDs or +PCI class of the device. Each PCI device node must have a <reg> property, as +defined by the IEEE Std 1275-1994 PCI bus binding document v2.1. Compatible +string list is optional and generally not needed, since PCI is discoverable +bus, albeit there are justified exceptions. If the compatible string is +present, matching on it takes precedence over PCI IDs and PCI classes. + +Note we must describe PCI devices with the same bus hierarchy as the +hardware, otherwise driver model cannot detect the correct parent/children +relationship during PCI bus enumeration thus PCI devices won't be bound to +their drivers accordingly. A working example like below:: + + pci { + #address-cells = <3>; + #size-cells = <2>; + compatible = "pci-x86"; + u-boot,dm-pre-reloc; + ranges = <0x02000000 0x0 0x40000000 0x40000000 0 0x80000000 + 0x42000000 0x0 0xc0000000 0xc0000000 0 0x20000000 + 0x01000000 0x0 0x2000 0x2000 0 0xe000>; + + pcie@17,0 { + #address-cells = <3>; + #size-cells = <2>; + compatible = "pci-bridge"; + u-boot,dm-pre-reloc; + reg = <0x0000b800 0x0 0x0 0x0 0x0>; + + topcliff@0,0 { + #address-cells = <3>; + #size-cells = <2>; + compatible = "pci-bridge"; + u-boot,dm-pre-reloc; + reg = <0x00010000 0x0 0x0 0x0 0x0>; + + pciuart0: uart@a,1 { + compatible = "pci8086,8811.00", + "pci8086,8811", + "pciclass,070002", + "pciclass,0700", + "x86-uart"; + u-boot,dm-pre-reloc; + reg = <0x00025100 0x0 0x0 0x0 0x0 + 0x01025110 0x0 0x0 0x0 0x0>; + ...... + }; + + ...... + }; + }; + + ...... + }; + +In this example, the root PCI bus node is the "/pci" which matches "pci-x86" +driver. It has a subnode "pcie@17,0" with driver "pci-bridge". "pcie@17,0" +also has subnode "topcliff@0,0" which is a "pci-bridge" too. Under that bridge, +a PCI UART device "uart@a,1" is described. This exactly reflects the hardware +bus hierarchy: on the root PCI bus, there is a PCIe root port which connects +to a downstream device Topcliff chipset. Inside Topcliff chipset, it has a +PCIe-to-PCI bridge and all the chipset integrated devices like the PCI UART +device are on the PCI bus. Like other devices in the device tree, if we want +to bind PCI devices before relocation, "u-boot,dm-pre-reloc" must be declared +in each of these nodes. + +If PCI devices are not listed in the device tree, U_BOOT_PCI_DEVICE can be used +to specify the driver to use for the device. The device tree takes precedence +over U_BOOT_PCI_DEVICE. Please note with U_BOOT_PCI_DEVICE, only drivers with +DM_FLAG_PRE_RELOC will be bound before relocation. If neither device tree nor +U_BOOT_PCI_DEVICE is provided, the built-in driver (either pci_bridge_drv or +pci_generic_drv) will be used. + + +Sandbox +------- + +With sandbox we need a device emulator for each device on the bus since there +is no real PCI bus. This works by looking in the device tree node for an +emulator driver. For example:: + + pci@1f,0 { + compatible = "pci-generic"; + reg = <0xf800 0 0 0 0>; + sandbox,emul = <&emul_1f>; + }; + pci-emul { + compatible = "sandbox,pci-emul-parent"; + emul_1f: emul@1f,0 { + compatible = "sandbox,swap-case"; + #emul-cells = <0>; + }; + }; + +This means that there is a 'sandbox,swap-case' driver at that bus position. +Note that the first cell in the 'reg' value is the bus/device/function. See +PCI_BDF() for the encoding (it is also specified in the IEEE Std 1275-1994 +PCI bus binding document, v2.1) + +The pci-emul node should go outside the pci bus node, since otherwise it will +be scanned as a PCI device, causing confusion. + +When this bus is scanned we will end up with something like this:: + + `- * pci@0 @ 05c660c8, 0 + `- pci@1f,0 @ 05c661c8, 63488 + `- emul@1f,0 @ 05c662c8 + +When accesses go to the pci@1f,0 device they are forwarded to its emulator. + +The sandbox PCI drivers also support dynamic driver binding, allowing device +driver to declare the driver binding information via U_BOOT_PCI_DEVICE(), +eliminating the need to provide any device tree node under the host controller +node. It is required a "sandbox,dev-info" property must be provided in the +host controller node for this functionality to work. + +.. code-block:: none + + pci1: pci@1 { + compatible = "sandbox,pci"; + ... + sandbox,dev-info = <0x08 0x00 0x1234 0x5678 + 0x0c 0x00 0x1234 0x5678>; + }; + +The "sandbox,dev-info" property specifies all dynamic PCI devices on this bus. +Each dynamic PCI device is encoded as 4 cells a group. The first and second +cells are PCI device number and function number respectively. The third and +fourth cells are PCI vendor ID and device ID respectively. + +When this bus is scanned we will end up with something like this:: + + pci [ + ] pci_sandbo |-- pci1 + pci_emul [ ] sandbox_sw | |-- sandbox_swap_case_emul + pci_emul [ ] sandbox_sw | `-- sandbox_swap_case_emul diff --git a/roms/u-boot/doc/develop/driver-model/pmic-framework.rst b/roms/u-boot/doc/develop/driver-model/pmic-framework.rst new file mode 100644 index 000000000..d24a1badd --- /dev/null +++ b/roms/u-boot/doc/develop/driver-model/pmic-framework.rst @@ -0,0 +1,143 @@ +.. SPDX-License-Identifier: GPL-2.0+ +.. (C) Copyright 2014-2015 Samsung Electronics +.. sectionauthor:: Przemyslaw Marczak <p.marczak@samsung.com> + +PMIC framework based on Driver Model +==================================== + +Introduction +------------ +This is an introduction to driver-model multi uclass PMIC IC's support. +At present it's based on two uclass types: + +UCLASS_PMIC: + basic uclass type for PMIC I/O, which provides common + read/write interface. +UCLASS_REGULATOR: + additional uclass type for specific PMIC features, which are + Voltage/Current regulators. + +New files: + +UCLASS_PMIC: + - drivers/power/pmic/pmic-uclass.c + - include/power/pmic.h +UCLASS_REGULATOR: + - drivers/power/regulator/regulator-uclass.c + - include/power/regulator.h + +Commands: +- common/cmd_pmic.c +- common/cmd_regulator.c + +How doees it work +----------------- +The Power Management Integrated Circuits (PMIC) are used in embedded systems +to provide stable, precise and specific voltage power source with over-voltage +and thermal protection circuits. + +The single PMIC can provide various functions by single or multiple interfaces, +like in the example below:: + + -- SoC + | + | ______________________________________ + | BUS 0 | Multi interface PMIC IC |--> LDO out 1 + | e.g.I2C0 | |--> LDO out N + |-----------|---- PMIC device 0 (READ/WRITE ops) | + | or SPI0 | |_ REGULATOR device (ldo/... ops) |--> BUCK out 1 + | | |_ CHARGER device (charger ops) |--> BUCK out M + | | |_ MUIC device (microUSB con ops) | + | BUS 1 | |_ ... |---> BATTERY + | e.g.I2C1 | | + |-----------|---- PMIC device 1 (READ/WRITE ops) |---> USB in 1 + . or SPI1 | |_ RTC device (rtc ops) |---> USB in 2 + . |______________________________________|---> USB out + . + +Since U-Boot provides driver model features for I2C and SPI bus drivers, +the PMIC devices should also support this. By the pmic and regulator API's, +PMIC drivers can simply provide a common functions, for multi-interface and +and multi-instance device support. + +Basic design assumptions: + +- Common I/O API: + UCLASS_PMIC. For the multi-function PMIC devices, this can be used as + parent I/O device for each IC's interface. Then, each children uses the + same dev for read/write. + +- Common regulator API: + UCLASS_REGULATOR. For driving the regulator attributes, auto setting + function or command line interface, based on kernel-style regulator device + tree constraints. + +For simple implementations, regulator drivers are not required, so the code can +use pmic read/write directly. + +Pmic uclass +----------- +The basic information: + +* Uclass: 'UCLASS_PMIC' +* Header: 'include/power/pmic.h' +* Core: 'drivers/power/pmic/pmic-uclass.c' (config 'CONFIG_DM_PMIC') +* Command: 'common/cmd_pmic.c' (config 'CONFIG_CMD_PMIC') +* Example: 'drivers/power/pmic/max77686.c' + +For detailed API description, please refer to the header file. + +As an example of the pmic driver, please refer to the MAX77686 driver. + +Please pay attention for the driver's bind() method. Exactly the function call: +'pmic_bind_children()', which is used to bind the regulators by using the array +of regulator's node, compatible prefixes. + +The 'pmic; command also supports the new API. So the pmic command can be enabled +by adding CONFIG_CMD_PMIC. +The new pmic command allows to: +- list pmic devices +- choose the current device (like the mmc command) +- read or write the pmic register +- dump all pmic registers + +This command can use only UCLASS_PMIC devices, since this uclass is designed +for pmic I/O operations only. + +For more information, please refer to the core file. + +Regulator uclass +---------------- +The basic information: + +* Uclass: 'UCLASS_REGULATOR' + +* Header: 'include/power/regulator.h' + +* Core: 'drivers/power/regulator/regulator-uclass.c' + (config 'CONFIG_DM_REGULATOR') + +* Binding: 'doc/device-tree-bindings/regulator/regulator.txt' + +* Command: 'common/cmd_regulator.c' (config 'CONFIG_CMD_REGULATOR') + +* Example: 'drivers/power/regulator/max77686.c' + 'drivers/power/pmic/max77686.c' (required I/O driver for the above) + +* Example: 'drivers/power/regulator/fixed.c' + (config 'CONFIG_DM_REGULATOR_FIXED') + +For detailed API description, please refer to the header file. + +For the example regulator driver, please refer to the MAX77686 regulator driver, +but this driver can't operate without pmic's example driver, which provides an +I/O interface for MAX77686 regulator. + +The second example is a fixed Voltage/Current regulator for a common use. + +The 'regulator' command also supports the new API. The command allow: +- list regulator devices +- choose the current device (like the mmc command) +- do all regulator-specific operations + +For more information, please refer to the command file. diff --git a/roms/u-boot/doc/develop/driver-model/remoteproc-framework.rst b/roms/u-boot/doc/develop/driver-model/remoteproc-framework.rst new file mode 100644 index 000000000..566495a21 --- /dev/null +++ b/roms/u-boot/doc/develop/driver-model/remoteproc-framework.rst @@ -0,0 +1,169 @@ +.. SPDX-License-Identifier: GPL-2.0+ +.. (C) Copyright 2015 +.. Texas Instruments Incorporated - http://www.ti.com/ + +Remote Processor Framework +========================== + +Introduction +------------ + +This is an introduction to driver-model for Remote Processors found +on various System on Chip(SoCs). The term remote processor is used to +indicate that this is not the processor on which U-Boot is operating +on, instead is yet another processing entity that may be controlled by +the processor on which we are functional. + +The simplified model depends on a single UCLASS - UCLASS_REMOTEPROC + +UCLASS_REMOTEPROC: + - drivers/remoteproc/rproc-uclass.c + - include/remoteproc.h + +Commands: + - common/cmd_remoteproc.c + +Configuration: + - CONFIG_REMOTEPROC is selected by drivers as needed + - CONFIG_CMD_REMOTEPROC for the commands if required. + +How does it work - The driver +----------------------------- + +Overall, the driver statemachine transitions are typically as follows:: + + (entry) + +-------+ + +---+ init | + | | | <---------------------+ + | +-------+ | + | | + | | + | +--------+ | + Load| | reset | | + | | | <----------+ | + | +--------+ | | + | |Load | | + | | | | + | +----v----+ reset | | + +-> | | (opt) | | + | Loaded +-----------+ | + | | | + +----+----+ | + | Start | + +---v-----+ (opt) | + +->| Running | Stop | + Ping +- | +--------------------+ + (opt) +---------+ + +(is_running does not change state) +opt: Optional state transition implemented by driver. + +NOTE: It depends on the remote processor as to the exact behavior +of the statemachine, remoteproc core does not intent to implement +statemachine logic. Certain processors may allow start/stop without +reloading the image in the middle, certain other processors may only +allow us to start the processor(image from a EEPROM/OTP) etc. + +It is hence the responsibility of the driver to handle the requisite +state transitions of the device as necessary. + +Basic design assumptions: + +Remote processor can operate on a certain firmware that maybe loaded +and released from reset. + +The driver follows a standard UCLASS DM. + +in the bare minimum form: + +.. code-block:: c + + static const struct dm_rproc_ops sandbox_testproc_ops = { + .load = sandbox_testproc_load, + .start = sandbox_testproc_start, + }; + + static const struct udevice_id sandbox_ids[] = { + {.compatible = "sandbox,test-processor"}, + {} + }; + + U_BOOT_DRIVER(sandbox_testproc) = { + .name = "sandbox_test_proc", + .of_match = sandbox_ids, + .id = UCLASS_REMOTEPROC, + .ops = &sandbox_testproc_ops, + .probe = sandbox_testproc_probe, + }; + +This allows for the device to be probed as part of the "init" command +or invocation of 'rproc_init()' function as the system dependencies define. + +The driver is expected to maintain it's own statemachine which is +appropriate for the device it maintains. It must, at the very least +provide a load and start function. We assume here that the device +needs to be loaded and started, else, there is no real purpose of +using the remoteproc framework. + +Describing the device using platform data +----------------------------------------- + +*IMPORTANT* NOTE: THIS SUPPORT IS NOT MEANT FOR USE WITH NEWER PLATFORM +SUPPORT. THIS IS ONLY FOR LEGACY DEVICES. THIS MODE OF INITIALIZATION +*WILL* BE EVENTUALLY REMOVED ONCE ALL NECESSARY PLATFORMS HAVE MOVED +TO DM/FDT. + +Considering that many platforms are yet to move to device-tree model, +a simplified definition of a device is as follows: + +.. code-block:: c + + struct dm_rproc_uclass_pdata proc_3_test = { + .name = "proc_3_legacy", + .mem_type = RPROC_INTERNAL_MEMORY_MAPPED, + .driver_plat_data = &mydriver_data; + }; + + U_BOOT_DRVINFO(proc_3_demo) = { + .name = "sandbox_test_proc", + .plat = &proc_3_test, + }; + +There can be additional data that may be desired depending on the +remoteproc driver specific needs (for example: SoC integration +details such as clock handle or something similar). See appropriate +documentation for specific remoteproc driver for further details. +These are passed via driver_plat_data. + +Describing the device using device tree +--------------------------------------- + +.. code-block: none + + / { + ... + aliases { + ... + remoteproc0 = &rproc_1; + remoteproc1 = &rproc_2; + + }; + ... + + rproc_1: rproc@1 { + compatible = "sandbox,test-processor"; + remoteproc-name = "remoteproc-test-dev1"; + }; + + rproc_2: rproc@2 { + compatible = "sandbox,test-processor"; + internal-memory-mapped; + remoteproc-name = "remoteproc-test-dev2"; + }; + ... + }; + +aliases usage is optional, but it is usually recommended to ensure the +users have a consistent usage model for a platform. +the compatible string used here is specific to the remoteproc driver involved. diff --git a/roms/u-boot/doc/develop/driver-model/serial-howto.rst b/roms/u-boot/doc/develop/driver-model/serial-howto.rst new file mode 100644 index 000000000..146913112 --- /dev/null +++ b/roms/u-boot/doc/develop/driver-model/serial-howto.rst @@ -0,0 +1,46 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +How to port a serial driver to driver model +=========================================== + +Almost all of the serial drivers have been converted as at January 2016. These +ones remain: + + * serial_bfin.c + * serial_pxa.c + +The deadline for this work was the end of January 2016. If no one steps +forward to convert these, at some point there may come a patch to remove them! + +Here is a suggested approach for converting your serial driver over to driver +model. Please feel free to update this file with your ideas and suggestions. + +- #ifdef out all your own serial driver code (#ifndef CONFIG_DM_SERIAL) +- Define CONFIG_DM_SERIAL for your board, vendor or architecture +- If the board does not already use driver model, you need CONFIG_DM also +- Your board should then build, but will not boot since there will be no serial + driver +- Add the U_BOOT_DRIVER piece at the end (e.g. copy serial_s5p.c for example) +- Add a private struct for the driver data - avoid using static variables +- Implement each of the driver methods, perhaps by calling your old methods +- You may need to adjust the function parameters so that the old and new + implementations can share most of the existing code +- If you convert all existing users of the driver, remove the pre-driver-model + code + +In terms of patches a conversion series typically has these patches: +- clean up / prepare the driver for conversion +- add driver model code +- convert at least one existing board to use driver model serial +- (if no boards remain that don't use driver model) remove the old code + +This may be a good time to move your board to use device tree also. Mostly +this involves these steps: + +- define CONFIG_OF_CONTROL and CONFIG_OF_SEPARATE +- add your device tree files to arch/<arch>/dts +- update the Makefile there +- Add stdout-path to your /chosen device tree node if it is not already there +- build and get u-boot-dtb.bin so you can test it +- Your drivers can now use device tree +- For device tree in SPL, define CONFIG_SPL_OF_CONTROL diff --git a/roms/u-boot/doc/develop/driver-model/soc-framework.rst b/roms/u-boot/doc/develop/driver-model/soc-framework.rst new file mode 100644 index 000000000..2609fda64 --- /dev/null +++ b/roms/u-boot/doc/develop/driver-model/soc-framework.rst @@ -0,0 +1,68 @@ +.. SPDX-License-Identifier: GPL-2.0+ +.. (C) Copyright 2020 +.. Texas Instruments Incorporated - http://www.ti.com/ + +SOC ID Framework +================ + +Introduction +------------ + +The driver-model SOC ID framework is able to provide identification +information about a specific SoC in use at runtime, and also provide matching +from a set of identification information from an array. This can be useful for +enabling small quirks in drivers that exist between SoC variants that are +impractical to implement using device tree flags. It is based on UCLASS_SOC. + +UCLASS_SOC: + - drivers/soc/soc-uclass.c + - include/soc.h + +Configuration: + - CONFIG_SOC_DEVICE is selected by drivers as needed. + +Implementing a UCLASS_SOC provider +---------------------------------- + +The purpose of this framework is to allow UCLASS_SOC provider drivers to supply +identification information about the SoC in use at runtime. The framework +allows drivers to define soc_ops that return identification strings. All +soc_ops need not be defined and can be left as NULL, in which case the +framework will return -ENOSYS and not consider the value when doing an +soc_device_match. + +It is left to the driver implementor to decide how the information returned is +determined, but in general the same SOC should always return the same set of +identifying information. Information returned must be in the form of a NULL +terminated string. + +See include/soc.h for documentation of the available soc_ops and the intended +meaning of the values that can be returned. See drivers/soc/soc_sandbox.c for +an example UCLASS_SOC provider driver. + +Using a UCLASS_SOC driver +------------------------- + +The framework provides the ability to retrieve and use the identification +strings directly. It also has the ability to return a match from a list of +different sets of SoC data using soc_device_match. + +An array of 'struct soc_attr' can be defined, each containing ID information +for a specific SoC, and when passed to soc_device_match, the identifier values +for each entry in the list will be compared against the values provided by the +UCLASS_SOC driver that is in use. The first entry in the list that matches all +non-null values will be returned by soc_device_match. + +An example of various uses of the framework can be found at test/dm/soc.c. + +Describing the device using device tree +--------------------------------------- + +.. code-block:: none + + chipid: chipid { + compatible = "sandbox,soc"; + }; + +All that is required in a DT node is a compatible for a corresponding +UCLASS_SOC driver. diff --git a/roms/u-boot/doc/develop/driver-model/spi-howto.rst b/roms/u-boot/doc/develop/driver-model/spi-howto.rst new file mode 100644 index 000000000..97fbf750c --- /dev/null +++ b/roms/u-boot/doc/develop/driver-model/spi-howto.rst @@ -0,0 +1,692 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +How to port a SPI driver to driver model +======================================== + +Here is a rough step-by-step guide. It is based around converting the +exynos SPI driver to driver model (DM) and the example code is based +around U-Boot v2014.10-rc2 (commit be9f643). This has been updated for +v2015.04. + +It is quite long since it includes actual code examples. + +Before driver model, SPI drivers have their own private structure which +contains 'struct spi_slave'. With driver model, 'struct spi_slave' still +exists, but now it is 'per-child data' for the SPI bus. Each child of the +SPI bus is a SPI slave. The information that was stored in the +driver-specific slave structure can now be port in private data for the +SPI bus. + +For example, struct tegra_spi_slave looks like this: + +.. code-block:: c + + struct tegra_spi_slave { + struct spi_slave slave; + struct tegra_spi_ctrl *ctrl; + }; + +In this case 'slave' will be in per-child data, and 'ctrl' will be in the +SPI's buses private data. + + +How long does this take? +------------------------ + +You should be able to complete this within 2 hours, including testing but +excluding preparing the patches. The API is basically the same as before +with only minor changes: + +- methods to set speed and mode are separated out +- cs_info is used to get information on a chip select + + +Enable driver mode for SPI and SPI flash +---------------------------------------- + +Add these to your board config: + +* CONFIG_DM_SPI +* CONFIG_DM_SPI_FLASH + + +Add the skeleton +---------------- + +Put this code at the bottom of your existing driver file: + +.. code-block:: c + + struct spi_slave *spi_setup_slave(unsigned int busnum, unsigned int cs, + unsigned int max_hz, unsigned int mode) + { + return NULL; + } + + struct spi_slave *spi_setup_slave_fdt(const void *blob, int slave_node, + int spi_node) + { + return NULL; + } + + static int exynos_spi_of_to_plat(struct udevice *dev) + { + return -ENODEV; + } + + static int exynos_spi_probe(struct udevice *dev) + { + return -ENODEV; + } + + static int exynos_spi_remove(struct udevice *dev) + { + return -ENODEV; + } + + static int exynos_spi_claim_bus(struct udevice *dev) + { + + return -ENODEV; + } + + static int exynos_spi_release_bus(struct udevice *dev) + { + + return -ENODEV; + } + + static int exynos_spi_xfer(struct udevice *dev, unsigned int bitlen, + const void *dout, void *din, unsigned long flags) + { + + return -ENODEV; + } + + static int exynos_spi_set_speed(struct udevice *dev, uint speed) + { + return -ENODEV; + } + + static int exynos_spi_set_mode(struct udevice *dev, uint mode) + { + return -ENODEV; + } + + static int exynos_cs_info(struct udevice *bus, uint cs, + struct spi_cs_info *info) + { + return -EINVAL; + } + + static const struct dm_spi_ops exynos_spi_ops = { + .claim_bus = exynos_spi_claim_bus, + .release_bus = exynos_spi_release_bus, + .xfer = exynos_spi_xfer, + .set_speed = exynos_spi_set_speed, + .set_mode = exynos_spi_set_mode, + .cs_info = exynos_cs_info, + }; + + static const struct udevice_id exynos_spi_ids[] = { + { .compatible = "samsung,exynos-spi" }, + { } + }; + + U_BOOT_DRIVER(exynos_spi) = { + .name = "exynos_spi", + .id = UCLASS_SPI, + .of_match = exynos_spi_ids, + .ops = &exynos_spi_ops, + .of_to_plat = exynos_spi_of_to_plat, + .probe = exynos_spi_probe, + .remove = exynos_spi_remove, + }; + + +Replace 'exynos' in the above code with your driver name +-------------------------------------------------------- + + +#ifdef out all of the code in your driver except for the above +-------------------------------------------------------------- + +This will allow you to get it building, which means you can work +incrementally. Since all the methods return an error initially, there is +less chance that you will accidentally leave something in. + +Also, even though your conversion is basically a rewrite, it might help +reviewers if you leave functions in the same place in the file, +particularly for large drivers. + + +Add some includes +----------------- + +Add these includes to your driver: + +.. code-block:: c + + #include <dm.h> + #include <errno.h> + + +Build +----- + +At this point you should be able to build U-Boot for your board with the +empty SPI driver. You still have empty methods in your driver, but we will +write these one by one. + +Set up your platform data structure +----------------------------------- + +This will hold the information your driver to operate, like its hardware +address or maximum frequency. + +You may already have a struct like this, or you may need to create one +from some of the #defines or global variables in the driver. + +Note that this information is not the run-time information. It should not +include state that changes. It should be fixed throughout the live of +U-Boot. Run-time information comes later. + +Here is what was in the exynos spi driver: + +.. code-block:: c + + struct spi_bus { + enum periph_id periph_id; + s32 frequency; /* Default clock frequency, -1 for none */ + struct exynos_spi *regs; + int inited; /* 1 if this bus is ready for use */ + int node; + uint deactivate_delay_us; /* Delay to wait after deactivate */ + }; + +Of these, inited is handled by DM and node is the device tree node, which +DM tells you. The name is not quite right. So in this case we would use: + +.. code-block:: c + + struct exynos_spi_plat { + enum periph_id periph_id; + s32 frequency; /* Default clock frequency, -1 for none */ + struct exynos_spi *regs; + uint deactivate_delay_us; /* Delay to wait after deactivate */ + }; + + +Write of_to_plat() [for device tree only] +------------------------------------------------- + +This method will convert information in the device tree node into a C +structure in your driver (called platform data). If you are not using +device tree, go to 8b. + +DM will automatically allocate the struct for us when we are using device +tree, but we need to tell it the size: + +.. code-block:: c + + U_BOOT_DRIVER(spi_exynos) = { + ... + .plat_auto = sizeof(struct exynos_spi_plat), + + +Here is a sample function. It gets a pointer to the platform data and +fills in the fields from device tree. + +.. code-block:: c + + static int exynos_spi_of_to_plat(struct udevice *bus) + { + struct exynos_spi_plat *plat = bus->plat; + const void *blob = gd->fdt_blob; + int node = dev_of_offset(bus); + + plat->regs = (struct exynos_spi *)fdtdec_get_addr(blob, node, "reg"); + plat->periph_id = pinmux_decode_periph_id(blob, node); + + if (plat->periph_id == PERIPH_ID_NONE) { + debug("%s: Invalid peripheral ID %d\n", __func__, + plat->periph_id); + return -FDT_ERR_NOTFOUND; + } + + /* Use 500KHz as a suitable default */ + plat->frequency = fdtdec_get_int(blob, node, "spi-max-frequency", + 500000); + plat->deactivate_delay_us = fdtdec_get_int(blob, node, + "spi-deactivate-delay", 0); + debug("%s: regs=%p, periph_id=%d, max-frequency=%d, deactivate_delay=%d\n", + __func__, plat->regs, plat->periph_id, plat->frequency, + plat->deactivate_delay_us); + + return 0; + } + + +Add the platform data [non-device-tree only] +-------------------------------------------- + +Specify this data in a U_BOOT_DRVINFO() declaration in your board file: + +.. code-block:: c + + struct exynos_spi_plat platdata_spi0 = { + .periph_id = ... + .frequency = ... + .regs = ... + .deactivate_delay_us = ... + }; + + U_BOOT_DRVINFO(board_spi0) = { + .name = "exynos_spi", + .plat = &platdata_spi0, + }; + +You will unfortunately need to put the struct definition into a header file +in this case so that your board file can use it. + + +Add the device private data +--------------------------- + +Most devices have some private data which they use to keep track of things +while active. This is the run-time information and needs to be stored in +a structure. There is probably a structure in the driver that includes a +'struct spi_slave', so you can use that. + +.. code-block:: c + + struct exynos_spi_slave { + struct spi_slave slave; + struct exynos_spi *regs; + unsigned int freq; /* Default frequency */ + unsigned int mode; + enum periph_id periph_id; /* Peripheral ID for this device */ + unsigned int fifo_size; + int skip_preamble; + struct spi_bus *bus; /* Pointer to our SPI bus info */ + ulong last_transaction_us; /* Time of last transaction end */ + }; + + +We should rename this to make its purpose more obvious, and get rid of +the slave structure, so we have: + +.. code-block:: c + + struct exynos_spi_priv { + struct exynos_spi *regs; + unsigned int freq; /* Default frequency */ + unsigned int mode; + enum periph_id periph_id; /* Peripheral ID for this device */ + unsigned int fifo_size; + int skip_preamble; + ulong last_transaction_us; /* Time of last transaction end */ + }; + + +DM can auto-allocate this also: + +.. code-block:: c + + U_BOOT_DRIVER(spi_exynos) = { + ... + .priv_auto = sizeof(struct exynos_spi_priv), + + +Note that this is created before the probe method is called, and destroyed +after the remove method is called. It will be zeroed when the probe +method is called. + + +Add the probe() and remove() methods +------------------------------------ + +Note: It's a good idea to build repeatedly as you are working, to avoid a +huge amount of work getting things compiling at the end. + +The probe method is supposed to set up the hardware. U-Boot used to use +spi_setup_slave() to do this. So take a look at this function and see +what you can copy out to set things up. + +.. code-block:: c + + static int exynos_spi_probe(struct udevice *bus) + { + struct exynos_spi_plat *plat = dev_get_plat(bus); + struct exynos_spi_priv *priv = dev_get_priv(bus); + + priv->regs = plat->regs; + if (plat->periph_id == PERIPH_ID_SPI1 || + plat->periph_id == PERIPH_ID_SPI2) + priv->fifo_size = 64; + else + priv->fifo_size = 256; + + priv->skip_preamble = 0; + priv->last_transaction_us = timer_get_us(); + priv->freq = plat->frequency; + priv->periph_id = plat->periph_id; + + return 0; + } + +This implementation doesn't actually touch the hardware, which is somewhat +unusual for a driver. In this case we will do that when the device is +claimed by something that wants to use the SPI bus. + +For remove we could shut down the clocks, but in this case there is +nothing to do. DM frees any memory that it allocated, so we can just +remove exynos_spi_remove() and its reference in U_BOOT_DRIVER. + + +Implement set_speed() +--------------------- + +This should set up clocks so that the SPI bus is running at the right +speed. With the old API spi_claim_bus() would normally do this and several +of the following functions, so let's look at that function: + +.. code-block:: c + + int spi_claim_bus(struct spi_slave *slave) + { + struct exynos_spi_slave *spi_slave = to_exynos_spi(slave); + struct exynos_spi *regs = spi_slave->regs; + u32 reg = 0; + int ret; + + ret = set_spi_clk(spi_slave->periph_id, + spi_slave->freq); + if (ret < 0) { + debug("%s: Failed to setup spi clock\n", __func__); + return ret; + } + + exynos_pinmux_config(spi_slave->periph_id, PINMUX_FLAG_NONE); + + spi_flush_fifo(slave); + + reg = readl(®s->ch_cfg); + reg &= ~(SPI_CH_CPHA_B | SPI_CH_CPOL_L); + + if (spi_slave->mode & SPI_CPHA) + reg |= SPI_CH_CPHA_B; + + if (spi_slave->mode & SPI_CPOL) + reg |= SPI_CH_CPOL_L; + + writel(reg, ®s->ch_cfg); + writel(SPI_FB_DELAY_180, ®s->fb_clk); + + return 0; + } + + +It sets up the speed, mode, pinmux, feedback delay and clears the FIFOs. +With DM these will happen in separate methods. + + +Here is an example for the speed part: + +.. code-block:: c + + static int exynos_spi_set_speed(struct udevice *bus, uint speed) + { + struct exynos_spi_plat *plat = bus->plat; + struct exynos_spi_priv *priv = dev_get_priv(bus); + int ret; + + if (speed > plat->frequency) + speed = plat->frequency; + ret = set_spi_clk(priv->periph_id, speed); + if (ret) + return ret; + priv->freq = speed; + debug("%s: regs=%p, speed=%d\n", __func__, priv->regs, priv->freq); + + return 0; + } + + +Implement set_mode() +-------------------- + +This should adjust the SPI mode (polarity, etc.). Again this code probably +comes from the old spi_claim_bus(). Here is an example: + +.. code-block:: c + + static int exynos_spi_set_mode(struct udevice *bus, uint mode) + { + struct exynos_spi_priv *priv = dev_get_priv(bus); + uint32_t reg; + + reg = readl(&priv->regs->ch_cfg); + reg &= ~(SPI_CH_CPHA_B | SPI_CH_CPOL_L); + + if (mode & SPI_CPHA) + reg |= SPI_CH_CPHA_B; + + if (mode & SPI_CPOL) + reg |= SPI_CH_CPOL_L; + + writel(reg, &priv->regs->ch_cfg); + priv->mode = mode; + debug("%s: regs=%p, mode=%d\n", __func__, priv->regs, priv->mode); + + return 0; + } + + +Implement claim_bus() +--------------------- + +This is where a client wants to make use of the bus, so claims it first. +At this point we need to make sure everything is set up ready for data +transfer. Note that this function is wholly internal to the driver - at +present the SPI uclass never calls it. + +Here again we look at the old claim function and see some code that is +needed. It is anything unrelated to speed and mode: + +.. code-block:: c + + static int exynos_spi_claim_bus(struct udevice *bus) + { + struct exynos_spi_priv *priv = dev_get_priv(bus); + + exynos_pinmux_config(priv->periph_id, PINMUX_FLAG_NONE); + spi_flush_fifo(priv->regs); + + writel(SPI_FB_DELAY_180, &priv->regs->fb_clk); + + return 0; + } + +The spi_flush_fifo() function is in the removed part of the code, so we +need to expose it again (perhaps with an #endif before it and '#if 0' +after it). It only needs access to priv->regs which is why we have +passed that in: + +.. code-block:: c + + /** + * Flush spi tx, rx fifos and reset the SPI controller + * + * @param regs Pointer to SPI registers + */ + static void spi_flush_fifo(struct exynos_spi *regs) + { + clrsetbits_le32(®s->ch_cfg, SPI_CH_HS_EN, SPI_CH_RST); + clrbits_le32(®s->ch_cfg, SPI_CH_RST); + setbits_le32(®s->ch_cfg, SPI_TX_CH_ON | SPI_RX_CH_ON); + } + + +Implement release_bus() +----------------------- + +This releases the bus - in our example the old code in spi_release_bus() +is a call to spi_flush_fifo, so we add: + +.. code-block:: c + + static int exynos_spi_release_bus(struct udevice *bus) + { + struct exynos_spi_priv *priv = dev_get_priv(bus); + + spi_flush_fifo(priv->regs); + + return 0; + } + + +Implement xfer() +---------------- + +This is the final method that we need to create, and it is where all the +work happens. The method parameters are the same as the old spi_xfer() with +the addition of a 'struct udevice' so conversion is pretty easy. Start +by copying the contents of spi_xfer() to your new xfer() method and proceed +from there. + +If (flags & SPI_XFER_BEGIN) is non-zero then xfer() normally calls an +activate function, something like this: + +.. code-block:: c + + void spi_cs_activate(struct spi_slave *slave) + { + struct exynos_spi_slave *spi_slave = to_exynos_spi(slave); + + /* If it's too soon to do another transaction, wait */ + if (spi_slave->bus->deactivate_delay_us && + spi_slave->last_transaction_us) { + ulong delay_us; /* The delay completed so far */ + delay_us = timer_get_us() - spi_slave->last_transaction_us; + if (delay_us < spi_slave->bus->deactivate_delay_us) + udelay(spi_slave->bus->deactivate_delay_us - delay_us); + } + + clrbits_le32(&spi_slave->regs->cs_reg, SPI_SLAVE_SIG_INACT); + debug("Activate CS, bus %d\n", spi_slave->slave.bus); + spi_slave->skip_preamble = spi_slave->mode & SPI_PREAMBLE; + } + +The new version looks like this: + +.. code-block:: c + + static void spi_cs_activate(struct udevice *dev) + { + struct udevice *bus = dev->parent; + struct exynos_spi_plat *pdata = dev_get_plat(bus); + struct exynos_spi_priv *priv = dev_get_priv(bus); + + /* If it's too soon to do another transaction, wait */ + if (pdata->deactivate_delay_us && + priv->last_transaction_us) { + ulong delay_us; /* The delay completed so far */ + delay_us = timer_get_us() - priv->last_transaction_us; + if (delay_us < pdata->deactivate_delay_us) + udelay(pdata->deactivate_delay_us - delay_us); + } + + clrbits_le32(&priv->regs->cs_reg, SPI_SLAVE_SIG_INACT); + debug("Activate CS, bus '%s'\n", bus->name); + priv->skip_preamble = priv->mode & SPI_PREAMBLE; + } + +All we have really done here is change the pointers and print the device name +instead of the bus number. Other local static functions can be treated in +the same way. + + +Set up the per-child data and child pre-probe function +------------------------------------------------------ + +To minimise the pain and complexity of the SPI subsystem while the driver +model change-over is in place, struct spi_slave is used to reference a +SPI bus slave, even though that slave is actually a struct udevice. In fact +struct spi_slave is the device's child data. We need to make sure this space +is available. It is possible to allocate more space that struct spi_slave +needs, but this is the minimum. + +.. code-block:: c + + U_BOOT_DRIVER(exynos_spi) = { + ... + .per_child_auto = sizeof(struct spi_slave), + } + + +Optional: Set up cs_info() if you want it +----------------------------------------- + +Sometimes it is useful to know whether a SPI chip select is valid, but this +is not obvious from outside the driver. In this case you can provide a +method for cs_info() to deal with this. If you don't provide it, then the +device tree will be used to determine what chip selects are valid. + +Return -EINVAL if the supplied chip select is invalid, or 0 if it is valid. +If you don't provide the cs_info() method, 0 is assumed for all chip selects +that do not appear in the device tree. + + +Test it +------- + +Now that you have the code written and it compiles, try testing it using +the 'sf test' command. You may need to enable CONFIG_CMD_SF_TEST for your +board. + + +Prepare patches and send them to the mailing lists +-------------------------------------------------- + +You can use 'tools/patman/patman' to prepare, check and send patches for +your work. See tools/patman/README for details. + +A little note about SPI uclass features +--------------------------------------- + +The SPI uclass keeps some information about each device 'dev' on the bus: + + struct dm_spi_slave_plat: + This is device_get_parent_plat(dev). + This is where the chip select number is stored, along with + the default bus speed and mode. It is automatically read + from the device tree in spi_child_post_bind(). It must not + be changed at run-time after being set up because platform + data is supposed to be immutable at run-time. + struct spi_slave: + This is device_get_parentdata(dev). + Already mentioned above. It holds run-time information about + the device. + +There are also some SPI uclass methods that get called behind the scenes: + + spi_post_bind(): + Called when a new bus is bound. + This scans the device tree for devices on the bus, and binds + each one. This in turn causes spi_child_post_bind() to be + called for each, which reads the device tree information + into the parent (per-child) platform data. + spi_child_post_bind(): + Called when a new child is bound. + As mentioned above this reads the device tree information + into the per-child platform data + spi_child_pre_probe(): + Called before a new child is probed. + This sets up the mode and speed in struct spi_slave by + copying it from the parent's platform data for this child. + It also sets the 'dev' pointer, needed to permit passing + 'struct spi_slave' around the place without needing a + separate 'struct udevice' pointer. + +The above housekeeping makes it easier to write your SPI driver. diff --git a/roms/u-boot/doc/develop/driver-model/usb-info.rst b/roms/u-boot/doc/develop/driver-model/usb-info.rst new file mode 100644 index 000000000..24d1e81a6 --- /dev/null +++ b/roms/u-boot/doc/develop/driver-model/usb-info.rst @@ -0,0 +1,423 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +How USB works with driver model +=============================== + +Introduction +------------ + +Driver model USB support makes use of existing features but changes how +drivers are found. This document provides some information intended to help +understand how things work with USB in U-Boot when driver model is enabled. + + +Enabling driver model for USB +----------------------------- + +A new CONFIG_DM_USB option is provided to enable driver model for USB. This +causes the USB uclass to be included, and drops the equivalent code in +usb.c. In particular the usb_init() function is then implemented by the +uclass. + + +Support for EHCI and XHCI +------------------------- + +So far OHCI is not supported. Both EHCI and XHCI drivers should be declared +as drivers in the USB uclass. For example: + +.. code-block:: c + + static const struct udevice_id ehci_usb_ids[] = { + { .compatible = "nvidia,tegra20-ehci", .data = USB_CTLR_T20 }, + { .compatible = "nvidia,tegra30-ehci", .data = USB_CTLR_T30 }, + { .compatible = "nvidia,tegra114-ehci", .data = USB_CTLR_T114 }, + { } + }; + + U_BOOT_DRIVER(usb_ehci) = { + .name = "ehci_tegra", + .id = UCLASS_USB, + .of_match = ehci_usb_ids, + .of_to_plat = ehci_usb_of_to_plat, + .probe = tegra_ehci_usb_probe, + .remove = tegra_ehci_usb_remove, + .ops = &ehci_usb_ops, + .plat_auto = sizeof(struct usb_plat), + .priv_auto = sizeof(struct fdt_usb), + .flags = DM_FLAG_ALLOC_PRIV_DMA, + }; + +Here ehci_usb_ids is used to list the controllers that the driver supports. +Each has its own data value. Controllers must be in the UCLASS_USB uclass. + +The of_to_plat() method allows the controller driver to grab any +necessary settings from the device tree. + +The ops here are ehci_usb_ops. All EHCI drivers will use these same ops in +most cases, since they are all EHCI-compatible. For EHCI there are also some +special operations that can be overridden when calling ehci_register(). + +The driver can use priv_auto to set the size of its private data. +This can hold run-time information needed by the driver for operation. It +exists when the device is probed (not when it is bound) and is removed when +the driver is removed. + +Note that usb_plat is currently only used to deal with setting up a bus +in USB device mode (OTG operation). It can be omitted if that is not +supported. + +The driver's probe() method should do the basic controller init and then +call ehci_register() to register itself as an EHCI device. It should call +ehci_deregister() in the remove() method. Registering a new EHCI device +does not by itself cause the bus to be scanned. + +The old ehci_hcd_init() function is no-longer used. Nor is it necessary to +set up the USB controllers from board init code. When 'usb start' is used, +each controller will be probed and its bus scanned. + +XHCI works in a similar way. + + +Data structures +--------------- + +The following primary data structures are in use: + +- struct usb_device: + This holds information about a device on the bus. All devices have + this structure, even the root hub. The controller itself does not + have this structure. You can access it for a device 'dev' with + dev_get_parent_priv(dev). It matches the old structure except that the + parent and child information is not present (since driver model + handles that). Once the device is set up, you can find the device + descriptor and current configuration descriptor in this structure. + +- struct usb_plat: + This holds platform data for a controller. So far this is only used + as a work-around for controllers which can act as USB devices in OTG + mode, since the gadget framework does not use driver model. + +- struct usb_dev_plat: + This holds platform data for a device. You can access it for a + device 'dev' with dev_get_parent_plat(dev). It holds the device + address and speed - anything that can be determined before the device + driver is actually set up. When probing the bus this structure is + used to provide essential information to the device driver. + +- struct usb_bus_priv: + This is private information for each controller, maintained by the + controller uclass. It is mostly used to keep track of the next + device address to use. + +Of these, only struct usb_device was used prior to driver model. + + +USB buses +--------- + +Given a controller, you know the bus - it is the one attached to the +controller. Each controller handles exactly one bus. Every controller has a +root hub attached to it. This hub, which is itself a USB device, can provide +one or more 'ports' to which additional devices can be attached. It is +possible to power up a hub and find out which of its ports have devices +attached. + +Devices are given addresses starting at 1. The root hub is always address 1, +and from there the devices are numbered in sequence. The USB uclass takes +care of this numbering automatically during enumeration. + +USB devices are enumerated by finding a device on a particular hub, and +setting its address to the next available address. The USB bus stretches out +in a tree structure, potentially with multiple hubs each with several ports +and perhaps other hubs. Some hubs will have their own power since otherwise +the 5V 500mA power supplied by the controller will not be sufficient to run +very many devices. + +Enumeration in U-Boot takes a long time since devices are probed one at a +time, and each is given sufficient time to wake up and announce itself. The +timeouts are set for the slowest device. + +Up to 127 devices can be on each bus. USB has four bus speeds: low +(1.5Mbps), full (12Mbps), high (480Mbps) which is only available with USB2 +and newer (EHCI), and super (5Gbps) which is only available with USB3 and +newer (XHCI). If you connect a super-speed device to a high-speed hub, you +will only get high-speed. + + +USB operations +-------------- + +As before driver model, messages can be sent using submit_bulk_msg() and the +like. These are now implemented by the USB uclass and route through the +controller drivers. Note that messages are not sent to the driver of the +device itself - i.e. they don't pass down the stack to the controller. +U-Boot simply finds the controller to which the device is attached, and sends +the message there with an appropriate 'pipe' value so it can be addressed +properly. Having said that, the USB device which should receive the message +is passed in to the driver methods, for use by sandbox. This design decision +is open for review and the code impact of changing it is small since the +methods are typically implemented by the EHCI and XHCI stacks. + +Controller drivers (in UCLASS_USB) themselves provide methods for sending +each message type. For XHCI an additional alloc_device() method is provided +since XHCI needs to allocate a device context before it can even read the +device's descriptor. + +These methods use a 'pipe' which is a collection of bit fields used to +describe the type of message, direction of transfer and the intended +recipient (device number). + + +USB Devices +----------- + +USB devices are found using a simple algorithm which works through the +available hubs in a depth-first search. Devices can be in any uclass, but +are attached to a parent hub (or controller in the case of the root hub) and +so have parent data attached to them (this is struct usb_device). + +By the time the device's probe() method is called, it is enumerated and is +ready to talk to the host. + +The enumeration process needs to work out which driver to attach to each USB +device. It does this by examining the device class, interface class, vendor +ID, product ID, etc. See struct usb_driver_entry for how drivers are matched +with USB devices - you can use the USB_DEVICE() macro to declare a USB +driver. For example, usb_storage.c defines a USB_DEVICE() to handle storage +devices, and it will be used for all USB devices which match. + + + +Technical details on enumeration flow +------------------------------------- + +It is useful to understand precisely how a USB bus is enumerating to avoid +confusion when dealing with USB devices. + +Device initialisation happens roughly like this: + +- At some point the 'usb start' command is run +- This calls usb_init() which works through each controller in turn +- The controller is probed(). This does no enumeration. +- Then usb_scan_bus() is called. This calls usb_scan_device() to scan the + (only) device that is attached to the controller - a root hub +- usb_scan_device() sets up a fake struct usb_device and calls + usb_setup_device(), passing the port number to be scanned, in this case + port 0 +- usb_setup_device() first calls usb_prepare_device() to set the device + address, then usb_select_config() to select the first configuration +- at this point the device is enumerated but we do not have a real struct + udevice for it. But we do have the descriptor in struct usb_device so we can + use this to figure out what driver to use +- back in usb_scan_device(), we call usb_find_child() to try to find an + existing device which matches the one we just found on the bus. This can + happen if the device is mentioned in the device tree, or if we previously + scanned the bus and so the device was created before +- if usb_find_child() does not find an existing device, we call + usb_find_and_bind_driver() which tries to bind one +- usb_find_and_bind_driver() searches all available USB drivers (declared + with USB_DEVICE()). If it finds a match it binds that driver to create a + new device. +- If it does not, it binds a generic driver. A generic driver is good enough + to allow access to the device (sending it packets, etc.) but all + functionality will need to be implemented outside the driver model. +- in any case, when usb_find_child() and/or usb_find_and_bind_driver() are + done, we have a device with the correct uclass. At this point we want to + probe the device +- first we store basic information about the new device (address, port, + speed) in its parent platform data. We cannot store it its private data + since that will not exist until the device is probed. +- then we call device_probe() which probes the device +- the first probe step is actually the USB controller's (or USB hubs's) + child_pre_probe() method. This gets called before anything else and is + intended to set up a child device ready to be used with its parent bus. For + USB this calls usb_child_pre_probe() which grabs the information that was + stored in the parent platform data and stores it in the parent private data + (which is struct usb_device, a real one this time). It then calls + usb_select_config() again to make sure that everything about the device is + set up +- note that we have called usb_select_config() twice. This is inefficient + but the alternative is to store additional information in the platform data. + The time taken is minimal and this way is simpler +- at this point the device is set up and ready for use so far as the USB + subsystem is concerned +- the device's probe() method is then called. It can send messages and do + whatever else it wants to make the device work. + +Note that the first device is always a root hub, and this must be scanned to +find any devices. The above steps will have created a hub (UCLASS_USB_HUB), +given it address 1 and set the configuration. + +For hubs, the hub uclass has a post_probe() method. This means that after +any hub is probed, the uclass gets to do some processing. In this case +usb_hub_post_probe() is called, and the following steps take place: + +- usb_hub_post_probe() calls usb_hub_scan() to scan the hub, which in turn + calls usb_hub_configure() +- hub power is enabled +- we loop through each port on the hub, performing the same steps for each +- first, check if there is a device present. This happens in + usb_hub_port_connect_change(). If so, then usb_scan_device() is called to + scan the device, passing the appropriate port number. +- you will recognise usb_scan_device() from the steps above. It sets up the + device ready for use. If it is a hub, it will scan that hub before it + continues here (recursively, depth-first) +- once all hub ports are scanned in this way, the hub is ready for use and + all of its downstream devices also +- additional controllers are scanned in the same way + +The above method has some nice properties: + +- the bus enumeration happens by virtue of driver model's natural device flow +- most logic is in the USB controller and hub uclasses; the actual device + drivers do not need to know they are on a USB bus, at least so far as + enumeration goes +- hub scanning happens automatically after a hub is probed + + +Hubs +---- + +USB hubs are scanned as in the section above. While hubs have their own +uclass, they share some common elements with controllers: + +- they both attach private data to their children (struct usb_device, + accessible for a child with dev_get_parent_priv(child)) +- they both use usb_child_pre_probe() to set up their children as proper USB + devices + + +Example - Mass Storage +---------------------- + +As an example of a USB device driver, see usb_storage.c. It uses its own +uclass and declares itself as follows: + +.. code-block:: c + + U_BOOT_DRIVER(usb_mass_storage) = { + .name = "usb_mass_storage", + .id = UCLASS_MASS_STORAGE, + .of_match = usb_mass_storage_ids, + .probe = usb_mass_storage_probe, + }; + + static const struct usb_device_id mass_storage_id_table[] = { + { .match_flags = USB_DEVICE_ID_MATCH_INT_CLASS, + .bInterfaceClass = USB_CLASS_MASS_STORAGE}, + { } /* Terminating entry */ + }; + + USB_DEVICE(usb_mass_storage, mass_storage_id_table); + +The USB_DEVICE() macro attaches the given table of matching information to +the given driver. Note that the driver is declared in U_BOOT_DRIVER() as +'usb_mass_storage' and this must match the first parameter of USB_DEVICE. + +When usb_find_and_bind_driver() is called on a USB device with the +bInterfaceClass value of USB_CLASS_MASS_STORAGE, it will automatically find +this driver and use it. + + +Counter-example: USB Ethernet +----------------------------- + +As an example of the old way of doing things, see usb_ether.c. When the bus +is scanned, all Ethernet devices will be created as generic USB devices (in +uclass UCLASS_USB_DEV_GENERIC). Then, when the scan is completed, +usb_host_eth_scan() will be called. This looks through all the devices on +each bus and manually figures out which are Ethernet devices in the ways of +yore. + +In fact, usb_ether should be moved to driver model. Each USB Ethernet driver +(e.g drivers/usb/eth/asix.c) should include a USB_DEVICE() declaration, so +that it will be found as part of normal USB enumeration. Then, instead of a +generic USB driver, a real (driver-model-aware) driver will be used. Since +Ethernet now supports driver model, this should be fairly easy to achieve, +and then usb_ether.c and the usb_host_eth_scan() will melt away. + + +Sandbox +------- + +All driver model uclasses must have tests and USB is no exception. To +achieve this, a sandbox USB controller is provided. This can make use of +emulation drivers which pretend to be USB devices. Emulations are provided +for a hub and a flash stick. These are enough to create a pretend USB bus +(defined by the sandbox device tree sandbox.dts) which can be scanned and +used. + +Tests in test/dm/usb.c make use of this feature. It allows much of the USB +stack to be tested without real hardware being needed. + +Here is an example device tree fragment: + +.. code-block:: none + + usb@1 { + compatible = "sandbox,usb"; + hub { + compatible = "usb-hub"; + usb,device-class = <USB_CLASS_HUB>; + hub-emul { + compatible = "sandbox,usb-hub"; + #address-cells = <1>; + #size-cells = <0>; + flash-stick { + reg = <0>; + compatible = "sandbox,usb-flash"; + sandbox,filepath = "flash.bin"; + }; + }; + }; + }; + +This defines a single controller, containing a root hub (which is required). +The hub is emulated by a hub emulator, and the emulated hub has a single +flash stick to emulate on one of its ports. + +When 'usb start' is used, the following 'dm tree' output will be available:: + + usb [ + ] `-- usb@1 + usb_hub [ + ] `-- hub + usb_emul [ + ] |-- hub-emul + usb_emul [ + ] | `-- flash-stick + usb_mass_st [ + ] `-- usb_mass_storage + + +This may look confusing. Most of it mirrors the device tree, but the +'usb_mass_storage' device is not in the device tree. This is created by +usb_find_and_bind_driver() based on the USB_DRIVER in usb_storage.c. While +'flash-stick' is the emulation device, 'usb_mass_storage' is the real U-Boot +USB device driver that talks to it. + + +Future work +----------- + +It is pretty uncommon to have a large USB bus with lots of hubs on an +embedded system. In fact anything other than a root hub is uncommon. Still +it would be possible to speed up enumeration in two ways: + +- breadth-first search would allow devices to be reset and probed in + parallel to some extent +- enumeration could be lazy, in the sense that we could enumerate just the + root hub at first, then only progress to the next 'level' when a device is + used that we cannot find. This could be made easier if the devices were + statically declared in the device tree (which is acceptable for production + boards where the same, known, things are on each bus). + +But in common cases the current algorithm is sufficient. + +Other things that need doing: +- Convert usb_ether to use driver model as described above +- Test that keyboards work (and convert to driver model) +- Move the USB gadget framework to driver model +- Implement OHCI in driver model +- Implement USB PHYs in driver model +- Work out a clever way to provide lazy init for USB devices + + +.. Simon Glass <sjg@chromium.org> +.. 23-Mar-15 diff --git a/roms/u-boot/doc/develop/driver-model/virtio.rst b/roms/u-boot/doc/develop/driver-model/virtio.rst new file mode 100644 index 000000000..8ac9c94ca --- /dev/null +++ b/roms/u-boot/doc/develop/driver-model/virtio.rst @@ -0,0 +1,287 @@ +.. SPDX-License-Identifier: GPL-2.0+ +.. sectionauthor:: Bin Meng <bmeng.cn@gmail.com> + +VirtIO Support +============== + +This document describes the information about U-Boot support for VirtIO_ +devices, including supported boards, build instructions, driver details etc. + +What's VirtIO? +-------------- +VirtIO is a virtualization standard for network and disk device drivers where +just the guest's device driver "knows" it is running in a virtual environment, +and cooperates with the hypervisor. This enables guests to get high performance +network and disk operations, and gives most of the performance benefits of +paravirtualization. In the U-Boot case, the guest is U-Boot itself, while the +virtual environment are normally QEMU_ targets like ARM, RISC-V and x86. + +Status +------ +VirtIO can use various different buses, aka transports as described in the +spec. While VirtIO devices are commonly implemented as PCI devices on x86, +embedded devices models like ARM/RISC-V, which does not normally come with +PCI support might use simple memory mapped device (MMIO) instead of the PCI +device. The memory mapped virtio device behaviour is based on the PCI device +specification. Therefore most operations including device initialization, +queues configuration and buffer transfers are nearly identical. Both MMIO +and PCI transport options are supported in U-Boot. + +The VirtIO spec defines a lots of VirtIO device types, however at present only +network and block device, the most two commonly used devices, are supported. + +The following QEMU targets are supported. + + - qemu_arm_defconfig + - qemu_arm64_defconfig + - qemu-riscv32_defconfig + - qemu-riscv64_defconfig + - qemu-x86_defconfig + - qemu-x86_64_defconfig + +Note ARM and RISC-V targets are configured with VirtIO MMIO transport driver, +and on x86 it's the PCI transport driver. + +Build Instructions +------------------ +Building U-Boot for pre-configured QEMU targets is no different from others. +For example, we can do the following with the CROSS_COMPILE environment +variable being properly set to a working toolchain for ARM: + +.. code-block:: bash + + $ make qemu_arm_defconfig + $ make + +You can even create a QEMU ARM target with VirtIO devices showing up on both +MMIO and PCI buses. In this case, you can enable the PCI transport driver +from 'make menuconfig': + +.. code-block:: none + + Device Drivers ---> + ... + VirtIO Drivers ---> + ... + [*] PCI driver for virtio devices + +Other drivers are at the same location and can be tuned to suit the needs. + +Requirements +------------ +It is required that QEMU v2.5.0+ should be used to test U-Boot VirtIO support +on QEMU ARM and x86, and v2.12.0+ on QEMU RISC-V. + +Testing +------- +The following QEMU command line is used to get U-Boot up and running with +VirtIO net and block devices on ARM. + +.. code-block:: bash + + $ qemu-system-arm -nographic -machine virt -bios u-boot.bin \ + -netdev tap,ifname=tap0,id=net0 \ + -device virtio-net-device,netdev=net0 \ + -drive if=none,file=test.img,format=raw,id=hd0 \ + -device virtio-blk-device,drive=hd0 + +On x86, command is slightly different to create PCI VirtIO devices. + +.. code-block:: bash + + $ qemu-system-i386 -nographic -bios u-boot.rom \ + -netdev tap,ifname=tap0,id=net0 \ + -device virtio-net-pci,netdev=net0 \ + -drive if=none,file=test.img,format=raw,id=hd0 \ + -device virtio-blk-pci,drive=hd0 + +Additional net and block devices can be created by appending more '-device' +parameters. It is also possible to specify both MMIO and PCI VirtIO devices. +For example, the following commnad creates 3 VirtIO devices, with 1 on MMIO +and 2 on PCI bus. + +.. code-block:: bash + + $ qemu-system-arm -nographic -machine virt -bios u-boot.bin \ + -netdev tap,ifname=tap0,id=net0 \ + -device virtio-net-pci,netdev=net0 \ + -drive if=none,file=test0.img,format=raw,id=hd0 \ + -device virtio-blk-device,drive=hd0 \ + -drive if=none,file=test1.img,format=raw,id=hd1 \ + -device virtio-blk-pci,drive=hd1 + +By default QEMU creates VirtIO legacy devices by default. To create non-legacy +(aka modern) devices, pass additional device property/value pairs like below: + +.. code-block:: bash + + $ qemu-system-i386 -nographic -bios u-boot.rom \ + -netdev tap,ifname=tap0,id=net0 \ + -device virtio-net-pci,netdev=net0,disable-legacy=true,disable-modern=false \ + -drive if=none,file=test.img,format=raw,id=hd0 \ + -device virtio-blk-pci,drive=hd0,disable-legacy=true,disable-modern=false + +A 'virtio' command is provided in U-Boot shell. + +.. code-block:: none + + => virtio + virtio - virtio block devices sub-system + + Usage: + virtio scan - initialize virtio bus + virtio info - show all available virtio block devices + virtio device [dev] - show or set current virtio block device + virtio part [dev] - print partition table of one or all virtio block devices + virtio read addr blk# cnt - read `cnt' blocks starting at block + `blk#' to memory address `addr' + virtio write addr blk# cnt - write `cnt' blocks starting at block + `blk#' from memory address `addr' + +To probe all the VirtIO devices, type: + +.. code-block:: none + + => virtio scan + +Then we can show the connected block device details by: + +.. code-block:: none + + => virtio info + Device 0: QEMU VirtIO Block Device + Type: Hard Disk + Capacity: 4096.0 MB = 4.0 GB (8388608 x 512) + +And list the directories and files on the disk by: + +.. code-block:: none + + => ls virtio 0 / + <DIR> 4096 . + <DIR> 4096 .. + <DIR> 16384 lost+found + <DIR> 4096 dev + <DIR> 4096 proc + <DIR> 4096 sys + <DIR> 4096 var + <DIR> 4096 etc + <DIR> 4096 usr + <SYM> 7 bin + <SYM> 8 sbin + <SYM> 7 lib + <SYM> 9 lib64 + <DIR> 4096 run + <DIR> 4096 boot + <DIR> 4096 home + <DIR> 4096 media + <DIR> 4096 mnt + <DIR> 4096 opt + <DIR> 4096 root + <DIR> 4096 srv + <DIR> 4096 tmp + 0 .autorelabel + +Driver Internals +---------------- +There are 3 level of drivers in the VirtIO driver family. + +.. code-block:: none + + +---------------------------------------+ + | virtio device drivers | + | +-------------+ +------------+ | + | | virtio-net | | virtio-blk | | + | +-------------+ +------------+ | + +---------------------------------------+ + +---------------------------------------+ + | virtio transport drivers | + | +-------------+ +------------+ | + | | virtio-mmio | | virtio-pci | | + | +-------------+ +------------+ | + +---------------------------------------+ + +----------------------+ + | virtio uclass driver | + +----------------------+ + +The root one is the virtio uclass driver (virtio-uclass.c), which does lots of +common stuff for the transport drivers (virtio_mmio.c, virtio_pci.c). The real +virtio device is discovered in the transport driver's probe() method, and its +device ID is saved in the virtio uclass's private data of the transport device. +Then in the virtio uclass's post_probe() method, the real virtio device driver +(virtio_net.c, virtio_blk.c) is bound if there is a match on the device ID. + +The child_post_bind(), child_pre_probe() and child_post_probe() methods of the +virtio uclass driver help bring the virtio device driver online. They do things +like acknowledging device, feature negotiation, etc, which are really common +for all virtio devices. + +The transport drivers provide a set of ops (struct dm_virtio_ops) for the real +virtio device driver to call. These ops APIs's parameter is designed to remind +the caller to pass the correct 'struct udevice' id of the virtio device, eg: + +.. code-block:: C + + int virtio_get_status(struct udevice *vdev, u8 *status) + +So the parameter 'vdev' indicates the device should be the real virtio device. +But we also have an API like: + +.. code-block:: C + + struct virtqueue *vring_create_virtqueue(unsigned int index, unsigned int num, + unsigned int vring_align, + struct udevice *udev) + +Here the parameter 'udev' indicates the device should be the transport device. +Similar naming is applied in other functions that are even not APIs, eg: + +.. code-block:: C + + static int virtio_uclass_post_probe(struct udevice *udev) + static int virtio_uclass_child_pre_probe(struct udevice *vdev) + +So it's easy to tell which device these functions are operating on. + +Development Flow +---------------- +At present only VirtIO network card (device ID 1) and block device (device +ID 2) are supported. If you want to develop new driver for new devices, +please follow the guideline below. + +1. add new device ID in virtio.h + +.. code-block:: C + + #define VIRTIO_ID_XXX X + +2. update VIRTIO_ID_MAX_NUM to be the largest device ID plus 1 + +3. add new driver name string in virtio.h + +.. code-block:: C + + #define VIRTIO_XXX_DRV_NAME "virtio-xxx" + +4. create a new driver with name set to the name string above + +.. code-block:: C + + U_BOOT_DRIVER(virtio_xxx) = { + .name = VIRTIO_XXX_DRV_NAME, + ... + .remove = virtio_reset, + .flags = DM_FLAG_ACTIVE_DMA, + } + +Note the driver needs to provide the remove method and normally this can be +hooked to virtio_reset(). The driver flags should contain DM_FLAG_ACTIVE_DMA +for the remove method to be called before jumping to OS. + +5. provide bind() method in the driver, where virtio_driver_features_init() + should be called for driver to negotiate feature support with the device. + +6. do funny stuff with the driver + +.. _VirtIO: http://docs.oasis-open.org/virtio/virtio/v1.0/virtio-v1.0.pdf +.. _QEMU: https://www.qemu.org diff --git a/roms/u-boot/doc/develop/global_data.rst b/roms/u-boot/doc/develop/global_data.rst new file mode 100644 index 000000000..230ebcd86 --- /dev/null +++ b/roms/u-boot/doc/develop/global_data.rst @@ -0,0 +1,55 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +Global data +=========== + +Globally required fields are held in the global data structure. A pointer to the +structure is available as symbol gd. The symbol is made available by the macro +%DECLARE_GLOBAL_DATA_PTR. + +Register pointing to global data +-------------------------------- + +On most architectures the global data pointer is stored in a register. + ++------------+----------+ +| ARC | r25 | ++------------+----------+ +| ARM 32bit | r9 | ++------------+----------+ +| ARM 64bit | x18 | ++------------+----------+ +| M68000 | d7 | ++------------+----------+ +| MicroBlaze | r31 | ++------------+----------+ +| NDS32 | r10 | ++------------+----------+ +| Nios II | gp | ++------------+----------+ +| PowerPC | r2 | ++------------+----------+ +| RISC-V | gp (x3) | ++------------+----------+ +| SuperH | r13 | ++------------+----------+ +| x86 32bit | fs | ++------------+----------+ + +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 +to the code size. + +Binaries called by U-Boot are not aware of the register usage and will not +conserve gd. UEFI binaries call the API provided by U-Boot and may return to +U-Boot. The value of gd has to be saved every time U-Boot is left and restored +whenever U-Boot is reentered. This is also relevant for the implementation of +function tracing. For setting the value of gd function set_gd() can be used. + +Global data structure +--------------------- + +.. kernel-doc:: include/asm-generic/global_data.h + :internal: diff --git a/roms/u-boot/doc/develop/index.rst b/roms/u-boot/doc/develop/index.rst new file mode 100644 index 000000000..3edffbc63 --- /dev/null +++ b/roms/u-boot/doc/develop/index.rst @@ -0,0 +1,47 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +Develop U-Boot +============== + +Implementation +-------------- + +.. toctree:: + :maxdepth: 1 + + commands + driver-model/index + global_data + logging + menus + uefi/index + version + +Debugging +--------- + +.. toctree:: + :maxdepth: 1 + + crash_dumps + trace + +Packaging +--------- + +.. toctree:: + :maxdepth: 1 + + package/index + +Testing +------- + +.. toctree:: + :maxdepth: 1 + + coccinelle + testing + py_testing + tests_writing + tests_sandbox diff --git a/roms/u-boot/doc/develop/logging.rst b/roms/u-boot/doc/develop/logging.rst new file mode 100644 index 000000000..f4e925048 --- /dev/null +++ b/roms/u-boot/doc/develop/logging.rst @@ -0,0 +1,319 @@ +.. SPDX-License-Identifier: GPL-2.0+ +.. Copyright (c) 2017 Simon Glass <sjg@chromium.org> + +Logging in U-Boot +================= + +Introduction +------------ + +U-Boot's internal operation involves many different steps and actions. From +setting up the board to displaying a start-up screen to loading an Operating +System, there are many component parts each with many actions. + +Most of the time this internal detail is not useful. Displaying it on the +console would delay booting (U-Boot's primary purpose) and confuse users. + +But for digging into what is happening in a particular area, or for debugging +a problem it is often useful to see what U-Boot is doing in more detail than +is visible from the basic console output. + +U-Boot's logging feature aims to satisfy this goal for both users and +developers. + +Logging levels +-------------- + +There are a number logging levels available. + +See enum :c:type:`log_level_t` + +Logging category +---------------- + +Logging can come from a wide variety of places within U-Boot. Each log message +has a category which is intended to allow messages to be filtered according to +their source. + +See enum :c:type:`log_category_t` + +Enabling logging +---------------- + +The following options are used to enable logging at compile time: + +* CONFIG_LOG - Enables the logging system +* CONFIG_LOG_MAX_LEVEL - Max log level to build (anything higher is compiled + out) +* CONFIG_LOG_CONSOLE - Enable writing log records to the console + +If CONFIG_LOG is not set, then no logging will be available. + +The above have SPL and TPL versions also, e.g. CONFIG_SPL_LOG_MAX_LEVEL and +CONFIG_TPL_LOG_MAX_LEVEL. + +Temporary logging within a single file +-------------------------------------- + +Sometimes it is useful to turn on logging just in one file. You can use this + +.. code-block:: c + + #define LOG_DEBUG + +to enable building in of all logging statements in a single file. Put it at +the top of the file, before any #includes. + +To actually get U-Boot to output this you need to also set the default logging +level - e.g. set CONFIG_LOG_DEFAULT_LEVEL to 7 (:c:data:`LOGL_DEBUG`) or more. +Otherwise debug output is suppressed and will not be generated. + +Using DEBUG +----------- + +U-Boot has traditionally used a #define called DEBUG to enable debugging on a +file-by-file basis. The debug() macro compiles to a printf() statement if +DEBUG is enabled, and an empty statement if not. + +With logging enabled, debug() statements are interpreted as logging output +with a level of LOGL_DEBUG and a category of LOGC_NONE. + +The logging facilities are intended to replace DEBUG, but if DEBUG is defined +at the top of a file, then it takes precedence. This means that debug() +statements will result in output to the console and this output will not be +logged. + +Logging statements +------------------ + +The main logging function is: + +.. code-block:: c + + log(category, level, format_string, ...) + +Also debug() and error() will generate log records - these use LOG_CATEGORY +as the category, so you should #define this right at the top of the source +file to ensure the category is correct. + +Generally each log format_string ends with a newline. If it does not, then the +next log statement will have the LOGRECF_CONT flag set. This can be used to +continue the statement on the same line as the previous one without emitting +new header information (such as category/level). This behaviour is implemented +with log_console. Here is an example that prints a list all on one line with +the tags at the start: + +.. code-block:: c + + log_debug("Here is a list:"); + for (i = 0; i < count; i++) + log_debug(" item %d", i); + log_debug("\n"); + +Also see the special category LOGL_CONT and level LOGC_CONT. + +You can also define CONFIG_LOG_ERROR_RETURN to enable the log_ret() macro. This +can be used whenever your function returns an error value: + +.. code-block:: c + + return log_ret(uclass_first_device_err(UCLASS_MMC, &dev)); + +This will write a log record when an error code is detected (a value < 0). This +can make it easier to trace errors that are generated deep in the call stack. + +The log_msg_ret() variant will print a short string if CONFIG_LOG_ERROR_RETURN +is enabled. So long as the string is unique within the function you can normally +determine exactly which call failed: + +.. code-block:: c + + ret = gpio_request_by_name(dev, "cd-gpios", 0, &desc, GPIOD_IS_IN); + if (ret) + return log_msg_ret("gpio", ret); + +Some functions return 0 for success and any other value is an error. For these, +log_retz() and log_msg_retz() are available. + +Convenience functions +~~~~~~~~~~~~~~~~~~~~~ + +A number of convenience functions are available to shorten the code needed +for logging: + +* log_err(_fmt...) +* log_warning(_fmt...) +* log_notice(_fmt...) +* log_info(_fmt...) +* log_debug(_fmt...) +* log_content(_fmt...) +* log_io(_fmt...) + +With these the log level is implicit in the name. The category is set by +LOG_CATEGORY, which you can only define once per file, above all #includes, e.g. + +.. code-block:: c + + #define LOG_CATEGORY LOGC_ALLOC + +or + +.. code-block:: c + + #define LOG_CATEGORY UCLASS_SPI + +Remember that all uclasses IDs are log categories too. + +Logging destinations +-------------------- + +If logging information goes nowhere then it serves no purpose. U-Boot provides +several possible determinations for logging information, all of which can be +enabled or disabled independently: + +* console - goes to stdout +* syslog - broadcast RFC 3164 messages to syslog servers on UDP port 514 + +The syslog driver sends the value of environmental variable 'log_hostname' as +HOSTNAME if available. + +Filters +------- + +Filters are attached to log drivers to control what those drivers emit. FIlters +can either allow or deny a log message when they match it. Only records which +are allowed by a filter make it to the driver. + +Filters can be based on several criteria: + +* minimum or maximum log level +* in a set of categories +* in a set of files + +If no filters are attached to a driver then a default filter is used, which +limits output to records with a level less than CONFIG_MAX_LOG_LEVEL. + +Log command +----------- + +The 'log' command provides access to several features: + +* level - list log levels or set the default log level +* categories - list log categories +* drivers - list log drivers +* filter-list - list filters +* filter-add - add a new filter +* filter-remove - remove filters +* format - access the console log format +* rec - output a log record + +Type 'help log' for details. + +Log format +~~~~~~~~~~ + +You can control the log format using the 'log format' command. The basic +format is:: + + LEVEL.category,file.c:123-func() message + +In the above, file.c:123 is the filename where the log record was generated and +func() is the function name. By default ('log format default') only the message +is displayed on the console. You can control which fields are present, but not +the field order. + +Adding Filters +~~~~~~~~~~~~~~ + +To add new filters at runtime, use the 'log filter-add' command. For example, to +suppress messages from the SPI and MMC subsystems, run:: + + log filter-add -D -c spi -c mmc + +You will also need to add another filter to allow other messages (because the +default filter no longer applies):: + + log filter-add -A -l info + +Log levels may be either symbolic names (like above) or numbers. For example, to +disable all debug and above (log level 7) messages from ``drivers/core/lists.c`` +and ``drivers/core/ofnode.c``, run:: + + log filter-add -D -f drivers/core/lists.c,drivers/core/ofnode.c -L 7 + +To view active filters, use the 'log filter-list' command. Some example output +is:: + + => log filter-list + num policy level categories files + 2 deny >= DEBUG drivers/core/lists.c,drivers/core/ofnode.c + 0 deny <= IO spi + mmc + 1 allow <= INFO + +Note that filters are processed in-order from top to bottom, not in the order of +their filter number. Filters are added to the top of the list if they deny when +they match, and to the bottom if they allow when they match. For more +information, consult the usage of the 'log' command, by running 'help log'. + +Code size +--------- + +Code size impact depends largely on what is enabled. The following numbers are +generated by 'buildman -S' for snow, which is a Thumb-2 board (all units in +bytes):: + + This series: adds bss +20.0 data +4.0 rodata +4.0 text +44.0 + CONFIG_LOG: bss -52.0 data +92.0 rodata -635.0 text +1048.0 + CONFIG_LOG_MAX_LEVEL=7: bss +188.0 data +4.0 rodata +49183.0 text +98124.0 + +The last option turns every debug() statement into a logging call, which +bloats the code hugely. The advantage is that it is then possible to enable +all logging within U-Boot. + +To Do +----- + +There are lots of useful additions that could be made. None of the below is +implemented! If you do one, please add a test in test/log/log_test.c +log filter-add -D -f drivers/core/lists.c,drivers/core/ofnode.c -l 6 +Convenience functions to support setting the category: + +* log_arch(level, format_string, ...) - category LOGC_ARCH +* log_board(level, format_string, ...) - category LOGC_BOARD +* log_core(level, format_string, ...) - category LOGC_CORE +* log_dt(level, format_string, ...) - category LOGC_DT + +More logging destinations: + +* device - goes to a device (e.g. serial) +* buffer - recorded in a memory buffer + +Convert debug() statements in the code to log() statements + +Support making printf() emit log statements at L_INFO level + +Convert error() statements in the code to log() statements + +Figure out what to do with BUG(), BUG_ON() and warn_non_spl() + +Add a way to browse log records + +Add a way to record log records for browsing using an external tool + +Add commands to add and remove log devices + +Allow sharing of printf format strings in log records to reduce storage size +for large numbers of log records + +Consider making log() calls emit an automatic newline, perhaps with a logn() +function to avoid that + +Passing log records through to linux (e.g. via device tree /chosen) + +Provide a command to access the number of log records generated, and the +number dropped due to them being generated before the log system was ready. + +Add a printf() format string pragma so that log statements are checked properly + +Add a command to delete existing log records. diff --git a/roms/u-boot/doc/develop/menus.rst b/roms/u-boot/doc/develop/menus.rst new file mode 100644 index 000000000..dda8f963f --- /dev/null +++ b/roms/u-boot/doc/develop/menus.rst @@ -0,0 +1,131 @@ +.. SPDX-License-Identifier: GPL-2.0+ +.. Copyright 2010-2011 Calxeda, Inc. + +Menus +===== + +U-Boot provides a set of interfaces for creating and using simple, text +based menus. Menus are displayed as lists of labeled entries on the +console, and an entry can be selected by entering its label. + +To use the menu code, enable CONFIG_MENU, and include "menu.h" where +the interfaces should be available. + +Menus are composed of items. Each item has a key used to identify it in +the menu, and an opaque pointer to data controlled by the consumer. + +If you want to show a menu, instead starting the shell, define +CONFIG_AUTOBOOT_MENU_SHOW. You have to code the int menu_show(int bootdelay) +function, which handle your menu. This function returns the remaining +bootdelay. + +Interfaces +---------- + +.. code-block:: c + + #include "menu.h" + + /* + * Consumers of the menu interfaces will use a struct menu * as the + * handle for a menu. struct menu is only fully defined in menu.c, + * preventing consumers of the menu interfaces from accessing its + * contents directly. + */ + struct menu; + + /* + * NOTE: See comments in common/menu.c for more detailed documentation on + * these interfaces. + */ + + /* + * menu_create() - Creates a menu handle with default settings + */ + struct menu *menu_create(char *title, int timeout, int prompt, + void (*item_data_print)(void *), + char *(*item_choice)(void *), + void *item_choice_data); + + /* + * menu_item_add() - Adds or replaces a menu item + */ + int menu_item_add(struct menu *m, char *item_key, void *item_data); + + /* + * menu_default_set() - Sets the default choice for the menu + */ + int menu_default_set(struct menu *m, char *item_key); + + /* + * menu_default_choice() - Set *choice to point to the default item's data + */ + int menu_default_choice(struct menu *m, void **choice); + + /* + * menu_get_choice() - Returns the user's selected menu entry, or the + * default if the menu is set to not prompt or the timeout expires. + */ + int menu_get_choice(struct menu *m, void **choice); + + /* + * menu_destroy() - frees the memory used by a menu and its items. + */ + int menu_destroy(struct menu *m); + + /* + * menu_display_statusline(struct menu *m); + * shows a statusline for every menu_display call. + */ + void menu_display_statusline(struct menu *m); + +Example Code +------------ + +This example creates a menu that always prompts, and allows the user +to pick from a list of tools. The item key and data are the same. + +.. code-block:: c + + #include "menu.h" + + char *tools[] = { + "Hammer", + "Screwdriver", + "Nail gun", + NULL + }; + + char *pick_a_tool(void) + { + struct menu *m; + int i; + char *tool = NULL; + + m = menu_create("Tools", 0, 1, NULL); + + for(i = 0; tools[i]; i++) { + if (menu_item_add(m, tools[i], tools[i]) != 1) { + printf("failed to add item!"); + menu_destroy(m); + return NULL; + } + } + + if (menu_get_choice(m, (void **)&tool) != 1) + printf("Problem picking tool!\n"); + + menu_destroy(m); + + return tool; + } + + void caller(void) + { + char *tool = pick_a_tool(); + + if (tool) { + printf("picked a tool: %s\n", tool); + use_tool(tool); + } + } diff --git a/roms/u-boot/doc/develop/package/binman.rst b/roms/u-boot/doc/develop/package/binman.rst new file mode 120000 index 000000000..2e26e84b7 --- /dev/null +++ b/roms/u-boot/doc/develop/package/binman.rst @@ -0,0 +1 @@ +../../../tools/binman/binman.rst
\ No newline at end of file diff --git a/roms/u-boot/doc/develop/package/entries.rst b/roms/u-boot/doc/develop/package/entries.rst new file mode 120000 index 000000000..ecedcebaa --- /dev/null +++ b/roms/u-boot/doc/develop/package/entries.rst @@ -0,0 +1 @@ +../../../tools/binman/entries.rst
\ No newline at end of file diff --git a/roms/u-boot/doc/develop/package/index.rst b/roms/u-boot/doc/develop/package/index.rst new file mode 100644 index 000000000..9374be2e6 --- /dev/null +++ b/roms/u-boot/doc/develop/package/index.rst @@ -0,0 +1,19 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +Package U-Boot +============== + +U-Boot uses Flat Image Tree (FIT) as a standard file format for packaging +images that it it reads and boots. Documentation about FIT is available at +doc/uImage.FIT + +U-Boot also provides binman for cases not covered by FIT. Examples include +initial execution (since FIT itself does not have an executable header) and +dealing with device boundaries, such as the read-only/read-write separation in +SPI flash. + + +.. toctree:: + :maxdepth: 2 + + binman diff --git a/roms/u-boot/doc/develop/py_testing.rst b/roms/u-boot/doc/develop/py_testing.rst new file mode 100644 index 000000000..c4cecc0a0 --- /dev/null +++ b/roms/u-boot/doc/develop/py_testing.rst @@ -0,0 +1,427 @@ +U-Boot pytest suite +=================== + +Introduction +------------ + +This tool aims to test U-Boot by executing U-Boot shell commands using the +console interface. A single top-level script exists to execute or attach to the +U-Boot console, run the entire script of tests against it, and summarize the +results. Advantages of this approach are: + +- Testing is performed in the same way a user or script would interact with + U-Boot; there can be no disconnect. +- There is no need to write or embed test-related code into U-Boot itself. + It is asserted that writing test-related code in Python is simpler and more + flexible than writing it all in C. But see :doc:`tests_writing` for caveats + and more discussion / analysis. +- It is reasonably simple to interact with U-Boot in this way. + +Requirements +------------ + +The test suite is implemented using pytest. Interaction with the U-Boot console +involves executing some binary and interacting with its stdin/stdout. You will +need to implement various "hook" scripts that are called by the test suite at +the appropriate time. + +In order to run the test suite at a minimum we require that both Python 3 and +pip for Python 3 are installed. All of the required python modules are +described in the requirements.txt file in the /test/py/ directory and can be +installed via the command + +.. code-block:: bash + + pip install -r requirements.txt + +In order to execute certain tests on their supported platforms other tools +will be required. The following is an incomplete list: + +* gdisk +* dfu-util +* dtc +* openssl +* sudo OR guestmount +* e2fsprogs +* util-linux +* coreutils +* dosfstools +* efitools +* mount +* mtools +* sbsigntool +* udisks2 + +Please use the appropriate commands for your distribution to match these tools +up with the package that provides them. + +The test script supports either: + +- Executing a sandbox port of U-Boot on the local machine as a sub-process, + and interacting with it over stdin/stdout. +- Executing an external "hook" scripts to flash a U-Boot binary onto a + physical board, attach to the board's console stream, and reset the board. + Further details are described later. + +Using `virtualenv` to provide requirements +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The recommended way to run the test suite, in order to ensure reproducibility +is to use `virtualenv` to set up the necessary environment. This can be done +via the following commands: + + +.. code-block:: console + + $ cd /path/to/u-boot + $ sudo apt-get install python3 python3-virtualenv + $ virtualenv -p /usr/bin/python3 venv + $ . ./venv/bin/activate + $ pip install -r test/py/requirements.txt + +Testing sandbox +--------------- + +To run the test suite on the sandbox port (U-Boot built as a native user-space +application), simply execute: + +.. code-block:: bash + + ./test/py/test.py --bd sandbox --build + +The `--bd` option tells the test suite which board type is being tested. This +lets the test suite know which features the board has, and hence exactly what +can be tested. + +The `--build` option tells U-Boot to compile U-Boot. Alternatively, you may +omit this option and build U-Boot yourself, in whatever way you choose, before +running the test script. + +The test script will attach to U-Boot, execute all valid tests for the board, +then print a summary of the test process. A complete log of the test session +will be written to `${build_dir}/test-log.html`. This is best viewed in a web +browser, but may be read directly as plain text, perhaps with the aid of the +`html2text` utility. + +Testing under a debugger +~~~~~~~~~~~~~~~~~~~~~~~~ + +If you need to run sandbox under a debugger, you may pass the command-line +option `--gdbserver COMM`. This causes two things to happens: + +- Instead of running U-Boot directly, it will be run under gdbserver, with + debug communication via the channel `COMM`. You can attach a debugger to the + sandbox process in order to debug it. See `man gdbserver` and the example + below for details of valid values for `COMM`. +- All timeouts in tests are disabled, allowing U-Boot an arbitrary amount of + time to execute commands. This is useful if U-Boot is stopped at a breakpoint + during debugging. + +A usage example is: + +Window 1: + +.. code-block:: bash + + ./test/py/test.py --bd sandbox --gdbserver localhost:1234 + +Window 2: + +.. code-block:: bash + + gdb ./build-sandbox/u-boot -ex 'target remote localhost:1234' + +Alternatively, you could leave off the `-ex` option and type the command +manually into gdb once it starts. + +You can use any debugger you wish, as long as it speaks the gdb remote +protocol, or any graphical wrapper around gdb. + +Some tests deliberately cause the sandbox process to exit, e.g. to test the +reset command, or sandbox's CTRL-C handling. When this happens, you will need +to attach the debugger to the new sandbox instance. If these tests are not +relevant to your debugging session, you can skip them using pytest's -k +command-line option; see the next section. + +Command-line options +-------------------- + +--board-type, --bd, -B + set the type of the board to be tested. For example, `sandbox` or `seaboard`. + +--board-identity`, --id + sets the identity of the board to be tested. This allows differentiation + between multiple instances of the same type of physical board that are + attached to the same host machine. This parameter is not interpreted by th + test script in any way, but rather is simply passed to the hook scripts + described below, and may be used in any site-specific way deemed necessary. + +--build + indicates that the test script should compile U-Boot itself before running + the tests. If using this option, make sure that any environment variables + required by the build process are already set, such as `$CROSS_COMPILE`. + +--buildman + indicates that `--build` should use buildman to build U-Boot. There is no need + to set $CROSS_COMPILE` in this case since buildman handles it. + +--build-dir + sets the directory containing the compiled U-Boot binaries. If omitted, this + is `${source_dir}/build-${board_type}`. + +--result-dir + sets the directory to write results, such as log files, into. + If omitted, the build directory is used. + +--persistent-data-dir + sets the directory used to store persistent test data. This is test data that + may be re-used across test runs, such as file-system images. + +`pytest` also implements a number of its own command-line options. Commonly used +options are mentioned below. Please see `pytest` documentation for complete +details. Execute `py.test --version` for a brief summary. Note that U-Boot's +test.py script passes all command-line arguments directly to `pytest` for +processing. + +-k + selects which tests to run. The default is to run all known tests. This + option takes a single argument which is used to filter test names. Simple + logical operators are supported. For example: + + - `'-k ums'` runs only tests with "ums" in their name. + - `'-k ut_dm'` runs only tests with "ut_dm" in their name. Note that in this + case, "ut_dm" is a parameter to a test rather than the test name. The full + test name is e.g. "test_ut[ut_dm_leak]". + - `'-k not reset'` runs everything except tests with "reset" in their name. + - `'-k ut or hush'` runs only tests with "ut" or "hush" in their name. + - `'-k not (ut or hush)'` runs everything except tests with "ut" or "hush" in + their name. + +-s + prevents pytest from hiding a test's stdout. This allows you to see + U-Boot's console log in real time on pytest's stdout. + +Testing real hardware +--------------------- + +The tools and techniques used to interact with real hardware will vary +radically between different host and target systems, and the whims of the user. +For this reason, the test suite does not attempt to directly interact with real +hardware in any way. Rather, it executes a standardized set of "hook" scripts +via `$PATH`. These scripts implement certain actions on behalf of the test +suite. This keeps the test suite simple and isolated from system variances +unrelated to U-Boot features. + +Hook scripts +~~~~~~~~~~~~ + +Environment variables +''''''''''''''''''''' + +The following environment variables are set when running hook scripts: + +- `UBOOT_BOARD_TYPE` the board type being tested. +- `UBOOT_BOARD_IDENTITY` the board identity being tested, or `na` if none was + specified. +- `UBOOT_SOURCE_DIR` the U-Boot source directory. +- `UBOOT_TEST_PY_DIR` the full path to `test/py/` in the source directory. +- `UBOOT_BUILD_DIR` the U-Boot build directory. +- `UBOOT_RESULT_DIR` the test result directory. +- `UBOOT_PERSISTENT_DATA_DIR` the test persistent data directory. + +u-boot-test-console +''''''''''''''''''' + +This script provides access to the U-Boot console. The script's stdin/stdout +should be connected to the board's console. This process should continue to run +indefinitely, until killed. The test suite will run this script in parallel +with all other hooks. + +This script may be implemented e.g. by executing `cu`, `kermit`, `conmux`, etc. +via exec(). + +If you are able to run U-Boot under a hardware simulator such as QEMU, then +you would likely spawn that simulator from this script. However, note that +`u-boot-test-reset` may be called multiple times per test script run, and must +cause U-Boot to start execution from scratch each time. Hopefully your +simulator includes a virtual reset button! If not, you can launch the +simulator from `u-boot-test-reset` instead, while arranging for this console +process to always communicate with the current simulator instance. + +u-boot-test-flash +''''''''''''''''' + +Prior to running the test suite against a board, some arrangement must be made +so that the board executes the particular U-Boot binary to be tested. Often +this involves writing the U-Boot binary to the board's flash ROM. The test +suite calls this hook script for that purpose. + +This script should perform the entire flashing process synchronously; the +script should only exit once flashing is complete, and a board reset will +cause the newly flashed U-Boot binary to be executed. + +It is conceivable that this script will do nothing. This might be useful in +the following cases: + +- Some other process has already written the desired U-Boot binary into the + board's flash prior to running the test suite. +- The board allows U-Boot to be downloaded directly into RAM, and executed + from there. Use of this feature will reduce wear on the board's flash, so + may be preferable if available, and if cold boot testing of U-Boot is not + required. If this feature is used, the `u-boot-test-reset` script should + perform this download, since the board could conceivably be reset multiple + times in a single test run. + +It is up to the user to determine if those situations exist, and to code this +hook script appropriately. + +This script will typically be implemented by calling out to some SoC- or +board-specific vendor flashing utility. + +u-boot-test-reset +''''''''''''''''' + +Whenever the test suite needs to reset the target board, this script is +executed. This is guaranteed to happen at least once, prior to executing the +first test function. If any test fails, the test infra-structure will execute +this script again to restore U-Boot to an operational state before running the +next test function. + +This script will likely be implemented by communicating with some form of +relay or electronic switch attached to the board's reset signal. + +The semantics of this script require that when it is executed, U-Boot will +start running from scratch. If the U-Boot binary to be tested has been written +to flash, pulsing the board's reset signal is likely all this script needs to +do. However, in some scenarios, this script may perform other actions. For +example, it may call out to some SoC- or board-specific vendor utility in order +to download the U-Boot binary directly into RAM and execute it. This would +avoid the need for `u-boot-test-flash` to actually write U-Boot to flash, thus +saving wear on the flash chip(s). + +Examples +'''''''' + +https://source.denx.de/u-boot/u-boot-test-hooks contains some working example hook +scripts, and may be useful as a reference when implementing hook scripts for +your platform. These scripts are not considered part of U-Boot itself. + +Board-type-specific configuration +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Each board has a different configuration and behaviour. Many of these +differences can be automatically detected by parsing the `.config` file in the +build directory. However, some differences can't yet be handled automatically. + +For each board, an optional Python module `u_boot_board_${board_type}` may exist +to provide board-specific information to the test script. Any global value +defined in these modules is available for use by any test function. The data +contained in these scripts must be purely derived from U-Boot source code. +Hence, these configuration files are part of the U-Boot source tree too. + +Execution environment configuration +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Each user's hardware setup may enable testing different subsets of the features +implemented by a particular board's configuration of U-Boot. For example, a +U-Boot configuration may support USB device mode and USB Mass Storage, but this +can only be tested if a USB cable is connected between the board and the host +machine running the test script. + +For each board, optional Python modules `u_boot_boardenv_${board_type}` and +`u_boot_boardenv_${board_type}_${board_identity}` may exist to provide +board-specific and board-identity-specific information to the test script. Any +global value defined in these modules is available for use by any test +function. The data contained in these is specific to a particular user's +hardware configuration. Hence, these configuration files are not part of the +U-Boot source tree, and should be installed outside of the source tree. Users +should set `$PYTHONPATH` prior to running the test script to allow these +modules to be loaded. + +Board module parameter usage +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The test scripts rely on the following variables being defined by the board +module: + +- none at present + +U-Boot `.config` feature usage +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The test scripts rely on various U-Boot `.config` features, either directly in +order to test those features, or indirectly in order to query information from +the running U-Boot instance in order to test other features. + +One example is that testing of the `md` command requires knowledge of a RAM +address to use for the test. This data is parsed from the output of the +`bdinfo` command, and hence relies on CONFIG_CMD_BDI being enabled. + +For a complete list of dependencies, please search the test scripts for +instances of: + +- `buildconfig.get(...` +- `@pytest.mark.buildconfigspec(...` +- `@pytest.mark.notbuildconfigspec(...` + +Complete invocation example +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Assuming that you have installed the hook scripts into $HOME/ubtest/bin, and +any required environment configuration Python modules into $HOME/ubtest/py, +then you would likely invoke the test script as follows: + +If U-Boot has already been built: + +.. code-block:: bash + + PATH=$HOME/ubtest/bin:$PATH \ + PYTHONPATH=${HOME}/ubtest/py/${HOSTNAME}:${PYTHONPATH} \ + ./test/py/test.py --bd seaboard + +If you want the test script to compile U-Boot for you too, then you likely +need to set `$CROSS_COMPILE` to allow this, and invoke the test script as +follows: + +.. code-block:: bash + + CROSS_COMPILE=arm-none-eabi- \ + PATH=$HOME/ubtest/bin:$PATH \ + PYTHONPATH=${HOME}/ubtest/py/${HOSTNAME}:${PYTHONPATH} \ + ./test/py/test.py --bd seaboard --build + +or, using buildman to handle it: + +.. code-block:: bash + + PATH=$HOME/ubtest/bin:$PATH \ + PYTHONPATH=${HOME}/ubtest/py/${HOSTNAME}:${PYTHONPATH} \ + ./test/py/test.py --bd seaboard --build --buildman + +Writing tests +------------- + +Please refer to the pytest documentation for details of writing pytest tests. +Details specific to the U-Boot test suite are described below. + +A test fixture named `u_boot_console` should be used by each test function. This +provides the means to interact with the U-Boot console, and retrieve board and +environment configuration information. + +The function `u_boot_console.run_command()` executes a shell command on the +U-Boot console, and returns all output from that command. This allows +validation or interpretation of the command output. This function validates +that certain strings are not seen on the U-Boot console. These include shell +error messages and the U-Boot sign-on message (in order to detect unexpected +board resets). See the source of `u_boot_console_base.py` for a complete list of +"bad" strings. Some test scenarios are expected to trigger these strings. Use +`u_boot_console.disable_check()` to temporarily disable checking for specific +strings. See `test_unknown_cmd.py` for an example. + +Board- and board-environment configuration values may be accessed as sub-fields +of the `u_boot_console.config` object, for example +`u_boot_console.config.ram_base`. + +Build configuration values (from `.config`) may be accessed via the dictionary +`u_boot_console.config.buildconfig`, with keys equal to the Kconfig variable +names. diff --git a/roms/u-boot/doc/develop/testing.rst b/roms/u-boot/doc/develop/testing.rst new file mode 100644 index 000000000..ced13ac8b --- /dev/null +++ b/roms/u-boot/doc/develop/testing.rst @@ -0,0 +1,126 @@ +Testing in U-Boot +================= + +U-Boot has a large amount of code. This file describes how this code is +tested and what tests you should write when adding a new feature. + + +Running tests +------------- + +To run most tests on sandbox, type this:: + + make check + +in the U-Boot directory. Note that only the pytest suite is run using this +command. + +Some tests take ages to run and are marked with @pytest.mark.slow. To run just +the quick ones, type this:: + + make qcheck + +It is also possible to run just the tests for tools (patman, binman, etc.). +Such tests are included with those tools, i.e. no actual U-Boot unit tests are +run. Type this:: + + make tcheck + +All of the above use the test/run script with a paremeter to select which tests +are run. + + +Sandbox +------- +U-Boot can be built as a user-space application (e.g. for Linux). This +allows test to be executed without needing target hardware. The 'sandbox' +target provides this feature and it is widely used in tests. + +See :doc:`tests_sandbox` for more information. + +Pytest Suite +------------ + +Many tests are available using the pytest suite, in test/py. This can run +either on sandbox or on real hardware. It relies on the U-Boot console to +inject test commands and check the result. It is slower to run than C code, +but provides the ability to unify lots of tests and summarise their results. + +You can run the tests on sandbox with:: + + ./test/py/test.py --bd sandbox --build + +This will produce HTML output in build-sandbox/test-log.html + +Some tests run with other versions of sandbox. For example sandbox_flattree +runs the tests with livetree (the hierachical devicetree) disabled. You can +also select particular tests with -k:: + + ./test/py/test.py --bd sandbox_flattree --build -k hello + +There are some special tests that run in SPL. For this you need the sandbox_spl +build:: + + ./test/py/test.py --bd sandbox_spl --build -k test_spl + +See test/py/README.md for more information about the pytest suite. + +See :doc:`tests_sandbox` for how to run tests directly (not through pytest). + + +tbot +---- + +Tbot provides a way to execute tests on target hardware. It is intended for +trying out both U-Boot and Linux (and potentially other software) on a +number of boards automatically. It can be used to create a continuous test +environment. See http://www.tbot.tools for more information. + + +Ad-hoc tests +------------ + +There are several ad-hoc tests which run outside the pytest environment: + +test/fs + File system test (shell script) +test/image + FIT and legacy image tests (shell script and Python) +test/stdint + A test that stdint.h can be used in U-Boot (shell script) +trace + Test for the tracing feature (shell script) + +TODO: Move these into pytest. + + +When to write tests +------------------- + +If you add code to U-Boot without a test you are taking a risk. Even if you +perform thorough manual testing at the time of submission, it may break when +future changes are made to U-Boot. It may even break when applied to mainline, +if other changes interact with it. A good mindset is that untested code +probably doesn't work and should be deleted. + +You can assume that the Pytest suite will be run before patches are accepted +to mainline, so this provides protection against future breakage. + +On the other hand there is quite a bit of code that is not covered with tests, +or is covered sparingly. So here are some suggestions: + +- If you are adding a new uclass, add a sandbox driver and a test that uses it +- If you are modifying code covered by an existing test, add a new test case + to cover your changes +- If the code you are modifying has not tests, consider writing one. Even a + very basic test is useful, and may be picked up and enhanced by others. It + is much easier to add onto a test - writing a new large test can seem + daunting to most contributors. + +See doc:`tests_writing` for how to write tests. + + +Future work +----------- + +Converting existing shell scripts into pytest tests. diff --git a/roms/u-boot/doc/develop/tests_sandbox.rst b/roms/u-boot/doc/develop/tests_sandbox.rst new file mode 100644 index 000000000..84608dcb8 --- /dev/null +++ b/roms/u-boot/doc/develop/tests_sandbox.rst @@ -0,0 +1,209 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +Sandbox tests +============= + +Test Design +----------- + +Most uclasses and many functions of U-Boot have sandbox tests. This allows much +of the code to be checked in an developer-friendly environment. + +Sandbox provides a way to write and run unit tests. The traditional approach to +unit tests is to build lots of little executables, one for each test or +category of tests. With sandbox, so far as possible, all the tests share a +small number of executables (e.g. 'u-boot' for sandbox, 'u-boot-spl' and +'u-boot' for sandbox_spl) and can be run very quickly. The vast majority of +tests can run on the 'sandbox' build, + +Available tests +--------------- + +Some of the available tests are: + + - command_ut: Unit tests for command parsing and handling + - compression: Unit tests for U-Boot's compression algorithms, useful for + security checking. It supports gzip, bzip2, lzma and lzo. + - image: Unit tests for images: + + - test/image/test-imagetools.sh - multi-file images + - test/py/tests/test-fit.py - FIT images + - tracing: test/trace/test-trace.sh tests the tracing system (see + README.trace) + - verified boot: test/py/tests/test_vboot.py + +If you change or enhance any U-Boot subsystem, you should write or expand a +test and include it with your patch series submission. Test coverage in some +older areas of U-Boot is still somewhat limited and we need to work to improve +it. + +Note that many of these tests are implemented as commands which you can +run natively on your board if desired (and enabled). + +To run all tests, use 'make check'. + + +Running sandbox tests directly +------------------------------ + +Typically tests are run using the pytest suite. Running pytests on sandbox is +easy and always gets things right. For example some tests require files to be +set up before they can work. + +But it is also possible to run some sandbox tests directly. For example, this +runs the dm_test_gpio() test which you can find in test/dm/gpio.c:: + + $ ./u-boot -T -c "ut dm gpio" + + + U-Boot 2021.01 + + Model: sandbox + DRAM: 128 MiB + WDT: Started with servicing (60s timeout) + MMC: mmc2: 2 (SD), mmc1: 1 (SD), mmc0: 0 (SD) + In: serial + Out: vidconsole + Err: vidconsole + Model: sandbox + SCSI: + Net: eth0: eth@10002000, eth5: eth@10003000, eth3: sbe5, eth6: eth@10004000 + Test: dm_test_gpio: gpio.c + Test: dm_test_gpio: gpio.c (flat tree) + Failures: 0 + +The -T option tells the U-Boot sandbox to run with the 'test' devicetree +(test.dts) instead of -D which selects the normal sandbox.dts - this is +necessary because many tests rely on nodes or properties in the test devicetree. +If you try running tests without -T then you may see failures, like:: + + $ ./u-boot -c "ut dm gpio" + + + U-Boot 2021.01 + + DRAM: 128 MiB + WDT: Not found! + MMC: + In: serial + Out: serial + Err: serial + SCSI: + Net: No ethernet found. + Please run with test device tree: + ./u-boot -d arch/sandbox/dts/test.dtb + Test: dm_test_gpio: gpio.c + test/dm/gpio.c:37, dm_test_gpio(): 0 == gpio_lookup_name("b4", &dev, &offset, &gpio): Expected 0x0 (0), got 0xffffffea (-22) + Test: dm_test_gpio: gpio.c (flat tree) + test/dm/gpio.c:37, dm_test_gpio(): 0 == gpio_lookup_name("b4", &dev, &offset, &gpio): Expected 0x0 (0), got 0xffffffea (-22) + Failures: 2 + +The message above should provide a hint if you forget to use the -T flag. Even +running with -D will produce different results. + +You can easily use gdb on these tests, without needing --gdbserver:: + + $ gdb u-boot --args -T -c "ut dm gpio" + ... + (gdb) break dm_test_gpio + Breakpoint 1 at 0x1415bd: file test/dm/gpio.c, line 37. + (gdb) run -T -c "ut dm gpio" + Starting program: u-boot -T -c "ut dm gpio" + Test: dm_test_gpio: gpio.c + + Breakpoint 1, dm_test_gpio (uts=0x5555558029a0 <global_dm_test_state>) + at files/test/dm/gpio.c:37 + 37 ut_assertok(gpio_lookup_name("b4", &dev, &offset, &gpio)); + (gdb) + +You can then single-step and look at variables as needed. + + +Running sandbox_spl tests directly +---------------------------------- + +SPL is the phase before U-Boot proper. It is present in the sandbox_spl build, +so you can run SPL like this:: + + ./spl/u-boot-spl + +SPL tests are special in that they run (only in the SPL phase, of course) if the +-u flag is given:: + + ./spl/u-boot-spl -u + + U-Boot SPL 2021.01-00723-g43c77b51be5-dirty (Jan 24 2021 - 16:38:24 -0700) + Running 5 driver model tests + Test: dm_test_of_plat_base: of_platdata.c (flat tree) + Test: dm_test_of_plat_dev: of_platdata.c (flat tree) + Test: dm_test_of_plat_parent: of_platdata.c (flat tree) + Test: dm_test_of_plat_phandle: of_platdata.c (flat tree) + Test: dm_test_of_plat_props: of_platdata.c (flat tree) + Failures: 0 + + + U-Boot 2021.01-00723-g43c77b51be5-dirty (Jan 24 2021 - 16:38:24 -0700) + + DRAM: 128 MiB + ... + +It is not possible to run SPL tests in U-Boot proper, firstly because they are +not built into U-Boot proper and secondly because the environment is very +different, e.g. some SPL tests rely on of-platdata which is only available in +SPL. + +Note that after running, SPL continues to boot into U-Boot proper. You can add +'-c exit' to make U-Boot quit without doing anything further. It is not +currently possible to run SPL tests and then stop, since the pytests require +that U-Boot produces the expected banner. + +You can use the -k flag to select which tests run:: + + ./spl/u-boot-spl -u -k dm_test_of_plat_parent + +Of course you can use gdb with sandbox_spl, just as with sandbox. + + +Running all tests directly +-------------------------- + +A fast way to run all sandbox tests is:: + + ./u-boot -T -c "ut all" + +It typically runs single-thread in 6 seconds on 2021 hardware, with 2s of that +to the delays in the time test. + +This should not be considered a substitute for 'make check', but can be helpful +for git bisect, etc. + + +What tests are built in? +------------------------ + +Whatever sandbox build is used, which tests are present is determined by which +source files are built. For sandbox_spl, the of_platdata tests are built +because of the build rule in test/dm/Makefile:: + + ifeq ($(CONFIG_SPL_BUILD),y) + obj-$(CONFIG_SPL_OF_PLATDATA) += of_platdata.o + else + ...other tests for non-spl + endif + +You can get a list of tests in a U-Boot ELF file by looking for the +linker_list:: + + $ nm /tmp/b/sandbox_spl/spl/u-boot-spl |grep 2_dm_test + 000000000001f200 D _u_boot_list_2_dm_test_2_dm_test_of_plat_base + 000000000001f220 D _u_boot_list_2_dm_test_2_dm_test_of_plat_dev + 000000000001f240 D _u_boot_list_2_dm_test_2_dm_test_of_plat_parent + 000000000001f260 D _u_boot_list_2_dm_test_2_dm_test_of_plat_phandle + 000000000001f280 D _u_boot_list_2_dm_test_2_dm_test_of_plat_props + + +Writing tests +------------- + +See :doc:`tests_writing` for how to write new tests. + diff --git a/roms/u-boot/doc/develop/tests_writing.rst b/roms/u-boot/doc/develop/tests_writing.rst new file mode 100644 index 000000000..1ddf7a353 --- /dev/null +++ b/roms/u-boot/doc/develop/tests_writing.rst @@ -0,0 +1,346 @@ +.. SPDX-License-Identifier: GPL-2.0+ +.. Copyright 2021 Google LLC +.. sectionauthor:: Simon Glass <sjg@chromium.org> + +Writing Tests +============= + +This describes how to write tests in U-Boot and describes the possible options. + +Test types +---------- + +There are two basic types of test in U-Boot: + + - Python tests, in test/py/tests + - C tests, in test/ and its subdirectories + +(there are also UEFI tests in lib/efi_selftest/ not considered here.) + +Python tests talk to U-Boot via the command line. They support both sandbox and +real hardware. They typically do not require building test code into U-Boot +itself. They are fairly slow to run, due to the command-line interface and there +being two separate processes. Python tests are fairly easy to write. They can +be a little tricky to debug sometimes due to the voluminous output of pytest. + +C tests are written directly in U-Boot. While they can be used on boards, they +are more commonly used with sandbox, as they obviously add to U-Boot code size. +C tests are easy to write so long as the required facilities exist. Where they +do not it can involve refactoring or adding new features to sandbox. They are +fast to run and easy to debug. + +Regardless of which test type is used, all tests are collected and run by the +pytest framework, so there is typically no need to run them separately. This +means that C tests can be used when it makes sense, and Python tests when it +doesn't. + + +This table shows how to decide whether to write a C or Python test: + +===================== =========================== ============================= +Attribute C test Python test +===================== =========================== ============================= +Fast to run? Yes No (two separate processes) +Easy to write? Yes, if required test Yes + features exist in sandbox + or the target system +Needs code in U-Boot? Yes No, provided the test can be + executed and the result + determined using the command + line +Easy to debug? Yes No, since access to the U-Boot + state is not available and the + amount of output can + sometimes require a bit of + digging +Can use gdb? Yes, directly Yes, with --gdbserver +Can run on boards? Some can, but only if Some + compiled in and not + dependent on sandboxau +===================== =========================== ============================= + + +Python or C +----------- + +Typically in U-Boot we encourage C test using sandbox for all features. This +allows fast testing, easy development and allows contributors to make changes +without needing dozens of boards to test with. + +When a test requires setup or interaction with the running host (such as to +generate images and then running U-Boot to check that they can be loaded), or +cannot be run on sandbox, Python tests should be used. These should typically +NOT rely on running with sandbox, but instead should function correctly on any +board supported by U-Boot. + + +How slow are Python tests? +-------------------------- + +Under the hood, when running on sandbox, Python tests work by starting a sandbox +test and connecting to it via a pipe. Each interaction with the U-Boot process +requires at least a context switch to handle the pipe interaction. The test +sends a command to U-Boot, which then reacts and shows some output, then the +test sees that and continues. Of course on real hardware, communications delays +(e.g. with a serial console) make this slower. + +For comparison, consider a test that checks the 'md' (memory dump). All times +below are approximate, as measured on an AMD 2950X system. Here is is the test +in Python:: + + @pytest.mark.buildconfigspec('cmd_memory') + def test_md(u_boot_console): + """Test that md reads memory as expected, and that memory can be modified + using the mw command.""" + + ram_base = u_boot_utils.find_ram_base(u_boot_console) + addr = '%08x' % ram_base + val = 'a5f09876' + expected_response = addr + ': ' + val + u_boot_console.run_command('mw ' + addr + ' 0 10') + response = u_boot_console.run_command('md ' + addr + ' 10') + assert(not (expected_response in response)) + u_boot_console.run_command('mw ' + addr + ' ' + val) + response = u_boot_console.run_command('md ' + addr + ' 10') + assert(expected_response in response) + +This runs a few commands and checks the output. Note that it runs a command, +waits for the response and then checks it agains what is expected. If run by +itself it takes around 800ms, including test collection. For 1000 runs it takes +19 seconds, or 19ms per run. Of course 1000 runs it not that useful since we +only want to run it once. + +There is no exactly equivalent C test, but here is a similar one that tests 'ms' +(memory search):: + + /* Test 'ms' command with bytes */ + static int mem_test_ms_b(struct unit_test_state *uts) + { + u8 *buf; + + buf = map_sysmem(0, BUF_SIZE + 1); + memset(buf, '\0', BUF_SIZE); + buf[0x0] = 0x12; + buf[0x31] = 0x12; + buf[0xff] = 0x12; + buf[0x100] = 0x12; + ut_assertok(console_record_reset_enable()); + run_command("ms.b 1 ff 12", 0); + ut_assert_nextline("00000030: 00 12 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................"); + ut_assert_nextline("--"); + ut_assert_nextline("000000f0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 12 ................"); + ut_assert_nextline("2 matches"); + ut_assert_console_end(); + + ut_asserteq(2, env_get_hex("memmatches", 0)); + ut_asserteq(0xff, env_get_hex("memaddr", 0)); + ut_asserteq(0xfe, env_get_hex("mempos", 0)); + + unmap_sysmem(buf); + + return 0; + } + MEM_TEST(mem_test_ms_b, UT_TESTF_CONSOLE_REC); + +This runs the command directly in U-Boot, then checks the console output, also +directly in U-Boot. If run by itself this takes 100ms. For 1000 runs it takes +660ms, or 0.66ms per run. + +So overall running a C test is perhaps 8 times faster individually and the +interactions are perhaps 25 times faster. + +It should also be noted that the C test is fairly easy to debug. You can set a +breakpoint on do_mem_search(), which is what implements the 'ms' command, +single step to see what might be wrong, etc. That is also possible with the +pytest, but requires two terminals and --gdbserver. + + +Why does speed matter? +---------------------- + +Many development activities rely on running tests: + + - 'git bisect run make qcheck' can be used to find a failing commit + - test-driven development relies on quick iteration of build/test + - U-Boot's continuous integration (CI) systems make use of tests. Running + all sandbox tests typically takes 90 seconds and running each qemu test + takes about 30 seconds. This is currently dwarfed by the time taken to + build all boards + +As U-Boot continues to grow its feature set, fast and reliable tests are a +critical factor factor in developer productivity and happiness. + + +Writing C tests +--------------- + +C tests are arranged into suites which are typically executed by the 'ut' +command. Each suite is in its own file. This section describes how to accomplish +some common test tasks. + +(there are also UEFI C tests in lib/efi_selftest/ not considered here.) + +Add a new driver model test +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Use this when adding a test for a new or existing uclass, adding new operations +or features to a uclass, adding new ofnode or dev_read_() functions, or anything +else related to driver model. + +Find a suitable place for your test, perhaps near other test functions in +existing code, or in a new file. Each uclass should have its own test file. + +Declare the test with:: + + /* Test that ... */ + static int dm_test_uclassname_what(struct unit_test_state *uts) + { + /* test code here */ + + return 0; + } + DM_TEST(dm_test_uclassname_what, UT_TESTF_SCAN_FDT); + +Replace 'uclassname' with the name of your uclass, if applicable. Replace 'what' +with what you are testing. + +The flags for DM_TEST() are defined in test/test.h and you typically want +UT_TESTF_SCAN_FDT so that the devicetree is scanned and all devices are bound +and ready for use. The DM_TEST macro adds UT_TESTF_DM automatically so that +the test runner knows it is a driver model test. + +Driver model tests are special in that the entire driver model state is +recreated anew for each test. This ensures that if a previous test deletes a +device, for example, it does not affect subsequent tests. Driver model tests +also run both with livetree and flattree, to ensure that both devicetree +implementations work as expected. + +Example commit: c48cb7ebfb4 ("sandbox: add ADC unit tests") [1] + +[1] https://gitlab.denx.de/u-boot/u-boot/-/commit/c48cb7ebfb4 + + +Add a C test to an existing suite +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Use this when you are adding to or modifying an existing feature outside driver +model. An example is bloblist. + +Add a new function in the same file as the rest of the suite and register it +with the suite. For example, to add a new mem_search test:: + + /* Test 'ms' command with 32-bit values */ + static int mem_test_ms_new_thing(struct unit_test_state *uts) + { + /* test code here*/ + + return 0; + } + MEM_TEST(mem_test_ms_new_thing, UT_TESTF_CONSOLE_REC); + +Note that the MEM_TEST() macros is defined at the top of the file. + +Example commit: 9fe064646d2 ("bloblist: Support relocating to a larger space") [1] + +[1] https://gitlab.denx.de/u-boot/u-boot/-/commit/9fe064646d2 + + +Add a new test suite +~~~~~~~~~~~~~~~~~~~~ + +Each suite should focus on one feature or subsystem, so if you are writing a +new one of those, you should add a new suite. + +Create a new file in test/ or a subdirectory and define a macro to register the +suite. For example:: + + #include <common.h> + #include <console.h> + #include <mapmem.h> + #include <dm/test.h> + #include <test/ut.h> + + /* Declare a new wibble test */ + #define WIBBLE_TEST(_name, _flags) UNIT_TEST(_name, _flags, wibble_test) + + /* Tetss go here */ + + /* At the bottom of the file: */ + + int do_ut_wibble(struct cmd_tbl *cmdtp, int flag, int argc, char *const argv[]) + { + struct unit_test *tests = UNIT_TEST_SUITE_START(wibble_test); + const int n_ents = UNIT_TEST_SUITE_COUNT(wibble_test); + + return cmd_ut_category("cmd_wibble", "wibble_test_", tests, n_ents, argc, argv); + } + +Then add new tests to it as above. + +Register this new suite in test/cmd_ut.c by adding to cmd_ut_sub[]:: + + /* Within cmd_ut_sub[]... */ + + U_BOOT_CMD_MKENT(wibble, CONFIG_SYS_MAXARGS, 1, do_ut_wibble, "", ""), + +and adding new help to ut_help_text[]:: + + "ut wibble - Test the wibble feature\n" + +If your feature is conditional on a particular Kconfig, then you can use #ifdef +to control that. + +Finally, add the test to the build by adding to the Makefile in the same +directory:: + + obj-$(CONFIG_$(SPL_)CMDLINE) += wibble.o + +Note that CMDLINE is never enabled in SPL, so this test will only be present in +U-Boot proper. See below for how to do SPL tests. + +As before, you can add an extra Kconfig check if needed:: + + ifneq ($(CONFIG_$(SPL_)WIBBLE),) + obj-$(CONFIG_$(SPL_)CMDLINE) += wibble.o + endif + + +Example commit: 919e7a8fb64 ("test: Add a simple test for bloblist") [1] + +[1] https://gitlab.denx.de/u-boot/u-boot/-/commit/919e7a8fb64 + + +Making the test run from pytest +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +All C tests must run from pytest. Typically this is automatic, since pytest +scans the U-Boot executable for available tests to run. So long as you have a +'ut' subcommand for your test suite, it will run. The same applies for driver +model tests since they use the 'ut dm' subcommand. + +See test/py/tests/test_ut.py for how unit tests are run. + + +Add a C test for SPL +~~~~~~~~~~~~~~~~~~~~ + +Note: C tests are only available for sandbox_spl at present. There is currently +no mechanism in other boards to existing SPL tests even if they are built into +the image. + +SPL tests cannot be run from the 'ut' command since there are no commands +available in SPL. Instead, sandbox (only) calls ut_run_list() on start-up, when +the -u flag is given. This runs the available unit tests, no matter what suite +they are in. + +To create a new SPL test, follow the same rules as above, either adding to an +existing suite or creating a new one. + +An example SPL test is spl_test_load(). + + +Writing Python tests +-------------------- + +See :doc:`py_testing` for brief notes how to write Python tests. You +should be able to use the existing tests in test/py/tests as examples. diff --git a/roms/u-boot/doc/develop/trace.rst b/roms/u-boot/doc/develop/trace.rst new file mode 100644 index 000000000..7776c4842 --- /dev/null +++ b/roms/u-boot/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 [<addr> <size>] + Dump a list of functions into the 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 +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 <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 + + +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 <sjg@chromium.org> +April 2013 diff --git a/roms/u-boot/doc/develop/uefi/index.rst b/roms/u-boot/doc/develop/uefi/index.rst new file mode 100644 index 000000000..7e65dbc5d --- /dev/null +++ b/roms/u-boot/doc/develop/uefi/index.rst @@ -0,0 +1,15 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +Unified Extensible Firmware (UEFI) +================================== + +U-Boot provides an implementation of the UEFI API allowing to run UEFI +compliant software like Linux, GRUB, and iPXE. Furthermore U-Boot itself +can be run an UEFI payload. + +.. toctree:: + :maxdepth: 2 + + uefi.rst + u-boot_on_efi.rst + iscsi.rst diff --git a/roms/u-boot/doc/develop/uefi/iscsi.rst b/roms/u-boot/doc/develop/uefi/iscsi.rst new file mode 100644 index 000000000..51d38cde2 --- /dev/null +++ b/roms/u-boot/doc/develop/uefi/iscsi.rst @@ -0,0 +1,184 @@ +.. SPDX-License-Identifier: GPL-2.0+ +.. Copyright (c) 2018 Heinrich Schuchardt + +iSCSI booting with U-Boot and iPXE +================================== + +Motivation +---------- + +U-Boot has only a reduced set of supported network protocols. The focus for +network booting has been on UDP based protocols. A TCP stack and HTTP support +are expected to be integrated in 2018 together with a wget command. + +For booting a diskless computer this leaves us with BOOTP or DHCP to get the +address of a boot script. TFTP or NFS can be used to load the boot script, the +operating system kernel and the initial file system (initrd). + +These protocols are insecure. The client cannot validate the authenticity +of the contacted servers. And the server cannot verify the identity of the +client. + +Furthermore the services providing the operating system loader or kernel are +not the ones that the operating system typically will use. Especially in a SAN +environment this makes updating the operating system a hassle. After installing +a new kernel version the boot files have to be copied to the TFTP server +directory. + +The HTTPS protocol provides certificate based validation of servers. Sensitive +data like passwords can be securely transmitted. + +The iSCSI protocol is used for connecting storage attached networks. It +provides mutual authentication using the CHAP protocol. It typically runs on +a TCP transport. + +Thus a better solution than DHCP/TFTP/NFS boot would be to load a boot script +via HTTPS and to download any other files needed for booting via iSCSI from the +same target where the operating system is installed. + +An alternative to implementing these protocols in U-Boot is to use an existing +software that can run on top of U-Boot. iPXE[1] is the "swiss army knife" of +network booting. It supports both HTTPS and iSCSI. It has a scripting engine for +fine grained control of the boot process and can provide a command shell. + +iPXE can be built as an EFI application (named snp.efi) which can be loaded and +run by U-Boot. + +Boot sequence +------------- + +U-Boot loads the EFI application iPXE snp.efi using the bootefi command. This +application has network access via the simple network protocol offered by +U-Boot. + +iPXE executes its internal script. This script may optionally chain load a +secondary boot script via HTTPS or open a shell. + +For the further boot process iPXE connects to the iSCSI server. This includes +the mutual authentication using the CHAP protocol. After the authentication iPXE +has access to the iSCSI targets. + +For a selected iSCSI target iPXE sets up a handle with the block IO protocol. It +uses the ConnectController boot service of U-Boot to request U-Boot to connect a +file system driver. U-Boot reads from the iSCSI drive via the block IO protocol +offered by iPXE. It creates the partition handles and installs the simple file +protocol. Now iPXE can call the simple file protocol to load GRUB[2]. U-Boot +uses the block IO protocol offered by iPXE to fulfill the request. + +Once GRUB is started it uses the same block IO protocol to load Linux. Via +the EFI stub Linux is called as an EFI application:: + + +--------+ +--------+ + | | Runs | | + | U-Boot |========>| iPXE | + | EFI | | snp.efi| + +--------+ | | DHCP | | + | |<===|********|<========| | + | DHCP | | | Get IP | | + | Server | | | Address | | + | |===>|********|========>| | + +--------+ | | Response| | + | | | | + | | | | + +--------+ | | HTTPS | | + | |<===|********|<========| | + | HTTPS | | | Load | | + | Server | | | Script | | + | |===>|********|========>| | + +--------+ | | | | + | | | | + | | | | + +--------+ | | iSCSI | | + | |<===|********|<========| | + | iSCSI | | | Auth | | + | Server |===>|********|========>| | + | | | | | | + | | | | Loads | | + | |<===|********|<========| | +--------+ + | | | | GRUB | | Runs | | + | |===>|********|========>| |======>| GRUB | + | | | | | | | | + | | | | | | | | + | | | | | | Loads | | + | |<===|********|<========|********|<======| | +--------+ + | | | | | | Linux | | Runs | | + | |===>|********|========>|********|======>| |=====>| Linux | + | | | | | | | | | | + +--------+ +--------+ +--------+ +--------+ | | + | | + | | + | ~ ~ ~ ~| + +Security +-------- + +The iSCSI protocol is not encrypted. The traffic could be secured using IPsec +but neither U-Boot nor iPXE does support this. So we should at least separate +the iSCSI traffic from all other network traffic. This can be achieved using a +virtual local area network (VLAN). + +Configuration +------------- + +iPXE +~~~~ + +For running iPXE on arm64 the bin-arm64-efi/snp.efi build target is needed:: + + git clone http://git.ipxe.org/ipxe.git + cd ipxe/src + make bin-arm64-efi/snp.efi -j6 EMBED=myscript.ipxe + +The available commands for the boot script are documented at: + +http://ipxe.org/cmd + +Credentials are managed as environment variables. These are described here: + +http://ipxe.org/cfg + +iPXE by default will put the CPU to rest when waiting for input. U-Boot does +not wake it up due to missing interrupt support. To avoid this behavior create +file src/config/local/nap.h: + +.. code-block:: c + + /* nap.h */ + #undef NAP_EFIX86 + #undef NAP_EFIARM + #define NAP_NULL + +The supported commands in iPXE are controlled by an include, too. Putting the +following into src/config/local/general.h is sufficient for most use cases: + +.. code-block:: c + + /* general.h */ + #define NSLOOKUP_CMD /* Name resolution command */ + #define PING_CMD /* Ping command */ + #define NTP_CMD /* NTP commands */ + #define VLAN_CMD /* VLAN commands */ + #define IMAGE_EFI /* EFI image support */ + #define DOWNLOAD_PROTO_HTTPS /* Secure Hypertext Transfer Protocol */ + #define DOWNLOAD_PROTO_FTP /* File Transfer Protocol */ + #define DOWNLOAD_PROTO_NFS /* Network File System Protocol */ + #define DOWNLOAD_PROTO_FILE /* Local file system access */ + +Open-iSCSI +~~~~~~~~~~ + +When the root file system is on an iSCSI drive you should disable pings and set +the replacement timer to a high value in the configuration file [3]:: + + node.conn[0].timeo.noop_out_interval = 0 + node.conn[0].timeo.noop_out_timeout = 0 + node.session.timeo.replacement_timeout = 86400 + +Links +----- + +* [1] https://ipxe.org - iPXE open source boot firmware +* [2] https://www.gnu.org/software/grub/ - + GNU GRUB (Grand Unified Bootloader) +* [3] https://github.com/open-iscsi/open-iscsi/blob/master/README - + Open-iSCSI README diff --git a/roms/u-boot/doc/develop/uefi/u-boot_on_efi.rst b/roms/u-boot/doc/develop/uefi/u-boot_on_efi.rst new file mode 100644 index 000000000..c9a41bc91 --- /dev/null +++ b/roms/u-boot/doc/develop/uefi/u-boot_on_efi.rst @@ -0,0 +1,235 @@ +.. SPDX-License-Identifier: GPL-2.0+ +.. Copyright (C) 2015 Google, Inc + +U-Boot on EFI +============= +This document provides information about U-Boot running on top of EFI, either +as an application or just as a means of getting U-Boot onto a new platform. + + +Motivation +---------- +Running U-Boot on EFI is useful in several situations: + +- You have EFI running on a board but U-Boot does not natively support it + fully yet. You can boot into U-Boot from EFI and use that until U-Boot is + fully ported + +- You need to use an EFI implementation (e.g. UEFI) because your vendor + requires it in order to provide support + +- You plan to use coreboot to boot into U-Boot but coreboot support does + not currently exist for your platform. In the meantime you can use U-Boot + on EFI and then move to U-Boot on coreboot when ready + +- You use EFI but want to experiment with a simpler alternative like U-Boot + + +Status +------ +Only x86 is supported at present. If you are using EFI on another architecture +you may want to reconsider. However, much of the code is generic so could be +ported. + +U-Boot supports running as an EFI application for 32-bit EFI only. This is +not very useful since only a serial port is provided. You can look around at +memory and type 'help' but that is about it. + +More usefully, U-Boot supports building itself as a payload for either 32-bit +or 64-bit EFI. U-Boot is packaged up and loaded in its entirety by EFI. Once +started, U-Boot changes to 32-bit mode (currently) and takes over the +machine. You can use devices, boot a kernel, etc. + + +Build Instructions +------------------ +First choose a board that has EFI support and obtain an EFI implementation +for that board. It will be either 32-bit or 64-bit. Alternatively, you can +opt for using QEMU [1] and the OVMF [2], as detailed below. + +To build U-Boot as an EFI application (32-bit EFI required), enable CONFIG_EFI +and CONFIG_EFI_APP. The efi-x86_app config (efi-x86_app_defconfig) is set up +for this. Just build U-Boot as normal, e.g.:: + + make efi-x86_app_defconfig + make + +To build U-Boot as an EFI payload (32-bit or 64-bit EFI can be used), enable +CONFIG_EFI, CONFIG_EFI_STUB, and select either CONFIG_EFI_STUB_32BIT or +CONFIG_EFI_STUB_64BIT. The efi-x86_payload configs (efi-x86_payload32_defconfig +and efi-x86_payload32_defconfig) are set up for this. Then build U-Boot as +normal, e.g.:: + + make efi-x86_payload32_defconfig (or efi-x86_payload64_defconfig) + make + +You will end up with one of these files depending on what you build for: + +* u-boot-app.efi - U-Boot EFI application +* u-boot-payload.efi - U-Boot EFI payload application + + +Trying it out +------------- +QEMU is an emulator and it can emulate an x86 machine. Please make sure your +QEMU version is 2.3.0 or above to test this. You can run the payload with +something like this:: + + mkdir /tmp/efi + cp /path/to/u-boot*.efi /tmp/efi + qemu-system-x86_64 -bios bios.bin -hda fat:/tmp/efi/ + +Add -nographic if you want to use the terminal for output. Once it starts +type 'fs0:u-boot-payload.efi' to run the payload or 'fs0:u-boot-app.efi' to +run the application. 'bios.bin' is the EFI 'BIOS'. Check [2] to obtain a +prebuilt EFI BIOS for QEMU or you can build one from source as well. + +To try it on real hardware, put u-boot-app.efi on a suitable boot medium, +such as a USB stick. Then you can type something like this to start it:: + + fs0:u-boot-payload.efi + +(or fs0:u-boot-app.efi for the application) + +This will start the payload, copy U-Boot into RAM and start U-Boot. Note +that EFI does not support booting a 64-bit application from a 32-bit +EFI (or vice versa). Also it will often fail to print an error message if +you get this wrong. + + +Inner workings +-------------- +Here follow a few implementation notes for those who want to fiddle with +this and perhaps contribute patches. + +The application and payload approaches sound similar but are in fact +implemented completely differently. + +EFI Application +~~~~~~~~~~~~~~~ +For the application the whole of U-Boot is built as a shared library. The +efi_main() function is in lib/efi/efi_app.c. It sets up some basic EFI +functions with efi_init(), sets up U-Boot global_data, allocates memory for +U-Boot's malloc(), etc. and enters the normal init sequence (board_init_f() +and board_init_r()). + +Since U-Boot limits its memory access to the allocated regions very little +special code is needed. The CONFIG_EFI_APP option controls a few things +that need to change so 'git grep CONFIG_EFI_APP' may be instructive. +The CONFIG_EFI option controls more general EFI adjustments. + +The only available driver is the serial driver. This calls back into EFI +'boot services' to send and receive characters. Although it is implemented +as a serial driver the console device is not necessarilly serial. If you +boot EFI with video output then the 'serial' device will operate on your +target devices's display instead and the device's USB keyboard will also +work if connected. If you have both serial and video output, then both +consoles will be active. Even though U-Boot does the same thing normally, +These are features of EFI, not U-Boot. + +Very little code is involved in implementing the EFI application feature. +U-Boot is highly portable. Most of the difficulty is in modifying the +Makefile settings to pass the right build flags. In particular there is very +little x86-specific code involved - you can find most of it in +arch/x86/cpu. Porting to ARM (which can also use EFI if you are brave +enough) should be straightforward. + +Use the 'reset' command to get back to EFI. + +EFI Payload +~~~~~~~~~~~ +The payload approach is a different kettle of fish. It works by building +U-Boot exactly as normal for your target board, then adding the entire +image (including device tree) into a small EFI stub application responsible +for booting it. The stub application is built as a normal EFI application +except that it has a lot of data attached to it. + +The stub application is implemented in lib/efi/efi_stub.c. The efi_main() +function is called by EFI. It is responsible for copying U-Boot from its +original location into memory, disabling EFI boot services and starting +U-Boot. U-Boot then starts as normal, relocates, starts all drivers, etc. + +The stub application is architecture-dependent. At present it has some +x86-specific code and a comment at the top of efi_stub.c describes this. + +While the stub application does allocate some memory from EFI this is not +used by U-Boot (the payload). In fact when U-Boot starts it has all of the +memory available to it and can operate as it pleases (but see the next +section). + +Tables +~~~~~~ +The payload can pass information to U-Boot in the form of EFI tables. At +present this feature is used to pass the EFI memory map, an inordinately +large list of memory regions. You can use the 'efi mem all' command to +display this list. U-Boot uses the list to work out where to relocate +itself. + +Although U-Boot can use any memory it likes, EFI marks some memory as used +by 'run-time services', code that hangs around while U-Boot is running and +is even present when Linux is running. This is common on x86 and provides +a way for Linux to call back into the firmware to control things like CPU +fan speed. U-Boot uses only 'conventional' memory, in EFI terminology. It +will relocate itself to the top of the largest block of memory it can find +below 4GB. + +Interrupts +~~~~~~~~~~ +U-Boot drivers typically don't use interrupts. Since EFI enables interrupts +it is possible that an interrupt will fire that U-Boot cannot handle. This +seems to cause problems. For this reason the U-Boot payload runs with +interrupts disabled at present. + +32/64-bit +~~~~~~~~~ +While the EFI application can in principle be built as either 32- or 64-bit, +only 32-bit is currently supported. This means that the application can only +be used with 32-bit EFI. + +The payload stub can be build as either 32- or 64-bits. Only a small amount +of code is built this way (see the extra- line in lib/efi/Makefile). +Everything else is built as a normal U-Boot, so is always 32-bit on x86 at +present. + +Future work +----------- +This work could be extended in a number of ways: + +- Add ARM support + +- Add 64-bit application support + +- Figure out how to solve the interrupt problem + +- Add more drivers to the application side (e.g. video, block devices, USB, + environment access). This would mostly be an academic exercise as a strong + use case is not readily apparent, but it might be fun. + +- Avoid turning off boot services in the stub. Instead allow U-Boot to make + use of boot services in case it wants to. It is unclear what it might want + though. + +Where is the code? +------------------ +lib/efi + payload stub, application, support code. Mostly arch-neutral + +arch/x86/cpu/efi + x86 support code for running as an EFI application and payload + +board/efi/efi-x86_app/efi.c + x86 board code for running as an EFI application + +board/efi/efi-x86_payload + generic x86 EFI payload board support code + +common/cmd_efi.c + the 'efi' command + +-- +Ben Stoltz, Simon Glass +Google, Inc +July 2015 + +* [1] http://www.qemu.org +* [2] http://www.tianocore.org/ovmf/ diff --git a/roms/u-boot/doc/develop/uefi/uefi.rst b/roms/u-boot/doc/develop/uefi/uefi.rst new file mode 100644 index 000000000..4f2b8b036 --- /dev/null +++ b/roms/u-boot/doc/develop/uefi/uefi.rst @@ -0,0 +1,574 @@ +.. SPDX-License-Identifier: GPL-2.0+ +.. Copyright (c) 2018 Heinrich Schuchardt + +UEFI on U-Boot +============== + +The Unified Extensible Firmware Interface Specification (UEFI) [1] has become +the default for booting on AArch64 and x86 systems. It provides a stable API for +the interaction of drivers and applications with the firmware. The API comprises +access to block storage, network, and console to name a few. The Linux kernel +and boot loaders like GRUB or the FreeBSD loader can be executed. + +Development target +------------------ + +The implementation of UEFI in U-Boot strives to reach the requirements described +in the "Embedded Base Boot Requirements (EBBR) Specification - Release v1.0" +[2]. The "Server Base Boot Requirements System Software on ARM Platforms" [3] +describes a superset of the EBBR specification and may be used as further +reference. + +A full blown UEFI implementation would contradict the U-Boot design principle +"keep it small". + +Building U-Boot for UEFI +------------------------ + +The UEFI standard supports only little-endian systems. The UEFI support can be +activated for ARM and x86 by specifying:: + + CONFIG_CMD_BOOTEFI=y + CONFIG_EFI_LOADER=y + +in the .config file. + +Support for attaching virtual block devices, e.g. iSCSI drives connected by the +loaded UEFI application [4], requires:: + + CONFIG_BLK=y + CONFIG_PARTITIONS=y + +Executing a UEFI binary +~~~~~~~~~~~~~~~~~~~~~~~ + +The bootefi command is used to start UEFI applications or to install UEFI +drivers. It takes two parameters:: + + bootefi <image address> [fdt address] + +* image address - the memory address of the UEFI binary +* fdt address - the memory address of the flattened device tree + +Below you find the output of an example session starting GRUB:: + + => load mmc 0:2 ${fdt_addr_r} boot/dtb + 29830 bytes read in 14 ms (2 MiB/s) + => load mmc 0:1 ${kernel_addr_r} efi/debian/grubaa64.efi + reading efi/debian/grubaa64.efi + 120832 bytes read in 7 ms (16.5 MiB/s) + => bootefi ${kernel_addr_r} ${fdt_addr_r} + +When booting from a memory location it is unknown from which file it was loaded. +Therefore the bootefi command uses the device path of the block device partition +or the network adapter and the file name of the most recently loaded PE-COFF +file when setting up the loaded image protocol. + +Launching a UEFI binary from a FIT image +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +A signed FIT image can be used to securely boot a UEFI image via the +bootm command. This feature is available if U-Boot is configured with:: + + CONFIG_BOOTM_EFI=y + +A sample configuration is provided as file doc/uImage.FIT/uefi.its. + +Below you find the output of an example session starting GRUB:: + + => load mmc 0:1 ${kernel_addr_r} image.fit + 4620426 bytes read in 83 ms (53.1 MiB/s) + => bootm ${kernel_addr_r}#config-grub-nofdt + ## Loading kernel from FIT Image at 40400000 ... + Using 'config-grub-nofdt' configuration + Verifying Hash Integrity ... sha256,rsa2048:dev+ OK + Trying 'efi-grub' kernel subimage + Description: GRUB EFI Firmware + Created: 2019-11-20 8:18:16 UTC + Type: Kernel Image (no loading done) + Compression: uncompressed + Data Start: 0x404000d0 + Data Size: 450560 Bytes = 440 KiB + Hash algo: sha256 + Hash value: 4dbee00021112df618f58b3f7cf5e1595533d543094064b9ce991e8b054a9eec + Verifying Hash Integrity ... sha256+ OK + XIP Kernel Image (no loading done) + ## Transferring control to EFI (at address 404000d0) ... + Welcome to GRUB! + +See doc/uImage.FIT/howto.txt for an introduction to FIT images. + +Configuring UEFI secure boot +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The UEFI specification[1] defines a secure way of executing UEFI images +by verifying a signature (or message digest) of image with certificates. +This feature on U-Boot is enabled with:: + + CONFIG_UEFI_SECURE_BOOT=y + +To make the boot sequence safe, you need to establish a chain of trust; +In UEFI secure boot the chain trust is defined by the following UEFI variables + +* PK - Platform Key +* KEK - Key Exchange Keys +* db - white list database +* dbx - black list database + +An in depth description of UEFI secure boot is beyond the scope of this +document. Please, refer to the UEFI specification and available online +documentation. Here is a simple example that you can follow for your initial +attempt (Please note that the actual steps will depend on your system and +environment.): + +Install the required tools on your host + +* openssl +* efitools +* sbsigntool + +Create signing keys and the key database on your host: + +The platform key + +.. code-block:: bash + + openssl req -x509 -sha256 -newkey rsa:2048 -subj /CN=TEST_PK/ \ + -keyout PK.key -out PK.crt -nodes -days 365 + cert-to-efi-sig-list -g 11111111-2222-3333-4444-123456789abc \ + PK.crt PK.esl; + sign-efi-sig-list -c PK.crt -k PK.key PK PK.esl PK.auth + +The key exchange keys + +.. code-block:: bash + + openssl req -x509 -sha256 -newkey rsa:2048 -subj /CN=TEST_KEK/ \ + -keyout KEK.key -out KEK.crt -nodes -days 365 + cert-to-efi-sig-list -g 11111111-2222-3333-4444-123456789abc \ + KEK.crt KEK.esl + sign-efi-sig-list -c PK.crt -k PK.key KEK KEK.esl KEK.auth + +The whitelist database + +.. code-block:: bash + + 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 \ + db.crt db.esl + 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. + +Sign an image with one of the keys in "db" on your host + +.. code-block:: bash + + sbsign --key db.key --cert db.crt helloworld.efi + +Now in U-Boot install the keys on your board:: + + fatload mmc 0:1 <tmpaddr> PK.auth + setenv -e -nv -bs -rt -at -i <tmpaddr>:$filesize PK + fatload mmc 0:1 <tmpaddr> KEK.auth + setenv -e -nv -bs -rt -at -i <tmpaddr>:$filesize KEK + fatload mmc 0:1 <tmpaddr> db.auth + setenv -e -nv -bs -rt -at -i <tmpaddr>:$filesize db + +Set up boot parameters on your board:: + + efidebug boot add -b 1 HELLO mmc 0:1 /helloworld.efi.signed "" + +Since kernel 5.7 there's an alternative way of loading an initrd using +LoadFile2 protocol if CONFIG_EFI_LOAD_FILE2_INITRD is enabled. +The initrd path can be specified with:: + + efidebug boot add -b ABE0 'kernel' mmc 0:1 Image -i mmc 0:1 initrd + +Now your board can run the signed image via the boot manager (see below). +You can also try this sequence by running Pytest, test_efi_secboot, +on the sandbox + +.. code-block:: bash + + cd <U-Boot source directory> + pytest.py test/py/tests/test_efi_secboot/test_signed.py --bd sandbox + +UEFI binaries may be signed by Microsoft using the following certificates: + +* KEK: Microsoft Corporation KEK CA 2011 + http://go.microsoft.com/fwlink/?LinkId=321185. +* db: Microsoft Windows Production PCA 2011 + http://go.microsoft.com/fwlink/p/?linkid=321192. +* db: Microsoft Corporation UEFI CA 2011 + http://go.microsoft.com/fwlink/p/?linkid=321194. + +Using OP-TEE for EFI variables +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Instead of implementing UEFI variable services inside U-Boot they can +also be provided in the secure world by a module for OP-TEE[1]. The +interface between U-Boot and OP-TEE for variable services is enabled by +CONFIG_EFI_MM_COMM_TEE=y. + +Tianocore EDK II's standalone management mode driver for variables can +be linked to OP-TEE for this purpose. This module uses the Replay +Protected Memory Block (RPMB) of an eMMC device for persisting +non-volatile variables. When calling the variable services via the +OP-TEE API U-Boot's OP-TEE supplicant relays calls to the RPMB driver +which has to be enabled via CONFIG_SUPPORT_EMMC_RPMB=y. + +EDK2 Build instructions +*********************** + +.. code-block:: bash + + $ git clone https://github.com/tianocore/edk2.git + $ git clone https://github.com/tianocore/edk2-platforms.git + $ cd edk2 + $ git submodule init && git submodule update --init --recursive + $ cd .. + $ export WORKSPACE=$(pwd) + $ export PACKAGES_PATH=$WORKSPACE/edk2:$WORKSPACE/edk2-platforms + $ export ACTIVE_PLATFORM="Platform/StandaloneMm/PlatformStandaloneMmPkg/PlatformStandaloneMmRpmb.dsc" + $ export GCC5_AARCH64_PREFIX=aarch64-linux-gnu- + $ source edk2/edksetup.sh + $ make -C edk2/BaseTools + $ build -p $ACTIVE_PLATFORM -b RELEASE -a AARCH64 -t GCC5 -n `nproc` + +OP-TEE Build instructions +************************* + +.. code-block:: bash + + $ git clone https://github.com/OP-TEE/optee_os.git + $ cd optee_os + $ ln -s ../Build/MmStandaloneRpmb/RELEASE_GCC5/FV/BL32_AP_MM.fd + $ export ARCH=arm + $ CROSS_COMPILE32=arm-linux-gnueabihf- make -j32 CFG_ARM64_core=y \ + PLATFORM=<myboard> CFG_STMM_PATH=BL32_AP_MM.fd CFG_RPMB_FS=y \ + CFG_RPMB_FS_DEV_ID=0 CFG_CORE_HEAP_SIZE=524288 CFG_RPMB_WRITE_KEY=1 \ + CFG_CORE_HEAP_SIZE=524288 CFG_CORE_DYN_SHM=y CFG_RPMB_TESTKEY=y \ + CFG_REE_FS=n CFG_CORE_ARM64_PA_BITS=48 CFG_TEE_CORE_LOG_LEVEL=1 \ + CFG_TEE_TA_LOG_LEVEL=1 CFG_SCTLR_ALIGNMENT_CHECK=n + +U-Boot Build instructions +************************* + +Although the StandAloneMM binary comes from EDK2, using and storing the +variables is currently available in U-Boot only. + +.. code-block:: bash + + $ git clone https://github.com/u-boot/u-boot.git + $ cd u-boot + $ export CROSS_COMPILE=aarch64-linux-gnu- + $ export ARCH=<arch> + $ make <myboard>_defconfig + $ make menuconfig + +Enable ``CONFIG_OPTEE``, ``CONFIG_CMD_OPTEE_RPMB`` and ``CONFIG_EFI_MM_COMM_TEE`` + +.. warning:: + + - Your OP-TEE platform port must support Dynamic shared memory, since that's + the only kind of memory U-Boot supports for now. + +[1] https://optee.readthedocs.io/en/latest/building/efi_vars/stmm.html + +Executing the boot manager +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The UEFI specification foresees to define boot entries and boot sequence via +UEFI variables. Booting according to these variables is possible via:: + + bootefi bootmgr [fdt address] + +As of U-Boot v2020.10 UEFI variables cannot be set at runtime. The U-Boot +command 'efidebug' can be used to set the variables. + +Executing the built in hello world application +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +A hello world UEFI application can be built with:: + + CONFIG_CMD_BOOTEFI_HELLO_COMPILE=y + +It can be embedded into the U-Boot binary with:: + + CONFIG_CMD_BOOTEFI_HELLO=y + +The bootefi command is used to start the embedded hello world application:: + + bootefi hello [fdt address] + +Below you find the output of an example session:: + + => bootefi hello ${fdtcontroladdr} + ## Starting EFI application at 01000000 ... + WARNING: using memory device/image path, this may confuse some payloads! + Hello, world! + Running on UEFI 2.7 + Have SMBIOS table + Have device tree + Load options: root=/dev/sdb3 init=/sbin/init rootwait ro + ## Application terminated, r = 0 + +The environment variable fdtcontroladdr points to U-Boot's internal device tree +(if available). + +Executing the built-in self-test +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +An UEFI self-test suite can be embedded in U-Boot by building with:: + + CONFIG_CMD_BOOTEFI_SELFTEST=y + +For testing the UEFI implementation the bootefi command can be used to start the +self-test:: + + bootefi selftest [fdt address] + +The environment variable 'efi_selftest' can be used to select a single test. If +it is not provided all tests are executed except those marked as 'on request'. +If the environment variable is set to 'list' a list of all tests is shown. + +Below you can find the output of an example session:: + + => setenv efi_selftest simple network protocol + => bootefi selftest + Testing EFI API implementation + Selected test: 'simple network protocol' + Setting up 'simple network protocol' + Setting up 'simple network protocol' succeeded + Executing 'simple network protocol' + DHCP Discover + DHCP reply received from 192.168.76.2 (52:55:c0:a8:4c:02) + as broadcast message. + Executing 'simple network protocol' succeeded + Tearing down 'simple network protocol' + Tearing down 'simple network protocol' succeeded + Boot services terminated + Summary: 0 failures + Preparing for reset. Press any key. + +The UEFI life cycle +------------------- + +After the U-Boot platform has been initialized the UEFI API provides two kinds +of services: + +* boot services +* runtime services + +The API can be extended by loading UEFI drivers which come in two variants: + +* boot drivers +* runtime drivers + +UEFI drivers are installed with U-Boot's bootefi command. With the same command +UEFI applications can be executed. + +Loaded images of UEFI drivers stay in memory after returning to U-Boot while +loaded images of applications are removed from memory. + +An UEFI application (e.g. an operating system) that wants to take full control +of the system calls ExitBootServices. After a UEFI application calls +ExitBootServices + +* boot services are not available anymore +* timer events are stopped +* the memory used by U-Boot except for runtime services is released +* the memory used by boot time drivers is released + +So this is a point of no return. Afterwards the UEFI application can only return +to U-Boot by rebooting. + +The UEFI object model +--------------------- + +UEFI offers a flexible and expandable object model. The objects in the UEFI API +are devices, drivers, and loaded images. These objects are referenced by +handles. + +The interfaces implemented by the objects are referred to as protocols. These +are identified by GUIDs. They can be installed and uninstalled by calling the +appropriate boot services. + +Handles are created by the InstallProtocolInterface or the +InstallMultipleProtocolinterfaces service if NULL is passed as handle. + +Handles are deleted when the last protocol has been removed with the +UninstallProtocolInterface or the UninstallMultipleProtocolInterfaces service. + +Devices offer the EFI_DEVICE_PATH_PROTOCOL. A device path is the concatenation +of device nodes. By their device paths all devices of a system are arranged in a +tree. + +Drivers offer the EFI_DRIVER_BINDING_PROTOCOL. This protocol is used to connect +a driver to devices (which are referenced as controllers in this context). + +Loaded images offer the EFI_LOADED_IMAGE_PROTOCOL. This protocol provides meta +information about the image and a pointer to the unload callback function. + +The UEFI events +--------------- + +In the UEFI terminology an event is a data object referencing a notification +function which is queued for calling when the event is signaled. The following +types of events exist: + +* periodic and single shot timer events +* exit boot services events, triggered by calling the ExitBootServices() service +* virtual address change events +* memory map change events +* read to boot events +* reset system events +* system table events +* events that are only triggered programmatically + +Events can be created with the CreateEvent service and deleted with CloseEvent +service. + +Events can be assigned to an event group. If any of the events in a group is +signaled, all other events in the group are also set to the signaled state. + +The UEFI driver model +--------------------- + +A driver is specific for a single protocol installed on a device. To install a +driver on a device the ConnectController service is called. In this context +controller refers to the device for which the driver is installed. + +The relevant drivers are identified using the EFI_DRIVER_BINDING_PROTOCOL. This +protocol has has three functions: + +* supported - determines if the driver is compatible with the device +* start - installs the driver by opening the relevant protocol with + attribute EFI_OPEN_PROTOCOL_BY_DRIVER +* stop - uninstalls the driver + +The driver may create child controllers (child devices). E.g. a driver for block +IO devices will create the device handles for the partitions. The child +controllers will open the supported protocol with the attribute +EFI_OPEN_PROTOCOL_BY_CHILD_CONTROLLER. + +A driver can be detached from a device using the DisconnectController service. + +U-Boot devices mapped as UEFI devices +------------------------------------- + +Some of the U-Boot devices are mapped as UEFI devices + +* block IO devices +* console +* graphical output +* network adapter + +As of U-Boot 2018.03 the logic for doing this is hard coded. + +The development target is to integrate the setup of these UEFI devices with the +U-Boot driver model [5]. So when a U-Boot device is discovered a handle should +be created and the device path protocol and the relevant IO protocol should be +installed. The UEFI driver then would be attached by calling ConnectController. +When a U-Boot device is removed DisconnectController should be called. + +UEFI devices mapped as U-Boot devices +------------------------------------- + +UEFI drivers binaries and applications may create new (virtual) devices, install +a protocol and call the ConnectController service. Now the matching UEFI driver +is determined by iterating over the implementations of the +EFI_DRIVER_BINDING_PROTOCOL. + +It is the task of the UEFI driver to create a corresponding U-Boot device and to +proxy calls for this U-Boot device to the controller. + +In U-Boot 2018.03 this has only been implemented for block IO devices. + +UEFI uclass +~~~~~~~~~~~ + +An UEFI uclass driver (lib/efi_driver/efi_uclass.c) has been created that +takes care of initializing the UEFI drivers and providing the +EFI_DRIVER_BINDING_PROTOCOL implementation for the UEFI drivers. + +A linker created list is used to keep track of the UEFI drivers. To create an +entry in the list the UEFI driver uses the U_BOOT_DRIVER macro specifying +UCLASS_EFI as the ID of its uclass, e.g:: + + /* Identify as UEFI driver */ + U_BOOT_DRIVER(efi_block) = { + .name = "EFI block driver", + .id = UCLASS_EFI, + .ops = &driver_ops, + }; + +The available operations are defined via the structure struct efi_driver_ops:: + + struct efi_driver_ops { + const efi_guid_t *protocol; + const efi_guid_t *child_protocol; + int (*bind)(efi_handle_t handle, void *interface); + }; + +When the supported() function of the EFI_DRIVER_BINDING_PROTOCOL is called the +uclass checks if the protocol GUID matches the protocol GUID of the UEFI driver. +In the start() function the bind() function of the UEFI driver is called after +checking the GUID. +The stop() function of the EFI_DRIVER_BINDING_PROTOCOL disconnects the child +controllers created by the UEFI driver and the UEFI driver. (In U-Boot v2013.03 +this is not yet completely implemented.) + +UEFI block IO driver +~~~~~~~~~~~~~~~~~~~~ + +The UEFI block IO driver supports devices exposing the EFI_BLOCK_IO_PROTOCOL. + +When connected it creates a new U-Boot block IO device with interface type +IF_TYPE_EFI, adds child controllers mapping the partitions, and installs the +EFI_SIMPLE_FILE_SYSTEM_PROTOCOL on these. This can be used together with the +software iPXE to boot from iSCSI network drives [4]. + +This driver is only available if U-Boot is configured with:: + + CONFIG_BLK=y + CONFIG_PARTITIONS=y + +Miscellaneous +------------- + +Load file 2 protocol +~~~~~~~~~~~~~~~~~~~~ + +The load file 2 protocol can be used by the Linux kernel to load the initial +RAM disk. U-Boot can be configured to provide an implementation with:: + + EFI_LOAD_FILE2_INITRD=y + +When the option is enabled the user can add the initrd path with the efidebug +command. + +Load options Boot#### have a FilePathList[] member. The first element of +the array (FilePathList[0]) is the EFI binary to execute. When an initrd +is specified the Device Path for the initrd is denoted by a VenMedia node +with the EFI_INITRD_MEDIA_GUID. Each entry of the array is terminated by the +'end of entire device path' subtype (0xff). If a user wants to define multiple +initrds, those must by separated by the 'end of this instance' identifier of +the end node (0x01). + +So our final format of the FilePathList[] is:: + + Loaded image - end node (0xff) - VenMedia - initrd_1 - [end node (0x01) - initrd_n ...] - end node (0xff) + +Links +----- + +* [1] http://uefi.org/specifications - UEFI specifications +* [2] https://github.com/ARM-software/ebbr/releases/download/v1.0/ebbr-v1.0.pdf - + Embedded Base Boot Requirements (EBBR) Specification - Release v1.0 +* [3] https://developer.arm.com/docs/den0044/latest/server-base-boot-requirements-system-software-on-arm-platforms-version-11 - + Server Base Boot Requirements System Software on ARM Platforms - Version 1.1 +* [4] :doc:`iscsi` +* [5] :doc:`../driver-model/index` diff --git a/roms/u-boot/doc/develop/version.rst b/roms/u-boot/doc/develop/version.rst new file mode 100644 index 000000000..a7797db41 --- /dev/null +++ b/roms/u-boot/doc/develop/version.rst @@ -0,0 +1,101 @@ +.. SPDX-License-Identifier: GPL-2.0+ +.. Copyright (c) 2013 The Chromium OS Authors. + +Version information +=================== + +U-Boot releases are named by year and patch level, for example 2020.10 means the +release that came out in October 2020. Release candidates are tagged every few +weeks as the project heads to the next release. So 2020.10-rc1 was the first +release candidate (RC), tagged soon after 2020.07 was released. + +See https://www.denx.de/wiki/view/U-Boot/ReleaseCycle for full details. + +Within the build system, various Makefile variables are created, making use of +VERSION, PATCHLEVEL and EXTRAVERSION defined at the top of 'Makefile'. There is +also SUBLEVEL available for downstream use. See also CONFIG_IDENT_STRING. + +Some variables end up in a generated header file at +include/generated/version_autogenerated.h and can be accessed from C source by +including <version.h> + +The following are available: + + UBOOTRELEASE (Makefile) + Full release version as a string. If this is not a tagged release, it also + includes the number of commits since the last tag as well as the the git + hash. If there are uncommitted changes a '-dirty' suffix is added too. + + This is written by scripts/setlocalversion (maintained by Linux) to + include/config/uboot.release and ends up in the UBOOTRELEASE Makefile + variable. + + Examples:: + + 2020.10-rc3 + 2021.01-rc5-00248-g60dd854f3ba-dirty + + PLAIN_VERSION (string #define) + This is UBOOTRELEASE but available in C source. + + Examples:: + + 2020.10 + 2021.01-rc5-00248-g60dd854f3ba-dirty + + UBOOTVERSION (Makefile) + This holds just the first three components of UBOOTRELEASE (i.e. not the + git hash, etc.) + + Examples:: + + 2020.10 + 2021.01-rc5 + + U_BOOT_VERSION (string #define) + "U-Boot " followed by UBOOTRELEASE, for example:: + + U-Boot 2020.10 + U-Boot 2021.01-rc5 + + This is used as part of the banner string when U-Boot starts. + + U_BOOT_VERSION_STRING (string #define) + U_BOOT_VERSION followed by build-time information + and CONFIG_IDENT_STRING. + + Examples:: + + U-Boot 2020.10 (Jan 06 2021 - 08:50:36 -0700) + U-Boot 2021.01-rc5-00248-g60dd854f3ba-dirty (Jan 06 2021 - 08:50:36 -0700) for spring + + U_BOOT_VERSION_NUM (integer #define) + Release year, e.g. 2021 for release 2021.01. Note + this is an integer, not a string. + + U_BOOT_VERSION_NUM_PATCH (integer #define) + Patch number, e.g. 1 for release 2020.01. Note + this is an integer, not a string. + +Build date/time is also included. See the generated file +include/generated/timestamp_autogenerated.h for the available +fields. For example:: + + #define U_BOOT_DATE "Jan 06 2021" (US format only) + #define U_BOOT_TIME "08:50:36" (24-hour clock) + #define U_BOOT_TZ "-0700" (Time zone in hours) + #define U_BOOT_DMI_DATE "01/06/2021" (US format only) + #define U_BOOT_BUILD_DATE 0x20210106 (hex yyyymmdd format) + #define U_BOOT_EPOCH 1609948236 + +The Epoch is the number of seconds since midnight on 1/1/70. You can convert +this to a time with:: + + $ date -u -d @1609948236 + Wed 06 Jan 2021 03:50:36 PM UTC + $ date -d 'Wed 06 Jan 2021 03:50:36 PM UTC' +%s + 1609948236 + +Every time you build U-Boot this will update based on the time +on your build machine. See 'Reproducible builds' if you want to +avoid that. |