# User customizations Source: [https://docs.qualcomm.com/doc/80-70014-27/topic/user_customizations.html](https://docs.qualcomm.com/doc/80-70014-27/topic/user_customizations.html) ## Custom machine configurations Source: [https://docs.qualcomm.com/doc/80-70014-27/topic/user_customizations.html](https://docs.qualcomm.com/doc/80-70014-27/topic/user_customizations.html) ### Before you begin ### About this task Following are the steps that a user must follow to add a custom machine configuration and rebuild the workspace: ### Procedure 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/testBoard.conf`. 2. In the newly created file, add the following content: #@TYPE: Machine #@NAME: TestBoard #@DESCRIPTION: Machine configuration for a development board, based on Qualcomm QCM6490 MACHINEOVERRIDES =. "qcm6490:" require qcm6490.confCopy to clipboard 3. Source the setup-environment script: MACHINE="testBoard" DISTRO="qcom-wayland" source setup-environment {WORKSPACE}/layers/meta-qcom-extras in file conf/bblayers.conf.Copy to clipboard Note: If you have access to `meta-qcom-extras`, add it to `EXTRALAYERS ?= ``${WORKSPACE}/layers/meta-qcom-extras` in file `conf/bblayers.conf`. 4. Build an image for the machine added: bitbake qcom-multimedia-imageCopy to clipboard ## Custom distro configurations Source: [https://docs.qualcomm.com/doc/80-70014-27/topic/user_customizations.html](https://docs.qualcomm.com/doc/80-70014-27/topic/user_customizations.html) The following steps are used to add a custom distro configuration and rebuild the workspace. ### Introduction to Qualcomm defined distro configuration The reference distro defined by the user is at the path `/layers/meta-qcom-distro/conf/distro/qcom-wayland.conf`. The DISTRO\_FEATURES variable, which is enabled, can be inspected using the following command: bitbake -e | grep ^DISTRO_FEATURES= 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 wayland vulkan opengl systemd pulseaudio gobject-introspection-data ldconfig" Copy to clipboard The distro enables the following DISTRO\_FEATURES: - Wayland - Vulkan - OpenGL - pam - overlayfs - acl - xattr - SELinux - ptest - security - virtualization Note: All are standard DISTRO\_FEATURE settings and for more information, see [https://docs.yoctoproject.org/4.0.18/singleindex.html#distro-features](https://docs.yoctoproject.org/4.0.18/singleindex.html#distro-features) ### Adding new distro configuration To add a distro configuration file, follow the steps: 1. Add a file `test-distro.conf` in the path `/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 file `test-distro.conf` 4. Set `DISTROOVERRIDES = test-dist` in file `test-distro.conf` After step 4 is completed, source the environment and export variables as follows: MACHINE="qcm6490" DISTRO="test-distro" source setup-environment Copy to clipboard After the source completes, the workspace current directory is changed to `/build-test-distro`. To check if `test-distro` defined has taken effect, open the file `conf/auto.conf` (and not the variable DISTRO) 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 Run the following command and check the output: 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 file `conf/bblayers.conf` To rebuild the image, run the command: bitbake qcom-multimedia-imageCopy to clipboard ### Enable or disable DISTRO\_FEATURES Following are the steps to enable or disable DISTRO\_FEATURES that the users may want to customize. Features provide a mechanism for working out, which packages must be included in the generated images. The users can select the features they want to support through the DISTRO\_FEATURES variable, which is set or appended to in a distribution’s configuration file `test-distro.conf`. Select a feature defined by the community. For more information, see [https://docs.yoctoproject.org/4.0.18/singleindex.html#distro-features](https://docs.yoctoproject.org/4.0.16/singleindex.html#distro-features). 1. Open the file and add the following line: DISTRO_FEATURES:append = " cramfs"Copy to clipboard 2. Test if the change has taken effect, and 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 wayland vulkan opengl cramfs systemd pulseaudio gobject-introspection-data ldconfig"Copy to clipboard 3. Rebuild using the following command: bitbake qcom-multimedia-imageCopy to clipboard ## Image recipes Source: [https://docs.qualcomm.com/doc/80-70014-27/topic/user_customizations.html](https://docs.qualcomm.com/doc/80-70014-27/topic/user_customizations.html) ### About this task **Adding new image recipes** ### Procedure 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=qcm6490 DISTRO=qcom-wayland source setup-environment export FWZIP_PATH="/path/to/cloned/qclinux.1.0/FWZIP/" export CUST_ID="213195"Copy to clipboard 4. The following step is optional and applies only if you have cloned `meta-qcom-extras` in the workspace. Open file `conf/bblayer.conf` | **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-imageCopy to clipboard ### Results The images are generated as follows: build-qcom-wayland> $ ls tmp-glibc/deploy/images/qcm6490/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 vmlinuxCopy to clipboard ## Customize features Source: [https://docs.qualcomm.com/doc/80-70014-27/topic/user_customizations.html](https://docs.qualcomm.com/doc/80-70014-27/topic/user_customizations.html) Users can customize images, such as disabling a particular technology area. Following are the examples: **Removing display packages from image:** `layers/meta-qcom-distro/recipes-products/packagegroups/packagegroup-qcom-multimedia.bb` | Before change | After change | | --- | --- | | RDEPENDS:${PN} = "\
packagegroup-container \
packagegroup-qcom-audio \
packagegroup-qcom-bluetooth \
packagegroup-qcom-camera \
packagegroup-qcom-display \
packagegroup-qcom-fastcv \
packagegroup-qcom-graphics \
packagegroup-qcom-opencv \
packagegroup-qcom-sensors \
packagegroup-qcom-video \
python3-docker-compose \
camera-server \
"Copy to clipboard | RDEPENDS:${PN} = "\
packagegroup-container \
packagegroup-qcom-audio \
packagegroup-qcom-bluetooth \
packagegroup-qcom-camera \
packagegroup-qcom-fastcv \
packagegroup-qcom-graphics \
packagegroup-qcom-opencv \
packagegroup-qcom-sensors \
packagegroup-qcom-video \
python3-docker-compose \
camera-server \
"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. **Removing Bluetooth from image:** `layers/meta-qcom-distro/recipes-products/packagegroups/packagegroup-qcom-multimedia.bb` | Before change | After change | | --- | --- | | RDEPENDS:${PN} = "\
packagegroup-container \
packagegroup-qcom-audio \
packagegroup-qcom-bluetooth \
packagegroup-qcom-camera \
packagegroup-qcom-display \
packagegroup-qcom-fastcv \
packagegroup-qcom-graphics \
packagegroup-qcom-opencv \
packagegroup-qcom-sensors \
packagegroup-qcom-video \
python3-docker-compose \
camera-server \
"Copy to clipboard | RDEPENDS:${PN} = "\
packagegroup-container \
packagegroup-qcom-audio \
packagegroup-qcom-camera \
packagegroup-qcom-display \
packagegroup-qcom-fastcv \
packagegroup-qcom-graphics \
packagegroup-qcom-opencv \
packagegroup-qcom-sensors \
packagegroup-qcom-video \
python3-docker-compose \
camera-server \
"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 Source: [https://docs.qualcomm.com/doc/80-70014-27/topic/user_customizations.html](https://docs.qualcomm.com/doc/80-70014-27/topic/user_customizations.html) This section covers how users can add, delete, modify, and rename partitions. A configuration file defining partitions for the UFS device are present at `layers/meta-qcom-hwe/recipes-devtools/partition-utils/partition-confs/generic-ufs-partitions.conf`. If a user intends to add a partition, a new row entry can be added to this file. If a partition is to be removed, removing an entry removes the target partition from the set of images to be flashed. Note: Know the purpose of partitions before removing them. Many partitions are crucial for functionality. To understand the details of how this file plays a role in generating the partition table, see [Partitioning](https://docs.qualcomm.com/doc/80-70014-27/topic/platform_software_features.html#partitioning). **Example 1 – Adding a new partition** To add a partition with name `test` in LUN0, add the following line to the `generic-ufs-partitions.conf` under LUN0 section: --partition --lun=0 --name=test --size=4096KB --type-guid=1B81F7E6-F50D-419B-A739-2AEFF8DA3335Copy to clipboard This adds a partition test to LUN0, with a size of 4 MB and a GUID determined by the user. 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 to the newly created partition** To add a partition with name `test1` in LUN0, add the following line to the `generic-ufs-partitions.conf` under LUN0 section: --partition --lun=0 --name=test --size=4096KB --type-guid=1B81F7E6-F50D-419B-A739-2AEFF8DA3335 --filename=test1.binCopy to clipboard Deploy the new binary `test1.bin` in `build-qcom-wayland/tmp-glibc/deploy/images/qcm6490/$(image_name)`. ## Nodistro build Source: [https://docs.qualcomm.com/doc/80-70014-27/topic/user_customizations.html](https://docs.qualcomm.com/doc/80-70014-27/topic/user_customizations.html) ### About this task A `nodistro` build can be useful for users who want to start with minimalistic images and want control over the software selection and configuration. To create a `nodistro` build, the user must set `/build-qcom-wayland/conf/local.conf` and specify `DISTRO=nodistro`. The user can run the following commands to create a `nodistro` build from a workspace they have created using the Qualcomm manifest. To create a workspace, see [Qualcomm Linux Build Guide](https://docs.qualcomm.com/bundle/publicresource/topics/80-70014-254/introduction.html). ### Procedure 1. Run setup-environment with `nodistro` set for DISTRO: MACHINE="qcm6490" DISTRO="nodistro" source setup-environmentCopy to clipboard After the previous command executes, the directory changes to `build-nodistro`. Changes in configuration files: # changes in build-nodistro/conf/local.conf # Add following lines at end of the file. DISTRO_FEATURES:append = " systemd pam overlayfs" INITRAMFS_IMAGE = "initramfs-qcom-image" INITRAMFS_IMAGE_BUNDLE ?= "1" INIT_MANAGER = "systemd" VIRTUAL-RUNTIME_init_manager = "systemd" VIRTUAL-RUNTIME_dev_manager = "udev"Copy to clipboard 2. Build the minimal image, as for `nodistro` the following is the validated image: bitbake qcom-minimal-imageCopy to clipboard 3. Flashing the device: See [Flash images](https://docs.qualcomm.com/bundle/publicresource/topics/80-70014-254/flash_images.html) for the steps to flash the images to the device using the QDL tool. 4. `nodistro` supports image recipes: `qcom-minimal-image` supports `nodistro`. ## Use of devtool Source: [https://docs.qualcomm.com/doc/80-70014-27/topic/user_customizations.html](https://docs.qualcomm.com/doc/80-70014-27/topic/user_customizations.html) Following are the examples depicting devtool usage for Qualcomm software components: - **Kernel** See [Yocto support](https://docs.qualcomm.com/bundle/publicresource/topics/80-70014-3/yocto-kernel-support.html). - **QDL tool** Use the dev tool 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/qdlCopy 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 └── qdlCopy 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.cCopy to clipboard 3. Change the source tree under `workspace/sources/qdl/` and build your changes: devtool build weston devtool build-image qcom-multimedia-imageCopy to clipboard 4. Images are generated in the path `build-qcom-wayland/tmp-glibc/deploy/images/qcm6490/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/westonCopy 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 └── westonCopy 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.md tests weston.ini.in compositor data doc ivi-shell libweston-desktop meson_options.txt oe-logs protocol remoting tools xwayland CONTRIBUTING.md DCO-1.1.txt fullscreen-shell kiosk-shell man notes.txt oe-workdir README.md shared wcapCopy to clipboard 3. Change the source tree under `workspace/sources/weston/` and build your changes: devtool build weston devtool build-image qcom-multimedia-imageCopy to clipboard 4. The images are generated in the path `build-qcom-wayland/tmp-glibc/deploy/images/qcm6490/qcom-multimedia-image`. ## Customizing kernel Source: [https://docs.qualcomm.com/doc/80-70014-27/topic/user_customizations.html](https://docs.qualcomm.com/doc/80-70014-27/topic/user_customizations.html) For more information on customizing the kernel, see [Qualcomm Linux Kernel Guide](https://docs.qualcomm.com/bundle/publicresource/topics/80-70014-3/). ## Add third-party layers to workspace Source: [https://docs.qualcomm.com/doc/80-70014-27/topic/user_customizations.html](https://docs.qualcomm.com/doc/80-70014-27/topic/user_customizations.html) ### About this task To add any layer to the workspace, perform the following steps: ### Procedure 1. Clone the layer under `/layers/`. 2. Add the layer in the file `layers/meta-qcom-distro/conf/bblayers.conf` as part of the variable `BBLAYERS`, 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 ### Results This allows the BitBake to parse the layer. ## Create a build for debugging Source: [https://docs.qualcomm.com/doc/80-70014-27/topic/user_customizations.html](https://docs.qualcomm.com/doc/80-70014-27/topic/user_customizations.html) You can generate a debug build by exporting `DEBUG_BUILD=1` before issuing Yocto BitBake build instructions: DEBUG_BUILD=1 bitbake qcom-multimedia-imageCopy to clipboard To understand which kernel defconfig and config fragments are used to when `DEBUG_BUILD` is set to **1**, see Kernel configuration, under [Kernel recipes](https://docs.qualcomm.com/doc/80-70014-27/topic/platform_software_features.html#qualcomm_bsp_metadata_layers__ul_hyj_wsh_r1c_rasam_03-08-24-1448-5-931). ## Create a build for optimized boot KPI Source: [https://docs.qualcomm.com/doc/80-70014-27/topic/user_customizations.html](https://docs.qualcomm.com/doc/80-70014-27/topic/user_customizations.html) To achieve the most optimal boot up time for the device, `PERFORMANCE_BUILD` variable is used. The `PERFORMANCE_BUILD` variable when set to **1**, modifies the `KERNEL_CMDLINE_EXTRA` to drop **console** option from the command line. The `PERFORMANCE_BUILD` variable takes effect when `DEBUG_BUILD` is set to **0**. To understand the effectiveness, see the following table: | | PERFORMANCE\_BUILD="0" | PERFORMANCE\_BUILD="1" | | --- | --- | --- | | `DEBUG_BUILD="0"` | Console on UART is enabled. | The console on UART is disabled.



Optimal boot up time. | | `DEBUG_BUILD="1"` | Console on UART is enabled. | Console on UART is enabled.



The `PERFORMANCE_BUILD="1"` setting is ignored as
`DEBUG_BUILD="1"` takes precedence over this
setting. | Last Published: Jul 11, 2024 [Previous Topic Qualcomm Linux features](https://docs.qualcomm.com/bundle/publicresource/80-70014-27/topics/platform_software_features.md) [Next Topic Debug](https://docs.qualcomm.com/bundle/publicresource/80-70014-27/topics/debug.md)