Zephyr Board 配置指南¶
1 概述¶
Zephyr使用Board的概念将各个板级硬件区分开,于是我们可以使用不同的board来编译不同的App工程;这种特性为实际项目提供了某种灵活性:如果App代码架构规划合理,将有办法使其很容易在不同board甚至SoC之间进行移植,缩短后续的开发周期。
Zephyr默认的board存放目录为zephyr\boards
,而对于PAN1080来说,其支持的boards目录为zephyr\boards\arm
。目前SDK中支持2种PAN1080 EVB Board:
pan1080a_afx_evb
:子板主控型号为PAN1080UB1
(QFN封装、1MiB Flash Size、32 Pin)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
):
将
zephyr\boards\arm
路径下的pan1080a_afld_evb
目录整体拷贝一份,并重新命名为my_custom_board
;进入
my_custom_board
子目录:将
pan1080a_afld_evb.yaml
文件删除;分别将
pan1080a_afld_evb.dts
和pan1080a_afld_evb_defconfig
文件重命名为my_custom_board.dts
和my_custom_board_defconfig
;打开
Kconfig.board
文件,将其中的Kconfig定义修改为:config BOARD_MY_CUSTOM_BOARD bool "My Custom Board"
打开
Kconfig.defconfig
文件,将其开头的if判断条件,以及BOARD默认值改为:if BOARD_MY_CUSTOM_BOARD config BOARD default "my_custom_board" ... endif # BOARD_MY_CUSTOM_BOARD
打开
my_custom_board_defconfig
文件,将当前的Board Configuration修改为新的board名称:... # Board Configuration CONFIG_BOARD_MY_CUSTOM_BOARD=y ...
打开
my_custom_board.dts
文件,修改根节点下的model
与compatible
值,以与EVB作区分:... / { model = "My custom Board"; compatible = "vendor,my-custom-board", "panchip,pan1080a-afld"; ...
至此,一个除名称不同外,各种配置完全与EVB相同的可用board就创建好了;这时候我们打开
ZAL
工具,在Board下拉菜单上可以看到新创建的board已经被成功识别:我们选择这个新增的
my_custom_board
,编译synchronization例程:直接点击
Flash
按钮进行烧录,查看UART1串口Log,可以看到例程成功运行,并且board名称也已经与我们新修改的相同:
注意:在实际项目中,仅仅将Board重命名是不够的,后续还应根据实际需要:
修改DTS文件中的其他部分,以符合实际的板级硬件情况;
修改Kconfig文件中的其他部分,以符合当前项目的实际需求;
4 更多相关文档¶
Zephyr Board Porting Guide:Zephyr官方板级目录移植指南