open-amp

本代码仓库是开放式异构多处理（OpenAMP）框架项目的所在地。OpenAMP 框架提供的软件组件，可支持异构多处理（AMP）系统的软件应用开发。该框架具备以下核心功能：

1. 提供生命周期管理和处理器间通信功能，用于管理远程计算资源及其关联的软件上下文。
2. 提供可独立使用的库，适用于 RTOS 和裸机软件环境。
3. 与上游 Linux remoteproc 和 rpmsg 组件兼容。
4. 支持以下 AMP 配置： a. Linux 主机/通用（裸机）远程 b. 通用（裸机）主机/Linux 远程
5. 代理基础架构及所提供的演示程序，展示了主机端代理能够处理来自裸机远程上下文的 printf、scanf、open、close、read、write 调用。

OpenAMP 源代码结构

|- lib/
|  |- virtio/     # virtio implementation
|  |- rpmsg/      # rpmsg implementation
|  |- remoteproc/ # remoteproc implementation
|  |- proxy/      # implement one processor access device on the
|  |              # other processor with file operations
|- apps/        # demonstration/testing applications
|  |- examples/ # Application samples using the OpenAMP framework.
|  |- machine/  # common files for machine can be shared by applications
|  |            # It is up to each app to decide whether to use these files.
|  |- system/   # common files for system can be shared by applications
|               # It is up to each app to decide whether to use these files.
|- cmake        # CMake files
|- script       # helper scripts (such as checkpatch) for contributors.

OpenAMP 库 libopen_amp 由 lib/ 目录下的以下子目录组成：

• virtio/
• rpmsg/
• remoteproc/
• proxy/

OpenAMP 的系统/机器支持已移至 libmetal，apps/ 目录下的 system/machine 层用于系统应用初始化和资源表定义。

OpenAMP 中使用的 libmetal API

以下是 OpenAMP 所使用的 libmetal API。如果您想为您的系统移植 OpenAMP，您需要在 libmetal 的 lib/system/<SYS> 目录中实现以下 libmetal API：

• alloc：用于内存分配与释放
• cache：用于缓存刷新与失效
• io：用于内存映射。OpenAMP 需要通过内存映射来访问 vrings 和预留内存（carved out memory）。
• irq：用于 IRQ 处理程序注册、IRQ 禁用/启用以及全局 IRQ 处理。
• mutex
• shmem（对于 RTOS，通常可以使用 lib/system/generic/ 中的实现）
• sleep：目前，OpenAMP 仅需要微秒级别的睡眠，因为当 OpenAMP 无法获取缓冲区发送消息时，会调用此函数进行睡眠，然后重试。
• time：用于时间戳
• init：用于 libmetal 初始化。
• atomic

在为您的系统移植 libmetal 时，请参考 lib/system/generic。

如果您使用的编译器不是 GNU gcc，请参考 lib/compiler/gcc/ 来为您的编译器移植 libmetal。目前，OpenAMP 需要 lib/compiler/gcc/atomic.h 中定义的原子操作。

OpenAMP 编译

OpenAMP 使用 CMake 进行库和演示应用程序的编译。OpenAMP 需要 libmetal 库。目前，在编译 OpenAMP 库之前，您需要单独下载并编译 libmetal 库。未来，我们将尝试把 libmetal 作为 OpenAMP 的子模块，以简化这一流程。

一些 CMake 选项允许用户根据其项目自定义 OpenAMP 库：

• WITH_PROXY（默认 OFF）：在库中包含代理支持。
• WITH_APPS（默认 OFF）：编译示例应用程序。
• WITH_PROXY_APPS（默认 OFF）：编译代理示例应用程序。
• WITH_VIRTIO_DRIVER（默认 ON）：启用 virtio 驱动程序编译。如果仅实现了远程模式（remote mode），此选项可设置为 OFF。
• WITH_VIRTIO_DEVICE（默认 ON）：启用 virtio 设备编译。如果仅实现了驱动模式（driver mode），此选项可设置为 OFF。
• WITH_VQ_RX_EMPTY_NOTIFY（默认 OFF）：选择通知模式。设置为 ON 时，仅在 RX 队列中不再有消息时进行通知。设置为 OFF 时，每释放一个 RX 缓冲区都会进行通知。
• WITH_STATIC_LIB（默认 ON）：编译静态库。
• WITH_SHARED_LIB（默认 ON）：编译共享库。
• WITH_ZEPHYR（默认 OFF）：将 open-amp 构建为 Zephyr 库。在 Zephyr 环境中，此选项是必需的。
• WITH_DCACHE_VRINGS（默认 OFF）：启用对 vrings 的数据缓存操作。
• WITH_DCACHE_BUFFERS（默认 OFF）：启用对缓冲区的 data cache 操作。
• WITH_DCACHE_RSC_TABLE（默认 OFF）：启用对资源表的 data cache 操作。
• WITH_DCACHE（默认 OFF）：启用所有缓存操作。设置为 ON 时，将启用对 vrings、缓冲区和资源表的缓存操作。
• RPMSG_BUFFER_SIZE（默认 512）：调整 RPMsg 缓冲区的大小。RPMsg 大小的默认值与 Linux 内核的硬编码值兼容。如果您的 AMP 配置是 Linux 内核主机搭配 OpenAMP 远程，则不得使用此选项。

为 Zephyr 编译 OpenAMP 的示例

Zephyr open-amp 代码库为 Zephyr 项目实现了 open-amp 库。它主要是本代码库的一个分支，并添加了一些用于集成到 Zephyr 项目的附加组件。 为 Zephyr 项目编译 OpenAMP 的标准方法是使用 Zephyr 构建环境。有关示例，请参考Zephyr OpenAMP 示例，有关构建过程，请参考Zephyr 文档。

为 Linux 进程间通信编译 OpenAMP 的示例：

• 在您的 Linux 主机上安装 libsysfs 开发包和 libhugetlbfs 开发包。

• 按以下步骤在主机上构建 libmetal 库：

  $ mkdir -p build-libmetal
  $ cd build-libmetal
  $ cmake <libmetal_source>
  $ make VERBOSE=1 DESTDIR=<libmetal_install> install
  

• 按以下步骤在主机上构建 OpenAMP 库：

  $ mkdir -p build-openamp
  $ cd build-openamp
  $ cmake <openamp_source> -DCMAKE_INCLUDE_PATH=<libmetal_built_include_dir> \
             -DCMAKE_LIBRARY_PATH=<libmetal_built_lib_dir> [-DWITH_APPS=ON]
  $ make VERBOSE=1 DESTDIR=$(pwd) install
  

OpenAMP 库将生成到 build/usr/local/lib 目录，头文件将生成到 build/usr/local/include 目录，应用程序可执行文件将生成到 build/usr/local/bin 目录。

• cmake 选项 -DWITH_APPS=ON 用于构建演示应用程序。

• 如果您使用 -DWITH_APPS=ON 构建了演示程序，可以按以下步骤在 Linux 主机上进行尝试：

  • rpmsg 回显演示：

  # 启动回显测试服务器以等待要回显的消息
  $ sudo LD_LIBRARY_PATH=<openamp_built>/usr/local/lib:<libmetal_built>/usr/local/lib \
     build/usr/local/bin/rpmsg-echo-shared
  # 运行回显测试以向回显测试服务器发送消息
  $ sudo LD_LIBRARY_PATH=<openamp_built>/usr/local/lib:<libmetal_built>/usr/local/lib \
     build/usr/local/bin/rpmsg-echo-ping-shared 1
  

  • 使用无复制 API 的 rpmsg 回显演示：

  # 启动回显测试服务器以等待要回显的消息
  $ sudo LD_LIBRARY_PATH=<openamp_built>/usr/local/lib:<libmetal_built>/usr/local/lib \
     build/usr/local/bin/rpmsg-nocopy-echo-shared
  # 运行回显测试以向回显测试服务器发送消息
  $ sudo LD_LIBRARY_PATH=<openamp_built>/usr/local/lib:<libmetal_built>/usr/local/lib \
     build/usr/local/bin/rpmsg-nocopy-ping-shared 1
  

编译 Zynq UltraScale+ MPSoC R5 通用（裸机）远程端示例：

• 按以下步骤在主机上构建 libmetal 库：

  • 创建 CMake 工具链文件，用于为通用（裸机）平台编译 libmetal。工具链文件示例如下：

  set (CMAKE_SYSTEM_PROCESSOR "arm"              CACHE STRING "")
  set (MACHINE "zynqmp_r5" CACHE STRING "")
  
  set (CROSS_PREFIX           "armr5-none-eabi-" CACHE STRING "")
  set (CMAKE_C_FLAGS          "-mfloat-abi=soft -mcpu=cortex-r5 -Wall -Werror -Wextra \
         -flto -Os -I/ws/xsdk/r5_0_bsp/psu_cortexr5_0/include" CACHE STRING "")
  
  SET(CMAKE_EXE_LINKER_FLAGS "${CMAKE_EXE_LINKER_FLAGS} -flto")
  SET(CMAKE_AR  "gcc-ar" CACHE STRING "")
  SET(CMAKE_C_ARCHIVE_CREATE "<CMAKE_AR> qcs <TARGET> <LINK_FLAGS> <OBJECTS>")
  SET(CMAKE_C_ARCHIVE_FINISH   true)
  
  include (cross-generic-gcc)
  

  • 编译 libmetal 库：

  $ mkdir -p build-libmetal
  $ cd build-libmetal
  $ cmake <libmetal_source> -DCMAKE_TOOLCHAIN_FILE=<toolchain_file>
  $ make VERBOSE=1 DESTDIR=<libmetal_install> install
  

• 按以下步骤在主机上构建 OpenAMP 库：

  • 创建 CMake 工具链文件，用于为通用（裸机）平台编译 openamp。工具链文件示例如下：

  set (CMAKE_SYSTEM_PROCESSOR "arm" CACHE STRING "")
  set (MACHINE                "zynqmp_r5" CACHE STRING "")
  set (CROSS_PREFIX           "armr5-none-eabi-" CACHE STRING "")
  set (CMAKE_C_FLAGS          "-mfloat-abi=soft -mcpu=cortex-r5 -Os -flto \
          -I/ws/libmetal-r5-generic/usr/local/include \
          -I/ws/xsdk/r5_0_bsp/psu_cortexr5_0/include" CACHE STRING "")
  set (CMAKE_ASM_FLAGS        "-mfloat-abi=soft -mcpu=cortex-r5" CACHE STRING "")
  set (PLATFORM_LIB_DEPS      "-lxil -lc -lm" CACHE STRING "")
  SET(CMAKE_EXE_LINKER_FLAGS "${CMAKE_EXE_LINKER_FLAGS} -flto")
  SET(CMAKE_AR  "gcc-ar" CACHE STRING "")
  SET(CMAKE_C_ARCHIVE_CREATE "<CMAKE_AR> qcs <TARGET> <LINK_FLAGS> <OBJECTS>")
  SET(CMAKE_C_ARCHIVE_FINISH   true)
  set (CMAKE_FIND_ROOT_PATH /ws/libmetal-r5-generic/usr/local/lib \
            /ws/xsdk/r5_bsp/psu_cortexr5_0/lib )
  
  include (cross_generic_gcc)
  

  • 我们使用 CMake 的 find_path 和 find_library 来检查 libmetal 头文件和库是否位于头文件搜索路径和库搜索路径中。但对于非 Linux 系统，CMAKE_INCLUDE_PATH 和 CMAKE_LIBRARY_PATH 变量无法正常工作，因此需要在工具链文件中通过 CMAKE_C_FLAGS 和 CMAKE_FIND_ROOT_PATH 指定这些路径。

• 编译 OpenAMP 库：

  $ mkdir -p build-openamp
  $ cd build-openamp
  $ cmake <openamp_source> -DCMAKE_TOOLCHAIN_FILE=<toolchain_file>
  $ make VERBOSE=1 DESTDIR=$(pwd) install
  

OpenAMP 库将生成在 build/usr/local/lib 目录，头文件将生成在 build/usr/local/include 目录，应用程序可执行文件将生成在 build/usr/local/bin 目录。

为 Zynq UltraScale+ MPSoC 编译 OpenAMP Linux 用户空间示例

我们可以使用 Yocto 构建 OpenAMP Linux 用户空间库和应用程序。 open-amp 和 libmetal 配方位于以下 Yocto 层中： https://github.com/OpenAMP/meta-openamp

• 将 meta-openamp 层添加到 Yocto 构建项目的 bblayers.conf 文件中的层列表。
• 将 libmetal 和 open-amp 添加到软件包列表。例如，在 local.conf 文件的 IMAGE_INSTALL_append 中添加 libmetal 和 open-amp。
• 您还可以将 OpenAMP 演示 Linux 应用程序软件包添加到 Yocto 软件包列表。OpenAMP 演示示例配方也位于 meta-openamp 中： https://github.com/OpenAMP/meta-openamp/tree/master/recipes-openamp/rpmsg-examples

为了在 Linux 用户空间中使用 OpenAMP(RPMsg)，您需要将 IPI 设备、vring 内存和共享缓冲区内存添加到 Linux 内核设备树中。设备树示例可在此处找到： https://github.com/OpenAMP/open-amp/blob/main/apps/machine/zynqmp/openamp-linux-userspace.dtsi

版本

OpenAMP 版本遵循 语义化版本规范 中提出的规则集。

支持的系统和机器

目前，它支持：

• Zynq 通用远程
• Zynq UltraScale+ MPSoC R5 通用远程
• Linux 主机上 Linux 用户空间进程间的 OpenAMP
• Linux 用户空间 OpenAMP RPMsg 主机
• Linux 用户空间 OpenAMP RPMsg 远程
• Linux 用户空间 OpenAMP RPMsg 和 MicroBlaze 裸机远程

已知限制：

1. 对于用于处理器间通信的 Linux 用户空间 OpenAMP，它仅支持静态 vrings 和共享缓冲区。
2. 在 Linux 进程间运行 OpenAMP 演示时需要 sudo，因为在某些系统上，普通用户无法正常运行。

如何贡献：

作为一个开源项目，我们欢迎并鼓励社区直接向项目提交补丁。作为贡献者，您应该熟悉常见的开发工具（如 Git 和 CMake）以及平台（如 GitHub）。 为了促进审查过程，应遵守以下几点。

许可协议

贡献给 Linux 内核的代码采用多种许可协议，但所有代码必须与 BSD 许可协议 兼容，该协议是涵盖整个 OpenAMP 发行版的许可协议。在实际应用中，请在各个文件中使用以下标记，而非完整的许可文本：

  SPDX-License-Identifier:    BSD-3-Clause
  SPDX-License-Identifier:    BSD-2-Clause

已签署（Signed-off-by）

提交信息必须包含“Signed-off-by:”行，且您的电子邮件必须与变更的作者信息匹配。请确保您的.gitconfig已正确配置：

  git config --global user.name "first-name Last-Namer"
  git config --global user.email "yourmail@company.com"

gitlint

在向项目提交拉取请求之前，请确认您的提交信息符合要求。 可使用 gitlint 命令在本地执行检查。

在已提交补丁的分支和代码树中，在本地运行 gitlint：

  gitlint

注意，gitlint 仅检查 HEAD（最新提交），因此你应在每次提交后运行它，或者使用 --commits 选项指定一个提交范围，涵盖所有要提交的开发补丁。

代码风格

总体上，遵循 Linux 内核编码风格，但有以下例外：

• 对于需要出现在文档中的 doxygen 注释，使用 /** */。

使用 Linux 内核 GPL 许可的工具 checkpatch 来检查代码风格的符合性。checkpatch 位于 scripts 目录中。

要检查你的 git 分支中的 <n> 个提交：

  ./scripts/checkpatch.pl --strict  -g HEAD-<n>

提交拉取请求

我们使用标准的 GitHub 拉取请求机制。如需帮助，请参考 GitHub 文档。

沟通与协作

订阅 OpenAMP 邮件列表（openamp-rp@lists.openampproject.org）。

有关该框架的更多详细信息，请参阅 OpenAMP 文档。