mkosi is a fancy wrapper to facilitate creating customized OS disk images. This repository contains configuration files and documentation helpful for utilizing mkosi to create disk images to assist in development and testing of platform-software on Qualcomm-based development boards (with UEFI boot).
The repository basic contains configuration for Arch Linux Arm, Debian, Fedora, and Ubuntu.
A recent version of mkosi is required, install this by issuing:
pipx install -f git+https://github.com/systemd/mkosi.git
Ensure your host OS is configured per the details in the frequently asked questions below.
Invoke mkosi with the build verb in order to build an image.
mkosi -d <distro> [--devicetree <dtb>] [--profile <profile>] [-f] build
The -d argument can be used to select the distribution you want to build. The provided configuration supports arch, debian, fedora, ubuntu.
Many Qualcomm boards does not come with upstream-compatible DeviceTree blobs loaded by UEFI, the --devicetree property can be provided, the DeviceTree blob will be expected to be installed by selected packages for the distribution.
Some boards require custom settings, for this --profile can be used to select a relevant profile. See below section about mkosi.profiles.
The -f option tells mkosi to overwrite a previously built disk image.
mkosi will produce an output image names image.raw, containing the full disk image containing EFI system partition and root file system.
Note: many targets lacks runtime firmware in the linux-firmware project, see note below on where in mkosi.extra to provide this.
mkosi -d debian --devicetree qcom/qcs6490-rb3gen2.dtb --profile qcs6490-rb3gen2 -f build
-f option will overwrite any previously baked image, instead of failing
The resulting image will be called image.raw, this can be flashed onto most boards with existing non-Linux firmware (boot etc), using e.g. QDL and the included rawprogram-ufs.xml and rawprogram-nvme.xml.
For UFS-absed devices use:
qdl prog_firehose_ddr.elf rawprogram-ufs.xml
For NVMe-based devices:
qdl prog_firehose_ddr.elf rawprogram-nvme.xml
On some targets xbl_s_devprg_ns.melf should be used instead of prog_firehose_ddr.elf, neither is provided through this project
If your device has multiple storage devices, such as UFS and NVME, use --storage nvme or --storage ufs to direct QDL to the appropriate destination.
Once flashed, power on the board and you should boot into the newly installed disk image. Some distributions will ask for timezone settings etc during boot, answer as desired.
Depending on the hardware support for your board, you may either use an attached display and keyboard for this, or access the board over UART.
Per the configuration log into the system using:
- user: root
- password: 14
Not all boards have firmware available in linux-firmware and/or the related packages of your Linux distribution. These files can be added as necessary under mkosi.extra/usr/lib/firmware and will then be baked into the image.
Base configuration, common for all boards and distributions. In particular it defines that the we're building a disk image, of the arm64 architecture, that it's bootable using systemd-boot, with a common kernel command line.
Read more about these options in the official mkosi man page
Contains extensions to the base mkosi.conf, matched on the selected distribution. Among a few other things, this is where the default list of packages to be installed for each distribution is defined.
Provides an overlay of a few configuration files to improve the out-of-the-box experience of the built image.
| file | Comments |
|---|---|
| 50-root.conf | Automatically extend the root partition (but not the file system) to cover the remainder of the disk |
| 10-network-manager.preset | Make the NetworkManager systemd service launch automatically on boot (if present) |
A placeholder directory mkosi.extra/usr/lib/firmware exists as a convenience for users to place any runtime firmware which is not provided through linux-firmware.
Empty directory in which you can add any custom built packages for the distribution your building.
Some boards requires some further customizations, these are captured in as mkosi profiles in the mkosi.profiles directory. One concrete example is the need to specify the 4k sector size for UFS-based devices.
Currently provided profiles are:
| profile | Comments |
|---|---|
| ufs | General purpose profile to override the SectorSize config, as needed on UFS-based devices |
| qcs6490-rb3gen2 | Override the SectorSize config and increase deferred_probe_timeout on kernel command line |
Not all boards require a profile to be selected, e.g. SC8280XP and X1 Elite devices with NVMe storage works without this.
The upstream Linux kernel community aims to maintain defconfig to the point where necessary hardware drivers for running the kernel on supported Qualcomm hardware are enabled by default.
The Arm64 build system does however by default produce a compressed kernel image (zImage), which a standard UEFI system will not decompress. It's therefore necessary to manually enable the CONFIG_EFI_ZBOOT option.
Kernel packages can then be built for the various distributions using below commands and copied into mkosi.packages. Note that the Packages list in relevant mkosi.conf.d config might need to be updated for the new package to be selected.
LLVM=1 ARCH=arm64 make -j99 pacman-pkg
LLVM=1 ARCH=arm64 make -j99 O=debian bindeb-pkg
LLVM=1 ARCH=arm64 make -j99 binrpm-pkg
In the event that your board's UEFI implementation does not provide an upstream compliant Devicetree blob, you need to ensure the board's dtb file is loaded during boot - e.g. by systemd-boot.
When baking the image, the --devicetree option provides the means for selecting a DeviceTree blob from the installed packages. When installing the generated package into an existing installation, make sure that the generated systemd-boot loader entry contains the correct devicetree entry, or that you build an UKI with the relevant DeviceTree blob included.
No. mkosi generates disk images of standard Linux distributions, that expects to be loaded by an UEFI bootloader.
Install the dependencies on your host system, for Ubuntu 22.04 this is:
sudo apt install binfmt-support dnf mkosi uidmap pipx rpm systemd-repart qemu-user-static qemu-system-arm
Make sure pipx-installed binaries are in your $PATH:
pipx ensurepath
Restart your terminal/shell.
Set up sub-UIDs/GIDs for containerization
echo "$USER:200000:65536" | sudo tee -a /etc/subuid
echo "$USER:200000:65536" | sudo tee -a /etc/subgid
Enable the Aarch64 emulation using QEMU.
sudo update-binfmts --enable qemu-aarch64
If you system is configured to a umask other than 0022, subsequent runs of mkosi will always fail with various permission issues. So make you set the umask in the terminal you're about to run mkosi:
umask 0022
mkosi depends on a variety of fairly recent features in systemd. To faciliate this mkosi includes a feature which first builds an image with tools, and then builds the image in that container.
Enable this by setting ToolsTree=default in the Build section of the config.
mkosi uses namespaces to set up Linux distribution to be built into the image, this does not play well with network mounted, such as NFS, home directories. Instead clone the mkosi-qcom project into some local storage; such as /mnt/local/mkosi-qcom (subject to your system configuration).
At runtime mkosi will use the user's cache directory, create a directory for this on local storage and update the XDG_CACHE_HOME to redirect these accesses like:
export XDG_CACHE_HOME=/mnt/local/tmp
With the goal of providing a convenient development environment for upstream work, please do contribute to documentation and configuration by opening a Pull Request. Issues can be used to track issues with this content, or specifics that needs to be corrected in the various Linux distributions.
See CONTRIBUTING for more information.
Licensed under BSD 3-Clause Clear License.