| 80 | | |
| 81 | | [=#distro-config] |
| 82 | | == Distro Config |
| 83 | | The Venice Bootloader uses U-Boot's 'Distro Config' which is a well defined U-Boot env intended to make it easier for distro maintainers to develop compatible bootscripts. This primarily entails a set of 'boot scripts' and variables that control them. |
| 84 | | |
| 85 | | Ultimately this U-Boot environment is looking for a U-Boot [#bootscript boot script] on a 'bootable' partition (partitions with the 'boot' flag enabled). It searches in this order with these rules: |
| 86 | | - **boot_targets** - list of target device type/nums to search: defaults to mmc1 mmc2 usb0 usb1 pxe |
| 87 | | - **devplist** - ''dynamically created'' list of all partitions flagged as 'bootable' |
| 88 | | - **boot_prefixes** - list of directories within a partition searched for bootscripts |
| 89 | | - **boot_scripts** - list of boot script names searched for |
| 90 | | |
| 91 | | |
| 92 | | [=#bootscript] |
| 93 | | == Boot Scripts |
| 94 | | When writing bootscripts compatible with [#distro-config Distro Config] you can assume the following env variables: |
| 95 | | - **devtype** - the device type the script was loaded from (mmc|usb|sata) |
| 96 | | - **devnum** - the device number the script was loaded from (ie 0 for mmc0, 1 for mmc1, etc) |
| 97 | | - **distro_bootpart** - the partition number the script was loaded from (ie 0, 1, etc) |
| 98 | | - **fdtcontroladdr** - the address the device-tree is at (Note that the Venice bootloader does not load/manipulate the device-tree itself - this is done by the SPL which loads/manipulates the device-tree and passes it to the bootloader) |
| 99 | | - **kernel_addr_r** - address where kernel can be loaded |
| 100 | | - **bootargs** - default bootargs to pass to the kernel - you probably want to add to this and not overwrite it |
| 101 | | - **console** - the serial console device to pass to the kernel |
| 102 | | |
| 103 | | Additionally you should note the following: |
| 104 | | - use load/ls/save commands which support FAT/ext filesystem types automatically instead of the fs specific commands |
| 105 | | - if using a root filesystem that is not supported by the bootloader (ie F2FS or BTRFS) you can place your bootscript and kernel image in the FAT12 filesystem on partition 1 of the boot device. This filesystem is part of the 16MB 'Boot Firmware' image. If doing so you will need to compress the kernel and package it into a [#fit FIT image] in order to fit it in the available space. |
| 106 | | |
| 107 | | The Distro-Config environment supports legacy uImage scripts (it does not support FIT images with scripts). You can create these with the {{{mkimage}}} tool from U-Boot as such: |
| 108 | | {{{#!bash |
| 109 | | mkimage -A arm64 -T script -C none -d boot.txt boot.scr |
| 110 | | }}} |
| 111 | | |
| 112 | | The bootscript can be updated at runtime on the Linux target. For example: |
| 113 | | {{{#!bash |
| 114 | | mkimage -A arm64 -T script -C none -d boot.txt /boot/boot.scr |
| 115 | | }}} |
| 116 | | |
| 117 | | |
| 118 | | [=#boot_targets] |
| 119 | | === Boot Device Order (boot_targets) |
| 120 | | While the Venice product family can only boot from its primary boot device (typically eMMC), once you are booted to the bootloader you can choose from a wider variety of devices to boot the OS from. |
| 121 | | |
| 122 | | This OS boot device order is specified by the [#distro-config Distro Config] environment. Specifically it is controlled by the {{{boot_targets}}} env variable which defaults to {{{mmc1 mmc2 usb0 usb1 pxe}}}. |
| 123 | | |
| 124 | | For example, to limit OS booting to only USB: |
| 125 | | {{{#!bash |
| 126 | | setenv boot_targets usb0 usb1 |
| 127 | | saveenv |
| 128 | | }}} |
| 129 | | |
| 130 | | |
| 131 | | [=#fit] |
| 132 | | == Flattened Image Tree (FIT) images |
| 133 | | The U-Boot bootloader supports Flattened Image Tree (FIT) images which expand greatly on the legacy U-Boot image (uImage) format by allowing multiple binary blobs within an image. These blobs can be kernel images, ramdisk images, device-tree blobs, and bootloader scripts. Each image can also be optionally compressed (meaning U-Boot will decompress it) and check-sumed with a variety of hash mechanisms (meaning U-Boot will verify the image before using it). |
| 134 | | |
| 135 | | Quick summary of FIT Images: |
| 136 | | * introduced to resolve limitations with original single-image formats and follow-on multi-image format supported by UBoot bootm (boot memory) |
| 137 | | * uses power of the Device-Tree-Compiler (DTC) |
| 138 | | * FIT .itb files can be created with mkimage by passing in a .its file which in device-tree notation describes the images |
| 139 | | * U-Boot supports FIT with several commands: |
| 140 | | - {{{source <addr>:<name>}}} # source a script by name from FIT image in memory |
| 141 | | - {{{iminfo <fitaddress>}}} # print all the info contained in a FIT image in memory and verify (just not boot it) |
| 142 | | - {{{imextract <fitaddress> <item> <addr>}}} # extract item (ie kernel@1) to addr |
| 143 | | - {{{bootm <fitaddress>[#conf] - $fdtcontroladdr}}} # boot default or 'conf' configuration (ie #config@1) |
| 144 | | - {{{bootm start <fitaddress>[#conf] - $fdtcontroladdr}}} # boot from memory a specific configuration (or default configuration) from FIT image |
| 145 | | |
| 146 | | Example: |
| 147 | | * kernel.its with a single compressed kernel for ARM64 |
| 148 | | {{{#!bash |
| 149 | | /dts-v1/; |
| 150 | | / { |
| 151 | | description = "Simple image with single Linux kernel"; |
| 152 | | #address-cells = <1>; |
| 153 | | images { |
| 154 | | kernel@1 { |
| 155 | | description = "Linux kernel"; |
| 156 | | data = /incbin/("./Image.gz"); |
| 157 | | type = "kernel"; |
| 158 | | arch = "arm64"; |
| 159 | | os = "linux"; |
| 160 | | compression = "gzip"; |
| 161 | | load = <0x40200000>; |
| 162 | | entry = <0x40200000>; |
| 163 | | hash@1 { |
| 164 | | algo = "sha256"; |
| 165 | | }; |
| 166 | | }; |
| 167 | | }; |
| 168 | | |
| 169 | | configurations { |
| 170 | | default = "conf@1"; |
| 171 | | conf@1 { |
| 172 | | description = "Boot Linux kernel"; |
| 173 | | kernel = "kernel@1"; |
| 174 | | }; |
| 175 | | }; |
| 176 | | }; |
| 177 | | }}} |
| 178 | | * create image: |
| 179 | | {{{#!bash |
| 180 | | cp arch/arm64/boot/Image . |
| 181 | | gzip Image |
| 182 | | mkimage -f kernel.its /tftpboot/kernel.itb |
| 183 | | }}} |
| 184 | | * boot the default configuration from U-Boot: |
| 185 | | {{{#!bash |
| 186 | | tftpboot $loadaddr kernel.itb && bootm $loadaddr - $fdtcontroladdr |
| 187 | | }}} |
| 188 | | |
| 189 | | References: |
| 190 | | * [http://git.denx.de/?p=u-boot.git;a=tree;f=doc/uImage.FIT doc/uImage.FIT] |
| 191 | | * http://www.denx.de/wiki/pub/U-Boot/Documentation/multi_image_booting_scenarios.pdf |
| 192 | | * http://elinux.org/images/f/f4/Elc2013_Fernandes.pdf |
| 193 | | |
| 194 | | |
| 195 | | = U-boot env tools |
| 196 | | A detailed description of u-boot-tools usage can be found [wiki:/ventana/bootloader#U-Bootenvtoolsfw_printenvfw_setenv here]. |
| 197 | | |
| 198 | | In order to configure u-boot-tools to work correctly for Venice you will need a fw_env.config file the appropriate values. |
| 199 | | |
| 200 | | To create this file: |
| 201 | | {{{#!bash |
| 202 | | cat << EOF > /etc/fw_env.config |
| 203 | | # Device offset Env. size |
| 204 | | /dev/mmcblk2 0xff0000 0x8000 |
| 205 | | /dev/mmcblk2 0xff8000 0x8000 |
| 206 | | EOF |
| 207 | | }}} |
| 208 | | |
| | 80 | see [wiki:uboot] for more info |
