| 160 | | |
| 161 | | [=#distro-config] |
| 162 | | == Distro Config |
| 163 | | The Newport 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. |
| 164 | | |
| 165 | | 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: |
| 166 | | - **boot_targets** - list of target device type/nums to search: defaults to mmc0 mmc1 usb0 sata0 |
| 167 | | - **devplist** - ''dynamically created'' list of all partitions flagged as 'bootable' |
| 168 | | - **boot_prefixes** - list of directories within a partition searched for bootscripts |
| 169 | | - **boot_scripts** - list of boot script names searched for |
| 170 | | |
| 171 | | |
| 172 | | [=#bootscript] |
| 173 | | == Boot Scripts |
| 174 | | When writing bootscripts compatible with [#distro-config Distro Config] you can assume the following env variables: |
| 175 | | - **devtype** - the device type the script was loaded from (mmc|usb|sata) |
| 176 | | - **devnum** - the device number the script was loaded from (ie 0 for mmc0, 1 for mmc1, etc) |
| 177 | | - **distro_bootpart** - the partition number the script was loaded from (ie 0, 1, etc) |
| 178 | | - **fdtcontroladdr** - the address the device-tree is at (Note that the Newport 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) |
| 179 | | - **kernel_addr_r** - address where kernel can be loaded |
| 180 | | - **bootargs** - default bootargs to pass to the kernel - you probably want to add to this and not overwrite it |
| 181 | | - **console** - the serial console device to pass to the kernel |
| 182 | | |
| 183 | | Additionally you should note the following: |
| 184 | | - use load/ls/save commands which support FAT/ext filesystem types automatically instead of the fs specific commands |
| 185 | | - 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. |
| 186 | | |
| 187 | | 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: |
| 188 | | {{{#!bash |
| 189 | | mkimage -A arm64 -T script -C none -d ubuntu.txt newport.scr |
| 190 | | }}} |
| 191 | | |
| 192 | | The bootscript can be updated at runtime on the target. For example: |
| 193 | | {{{#!bash |
| 194 | | mkimage -A arm64 -T script -C none -d ubuntu.txt /boot/newport.scr |
| 195 | | }}} |
| 196 | | |
| 197 | | If storing the bootscript on the embedded FATFS partition (which would make sense if your root filesystem is something that is not supported by the Bootloader such as F2FS or BTRFS): |
| 198 | | * You can update the bootscript uImage {{{newport.scr}}} in the boot firmware: |
| 199 | | {{{#!bash |
| 200 | | fatfs-tool -i firmware-newport.img cp newport.scr / |
| 201 | | }}} |
| 202 | | * You can udpate the bootscript uImage {{{newport.scr}}} on a live target via: |
| 203 | | {{{#!bash |
| 204 | | mount /dev/mmcblk0p1 /mnt |
| 205 | | mkimage -A arm64 -T script -C none -d ubuntu.txt /mnt/newport.scr |
| 206 | | umount |
| 207 | | }}} |
| 208 | | |
| 209 | | |
| 210 | | |
| 211 | | [=#boot_targets] |
| 212 | | === Boot Device Order (boot_targets) === |
| 213 | | While the Newport product family can only boot its [wiki:newport/boot Boot Firmware] from an MMC device (ie eMMC or microSD), once you are booted to the bootloader you can choose from a wider variety of devices to boot the OS from. |
| 214 | | |
| 215 | | 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 {{{mmc0 mmc1 usb0 sata0}}}. |
| 216 | | |
| 217 | | For example, to limit OS booting to only SATA: |
| 218 | | {{{#!bash |
| 219 | | setenv boot_targets sata0 |
| 220 | | saveenv |
| 221 | | }}} |
| 222 | | |
| 223 | | |
| 224 | | [=#fit] |
| 225 | | == Flattened Image Tree (FIT) images == |
| 226 | | 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). |
| 227 | | |
| 228 | | Quick summary of FIT Images: |
| 229 | | * introduced to resolve limitations with original single-image formats and follow-on multi-image format supported by UBoot bootm (boot memory) |
| 230 | | * uses power of the Device-Tree-Compiler (DTC) |
| 231 | | * FIT .itb files can be created with mkimage |
| 232 | | * U-Boot supports FIT with several commands: |
| 233 | | - {{{source <addr>:<name>}}} # source a script by name from FIT image in memory |
| 234 | | - {{{iminfo <fitaddress>}}} # print all the info contained in a FIT image in memory and verify (just not boot it) |
| 235 | | - {{{imextract <fitaddress> <item> <addr>}}} # extract item (ie kernel@1) to addr |
| 236 | | - {{{bootm <fitaddress>[#conf] - $fdtcontroladdr}}} # boot default or 'conf' configuration (ie #config@1) |
| 237 | | - {{{bootm start <fitaddress>[#conf] - $fdtcontroladdr}}} # boot from memory a specific configuration (or default configuration) from FIT image |
| 238 | | |
| 239 | | Example: |
| 240 | | * create FIT image comprised of compressed kernel image: |
| 241 | | {{{#!bash |
| 242 | | cp arch/arm64/boot/Image . |
| 243 | | gzip Image |
| 244 | | mkimage -f auto -A arm64 -O linux -T kernel -C gzip -n "Kernel" \ |
| 245 | | -a 20080000 -e 20080000 -d Image.gz kernel.itb |
| 246 | | }}} |
| 247 | | * boot the default configuration from U-Boot. For example if your using an ext4 fs on the first MMC device, 2nd partition use: |
| 248 | | {{{#!bash |
| 249 | | tftpboot $loadaddr kernel.itb && setenv bootargs 'console=ttyAMA0,115200n8 earlycon=pl011,0x87e028000000 coherent_poll=64M root=/dev/mmcblk0p2 rootfstype=ext4 rootwait rw' && bootm $loadaddr - $fdtcontroladdr |
| 250 | | }}} |
| 251 | | |
| 252 | | The Newport BSP also uses the [https://github.com/Gateworks/bsp-newport/blob/master/newport.env newport/newport.env] bootscript to create its kernel parameters which may be useful to understand. |
| 253 | | |
| 254 | | References: |
| 255 | | * [http://git.denx.de/?p=u-boot.git;a=tree;f=doc/uImage.FIT doc/uImage.FIT] |
| 256 | | * http://www.denx.de/wiki/pub/U-Boot/Documentation/multi_image_booting_scenarios.pdf |
| 257 | | * http://elinux.org/images/f/f4/Elc2013_Fernandes.pdf |
| 258 | | |
| 259 | | = U-boot tools |
| 260 | | |
| 261 | | A detailed description of u-boot-tools usage can be found [wiki:/ventana/bootloader#U-Bootenvtoolsfw_printenvfw_setenv here]. |
| 262 | | |
| 263 | | In order to configure u-boot-tools to work correctly for Newport you will need a fw_env.config file the appropriate values. |
| 264 | | |
| 265 | | This file will be downloaded as part of the [http://trac.gateworks.com/wiki/newport/bsp#BuildingtheBSPfromsource Newport BSP] and found in the newport/ folder. |
| 266 | | |
| 267 | | To create this file: |
| 268 | | |
| 269 | | {{{#!bash |
| 270 | | cat << EOF > /etc/fw_env.config |
| 271 | | # Device offset Env. size |
| 272 | | /dev/mmcblk0 0xff0000 0x8000 |
| 273 | | /dev/mmcblk0 0xff8000 0x8000 |
| 274 | | EOF |
| 275 | | }}} |
| 276 | | |
| 277 | | Further information on these offsets and the adjcent data can be found [wiki:/newport/boot#BootFirmareImage here]. |
| 278 | | |
