README.distro 17 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430
  1. SPDX-License-Identifier: GPL-2.0+
  2. /*
  3. * (C) Copyright 2014 Red Hat Inc.
  4. * Copyright (c) 2014-2015, NVIDIA CORPORATION. All rights reserved.
  5. * Copyright (C) 2015 K. Merker <merker@debian.org>
  6. */
  7. Generic Distro Configuration Concept
  8. ====================================
  9. Linux distributions are faced with supporting a variety of boot mechanisms,
  10. environments or bootloaders (PC BIOS, EFI, U-Boot, Barebox, ...). This makes
  11. life complicated. Worse, bootloaders such as U-Boot have a configurable set
  12. of features, and each board chooses to enable a different set of features.
  13. Hence, distros typically need to have board-specific knowledge in order to
  14. set up a bootable system.
  15. This document defines a common set of U-Boot features that are required for
  16. a distro to support the board in a generic fashion. Any board wishing to
  17. allow distros to install and boot in an out-of-the-box fashion should enable
  18. all these features. Linux distros can then create a single set of boot
  19. support/install logic that targets these features. This will allow distros
  20. to install on many boards without the need for board-specific logic.
  21. In fact, some of these features can be implemented by any bootloader, thus
  22. decoupling distro install/boot logic from any knowledge of the bootloader.
  23. This model assumes that boards will load boot configuration files from a
  24. regular storage mechanism (eMMC, SD card, USB Disk, SATA disk, etc.) with
  25. a standard partitioning scheme (MBR, GPT). Boards that cannot support this
  26. storage model are outside the scope of this document, and may still need
  27. board-specific installer/boot-configuration support in a distro.
  28. To some extent, this model assumes that a board has a separate boot flash
  29. that contains U-Boot, and that the user has somehow installed U-Boot to this
  30. flash before running the distro installer. Even on boards that do not conform
  31. to this aspect of the model, the extent of the board-specific support in the
  32. distro installer logic would be to install a board-specific U-Boot package to
  33. the boot partition during installation. This distro-supplied U-Boot can still
  34. implement the same features as on any other board, and hence the distro's boot
  35. configuration file generation logic can still be board-agnostic.
  36. Locating Bootable Disks
  37. -----------------------
  38. Typical desktop/server PCs search all (or a user-defined subset of) attached
  39. storage devices for a bootable partition, then load the bootloader or boot
  40. configuration files from there. A U-Boot board port that enables the features
  41. mentioned in this document will search for boot configuration files in the
  42. same way.
  43. Thus, distros do not need to manipulate any kind of bootloader-specific
  44. configuration data to indicate which storage device the system should boot
  45. from.
  46. Distros simply need to install the boot configuration files (see next
  47. section) in an ext2/3/4 or FAT partition, mark the partition bootable (via
  48. the MBR bootable flag, or GPT legacy_bios_bootable attribute), and U-Boot (or
  49. any other bootloader) will find those boot files and execute them. This is
  50. conceptually identical to creating a grub2 configuration file on a desktop
  51. PC.
  52. Note that in the absence of any partition that is explicitly marked bootable,
  53. U-Boot falls back to searching the first valid partition of a disk for boot
  54. configuration files. Other bootloaders are recommended to do the same, since
  55. I believe that partition table bootable flags aren't so commonly used outside
  56. the realm of x86 PCs.
  57. U-Boot can also search for boot configuration files from a TFTP server.
  58. Boot Configuration Files
  59. ------------------------
  60. The standard format for boot configuration files is that of extlinux.conf, as
  61. handled by U-Boot's "syslinux" (disk) or "pxe boot" (network). This is roughly
  62. as specified at:
  63. http://www.freedesktop.org/wiki/Specifications/BootLoaderSpec/
  64. ... with the exceptions that the BootLoaderSpec document:
  65. * Prescribes a separate configuration per boot menu option, whereas U-Boot
  66. lumps all options into a single extlinux.conf file. Hence, U-Boot searches
  67. for /extlinux/extlinux.conf then /boot/extlinux/extlinux.conf on disk, or
  68. pxelinux.cfg/default over the network.
  69. * Does not document the fdtdir option, which automatically selects the DTB to
  70. pass to the kernel.
  71. One example extlinux.conf generated by the Fedora installer is:
  72. ------------------------------------------------------------
  73. # extlinux.conf generated by anaconda
  74. ui menu.c32
  75. menu autoboot Welcome to Fedora. Automatic boot in # second{,s}. Press a key for options.
  76. menu title Fedora Boot Options.
  77. menu hidden
  78. timeout 50
  79. #totaltimeout 9000
  80. default Fedora (3.17.0-0.rc4.git2.1.fc22.armv7hl+lpae) 22 (Rawhide)
  81. label Fedora (3.17.0-0.rc4.git2.1.fc22.armv7hl) 22 (Rawhide)
  82. kernel /boot/vmlinuz-3.17.0-0.rc4.git2.1.fc22.armv7hl
  83. append ro root=UUID=8eac677f-8ea8-4270-8479-d5ddbb797450 console=ttyS0,115200n8 LANG=en_US.UTF-8 drm.debug=0xf
  84. fdtdir /boot/dtb-3.17.0-0.rc4.git2.1.fc22.armv7hl
  85. initrd /boot/initramfs-3.17.0-0.rc4.git2.1.fc22.armv7hl.img
  86. label Fedora (3.17.0-0.rc4.git2.1.fc22.armv7hl+lpae) 22 (Rawhide)
  87. kernel /boot/vmlinuz-3.17.0-0.rc4.git2.1.fc22.armv7hl+lpae
  88. append ro root=UUID=8eac677f-8ea8-4270-8479-d5ddbb797450 console=ttyS0,115200n8 LANG=en_US.UTF-8 drm.debug=0xf
  89. fdtdir /boot/dtb-3.17.0-0.rc4.git2.1.fc22.armv7hl+lpae
  90. initrd /boot/initramfs-3.17.0-0.rc4.git2.1.fc22.armv7hl+lpae.img
  91. label Fedora-0-rescue-8f6ba7b039524e0eb957d2c9203f04bc (0-rescue-8f6ba7b039524e0eb957d2c9203f04bc)
  92. kernel /boot/vmlinuz-0-rescue-8f6ba7b039524e0eb957d2c9203f04bc
  93. initrd /boot/initramfs-0-rescue-8f6ba7b039524e0eb957d2c9203f04bc.img
  94. append ro root=UUID=8eac677f-8ea8-4270-8479-d5ddbb797450 console=ttyS0,115200n8
  95. fdtdir /boot/dtb-3.16.0-0.rc6.git1.1.fc22.armv7hl+lpae
  96. ------------------------------------------------------------
  97. Another hand-crafted network boot configuration file is:
  98. ------------------------------------------------------------
  99. TIMEOUT 100
  100. MENU TITLE TFTP boot options
  101. LABEL jetson-tk1-emmc
  102. MENU LABEL ../zImage root on Jetson TK1 eMMC
  103. LINUX ../zImage
  104. FDTDIR ../
  105. APPEND console=ttyS0,115200n8 console=tty1 loglevel=8 rootwait rw earlyprintk root=PARTUUID=80a5a8e9-c744-491a-93c1-4f4194fd690b
  106. LABEL venice2-emmc
  107. MENU LABEL ../zImage root on Venice2 eMMC
  108. LINUX ../zImage
  109. FDTDIR ../
  110. APPEND console=ttyS0,115200n8 console=tty1 loglevel=8 rootwait rw earlyprintk root=PARTUUID=5f71e06f-be08-48ed-b1ef-ee4800cc860f
  111. LABEL sdcard
  112. MENU LABEL ../zImage, root on 2GB sdcard
  113. LINUX ../zImage
  114. FDTDIR ../
  115. APPEND console=ttyS0,115200n8 console=tty1 loglevel=8 rootwait rw earlyprintk root=PARTUUID=b2f82cda-2535-4779-b467-094a210fbae7
  116. LABEL fedora-installer-fk
  117. MENU LABEL Fedora installer w/ Fedora kernel
  118. LINUX fedora-installer/vmlinuz
  119. INITRD fedora-installer/initrd.img.orig
  120. FDTDIR fedora-installer/dtb
  121. APPEND loglevel=8 ip=dhcp inst.repo=http://10.0.0.2/mirrors/fedora/linux/development/rawhide/armhfp/os/ rd.shell cma=64M
  122. ------------------------------------------------------------
  123. U-Boot Implementation
  124. =====================
  125. Enabling the distro options
  126. ---------------------------
  127. In your board's defconfig, enable the DISTRO_DEFAULTS option by adding
  128. a line with "CONFIG_DISTRO_DEFAULTS=y". If you want to enable this
  129. from Kconfig itself, for e.g. all boards using a specific SoC then
  130. add a "imply DISTRO_DEFAULTS" to your SoC CONFIG option.
  131. In your board configuration file, include the following:
  132. ------------------------------------------------------------
  133. #ifndef CONFIG_SPL_BUILD
  134. #include <config_distro_bootcmd.h>
  135. #endif
  136. ------------------------------------------------------------
  137. The first of those headers primarily enables a core set of U-Boot features,
  138. such as support for MBR and GPT partitions, ext* and FAT filesystems, booting
  139. raw zImage and initrd (rather than FIT- or uImage-wrapped files), etc. Network
  140. boot support is also enabled here, which is useful in order to boot distro
  141. installers given that distros do not commonly distribute bootable install
  142. media for non-PC targets at present.
  143. Finally, a few options that are mostly relevant only when using U-Boot-
  144. specific boot.scr scripts are enabled. This enables distros to generate a
  145. U-Boot-specific boot.scr script rather than extlinux.conf as the boot
  146. configuration file. While doing so is fully supported, and
  147. CONFIG_DISTRO_DEFAULTS exposes enough parameterization to boot.scr to
  148. allow for board-agnostic boot.scr content, this document recommends that
  149. distros generate extlinux.conf rather than boot.scr. extlinux.conf is intended
  150. to work across multiple bootloaders, whereas boot.scr will only work with
  151. U-Boot. TODO: document the contract between U-Boot and boot.scr re: which
  152. environment variables a generic boot.scr may rely upon.
  153. The second of those headers sets up the default environment so that $bootcmd
  154. is defined in a way that searches attached disks for boot configuration files,
  155. and executes them if found.
  156. Required Environment Variables
  157. ------------------------------
  158. The U-Boot "syslinux" and "pxe boot" commands require a number of environment
  159. variables be set. Default values for these variables are often hard-coded into
  160. CONFIG_EXTRA_ENV_SETTINGS in the board's U-Boot configuration file, so that
  161. the user doesn't have to configure them.
  162. fdt_addr:
  163. Mandatory for any system that provides the DTB in HW (e.g. ROM) and wishes
  164. to pass that DTB to Linux, rather than loading a DTB from the boot
  165. filesystem. Prohibited for any other system.
  166. If specified a DTB to boot the system must be available at the given
  167. address.
  168. fdt_addr_r:
  169. Mandatory. The location in RAM where the DTB will be loaded or copied to when
  170. processing the fdtdir/devicetreedir or fdt/devicetree options in
  171. extlinux.conf.
  172. This is mandatory even when fdt_addr is provided, since extlinux.conf must
  173. always be able to provide a DTB which overrides any copy provided by the HW.
  174. A size of 1MB for the FDT/DTB seems reasonable.
  175. fdtfile:
  176. Mandatory. the name of the DTB file for the specific board for instance
  177. the espressobin v5 board the value is "marvell/armada-3720-espressobin.dtb"
  178. while on a clearfog pro it is "armada-388-clearfog-pro.dtb" in the case of
  179. a board providing its firmware based DTB this value can be used to override
  180. the DTB with a different DTB. fdtfile will automatically be set for you if
  181. it matches the format ${soc}-${board}.dtb which covers most 32 bit use cases.
  182. AArch64 generally does not match as the Linux kernel put the dtb files under
  183. SoC vendor directories.
  184. ramdisk_addr_r:
  185. Mandatory. The location in RAM where the initial ramdisk will be loaded to
  186. when processing the initrd option in extlinux.conf.
  187. It is recommended that this location be highest in RAM out of fdt_addr_,
  188. kernel_addr_r, and ramdisk_addr_r, so that the RAM disk can vary in size
  189. and use any available RAM.
  190. kernel_addr_r:
  191. Mandatory. The location in RAM where the kernel will be loaded to when
  192. processing the kernel option in the extlinux.conf.
  193. The kernel should be located within the first 128M of RAM in order for the
  194. kernel CONFIG_AUTO_ZRELADDR option to work, which is likely enabled on any
  195. distro kernel. Since the kernel will decompress itself to 0x8000 after the
  196. start of RAM, kernel_addr_r should not overlap that area, or the kernel will
  197. have to copy itself somewhere else first before decompression.
  198. A size of 16MB for the kernel is likely adequate.
  199. kernel_comp_addr_r:
  200. Optional. This is only required if user wants to boot Linux from a compressed
  201. Image(.gz, .bz2, .lzma, .lzo) using the booti command. It represents the
  202. location in RAM where the compressed Image will be decompressed temporarily.
  203. Once the decompression is complete, the decompressed data will be moved to
  204. kernel_addr_r for booting.
  205. kernel_comp_size:
  206. Optional. This is only required if user wants to boot Linux from a compressed
  207. Image using booti command. It represents the size of the compressed file. The
  208. size has to at least the size of loaded image for decompression to succeed.
  209. pxefile_addr_r:
  210. Mandatory. The location in RAM where extlinux.conf will be loaded to prior
  211. to processing.
  212. A size of 1MB for extlinux.conf is more than adequate.
  213. scriptaddr:
  214. Mandatory, if the boot script is boot.scr rather than extlinux.conf. The
  215. location in RAM where boot.scr will be loaded to prior to execution.
  216. A size of 1MB for extlinux.conf is more than adequate.
  217. For suggestions on memory locations for ARM systems, you must follow the
  218. guidelines specified in Documentation/arm/Booting in the Linux kernel tree.
  219. For a commented example of setting these values, please see the definition of
  220. MEM_LAYOUT_ENV_SETTINGS in include/configs/tegra124-common.h.
  221. Boot Target Configuration
  222. -------------------------
  223. <config_distro_bootcmd.h> defines $bootcmd and many helper command variables
  224. that automatically search attached disks for boot configuration files and
  225. execute them. Boards must provide configure <config_distro_bootcmd.h> so that
  226. it supports the correct set of possible boot device types. To provide this
  227. configuration, simply define macro BOOT_TARGET_DEVICES prior to including
  228. <config_distro_bootcmd.h>. For example:
  229. ------------------------------------------------------------
  230. #ifndef CONFIG_SPL_BUILD
  231. #define BOOT_TARGET_DEVICES(func) \
  232. func(MMC, mmc, 1) \
  233. func(MMC, mmc, 0) \
  234. func(USB, usb, 0) \
  235. func(PXE, pxe, na) \
  236. func(DHCP, dhcp, na)
  237. #include <config_distro_bootcmd.h>
  238. #endif
  239. ------------------------------------------------------------
  240. Each entry in the macro defines a single boot device (e.g. a specific eMMC
  241. device or SD card) or type of boot device (e.g. USB disk). The parameters to
  242. the func macro (passed in by the internal implementation of the header) are:
  243. - Upper-case disk type (MMC, SATA, SCSI, IDE, USB, DHCP, PXE, VIRTIO).
  244. - Lower-case disk type (same options as above).
  245. - ID of the specific disk (MMC only) or ignored for other types.
  246. User Configuration
  247. ==================
  248. Once the user has installed U-Boot, it is expected that the environment will
  249. be reset to the default values in order to enable $bootcmd and friends, as set
  250. up by <config_distro_bootcmd.h>. After this, various environment variables may
  251. be altered to influence the boot process:
  252. boot_targets:
  253. The list of boot locations searched.
  254. Example: mmc0, mmc1, usb, pxe
  255. Entries may be removed or re-ordered in this list to affect the boot order.
  256. boot_prefixes:
  257. For disk-based booting, the list of directories within a partition that are
  258. searched for boot configuration files (extlinux.conf, boot.scr).
  259. Example: / /boot/
  260. Entries may be removed or re-ordered in this list to affect the set of
  261. directories which are searched.
  262. boot_scripts:
  263. The name of U-Boot style boot.scr files that $bootcmd searches for.
  264. Example: boot.scr.uimg boot.scr
  265. (Typically we expect extlinux.conf to be used, but execution of boot.scr is
  266. maintained for backwards-compatibility.)
  267. Entries may be removed or re-ordered in this list to affect the set of
  268. filenames which are supported.
  269. scan_dev_for_extlinux:
  270. If you want to disable extlinux.conf on all disks, set the value to something
  271. innocuous, e.g. setenv scan_dev_for_extlinux true.
  272. scan_dev_for_scripts:
  273. If you want to disable boot.scr on all disks, set the value to something
  274. innocuous, e.g. setenv scan_dev_for_scripts true.
  275. boot_net_usb_start:
  276. If you want to prevent USB enumeration by distro boot commands which execute
  277. network operations, set the value to something innocuous, e.g. setenv
  278. boot_net_usb_start true. This would be useful if you know your Ethernet
  279. device is not attached to USB, and you wish to increase boot speed by
  280. avoiding unnecessary actions.
  281. boot_net_pci_enum:
  282. If you want to prevent PCI enumeration by distro boot commands which execute
  283. network operations, set the value to something innocuous, e.g. setenv
  284. boot_net_pci_enum true. This would be useful if you know your Ethernet
  285. device is not attached to PCI, and you wish to increase boot speed by
  286. avoiding unnecessary actions.
  287. Interactively booting from a specific device at the u-boot prompt
  288. =================================================================
  289. For interactively booting from a user-selected device at the u-boot command
  290. prompt, the environment provides predefined bootcmd_<target> variables for
  291. every target defined in boot_targets, which can be run be the user.
  292. If the target is a storage device, the format of the target is always
  293. <device type><device number>, e.g. mmc0. Specifying the device number is
  294. mandatory for storage devices, even if only support for a single instance
  295. of the storage device is actually implemented.
  296. For network targets (dhcp, pxe), only the device type gets specified;
  297. they do not have a device number.
  298. Examples:
  299. - run bootcmd_usb0
  300. boots from the first USB mass storage device
  301. - run bootcmd_mmc1
  302. boots from the second MMC device
  303. - run bootcmd_pxe
  304. boots by tftp using a pxelinux.cfg
  305. The list of possible targets consists of:
  306. - network targets
  307. * dhcp
  308. * pxe
  309. - storage targets (to which a device number must be appended)
  310. * mmc
  311. * sata
  312. * scsi
  313. * ide
  314. * usb
  315. * virtio
  316. Other *boot* variables than the ones defined above are only for internal use
  317. of the boot environment and are not guaranteed to exist or work in the same
  318. way in future u-boot versions. In particular the <device type>_boot
  319. variables (e.g. mmc_boot, usb_boot) are a strictly internal implementation
  320. detail and must not be used as a public interface.