Introduction
This article introduces how to build a Linux desktop environment using the Yocto Project for Altera® SoC FPGA.
The construction of a Linux environment using the Yocto Project is introduced separately in the article below. Based on the procedure in the article below (hereafter, Basic Procedure), we will explain the necessary changes to build a desktop environment.
Reference: How to Build Linux for Altera® SoC FPGA (Yocto Poky Edition)
Furthermore, the desktop environment created using the procedure in this article is published on the following page, so you can try it targeting Terasic's DE25-Nano (equipped with Altera® Agilex™ 5 SoC FPGA).
Reference: SoC FPGA Linux Desktop Environment (for Terasic DE25-Nano)
1. Customizing the Yocto Build Environment and Running bitbake
The meta-openembedded layer used together with the Yocto standard meta layer (poky) already includes recipes for supporting desktop environments.
There are two layers that include relevant recipes: meta-xfce and meta-gnome. This time, we built the desktop using meta-xfce, which is lightweight and suitable for embedded applications.
| Item | meta-xfce | meta-gnome |
|---|---|---|
| Intended Use | Embedded GUI / Industrial Use | Desktop-class Linux |
| UI Characteristics | Lightweight & Simple | Feature-rich & Modern |
| Display Platform | X11 (Xorg) | Wayland / X11 |
| Resource Consumption | Low | High |
| GPU Requirement | Low (Software Rendering Possible) | High (GPU Required) |
| Startup Speed | Fast | Slower |
| Customizability | High | More Constraints |
| Number of Recipes / Dependencies | Relatively Few | Very Many |
| Yocto Build Load | Light | Heavy |
| Embedded Suitability | High | Low to Medium |
1-1. Initial Setup
First, perform the initial setup of the Yocto environment according to the Basic Procedure. Assuming the steps in the linked page have been completed, we will introduce the changes necessary to build the desktop environment.
Reference: How to Build Linux for Altera® SoC FPGA (Yocto Poky Edition)
- 1. Preparing the host machine
- 2. Setting up the Yocto environment - getting a recipe (first time only)
- 3. Script execution and environment setting (first time only)
1-2. Adding meta Layers
The meta-openembedded and meta-xfce/meta-gnome layers become available by performing the setup described in the Basic Procedure. Therefore, there is no need to add layers specifically for building the desktop environment.
Note: In the procedures introduced below, a web browser (firefox) is added. The recipe for firefox is not included in the meta layers set up in the Basic Procedure, so it needs to be added separately.
Add the meta-browser layer for setting up the web browser (firefox). Execute the following commands to download meta-browser and add its configuration to bblayers.conf.
cd ~/poky-socfpga
cd layers
git clone -b master https://github.com/OSSystems/meta-browser
cd ..
echo 'BBLAYERS += " ${TOPDIR}/../layers/meta-browser/meta-firefox "' >> conf/bblayers.conf Note: Since meta-browser is downloaded specifying the master branch, be careful about the compatible Yocto version. Please confirm that the layer.conf's LAYERSERIES_COMPAT_firefox-browser-layer includes the Yocto version you use (e.g., walnascar).
meta-browser/meta-firefox/conf/layer.conf at master · OSSystems/meta-browser
1-3. Adding Desktop Image Recipe (xfce-extended-image)
In addition to the recipes included under meta-xfce, create and add an original recipe.
Please place a text file with the same contents as the attached xfce-extended-image.bb at the following location.
- Location: ~/poky-socfpga/layers/meta-intel-fpga-refdes/recipes-images/poky
1-4. Configuration Changes (local.conf)
No changes are necessary specifically for building the desktop environment.
Optionally, to stabilize operation after the desktop starts, add the following lines to conf/local.conf.
PACKAGE_EXCLUDE += " blueman blueman-locale-en-gb bluez5-testtools"
BAD_RECOMMENDATIONS += " blueman blueman-locale-en-gb" Note: This configuration excludes blueman and Bluetooth-related packages from installation. Although blueman is registered to start at desktop startup, it was removed from installation targets because it increased memory usage and affected stable operation.
1-5. Build / Running bitbake
Finally, just run bitbake specifying the added desktop image recipe.
cd ~/poky-socfpga
source poky/oe-init-build-env
bitbake xfce-extended-imageAfter the build completes, a desktop-compatible Root Filesystem will be generated under ~/poky-socfpga/deploy/images/agilex5.
- xfce-extended-image-agilex5.rootfs.tar.gz ... Other files in jffs2 format are also generated
- xfce-extended-image-agilex5.rootfs.manifest ... List of packages included in the Root Filesystem
By creating an SD card image using this Root Filesystem, you can realize the desktop environment.
2. Changes to the Linux Kernel
In addition to supporting the Root Filesystem, changes are also required on the Linux Kernel side.
The necessary changes are described below by item.
2-1. Changes to defconfig
The following settings were added to arch/arm64/configs/defconfig.
These settings enable functions essential for desktop use such as video processing (V4L2 / Media Framework), USB camera/input devices, DMA/shared memory, and FPGA framebuffer display.
CONFIG_CMA_AREAS=32
CONFIG_MEDIA_SUPPORT_FILTER=y
CONFIG_MEDIA_SUBDRV_AUTOSELECT=y
CONFIG_VIDEO_DEV=y
CONFIG_MEDIA_CONTROLLER=y
CONFIG_DVB_CORE=y
CONFIG_V4L2_H264=m
CONFIG_V4L2_VP9=m
CONFIG_V4L2_MEM2MEM_DEV=m
CONFIG_V4L2_FWNODE=m
CONFIG_V4L2_ASYNC=m
CONFIG_USB_VIDEO_CLASS_INPUT_EVDEV=y
CONFIG_VIDEOBUF2_CORE=y
CONFIG_VIDEOBUF2_V4L2=y
CONFIG_VIDEOBUF2_MEMOPS=y
CONFIG_VIDEOBUF2_DMA_CONTIG=m
CONFIG_VIDEOBUF2_VMALLOC=y
CONFIG_VIDEOBUF2_DMA_SG=m
CONFIG_MEDIA_TUNER=m
CONFIG_MEDIA_TUNER_MC44S803=m
CONFIG_MEDIA_TUNER_MT20XX=m
CONFIG_MEDIA_TUNER_SIMPLE=m
CONFIG_MEDIA_TUNER_TDA18271=m
CONFIG_MEDIA_TUNER_TDA827X=m
CONFIG_MEDIA_TUNER_TDA8290=m
CONFIG_MEDIA_TUNER_TDA9887=m
CONFIG_MEDIA_TUNER_XC2028=m
CONFIG_MEDIA_TUNER_XC4000=m
CONFIG_MEDIA_TUNER_XC5000=m
CONFIG_FB_ALTERA_VIP_FB2=y
CONFIG_FB_ALTERA_VIP_FB2_PLAT=y
CONFIG_FB_SIMPLE=y
CONFIG_HIDRAW=y
CONFIG_USB_HIDDEV=y
CONFIG_SERIAL_ALTERA_JTAGUART=y
CONFIG_EXPERT=y
#CONFIG_PREEMPT_RT=y
#CONFIG_HZ_1000=y
#CONFIG_HZ=1000
CONFIG_DMA_SHARED_BUFFER=y
CONFIG_UVC_COMMON=y
CONFIG_UDMABUF=y
CONFIG_LOGO_LINUX_CLUT224=y Note: Since related config items are set broadly, please note that not all of them are necessarily required. For example, multiple framebuffer driver settings (CONFIG_FB_xx) are enabled, but only the driver linked to CONFIG_FB_SIMPLE is actually used.
Note: The method to switch the log output destination will be explained later, but if you want to display the Linux boot log on an HDMI monitor (Framebuffer), you need to specify
CONFIG_LOGO_LINUX_CLUT224=y.
2-2. Changes to Device Tree
You need to add the definition of the Framebuffer (a buffer holding desktop rendering data) to the Linux device tree.
Note: Framebuffer parameters include compatible indicating Simple Framebuffer, buffer address and size (reg), as well as format and viewing angle.
Note: The reserved-memory definition excludes the memory area used for the Framebuffer from being managed by the Linux Kernel as part of the memory pool.
Note: The figure above also enables i2c0, which depends on the board used. This enables the device definition for the HDMI control I2C interface.
2-3. Changes to Kernel Arguments (bootargs)
If the bootloader (SSBL: U-Boot) performs initial setup of HDMI and Framebuffer, you can display the boot log on the HDMI monitor by changing the kernel arguments (bootargs) passed from U-Boot to Linux.
Below are the bootargs settings for changing the boot log output destination.
- To display the boot log on the serial terminal (UART) (normal setting):
setenv bootargs console=ttyS0,115200 root=${mmcroot} rw rootwait- To display the boot log on the Framebuffer:
setenv bootargs console=tty0 root=${mmcroot} rw rootwait- To display the boot log on both Framebuffer and UART:
setenv bootargs console=tty0 console=ttyS0,115200 root=${mmcroot} rw rootwait Note: The boot log output destination changes depending on the console specification in bootargs.
Note: This article does not cover bootloader customization. For bootloader changes, please refer to the source tree attached to the following article.
Reference: SoC FPGA Linux Desktop Environment (for Terasic DE25-Nano)
3. Others
3-1. Swap Settings
When running a desktop in a Linux environment with limited memory resources, it is safer to set up swap. This time, we confirmed the desktop environment construction using Terasic's DE25-Nano. Since the DE25-Nano only has 1GB of DDR memory on the HPS side, setting up swap was essential when performing operations that consume a lot of memory after the desktop starts.
Note: It is recommended to secure a total size of about 1.5GB combining DDR (actual memory) and swap area. Depending on usage, 1GB alone may cause memory exhaustion.
When setting up swap during SD card image creation, run the following commands in the rootfs directory. (Example of securing a 512MB swap area within the same partition as rootfs)
cd rootfs
sudo mkdir mnt/data
sudo fallocate -l 512M mnt/data/swapfile
sudo chmod 600 mnt/data/swapfile
sudo mkswap mnt/data/swapfileAlso, by adding the following entry to etc/fstab under rootfs, the swap area will be automatically set at Linux boot. Edit etc/fstab by launching an editor such as vi or nano with sudo.
/mnt/data/swapfile none swap sw,nofail 0 0 Note: Besides the swap file method introduced above, you can also create a dedicated partition for swap.
Summary
This article introduced how to build a Linux desktop environment using the Yocto Project for Altera® SoC FPGA.
As introduced at the beginning of this article, the desktop environment created by the method in this article is published on the following article page.
Reference: SoC FPGA Linux Desktop Environment (for Terasic DE25-Nano)
In addition to the image files for launching the desktop, source trees, Yocto recipes, and configuration files are also available for download, so please refer to them.