Changes between Version 1 and Version 2 of newport/boot


Ignore:
Timestamp:
02/09/2018 05:12:18 PM (6 months ago)
Author:
Tim Harvey
Comment:

added section on creating bootable disk images

Legend:

Unmodified
Added
Removed
Modified
  • newport/boot

    v1 v2  
    125125 * the ATF defines the the location of the FIP image (plat/cavium/common/thunder_io_storage.c fip_block_spec.offset)
    126126 * the U-Boot Bootloader config defines the location of the U-Boot env (CONFIG_ENV_OFFSET/CONFIG_ENV_SIZE/CONFIG_ENV_OFFSET_REDUND)
     127
     128
     129[=#disk-images]
     130== Building a Bootable Disk Images ==
     131Gateworks releases disk images that can be easily flashed using the U-Boot Bootloader (see [wiki:newport#serial-ethernet here]). These disk images contain a partition table so they are tailored to the specific device size they are intended for. Additionally they are configured for a small partition size to keep flash programming time at a minimum. This requires resizing the rootfs filesystem in order to take advantage of the remaining flash space.
     132
     133Once you have a root filesystem directory/tarball and have a kernel Image you can create a compressed disk image that can be installed easily from the bootloader (see [wiki:newport#firmware-update newport/firmware-update]).
     134
     135The basic steps to create a bootable image of your Linux based OS are:
     136 1. start with the 16MB Newport [wiki:newport/boot Boot Firmware] (firmware-newport.img)
     137 1. (optional) update it's partition table if necessary:
     138  - the first partition is the FAT12 partition integrated into the Boot Firmware and thus its start/end is dictated by the boot firmware itself and should not be changed.
     139  - the second partition by default starts at the end of the 16MB boot firmware and extends to then end of the image
     140  - the end of the image is dictated the size of the target FLASH device. The 8GB eMMC on Newport has a usable user partition size of 7264MB thus the 2nd partition can be 7264-16=7248MB
     141 1. place a [wiki:newport/bootloader#bootscript uImage bootscript] and kernel image on a bootable partition such as the FAT12 partition in the boot firmware. Alternatively your bootscript can look for the kernel wherever U-Boot can access it but typically we compress the kernel and place it into a [wiki:newport/bootloader#fit FIT image] and put it along side the bootscript.
     142 1. create a root filesystem image (using a filesystem type supported by your kernel). You can use the {{{mkfs}}} script in the Newport BSP to create ext4 and f2fs filesystem images.
     143 1. copy your filesystem image into the image file at the offset dictated by the partition table (16MB using the default partition table in firmware-newport.img)
     144 1. compress the resulting disk image (so it can fit into DRAM without slicing and reduces transfer/writing time)
     145
     146This is process made easy using scripts available in the [wiki:newport/bsp Gateworks Newport BSP]:
     147{{{#!bash
     148# define some variables
     149OUT=myimage.img
     150
     151# 1. start with firmware-newport.img
     152cp firmware-newport.img $OUT
     153
     154# 2. update it's partition table if necessary
     155# - use 'sfdisk -l -uS $OUT' to show the partition table
     156# - use 'newport/ptgen -o $OUT -p ...' to adjust partition table if desired
     157# - make sure you don't change the first partition as the start/end of that is dictated by
     158#   the boot firmware
     159sfdisk -l -uS $OUT # show partition table
     160
     161# 3. create a uImage bootscript and kernel.itb and place them on FAT12 partition:
     162# - you can use the newport/ubuntu.scr as a sample bootscript which shows how to
     163#   load and execute a compressed kernel in a FIT image: kernel.itb
     164# - create kernel.itb with compressed kernel image
     165# - use newport/mkits.sh to create a kernel.its template
     166# - use mkimage to create a fit image from the template
     167# - use fatfs-tool to copy the files into the FATFS filesystem within the image
     168cp linux/arch/arm64/boot/Image vmlinux
     169gzip -f vmlinux
     170./newport/mkits.sh -o kernel.its -k vmlinux.gz -C gzip -v "Newport Kernel"
     171mkimage -f kernel.its kernel.itb
     172# inject the kernel.itb into the FAT12 filesystem
     173fatfs-tool -i $OUT cp kernel.itb /
     174# create bootscript and inect it into the FAT12 filesystem
     175mkimage -A arm64 -T script -C none -d newport/ubuntu.scr newport.scr
     176fatfs-tool -i $OUT cp newport.scr /
     177# you can use fatfs-tool to list the contents of the FAT12 and see your files
     178fatfs-tool -i $OUT ls
     179
     180# 4. create your root filesystem
     181# - you can use the newport/mkfs script to create an f2fs|ext4 fs from a set of dirs/tarballs
     182# - specify a minimum filesystem size to keep your image small in order to
     183#   a) fit in SDRAM if using U-Boot tftpboot/gzwrite to update
     184#   b) transfer quickly
     185#   c) write less data and thus more quickly
     186# - once booted you can resize2fs for ext4 or
     187sudo ./newport/mkfs ext4 xenial-newport.ext4 1536M linux-newport.tar.xz xenial-newport.tar.xz
     188
     189# 5. copy your filesystem to the correct partition offset
     190# (16MB unless you've had reason to change it)
     191dd if=xenial-newport.ext4 of=$OUT bs=16M seek=1
     192
     193# 6. compress it
     194#  - add a '-k' flag if you want to keep around the uncompressed image to perform
     195#    more maintanence on it like partition changes or FAT12 fs changes
     196gzip -f $OUT
     197}}}
     198
     199To further simplify this process, the Newport BSP Makefile has a 'ubuntu-image' make target that will do all of the above for you if you provide env variables:
     200 * UBUNTU_KERNEL (uncompressed kernel Image, defaults to linux/arch/arm64/boot/Image)
     201 * UBUNTU_FS (uncompressed filesystem image defaults to xenial-newport.ext4)
     202 * UBUNTU_IMG (output file without the .gz extension, defaults to xenial-newport.img):
     203{{{#!bash
     204# create uncompressed root filesystem image
     205sudo ./newport/mkfs ext4 xenial-newport.ext4 1536M linux-newport.tar.xz xenial-newport.tar.xz
     206UBUNTU_KERNEL=linux/arch/arm64/boot/Image UBUNTU_FS=xenial-newport.ext4 UBUNTU_IMG=myimage make ubuntu-image
     207}}}
     208
     209You can now install this using the methods described in [wiki:newport#firmware-update newport/firware-update]. For example in the bootloader:
     210{{{#!bash
     211setenv dev 0 # specify 0 for primary boot device; use mmc list to see all mmc devs
     212tftpboot ${loadaddr} myimage.img.gz && gzwrite mmc ${dev} ${loadaddr} ${filesize}
     213}}}
     214
     215If you created a filesystem that did not stretch to the partition it was installed on (as above where we created a 1536MB filesystem image to fit within a 7264M partition) you will want to resize it after booting (one time operation):
     216 * ext4 filesystem booted on MMC device (resize2fs)
     217{{{#!bash
     218resize2fs /dev/mmcblk0p2
     219}}}
     220
     221Note there is no requirement that your root filesystem be on the boot device containing the 16MB Boot Firmware. You have other options as well as long as you have a bootscript that the bootloader can find, load, and execute. For example you could choose to put your bootscript in the FAT12 filesystem and have it load a kernel from an ext4 rootfs /boot/Image directory. You could also for that matter, have another device such as a mSATA with a single ext4 filesystem (make sure the partition is flagged as bootable) with a bootscript/kernel in its / or /boot directory (as those are in the search path for boot scripts).
     222
     223To install the kernel and root filesystem on a removable block storage device see [wiki:linux/blockdev].