当前文档版本为v0.3.0，您可以访问开发中的文档以获取最近可能的更新。

SoC App 开发指南¶

本文介绍 PAN1080 SDK APP 开发的基础知识。

1 概述¶

PAN1080 SDK 基于 Zephyr OS 开发，其构建系统（Build System）使用 CMake。

01_SDK/zephyr目录下存放有 Zephyr OS 的核心代码、内核配置信息、SoC定义、开发板定义以及Panchip提供的例程等。

从文件结构上来说，构建系统允许我们将自己的APP工程创建在任意目录下；只要配置正确，构建系统可以在编译APP工程的时候，自动识别到 SDK 中 Zephyr 的路径。

一个最简单的 APP 工程文件结构如下所示：

   <work_dir>/my_app
   ├── CMakeLists.txt
   ├── prj.conf
   └── src
       └── main.c

其中：

CMakeLists.txt: 构建系统从此文件中查找待编译 APP 源码，并将 APP 目录与 Zephyr 链接起来，使得 APP 可以编译、配置、使用 Zephyr 提供的各种功能。
配置文件: APP 需要提供一个 Kconfig 配置文件（通常称为prj.conf），其中包含一个或多个 Zephyr 内核配置信息，这些配置与特定的芯片（SoC）配置、特定的开发板（Board）配置等配置信息合并，生成最终的配置文件（.config文件与autoconf.h文件）。
APP 源码文件: APP 需要包含一个或多个C语言或汇编源码文件，这些文件通常位于名为src的目录下。

APP 工程创建后，我们即可以使用west build 命令触发编译操作（其内部是调用 CMake ），编译过程中会自动生成单独的Build（构建）目录，其中存放编译输出的所有文件。

下面介绍如何创建、构建和运行一个自定义的 APP。

2 Zephyr 目录结构¶

Zephyr 的核心代码位于01_SDK/zephyr目录下，其中包含一些重要的文件：
- CMakeLists.txt：CMake 构建系统的顶层文件，包含构建 Zephyr 核心代码所需的 CMake 信息。
- Kconfig：Kconfig 顶层文件，其直接引用另一个顶层文件Kconfig.zephyr。
- west.yml：west manifest 文件，其中列出了 west 工具能够识别和管理的外部模块目录。
Zephyr 的核心代码还包括如下这些顶层目录（每个顶层目录下还包括一个或多个子目录）：
- arch：存放芯片 CPU 架构级信息，由于 PAN1080 是 ARM 架构，因此其中只保留了 ARM 架构信息。
- soc：存放芯片 SoC 级信息及一些默认配置。
- boards：存放板级信息，比如 PAN1080 各种 EVB 开发板。
- doc：Zephyr 官方文档，其内容与 Zephyr文档官网一致。
- drivers：存放设备驱动代码。
- dts：存放 DeviceTree（芯片硬件初始化配置）信息。
- include：存放 Zephyr 公开的 API 头文件。
- kernel：存放 Zephyr OS 内核代码。
- lib：存放库文件，包含一个简单的标准C语言库等。
- misc：其他一些不便分类的文件。
- samples_panchip：存放 Panchip 提供的 PAN1080 官方例程。
- scripts：存放编译测试相关的脚本文件。
- cmake：存放 CMake 构建 Zephyr App 所需的相关配置和脚本文件。
- subsys：Zephyr 子系统，包括：USB Device Stack（USB 设备栈）、File System（文件系统）、Bluetooth Host and Controller（低功耗蓝牙Host端与Controller端）等实现代码。
- share：存放一些额外的架构无关的数据，目前包含 Zephyr CMake Package。

3 创建一个 APP 工程¶

创建一个 APP 最简单的方式，是从 01_SDK/zephyr/samples_panchip 目录下，Copy一个例程，并将其中的非必要文件（如README.rst和sample.yaml）删除即可。

下面介绍如何重新创建一个 APP 工程。

在合适的位置创建一个空目录，作为 APP 工程目录（此处以存放在 PAN1080 Development Kit 同级目录下为例）：

虽然 SDK 中的所有例程APP均存放在zephpyr/sample_panchip子目录下，但实际上，zephyr的构建系统支持将 APP 工程创建在任意不包含中文和空格的路径下。
将 APP 程序源码，存放在其中的src子目录下，此处假设我们创建了一个名为main.c的源文件。
在my_app目录中创建一个CMakeLists.txt文件，其内容如下：
```
   # Find Zephyr. This also loads Zephyr's build system.
   cmake_minimum_required(VERSION 3.20.0)
   find_package(Zephyr)
   project(my_app)

   # Add your source file to the "app" target. This must come after
   # find_package(Zephyr) which defines the target.
   target_sources(app PRIVATE src/main.c)
```
其中：
- cmake_minimum_required指定了CMake的最低版本需求；
- find_package(Zephyr)表示 APP 会与 Zephyr 一起编译；
- project(my_app)指定了当前APP工程的名称；
- target_sources(app PRIVATE src/main.c)表示将APP工程src子目录下的main.c文件加入构建系统参与编译；
增加一个名为prj.conf的文件，用于配置Kconfig选项；

例如，我们想在 APP 中使用 Zephyr 的 GPIO Driver，则在其中填入：
```
CONFIG_GPIO=y
```
又如，我们想开启C++支持，则在其中填入：
```
CONFIG_CPLUSPLUS=y
```
（可选）如果需要配置额外的 DeviceTree 信息，还可以在 APP 目录下增加 Overlay 文件，以覆盖默认的配置。

关于 Devicetree Overlay 的更多信息，请参考 Zephyr 官方文档：如何配置 DeviceTree Overlay。
创建完成后的目录结构如图所示：
APP 基础框架创建完成后，即可使用 west 工具进行编译：
- 打开 PAN1080 SDK CLI（位于01_SDK目录下），输入如下命令：
```
west build -d ../../my_app_build_pan1080a_afld -b pan1080a_afld_evb ../../my_app
```
- 编译成功：
编译完成，可以继续执行烧录和调试，方法请参考SDK 开发环境介绍