{"id":34610132,"url":"https://github.com/qualcomm/mkosi-qcom","last_synced_at":"2025-12-24T14:07:09.630Z","repository":{"id":314990518,"uuid":"943325748","full_name":"qualcomm/mkosi-qcom","owner":"qualcomm","description":"mkosi.conf for Qualcomm-based development boards","archived":false,"fork":false,"pushed_at":"2025-09-16T03:37:38.000Z","size":21,"stargazers_count":10,"open_issues_count":0,"forks_count":4,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-09-16T04:28:10.613Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause-clear","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/qualcomm.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.txt","code_of_conduct":"CODE-OF-CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-03-05T14:27:04.000Z","updated_at":"2025-09-16T03:37:42.000Z","dependencies_parsed_at":"2025-09-16T04:28:13.465Z","dependency_job_id":"2d10eaca-1fe1-48de-8a6f-18965128c2db","html_url":"https://github.com/qualcomm/mkosi-qcom","commit_stats":null,"previous_names":["qualcomm/mkosi-qcom"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/qualcomm/mkosi-qcom","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qualcomm%2Fmkosi-qcom","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qualcomm%2Fmkosi-qcom/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qualcomm%2Fmkosi-qcom/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qualcomm%2Fmkosi-qcom/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/qualcomm","download_url":"https://codeload.github.com/qualcomm/mkosi-qcom/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qualcomm%2Fmkosi-qcom/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28003724,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-12-24T02:00:07.193Z","response_time":83,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-12-24T14:05:54.547Z","updated_at":"2025-12-24T14:07:09.623Z","avatar_url":"https://github.com/qualcomm.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Introduction\n\n[mkosi](https://mkosi.systemd.io/) is a fancy wrapper to facilitate creating\ncustomized OS disk images. This repository contains configuration files and\ndocumentation helpful for utilizing *mkosi* to create disk images to assist in\ndevelopment and testing of platform-software on Qualcomm-based development\nboards (with UEFI boot).\n\nThe repository basic contains configuration for **Arch Linux Arm**, **Debian**,\n**Fedora**, and **Ubuntu**.\n\n# Installing mkosi\n\nA recent version of *mkosi* is required, install this by issuing:\n\n```\npipx install -f git+https://github.com/systemd/mkosi.git\n```\n\nEnsure your host OS is configured per the details in the [Frequently asked\nquestions](#Frequently-asked-questions) below.\n\n# Baking an image\n\nInvoke *mkosi* with the **build** verb in order to build an image.\n\n```\nmkosi -d \u003cdistro\u003e [--devicetrees \u003cdtb\u003e] [--profile \u003cprofile\u003e] [-f] build\n```\n\nThe **-d** argument can be used to select the distribution you want to build.\nThe provided configuration supports **arch**, **debian**, **fedora**, **ubuntu**.\n\nMany Qualcomm boards does not come with upstream-compatible DeviceTree blobs\nloaded by UEFI, the **--devicetrees** property can be provided, the DeviceTree\nblob will be expected to be installed by selected packages for the\ndistribution.\n\nSome boards require custom settings, for this **--profile** can be used to\nselect a relevant profile. See below section about *mkosi.profiles*.\n\nThe **-f** option tells *mkosi* to overwrite a previously built disk image.\n\n*mkosi* will produce an output image names **image.raw**, containing the full\ndisk image containing EFI system partition and root file system.\n\n**Note:** many targets lacks runtime firmware in the *[linux-firmware](https://web.git.kernel.org/pub/scm/linux/kernel/git/firmware/linux-firmware.git/)*\nproject, see note below on where in *mkosi.extra* to provide this.\n\n## Example\n```\nmkosi -d debian --devicetrees qcom/qcs6490-rb3gen2.dtb --profile ufs -f build\n```\n*-f option will overwrite any previously baked image, instead of failing*\n\n## Flashing the baked image\n\nThe resulting image will be called *image.raw*, this can be flashed onto most\nboards with existing non-Linux firmware (boot etc), using e.g. [QDL](https://github.com/linux-msm/qdl)\nand the included **rawprogram-ufs.xml** and **rawprogram-nvme.xml**.\n\nFor UFS-absed devices use:\n```\nqdl prog_firehose_ddr.elf rawprogram-ufs.xml\n```\n\nFor NVMe-based devices:\n\n```\nqdl prog_firehose_ddr.elf rawprogram-nvme.xml\n```\n\n*On some targets xbl_s_devprg_ns.melf should be used instead of\nprog_firehose_ddr.elf, neither is provided through this project*\n\nIf your device has multiple storage devices, such as UFS and NVME, use\n*--storage nvme* or *--storage ufs* to direct QDL to the appropriate\ndestination.\n\n## Booting the image\n\nOnce flashed, power on the board and you should boot into the newly installed\ndisk image. Some distributions will ask for timezone settings etc during boot,\nanswer as desired.\n\nDepending on the hardware support for your board, you may either use an\nattached display and keyboard for this, or access the board over UART.\n\n### Logging in\n\nPer the configuration log into the system using:\n\n- user: **root**\n- password: **14**\n\n## linux-firmware\n\nNot all boards have firmware available in *[linux-firmware](https://web.git.kernel.org/pub/scm/linux/kernel/git/firmware/linux-firmware.git/)*\nand/or the related packages of your Linux distribution. These files can be\nadded as necessary under **mkosi.extra/usr/lib/firmware** and will then be\nbaked into the image.\n\n# Structure of the project\n\n## mkosi.conf\n\nBase configuration, common for all boards and distributions. In particular it\ndefines that the we're building a disk image, of the *arm64* architecture, that\nit's *bootable* using *systemd-boot*, with a common kernel command line.\n\nRead more about these options in the official [mkosi man page](https://github.com/systemd/mkosi/blob/main/mkosi/resources/man/mkosi.1.md)\n\n## mkosi.conf.d\n\nContains extensions to the base *mkosi.conf*, matched on the selected\ndistribution. Among a few other things, this is where the default list of\npackages to be installed for each distribution is defined.\n\n## mkosi.extra\n\nProvides an overlay of a few configuration files to improve the out-of-the-box\nexperience of the built image.\n\n| file | Comments |\n| --- | --- |\n| 50-root.conf | Automatically extend the root partition (but not the file system) to cover the remainder of the disk |\n| 10-network-manager.preset | Make the NetworkManager systemd service launch automatically on boot (if present) |\n\n### Runtime firmware\n\nA placeholder directory **mkosi.extra/usr/lib/firmware** exists as a\nconvenience for users to place any runtime firmware which is not provided\nthrough *[linux-firmware](https://web.git.kernel.org/pub/scm/linux/kernel/git/firmware/linux-firmware.git/)*.\n\n## mkosi.packages\n\nEmpty directory in which you can add any custom built packages for the\ndistribution your building.\n\n## mkosi.profiles\n\nSome boards requires some further customizations, these are captured in as\n*mkosi profiles* in the *mkosi.profiles* directory. One concrete example is the\nneed to specify the 4k sector size for UFS-based devices.\n\nCurrently provided profiles are:\n| profile | Comments |\n| --- | --- |\n| ufs | General purpose profile to override the SectorSize config, as needed on UFS-based devices |\n\nNot all boards require a profile to be selected, e.g. SC8280XP and X1 Elite\ndevices with NVMe storage works without this.\n\n# Build your own kernel\n\nThe upstream Linux kernel community aims to maintain *defconfig* to the point\nwhere necessary hardware drivers for running the kernel on supported Qualcomm\nhardware are enabled by default.\n\nKernel packages can then be built for the various distributions using below\ncommands and copied into **mkosi.packages**. Note that the *Packages* list in\nrelevant *mkosi.conf.d* config might need to be updated for the new package to\nbe selected.\n\n## Arch Linux\n```\nLLVM=1 ARCH=arm64 make -j99 pacman-pkg\n```\n\nCopy the resulting **linux-upstream** files into *mkosi.packages* and make\nsure that **linux-upstream** is in the *Packages=* directive in\n*mkosi.conf.d/arch.conf*.\n\n## Debian or Ubuntu\n```\nLLVM=1 ARCH=arm64 make -j99 O=debian bindeb-pkg\n```\n\nCopy the resulting **\\*.deb** files into *mkosi.packages*. Use **dpkg-deb\n--into mkosi.packages ...** to acquire the **Package:** specifier of the kernel\npacket, then plug this into the *Packages=* directive in\n*mkosi.conf.d/debian.conf* or *mkosi.conf.d/ubuntu.conf*.\n\n## Fedora\n```\nLLVM=1 ARCH=arm64 make -j99 binrpm-pkg\n```\n\nCopy **rpmbuild/RPMS/*.rpm** files into *mkosi.packages*.\n\n### Note on compression and UEFI\n\nThe provided ***mkosi.conf*** does enable the packaging of the kernel and\nrelated parts into a UKI. If you disable this, you need to make sure that the\nkernel is uncompressed, or built with the **CONFIG_EFI_ZBOOT** option, as UEFI\ndoes not decompress the kernel.\n\n## Managing DeviceTree for your kernel\n\nIn the event that your board's UEFI implementation does not provide an upstream\ncompliant Devicetree blob, you need to ensure the board's dtb file is loaded\nduring boot - e.g. by systemd-boot.\n\nWhen baking the image, the *--devicetrees* option provides the means for\nselecting a DeviceTree blob from the installed packages. When installing the\ngenerated package into an existing installation, make sure that the generated\n*systemd-boot* loader entry contains the correct **devicetree** entry, or that\nyou build an *UKI* with the relevant DeviceTree blob included.\n\n# Frequently asked questions\n\n## Does this work on a device with Android Boot Loader (abl)\n\nNo. *mkosi* generates disk images of standard Linux distributions, that expects\nto be loaded by an UEFI bootloader.\n\n## mkosi system dependencies\n\nInstall the dependencies on your host system, for Ubuntu 22.04 this is:\n\n```\nsudo apt install binfmt-support dnf mkosi uidmap pipx rpm systemd-repart qemu-user-static qemu-system-arm\n```\n\nMake sure pipx-installed binaries are in your $PATH:\n\n```\npipx ensurepath\n```\n\nRestart your terminal/shell.\n\nSet up sub-UIDs/GIDs for containerization\n\n```\necho \"$USER:200000:65536\" | sudo tee -a /etc/subuid\necho \"$USER:200000:65536\" | sudo tee -a /etc/subgid\n```\n\nEnable the Aarch64 emulation using QEMU.\n\n```\nsudo update-binfmts --enable qemu-aarch64\n```\n\n### umask\n\nIf you system is configured to a umask other than 0022, subsequent runs of\n*mkosi* will always fail with various permission issues. So make you set the\numask in the terminal you're about to run *mkosi*:\n\n```\numask 0022\n```\n\n## systemd-* is too old\n\n*mkosi* depends on a variety of fairly recent features in *systemd*. To\nfaciliate this *mkosi* includes a feature which first builds an image with\ntools, and then builds the image in that container.\n\nEnable this by setting **ToolsTree=default** in the *Build* section of the\nconfig.\n\n## $HOME is a network mount\n\n*mkosi* uses namespaces to set up Linux distribution to be built into the\nimage, this does not play well with network mounted, such as NFS, home\ndirectories. Instead clone the *mkosi-qcom* project into some local storage;\nsuch as */mnt/local/mkosi-qcom* (subject to your system configuration).\n\nAt runtime *mkosi* will use the user's cache directory, create a directory for\nthis on local storage and update the *XDG_CACHE_HOME* to redirect these\naccesses like:\n\n```\nexport XDG_CACHE_HOME=/mnt/local/tmp\n```\n\n# Contribute\n\nWith the goal of providing a convenient development environment for upstream\nwork, please do contribute to documentation and configuration by opening a Pull\nRequest. Issues can be used to track issues with this content, or specifics\nthat needs to be corrected in the various Linux distributions.\n\nSee [CONTRIBUTING](CONTRIBUTING.md) for more information.\n\n## License\n\nLicensed under [BSD 3-Clause Clear License](LICENSE.txt).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fqualcomm%2Fmkosi-qcom","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fqualcomm%2Fmkosi-qcom","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fqualcomm%2Fmkosi-qcom/lists"}