[PATCH 15/19] doc: Convert Chromium OS docs to rst
Heinrich Schuchardt
xypron.glpk at gmx.de
Mon Mar 15 11:56:25 CET 2021
On 3/15/21 6:11 AM, Simon Glass wrote:
> Move this documentation over to reST. Move the example files into a files/
> directory so they are still separate.
>
> Do a few minor updates while we are here:
> - Tidy up sandbox build instructions
> - Update my github account name
> - Add some talks and links
>
> Signed-off-by: Simon Glass <sjg at chromium.org>
> ---
>
> .../chainload.rst} | 80 ++++++++++------
> doc/chromium/{ => files}/chromebook_jerry.its | 0
> .../{ => files}/devkeys/kernel.keyblock | Bin
> .../devkeys/kernel_data_key.vbprivk | Bin
> doc/chromium/{ => files}/nyan-big.its | 0
> doc/chromium/index.rst | 14 +++
> doc/chromium/overview.rst | 74 ++++++++++++++
> .../run_vboot.rst} | 90 ++++++++----------
> doc/index.rst | 8 ++
> 9 files changed, 183 insertions(+), 83 deletions(-)
> rename doc/{README.chromium-chainload => chromium/chainload.rst} (79%)
> rename doc/chromium/{ => files}/chromebook_jerry.its (100%)
> rename doc/chromium/{ => files}/devkeys/kernel.keyblock (100%)
> rename doc/chromium/{ => files}/devkeys/kernel_data_key.vbprivk (100%)
> rename doc/chromium/{ => files}/nyan-big.its (100%)
> create mode 100644 doc/chromium/index.rst
> create mode 100644 doc/chromium/overview.rst
> rename doc/{README.chromium => chromium/run_vboot.rst} (68%)
>
> diff --git a/doc/README.chromium-chainload b/doc/chromium/chainload.rst
> similarity index 79%
> rename from doc/README.chromium-chainload
> rename to doc/chromium/chainload.rst
> index 45eaeced2da..7b6bb10d36d 100644
> --- a/doc/README.chromium-chainload
> +++ b/doc/chromium/chainload.rst
> @@ -1,3 +1,6 @@
> +.. SPDX-License-Identifier: GPL-2.0+
> +.. Copyright 2020 Google LLC
> +
> Running U-Boot from coreboot on Chromebooks
> ===========================================
>
> @@ -15,7 +18,7 @@ replace the ROM unless you have a servo board and cable to restore it with.
>
>
> For all of these the standard U-Boot build instructions apply. For example on
> -ARM:
> +ARM::
>
> sudo apt install gcc-arm-linux-gnueabi
> mkdir b
> @@ -37,14 +40,17 @@ https://www.chromium.org/chromium-os/firmware-porting-guide/using-nv-u-boot-on-t
> Nyan-big
> --------
>
> -Compiled based on information here:
> -https://lists.denx.de/pipermail/u-boot/2015-March/209530.html
> -https://git.collabora.com/cgit/user/tomeu/u-boot.git/commit/?h=nyan-big
> -https://lists.denx.de/pipermail/u-boot/2017-May/289491.html
> -https://github.com/chromeos-nvidia-androidtv/gnu-linux-on-acer-chromebook-13#copy-data-to-the-sd-card
> +Compiled based on information here::
> +
> + https://lists.denx.de/pipermail/u-boot/2015-March/209530.html
> + https://git.collabora.com/cgit/user/tomeu/u-boot.git/commit/?h=nyan-big
> + https://lists.denx.de/pipermail/u-boot/2017-May/289491.html
> + https://github.com/chromeos-nvidia-androidtv/gnu-linux-on-acer-chromebook-13#copy-data-to-the-sd-card
>
> 1. Build U-Boot
>
> +Steps::
> +
> mkdir b
> make -j8 O=b/nyan-big CROSS_COMPILE=arm-linux-gnueabi- nyan-big_defconfig all
>
> @@ -61,16 +67,21 @@ kernel, and crashes if it is not present.
>
> 3. Build and sign an image
>
> - ./b/nyan-big/tools/mkimage -f doc/chromium/nyan-big.its u-boot-chromium.fit
> +Steps::
> +
> + ./b/nyan-big/tools/mkimage -f doc/chromium/files/nyan-big.its u-boot-chromium.fit
> echo test >dummy.txt
> - vbutil_kernel --arch arm --keyblock doc/chromium/devkeys/kernel.keyblock \
> - --signprivate doc/chromium/devkeys/kernel_data_key.vbprivk \
> - --version 1 --config dummy.txt --vmlinuz u-boot-chromium.fit \
> - --bootloader dummy.txt --pack u-boot.kpart
> + vbutil_kernel --arch arm \
> + --keyblock doc/chromium/files/devkeys/kernel.keyblock \
> + --signprivate doc/chromium/files/devkeys/kernel_data_key.vbprivk \
> + --version 1 --config dummy.txt --vmlinuz u-boot-chromium.fit \
> + --bootloader dummy.txt --pack u-boot.kpart
>
>
> 4. Prepare an SD card
>
> +Steps::
> +
> DISK=/dev/sdc # Replace with your actual SD card device
> sudo cgpt create $DISK
> sudo cgpt add -b 34 -s 32768 -P 1 -S 1 -t kernel $DISK
> @@ -80,6 +91,8 @@ kernel, and crashes if it is not present.
>
> 5. Write U-Boot to the SD card
>
> +Steps::
> +
> sudo dd if=u-boot.kpart of=/dev/sdc1; sync
>
>
> @@ -90,7 +103,7 @@ do this, login as root (via Ctrl-Alt-forward_arrow) and type
> 'enable_dev_usb_boot'. You only need to do this once.
>
> Reboot the device with the SD card inserted. Press Clrl-U at the developer
> -mode screen. It should show something like the following on the display:
> +mode screen. It should show something like the following on the display::
>
> U-Boot 2017.07-00637-g242eb42-dirty (May 22 2017 - 06:14:21 -0600)
>
> @@ -104,9 +117,9 @@ mode screen. It should show something like the following on the display:
>
> 7. Known problems
>
> -On the serial console the word MMC is chopped at the start of the line:
> +On the serial console the word MMC is chopped at the start of the line::
>
> -C: sdhci at 700b0000: 2, sdhci at 700b0400: 1, sdhci at 700b0600: 0
> + C: sdhci at 700b0000: 2, sdhci at 700b0400: 1, sdhci at 700b0600: 0
>
> This is likely due to some problem with change-over of the serial driver
> during relocation (or perhaps updating the clock setup in board_init()).
> @@ -116,7 +129,7 @@ during relocation (or perhaps updating the clock setup in board_init()).
>
> To check that you copied the u-boot.its file correctly, use these commands.
> You should see that the data at 0x100 in u-boot-chromium.fit is the first few
> -bytes of U-Boot:
> +bytes of U-Boot::
>
> hd u-boot-chromium.fit |head -20
> ...
> @@ -141,34 +154,39 @@ The instruction are similar to those for Nyan with changes as noted below:
>
> Open include/configs/rk3288_common.h
>
> -Change:
> +Change::
>
> -#define CONFIG_SYS_TEXT_BASE 0x00100000
> + #define CONFIG_SYS_TEXT_BASE 0x00100000
>
> -to:
> +to::
>
> -#define CONFIG_SYS_TEXT_BASE 0x02000100
> + #define CONFIG_SYS_TEXT_BASE 0x02000100
>
>
>
> 2. Build U-Boot
>
> +Steps::
> +
> mkdir b
> make -j8 O=b/chromebook_jerry CROSS_COMPILE=arm-linux-gnueabi- \
> - chromebook_jerry_defconfig all
> + chromebook_jerry_defconfig all
>
>
> 3. See above
>
> 4. Build and sign an image
>
> +Steps::
> +
> ./b/chromebook_jerry/tools/mkimage -f doc/chromium/chromebook_jerry.its \
> - u-boot-chromium.fit
> + u-boot-chromium.fit
> echo test >dummy.txt
> - vbutil_kernel --arch arm --keyblock doc/chromium/devkeys/kernel.keyblock \
> - --signprivate doc/chromium/devkeys/kernel_data_key.vbprivk \
> - --version 1 --config dummy.txt --vmlinuz u-boot-chromium.fit \
> - --bootloader dummy.txt --pack u-boot.kpart
> + vbutil_kernel --arch arm \
> + --keyblock doc/chromium/files/devkeys/kernel.keyblock \
> + --signprivate doc/chromium/files/devkeys/kernel_data_key.vbprivk \
> + --version 1 --config dummy.txt --vmlinuz u-boot-chromium.fit \
> + --bootloader dummy.txt --pack u-boot.kpart
>
>
> 5. See above
> @@ -182,7 +200,7 @@ do this, login as root (via Ctrl-Alt-forward_arrow) and type
> 'enable_dev_usb_boot'. You only need to do this once.
>
> Reboot the device with the SD card inserted. Press Clrl-U at the developer
> -mode screen. It should show something like the following on the display:
> +mode screen. It should show something like the following on the display::
>
> U-Boot 2017.05-00649-g72acdbf-dirty (May 29 2017 - 14:57:05 -0600)
>
> @@ -203,18 +221,18 @@ None as yet.
>
>
> Other notes
> -===========
> +-----------
>
> flashrom
> ---------
> +~~~~~~~~
>
> - Used to make a backup of your firmware, or to replace it.
> +Used to make a backup of your firmware, or to replace it.
>
> - See: https://www.chromium.org/chromium-os/packages/cros-flashrom
> +See: https://www.chromium.org/chromium-os/packages/cros-flashrom
>
>
> coreboot
> ---------
> +~~~~~~~~
>
> Coreboot itself is not designed to actually boot an OS. Instead, a program
> called Depthcharge is used. This originally came out of U-Boot and was then
> diff --git a/doc/chromium/chromebook_jerry.its b/doc/chromium/files/chromebook_jerry.its
> similarity index 100%
> rename from doc/chromium/chromebook_jerry.its
> rename to doc/chromium/files/chromebook_jerry.its
> diff --git a/doc/chromium/devkeys/kernel.keyblock b/doc/chromium/files/devkeys/kernel.keyblock
> similarity index 100%
> rename from doc/chromium/devkeys/kernel.keyblock
> rename to doc/chromium/files/devkeys/kernel.keyblock
> diff --git a/doc/chromium/devkeys/kernel_data_key.vbprivk b/doc/chromium/files/devkeys/kernel_data_key.vbprivk
> similarity index 100%
> rename from doc/chromium/devkeys/kernel_data_key.vbprivk
> rename to doc/chromium/files/devkeys/kernel_data_key.vbprivk
> diff --git a/doc/chromium/nyan-big.its b/doc/chromium/files/nyan-big.its
> similarity index 100%
> rename from doc/chromium/nyan-big.its
> rename to doc/chromium/files/nyan-big.its
> diff --git a/doc/chromium/index.rst b/doc/chromium/index.rst
> new file mode 100644
> index 00000000000..0722c250033
> --- /dev/null
> +++ b/doc/chromium/index.rst
> @@ -0,0 +1,14 @@
> +.. SPDX-License-Identifier: GPL-2.0+
> +.. Copyright 2020 Google LLC
> +
> +Chromium OS-specific doc
> +========================
> +
> +This provides some information about Chromium OS and U-Boot.
> +
> +.. toctree::
> + :maxdepth: 2
> +
> + overview
> + run_vboot
> + chainload
> diff --git a/doc/chromium/overview.rst b/doc/chromium/overview.rst
> new file mode 100644
> index 00000000000..5498ed9c16c
> --- /dev/null
> +++ b/doc/chromium/overview.rst
> @@ -0,0 +1,74 @@
> +.. SPDX-License-Identifier: GPL-2.0+
> +.. Copyright 2020 Google LLC
> +
> +Chromium OS Support in U-Boot
> +=============================
> +
> +Introduction
> +------------
> +
> +This describes how to use U-Boot with Chromium OS. Several options are
> +available:
> +
> + - Running U-Boot from the 'altfw' feature, which is available on selected
> + Chromebooks from 2019 onwards (initially Grunt). Press '1' from the
> + developer-mode screen to get into U-Boot. See here for details:
> + https://chromium.googlesource.com/chromiumos/docs/+/HEAD/developer_mode.md
> +
> + - Running U-Boot from the disk partition. This involves signing U-Boot and
> + placing it on the disk, for booting as a 'kernel'. See
> + :doc:`chainload` for information on this. This is the only
> + option on non-U-Boot Chromebooks from 2013 to 2018 and is somewhat
> + more involved.
> +
> + - Running U-Boot with Chromium OS verified boot. This allows U-Boot to be
> + used instead of either or both of depthcharge (a bootloader which forked
> + from U-Boot in 2013) and coreboot. See :doc:`run_vboot` for more
> + information on this.
> +
> + - Running U-Boot from coreboot. This allows U-Boot to run on more devices
> + since many of them only support coreboot as the bootloader and have
> + no bare-metal support in U-Boot. For this, use the 'coreboot' target.
> +
> + - Running U-Boot and booting into a Chrome OS image, but without verified
> + boot. This can be useful for testing.
> +
> +
> +Talks and documents
> +-------------------
> +
> +Here is some material relevant to Chromium OS verified boot with U-Boot:
> +
> + - "U-Boot with Chrome OS and firmware packaging"
> +
> + - Author: Simon Glass
> + - Presented at Open Source Firmware Conference 2018, Erlangen
> + - Describes the work in progress as at the end of 2018
> + - Slides at `OSFC <https://2018.osfc.io/uploads/talk/paper/26/U-Boot_with_Chrome_OS_and_firmware_packaging.pdf>`_
> + - Video on `Youtube <https://www.youtube.com/watch?v=1jknxUvmwpo>`_
With this patch applied to U-Boot master 'make htmldocs' generates an error:
Warning, treated as error:
doc/chromium/overview.rst:5:Duplicate explicit target name: "youtube".
This seems to relate to:
doc/chromium/overview.rst:48: - Video on `Youtube
<https://www.youtube.com/watch?v=1jknxUvmwpo>`_
doc/chromium/overview.rst:61: - Video at `Youtube
<https://www.youtube.com/watch?v=kdpZC9jFzZA>`_
doc/chromium/overview.rst:70: - Video at `YouTube
<https://www.youtube.com/watch?v=WY2sWpuda2g>`_
Best regards
Heinrich
> +
> + - "Verified Boot in Chrome OS and how to make it work for you"
> +
> + - Author: Simon Glass
> + - Presented at ELCE 2013, Edinburgh
> + - Describes the original 2013 implementation as shipped on snow (first
> + `ARM Chromebook was a Samsung Chromebook <https://www.cnet.com/products/samsung-series-3-chromebook-xe303c12-11-6-exynos-5250-2-gb-ram-16-gb-ssd-bilingual-english-french/>`_
> + with Samsung Exynos5250 `review <https://www.cnet.com/reviews/samsung-chromebook-series-3-review/>`_),
> + spring (`HP Chromebook 11 <https://www.cnet.com/products/hp-chromebook-11-g2-11-6-exynos-5250-4-gb-ram-16-gb-emmc/>`_)
> + and pit/pi (`Samsung Chromebook 2 <https://www.cnet.com/products/samsung-chromebook-2-xe503c12-11-6-exynos-5-octa-4-gb-ram-16-gb-ssd/>`_
> + with Exynos 5 Octa 5420 in 2014).
> + - Slides at `Google research <https://research.google/pubs/pub42038/>`_
> + - Video at `Youtube <https://www.youtube.com/watch?v=kdpZC9jFzZA>`_
> +
> + - "Chrome University 2018: Chrome OS Firmware and Verified Boot 201"
> +
> + - Author: Duncan Laurie
> + - Describes Chrome OS firmware as of 2018 and includes a wide range of
> + topics. This has no U-Boot information, but does cover coreboot and also
> + talks about the Chrome OS EC and Security chip. This is probably the
> + best introduction talk.
> + - Video at `YouTube <https://www.youtube.com/watch?v=WY2sWpuda2g>`_
> +
> + - `Chromium OS U-Boot <https://www.chromium.org/developers/u-boot>`_
> +
> + - `Firmware porting Guide <https://www.chromium.org/chromium-os/firmware-porting-guide>`_
> diff --git a/doc/README.chromium b/doc/chromium/run_vboot.rst
> similarity index 68%
> rename from doc/README.chromium
> rename to doc/chromium/run_vboot.rst
> index 75f2f24042c..41b4f631835 100644
> --- a/doc/README.chromium
> +++ b/doc/chromium/run_vboot.rst
> @@ -1,42 +1,14 @@
> -Chromium OS Support in U-Boot
> -=============================
> -
> -Introduction
> -------------
> -
> -This describes how to use U-Boot with Chromium OS. Several options are
> -available:
> -
> - - Running U-Boot from the 'altfw' feature, which is available on selected
> - Chromebooks from 2019 onwards (initially Grunt). Press '1' from the
> - developer-mode screen to get into U-Boot. See here for details:
> - https://sites.google.com/a/chromium.org/dev/chromium-os/poking-around-your-chrome-os-device?pli=1
> -
> - - Running U-Boot from the disk partition. This involves signing U-Boot and
> - placing it on the disk, for booting as a 'kernel'. See
> - README.chromium-chainload for information on this. This is the only
> - option on non-U-Boot Chromebooks from 2013 to 2018 and is somewhat
> - more involved.
> -
> - - Running U-Boot with Chromium OS verified boot. This allows U-Boot to be
> - used instead of either or both of depthcharge (a bootloader which forked
> - from U-Boot in 2013) and coreboot. See below for more information on
> - this.
> -
> - - Running U-Boot from coreboot. This allows U-Boot to run on more devices
> - since many of them only support coreboot as the bootloader and have
> - no bare-metal support in U-Boot. For this, use the 'coreboot' target.
> -
> - - Running U-Boot and booting into a Chrome OS image, but without verified
> - boot. This can be useful for testing.
> +.. SPDX-License-Identifier: GPL-2.0+
> +.. Copyright 2020 Google LLC
> +.. sectionauthor:: Simon Glass <sjg at chromium.org>
>
>
> -U-Boot with Chromium OS verified boot
> --------------------------------------
> +Running U-Boot with Chromium OS verified boot
> +=============================================
>
> -To obtain:
> +To obtain::
>
> - git clone https://github.com/sglass68/u-boot.git
> + git clone https://github.com/sjg20/u-boot.git
> cd u-boot
> git checkout cros-master
>
> @@ -46,28 +18,35 @@ To obtain:
> git checkout 45964294
> # futility: updater: Correct output version for Snow
>
> -To build for sandbox:
> +To build for sandbox::
>
> UB=/tmp/b/chromeos_sandbox # U-Boot build directory
> cd u-boot
> make O=$UB chromeos_sandbox_defconfig
> make O=$UB -j20 -s VBOOT_SOURCE=/path/to/vboot_reference \
> - MAKEFLAGS_VBOOT=DEBUG=1 QUIET=1
> + MAKEFLAGS_VBOOT=DEBUG=1 QUIET=1
>
> Replace sandbox with another supported target.
>
> This produces $UB/image.bin which contains the firmware binaries in a SPI
> flash image.
>
> -To run on sandbox:
> +To run on sandbox::
>
> + CROS=~/cosarm
> + IMG=$CROS/src/build/images/coral/latest/chromiumos_image.bin
> $UB/tpl/u-boot-tpl -d $UB/u-boot.dtb.out \
> - -L6 -c "host bind 0 $CROS/src/build/images/cheza/latest/chromiumos_image.bin; vboot go auto" \
> - -l -w -s state.dtb -r
> + -L6 -c "host bind 0 $IMG; vboot go auto" \
> + -l -w -s state.dtb -r -n -m $UB/ram
> +
> + $UB/tpl/u-boot-tpl -d $UB/u-boot.dtb.out -L6 -l \
> + -c "host bind 0 $IMG; vboot go auto" -w -s $UB/state.dtb -r -n -m $UB/mem
> +
>
> To run on other boards:
> - Install image.bin in the SPI flash of your device
> - Boot your system
> +
> + - Install image.bin in the SPI flash of your device
> + - Boot your system
>
>
> Sandbox
> @@ -83,7 +62,7 @@ a device tree and binding a Chromium OS disk image for use to find kernels
> phases into state.dtb and will automatically ensure that memory is shared
> between all phases. TPL will jump to SPL and then on to U-Boot proper.
>
> -It is possible to run with debugging on, e.g.
> +It is possible to run with debugging on, e.g.::
>
> gdb --args $UB/tpl/u-boot-tpl -d ....
>
> @@ -95,7 +74,7 @@ Samus
> -----
>
> Basic support is available for samus, using the chromeos_samus target. If you
> -have an em100, use:
> +have an em100, use::
>
> sudo em100 -s -c W25Q128FW -d $UB/image.bin -t -r
>
> @@ -119,11 +98,20 @@ New uclasses
>
> Several uclasses are provided in cros/:
>
> - UCLASS_CROS_AUX_FW Chrome OS auxiliary firmware
> - UCLASS_CROS_FWSTORE Chrome OS firmware storage
> - UCLASS_CROS_NVDATA Chrome OS non-volatile data device
> - UCLASS_CROS_VBOOT_EC Chrome OS vboot EC operations
> - UCLASS_CROS_VBOOT_FLAG Chrome OS verified boot flag
> +UCLASS_CROS_AUX_FW
> + Chrome OS auxiliary firmware
> +
> +UCLASS_CROS_FWSTORE
> + Chrome OS firmware storage
> +
> +UCLASS_CROS_NVDATA
> + Chrome OS non-volatile data device
> +
> +UCLASS_CROS_VBOOT_EC
> + Chrome OS vboot EC operations
> +
> +UCLASS_CROS_VBOOT_FLAG
> + Chrome OS verified boot flag
>
> The existing UCLASS_CROS_EC is also used.
>
> @@ -181,7 +169,7 @@ detect problems that affect the flow or particular vboot features.
> U-Boot without Chromium OS verified boot
> ----------------------------------------
>
> -The following script can be used to boot a Chrome OS image on coral:
> +The following script can be used to boot a Chrome OS image on coral::
>
> # Read the image header and obtain the address of the kernel
> # The offset 4f0 is defined by verified boot and may change for other
> @@ -213,6 +201,4 @@ TO DO
> Get the full ACPI tables working with Coral
>
>
> -Simon Glass
> -sjg at chromium.org
> 7 October 2018
> diff --git a/doc/index.rst b/doc/index.rst
> index 4c44955d67f..ce91a2a41ef 100644
> --- a/doc/index.rst
> +++ b/doc/index.rst
> @@ -110,6 +110,14 @@ Android-specific features available in U-Boot.
>
> android/index
>
> +Chromium OS-specific doc
> +------------------------
> +
> +.. toctree::
> + :maxdepth: 2
> +
> + chromium/index
> +
> Indices and tables
> ==================
>
>
More information about the U-Boot
mailing list