Changes between Version 1 and Version 2 of newport/boot

Timestamp:

02/10/2018 01:12:18 AM (7 years ago)

Author:

Tim Harvey

Comment:

added section on creating bootable disk images

newport/boot

@@ -125 +125 @@
  * the ATF defines the the location of the FIP image (plat/cavium/common/thunder_io_storage.c fip_block_spec.offset)
  * the U-Boot Bootloader config defines the location of the U-Boot env (CONFIG_ENV_OFFSET/CONFIG_ENV_SIZE/CONFIG_ENV_OFFSET_REDUND)
+
+
+[=#disk-images]
+== Building a Bootable Disk Images ==
+Gateworks 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.
+
+Once 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]).
+
+The basic steps to create a bootable image of your Linux based OS are:
+ 1. start with the 16MB Newport [wiki:newport/boot Boot Firmware] (firmware-newport.img)
+ 1. (optional) update it's partition table if necessary:
+  - 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.
+  - the second partition by default starts at the end of the 16MB boot firmware and extends to then end of the image
+  - 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
+ 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.
+ 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.
+ 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)
+ 1. compress the resulting disk image (so it can fit into DRAM without slicing and reduces transfer/writing time)
+
+This is process made easy using scripts available in the [wiki:newport/bsp Gateworks Newport BSP]:
+{{{#!bash
+# define some variables
+OUT=myimage.img
+
+# 1. start with firmware-newport.img
+cp firmware-newport.img $OUT
+
+# 2. update it's partition table if necessary
+# - use 'sfdisk -l -uS $OUT' to show the partition table
+# - use 'newport/ptgen -o $OUT -p ...' to adjust partition table if desired
+# - make sure you don't change the first partition as the start/end of that is dictated by
+#   the boot firmware
+sfdisk -l -uS $OUT # show partition table
+
+# 3. create a uImage bootscript and kernel.itb and place them on FAT12 partition:
+# - you can use the newport/ubuntu.scr as a sample bootscript which shows how to
+#   load and execute a compressed kernel in a FIT image: kernel.itb
+# - create kernel.itb with compressed kernel image
+# - use newport/mkits.sh to create a kernel.its template
+# - use mkimage to create a fit image from the template
+# - use fatfs-tool to copy the files into the FATFS filesystem within the image
+cp linux/arch/arm64/boot/Image vmlinux
+gzip -f vmlinux
+./newport/mkits.sh -o kernel.its -k vmlinux.gz -C gzip -v "Newport Kernel"
+mkimage -f kernel.its kernel.itb
+# inject the kernel.itb into the FAT12 filesystem
+fatfs-tool -i $OUT cp kernel.itb /
+# create bootscript and inect it into the FAT12 filesystem 
+mkimage -A arm64 -T script -C none -d newport/ubuntu.scr newport.scr
+fatfs-tool -i $OUT cp newport.scr /
+# you can use fatfs-tool to list the contents of the FAT12 and see your files
+fatfs-tool -i $OUT ls
+
+# 4. create your root filesystem
+# - you can use the newport/mkfs script to create an f2fs|ext4 fs from a set of dirs/tarballs
+# - specify a minimum filesystem size to keep your image small in order to
+#   a) fit in SDRAM if using U-Boot tftpboot/gzwrite to update
+#   b) transfer quickly
+#   c) write less data and thus more quickly
+# - once booted you can resize2fs for ext4 or 
+sudo ./newport/mkfs ext4 xenial-newport.ext4 1536M linux-newport.tar.xz xenial-newport.tar.xz
+
+# 5. copy your filesystem to the correct partition offset
+# (16MB unless you've had reason to change it)
+dd if=xenial-newport.ext4 of=$OUT bs=16M seek=1
+
+# 6. compress it
+#  - add a '-k' flag if you want to keep around the uncompressed image to perform
+#    more maintanence on it like partition changes or FAT12 fs changes
+gzip -f $OUT
+}}}
+
+To 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:
+ * UBUNTU_KERNEL (uncompressed kernel Image, defaults to linux/arch/arm64/boot/Image)
+ * UBUNTU_FS (uncompressed filesystem image defaults to xenial-newport.ext4)
+ * UBUNTU_IMG (output file without the .gz extension, defaults to xenial-newport.img):
+{{{#!bash
+# create uncompressed root filesystem image
+sudo ./newport/mkfs ext4 xenial-newport.ext4 1536M linux-newport.tar.xz xenial-newport.tar.xz
+UBUNTU_KERNEL=linux/arch/arm64/boot/Image UBUNTU_FS=xenial-newport.ext4 UBUNTU_IMG=myimage make ubuntu-image
+}}}
+
+You can now install this using the methods described in [wiki:newport#firmware-update newport/firware-update]. For example in the bootloader:
+{{{#!bash
+setenv dev 0 # specify 0 for primary boot device; use mmc list to see all mmc devs
+tftpboot ${loadaddr} myimage.img.gz && gzwrite mmc ${dev} ${loadaddr} ${filesize}
+}}}
+
+If 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):
+ * ext4 filesystem booted on MMC device (resize2fs)
+{{{#!bash
+resize2fs /dev/mmcblk0p2
+}}}
+
+Note 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).
+
+To install the kernel and root filesystem on a removable block storage device see [wiki:linux/blockdev].