From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id CDBA7C433EF for ; Tue, 9 Nov 2021 08:09:00 +0000 (UTC) Received: from phobos.denx.de (phobos.denx.de [85.214.62.61]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by mail.kernel.org (Postfix) with ESMTPS id 4DF756113D for ; Tue, 9 Nov 2021 08:09:00 +0000 (UTC) DMARC-Filter: OpenDMARC Filter v1.4.1 mail.kernel.org 4DF756113D Authentication-Results: mail.kernel.org; dmarc=fail (p=none dis=none) header.from=gmail.com Authentication-Results: mail.kernel.org; spf=pass smtp.mailfrom=lists.denx.de Received: from h2850616.stratoserver.net (localhost [IPv6:::1]) by phobos.denx.de (Postfix) with ESMTP id 925B1838F4; Tue, 9 Nov 2021 09:08:58 +0100 (CET) Authentication-Results: phobos.denx.de; dmarc=pass (p=none dis=none) header.from=gmail.com Authentication-Results: phobos.denx.de; spf=pass smtp.mailfrom=u-boot-bounces@lists.denx.de Authentication-Results: phobos.denx.de; dkim=pass (2048-bit key; unprotected) header.d=gmail.com header.i=@gmail.com header.b="K27r56ZQ"; dkim-atps=neutral Received: by phobos.denx.de (Postfix, from userid 109) id DCD72838F0; Tue, 9 Nov 2021 09:08:56 +0100 (CET) Received: from mail-ot1-x32c.google.com (mail-ot1-x32c.google.com [IPv6:2607:f8b0:4864:20::32c]) (using TLSv1.3 with cipher TLS_AES_128_GCM_SHA256 (128/128 bits)) (No client certificate requested) by phobos.denx.de (Postfix) with ESMTPS id 35933838F4 for ; Tue, 9 Nov 2021 09:08:51 +0100 (CET) Authentication-Results: phobos.denx.de; dmarc=pass (p=none dis=none) header.from=gmail.com Authentication-Results: phobos.denx.de; spf=pass smtp.mailfrom=rfried.dev@gmail.com Received: by mail-ot1-x32c.google.com with SMTP id z2-20020a9d71c2000000b0055c6a7d08b8so17534171otj.5 for ; Tue, 09 Nov 2021 00:08:51 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=mime-version:references:in-reply-to:from:date:message-id:subject:to :cc; bh=AqjmzxsJzJqkrMWon5dWaIi+r83dGzo0tnDzbyUa4Nw=; b=K27r56ZQkDXZhjNoG+bZw6+L7b4PI3S1kqX6SLCFkj0ufavfRgCtqgDlo5VDbiutpf UNvakuLyaDzeSYJv0k0KY0seI5p1ywcdomWyzeENG6EbI/BgpqsK7acK8GBXftImAJb2 fqBbfyzQ3w6FfudcJamTkxYr/TZ1YJwmccv+QQn1yMIgjVrdpQaBe0CmNpKwpyLSbym9 lGJCaRCIUrwWmSgV+nBa9YW8SxteyexGsNzQpFYpKOhQSPRvWAEAlyVnGhyEzH9m8p2F nIMxsmb9HAb2KfnTQX4SFvxWsL/ZJ9Ykg+RIkd76vbxu4ZXIHpYrD6YZUcpCWEJlgG5L xAvA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=x-gm-message-state:mime-version:references:in-reply-to:from:date :message-id:subject:to:cc; bh=AqjmzxsJzJqkrMWon5dWaIi+r83dGzo0tnDzbyUa4Nw=; b=3NlaqdWsgkBnhU2j+PbRcmbaeD3Fl5h8CxUt4n0X58sddmw2Sjx/mK2nhG+X4Ie+zr vvw9DzGWcIyP4LuTQLMwbNynhcjzrxqSFdnjfZKCBrROirNVkEmjak82YFkRl9H4NJuM AmW6DlEc/d/TLR6FdT72bCfCXWROjq5X+EdgXo7AP5Bt8fjKesvNxEKxPRoWTymbJtNK nUPsjXV4VxXoH1Jb9hNy6SZ3n39oLte/8r+nGTl7cxpujD+EG89O5k01bKsfzIMJOmby LXk8QVhRFKti8bT/zgz7SA32VKgvJ8aObgC5QXX0DTdo/prtl2MX65Qj3M77pUe7KiWH JlZQ== X-Gm-Message-State: AOAM530o2nCfSjOJepwJvJ1Llo9mbLiDmc7NpbQAB/OiRgxq329MPc7w gBGIVXVSfiA5wYuiLutjqqEeimG5FGQ3CH3KmT0= X-Google-Smtp-Source: ABdhPJxwbHeqz5gYo8RF9ocDvSkSPiyGYLRBN7EVElyPG1QK8Ni/ZYAEhU46AnjOEQBOMdH8vra2GkIJSLlhQRKNyf4= X-Received: by 2002:a9d:6646:: with SMTP id q6mr4426657otm.327.1636445329608; Tue, 09 Nov 2021 00:08:49 -0800 (PST) MIME-Version: 1.0 References: <20211014184811.482560-1-sjg@chromium.org> <20211014124803.v3.17.Icbffbc563f1de65873914fb8e073c7e2d6103891@changeid> In-Reply-To: <20211014124803.v3.17.Icbffbc563f1de65873914fb8e073c7e2d6103891@changeid> From: Ramon Fried Date: Tue, 9 Nov 2021 10:08:38 +0200 Message-ID: Subject: Re: [PATCH v3 17/18] doc: Move distro boot doc to rST To: Simon Glass Cc: U-Boot Mailing List , Patrice Chotard , Artem Lapkin , Tom Rini , Joe Hershberger , Heinrich Schuchardt , Peter Hoyes Content-Type: text/plain; charset="UTF-8" X-BeenThere: u-boot@lists.denx.de X-Mailman-Version: 2.1.34 Precedence: list List-Id: U-Boot discussion List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: u-boot-bounces@lists.denx.de Sender: "U-Boot" X-Virus-Scanned: clamav-milter 0.103.2 at phobos.denx.de X-Virus-Status: Clean On Thu, Oct 14, 2021 at 9:52 PM Simon Glass wrote: > > Move this over to the new rST format. > > Signed-off-by: Simon Glass > --- > > (no changes since v1) > > doc/{README.distro => develop/distro.rst} | 177 ++++++++++------------ > doc/develop/index.rst | 1 + > 2 files changed, 80 insertions(+), 98 deletions(-) > rename doc/{README.distro => develop/distro.rst} (76%) > > diff --git a/doc/README.distro b/doc/develop/distro.rst > similarity index 76% > rename from doc/README.distro > rename to doc/develop/distro.rst > index fa8cec11028..c522be69349 100644 > --- a/doc/README.distro > +++ b/doc/develop/distro.rst > @@ -1,9 +1,4 @@ > -SPDX-License-Identifier: GPL-2.0+ > -/* > - * (C) Copyright 2014 Red Hat Inc. > - * Copyright (c) 2014-2015, NVIDIA CORPORATION. All rights reserved. > - * Copyright (C) 2015 K. Merker > - */ > +.. SPDX-License-Identifier: GPL-2.0+ > > Generic Distro Configuration Concept > ==================================== > @@ -73,9 +68,8 @@ Boot Configuration Files > > The standard format for boot configuration files is that of extlinux.conf, as > handled by U-Boot's "syslinux" (disk) or "pxe boot" (network). This is roughly > -as specified at: > +as specified at BootLoaderSpec_: > > -http://www.freedesktop.org/wiki/Specifications/BootLoaderSpec/ > > ... with the exceptions that the BootLoaderSpec document: > > @@ -87,73 +81,70 @@ http://www.freedesktop.org/wiki/Specifications/BootLoaderSpec/ > * Does not document the fdtdir option, which automatically selects the DTB to > pass to the kernel. > > -One example extlinux.conf generated by the Fedora installer is: > +One example extlinux.conf generated by the Fedora installer is:: > > ------------------------------------------------------------- > -# extlinux.conf generated by anaconda > + # extlinux.conf generated by anaconda > > -ui menu.c32 > + ui menu.c32 > > -menu autoboot Welcome to Fedora. Automatic boot in # second{,s}. Press a key for options. > -menu title Fedora Boot Options. > -menu hidden > + menu autoboot Welcome to Fedora. Automatic boot in # second{,s}. Press a key for options. > + menu title Fedora Boot Options. > + menu hidden > > -timeout 50 > -#totaltimeout 9000 > + timeout 50 > + #totaltimeout 9000 > > -default Fedora (3.17.0-0.rc4.git2.1.fc22.armv7hl+lpae) 22 (Rawhide) > + default Fedora (3.17.0-0.rc4.git2.1.fc22.armv7hl+lpae) 22 (Rawhide) > > -label Fedora (3.17.0-0.rc4.git2.1.fc22.armv7hl) 22 (Rawhide) > - kernel /boot/vmlinuz-3.17.0-0.rc4.git2.1.fc22.armv7hl > - append ro root=UUID=8eac677f-8ea8-4270-8479-d5ddbb797450 console=ttyS0,115200n8 LANG=en_US.UTF-8 drm.debug=0xf > - fdtdir /boot/dtb-3.17.0-0.rc4.git2.1.fc22.armv7hl > - initrd /boot/initramfs-3.17.0-0.rc4.git2.1.fc22.armv7hl.img > + label Fedora (3.17.0-0.rc4.git2.1.fc22.armv7hl) 22 (Rawhide) > + kernel /boot/vmlinuz-3.17.0-0.rc4.git2.1.fc22.armv7hl > + append ro root=UUID=8eac677f-8ea8-4270-8479-d5ddbb797450 console=ttyS0,115200n8 LANG=en_US.UTF-8 drm.debug=0xf > + fdtdir /boot/dtb-3.17.0-0.rc4.git2.1.fc22.armv7hl > + initrd /boot/initramfs-3.17.0-0.rc4.git2.1.fc22.armv7hl.img > > -label Fedora (3.17.0-0.rc4.git2.1.fc22.armv7hl+lpae) 22 (Rawhide) > - kernel /boot/vmlinuz-3.17.0-0.rc4.git2.1.fc22.armv7hl+lpae > - append ro root=UUID=8eac677f-8ea8-4270-8479-d5ddbb797450 console=ttyS0,115200n8 LANG=en_US.UTF-8 drm.debug=0xf > - fdtdir /boot/dtb-3.17.0-0.rc4.git2.1.fc22.armv7hl+lpae > - initrd /boot/initramfs-3.17.0-0.rc4.git2.1.fc22.armv7hl+lpae.img > + label Fedora (3.17.0-0.rc4.git2.1.fc22.armv7hl+lpae) 22 (Rawhide) > + kernel /boot/vmlinuz-3.17.0-0.rc4.git2.1.fc22.armv7hl+lpae > + append ro root=UUID=8eac677f-8ea8-4270-8479-d5ddbb797450 console=ttyS0,115200n8 LANG=en_US.UTF-8 drm.debug=0xf > + fdtdir /boot/dtb-3.17.0-0.rc4.git2.1.fc22.armv7hl+lpae > + initrd /boot/initramfs-3.17.0-0.rc4.git2.1.fc22.armv7hl+lpae.img > > -label Fedora-0-rescue-8f6ba7b039524e0eb957d2c9203f04bc (0-rescue-8f6ba7b039524e0eb957d2c9203f04bc) > - kernel /boot/vmlinuz-0-rescue-8f6ba7b039524e0eb957d2c9203f04bc > - initrd /boot/initramfs-0-rescue-8f6ba7b039524e0eb957d2c9203f04bc.img > - append ro root=UUID=8eac677f-8ea8-4270-8479-d5ddbb797450 console=ttyS0,115200n8 > - fdtdir /boot/dtb-3.16.0-0.rc6.git1.1.fc22.armv7hl+lpae > ------------------------------------------------------------- > + label Fedora-0-rescue-8f6ba7b039524e0eb957d2c9203f04bc (0-rescue-8f6ba7b039524e0eb957d2c9203f04bc) > + kernel /boot/vmlinuz-0-rescue-8f6ba7b039524e0eb957d2c9203f04bc > + initrd /boot/initramfs-0-rescue-8f6ba7b039524e0eb957d2c9203f04bc.img > + append ro root=UUID=8eac677f-8ea8-4270-8479-d5ddbb797450 console=ttyS0,115200n8 > + fdtdir /boot/dtb-3.16.0-0.rc6.git1.1.fc22.armv7hl+lpae > > -Another hand-crafted network boot configuration file is: > > ------------------------------------------------------------- > -TIMEOUT 100 > +Another hand-crafted network boot configuration file is:: > > -MENU TITLE TFTP boot options > + TIMEOUT 100 > > -LABEL jetson-tk1-emmc > - MENU LABEL ../zImage root on Jetson TK1 eMMC > - LINUX ../zImage > - FDTDIR ../ > - APPEND console=ttyS0,115200n8 console=tty1 loglevel=8 rootwait rw earlyprintk root=PARTUUID=80a5a8e9-c744-491a-93c1-4f4194fd690b > + MENU TITLE TFTP boot options > > -LABEL venice2-emmc > - MENU LABEL ../zImage root on Venice2 eMMC > - LINUX ../zImage > - FDTDIR ../ > - APPEND console=ttyS0,115200n8 console=tty1 loglevel=8 rootwait rw earlyprintk root=PARTUUID=5f71e06f-be08-48ed-b1ef-ee4800cc860f > + LABEL jetson-tk1-emmc > + MENU LABEL ../zImage root on Jetson TK1 eMMC > + LINUX ../zImage > + FDTDIR ../ > + APPEND console=ttyS0,115200n8 console=tty1 loglevel=8 rootwait rw earlyprintk root=PARTUUID=80a5a8e9-c744-491a-93c1-4f4194fd690b > > -LABEL sdcard > - MENU LABEL ../zImage, root on 2GB sdcard > - LINUX ../zImage > - FDTDIR ../ > - APPEND console=ttyS0,115200n8 console=tty1 loglevel=8 rootwait rw earlyprintk root=PARTUUID=b2f82cda-2535-4779-b467-094a210fbae7 > + LABEL venice2-emmc > + MENU LABEL ../zImage root on Venice2 eMMC > + LINUX ../zImage > + FDTDIR ../ > + APPEND console=ttyS0,115200n8 console=tty1 loglevel=8 rootwait rw earlyprintk root=PARTUUID=5f71e06f-be08-48ed-b1ef-ee4800cc860f > > -LABEL fedora-installer-fk > - MENU LABEL Fedora installer w/ Fedora kernel > - LINUX fedora-installer/vmlinuz > - INITRD fedora-installer/initrd.img.orig > - FDTDIR fedora-installer/dtb > - APPEND loglevel=8 ip=dhcp inst.repo=http://10.0.0.2/mirrors/fedora/linux/development/rawhide/armhfp/os/ rd.shell cma=64M > ------------------------------------------------------------- > + LABEL sdcard > + MENU LABEL ../zImage, root on 2GB sdcard > + LINUX ../zImage > + FDTDIR ../ > + APPEND console=ttyS0,115200n8 console=tty1 loglevel=8 rootwait rw earlyprintk root=PARTUUID=b2f82cda-2535-4779-b467-094a210fbae7 > + > + LABEL fedora-installer-fk > + MENU LABEL Fedora installer w/ Fedora kernel > + LINUX fedora-installer/vmlinuz > + INITRD fedora-installer/initrd.img.orig > + FDTDIR fedora-installer/dtb > + APPEND loglevel=8 ip=dhcp inst.repo=http://10.0.0.2/mirrors/fedora/linux/development/rawhide/armhfp/os/ rd.shell cma=64M > > U-Boot Implementation > ===================== > @@ -166,13 +157,11 @@ a line with "CONFIG_DISTRO_DEFAULTS=y". If you want to enable this > from Kconfig itself, for e.g. all boards using a specific SoC then > add a "imply DISTRO_DEFAULTS" to your SoC CONFIG option. > > -In your board configuration file, include the following: > +In your board configuration file, include the following:: > > ------------------------------------------------------------- > -#ifndef CONFIG_SPL_BUILD > -#include > -#endif > ------------------------------------------------------------- > + #ifndef CONFIG_SPL_BUILD > + #include > + #endif > > The first of those headers primarily enables a core set of U-Boot features, > such as support for MBR and GPT partitions, ext* and FAT filesystems, booting > @@ -205,7 +194,6 @@ CONFIG_EXTRA_ENV_SETTINGS in the board's U-Boot configuration file, so that > the user doesn't have to configure them. > > fdt_addr: > - > Mandatory for any system that provides the DTB in HW (e.g. ROM) and wishes > to pass that DTB to Linux, rather than loading a DTB from the boot > filesystem. Prohibited for any other system. > @@ -214,7 +202,6 @@ fdt_addr: > address. > > fdt_addr_r: > - > Mandatory. The location in RAM where the DTB will be loaded or copied to when > processing the fdtdir/devicetreedir or fdt/devicetree options in > extlinux.conf. > @@ -225,7 +212,6 @@ fdt_addr_r: > A size of 1MB for the FDT/DTB seems reasonable. > > fdtfile: > - > Mandatory. the name of the DTB file for the specific board for instance > the espressobin v5 board the value is "marvell/armada-3720-espressobin.dtb" > while on a clearfog pro it is "armada-388-clearfog-pro.dtb" in the case of > @@ -236,16 +222,14 @@ fdtfile: > SoC vendor directories. > > ramdisk_addr_r: > - > Mandatory. The location in RAM where the initial ramdisk will be loaded to > when processing the initrd option in extlinux.conf. > > - It is recommended that this location be highest in RAM out of fdt_addr_, > + It is recommended that this location be highest in RAM out of fdt_addr_r, > kernel_addr_r, and ramdisk_addr_r, so that the RAM disk can vary in size > and use any available RAM. > > kernel_addr_r: > - > Mandatory. The location in RAM where the kernel will be loaded to when > processing the kernel option in the extlinux.conf. > > @@ -270,14 +254,12 @@ kernel_comp_size: > size has to at least the size of loaded image for decompression to succeed. > > pxefile_addr_r: > - > Mandatory. The location in RAM where extlinux.conf will be loaded to prior > to processing. > > A size of 1MB for extlinux.conf is more than adequate. > > scriptaddr: > - > Mandatory, if the boot script is boot.scr rather than extlinux.conf. The > location in RAM where boot.scr will be loaded to prior to execution. > > @@ -292,24 +274,22 @@ MEM_LAYOUT_ENV_SETTINGS in include/configs/tegra124-common.h. > Boot Target Configuration > ------------------------- > > - defines $bootcmd and many helper command variables > -that automatically search attached disks for boot configuration files and > -execute them. Boards must provide configure so that > -it supports the correct set of possible boot device types. To provide this > +The `config_distro_bootcmd.h` file defines $bootcmd and many helper command > +variables that automatically search attached disks for boot configuration files > +and execute them. Boards must provide configure so > +that it supports the correct set of possible boot device types. To provide this > configuration, simply define macro BOOT_TARGET_DEVICES prior to including > -. For example: > - > ------------------------------------------------------------- > -#ifndef CONFIG_SPL_BUILD > -#define BOOT_TARGET_DEVICES(func) \ > - func(MMC, mmc, 1) \ > - func(MMC, mmc, 0) \ > - func(USB, usb, 0) \ > - func(PXE, pxe, na) \ > - func(DHCP, dhcp, na) > -#include > -#endif > ------------------------------------------------------------- > +. For example:: > + > + #ifndef CONFIG_SPL_BUILD > + #define BOOT_TARGET_DEVICES(func) \ > + func(MMC, mmc, 1) \ > + func(MMC, mmc, 0) \ > + func(USB, usb, 0) \ > + func(PXE, pxe, na) \ > + func(DHCP, dhcp, na) > + #include > + #endif > > Each entry in the macro defines a single boot device (e.g. a specific eMMC > device or SD card) or type of boot device (e.g. USB disk). The parameters to > @@ -328,7 +308,6 @@ up by . After this, various environment variables may > be altered to influence the boot process: > > boot_targets: > - > The list of boot locations searched. > > Example: mmc0, mmc1, usb, pxe > @@ -336,7 +315,6 @@ boot_targets: > Entries may be removed or re-ordered in this list to affect the boot order. > > boot_prefixes: > - > For disk-based booting, the list of directories within a partition that are > searched for boot configuration files (extlinux.conf, boot.scr). > > @@ -346,7 +324,6 @@ boot_prefixes: > directories which are searched. > > boot_scripts: > - > The name of U-Boot style boot.scr files that $bootcmd searches for. > > Example: boot.scr.uimg boot.scr > @@ -358,17 +335,14 @@ boot_scripts: > filenames which are supported. > > scan_dev_for_extlinux: > - > If you want to disable extlinux.conf on all disks, set the value to something > innocuous, e.g. setenv scan_dev_for_extlinux true. > > scan_dev_for_scripts: > - > If you want to disable boot.scr on all disks, set the value to something > innocuous, e.g. setenv scan_dev_for_scripts true. > > boot_net_usb_start: > - > If you want to prevent USB enumeration by distro boot commands which execute > network operations, set the value to something innocuous, e.g. setenv > boot_net_usb_start true. This would be useful if you know your Ethernet > @@ -376,7 +350,6 @@ boot_net_usb_start: > avoiding unnecessary actions. > > boot_net_pci_enum: > - > If you want to prevent PCI enumeration by distro boot commands which execute > network operations, set the value to something innocuous, e.g. setenv > boot_net_pci_enum true. This would be useful if you know your Ethernet > @@ -412,10 +385,12 @@ Examples: > The list of possible targets consists of: > > - network targets > + > * dhcp > * pxe > > - storage targets (to which a device number must be appended) > + > * mmc > * sata > * scsi > @@ -428,3 +403,9 @@ of the boot environment and are not guaranteed to exist or work in the same > way in future u-boot versions. In particular the _boot > variables (e.g. mmc_boot, usb_boot) are a strictly internal implementation > detail and must not be used as a public interface. > + > +.. _BootLoaderSpec: http://www.freedesktop.org/wiki/Specifications/BootLoaderSpec/ > + > +.. sectionauthor:: (C) Copyright 2014 Red Hat Inc. > +.. sectionauthor:: Copyright (c) 2014-2015, NVIDIA CORPORATION. All rights reserved. > +.. sectionauthor:: Copyright (C) 2015 K. Merker > diff --git a/doc/develop/index.rst b/doc/develop/index.rst > index 5e064a4dac1..b3871b16f35 100644 > --- a/doc/develop/index.rst > +++ b/doc/develop/index.rst > @@ -14,6 +14,7 @@ Implementation > commands > config_binding > devicetree/index > + distro > driver-model/index > global_data > logging > -- > 2.33.0.1079.g6e70778dc9-goog > Reviewed-by: Ramon Fried