WIXLIB

How to create a partitioned image with the customWic plugin?Tips and tricks based on the bootimg-grub-tb plugin developmentNorbert Kamiński,3mdeb Embedded Systems ConsultingYocto Project Virtual Summit Europe, October 29-30, 2020

Agenda whoami Wic – OpenEmbedded Image Creator Preparing layer WKS files Wic Plug-in Interface Overall information PluginSource Methods Wic Plug-in development bootimg-grub-tb - custom Wic Plug-in2Yocto Project The Linux Foundation

whoami Norbert KamińskiOpen-source contributor meta-pcengines meta-trenchboot qubes-fwupdScope of interests embedded Linux virtualization and containerization bootloadersEmbedded Systems Engineer at3mdeb Embedded Systems Consulting3Yocto Project The Linux Foundation

Wic – OpenEmbedded Image CreatorYocto Project The Linux Foundation

What is the Wic? Wic stands for OpenEmbedded Image Creator It is used to a create partitioned image Wic is loosely based on the Meego Image Creatorframework (mic) It is using build artifacts instead of installingpackages and configurations5Yocto Project The Linux Foundation

Prepare your layer Go to your meta layer Add wic to the IMAGE FSTYPE variable in yourlocal configurationIMAGE FSTYPES "wic" Use the existing wic kickstart file or createspecific one for your purposes6Yocto Project The Linux Foundation

Default partition layouts At the start source poky/oe-init-build-env List the available wic kickstart configurations wic list rd image forcard image forcard image forEFI disk imageMPC8315E-RDBEdgerouterBeaglebonefor genericx86*Create qcow2 image for RISC-V QEMU machines Choose the WKS configuration and add it to thelocal.conf fileWKS FILE "genericx86.wks"7Yocto Project The Linux Foundation

Create your custom partition layout Go to your layer and create the wic directory Create Wic kickstart file and set the descriptionfor your partition layout# short-description: Create a partitioned image for the TrenchBoot# long-description: Create a partitioned image for the TrenchBoot Specify your custom partition ootimg-grub-tb --ondisk sda --label msdos --active --align 1024rootfs --ondisk sda --fstype ext4 --label rootfsA1 --align 4096 --fixed-size 2048rootfs --ondisk sda --fstype ext4 --label rootfsA2 --align 4096 --fixed-size 2048Yocto Project The Linux Foundation

Create your custom partition layoutpart /bootpart /part --source--source--sourcebootimg-grub-tb --ondisk sda --label msdos --active --align 1024rootfs --ondisk sda --fstype ext4 --label rootfsA1 --align 4096 --fixed-size 2048rootfs --ondisk sda --fstype ext4 --label rootfsA2 --align 4096 --fixed-size 2048part command creates partition and takes the mountpoint as the input e.g. /boot --source parameter specifies the Wic plug-in --ondisk parameter force creating the partition ona particular disk 9--fstype sets the file system for the partitionYocto Project The Linux Foundation

Create your custom partition layoutpart /bootpart /part --source--source--sourcebootimg-grub-tb --ondisk sda --label msdos --active --align 1024rootfs --ondisk sda --fstype ext4 --label rootfsA1 --align 4096 --fixed-size 2048rootfs --ondisk sda --fstype ext4 --label rootfsA2 --align 4096 --fixed-size 2048--label specifes the the label that is given for thefilesystem --active sets the partition as bootable --align specifies maximum size of boundaries betweenthe partitions (in KB) 10--fixed-size sets exact size of the partition (in MB)Yocto Project The Linux Foundation

Create your custom partition layout Specify the bootloader optionsbootloader--ptable msdos --timeout 5 --append "rootfstype ext4 console ttyS0,115200 earlyprintk serial,ttyS0,115200" If you list the available partition configurations,you will see the new custom configuration wic list teCreateCreatea partitioned image for the TrenchBootSD card image for MPC8315E-RDBSD card image for EdgerouterSD card image for Beaglebonean EFI disk image for genericx86*Create qcow2 image for RISC-V QEMU machinesYocto Project The Linux Foundation

Development tips You don’t need to flash the device to check, ifthe partition layout is correct. Use the loopdevice to this purpose: sudo losetup -P -f --show -image-pcengines-apu2.wic/dev/loop20 sudo fdisk -l /dev/loop20[.]Disk identifier: 78719Sectors Size Id Type87640 42,8M c W95 FAT32 (LBA)41943042G 83 Linux41943042G 83 LinuxYocto Project The Linux Foundation

Development tips To speed up the flashing process create thebmap artifact. Add wic.bmap and wic.gz to theIMAGE FSTYPEIMAGE FSTYPES "wic wic.gz wic.bmap" Use bmap-tool to copy the image on the drive# bmaptool copy/dev/sddbmaptool: info:bmaptool: info:bmaptool: info:bmaptool: info:bmaptool: info:bmaptool: info:bmaptool: info:13--bmap xen-tb-dom0-image-efi-genericx86-64.wic.bmap xen-tb-dom0-image-efi-genericx86-64.wic.gz \block map format version 2.0540672 blocks of size 4096 (2.1 GiB), mapped 139322 blocks (544.2 MiB or 25.8%)copying image 'xen-tb-dom0-image-efi-genericx86-64.wic.gz' to block device '/dev/sdd'using bmap file 'xen-tb-dom0-image-efi-genericx86-64.wic.bmap'100% copiedsynchronizing '/dev/sdd'copying time: 1m 37.3s, copying speed 5.6 MiB/secYocto Project The Linux Foundation

Wic Plug-in InterfaceYocto Project The Linux Foundation

Wic Plug-in Interface Wic plug-in interface provides the mechanism tocustomize the image generation process --source variable in the Wic kickstart file specifies thethe source plugin which is used to generate thepartition image The source plugins are subclasses based on SourcePluginclass, which is defined in poky/scripts/lib/wic/pluginbase.py15Yocto Project The Linux Foundation

Wic Plug-in Interface Wic plug-in sources could be defined in the externallayers Custom plugins must be placed inscripts/lib/wic/plugins/source/ within external layer Each Wic plug-in has particular name variable thatcorresponds to the --source parameterclass BootimgGrubTbPlugin(SourcePlugin):"""Creates TrenchBoot boot partition for PC BIOS platforms"""name 'bootimg-grub-tb'16Yocto Project The Linux Foundation

The methods of the SourcePlugin classThe SourcePlugin class provides the following methods tothe source file: do configure partition()- method that creates customconfiguration files for a partition (e. g. custom grub.cfgfile) do stage preparation()- method allows stage the partitionfiles in customized way. Typically, this method is empty.17Yocto Project The Linux Foundation

The methods of the SourcePlugin class do prepare partition()- method does the contentpopulation for a partition, it prepares the final partitionto be incorporated into image do install disk()- method finalize the disk imagecreation, e. g. it writes the MBR (Master Boot Record) do post partition()- method allows to execute the postoperations after the partition is created, it could beused e. g. for security signing18Yocto Project The Linux Foundation

Wic Plug-in developmentYocto Project The Linux Foundation

Custom boot partition for the TrenchBoot TrenchBoot is a framework that allows individuals andprojects to build security engines to perform launchintegrity actions for their systems The meta-trenchboot layer creates ready to use Yoctobuilds, that provides the D-RTM for the UEFI and PCBIOS platforms bootimg-grub-tb plug-in creates the custom bootpartition for the TrechBoot purposes20Yocto Project The Linux Foundation

The BIOS selects a hard drive to boot from and loads theboot image The boot image is written to the first 512-byte sector ofthe partition. It contains logical block addressing (LBA)of the first sector of core image and its task is to loadthat sector into memory and transfer the control to coreimage21Yocto Project The Linux Foundation

The core image contains the loader and addresses of theblocks that allows loading core image to the memory.Once it is done the GRUB kernel takes over initialization. At first GRUB is trying to load the normal module. Itattempts to locate the normal.mod file that should beinstalled in the (hd0,msdos1)/boot/grub/i386-pc/ directory.22Yocto Project The Linux Foundation

Normal module loads another couple of modules. Oncethe normal is loaded properly, it runs the normalcommand that displays the GRUB menu with thegrub.cfg configuration file.23Yocto Project The Linux Foundation

bootimg-grub-tb – Wic plug-in developmentThe plug-in source: py24Yocto Project The Linux Foundation

Development Challenges grub-bios-setup allows to install grub boot image to thephysical device. When creating the bootable partition ina file, it’s not possible to guess the root partition. Toworkaround this problem, it’s necessary to create newparameter (-r) that would specify the root partitiongrub dir os.path.join(workdir, "hdd/boot/grub/i386-pc")cmd bios setup (f'grub-bios-setup -v --device-map {device map path}'f' -r "hd0,msdos1" -d {grub dir} {full path}')exec cmd(cmd bios setup, native sysroot)The patch source code: atch25Yocto Project The Linux Foundation

Development Tips To obtain Bitbake variables use get bitbake vardeploy dir get bitbake var("DEPLOY DIR IMAGE") The second way of passing variables to the plug-inis --sourceparams parameter; it is defined in the Wickickstarter filepart /boot --source bootimg-grub-tb –-sourceparams "initrd initrd.cpio" \--ondisk sda --label msdos --active --align 1024To obtain the parameter in the plugin use source params.getinitrd source params.get('initrd')26Yocto Project The Linux Foundation

Development TipsDuring the plug-in development you may need to use theparameters of SourcePlugin methods: cr workdir – work directory of the Wic, it containscreated artifacts hdddir – directory which is used to populate a partition kernel dir – kernel directory typically it’s equalto27DEPLOY DIR IMAGEYocto Project The Linux Foundation

Thanks for yourtime

9 Yocto Project The Linux Foundation Create your custom partition layout part command creates partition and takes the mount point as the input e.g. /boot --source parameter specifies the Wic plug-in --ondisk parameter force creating the partition on a particular disk --fstype sets the file system for the partition part /boot --source bootimg-grub-tb --ondisk sda --label .