# User customizations This section provides instructions to customize Qualcomm Linux, covering the following topics: - Add custom machine configurations - Modify distro configurations - Create image recipes - Customize the kernel ## Custom machine configurations To add a custom machine configuration and rebuild the workspace, do the following: 1. To add a machine, introduce a new machine configuration file at `layers/meta-qcom-hwe/conf/machine/`; for example, `layers/meta-qcom-hwe/conf/machine/test-board.conf`. 2. If the new machine is using the QCS6490 hardware SoC, in the newly created file, add the following content: #@TYPE: Machine #@NAME: TestBoard #@DESCRIPTION: Machine configuration for a development board, based on Qualcomm QCS6490 require conf/machine/include/qcom-qcs6490.inc Copy to clipboard 3. Source the setup-environment script: MACHINE=test-board DISTRO=qcom-wayland QCOM_SELECTED_BSP=custom source setup-environment Copy to clipboard Note If you have access to `meta-qcom-extras`, add it to `EXTRALAYERS ?=` `${WORKSPACE}/layers/meta-qcom-extras` in the `conf/bblayers.conf` file. 4. To build an image for the machine added, run the following command: bitbake qcom-multimedia-image Copy to clipboard ## Custom distro configurations The following subsections explain how to add a custom distro configuration and rebuild the workspace. ### Qualcomm defined distro configuration overview The reference distro defined for Qualcomm Linux is at `/layers/meta-qcom-distro/conf/distro/qcom-wayland.conf`. The DISTRO\_FEATURES variable can be inspected using the following command: bitbake -e | grep ^DISTRO_FEATURES= Copy to clipboard Output: DISTRO\_FEATURES=”acl alsa argp bluetooth debuginfod ext2 ipv4 ipv6 largefile pcmcia usbgadget usbhost wifi xattr nfs zeroconf pci 3g nfc vfat seccomp pam overlayfs acl xattr selinux ptest security virtualization tpm wayland vulkan opengl systemd pulseaudio gobject-introspection-data ldconfig” Note The DISTRO\_FEATURES shown in the output are described in [Distro features](https://docs.yoctoproject.org/4.0.22/singleindex.html#distro-features). ### Add distro configuration To add a distro configuration file, do the following: 1. Add a `test-distro.conf` file in `/layers/meta-qcom-distro/conf/distro`. 2. Use the same content as `qcom-wayland.conf`, that is, `cp qcom-wayland.conf test-distro.conf`. 3. Set `DISTRO_NAME = "Test Reference Distro with Wayland"` in the `test-distro.conf` file. 4. Set `DISTROOVERRIDES = "test-dist"` in the `test-distro.conf` file. 5. Source the environment and export variables as follows: MACHINE="qcs6490-rb3gen2-core-kit" DISTRO="test-distro" source setup-environment Copy to clipboard After sourcing the environment is completed, the current workspace directory is changed to `/build-test-distro`. To verify if the `test-distro` defined has taken effect, open the `conf/auto.conf` file to confirm the following: # This configuration file is dynamically generated every time # set_bb_env.sh is sourced to set up a workspace. DO NOT EDIT. #-------------------------------------------------------------- DISTRO ?= "test-distro" Copy to clipboard To verify the output, run the following command: bitbake -e | grep ^DISTROOVERRIDES= DISTROOVERRIDES="test-dist" Copy to clipboard Note If you have access to `meta-qcom-extras`, add it to `EXTRALAYERS ?=` `${WORKSPACE}/layers/meta-qcom-extras` in the `conf/bblayers.conf` file. To rebuild the image, run the following command: bitbake qcom-multimedia-image Copy to clipboard ### Enable or disable DISTRO\_FEATURES DISTRO\_FEATURES provide a mechanism to verify, which packages must be included in the generated images. You can select the features you want to enable through the DISTRO\_FEATURES variable, which is set or appended to in a `test-distro.conf` configuration file of a distribution. For more information, see [Distro Features](https://docs.yoctoproject.org/4.0.22/singleindex.html#distro-features). Note Select a feature defined by the community. 1. Open the `test-distro.conf` file and add the following line: DISTRO_FEATURES:append = " cramfs" Copy to clipboard 2. Test if the change has taken effect, and then rebuild: bitbake -e | grep ^DISTRO_FEATURES= Copy to clipboard The output is as follows: DISTRO_FEATURES="acl alsa argp bluetooth debuginfod ext2 ipv4 ipv6 largefile pcmcia usbgadget usbhost wifi xattr nfs zeroconf pci 3g nfc vfat seccomp pam overlayfs acl xattr selinux ptest security virtualization tpm usrmerge sota wayland vulkan opengl cramfs systemd pulseaudio gobject-introspection-data ldconfig" Copy to clipboard 3. To rebuild, run the following command: bitbake qcom-multimedia-image Copy to clipboard ## Image recipes **Add image recipes** 1. To add an image recipe, change the directory to `/layers/meta-qcom-distro/recipes-products/images`. 2. Create a file, for example `test-image.bb`, and add the following content: SUMMARY = "Test image" LICENSE = "BSD-3-Clause-Clear" IMAGE_FEATURES += "splash \ tools-debug \ debug-tweaks \ enable-adbd \ " inherit core-image features_check extrausers image-adbd image-qcom-deploy image-efi REQUIRED_DISTRO_FEATURES = "pam systemd" CORE_IMAGE_BASE_INSTALL += " \ kernel-modules \ packagegroup-filesystem-utils \ " CORE_IMAGE_EXTRA_INSTALL += "overlayfs-qcom-paths" Copy to clipboard 3. Source the environment: MACHINE=qcs6490-rb3gen2-core-kit DISTRO=qcom-wayland source setup-environment Copy to clipboard 4. The following step is optional and applies only if you have cloned `meta-qcom-extras` in the workspace. Open the `conf/bblayer.conf` file and verify the change in the content: | Before change | After change | | --- | --- | | # Add your overlay location to EXTRALAYERS
# Make sure to have a conf/layers.conf in there
EXTRALAYERS ?= ""
Copy to clipboard | # Add your overlay location to EXTRALAYERS
# Make sure to have a conf/layers.conf in there
EXTRALAYERS ?= "${WORKSPACE}/layers/meta-qcom-extras"
Copy to clipboard | 5. Build using the BitBake command: bitbake test-image Copy to clipboard The images are generated as follows: build-qcom-wayland> $ ls tmp-glibc/deploy/images/qcs6490-rb3gen2-core-kit/test-image aop.mbn gpt_backup0.bin gpt_backup5.bin gpt_main4.bin kernel-modules.tgz patch2.xml prog_firehose_lite.elf rawprogram2.xml system.img xbl_config.elf cpucp.elf gpt_backup1.bin gpt_main0.bin gpt_main5.bin logfs_ufs_8mb.bin patch3.xml qdl rawprogram3.xml tz.mbn xbl.elf devcfg.mbn gpt_backup2.bin gpt_main1.bin hypvm.mbn multi_image.mbn patch4.xml qupv3fw.elf rawprogram4.xml uefi.elf XblRamdump.elf dtb.bin gpt_backup3.bin gpt_main2.bin Image patch0.xml patch5.xml rawprogram0.xml rawprogram5.xml uefi_sec.mbn zeros_5sectors.bin efi.bin gpt_backup4.bin gpt_main3.bin imagefv.elf patch1.xml prog_firehose_ddr.elf rawprogram1.xml shrm.elf vmlinux Copy to clipboard ## Customize features This section provides examples of how to customize images: **Remove display packages from image** `layers/meta-qcom-distro/recipes-products/packagegroups/packagegroup-qcom-multimedia.bb` | Before change | After change | | --- | --- | | RDEPENDS:${PN}:append:qcom-custom-bsp = "\
camera-server \
packagegroup-qcom-audio \
packagegroup-qcom-bluetooth \
packagegroup-qcom-camera \
packagegroup-qcom-display \
packagegroup-qcom-fastcv \
packagegroup-qcom-graphics \
packagegroup-qcom-iot-base-utils \
packagegroup-qcom-location \
packagegroup-qcom-video \
packagegroup-qcom-voiceai \
"
Copy to clipboard | RDEPENDS:${PN}:append:qcom-custom-bsp = "\
camera-server \
packagegroup-qcom-audio \
packagegroup-qcom-bluetooth \
packagegroup-qcom-camera \
packagegroup-qcom-fastcv \
packagegroup-qcom-graphics \
packagegroup-qcom-iot-base-utils \
packagegroup-qcom-location \
packagegroup-qcom-video \
packagegroup-qcom-voiceai \
"
Copy to clipboard | After executing the `bitbake qcom-multimedia-image` command, the display-related packages are removed from the build. The content from the `packagegroup-qcom-display.bb` package group is removed from the image. **Remove Bluetooth**^®^ **from image** `layers/meta-qcom-distro/recipes-products/packagegroups/packagegroup-qcom-multimedia.bb` | Before change | After change | | --- | --- | | RDEPENDS:${PN}:append:qcom-custom-bsp = "\
camera-server \
packagegroup-qcom-audio \
packagegroup-qcom-bluetooth \
packagegroup-qcom-camera \
packagegroup-qcom-display \
packagegroup-qcom-fastcv \
packagegroup-qcom-graphics \
packagegroup-qcom-iot-base-utils \
packagegroup-qcom-location \
packagegroup-qcom-video \
packagegroup-qcom-voiceai \
"
Copy to clipboard | RDEPENDS:${PN}:append:qcom-custom-bsp = "\
camera-server \
packagegroup-qcom-audio \
packagegroup-qcom-camera \
packagegroup-qcom-fastcv \
packagegroup-qcom-graphics \
packagegroup-qcom-iot-base-utils \
packagegroup-qcom-location \
packagegroup-qcom-video \
packagegroup-qcom-voiceai \
"
Copy to clipboard | After executing the `bitbake qcom-multimedia-image` command, the bluetooth-related packages are removed from the build. The content from the `packagegroup-qcom-bluetooth.bb` package group is removed from the image recipe. ## Modify partition layout This section explains how to add, delete, modify, or rename partitions. A configuration file defining partitions for the UFS device are present at `layers/meta-qcom-hwe/recipes-devtools/partition-utils/qcom-partition-confs/qcm6490-partitions.conf`. To add a partition, add a row entry to this file. To remove a partition, delete the corresponding entry to remove the target partition from the set of images to be flashed. Many partitions are crucial for functionality. To understand the details of how this file plays a role in generating the partition table, see Partitioning. **Example 1 – Adding a partition** To add a partition with name `test` in LUN0, add the following line to the `qcm6490-partitions.conf` under LUN0 section: --partition --lun=0 --name=test --size=4096KB --type-guid=1B81F7E6-F50D-419B-A739-2AEFF8DA3335 Copy to clipboard This adds a 4 MB partition test to LUN0 and a GUID determined by you. This partition is not flashed with any image, but it is available as a raw partition after the device boots up. As this partition is added to LUN0, it shows up at either of the following options: - `/dev/sda` - `/dev/disk/by-partlabel/test` **Example 2 – Add an example partition with a binary to be flashed tothe newly created partition** To add a partition with name `test1` in LUN0, add the following line to `qcm6490-partitions.conf` under LUN0 section: --partition --lun=0 --name=test --size=4096KB --type-guid=1B81F7E6-F50D-419B-A739-2AEFF8DA3335 --filename=test1.bin Copy to clipboard Deploy the new `test1.bin` binary in `build-qcom-wayland/tmp-glibc/deploy/images/qcs6490-rb3gen2-core-kit/$(image_name)`. ## Use of devtool The following examples show the devtool usage for Qualcomm software components: - **Kernel** See [Yocto support](https://docs.qualcomm.com/bundle/publicresource/topics/80-70017-3/yocto-kernel-support.html). - **QDL tool** Use the devtool to modify the QDL source in the workspace created. devtool modify qdl INFO: Source tree extracted to /build-qcom-wayland/workspace/sources/qdl INFO: Using source tree as build directory since that would be the default for this recipe INFO: Recipe qdl now set up to build from /build-qcom-wayland/workspace/sources/qdl Copy to clipboard 1. The following tree is checked-out locally: tree -L 2 build-qcom-wayland/workspace/ build-qcom-wayland/workspace/ ├── appends │ └── qdl_git.bbappend ├── conf │ └── layer.conf ├── README └── sources └── qdl Copy to clipboard 2. Inspect the checked-out QDL source-tree: ls workspace/sources/qdl/ firehose.c LICENSE Makefile patch.c patch.h program.c program.h qdl.c qdl.h README sahara.c ufs.c ufs.h util.c Copy to clipboard 3. Change the source tree under `workspace/sources/qdl/` and build your changes: devtool build qdl devtool build-image qcom-multimedia-image Copy to clipboard 4. Images are generated in the path `build-qcom-wayland/tmp-glibc/deploy/images/qcs6490-rb3gen2-core-kit/qcom-multimedia-image`. - **Weston** devtool modify weston INFO: Adding local source files to srctree... INFO: Source tree extracted to /build-qcom-wayland/workspace/sources/pulseaudio INFO: Recipe weston now set up to build from /build-qcom-wayland/workspace/sources/weston Copy to clipboard 1. The following tree is checked-out locally: tree -L 2 build-qcom-wayland/workspace/ build-qcom-wayland/workspace/ ├── appends │ └── weston_10.0.2.bbappend ├── conf │ └── layer.conf ├── README └── sources └── weston Copy to clipboard 2. Inspect the checked-out Weston source-tree: ls workspace/sources/weston/ clients COPYING desktop-shell include libweston meson.build oe-local-files pipewire releasing.rst tests weston.ini.in compositor data doc ivi-shell libweston-desktop meson_options.txt oe-logs protocol remoting tools xwayland CONTRIBUTING.rst DCO-1.1.txt fullscreen-shell kiosk-shell man notes.txt oe-workdir README.rst shared wcap Copy to clipboard 3. Change the source tree under `workspace/sources/weston/` and build your changes: devtool build weston devtool build-image qcom-multimedia-image Copy to clipboard 4. The images are generated in the path `build-qcom-wayland/tmp-glibc/deploy/images/qcs6490-rb3gen2-core-kit/qcom-multimedia-image`. ## Customize kernel To customize the kernel, see [Qualcomm Linux Kernel Guide](https://docs.qualcomm.com/bundle/publicresource/topics/80-70017-3/). ## Add third-party layers to workspace To add a third-party layer to the workspace, perform the following steps: 1. Clone the layer under `/layers/`. 2. Add the layer in the `layers/meta-qcom-distro/conf/bblayers.conf` file as part of the `BBLAYERS` variable, as follows: # These layers hold machine specific content, aka Board Support Packages BSPLAYERS ?= " \ ${WORKSPACE}/layers/meta-testlayer \ ${WORKSPACE}/layers/meta-qcom-hwe \ ${WORKSPACE}/layers/meta-qcom \ " Copy to clipboard Cloning and adding the layer allows the BitBake to parse the layer. ## Create a build for debugging To generate a debug build to export `DEBUG_BUILD=1` before issuing Yocto BitBake build instructions, run the following command: DEBUG_BUILD=1 bitbake qcom-multimedia-image Copy to clipboard To understand which kernel defconfig and config fragments are used when `DEBUG_BUILD` is set to **1**, see Kernel configuration, under [Kernel recipes](https://docs.qualcomm.com/doc/80-70017-27/topic/platform_software_features.html#kernel-recipes-section). ## Create a build for most optimized boot KPI To achieve the best bootup time for the device, use the `PERFORMANCE_BUILD` variable. When the `PERFORMANCE_BUILD` variable is set to **1**, it modifies `KERNEL_CMDLINE_EXTRA` to drop the **console** option from the command line. The `PERFORMANCE_BUILD` variable takes effect when `DEBUG_BUILD` is set to **0**. To understand how the `PERFORMANCE_BUILD` variable affects the boot up time, see the following table: | | PERFORMANCE\_BUILD=“0” | PERFORMANCE\_BUILD=“1” | | --- | --- | --- | | `DEBUG_BUILD=0` | Console on UART is enabled |

  • The console on UART is disabled


  • Best boot up time


| | `DEBUG_BUILD=1` | Console on UART is enabled |

  • The PERFORMANCE_BUILD="1" when DEBUG_BUILD is set to "1".


| Last Published: Dec 30, 2024 [Previous Topic Qualcomm Linux features](https://docs.qualcomm.com/bundle/publicresource/80-70017-27/topics/platform_software_features.md) [Next Topic Debug](https://docs.qualcomm.com/bundle/publicresource/80-70017-27/topics/debug.md)