From 2f6d2c726c2c6a23a89c92a61d4eba1f7d8c9c07 Mon Sep 17 00:00:00 2001 From: Sam Povilus Date: Tue, 4 Jun 2024 13:52:55 -0600 Subject: [PATCH 1/6] doc: Remove extraneous curly braces Update documentation to remove un-needed curly braces. Signed-off-by: Sam Povilus --- doc/usage/fit/source_file_format.rst | 28 ++++++++++++++-------------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/doc/usage/fit/source_file_format.rst b/doc/usage/fit/source_file_format.rst index b2b1e42bd73..310225d8390 100644 --- a/doc/usage/fit/source_file_format.rst +++ b/doc/usage/fit/source_file_format.rst @@ -192,13 +192,13 @@ type invalid Invalid Image aisimage Davinci AIS image atmelimage ATMEL ROM-Boot Image - copro Coprocessor Image} + copro Coprocessor Image fdt_legacy legacy Image with Flat Device Tree filesystem Filesystem Image firmware Firmware - firmware_ivt Firmware with HABv4 IVT } + firmware_ivt Firmware with HABv4 IVT flat_dt Flat Device Tree - fpga FPGA Image } + fpga FPGA Image gpimage TI Keystone SPL Image imx8image NXP i.MX8 Boot Image imx8mimage NXP i.MX8M Boot Image @@ -207,31 +207,31 @@ type kernel_noload Kernel Image (no loading done) kwbimage Kirkwood Boot Image lpc32xximage LPC32XX Boot Image - mtk_image MediaTek BootROM loadable Image } + mtk_image MediaTek BootROM loadable Image multi Multi-File Image mxsimage Freescale MXS Boot Image omapimage TI OMAP SPL With GP CH pblimage Freescale PBL Boot Image pmmc TI Power Management Micro-Controller Firmware ramdisk RAMDisk Image - rkimage Rockchip Boot Image } - rksd Rockchip SD Boot Image } - rkspi Rockchip SPI Boot Image } + rkimage Rockchip Boot Image + rksd Rockchip SD Boot Image + rkspi Rockchip SPI Boot Image script Script socfpgaimage Altera SoCFPGA CV/AV preloader socfpgaimage_v1 Altera SoCFPGA A10 preloader - spkgimage Renesas SPKG Image } + spkgimage Renesas SPKG Image standalone Standalone Program - stm32image STMicroelectronics STM32 Image } - sunxi_egon Allwinner eGON Boot Image } - sunxi_toc0 Allwinner TOC0 Boot Image } + stm32image STMicroelectronics STM32 Image + sunxi_egon Allwinner eGON Boot Image + sunxi_toc0 Allwinner TOC0 Boot Image tee Trusted Execution Environment Image ublimage Davinci UBL image vybridimage Vybrid Boot Image x86_setup x86 setup.bin - zynqimage Xilinx Zynq Boot Image } - zynqmpbif Xilinx ZynqMP Boot Image (bif) } - zynqmpimage Xilinx ZynqMP Boot Image } + zynqimage Xilinx Zynq Boot Image + zynqmpbif Xilinx ZynqMP Boot Image (bif) + zynqmpimage Xilinx ZynqMP Boot Image ==================== ================== compression From 9edc13159ec4c280961d02775db25e7588f1cecb Mon Sep 17 00:00:00 2001 From: Sam Povilus Date: Tue, 4 Jun 2024 13:52:56 -0600 Subject: [PATCH 2/6] doc: add clarity to what a "fpga" image is Update fit documentation to clarify that FPGA images are vendor specific and opaque bitstreams. Signed-off-by: Sam Povilus --- doc/usage/fit/source_file_format.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/usage/fit/source_file_format.rst b/doc/usage/fit/source_file_format.rst index 310225d8390..7727ab77c54 100644 --- a/doc/usage/fit/source_file_format.rst +++ b/doc/usage/fit/source_file_format.rst @@ -198,7 +198,7 @@ type firmware Firmware firmware_ivt Firmware with HABv4 IVT flat_dt Flat Device Tree - fpga FPGA Image + fpga FPGA Device Image (bitstream file, vendor specific) gpimage TI Keystone SPL Image imx8image NXP i.MX8 Boot Image imx8mimage NXP i.MX8M Boot Image From 5a116726cf757192eb23c6beab6c5365f3fcd4f5 Mon Sep 17 00:00:00 2001 From: Fiona Klute Date: Sat, 18 May 2024 12:47:05 +0200 Subject: [PATCH 3/6] doc: Detailed example for netconsole setup This adds details that I would have liked to have readily available, in particular how to activate the network interface before enabling netconsole, and how to integrate netconsole so you can use the U-Boot prompt. Signed-off-by: Fiona Klute Reviewed-by: Tony Dinh --- doc/usage/netconsole.rst | 35 ++++++++++++++++++++++++++++++++++- 1 file changed, 34 insertions(+), 1 deletion(-) diff --git a/doc/usage/netconsole.rst b/doc/usage/netconsole.rst index 2aa3b9ccc59..cb9a42d918a 100644 --- a/doc/usage/netconsole.rst +++ b/doc/usage/netconsole.rst @@ -18,7 +18,9 @@ broadcast address and port 6666 are used. If it is set to an IP address of 0 (or 0.0.0.0) then no messages are sent to the network. The source / listening port can be configured separately by setting the 'ncinport' environment variable and the destination port can be -configured by setting the 'ncoutport' environment variable. +configured by setting the 'ncoutport' environment variable. Note that +you need to set up the network interface (e.g. using DHCP) before it +can be used for network console. For example, if your server IP is 192.168.1.1, you could use:: @@ -107,3 +109,34 @@ as follows: Note that unlike the U-Boot implementation the Linux netconsole is unidirectional, i. e. you have console output only in Linux. + +Setup via environment +--------------------- + +If persistent environment is enabled in your U-Boot configuration, you +can configure the network console using the environment. For example: + +.. prompt:: bash => + + env set autoload no + env set hostname "u-boot" + env set bootdelay 5 + env set nc 'dhcp; env set stdout nc; env set stderr nc; env set stdin nc' + env set ncip '192.168.1.1' + env set preboot "${preboot}; run nc;" + env save + reset + +``autoload no`` tells the ``dhcp`` command to configure the network +interface without trying to load an image. ``hostname "u-boot"`` sets +the hostname to be sent in DHCP requests, so they are easy to +recognize in the DHCP server log. The command in ``nc`` calls ``dhcp`` +to make sure the network interface is set up before enabling +netconsole. + +Adding ``nc`` to ``preboot`` tells U-Boot to activate netconsole +before trying to find any boot options, so you can interact with it if +desired. + +``env save`` stores the settings persistently, and ``reset`` then +triggers a fresh start that will use the changed settings. From 7c53182e52f591746e64f611b5bf6d0b8ff79483 Mon Sep 17 00:00:00 2001 From: Fiona Klute Date: Sat, 18 May 2024 12:47:06 +0200 Subject: [PATCH 4/6] doc: Update netconsole examples, mention stderr Stderr was missing from the initial description and example. As I understand the env command documentation the subcommand style is preferred, though the old format is still fully supported. Signed-off-by: Fiona Klute Reviewed-by: Tony Dinh Reviewed-by: Heinrich Schuchardt --- doc/usage/netconsole.rst | 20 +++++++++++--------- 1 file changed, 11 insertions(+), 9 deletions(-) diff --git a/doc/usage/netconsole.rst b/doc/usage/netconsole.rst index cb9a42d918a..df27b78342f 100644 --- a/doc/usage/netconsole.rst +++ b/doc/usage/netconsole.rst @@ -3,10 +3,10 @@ Network console In U-Boot, we implemented the networked console via the standard "devices" mechanism, which means that you can switch between the -serial and network input/output devices by adjusting the 'stdin' and -'stdout' environment variables. To switch to the networked console, -set either of these variables to "nc". Input and output can be -switched independently. +serial and network input/output devices by adjusting the 'stdin', +'stdout', and 'stderr' environment variables. To switch to the +networked console, set either of these variables to "nc". Input and +output can be switched independently. The default buffer size can be overridden by setting CFG_NETCONSOLE_BUFFER_SIZE. @@ -22,12 +22,14 @@ configured by setting the 'ncoutport' environment variable. Note that you need to set up the network interface (e.g. using DHCP) before it can be used for network console. -For example, if your server IP is 192.168.1.1, you could use:: +For example, if your server IP is 192.168.1.1, you could use: - => setenv nc 'setenv stdout nc;setenv stdin nc' - => setenv ncip 192.168.1.1 - => saveenv - => run nc +.. prompt:: bash => + + env set nc 'env set stdout nc; env set stderr nc; env set stdin nc' + env set ncip '192.168.1.1' + env save + run nc On the host side, please use this script to access the console From b439b999316f62b2ae9d1ae0a296425a7ed70460 Mon Sep 17 00:00:00 2001 From: Tom Rini Date: Fri, 17 May 2024 11:49:29 -0600 Subject: [PATCH 5/6] doc: process.rst: Use subsubheading for "Phases of the Development Process" These sections which talk about the different phases of the development process should be using the subsubheading identifier. Signed-off-by: Tom Rini Reviewed-by: Quentin Schulz --- doc/develop/process.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/doc/develop/process.rst b/doc/develop/process.rst index 92477d05dd8..a66540a698c 100644 --- a/doc/develop/process.rst +++ b/doc/develop/process.rst @@ -34,7 +34,7 @@ It is followed by a *Stabilization Period*. The end of a Release Cycle is marked by the release of a new U-Boot version. Merge Window ------------- +^^^^^^^^^^^^ The Merge Window is the period when new patches get submitted (and hopefully accepted) for inclusion into U-Boot mainline. This period lasts for 21 days (3 @@ -44,7 +44,7 @@ This is the only time when new code (like support for new processors or new boards, or other new features or reorganization of code) is accepted. Twilight Time -------------- +^^^^^^^^^^^^^ Usually patches do not get accepted as they are - the peer review that takes place will usually require changes and resubmissions of the patches before they @@ -65,13 +65,13 @@ the Merge Window does not preclude patches that were already posted from being merged for the upcoming release. Stabilization Period --------------------- +^^^^^^^^^^^^^^^^^^^^ During the Stabilization Period only patches containing bug fixes get applied. Corner Cases ------------- +^^^^^^^^^^^^ Sometimes it is not clear if a patch contains a bug fix or not. For example, changes that remove dead code, unused macros etc. or From 0efc5a9f670144cad7f287711f25c69cba0fde39 Mon Sep 17 00:00:00 2001 From: Tom Rini Date: Fri, 17 May 2024 11:49:30 -0600 Subject: [PATCH 6/6] doc: process.rst: Document device tree resync rules Document the logic of when we do a full resync of the device trees used by OF_UPSTREAM as well as that cherry-picking is allowed as needed. Signed-off-by: Tom Rini Reviewed-by: Quentin Schulz --- doc/develop/devicetree/control.rst | 9 ++++++--- doc/develop/process.rst | 13 +++++++++++++ 2 files changed, 19 insertions(+), 3 deletions(-) diff --git a/doc/develop/devicetree/control.rst b/doc/develop/devicetree/control.rst index 4cc1457d4ea..ca4fb0b5b10 100644 --- a/doc/develop/devicetree/control.rst +++ b/doc/develop/devicetree/control.rst @@ -113,9 +113,12 @@ SoC being used via Kconfig and set `DEFAULT_DEVICE_TREE=/` when prompted by Kconfig. However, if `dts/upstream/` hasn't yet received devicetree source file for your -newly added board support then you can add corresponding devicetree source file -as `arch//dts/.dts`. To select that add `# CONFIG_OF_UPSTREAM is not -set` and set `DEFAULT_DEVICE_TREE=` when prompted by Kconfig. +newly added board support then one option is that you can add the corresponding +devicetree source file as `arch//dts/.dts`. To select that add `# +CONFIG_OF_UPSTREAM is not set` and set `DEFAULT_DEVICE_TREE=` when +prompted by Kconfig. Another option is that you can use use the "pick" option of +`dts/update-dts-subtree.sh` mentioned above to bring in the commits that you +need. This should include your CPU or SoC's devicetree file. On top of that any U-Boot specific tweaks (see: :ref:`dttweaks`) can be made for your board. diff --git a/doc/develop/process.rst b/doc/develop/process.rst index a66540a698c..0542b3fc124 100644 --- a/doc/develop/process.rst +++ b/doc/develop/process.rst @@ -108,6 +108,19 @@ Differences to the Linux Development Process In U-Boot, ``"-rc1"`` will only be released after all (or at least most of the) patches that were submitted during the merge window have been applied. +Resyncing of the device tree subtree +------------------------------------ + +As explained in :doc:`devicetree/control` some platforms make use of device tree +files which come from a git subtree that mirrors the Linux Kernel sources +itself. For our purposes, we only track releases and not release candidates for +merging in our tree. These merges follow the normal merge window rules. + +In the case of specific changes, such as bug fixes or new platform support, +these can be "cherry-picked" and are subject to the normal merge rules. For +example, a bug fix can come in later in the window but a full re-sync only +happens within the merge window itself. + .. _custodians: Custodians