[PATCH] doc: board: bcm7xxx: Convert to reStructuredText format
Heinrich Schuchardt
xypron.glpk at gmx.de
Mon Feb 13 08:49:34 CET 2023
On 2/11/23 01:24, Thomas Fitzsimmons wrote:
> Convert the documentation for the Broadcom BCM7445 and BCM7260 boards
> to reStructuredText format and add the new filename to
> doc/board/broadcom/index.rst.
> ---
> doc/README.bcm7xxx | 156 ---------------------------
> doc/board/broadcom/bcm7xxx.rst | 186 +++++++++++++++++++++++++++++++++
> doc/board/broadcom/index.rst | 1 +
> 3 files changed, 187 insertions(+), 156 deletions(-)
> delete mode 100644 doc/README.bcm7xxx
> create mode 100644 doc/board/broadcom/bcm7xxx.rst
>
> diff --git a/doc/README.bcm7xxx b/doc/README.bcm7xxx
> deleted file mode 100644
> index 6839da5f97..0000000000
> --- a/doc/README.bcm7xxx
> +++ /dev/null
> @@ -1,156 +0,0 @@
> -Summary
> -=======
> -
> -This document describes how to use U-Boot on the Broadcom 7445 SoC, as
> -a third stage bootloader loaded by Broadcom's BOLT bootloader.
> -
> -BOLT loads U-Boot as a generic ELF binary. Some U-Boot features such
> -as networking are not yet available but other important features are,
> -including:
> -
> - - ext4 file system traversal
> -
> - - support for loading FIT images
> -
> - - advanced scripting
> -
> - - support for FIT-provided DTBs instead of relying on the
> - BOLT-provided DTB
> -
> -A customized version of this port has been used in production. The
> -same approach may work on other BCM7xxx boards, with some
> -configuration adjustments and memory layout experimentation.
> -
> -Build
> -=====
> -
> -make bcm7445_defconfig
> -make
> -${CROSS_COMPILE}strip u-boot
> -
> -Run
> -===
> -
> -To tell U-Boot which serial port to use for its console, set the
> -"stdout-path" property in the "/chosen" node of the BOLT-generated
> -device tree. For example:
> -
> -BOLT> dt add prop chosen stdout-path s serial0:115200n8
> -
> -Flash the u-boot binary into board storage, then invoke it from BOLT.
> -For example:
> -
> -BOLT> boot -bsu -elf flash0.u-boot1
> -
> -This port assumes that I-cache and D-cache are already enabled when
> -U-Boot is entered.
> -
> -Flattened Image Tree Support
> -============================
> -
> -What follows is an example FIT image source file. Build it with:
> -
> -mkimage -f image.its image.itb
> -
> -Booting the resulting image.itb was tested on BOLT v1.20, with the
> -following kernels:
> -
> -https://github.com/Broadcom/stblinux-3.14
> -https://github.com/Broadcom/stblinux-4.1
> -https://github.com/Broadcom/stblinux-4.9
> -
> -and with a generic ARMv7 root file system.
> -
> -image.its:
> -/dts-v1/;
> -/ {
> - description = "BCM7445 FIT";
> - images {
> - kernel at 1 {
> - description = "Linux kernel";
> - /*
> - * This kernel image output format can be
> - * generated with:
> - *
> - * make vmlinux
> - * ${CROSS_COMPILE}objcopy -O binary -S vmlinux vmlinux.bin
> - * gzip -9 vmlinux.bin
> - *
> - * For stblinux-3.14, the specific Broadcom
> - * board type should be configured in the
> - * kernel, for example CONFIG_BCM7445D0=y.
> - */
> - data = /incbin/("<vmlinux.bin.gz>");
> - type = "kernel";
> - arch = "arm";
> - os = "linux";
> - compression = "gzip";
> - load = <0x8000>;
> - entry = <0x8000>;
> - hash at 1 {
> - algo = "sha256";
> - };
> - };
> - ramdisk at 1 {
> - description = "Initramfs root file system";
> - data = /incbin/("<initramfs.cpio.gz>");
> - type = "ramdisk";
> - arch = "arm";
> - os = "linux";
> - compression = "gzip";
> - /*
> - * Set the environment variable initrd_high to
> - * 0xffffffff, and set "load" and "entry" here
> - * to 0x0 to keep initramfs in-place and to
> - * accommodate stblinux bmem/CMA reservations.
> - */
> - load = <0x0>;
> - entry = <0x0>;
> - hash at 1 {
> - algo = "sha256";
> - };
> - };
> - fdt at 1 {
> - description = "Device tree dumped from BOLT";
> - /*
> - * This DTB should be similar to the
> - * BOLT-generated device tree, after BOLT has
> - * done its runtime modifications to it. For
> - * example, it can be dumped from within
> - * U-Boot (at ${fdtcontroladdr}), after BOLT
> - * has loaded U-Boot. The result can be added
> - * to the Linux source tree as a .dts file.
> - *
> - * To support modifications to the device tree
> - * in-place in U-Boot, add to Linux's
> - * arch/arm/boot/dts/Makefile:
> - *
> - * DTC_FLAGS ?= -p 4096
> - *
> - * This will leave some padding in the DTB and
> - * thus reserve room for node additions.
> - *
> - * Also, set the environment variable fdt_high
> - * to 0xffffffff to keep the DTB in-place and
> - * to accommodate stblinux bmem/CMA
> - * reservations.
> - */
> - data = /incbin/("<bolt-<version>.dtb");
> - type = "flat_dt";
> - arch = "arm";
> - compression = "none";
> - hash at 1 {
> - algo = "sha256";
> - };
> - };
> - };
> - configurations {
> - default = "conf at bcm7445";
> - conf at bcm7445 {
> - description = "BCM7445 configuration";
> - kernel = "kernel at 1";
> - ramdisk = "ramdisk at 1";
> - fdt = "fdt at 1";
> - };
> - };
> -};
> diff --git a/doc/board/broadcom/bcm7xxx.rst b/doc/board/broadcom/bcm7xxx.rst
> new file mode 100644
> index 0000000000..6231431a67
> --- /dev/null
> +++ b/doc/board/broadcom/bcm7xxx.rst
> @@ -0,0 +1,186 @@
> +.. SPDX-License-Identifier: GPL-2.0+
> +.. Copyright (C) 2018, 2023 Thomas Fitzsimmons <fitzsim at fitzsim.org>
> +
> +BCM7445 and BCM7260
> +===================
> +
> +About this
> +----------
Can we leave this as 'Summary'? Or better drop the heading as it is
expected that an introduction follows.
Acked-by: Heinrich Schuchardt <xypron.glpk at gmx.de>
> +
> +This document describes how to use U-Boot on the Broadcom 7445 and
> +Broadcom 7260 SoC, as a third stage bootloader loaded by Broadcom's
> +BOLT bootloader.
> +
> +BOLT loads U-Boot as a generic ELF binary. Some U-Boot features such
> +as networking are not implemented but other important features are,
> +including:
> +
> +* ext4 file system traversal
> +* support for loading FIT images
> +* advanced scripting
> +* support for FIT-provided DTBs instead of relying on the BOLT-provided DTB
> +
> +A customized version of this port has been used in production. The
> +same approach may work on other BCM7xxx boards, with some
> +configuration adjustments and memory layout experimentation.
> +
> +Configure
> +---------
> +
> +BCM7445
> +^^^^^^^
> +
> +.. code-block:: console
> +
> + $ make bcm7445_defconfig
> +
> +BCM7260
> +^^^^^^^
> +
> +.. code-block:: console
> +
> + $ make bcm7260_defconfig
> +
> +Build
> +-----
> +
> +.. code-block:: console
> +
> + $ make
> + $ ${CROSS_COMPILE}strip u-boot
> +
> +Run
> +---
> +
> +To tell U-Boot which serial port to use for its console, set the
> +``stdout-path`` property in the ``/chosen`` node of the BOLT-generated
> +device tree. For example:
> +
> +::
> +
> + BOLT> dt add prop chosen stdout-path s serial0:115200n8
> +
> +Flash the ``u-boot`` binary into board storage, then invoke it from
> +BOLT. For example:
> +
> +::
> +
> + BOLT> boot -bsu -elf flash0.u-boot1
> +
> +This port assumes that I-cache and D-cache are already enabled when
> +U-Boot is entered.
> +
> +Flattened Image Tree Support
> +----------------------------
> +
> +What follows is an example FIT image source file. Build it with:
> +
> +.. code-block:: console
> +
> + $ mkimage -f image.its image.itb
> +
> +Booting the resulting ``image.itb`` was tested on BOLT v1.20, with the
> +following kernels:
> +
> +* https://github.com/Broadcom/stblinux-3.14
> +* https://github.com/Broadcom/stblinux-4.1
> +* https://github.com/Broadcom/stblinux-4.9
> +
> +and with a generic ARMv7 root file system.
> +
> +**image.its**
> +
> +::
> +
> + /dts-v1/;
> + / {
> + description = "BCM7445 FIT";
> + images {
> + kernel at 1 {
> + description = "Linux kernel";
> + /*
> + * This kernel image output format can be
> + * generated with:
> + *
> + * make vmlinux
> + * ${CROSS_COMPILE}objcopy -O binary -S vmlinux vmlinux.bin
> + * gzip -9 vmlinux.bin
> + *
> + * For stblinux-3.14, the specific Broadcom
> + * board type should be configured in the
> + * kernel, for example CONFIG_BCM7445D0=y.
> + */
> + data = /incbin/("<vmlinux.bin.gz>");
> + type = "kernel";
> + arch = "arm";
> + os = "linux";
> + compression = "gzip";
> + load = <0x8000>;
> + entry = <0x8000>;
> + hash at 1 {
> + algo = "sha256";
> + };
> + };
> + ramdisk at 1 {
> + description = "Initramfs root file system";
> + data = /incbin/("<initramfs.cpio.gz>");
> + type = "ramdisk";
> + arch = "arm";
> + os = "linux";
> + compression = "gzip";
> + /*
> + * Set the environment variable initrd_high to
> + * 0xffffffff, and set "load" and "entry" here
> + * to 0x0 to keep initramfs in-place and to
> + * accommodate stblinux bmem/CMA reservations.
> + */
> + load = <0x0>;
> + entry = <0x0>;
> + hash at 1 {
> + algo = "sha256";
> + };
> + };
> + fdt at 1 {
> + description = "Device tree dumped from BOLT";
> + /*
> + * This DTB should be similar to the
> + * BOLT-generated device tree, after BOLT has
> + * done its runtime modifications to it. For
> + * example, it can be dumped from within
> + * U-Boot (at ${fdtcontroladdr}), after BOLT
> + * has loaded U-Boot. The result can be added
> + * to the Linux source tree as a .dts file.
> + *
> + * To support modifications to the device tree
> + * in-place in U-Boot, add to Linux's
> + * arch/arm/boot/dts/Makefile:
> + *
> + * DTC_FLAGS ?= -p 4096
> + *
> + * This will leave some padding in the DTB and
> + * thus reserve room for node additions.
> + *
> + * Also, set the environment variable fdt_high
> + * to 0xffffffff to keep the DTB in-place and
> + * to accommodate stblinux bmem/CMA
> + * reservations.
> + */
> + data = /incbin/("<bolt-<version>.dtb");
> + type = "flat_dt";
> + arch = "arm";
> + compression = "none";
> + hash at 1 {
> + algo = "sha256";
> + };
> + };
> + };
> + configurations {
> + default = "conf at bcm7445";
> + conf at bcm7445 {
> + description = "BCM7445 configuration";
> + kernel = "kernel at 1";
> + ramdisk = "ramdisk at 1";
> + fdt = "fdt at 1";
> + };
> + };
> + };
> diff --git a/doc/board/broadcom/index.rst b/doc/board/broadcom/index.rst
> index 4f0e825fef..a56bd1f069 100644
> --- a/doc/board/broadcom/index.rst
> +++ b/doc/board/broadcom/index.rst
> @@ -7,4 +7,5 @@ Broadcom
> .. toctree::
> :maxdepth: 2
>
> + bcm7xxx
> raspberrypi
More information about the U-Boot
mailing list