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实例上, 从零开始构建 vs640astra-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上运行。 您可以在 WSL 2安装(仅在使用Windows时需要) 中找到关于如何安装WSL 2的更多信息。

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

WSL 2安装(仅在使用Windows时需要)

备注

如果您曾在您的机器安装过WSL 1,安装过另一个WSL 2发行版或禁用了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配置的更多信息。

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

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

Docker安装

要安装Docker,请使用以下步骤:

  1. 安装docker包:

    $ sudo apt install docker.io
    
  2. 将当前用户添加到docker组,以便它能够使用docker:

    $ sudo adduser ${USER} docker
    
  3. 在重新启动之前,用户的改动不会自动生效(在某些情况下,登录就足够了)。要让改动在 当前shell中生效,您还可运行以下命令:

    $ newgrp docker
    $ newgrp ${USER}
    

如何构建映像

启动构建环境

备注

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

警告

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

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

要启动容器,请使用以下命令行:

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

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

备注

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

备注

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

获取源码

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

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

pokyuser@xyz:/path/to/workspace $ git clone -b v0.9.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 $ source meta-synaptics/setup/setup-environment
pokyuser@xyz:/path/to/workspace $ bitbake astra-media

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

可以将映像刷新到评估套件板, 如 更新固件 中所述。

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

如何开发应用程序

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

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

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

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

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

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

$ ./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

该工具链环境文件的确切名称取决于目标板: sl1680CPUTYPEcortexa73 , 而 sl1620sl1640 的则是 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 ](可选)

映像

astra-media

基于 poky 发行版的 astra-media 映像提供了一个带有 weston 的基本图形系统,适合测试 sl1640sl1680 的特性。

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

有关这些配置的更多细节,请参阅 meta-synaptics/setup/conf/local.conf.sample 中的示例 local.conf 的注解。

要在wayland上运行qt应用,还必须添加以下软件包 .即便用 setup/setup-environment ,也必须通过手动来启用:

DISTRO_EXTRA_RDEPENDS:append = " qtwayland"

配置

内核命令行

内核命令行由 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依赖于变量 MACHINEDISTRO_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命令行。

使用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 下进行构建,在WSL 2上构建失败。

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.

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

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

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

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

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

  1. 在Linux上启用Windows子系统:

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

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

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

  5. 将WSL 2设置为默认版本:

    ps C:\Users\username> wsl --set-default-version 2
    
  1. Microsoft Store 安装Ubuntu 22.04 LTS。

  2. 将默认发行版设为Ubuntu—22.04:

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