Changes between Version 27 and Version 28 of newport/bootloader


Ignore:
Timestamp:
05/01/2023 09:42:58 PM (14 months ago)
Author:
Tim Harvey
Comment:

move U-Boot details to new page

Legend:

Unmodified
Added
Removed
Modified
  • newport/bootloader

    v27 v28  
    22
    33[=#bootloader]
    4 = Newport U-Boot Bootloader =
     4= Newport U-Boot Bootloader
    55Gateworks supports the U-Boot Bootloader for the Newport product family. We provide pre-built firmware images (see [wiki:newport#firmware here]) as well as source for building and/or modifying it yourself.
    66
    77One of the primary features of the Bootloader is to provide access to the {{{hwconfig}}} environment variable that the firmware uses for initial board configuration on power-up.
    88
    9 == Pre-Built U-Boot Firmware ==
     9see [wiki:uboot] for more info on U-Boot
     10
     11== Pre-Built U-Boot Firmware
    1012
    1113Pre-Built U-Boot is contained inside of the Gateworks Newport boot firmware artifact here: [http://dev.gateworks.com/newport/boot_firmware/]
    1214
    13 == Version ==
     15== Version
    1416
    1517The U-Boot version used on the Newport boards is v2019.10
     
    158160'''Note that {{{hwconfig}}} is also used for pcie configuration so care should be taken to preserve that configuration if used'''
    159161
    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 
    279162= Editing the environment
    280163