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

Zephyr Board 配置指南

1 概述

Zephyr使用Board的概念将各个板级硬件区分开，于是我们可以使用不同的board来编译不同的App工程；这种特性为实际项目提供了某种灵活性：如果App代码架构规划合理，将有办法使其很容易在不同board甚至SoC之间进行移植，缩短后续的开发周期。

Zephyr默认的board存放目录为zephyr\boards，而对于PAN1080来说，其支持的boards目录为zephyr\boards\arm。目前SDK中支持2种PAN1080 EVB Board：

  1. pan1080a_afx_evb：子板主控型号为PAN1080UB1（QFN封装、1MiB Flash Size、32 Pin）

  2. pan1080a_afld_evb：子板主控型号为PAN1080LB5（LQFP封装、1MiB Flash Size、64 Pin）

2 PAN1080 Evaluation Board

下面以pan1080a_afld_evb board为例，介绍相关文件含义。

pan1080a_afld_evb目录树如下：

<home>/01_SDK/zephyr/boards/arm/pan1080a_afld_evb
├─board.cmake
├─Kconfig.board
├─Kconfig.defconfig
├─pan1080a_afld_evb.dts
├─pan1080a_afld_evb.yaml
└─pan1080a_afld_evb_defconfig

其中：

  • board.cmake：板级CMake配置；

  • Kconfig.board：板级Kconfig定义；

  • Kconfig.defconfig：板级Kconfig默认值，配置后在Menuconfig中可修改；

  • pan1080a_afld_evb.dts：板级Devicetree定义；

  • pan1080a_afld_evb.yaml：板级测试相关信息（用于zephyr自动化单元测试系统）；

  • pan1080a_afld_evb_defconfig：板级Kconfig默认值，配置后在Menuconfig中不可修改；

2.1 board.cmake

board.cmake文件用于描述当前板级的cmake信息，目前主要是配置了jlink相关参数，供JLink烧录和调试的时候调用：

# SPDX-License-Identifier: Apache-2.0

board_runner_args(jlink "--device=PN108D" "--speed=2000")

include(${ZEPHYR_BASE}/boards/common/openocd.board.cmake)
include(${ZEPHYR_BASE}/boards/common/jlink.board.cmake)

注：此文件非必要请不要修改，唯一可考虑修改的参数为"--speed=2000"，可以根据实际情况修改JLink通信速率。

2.2 Kconfig.board

Kconfig.board文件用于描述当前板级的Kconfig定义，目前主要定义了当前EVB板的名称为BOARD_PAN1080A_AFLD_EVB，并通过一系列select关键字，使能了PAN1080 HAL层的各个底层Driver：

# PAN1080A-AFLD EVB MCU configuration

# Copyright (c) 2020-2022 Shanghai Panchip Microelectronics Co.,Ltd.
# SPDX-License-Identifier: Apache-2.0

config BOARD_PAN1080A_AFLD_EVB
	bool "PAN1080-AFLD Evaluation Board"
	depends on SOC_PAN1080A_AFLD
	select USE_PANPLAT_ACC
	select USE_PANPLAT_ADC
	select USE_PANPLAT_CLKTRIM
	select USE_PANPLAT_DMAC
	select USE_PANPLAT_FMC
	select USE_PANPLAT_GPIO
	select USE_PANPLAT_I2C
	select USE_PANPLAT_I2S
	select USE_PANPLAT_KSCAN
	select USE_PANPLAT_LOWPOWER
	select USE_PANPLAT_PWM
	select USE_PANPLAT_PRF
	select USE_PANPLAT_QDEC
	select USE_PANPLAT_SPI
	select USE_PANPLAT_TIMER
	select USE_PANPLAT_UART
	select USE_PANPLAT_USB
	select USE_PANPLAT_WDT
	select USE_PANPLAT_WWDT

注：此文件非必要请不要修改，但如果希望新增一些板级Kconfig定义，则直接在文件结尾新增定义即可。

2.3 Kconfig.defconfig

Kconfig.defconfig文件用于描述当前板级的默认值，并且此处配置的默认值是非强制的；换句话说，即使在此处配置了默认值，后续仍然可以在Menuconfig中或者App工程目录的prj.conf文件中进行强制修改：

# PAN1080A-AFLD EVB MCU configuration

# Copyright (c) 2020-2022 Shanghai Panchip Microelectronics Co.,Ltd.
# SPDX-License-Identifier: Apache-2.0

if BOARD_PAN1080A_AFLD_EVB

config BOARD
	default "pan1080a_afld_evb"

# BT_CTLR depends on BT. When BT is enabled we should default to also
# enabling the controller.
config BT_CTLR
	default y if BT

# Use Panchip BLE Link Layer instead of Zephyr's
choice BT_LL_CHOICE
	default BT_LL_PANCHIP if BT_CTLR
endchoice

if BT_LL_PANCHIP

config SOC_USE_CLOCK_XTAL_32M
	default y
config SOC_USE_DPLL_64M_CLK_REF_XTH
	default n
config SYS_CLOCK_HW_CYCLES_PER_SEC
	default 48000000
config SOC_USE_DPLL_48M_CLK_REF_XTH
	default y
config SOC_DCDC_PAN1080
	default n
config SOC_USE_MINIMAL_PERIPHERAL
	default n
config BT_HCI_TX_STACK_SIZE
	default 2048

endif # BT_LL_PANCHIP

# Change default Logging configurations
if LOG

config LOG_BUFFER_SIZE
	default 5120

config LOG_STRDUP_BUF_COUNT
	default 8

config LOG_DEFAULT_LEVEL
	default 3

endif # LOG

if USB_DEVICE_STACK

config USB_DEVICE_VID
	default 0x2FE4

config USB_DEVICE_PID
	default 0x0001

config USB_DEVICE_MANUFACTURER
	default "Panchip"

config USB_DEVICE_REMOTE_WAKEUP
	default n

endif # USB_DEVICE_STACK

# Increase ztest_thread_stack[] from default 1024 to 2048, since
# the default size is not enough, such as when test fcb_raw cases.
config ZTEST_STACKSIZE
	default 2048
	depends on ZTEST

endif # BOARD_PAN1080A_AFLD_EVB

注：此文件可以根据实际需要进行修改。

2.4 pan1080a_afld_evb.dts

pan1080a_afld_evb.dts文件用于描述当前板级的Devicetree定义：

/*
 * Copyright (c) 2020-2022 Shanghai Panchip Microelectronics Co.,Ltd.
 *
 * SPDX-License-Identifier: Apache-2.0
 */

/dts-v1/;
#include <mem.h>
#include <panchip/pan1080/pan1080a_afld.dtsi>

/ {
	model = "Panchip PAN1080A-AFLD Evaluation Board";
	compatible = "panchip,pan1080a-afld-evb", "panchip,pan1080a-afld";

	chosen {
		zephyr,console = &uart1;
		zephyr,shell-uart = &uart1;
		zephyr,bt-mon-uart = &uart1;
		zephyr,bt-c2h-uart = &uart1;
		zephyr,sram = &sram0;
		zephyr,flash = &flash0;
		zephyr,code-partition = &slot0_partition;
	};

	soc {
		pin-controller@40030000 {
			/* port, pin, pinmux_name, pinmux_sel [, flag1, ... ] */
			DT_PAN_PINS(p4, 3, uart0_rx, PAN1080_PIN_FUNC_P43_UART0_RX, input-enable);
			DT_PAN_PINS(p0, 7, uart1_rx, PAN1080_PIN_FUNC_P07_UART1_RX, input-enable);
			DT_PAN_PINS(p0, 4, qdec_x0, PAN1080_PIN_FUNC_P04_QDEC_X0, bias-pull-up, input-enable);
			DT_PAN_PINS(p0, 5, qdec_x1, PAN1080_PIN_FUNC_P05_QDEC_X1, bias-pull-up, input-enable);
			DT_PAN_PINS(p3, 1, spi0_miso, PAN1080_PIN_FUNC_P31_SPI0_MISO, input-enable);
			DT_PAN_PINS(p4, 0, i2c0_sda, PAN1080_PIN_FUNC_P40_I2C0_SDA, bias-pull-up, input-enable);
			DT_PAN_PINS(p4, 1, i2c0_scl, PAN1080_PIN_FUNC_P41_I2C0_SCL, bias-pull-up, input-enable);
		};
	};

	leds {
		compatible = "gpio-leds";
		led_red: led_r {
			gpios = <&p2 1 GPIO_ACTIVE_HIGH>;
			label = "LED_RED";
		};
	};

	pwmleds {
		compatible = "pwm-leds";
		pwm_led_red: pwm_led_r {
			pwms = <&pwm0 4 PWM_POLARITY_NORMAL>;
			label = "RGB_LED_RED";
		};
		pwm_led_green: pwm_led_g {
			pwms = <&pwm0 5 PWM_POLARITY_NORMAL>;
			label = "RGB_LED_GREEN";
		};
		pwm_led_blue: pwm_led_b {
			pwms = <&pwm0 6 PWM_POLARITY_NORMAL>;
			label = "RGB_LED_BLUE";
		};
	};

	buttons {
		compatible = "gpio-keys";
		key1: k1 {
			label = "KEY_1";
			gpios = <&p0 4 GPIO_ACTIVE_LOW>;
		};
		key2: k2 {
			label = "KEY_2";
			gpios = <&p0 5 GPIO_ACTIVE_LOW>;
		};
	};

	aliases {
		led0 = &led_red;
		sw0 = &key1;
		pwm-led0 = &pwm_led_red;
		pwm-led1 = &pwm_led_green;
		pwm-led2 = &pwm_led_blue;
		pwm-0 = &pwm0;
	};
};

&acc {
	status = "okay";
};

&p0 {
	status = "okay";
};

&p1 {
	status = "okay";
};

&p2 {
	status = "okay";
};

&p3 {
	status = "okay";
};

&p4 {
	status = "okay";
};

&p5 {
	status = "okay";
};

&uart0 {
	current-speed = <115200>;
	pinctrl-0 = <&p4_4_uart0_tx &p4_3_uart0_rx>;
	status = "okay";
};

&uart1 {
	current-speed = <921600>;
	pinctrl-0 = <&p0_6_uart1_tx &p0_7_uart1_rx>;
	status = "okay";
};

&timer0 {
	freq = <16000000>;
	status = "okay";
};

&timer1 {
	freq = <8000000>;
	status = "okay";
};

&timer2 {
	freq = <16000000>;
	status = "okay";
};

&pwm0 {
	pinctrl-0 = <&p1_0_pwm0_ch4 &p1_1_pwm0_ch5 &p1_6_pwm0_ch6>;
	status = "okay";
};

&adc {
	#io-channel-cells = <1>;
	status = "okay";
};

&qdec {
	event-threshold = <100>;
	polarity = "polarity-low";
	resolution = "cnt-resolution-1x";
	filter-threshold = "filter-threshold-3";
	pinctrl-0 = <&p0_4_qdec_x0 &p0_5_qdec_x1>;
	status = "okay";
};

&i2c0 {
	pinctrl-0 = <&p4_0_i2c0_sda &p4_1_i2c0_scl>;
	status = "okay";
};

&spi0 {
	pinctrl-0 = <&p3_0_spi0_mosi &p3_1_spi0_miso &p0_2_spi0_cs &p0_3_spi0_clk>;
	#address-cells = <1>;
	#size-cells = <0>;
	status = "okay";
};

&flash0 {
	partitions {
		compatible = "fixed-partitions";
		#address-cells = <1>;
		#size-cells = <1>;

		boot_partition: partition@0 {
			label = "mcuboot";
			reg = <0x00000000 0x00010000>;
			read-only;
		};
		slot0_partition: partition@10000 {
			label = "image-0";
			reg = <0x00010000 0x00060000>;
		};
		slot1_partition: partition@70000 {
			label = "image-1";
			reg = <0x00070000 0x00060000>;
		};
		scratch_partition: partition@D0000 {
			label = "image-scratch";
			reg = <0x000D0000 0x00020000>;
		};
		storage_partition: partition@f0000 {
			label = "storage";
			reg = < 0xf0000 0xF000 >;
		};
	};
};

注：此文件请谨慎修改，因为修改后可能会导致某些例程执行条件发生变化。如果某个App确实需要修改dts文件，则可以优先考虑通过DTS Overlay的方式进行修改，相关说明请参考Zephyr配置系统指南文档中的介绍。

2.5 pan1080a_afld_evb.yaml

pan1080a_afld_evb.yaml文件用于描述当前板级的测试环境相关信息，供zephyr自动化单元测试系统解析，以了解当前的板级硬件资源情况：

identifier: pan1080a_afld_evb
name: PAN1080A-AFLD Evaluation Board
type: mcu
arch: arm
toolchain:
  - zephyr
  - gnuarmemb
  - xtools
ram: 64
flash: 1020
supported:
  - adc
  - counter
  - gpio
  - pwm
  - serial

注：仅供Zephyr自动化单元测试系统使用，一般实际项目中可以不用关心此文件。

2.6 pan1080a_afld_evb_defconfig

pan1080a_afld_evb_defconfig文件用于配置当前板级的默认值，并且此处配置的默认值是强制的，注意这点与Kconfig.defconfig不同；换句话说，如果在此处配置了默认值，那么后续将无法在Menuconfig中或者App工程目录的prj.conf文件中再进行修改：

# SPDX-License-Identifier: Apache-2.0

# SoC Configuration
CONFIG_SOC_SERIES_PAN1080=y
CONFIG_SOC_PAN1080A_AFLD=y
# Board Configuration
CONFIG_BOARD_PAN1080A_AFLD_EVB=y

# Kernel Memory Options (Total SRAM 64KB)
CONFIG_MAIN_STACK_SIZE=1280
CONFIG_IDLE_STACK_SIZE=1024
CONFIG_ISR_STACK_SIZE=1024
# Prevent Interrupt Vector Table in RAM
CONFIG_IS_BOOTLOADER=y

# Serial Drivers
CONFIG_SERIAL=y
CONFIG_UART_INTERRUPT_DRIVEN=y
# enable console
CONFIG_CONSOLE=y
CONFIG_UART_CONSOLE=y

# Pinmux Driver
CONFIG_PINMUX=y
# GPIO Controller
CONFIG_GPIO=y
# Clock configuration
CONFIG_CLOCK_CONTROL=n

# Use XTH as system clock
CONFIG_SOC_USE_CLOCK_XTAL_32M=y

# Enable stack sentinel feature to make it easy to find issue
# caused by stack overflow
CONFIG_STACK_SENTINEL=y

# Set default BT log level to 4 (DBG)
# CONFIG_BT_LOG_LEVEL_DBG=y

CONFIG_SIZE_OPTIMIZATIONS=y

注：此文件可以根据实际需要进行修改。

3 创建一个自己的Board

3.1 为什么要创建自己的Board

由前面的介绍我们知道，SDK中已经存在2个对应PAN1080 EVB的board，其中的DTS文件描述了EVB的板级硬件资源以及各板级硬件模块之间的连接关系，Kconfig文件中则配置了能保证各个例程均能正确运行所需要开启的Zephyr功能。

而然，对于一个实际项目来说，一定有单独的板级硬件，其中的硬件资源可能与EVB上的完全不同了，并且使用过程中所需的板级Kconfig配置也大概率会与EVB不同，因此，为自己的项目重新创建一个zephyr board是一个必要且合理的选择。

3.2 如何创建Board

创建Board最简单的方法是从当前已有的模板中修改，方法如下（假设新的board硬件主控SoC型号与pan1080a_afld_evb相同，也为PAN1080LB5，并将新的board命名为my_custom_board）：

  1. 将zephyr\boards\arm路径下的pan1080a_afld_evb目录整体拷贝一份，并重新命名为my_custom_board；

  2. 进入my_custom_board子目录：

    1. 将pan1080a_afld_evb.yaml文件删除；

    2. 分别将pan1080a_afld_evb.dts和pan1080a_afld_evb_defconfig文件重命名为my_custom_board.dts和my_custom_board_defconfig；

    3. 打开Kconfig.board文件，将其中的Kconfig定义修改为：

      config BOARD_MY_CUSTOM_BOARD
	bool "My Custom Board"

    4. 打开Kconfig.defconfig文件，将其开头的if判断条件，以及BOARD默认值改为：

      if BOARD_MY_CUSTOM_BOARD

config BOARD
	default "my_custom_board"

...

endif # BOARD_MY_CUSTOM_BOARD

    5. 打开my_custom_board_defconfig文件，将当前的Board Configuration修改为新的board名称：

      ...

# Board Configuration
CONFIG_BOARD_MY_CUSTOM_BOARD=y

...

    6. 打开my_custom_board.dts文件，修改根节点下的model与compatible值，以与EVB作区分：

      ...

/ {
	model = "My custom Board";
	compatible = "vendor,my-custom-board", "panchip,pan1080a-afld";

...

  3. 至此，一个除名称不同外，各种配置完全与EVB相同的可用board就创建好了；这时候我们打开ZAL工具，在Board下拉菜单上可以看到新创建的board已经被成功识别：

    image

    使用ZAL工具识别新增的Board

  4. 我们选择这个新增的my_custom_board，编译synchronization例程：

    image

    使用新增的Board编译Synchronization例程

  5. 直接点击Flash按钮进行烧录，查看UART1串口Log，可以看到例程成功运行，并且board名称也已经与我们新修改的相同：

    image

    烧录新编译的Synchronization例程

注意：在实际项目中，仅仅将Board重命名是不够的，后续还应根据实际需要：

  1. 修改DTS文件中的其他部分，以符合实际的板级硬件情况；

  2. 修改Kconfig文件中的其他部分，以符合当前项目的实际需求；

4 更多相关文档

  1. Zephyr Board Porting Guide：Zephyr官方板级目录移植指南