================== Modify Device Tree ================== After completing your board design, usually you need to provide corresponding device tree blobs so that the kernel can recognize your new hardware. For Genio EVK boards, device tree binaries (.dtb/dtbo) are stored in a firmware partition, formatted as the FAT32 filesystem. To generate necessary assets from your device tree blobs used for flashing, there are two methods to achieve this: * Using IOT Yocto to generate firmware partition image. This is the standard and recommended way. * Modifying the existing firmware partition image. Useful for those who are impatient. The overall process can be summarized to following steps: * Create your board dts based on Genio EVK boards. * Build and compile the board dts into dtb files with Ubuntu Linux kernel. * Deploy the dtb files to the FIRMWARE partition of bootloader. * Modify bootloader (U-Boot) to load your dtb files during boot. The following sections will describe both methods in detail. Compile Board DTS with Ubuntu Linux Kernel ========================================== To build your board dts into dtb binary, follow the steps below: 1. First, follow the steps in :doc:`customize-kernel` to set up an Ubuntu kernel build environment, and fetch the Ubuntu kernel source code. .. note:: Be sure to use the same kernel tag as the kernel version used in the board image 2. Add your device tree files to Ubuntu kernel source tree. Assume your dts is named ``customBoard.dts``: .. prompt:: bash auto $ $ cd jammy $ cp customBoard.dts arch/arm64/boot/dts/mediatek/ 3. Modify the ``Makefile``: .. prompt:: bash auto $ $ vim arch/arm64/boot/dts/mediatek/Makefile and add the following line at the bottom of the file: .. code-block:: Makefile dtb-$(CONFIG_ARCH_MEDIATEK) += customBoard.dtb 4. Then simply build the kernel using the same steps in :doc:`customize-kernel`. Set the cross-compilation environment variables if you would like to build on a non-ARM64 platform: .. prompt:: bash $ auto $ export ARCH=arm64 $ export $(dpkg-architecture -aarm64) $ export CROSS_COMPILE=aarch64-linux-gnu- and build the kernel with the following commands: .. prompt:: bash $ auto $ fakeroot debian/rules clean $ fakeroot debian/rules binary The building system will produce Debian packages in the **upper-level** directory. For example, .. code-block:: text $ cd .. $ ls -1 *.deb linux-buildinfo-5.15.0-1003-mtk_5.15.0-1003.4_arm64.deb linux-headers-5.15.0-1003-mtk_5.15.0-1003.4_arm64.deb linux-image-5.15.0-1003-mtk_5.15.0-1003.4_arm64.deb linux-modules-5.15.0-1003-mtk_5.15.0-1003.4_arm64.deb Locate the ``.deb`` package named **modules**. In the example above, it should be ``linux-modules-5.15.0-1003-mtk_5.15.0-1003.4_arm64.deb``. Then extract the ``linux-modules-*.deb`` file into a directory. In the example below we use ``modules``: .. prompt:: bash $ auto $ mkdir modules $ dpkg -x linux-modules-5.15.0-1017-mtk_5.15.0-1017.19_arm64.deb modules $ cd modules $ ls lib/firmware/5.15.0-1017-mtk/device-tree/mediatek/customBoard.dtb The ``lib/firmware/5.15.0-1017-mtk/device-tree/mediatek/customBoard.dtb`` is the device tree binary you need. In the following sections, we will package this ``customBoard.dtb`` file into the boot firmware archives. Using IOT Yocto to Create Boot Assets ===================================== The overall boot firmwares generation process using IOT Yocto can be depicted in following diagram: .. figure:: /_asset/dtb_modify_yocto.png :width: 720px Step 1: Downloading Ubuntu disk image tarball --------------------------------------------- Visit https://ubuntu.com/download/mediatek-genio to download and extract the Ubuntu disk image. Step 2: Building custom device tree blobs ----------------------------------------- Please refer to `Compile Board DTS with Ubuntu Linux Kernel`_. Step 3: Adding custom device tree blobs to IOT Yocto source ----------------------------------------------------------- To add device tree blobs, an IOT Yocto source tree is needed. To download IOT Yocto source, please visit `IOT Yocto documentation `_ for more details. Supposed that we have downloaded IOT Yocto source tree, please create a new folder ``files`` under the source tree and copy all custom device tree blobs to the folder: .. prompt:: bash $ auto mkdir /src/meta-rity/meta/recipes-core/board-assets/files cp /src/meta-rity/meta/recipes-core/board-assets/files And create a new file ``firmware-part.bbappend`` with following content: .. code-block:: FILESEXTRAPATHS:prepend := "${THISDIR}/files:" SRC_URI = " \ file://customBoard.dtb \ file://device1.dtbo \ file://device2.dtbo \ " Step 4: Building board assets ----------------------------- Please run following commands to initialize building environment: .. prompt:: bash $ auto cd TEMPLATECONF=$PWD/src/meta-rity/meta/conf source src/poky/oe-init-build-env And modify the content of building configuration file ``build/conf/local.conf`` to add following settings: .. code-block:: DISTRO_FEATURES += "prebuilt-dtb" MACHINE_DTB = "customBoard.dtb" DTB_PATH = "/FIRMWARE/your-vendor/customBoard/" # Enable building proprietary software if you have access to MediaTek proprietary # repositories. #NDA_BUILD = "1" Now please run following command to build board assets: .. prompt:: bash $ auto DISTRO=rity-demo MACHINE= bitbake board-assets Where ```` is the name of a Genio EVK board, such as ``genio-700-evk``. .. note:: The value of ```` must be one of the machine names defined in IOT Yocto. You can choose the name of a Genio EVK board on which your custom board is based. If building process completes, a tarball ``board-assets.tar.gz`` will be created under ``/build/tmp/deploy/images/`` folder. Step 5: Flashing board assets ----------------------------- Before flashing board assets, we need to put built assets under the extracted folder of Ubuntu image tarball (refer to `Step 1: Downloading Ubuntu disk image tarball`_), so that the flashing tool can recognize and load necessary files correctly. Please run the following commands to copy board assets: .. prompt:: bash $ auto cd && tar zxf board-assets.tar.gz cp /board-assets/firmware.vfat cp /board-assets/u-boot-initial-env Note the file ``firmware.vfat`` is a partition image containing your custom device tree blobs. Now we're ready to flash our custom device tree blobs: .. prompt:: bash $ auto cd genio-flash firmware:firmware.vfat mmc0boot1 .. _modify-firmware-partition-content-manually: Modifying FIRMWARE Partition Content Manually ============================================= If you already have a ``firmware.vfat`` file (no matter it's downloaded or built), in addition to using IOT Yocto, you can also modify the content of ``firmware.vfat`` to add the device tree blobs for your custom board. .. note:: This method is intended solely for development purposes. We strongly advise using IOT Yocto to construct board assets. The overall board assets manual modification process can be depicted in following diagram: .. figure:: /_asset/dtb_modify_manual.png :width: 720px Step 1: Building custom device tree blobs ----------------------------------------- Please refer to `Compile Board DTS with Ubuntu Linux Kernel`_. Step 2: Modifying firmware.vfat ------------------------------- To modify ``firmware.vfat``, we need to mount the file as a loop device: .. prompt:: bash $ auto sudo mkdir -p /mnt/firmware sudo mount -o loop firmware.vfat /mnt/firmware And copy your compiled DTB file, e.g. ``customBoard.dtb``, to the subfolder under the ``/mnt/firmware`` folder: .. prompt:: bash $ auto sudo mkdir -p /mnt/firmware/FIRMWARE/your-vendor/customBoard/ sudo cp customBoard.dtb /mnt/firmware/FIRMWARE/your-vendor/customBoard/ sudo cp device1.dtbo /mnt/firmware/FIRMWARE/your-vendor/customBoard/ sudo cp device2.dtbo /mnt/firmware/FIRMWARE/your-vendor/customBoard/ And then unmount to ensure changes are written to the file: .. prompt:: bash $ auto sudo umount /mnt/firmware Finally, integrate the resulting ``firmware.vfat`` into your boot assets. Step 3: Adjust Boot Script -------------------------- In most cases, you might add new device tree binaries or adding new overlay(``.dtbo``) files. Therefore it is necessary to update the bootloader's initialization script to load the device tree files you want, and pass the device tree to Linux kernel for correct hardware device detection and driver probing. In U-Boot, the device tree files being loaded during boot flow is determined by a set of **environment variables**. To change the device tree files being used, you can simply update the ``u-boot-initial-env`` file in the boot assets. For example, to allow U-Boot to load your custom device tree files, please edit ``u-boot-initial-env`` and change following settings: .. code-block:: ini dtb_path=/FIRMWARE/your-vendor/customBoard/ fdtfile=customBoard.dtb list_dtbo= device1.dtbo device2.dtbo boot_conf=#conf-customBoard.dtb#conf-device1.dtbo#conf-device2.dtbo Note we modify the ``dtb_path`` with the folder path you've added in `Step 2: Modifying firmware.vfat`_. Additionally, we update ``fdtfile`` with the custom device tree file, and include custom device tree overlays in both ``list_dtbo`` and ``boot_conf``. Step 4: Flashing board assets ----------------------------- You can use ``genio-flash`` to update the ``firmware`` partition on the EVK during development: .. prompt:: bash $ auto genio-flash firmware:firmware.vfat If you want to apply this firmware during production, you might want to combine this partition with other partitions to produce a full-disk image. Please refer to :ref:`ubuntu-combine-into-full-disk-image` to do so. If you modified boot scripts in `Step 3: Adjust Boot Script`_, you also need to update the ``mmc0boot1`` partition to update these U-Boot environment variables on the board during development: .. prompt:: bash $ auto genio-flash mmc0boot1 Check Device Tree ================= After updating ``firmware`` partition and booting into the Linux kernel, you can use ``dtc`` tool to convert the dtb binary loaded by the Linux kernel back into a plain-text format for inspection: .. prompt:: bash $ auto dtc -I fs /proc/device-tree You can check the device tree nodes to confirm if your modifications to the device tree have been successfully applied or not.