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