Astra Yocto Linux开发人员指南

概述

本指南介绍在支持的Astra SOC和开发板上构建和使用Yocto镜像所需的特定配置和步骤。

本指南假设读者已经对 Yocto的概念有所熟悉。有关Yocto的介绍材料和通用的Yocto参考指南，请参考官方的 Yocto文档。

此BSP与Yocto Kirkstone版本配套使用，并为以下机器、发行版和镜像提供支持：

已支持的机器、发行版和镜像
机器	发行版	镜像
SL1620	poky	astra-media
SL1640	poky	astra-media
SL1680	poky	astra-media

构建主机要求

推荐的硬件是 x86_64 主机，至少具有：

16 核

32 GB RAM

150 GB磁盘

例如，在符合上述要求的 c5a.4xlarge AWS实例上，从零开始构建 vs640 的 astra-media 镜像，大约需要2小时。

Yocto构建系统可以非常有效地利用更多可用的内核。

备注

Yocto构建系统不支持完全从NFS装载的目录构建。更多详细信息，请参阅关于TMPDIR变量的Yocto文档。

推荐的软件配置如下：

Ubuntu 22.04 LTS

由标准的Ubuntu包 docker.io 提供的Docker 20.10或更高版本

其他版本的Linux和Docker也可以使用，但可能需要特殊配置。您可以在 Docker安装中找到更多关于如何在Ubuntu中安装Docker的信息。

众所周知，Astra SDK也可在安装于Windows 11上的Windows Subsystem For Linux（WSL）2.0中的Ubuntu 22.04上运行。您可以在 WSL2安装（仅在使用Windows时需要）中找到关于如何安装WSL2的更多信息。

如果Yocto构建的所有依赖项均已安装，则构建也可直接在Linux主机上执行。当前不支持此配置。

WSL2安装（仅在使用Windows时需要）

备注

如果您曾在您的机器安装过WSL 1，安装过另一个WSL2发行版或禁用了Hyper-v支持，则可能需要执行一些额外的步骤。关于建议的步骤，请参见故障排除章节。

首先在PowerShell中使用以下命令安装Windows Subsystem for Linux（作为管理员）

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

此命令将安装WSL和本文撰写时的默认版本Ubuntu 22.04。您可以在 WSL网站上找到有关安装过程的更多详细信息。

默认情况下，WSL仅使用主机RAM的50%，这可能达不到构建镜像所需的内存。如果是这种情况，您可以在您的用户目录（通常为 C:\Users\<Username ）下的文件 .wslconfig 中添加以下内容来增加内存：

[wsl2]
memory=24GB

然后需要在powershell中让改动生效，请运行命令：

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

您可以在这里找到有关WSL配置的更多信息。

一旦安装了WSL2环境，您可以从开始菜单中启动终端，方法是选择Windows Terminal App，然后选择Ubuntu-22.04发行版。

进入终端后，您可以按照 Docker安装中的说明安装Docker。

Docker安装

要安装Docker，请使用以下步骤：

安装docker包：

    $ sudo apt install docker.io

将当前用户添加到docker组，以便它能够使用docker：

    $ sudo adduser ${USER} docker

在重新启动之前，用户的改动不会自动生效（在某些情况下，登录就足够了）。要让改动在当前shell中生效，您还可运行以下命令：

    $ newgrp docker
    $ newgrp ${USER}

如何构建镜像

启动构建环境

备注

以下步骤需要一个正确安装了docker的主机，你可以在构建主机要求中找到关于如何设置docker的更多信息。

警告

不支持在 /mnt/c 以及其他主机文件系统驱动上使用WSL2构建。您的构建文件夹必须位于本机WSL2文件系统上（例如 /home/${USER} ）

为了确保正确配置和干净的环境，必须在Docker容器中执行构建。为此，您需要启动一个新的临时容器来承载该构建。当构建完成时，可以终止容器，稍后可以启动新容器以使用相同的命令进行重建。

要启动容器，请使用以下命令行：

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

这将在容器内生成一个shell。主机的当前目录挂载在容器内，以便该工作空间在容器内可用。

备注

在Ubuntu 20和18 LTS上，创建构建容器时，必须禁用docker的seccomp保护功能，方法是在上面的命令行中的 --rm 参数之后添加参数 --security-opt "seccomp=unconfined" 。

备注

Astra在如果您的环境需要代理连接到互联网，请按照以下说明配置Docker守护进程和配置Docker客户端以使用代理服务器。

备注

Astra在 ghcr.io/synaptics-astra/crops 中提供了一个预构建的容器，当您运行上面的命令时，该容器会自动下载，但您也可以从这里。提供的源代码进行编译。

获取源码

Astra Yocto发行版的源代码可通过克隆 top level git repo 来下载。代码仓库包含作为子模块的所有必需层。

要在根据启动构建环境说明所生成的构建环境中克隆代码仓库，请使用以下命令：

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

包含在 meta-synaptics 层中的recipes指向相关的git代码仓库，并可通过Yocto的标准Bitbake获取机制来下载。

构建镜像

要构建镜像，请执行以下命令：

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

生成的镜像可以在 build-${MACHINE}/tmp/deploy/images/${MACHINE}/SYNAIMG/ 中找到。

备注

这个样例构建了 astra-media 镜像。要构建不同的镜像，请将 astra-media 替换成您想要构建的镜像。有关 Astra Yocto 支持的其他镜像的详细信息，请参阅 Astra Yocto 镜像。

要构建 astra-media-oobe 镜像，请执行以下命令：

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

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

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

可以将镜像刷新到开发套件板，如更新固件中所述。

刷新主板后，请参阅 Linux操作系统登录来登录主板。

如何开发应用程序

Yocto项目的一个关键特性是能够创建一个独立SDK，包含为给定的目标的镜像开发和测试应用程序的一切所需。

独立工具链是一组预编译好的工具、库和头文件，与您的Yocto Project构建的配置相匹配。它提供了一个密切反映目标系统的一致的、可控的开发环境，以确保您开发的应用程序与您在嵌入式设备上部署的特定镜像兼容。

使用该独立的工具链，您可以在开发机器上完成编译后将它们部署到目标设备。这可以极大地加快开发过程，因为当您对某处改动进行测试时，无需每次都编译整个镜像。

GitHub 上也为默认Astra开发套件镜像提供了预编译好的工具链。。

获得该工具链后，您可以将其安装在开发机器上。该工具链含有一个脚本用于设置使用那些工具所需的环境变量。开发机器中推荐的和支持的配置与构建主机要求中描述的一致，而该工具链是与多种环境相兼容的。

要安装该工具链，首先要按如下方式解压缩：

$ chmod 755 poky-glibc-x86_64-astra-media-cortexa73-sl1680-toolchain-4.0.17.sh
$ ./poky-glibc-x86_64-astra-media-cortexa73-sl1680-toolchain-4.0.17.sh
Poky (Yocto Project Reference Distro) SDK installer version 4.0.17
==================================================================
Enter target directory for SDK (default: /opt/poky/4.0.17): 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-cortexa73-poky-linux

备注

该工具链环境文件的确切名称取决于目标板： sl1680 的 CPUTYPE 是 cortexa73 ，而 sl1620 和 sl1640 的则是 cortexa55 。

然后，要配置构建环境，您需要按如下方式获取配置脚本：

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

通过环境设置，您可以使用提供的交叉编译器来编译应用程序。该工具链还包括镜像中包含的各种组件的库和头文件，因此您可以充分利用这些组件来开发应用。您可以使用脚本（如 CC ）设置的环境变量来调用交叉编译器并用它构建应用程序。

有关该独立工具链的更多信息，请参见 Yocto documentation 。

如何重新构建独立的工具链

通过运行以下命令，您可以在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

构建过程将在目录 build-${MACHINE}/tmp/deploy/sdk 中生成工具链。

兼容层

此BSP与以下层兼容：

poky [分支： kirkstone ]

meta-openembedded [分支： kirkstone ]

meta-oe （下面的 meta-python 所须）

meta-python （下面的 meta-multimedia 所须）

meta-multimedia （可选-用于支持 gstreamer）

meta-qt [分支 qt/upstream/kirkstone ]（可选）

meta-swupdate (可选 - 用于支持 OTA )

meta-browser (可选- 用于支持 Chromium )

meta-clang (可选 - 用于支持 Chromium )

meta-ros (可选 - 用于支持 Robot Operating System )

meta-virtualization (可选 - 用于支持 container )

Astra Yocto 镜像

Astra Yocto版本包含多个镜像，提供不同级别的功能.

镜像

描述

已添加版本

astra-tiny

用于构建适合从32MB SPI NOR闪存启动的映像的最小软件包。

v1.5

astra-core

用于电源管理测试的核心系统包。

v1.2

astra-media

默认镜像，其中包含核心包以及支持完整多媒体功能的完整包。

v0.9

astra-media-oobe

包含 astra-media 中的所有软件包，以及 Chromium、Docker、开发工具和其他演示应用程序。

v1.5

astra-media 镜像可以用作开发自定义发行版的起点。它包含创建功能齐全的系统所需的所有包。而 astra-media-oobe 则还包含可用于展示 Astra 开发套件功能的其他软件包。

astra-media 镜像, 基于 poky 发行版, 用 weston 提供了一个基本的图形系统，适用于测试 sl1620 、 sl1640 和 sl1680 的特性。

该镜像需要 conf/local.conf 中的一些特定配置才能正常工作。脚本 meta-synaptics/setup/setup-environment 可用于正确设置要自动构建的镜像。

有关这些配置的更多详细信息，请参阅 meta-synaptics/setup/conf/local.conf.sample 中示例 local.conf 的注释。

备注

构建 astra-media-oobe 镜像包括构建Chromium浏览器。这可能会增加几个小时的构建时间，并需要额外的存储空间。

Distro 功能

Astra Yocto支持可选的发行版功能，可在 local.conf 文件中启用，也可以通过将变量传递给脚本 setup-environment 来启用。

X11 显示服务器

在 Astra Yocto 上, Wayland 是默认的显示服务器。使用 X11 而不是 Wayland，需将变量 DISPLAY_SERVER 传递给脚本 setup-environment 。

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

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

备注

v1.5版本中添加了对使用 X11 的支持。旧版本不支持 X11。

面向对象的虚拟化

虚拟化用于在 OOBE 镜像上启用容器支持及启用 Docker。启用虚拟化和完全的OOBE支持需要将变量 OOBE 传递给脚本 setup-environment 。

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

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

备注

v1.5版本增加了对构建 OOBE 镜像和虚拟化的支持。旧版本不支持构建 OOBE 镜像或虚拟化。

配置

内核命令行

内核命令行由 linux-syna recipe的变量 CMDLINE 定义。

系统内存配置

通过更改 SYNA_SDK_CONFIG_FILE 变量指向的配置文件中的变量 CONFIG_PREBOOT_ 来执行系统内存配置。在 https://github.com/synaptics-astra/boot-preboot-prebuilts 上可找到这些可用配置。

分区表

分区表是配置在目录 product/${SYNA_SDK_CONFIG_NAME}/emmc.pt下的文件 emmc.pt里，可在 http://github.com/synaptics-astra/configs 上找到。 SYNA_SDK_CONFIG_NAME依赖于变量 MACHINE和 DISTRO_CONFIG。

您可以改写recipe syna-config-native 来客制化此文件。

一些分区是供存储在eMMC引导分区中的早期引导组件使用的。它们不能被删除，但可移动。早期的引导组件使用UDA中的GPT定位这些分区。不支持从其他硬件分区加载。

常见问题

如何改写 local.conf 中的 recipe 变量？

要将文本 some text 追加到 recipe bar 里的变量FOO中，可在文件 local.conf 中添加如下这行：

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

  可以使用 Bitbake Guide 中描述的标准操作符来执行对变量的其他更改。

故障排除

在 Ubuntu 20或18 上构建包 gdk-pixbuf-native 失败，错误信息为 Failed to close file descriptor for child process 。

此问题是由包构建系统与运行Docker的主机上的库 libseccomp 不兼容引起的。要解决此问题，请在运行docker的主机上更新库libseccomp2，或在创建docker构建环境时将参数 --security-opt "seccomp=unconfined 添加到docker命令行。

构建失败于打包 astra media 时，错误信息为 path mismatch. 。

向 astra-media 镜像添加新包时可能会出现此错误。对 astra-media 包进行清理，然后重新构建，将解决问题：
bitbake -c clean astra-media

使用Out-Of-Trees模块（ 如synasdk-synap-module ）构建包失败，错误信息为 Kernel configuration is invalid. 。

在某些情形下， recipe make-mod-scripts 的状态可能被损坏。要修复此问题，请用以下命令清理recipe：
bitbake -c cleansstate make-mod-scripts

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 。

请确保您的用户账号在 docker 组中：

    $ getent group docker
    docker:x:133:yourusername

并且您的当前会话已登录到 docker 组：

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

如要添加您的用户账号到 docker 组，请使用以下命令：

    $ sudo adduser yourusername docker

如要确保您的会话登录到 docker 组，请使用以下命令：

    $ newgrp docker

从 /mnt/c 进行构建时，在 WSL2 上构建失败。

Yocto版本的构建需要区分大小写的文件系统。然而缺省情况下，在 /mnt/c 下找到的WSL2所挂载的 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.

若要解决此问题，请把构建放在WSL2主目录（如 cd ~ ）下进行，或者在admin PowerShell中使用以下命令，打开主Windows文件系统的大小写区分功能：

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

其中 C:\work\astra\sdk\ 是sdk代码仓库克隆所在的目录。

WSL2 在我的Windows计算机上无法正常工作

您可以尝试以下操作来复位机器状态：

在Linux上启用Windows子系统：

      ps C:\Users\username> dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart

启用虚拟机功能：

      ps C:\Users\username> dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

重新启动您的电脑。

下载并安装Linux内核更新包 Linux kernel update package 。

将WSL2设置为默认版本：

      ps C:\Users\username> wsl --set-default-version 2

从 Microsoft Store 安装Ubuntu 22.04 LTS。

将默认发行版设为Ubuntu—22.04：

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