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 X-Spam-Level: X-Spam-Status: No, score=-18.2 required=3.0 tests=BAYES_00,DKIMWL_WL_HIGH, DKIM_SIGNED,DKIM_VALID,DKIM_VALID_AU,HEADER_FROM_DIFFERENT_DOMAINS, INCLUDES_CR_TRAILER,INCLUDES_PATCH,MAILING_LIST_MULTI,NUMERIC_HTTP_ADDR, SPF_HELO_NONE,SPF_PASS,USER_AGENT_GIT autolearn=ham autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id D35D3C4338F for ; Thu, 19 Aug 2021 03:49:38 +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 5BEA46108B for ; Thu, 19 Aug 2021 03:49:38 +0000 (UTC) DMARC-Filter: OpenDMARC Filter v1.4.1 mail.kernel.org 5BEA46108B Authentication-Results: mail.kernel.org; dmarc=fail (p=none dis=none) header.from=chromium.org 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 DF11383227; Thu, 19 Aug 2021 05:47:30 +0200 (CEST) Authentication-Results: phobos.denx.de; dmarc=pass (p=none dis=none) header.from=chromium.org Authentication-Results: phobos.denx.de; spf=pass smtp.mailfrom=u-boot-bounces@lists.denx.de Authentication-Results: phobos.denx.de; dkim=pass (1024-bit key; unprotected) header.d=chromium.org header.i=@chromium.org header.b="LGGNX0p0"; dkim-atps=neutral Received: by phobos.denx.de (Postfix, from userid 109) id 3925F831D6; Thu, 19 Aug 2021 05:46:43 +0200 (CEST) Received: from mail-oi1-x22a.google.com (mail-oi1-x22a.google.com [IPv6:2607:f8b0:4864:20::22a]) (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 347FF83146 for ; Thu, 19 Aug 2021 05:46:32 +0200 (CEST) Authentication-Results: phobos.denx.de; dmarc=pass (p=none dis=none) header.from=chromium.org Authentication-Results: phobos.denx.de; spf=pass smtp.mailfrom=sjg@chromium.org Received: by mail-oi1-x22a.google.com with SMTP id u10so6673548oiw.4 for ; Wed, 18 Aug 2021 20:46:32 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=chromium.org; s=google; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=pGrLAuuHoku1SaDccdEKPmOjej4Y7H9rkHk6YAY5Ak0=; b=LGGNX0p0fRtdPGiL4QGi8nJy6OJxVItn+VELsGU4qD8Iw+LWk7Occ228zN+Alx+Rbr LsLAORQGkALVntHzatvyatpdcRq9lozaDfiJyqe09XmvXHVoEYfvnPuWsHKe/4iURtBC aiQcXDxV+g6oXVn7bobOAtgevjlN8G8oVe6OE= X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=pGrLAuuHoku1SaDccdEKPmOjej4Y7H9rkHk6YAY5Ak0=; b=mO8Gi9QeoB9la34RYz9esOofYXY0YdOO7LanzVocDCZ5/HisAcTfgwjOPQ7W9L7POd txGIbq0+nHDgccTy3swBjlOI52/b0UD0lM2CUrNOIdvPf7XYQXqIC+3QeSeKKrKQUNbb 72VY0xCmcbCXs6uV8DEtBIzg835XijGtmeArfB0wHRQquuJ/q/4FetaZOWNXCwMnnCI9 8ZQtqOzkIsiGMpJsy1THuBlMNGtKhNJ6MCU4+RfZkEVtJQ/nGw6bHeoZ/bACZ1RsJ4ZA lrYY851ta4ZpUNIXWoLtEeK3ELBq8KOFCawCWuNCc3bP0/90QTPIQYYjqAaEgCNlYpdK pP+w== X-Gm-Message-State: AOAM530u2wQingfj9rnalJPCcGXN5v67ruE56PSB16Pm+qj4ROPfReI2 arHGoHWjb3nz2zb6cP0dS0tJbEfRNt84xw== X-Google-Smtp-Source: ABdhPJyWqDjvmrBMpT92dQhqovaxuYqA7e8EVsPL3PNGn8lW3gxoYRDzvbjjBWaQp0vOtxboIWHUxQ== X-Received: by 2002:aca:ea54:: with SMTP id i81mr1111946oih.174.1629344790513; Wed, 18 Aug 2021 20:46:30 -0700 (PDT) Received: from kiwi.bld.corp.google.com (c-67-190-101-114.hsd1.co.comcast.net. [67.190.101.114]) by smtp.gmail.com with ESMTPSA id q3sm370025ooa.13.2021.08.18.20.46.29 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Wed, 18 Aug 2021 20:46:30 -0700 (PDT) From: Simon Glass To: U-Boot Mailing List Cc: Ilias Apalodimas , Steffen Jaeckel , Michal Simek , Tom Rini , Dennis Gilmore , Daniel Schwierzeck , Lukas Auer , Simon Glass Subject: [PATCH 17/28] doc: Move distro boot doc to rST Date: Wed, 18 Aug 2021 21:45:50 -0600 Message-Id: <20210818214547.17.Icbffbc563f1de65873914fb8e073c7e2d6103891@changeid> X-Mailer: git-send-email 2.33.0.rc1.237.g0d66db33f3-goog In-Reply-To: <20210819034601.1618773-1-sjg@chromium.org> References: <20210819034601.1618773-1-sjg@chromium.org> MIME-Version: 1.0 Content-Transfer-Encoding: 8bit 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 Move this over to the new rST format. Signed-off-by: Simon Glass --- 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 c4f041ca712..105dcf28190 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 83c929babda..1fb0f06f6e8 100644 --- a/doc/develop/index.rst +++ b/doc/develop/index.rst @@ -12,6 +12,7 @@ Implementation ci_testing commands devicetree/index + distro driver-model/index global_data logging -- 2.33.0.rc1.237.g0d66db33f3-goog