Astra Yocto Linux开发人员指南

Overview概述

This guide describes Synaptics specific configurations and procedures required to build and use Yocto images with the supported Synaptics SoC and development boards.
本指南介绍 在支持的Synaptics SOC和开发板上构建和使用Yocto映像所需的Synaptics特定配置和步骤。

This guide assumes that the reader already has some familiarity with Yocto concepts. For introductory material about Yocto and general Yocto reference guides, please refer to the official Yocto Documentation.
本指南假设读者已经对 Yocto的概念有所熟悉。有关Yocto的介绍材料和通用的Yocto参考指南,请参考官方的 Yocto文档

This BSP works with the Yocto Kirkstone release and provides support for the following machines, distributions and images:
此BSP与Yocto Kirkstone版本配套使用,并为以下 机器、发行版和映像提供支持:

Supported machines, distributions and images
已支持的机器、发行版和映像

Machine机器

Distribution发行版

Images映像

sl1620SL1620

poky

astra-mediaastra-media

sl1640SL1640

poky

astra-mediaastra-media

sl1680SL1680

poky

astra-mediaastra-media

Build host requirements构建主机要求

The recommended hardware is a x86_64 host with at least:
推荐的硬件是x86_64主机,至少具有:

  • 16 cores16 核

  • 32 GB of RAM32 GB RAM

  • 150 GB of disk150 GB磁盘

As an example, building from scratch the astra-media image for vs640 on a c5a.4xlarge AWS instance, which matches the requirements above, takes approximately 2 hours.
例如,在符合上述要求的 c5a.4xlarge AWS实例上, 从零开始构建vs640astra-media映像,大约需要2小时。

The Yocto build system can very efficiently exploit more cores if these are available.
Yocto构建系统可以非常有效地利用更多可用的内核。

Note注意

Building entirely from NFS mounted directories is not supported by the Yocto build system. Please refer to Yocto documentation on the TMPDIR variable for more details.
Yocto构建系统不支持完全从NFS装载的目录构建。更多详细信息, 请参阅 关于TMPDIR变量的Yocto文档

The recommended software configuration is the following:
推荐的软件配置如下:

  • Ubuntu 22.04 LTS

  • Docker 20.10 or later provided by the standard Ubuntu package docker.io
    由标准的Ubuntu包 docker.io 提供的Docker 20.10或更高版本

Other versions of Linux and Docker may also work but may need special configuration. You can find more information on how to install Docker in Ubuntu in Docker setup.
其他版本的Linux和Docker也可以使用,但可能需要特殊配置。您可以在 Docker安装 中找到更多关于如何在Ubuntu中安装Docker的信息。

The Synaptics Astra SDK is known to work also on Ubuntu 22.04 installed inside Windows Subsystem For Linux (WSL) 2.0 on Windows 11. You can find more information on how to install WSL2 in WSL 2 Setup (required only when using Windows).
众所周知, Synaptics Astra SDK也可在安装于Windows 11上的Windows Subsystem For Linux(WSL)2.0中的Ubuntu 22.04上运行。您可以在 WSL 2安装(仅在使用Windows时需要)中找到关于如何安装WSL 2的更多信息。

The build can also be executed directly on a Linux host provided that the Yocto build dependencies are installed. This configuration is not supported by Synaptics.
如果Yocto构建的所有依赖项均已安装,则构建也可直接在Linux主机上执行。当前Synaptics不支持此配置。

WSL 2 Setup (required only when using Windows)WSL 2安装(仅在使用Windows时需要)

Note注意

If you previously installed WSL1, installed another WSL2 distribution or disabled the hyper-v support on your machine you may need to perform some additional steps. See the Troubleshooting section for some suggested steps.
如果您曾在您的机器安装过WSL 1,安装过另一个WSL 2发行版或禁用了Hyper-v支持, 则可能需要执行一些额外的步骤。关于建议的步骤,请参见 故障排除 章节。

First install Windows Subsystem for Linux with the following command in PowerShell (as administrator):
首先在PowerShell中使用以下命令安装Windows Subsystem for Linux(作为管理员):

PS C:\Users\username> wsl --install

This command will setup WSL and the default distribution which is Ubuntu 22.04 at the time of writing. You can find more details on installation procedure the WSL website.
此命令将安装WSL和本文撰写时的默认版本Ubuntu 22.04。 您可以在WSL网站上找到有关安装过程的更多详细信息。

By default WSL only uses up to 50% of the RAM of the host, this may not be enough to reach the memory required to build an image. If that’s the case you can in increase the memory adding the following to the file .wslconfig in your user directory (normally C:\Users\<Username):
默认情况下,WSL仅使用主机RAM的50%,这可能达不到构建映像所需的内存。 如果是这种情况,您可以在您的用户目录(通常为C:\Users\<Username)下的文件.wslconfig中添加以下内容来增加内存:

[wsl2]
memory=24GB

Then to apply the changes in powershell run the command:
然后需要在powershell中让改动生效,请运行命令:

PS C:\Users\username> wsl.exe --shutdown

You can find more information about WSL configuration here.
您可以在 这里 找到有关WSL配置的更多信息。

Once you setup the WSL2 environment you can start a terminal from the start menu by selecting the Windows Terminal App and then select the Ubuntu-22.04 distribution.
一旦安装了WSL 2环境, 您可以从开始菜单中启动终端,方法是选择Windows Terminal App,然后选择Ubuntu-22.04发行版。

Once you are in the terminal you can install Docker as described in Docker setup
进入终端后,您可以按照 Docker安装 中的说明安装Docker

Docker setupDocker安装

To install docker use the following steps:
要安装Docker,请使用以下步骤:

  1. Install the docker package:安装docker包:

    $ sudo apt install docker.io
    
  2. Add the current user to the docker group so that it will be able to use docker:
    将当前用户添加到docker组,以便它能够使用docker:

    $ sudo adduser ${USER} docker
    
  3. The change of user will not be automatically applied until a reboot (in some situation a log-in may suffice). To apply the changes to the current shell you can also run the following command:
    在重新启动之前,用户的改动不会自动生效(在某些情况下,登录就足够了)。要让改动在 当前shell中生效,您还可运行以下命令:

    $ newgrp docker
    $ newgrp ${USER}
    

How to build an image如何构建映像

Start the build environment启动构建环境

Note注意

The following steps require an host with docker correctly installed, you can find more information on how to setup docker in Build host requirements.
以下步骤需要一个正确安装了docker的主机, 你可以在 Build host requirements 中找到关于如何设置docker的更多信息。

Warning警告

When using WSL2 build from /mnt/c and other host file system drives is not supported. Your build folder must reside on the native WSL2 file system (e.g. /home/${USER})
不支持在/mnt/c以及其他主机文件系统驱动上使用WSL 2构建。您的构建 文件夹必须位于本机WSL 2文件系统上(例如/home/${USER}

In order to ensure a correctly configured and clean environment, the build must be performed within a Docker container. To do so you need to start a new temporary container that will host the build. The container can be terminated when the build is finished and a new container can be started later to rebuild with the same command.
为了确保正确配置和干净的环境, 必须在Docker容器中执行构建。为此,您需要启动一个新的临时容器来承载该构建。 当构建完成时,可以终止容器,稍后可以启动新容器以使用相同的命令进行重建。

To start the container use the following command line:
要启动容器,请使用以下命令行:

$ docker run --rm -it -v $(pwd):$(pwd) ghcr.io/synaptics-astra/crops:0.9.0 --workdir=$(pwd)

This will spawn a shell inside the container. The current directory of the host is mounted inside the container so that the workspace is available within the container.
这将在容器内生成一个shell。 主机的当前目录挂载在容器内,以便该工作空间在容器内可用。

Note注意

On Ubuntu 20 and 18 LTS the seccomp protection feature of docker has to be disabled when creating the build container by adding the parameter --security-opt "seccomp=unconfined" after the --rm parameter in the command line above.
在Ubuntu 20和18 LTS上,创建构建容器时,必须禁用docker的seccomp保护功能,方法是在上面的命令行中的--rm参数之后添加参数 --security-opt "seccomp=unconfined"

Note注意

Synaptics provides a pre-built container at ghcr.io/synaptics-astra/crops that is automatically downloaded when you run the command above but you can also compile from the sources available here.
Synaptics在ghcr.io/synaptics-astra/crops 中提供了一个预构建的容器,当您运行上面的命令时,该容器会自动下载,但您也可以从 这里 提供的源代码进行编译。

Obtain the sources获取源码

The sources of the Synaptics Yocto release can be downloaded by cloning a top level git repo. The repository contains all the required layers as submodules.
Synaptics Yocto发行版的源代码可通过克隆top level git repo来下载。代码仓库包含作为子模块的所有必需层。

To clone the repository within the build environment started with the instructions in Start the build environment use the following command:
要在根据 启动构建环境 说明所生成的构建环境中克隆代码仓库,请使用以下命令:

pokyuser@xyz:/path/to/workspace $ git clone -b v0.9.0 --recurse-submodules \
                                            https://github.com/synaptics-astra/sdk

The recipes contained in the meta-synaptics layer point to the relevant git repository and will be downloaded using the standard bitbake fetching mechanism of Yocto.
包含在meta-synaptics 层中的recipes指向相关的git代码仓库,并可通过Yocto的标准Bitbake获取机制来下载。

Build an image构建映像

To build an image execute the following commands:
要构建映像,请执行以下命令:

pokyuser@xyz:/path/to/workspace $ cd sdk

pokyuser@xyz:/path/to/workspace/sdk $ source meta-synaptics/setup/setup-environment

pokyuser@xyz:/path/to/workspace/sdk/build-XYZ $ bitbake astra-media

The resulting image can be found in build-${MACHINE}/tmp/deploy/images/${MACHINE}/SYNAIMG/.
生成的映像可以在build-${MACHINE}/tmp/deploy/images/${MACHINE}/SYNAIMG/中找到。

The image can be flashed to an evaluation kit board as described in Updating the Firmware.
可以将映像刷新到评估套件板, 如 更新固件 中所述。

After flashing the board, to log in to the board please refer to Linux OS Login.
刷新主板后, 请参阅 Linux操作系统登录 来登录主板。

How to develop an application如何开发应用程序

One of the key features of the Yocto project is the ability to create a standalone SDK that includes everything you need to develop and test applications for a given target image.
Yocto项目的一个关键特性是能够创建一个独立SDK,包含为给定的目标的映像开发和测试应用程序的一切所需。

The standalone toolchain is a precompiled set of tools, libraries, and headers that match the configuration of your Yocto Project build. It provides a consistent and controlled development environment that closely mirrors the target system. This ensures that the applications you develop will be compatible with the specific image that you’re deploying on your embedded devices.
独立工具链是一组预编译好的工具、库和头文件, 与您的Yocto Project构建的配置相匹配。它提供了一个密切反映目标系统的一致的、可控的开发环境, 以确保您开发的应用程序与您在嵌入式设备上部署的特定映像兼容。

Using the standalone toolchain, you can compile on your development machine before deploying them to the target device. This can greatly speed up the development process, as you don’t need to compile the entire image each time you want to test a change.
使用该独立的工具链, 您可以在开发机器上完成编译后将它们部署到目标设备。这可以极大地加快开发过程,因为当您对某处改动进行测试时,无需每次都编译整个映像。

Pre-compiled toolchains for the default Astra Machina images are also available on GitHub.
GitHub 上也为默认Astra Machina映像提供了预编译好的工具链。

Once you obtained the toolchain, you can install it on your development machine. The toolchain includes a script that sets up the environment variables needed to use the tools. The recommended and supported configuration of the development machine is the same as described in Build host requirements but the toolchain is compatible with a wide range of environments.
获得该工具链后,您可以将其安装在开发机器上。该工具链含有一个脚本 用于设置使用那些工具所需的环境变量。开发机器中推荐的和支持的配置与 构建主机要求 中描述的一致,而该工具链是与多种环境相兼容的。

To setup the toolchain you first uncompress it as follows:
要安装该工具链,首先要按如下方式解压缩:

$ ./poky-glibc-x86_64-astra-media-${CPUTYPE}-${MACHINE}-toolchain-4.0.9.sh
Poky (Yocto Project Reference Distro) SDK installer version 4.0.9
=================================================================
Enter target directory for SDK (default: /opt/poky/4.0.9): toolchain
You are about to install the SDK to "/home/user/toolchain". Proceed [Y/n]?
Extracting SDK.................................................................................................................................................................................................................................................................................................................................done
Setting it up...done
SDK has been successfully set up and is ready to be used.
Each time you wish to use the SDK in a new shell session, you need to source the environment setup script e.g.
  $ . /home/user/toolchain/environment-setup-armv7at2hf-neon-vfpv4-pokymllib32-linux-gnueabi
  $ . /home/user/toolchain/environment-setup-cortexa73-poky-linux

The exact names of the toolchain environment files depend on the target board: CPUTYPE for sl1680 is cortexa73, for sl1620 and sl1640 is cortexa55
该工具链环境文件的确切名称取决于目标板:sl1680CPUTYPEcortexa73,而sl1620sl1640的则是cortexa55

Then to configure the build environment you need to source a configuration script as follows:
然后,要配置构建环境,您需要按如下方式获取配置脚本:

$ . toolchain/environment-setup-${CPUTYPE}-poky-linux

With the environment setup, you can use the provided cross-compiler to compile your applications. The toolchain also includes libraries and headers for the various components included in the image, so you can develop applications that take full advantage of these components. You can use the environment variables set by the script such as CC to invoke the cross-compiler and build your application with it.
通过环境设置,您可以使用提供的交叉编译器来编译应用程序。该工具链还包括映像中包含的各种组件的库和头文件,因此您可以充分利用这些组件来开发 应用。您可以使用脚本(如CC)设置的环境变量来调用交叉编译器并用它构建应用程序。

More information about the standalone toolchain are available in the Yocto documentation.
有关该独立工具链的更多信息,请参见 Yocto documentation

How to re-build a standalone toolchain如何重新构建独立的工具链

You can re-generate a toolchain in your Yocto build environment configured as described in How to build an image by running the following command:
通过运行以下命令,您可以在Yocto构建环境中重新生成工具链,该环境按照 如何构建映像 中所述进行配置:

pokyuser@xyz:/path/to/workspace $ cd sdk

pokyuser@xyz:/path/to/workspace/sdk $ source meta-synaptics/setup/setup-environment

pokyuser@xyz:/path/to/workspace/sdk/build-XYZ $ bitbake astra-media -c do_populate_sdk

The build proces will generate the toolchain in the directory build-${MACHINE}/tmp/deploy/sdk.
构建过程将在目录build-${MACHINE}/tmp/deploy/sdk中生成工具链。

Compatible Layers兼容层

This BSP is compatible with these layers:此BSP与以下层兼容:

  • poky [branch: kirkstone]
    poky[分支:kirkstone]

  • meta-openembedded [branch: kirkstone]
    meta-openembedded [分支:kirkstone]

    • meta-oe (required by meta-python below)
      meta-oe(以下meta-python所要求)

    • meta-python (required by meta-multimedia below)
      meta-python(以下meta-multimedia所要求)

    • meta-multimedia (optional - for gstreamer support)
      meta-multimedia(可选-用于gstreamer支持)

  • meta-qt [branch qt/upstream/kirkstone ] (optional)
    meta-qt [分支qt/upstream/kirkstone ](可选)

Images映像

astra-media

The astra-media image, based on the poky distribution, provides a basic graphical system with weston and it is suitable to test sl1640 and sl1680 features.
基于poky发行版的astra-media映像提供了 一个带有weston的基本图形系统,适合测试sl1640sl1680的特性。

The image requires some specific configurations in conf/local.conf to work correctly. The meta-synaptics/setup/setup-environment script can be used to correctly setup a astra-media build automatically.
映像需要 conf/local.conf中的一些特定配置才能正常工作。meta-synaptics/setup/setup-environment脚本可用于自动正确设置astra-media构建。

For more details about these configurations please refer to the comments in the sample local.conf found in meta-synaptics/setup/conf/local.conf.sample.
有关这些配置的更多细节,请参阅 meta-synaptics/setup/conf/local.conf.sample中的示例local.conf的注解。

In order to be able to run qt application on wayland the following package must also be added. This must be enable manually even when using setup/setup-environment:
要在wayland上运行qt应用,还必须添加以下软件包 .即便用setup/setup-environment,也必须通过手动来启用:

DISTRO_EXTRA_RDEPENDS:append = " qtwayland"

Configuration配置

Kernel command line内核命令行

The kernel command line is defined by the variable CMDLINE of the linux-syna recipe.
内核命令行由linux-syna recipe的变量CMDLINE定义。

System Memory configuration系统内存配置

System memory configuration is performed by changing the variables CONFIG_PREBOOT_ in the configuration file pointed by SYNA_SDK_CONFIG_FILE variable. The available configurations can be found by inspecting https://github.com/synaptics-astra/boot-preboot-prebuilts .
通过更改 SYNA_SDK_CONFIG_FILE 变量指向的配置文件中的变量 CONFIG_PREBOOT_ 来执行系统内存配置。 在 https://github.com/synaptics-configuration/boot-preboot-prebuilts 上可找到这些可用配置。

Partition tables分区表

Partition tables are configured in the file emmc.pt found in the directory product/${SYNA_SDK_CONFIG_NAME}/emmc.pt found at http://github.com/synaptics-astra/configs . The SYNA_SDK_CONFIG_NAME depends on the MACHINE and DISTRO_CONFIG variables.
分区表是配置在目录product/${SYNA_SDK_CONFIG_NAME}/emmc.pt下的文件emmc.pt里, 可在 http://github.com/synaptics-brows/browses 上找到。 SYNA_SDK_CONFIG_NAME依赖于变量MACHINEDISTRO_CONFIG

To customize this file you can override the recipe syna-config-native.
您可以改写recipe syna-config-native 来客制化此文件。

Some partitions are used by the early boot components stored in eMMC boot partition. These partitions cannot be removed but can be moved. The early boot components locate these partitions using the GPT found in the UDA. Loading from other hardware partitions is not supported.
一些分区是供存储在eMMC引导分区中的早期引导组件使用的。 它们不能被删除,但可移动。早期的引导组件使用UDA中的GPT定位这些分区。不支持从其他硬件分区加载。

Frequently Asked Questions常见问题

How do I override the value of to a recipe variable in local.conf?
如何改写local.conf中的recipe变量?

To append the text some text to the variable FOO of recipe bar add the following line to local.conf:
要将文本some text追加到recipe bar里的变量FOO中, 可在文件 local.conf 中添加如下这行:

FOO:append:pn-bar = " some text"

Other changes to the variable can be performed with the standard operators described in the Bitbake Guide.
可以使用 Bitbake Guide 中描述的标准操作符来执行对变量的其他更改。

Troubleshooting故障排除

The build fails at the package gdk-pixbuf-native with error Failed to close file descriptor for child process on Ubuntu 20 or 18.
在Ubuntu 20或18上构建包gdk-pixbuf-native失败, 错误信息为Failed to close file descriptor for child process

This problem is caused by an incompatibility of the package build system with the libseccomp library on the host that is running docker. To solve this issue update the libseccomp2 library on the host that runs docker or add the parameter --security-opt "seccomp=unconfined to the docker command line when creating the docker build environment.
此问题是由包构建系统与运行Docker的主机上的库libseccomp不兼容引起的。 要解决此问题,请在运行docker的主机上更新库libseccomp2,或在创建docker构建环境时将参数--security-opt "seccomp=unconfined添加到docker命令行。

Build of packages with out-of-trees modules (such as synasdk-synap-module) fail with error Kernel configuration is invalid..
使用Out-Of-Trees模块(如synasdk-synap-module)构建包失败,错误信息为Kernel configuration is invalid.

Under some circumstances the state of the recipe make-mod-scripts may become corrupted. To fix the issue clean the recipe with the command:
在某些情形下,recipe make-mod-scripts的状态可能被损坏。 要修复此问题,请用以下命令清理recipe:

bitbake -c cleansstate make-mod-scripts

Docker commands fail with the error permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock: Get "http://%2Fvar%2Frun%2Fdocker.sock/v1.24/version": dial unix /var/run/docker.sock: connect: permission denied
Docker命令失败, 错误信息为 permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock: Get "http://%2Fvar%2Frun%2Fdocker.sock/v1.24/version": dial unix /var/run/docker.sock: connect: permission denied

Make sure your user is in the docker group:
请确保您的用户账号在docker组中:

$ getent group docker
docker:x:133:yourusername

and that your current session is logged in to the docker group:
并且您的当前会话已登录到docker组:

$ id
uid=1000(yourusername) gid=1000(yourusername) groups=1000(yourusername),133(docker)

To add your user to the docker group use the following command:
如要添加您的用户账号到docker组,请使用以下命令:

$ sudo adduser yourusername docker

To ensure your session logged in to the docker group use the following command:
如要确保您的会话登录到docker组,请使用以下命令:

$ newgrp docker

The build fails on WSL2 when building from /mnt/c
/mnt/c下进行构建,在WSL 2上构建失败。

The Yocto build requires a case-sensitive file system. By default WSL2 mounts of the C: drive found in /mnt/c is not. This leads to the following error:
Yocto版本构建需要区分大小写的文件系统。 然而缺省情况下,在/mnt/c下找到的WSL 2所挂载的C:盘则不是。这将产生以下错误:

pokyuser@868531cb885f:/mnt/c/work/astra/sdk/build-sl1680$ bitbake astra-media
WARNING: You are running bitbake under WSLv2, this works properly but you should optimize your VHDX file eventually to avoid running out of storage space
ERROR:  OE-core's config sanity checker detected a potential misconfiguration.
    Either fix the cause of this error or at your own risk disable the checker (see sanity.conf).
    Following is the list of potential problems / advisories:
The TMPDIR (/mnt/c/work/astra/sdk/build-sl1680/tmp) can't be on a case-insensitive file system.

To solve this problem, either setup the build in the WSL2 home directory (i.e. cd ~) or enable case-sensitive on the main Windows file system with the following command in an admin PowerShell:
若要解决此问题,请把构建放在WSL 2主目录(如cd ~)下进行,或者在admin PowerShell中使用以下命令,打开主Windows文件系统的大小写区分功能:

PS C:> fsutil.exe file SetCaseSensitiveInfo C:\work\astra\sdk

Where C:\work\astra\sdk\ is the directory containing the sdk repository clone.
其中 C:\work\astra\sdk\ 是sdk代码仓库克隆所在的目录。

WSL2 is not working correctly on my Windows machine
在我的Windows计算机上WSL 2无法正常工作

You may try the following things to reset the state on your machine:
您可以尝试以下操作来复位机器状态:

  1. Enable the Windows Subsystem for Linux:在Linux上启用Windows子系统:

    PS C:\Users\username> dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
    
  2. Enable Virtual Machine feature:启用虚拟机功能:

    PS C:\Users\username> dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart
    
  3. Restart your PC重新启动您的电脑。

  4. Download the Linux kernel update package and install it
    下载并安装Linux内核更新包 Linux kernel update package

  5. Set WSL 2 as default version:将WSL 2设置为默认版本:

    PS C:\Users\username> wsl --set-default-version 2
    
  6. Install Ubuntu 22.04 LTS from Microsoft Store
    Microsoft Store 安装Ubuntu 22.04 LTS。

  7. Set default distro to Ubuntu-22.04:将默认发行版设为Ubuntu—22.04:

    PS C:\Users\username> wsl --set-default Ubuntu-22.04