diff options
Diffstat (limited to 'doc/develop')
| -rw-r--r-- | doc/develop/board_best_practices.rst | 26 | ||||
| -rw-r--r-- | doc/develop/bootstd.rst | 15 | ||||
| -rw-r--r-- | doc/develop/cedit.rst | 169 | ||||
| -rw-r--r-- | doc/develop/expo.rst | 48 | ||||
| -rw-r--r-- | doc/develop/falcon.rst | 258 | ||||
| -rw-r--r-- | doc/develop/index.rst | 3 | ||||
| -rw-r--r-- | doc/develop/printf.rst | 6 | ||||
| -rw-r--r-- | doc/develop/release_cycle.rst | 6 | ||||
| -rw-r--r-- | doc/develop/spl.rst | 13 | ||||
| -rw-r--r-- | doc/develop/trace.rst | 6 | ||||
| -rw-r--r-- | doc/develop/uefi/uefi.rst | 59 |
11 files changed, 562 insertions, 47 deletions
diff --git a/doc/develop/board_best_practices.rst b/doc/develop/board_best_practices.rst new file mode 100644 index 00000000000..f44401eab7d --- /dev/null +++ b/doc/develop/board_best_practices.rst @@ -0,0 +1,26 @@ +.. SPDX-License-Identifier: GPL-2.0+: + +Best Practices for Board Ports +============================== + +In addition to the regular best practices such as using :doc:`checkpatch` and +following the :doc:`docstyle` and the :doc:`codingstyle` there are some things +which are specific to creating a new board port. + +* Implement :doc:`bootstd` to ensure that most operating systems will be + supported by the platform. + +* The platform defconfig file must be generated via `make savedefconfig`. + +* The Kconfig and Kbuild infrastructure supports using "fragments" that can be + used to apply changes on top of a defconfig file. These can be useful for + many things such as: + + * Supporting different firmware locations (e.g. eMMC, SD, QSPI). + + * Multiple board variants when runtime detection is not desired. + + * Supporting different build types such as production and development. + + Kconfig fragments should reside in the board directory itself rather than in + the top-level `configs/` directory. diff --git a/doc/develop/bootstd.rst b/doc/develop/bootstd.rst index 7a2a69fdfce..c01e0971dc8 100644 --- a/doc/develop/bootstd.rst +++ b/doc/develop/bootstd.rst @@ -306,7 +306,7 @@ media device:: The bootdev device is typically created automatically in the media uclass' `post_bind()` method by calling `bootdev_setup_for_dev()` or -`bootdev_setup_sibling_blk()`. The code typically something like this:: +`bootdev_setup_for_sibling_blk()`. The code typically something like this:: /* dev is the Ethernet device */ ret = bootdev_setup_for_dev(dev, "eth_bootdev"); @@ -316,7 +316,7 @@ The bootdev device is typically created automatically in the media uclass' or:: /* blk is the block device (child of MMC device) - ret = bootdev_setup_sibling_blk(blk, "mmc_bootdev"); + ret = bootdev_setup_for_sibling_blk(blk, "mmc_bootdev"); if (ret) return log_msg_ret("bootdev", ret); @@ -677,11 +677,12 @@ Assuming the bootmeth is happy, or at least indicates that it is willing to try partition. If that works it tries to detect a file system. If that works then it calls the bootmeth device once more, this time to read the bootflow. -Note: At present a filesystem is needed for the bootmeth to be called on block -devices, simply because we don't have any examples where this is not the case. -This feature can be added as needed. Note that sandbox is a special case, since -in that case the host filesystem can be accessed even though the block device -is NULL. +Note: Normally a filesystem is needed for the bootmeth to be called on block +devices, but bootmeths which don't need that can set the BOOTMETHF_ANY_PART +flag to indicate that they can scan any partition. An example is the ChromiumOS +bootmeth which can store a kernel in a raw partition. Note also that sandbox is +a special case, since in that case the host filesystem can be accessed even +though the block device is NULL. If we take the example of the `bootmeth_extlinux` driver, this call ends up at `extlinux_read_bootflow()`. It has the filesystem ready, so tries various diff --git a/doc/develop/cedit.rst b/doc/develop/cedit.rst new file mode 100644 index 00000000000..63dff9d3f14 --- /dev/null +++ b/doc/develop/cedit.rst @@ -0,0 +1,169 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +Configuration Editor +==================== + +Introduction +------------ + +U-Boot provides a configuration editor which allows settings to be changed in +a GUI or text environment. + + +This feature is still in development and has a number of limitations. For +example, cedit only supports menu items (there is no numeric or text entry), +provides no support for colour text and does not support scrolling. Still it is +possible to use it for simple applications. + + +Overview +-------- + +The configuration editor makes use of :doc:`expo` to build a description of the +configuration screens and allow user to interact with it. + +To create a single-scene cedit for your application: + +#. Design the scene, i.e. the objects that need to be present and what their + possible values are + +#. Enter this in .dts format + +#. Create a header file containing the IDs + +#. Run the 'expo.py' tool to generate a .dtb file containing the layout, which + can be used by U-Boot + +#. Use the :doc:`../usage/cmd/cedit` to create the cedit, read the settings, + present the cedit to the user and save the settings afterwards. + +Each of these is described in a separate section. See :ref:`expo_example` for +an example file. + + +Design a scene +-------------- + +Using a piece of paper or a drawing tool, lay out the objects you want in your +scene. Typically you will use the default layout engine, which simply puts items +one after the other from top to bottom. So use a single column and show the +prompt and value for each object. + +For menu items, show one of the values, but keep in mind what else you need. + + +Create an expo-format file +-------------------------- + +The description is in the form of a devicetree file, as documented at +:ref:`expo_format`. Since everything in an expo has an ID number (an integer +greater than 1) the description is written terms of these IDs. They each have +an enum value. which is typically taken care of by the `expo.py` tool. + +The expo should have a `scenes` node with a named scene as a subnode. Within the +scene, add properties for the scene, then a subnode for each object in the +scene. + +All object nodes require an `id` value and a `type` property. Other properties +depend on the type. For example, a menu has a `title` and an `item-label` list +proving the text for the menu items, as well as an `item-id` list providing the +ID of each menu item, so it can be selected. + +Text properties may have two variants. For example `title` specifies the title +of a menu, but you can instead use `title-id` to specify the string ID to use as +the title. String are defined in a separate area, common to the whole expo, +which contains a subnode for each string. Within that subnode are the ID and the +`value` (i.e. the text). For now only English is supported, but in future it may +be possible to append a language identifier to provide other values (e.g. +'value-es' for Spanish). + + +Create an ID header-file +------------------------ + +Expo needs to know the integer value to use for every ID referenced in your +expo-format file. For example, if you have defined a `cpu-speed` node with an +id of `ID_CPU_SPEED`, then Expo needs to know the value of `ID_CPU_SPEED`. + +When you write C code to use the expo, you may need to know the IDs. For +example, to find which value the user selected in `cpu-speed` menu, you must +use the `ID_CPU_SPEED` ID. The ID is the only way to refer to anything in Expo. + +Since we need a shared set of IDs, it is best to have a header file containing +them. Expo supports doing this with an enum, where every ID is listed in the +enum:: + + enum { + ZERO, + + ID_PROMPT, + + ID_SCENE1, + ID_SCENE1_TITLE, + ... + }; + +The C compiler can parse this directly. The `expo.py` tool parses it for expo. + +Create a header file containing every ID mentioned in your expo. Try to group +related things together. + + +Build the expo layout +--------------------- + +Use the `expo.py` tool to build a .dtb for your expo:: + + ./tools/expo.py -e expo_ids.h -l expo_layout.dts -o expo.dtb + +This uses the enum in the provided header file to get the ID numbers, grabs +the `.dts` file, inserts the ID numbers and then uses the devicetree compiler to +build a `.dtb` file. + +If you get an error:: + + Devicetree compiler error: + Error: <stdin>:9.19-20 syntax error + FATAL ERROR: Unable to parse input tree + +that means that something is wrong with your syntax, or perhaps you have an ID +in the `.dts` file that is not mentioned in your enum. Check both files and try +again. + + +Use the command interface +------------------------- + +See the :doc:`../usage/cmd/cedit` command for information on available commands. +Typically you will use `cedit load` to load the `.dtb` file and `cedit run` to +let the user interact with it. + + +Multiple scenes +--------------- + +Expo supports multiple scenes but has no pre-determined way of moving between +them. You could use selection of a menu item as a signal to change the scene, +but this is not currently implemented in the cedit code (see `cedit_run()`). + + +Themes +------ + +The configuration editor uses simple expo themes. The theme is read from +`/bootstd/cedit-theme` in the devicetree. + + +Reading and writing settings +---------------------------- + +Cedit provides several options for persistent settings: + +- Writing an FDT file to a filesystem +- Writing to U-Boot's environment variables, which are then typically stored in + a persistent manner +- Writing to CMOS RAM registers (common on x86 machines) + +For now, reading and writing settings is not automatic. See the +:doc:`../usage/cmd/cedit` for how to do this on the command line or in a +script. diff --git a/doc/develop/expo.rst b/doc/develop/expo.rst index 2ac4af232da..f13761995d3 100644 --- a/doc/develop/expo.rst +++ b/doc/develop/expo.rst @@ -317,6 +317,18 @@ id Specifies the ID of the object. This is used when referring to the object. +Where CMOS RAM is used for reading and writing settings, the following +additional properties are required: + +start-bit + Specifies the first bit in the CMOS RAM to use for this setting. For a RAM + with 0x100 bytes, there are 0x800 bit locations. For example, register 0x80 + holds bits 0x400 to 0x407. + +bit-length + Specifies the number of CMOS RAM bits to use for this setting. The bits + extend from `start-bit` to `start-bit + bit-length - 1`. Note that the bits + must be contiguous. Menu nodes have the following additional properties: @@ -358,6 +370,9 @@ The `expo_arrange()` function can be called to arrange the expo objects in a suitable manner. For each scene it puts the title at the top, the prompt at the bottom and the objects in order from top to bottom. + +.. _expo_example: + Expo format example ~~~~~~~~~~~~~~~~~~~ @@ -367,22 +382,27 @@ strings are provided inline in the nodes where they are used. :: - #define ID_PROMPT 1 - #define ID_SCENE1 2 - #define ID_SCENE1_TITLE 3 + /* this comment is parsed by the expo.py tool to insert the values below + + enum { + ZERO, + ID_PROMPT, + ID_SCENE1, + ID_SCENE1_TITLE, - #define ID_CPU_SPEED 4 - #define ID_CPU_SPEED_TITLE 5 - #define ID_CPU_SPEED_1 6 - #define ID_CPU_SPEED_2 7 - #define ID_CPU_SPEED_3 8 + ID_CPU_SPEED, + ID_CPU_SPEED_TITLE, + ID_CPU_SPEED_1, + ID_CPU_SPEED_2, + ID_CPU_SPEED_3, - #define ID_POWER_LOSS 9 - #define ID_AC_OFF 10 - #define ID_AC_ON 11 - #define ID_AC_MEMORY 12 + ID_POWER_LOSS, + ID_AC_OFF, + ID_AC_ON, + ID_AC_MEMORY, - #define ID_DYNAMIC_START 13 + ID_DYNAMIC_START, + */ &cedit { dynamic-start = <ID_DYNAMIC_START>; @@ -465,7 +485,7 @@ Some ideas for future work: - Support unicode - Support curses for proper serial-terminal menus - Add support for large menus which need to scroll -- Add support for reading and writing configuration settings with cedit +- Update expo.py tool to check for overlapping names and CMOS locations .. Simon Glass <sjg@chromium.org> .. 7-Oct-22 diff --git a/doc/develop/falcon.rst b/doc/develop/falcon.rst new file mode 100644 index 00000000000..a569d1a2951 --- /dev/null +++ b/doc/develop/falcon.rst @@ -0,0 +1,258 @@ +.. SPDX-License-Identifier: GPL-2.0-or-later + +Falcon Mode +=========== + +Introduction +------------ + +This document provides an overview of how to add support for Falcon Mode +to a board. + +Falcon Mode is introduced to speed up the booting process, allowing +to boot a Linux kernel (or whatever image) without a full blown U-Boot. + +Falcon Mode relies on the SPL framework. In fact, to make booting faster, +U-Boot is split into two parts: the SPL (Secondary Program Loader) and U-Boot +image. In most implementations, SPL is used to start U-Boot when booting from +a mass storage, such as NAND or SD-Card. SPL has now support for other media, +and can generally be seen as a way to start an image performing the minimum +required initialization. SPL mainly initializes the RAM controller, and then +copies U-Boot image into the memory. + +The Falcon Mode extends this way allowing to start the Linux kernel directly +from SPL. A new command is added to U-Boot to prepare the parameters that SPL +must pass to the kernel, using ATAGS or Device Tree. + +In normal mode, these parameters are generated each time before +loading the kernel, passing to Linux the address in memory where +the parameters can be read. +With Falcon Mode, this snapshot can be saved into persistent storage and SPL is +informed to load it before running the kernel. + +To boot the kernel, these steps under a Falcon-aware U-Boot are required: + +1. Boot the board into U-Boot. + After loading the desired legacy-format kernel image into memory (and DT as + well, if used), use the "spl export" command to generate the kernel + parameters area or the DT. U-Boot runs as when it boots the kernel, but + stops before passing the control to the kernel. + +2. Save the prepared snapshot into persistent media. + The address where to save it must be configured into board configuration + file (CONFIG_CMD_SPL_NAND_OFS for NAND). + +3. Boot the board into Falcon Mode. SPL will load the kernel and copy + the parameters which are saved in the persistent area to the required + address. If a valid uImage is not found at the defined location, U-Boot + will be booted instead. + +It is required to implement a custom mechanism to select if SPL loads U-Boot +or another image. + +The value of a GPIO is a simple way to operate the selection, as well as +reading a character from the SPL console if CONFIG_SPL_CONSOLE is set. + +Falcon Mode is generally activated by setting CONFIG_SPL_OS_BOOT. This tells +SPL that U-Boot is not the only available image that SPL is able to start. + +Configuration +------------- + +CONFIG_CMD_SPL + Enable the "spl export" command. + The command "spl export" is then available in U-Boot mode. + +CONFIG_SYS_SPL_ARGS_ADDR + Address in RAM where the parameters must be copied by SPL. + In most cases, it is <start_of_ram> + 0x100. + +CONFIG_SYS_NAND_SPL_KERNEL_OFFS + Offset in NAND where the kernel is stored + +CONFIG_CMD_SPL_NAND_OFS + Offset in NAND where the parameters area was saved. + +CONFIG_CMD_SPL_NOR_OFS + Offset in NOR where the parameters area was saved. + +CONFIG_CMD_SPL_WRITE_SIZE + Size of the parameters area to be copied + +CONFIG_SPL_OS_BOOT + Activate Falcon Mode. + +Function that a board must implement +------------------------------------ + +void spl_board_prepare_for_linux(void) + optional, called from SPL before starting the kernel + +spl_start_uboot() + required, returns "0" if SPL should start the kernel, "1" if U-Boot + must be started. + +Environment variables +--------------------- + +A board may chose to look at the environment for decisions about falcon +mode. In this case the following variables may be supported: + +boot_os + Set to yes/Yes/true/True/1 to enable booting to OS, + any other value to fall back to U-Boot (including unset) + +falcon_args_file + Filename to load as the 'args' portion of falcon mode rather than the + hard-coded value. + +falcon_image_file + Filename to load as the OS image portion of falcon mode rather than the + hard-coded value. + +Using spl command +----------------- + +spl - SPL configuration + +Usage:: + + spl export <img=atags|fdt> [kernel_addr] [initrd_addr] [fdt_addr ] + +img + "atags" or "fdt" + +kernel_addr + kernel is loaded as part of the boot process, but it is not started. + This is the address where a kernel image is stored. + +initrd_addr + Address of initial ramdisk + can be set to "-" if fdt_addr without initrd_addr is used + +fdt_addr + in case of fdt, the address of the device tree. + +The *spl export* command does not write to a storage media. The user is +responsible to transfer the gathered information (assembled ATAGS list +or prepared FDT) from temporary storage in RAM into persistent storage +after each run of *spl export*. Unfortunately the position of temporary +storage can not be predicted nor provided at command line, it depends +highly on your system setup and your provided data (ATAGS or FDT). +However at the end of an successful *spl export* run it will print the +RAM address of temporary storage. The RAM address of FDT will also be +set in the environment variable *fdtargsaddr*, the new length of the +prepared FDT will be set in the environment variable *fdtargslen*. +These environment variables can be used in scripts for writing updated +FDT to persistent storage. + +Now the user have to save the generated BLOB from that printed address +to the pre-defined address in persistent storage +(CONFIG_CMD_SPL_NAND_OFS in case of NAND). +The following example shows how to prepare the data for Falcon Mode on +twister board with ATAGS BLOB. + +The *spl export* command is prepared to work with ATAGS and FDT. However, +using FDT is at the moment untested. The ppc port (see a3m071 example +later) prepares the fdt blob with the fdt command instead. + + +Usage on the twister board +-------------------------- + +Using mtd names with the following (default) configuration +for mtdparts:: + + device nand0 <omap2-nand.0>, # parts = 9 + #: name size offset mask_flags + 0: MLO 0x00080000 0x00000000 0 + 1: u-boot 0x00100000 0x00080000 0 + 2: env1 0x00040000 0x00180000 0 + 3: env2 0x00040000 0x001c0000 0 + 4: kernel 0x00600000 0x00200000 0 + 5: bootparms 0x00040000 0x00800000 0 + 6: splashimg 0x00200000 0x00840000 0 + 7: mini 0x02800000 0x00a40000 0 + 8: rootfs 0x1cdc0000 0x03240000 0 + +:: + + twister => nand read 82000000 kernel + + NAND read: device 0 offset 0x200000, size 0x600000 + 6291456 bytes read: OK + +Now the kernel is in RAM at address 0x82000000:: + + twister => spl export atags 0x82000000 + ## Booting kernel from Legacy Image at 82000000 ... + Image Name: Linux-3.5.0-rc4-14089-gda0b7f4 + Image Type: ARM Linux Kernel Image (uncompressed) + Data Size: 3654808 Bytes = 3.5 MiB + Load Address: 80008000 + Entry Point: 80008000 + Verifying Checksum ... OK + Loading Kernel Image ... OK + OK + cmdline subcommand not supported + bdt subcommand not supported + Argument image is now in RAM at: 0x80000100 + +The result can be checked at address 0x80000100:: + + twister => md 0x80000100 + 80000100: 00000005 54410001 00000000 00000000 ......AT........ + 80000110: 00000000 00000067 54410009 746f6f72 ....g.....ATroot + 80000120: 65642f3d 666e2f76 77722073 73666e20 =/dev/nfs rw nfs + +The parameters generated with this step can be saved into NAND at the offset +0x800000 (value for twister for CONFIG_CMD_SPL_NAND_OFS):: + + nand erase.part bootparms + nand write 0x80000100 bootparms 0x4000 + +Now the parameters are stored into the NAND flash at the address +CONFIG_CMD_SPL_NAND_OFS (=0x800000). + +Next time, the board can be started into Falcon Mode moving the +setting the GPIO (on twister GPIO 55 is used) to kernel mode. + +The kernel is loaded directly by the SPL without passing through U-Boot. + +Example with FDT: a3m071 board +------------------------------- + +To boot the Linux kernel from the SPL, the DT blob (fdt) needs to get +prepared/patched first. U-Boot usually inserts some dynamic values into +the DT binary (blob), e.g. autodetected memory size, MAC addresses, +clocks speeds etc. To generate this patched DT blob, you can use +the following command: + +1. Load fdt blob to SDRAM:: + + => tftp 1800000 a3m071/a3m071.dtb + +2. Set bootargs as desired for Linux booting (e.g. flash_mtd):: + + => run mtdargs addip2 addtty + +3. Use "fdt" commands to patch the DT blob:: + + => fdt addr 1800000 + => fdt boardsetup + => fdt chosen + +4. Display patched DT blob (optional):: + + => fdt print + +5. Save fdt to NOR flash:: + + => erase fc060000 fc07ffff + => cp.b 1800000 fc060000 10000 + ... + + +Falcon Mode was presented at the RMLL 2012. Slides are available at: + +http://schedule2012.rmll.info/IMG/pdf/LSM2012_UbootFalconMode_Babic.pdf diff --git a/doc/develop/index.rst b/doc/develop/index.rst index ddbf8dad4a1..0d12484ace8 100644 --- a/doc/develop/index.rst +++ b/doc/develop/index.rst @@ -9,6 +9,7 @@ General .. toctree:: :maxdepth: 1 + board_best_practices codingstyle designprinciples docstyle @@ -37,6 +38,7 @@ Implementation driver-model/index environment expo + cedit event global_data logging @@ -45,6 +47,7 @@ Implementation printf smbios spl + falcon uefi/index vbe version diff --git a/doc/develop/printf.rst b/doc/develop/printf.rst index 7b9aea06876..99d05061b14 100644 --- a/doc/develop/printf.rst +++ b/doc/develop/printf.rst @@ -105,19 +105,19 @@ for the individual integer types. =================== ================== Type Format specifier =================== ================== -bool %d, %x +bool %d, %x char %d, %x unsigned char %u, %x short %d, %x unsigned short %u, %x int %d, %x -unsigned int %d, %x +unsigned int %u, %x long %ld, %lx unsigned long %lu, %lx long long %lld, %llx unsigned long long %llu, %llx off_t %llu, %llx -ptr_diff_t %td, %tx +ptr_diff_t %td, %tx fdt_addr_t %pa, see pointers fdt_size_t %pa, see pointers phys_addr_t %pa, see pointers diff --git a/doc/develop/release_cycle.rst b/doc/develop/release_cycle.rst index 46bc200e486..50d33df4211 100644 --- a/doc/develop/release_cycle.rst +++ b/doc/develop/release_cycle.rst @@ -52,7 +52,7 @@ Current Status * The Merge Window for the next release (v2023.10) is **closed**. -* The next branch is now **closed**. +* The next branch is now **open**. * Release "v2023.10" is scheduled for 02 October 2023. @@ -66,9 +66,9 @@ For the next scheduled release, release candidates were made on:: * U-Boot v2023.10-rc1 was released on Tue 25 July 2023. -.. * U-Boot v2023.10-rc2 was released on Mon 07 August 2023. +* U-Boot v2023.10-rc2 was released on Mon 07 August 2023. -.. * U-Boot v2023.10-rc3 was released on Mon 21 August 2023. +* U-Boot v2023.10-rc3 was released on Mon 21 August 2023. .. * U-Boot v2023.10-rc4 was released on Mon 04 September 2023. diff --git a/doc/develop/spl.rst b/doc/develop/spl.rst index a1515a7b43b..76e87f07c72 100644 --- a/doc/develop/spl.rst +++ b/doc/develop/spl.rst @@ -77,10 +77,11 @@ To check whether a feature is enabled, use CONFIG_IS_ENABLED():: This checks CONFIG_CLK for the main build, CONFIG_SPL_CLK for the SPL build, CONFIG_TPL_CLK for the TPL build, etc. -U-Boot Phases -------------- +U-Boot Boot Phases +------------------ -U-Boot boots through the following phases: +U-Boot goes through the following boot phases where TPL, VPL, SPL are optional. +While many boards use SPL, less use TPL. TPL Very early init, as tiny as possible. This loads SPL (or VPL if enabled). @@ -97,6 +98,12 @@ SPL U-Boot U-Boot proper, containing the command line and boot logic. +Further usages of U-Boot SPL comprise: + +* Launching BL31 of ARM Trusted Firmware which invokes main U-Boot as BL33 +* launching EDK II +* launching Linux kernel +* launching RISC-V OpenSBI which invokes main U-Boot Checking the boot phase ----------------------- diff --git a/doc/develop/trace.rst b/doc/develop/trace.rst index 9bbe1345d2d..546862020b1 100644 --- a/doc/develop/trace.rst +++ b/doc/develop/trace.rst @@ -139,7 +139,7 @@ There is a -f option available to select a function graph: .. code-block:: console - $ ./sandbox/tools/proftool -m sandbox/System.map -t trace -f funcgraph dump-ftrace >trace.dat + $ ./sandbox/tools/proftool -m sandbox/System.map -t trace -f funcgraph dump-ftrace -o trace.dat Again, you can use kernelshark or trace-cmd to look at the output. In this case you will see the time taken by each function shown against its exit record. @@ -171,7 +171,7 @@ command: .. code-block:: console - $ ./sandbox/tools/proftool -m sandbox/System.map -t trace dump-flamegraph >trace.fg + $ ./sandbox/tools/proftool -m sandbox/System.map -t trace dump-flamegraph -o trace.fg $ flamegraph.pl trace.fg >trace.svg You can load the .svg file into a viewer. If you use Chrome (and some other @@ -191,7 +191,7 @@ spend in each call stack: .. code-block:: console - $ ./sandbox/tools/proftool -m sandbox/System.map -t trace dump-flamegraph -f timing >trace.fg + $ ./sandbox/tools/proftool -m sandbox/System.map -t trace dump-flamegraph -f timing -o trace.fg $ flamegraph.pl trace.fg >trace.svg Note that trace collection does slow down execution so the timings will be diff --git a/doc/develop/uefi/uefi.rst b/doc/develop/uefi/uefi.rst index a7a41f2facf..68f9b332d15 100644 --- a/doc/develop/uefi/uefi.rst +++ b/doc/develop/uefi/uefi.rst @@ -318,6 +318,9 @@ Run the following command --guid <image GUID> \ <capsule_file_name> +Capsule with firmware version +***************************** + The UEFI specification does not define the firmware versioning mechanism. EDK II reference implementation inserts the FMP Payload Header right before the payload. It coutains the fw_version and lowest supported version, @@ -345,6 +348,43 @@ add --fw-version option in mkeficapsule tool. If the --fw-version option is not set, FMP Payload Header is not inserted and fw_version is set as 0. +Capsule Generation through binman +********************************* + +Support has also been added to generate capsules during U-Boot build +through binman. This requires the platform's DTB to be populated with +the capsule entry nodes for binman. The capsules then can be generated +by specifying the capsule parameters as properties in the capsule +entry node. + +Check the test/py/tests/test_efi_capsule/capsule_gen_binman.dts file +as reference for how a typical binman node for capsule generation +looks like. For generating capsules as part of the platform's build, a +capsule node would then have to be included into the platform's +devicetree. + +A typical binman node for generating a capsule would look like:: + + capsule { + filename = "u-boot.capsule"; + efi-capsule { + image-index = <0x1>; + image-guid = "09d7cf52-0720-4710-91d1-08469b7fe9c8"; + + u-boot { + }; + }; + }; + +In the above example, a capsule file named u-boot.capsule will be +generated with u-boot.bin as it's input payload. The capsule +generation parameters like image-index and image-guid are being +specified as properties. Similarly, other properties like the private +and public key certificate can be specified for generating signed +capsules. Refer :ref:`etype_efi_capsule` for documentation about the +efi-capsule binman entry type, which describes all the properties that +can be specified. + Performing the update ********************* @@ -522,20 +562,11 @@ and used by the steps highlighted below. ... } -You can do step-4 manually with - -.. code-block:: console - - $ dtc -@ -I dts -O dtb -o signature.dtbo signature.dts - $ fdtoverlay -i orig.dtb -o new.dtb -v signature.dtbo - -where signature.dts looks like:: - - &{/} { - signature { - capsule-key = /incbin/("CRT.esl"); - }; - }; +You can perform step-4 through the Kconfig symbol +CONFIG_EFI_CAPSULE_ESL_FILE. This symbol points to the esl file +generated in step-2. Once the symbol has been populated with the path +to the esl file, it will automatically get embedded into the +platform's dtb as part of U-Boot build. Anti-rollback Protection ************************ |