自定义板型开发指南

本文档提供创建自定义板型的完整指南，包括文件结构、接口规范、开发步骤和文件模板。

概述

创建自定义板型需要准备以下文件：

my_board/
├── CMakeLists.txt    # 板型构建脚本（必需）
├── board.h           # 板级接口声明（必需）
├── board.c           # 板级初始化实现（必需）
├── pinmux.h          # 引脚配置声明（必需）
├── pinmux.c          # 引脚配置实现（必需）
└── Kconfig           # 板型配置选项（必需）

开发步骤

Step 1: 创建板型目录

# 创建板型目录
mkdir -p /path/to/my_boards/my_board
cd /path/to/my_boards/my_board

Step 2: 创建 CMakeLists.txt

复制以下内容到 CMakeLists.txt：

# ARCS BOARD SUPPORT
#
# Copyright (c) 2025, LISTENAI
# SPDX-License-Identifier: Apache-2.0

# 创建板型库
listenai_library_named(module_boards)

# 添加源文件
listenai_library_sources(
    pinmux.c
    board.c
)

# 添加头文件路径
listenai_include_directories(${CMAKE_CURRENT_SOURCE_DIR})

Step 3: 创建 board.h 和 board.c

方法一：复制 SDK 内置板型作为起点

cp $ARCS_SDK_BASE/boards/arcs_evb/board.h .
cp $ARCS_SDK_BASE/boards/arcs_evb/board.c .

然后修改文件中的注释和 board_get_name() 返回值为您的板型名称。

方法二：使用下方的文件模板手动创建

参考本文档后面的”文件模板”章节。

Step 4: 使用 Pinmux 工具生成引脚配置

重要：pinmux.h 和 pinmux.c 必须使用工具生成，不应手动编辑。

工具信息

工具地址：https://tool.listenai.com/ls-pinmux-tool/
功能：根据芯片型号和外设配置，自动生成引脚复用代码

使用步骤

访问 Pinmux 配置工具
选择目标芯片型号
配置项目中使用的外设（如 UART0、SPI0、I2C0 等）
为每个外设配置引脚映射
生成代码
将生成的 pinmux.h 和 pinmux.c 保存到板型目录

设备驱动集成

生成的 pinmux 函数会被对应的设备驱动自动调用：

lisa_uart0_pinmux() - 由 lisa_uart 驱动的 uart0 设备初始化时调用
lisa_spi0_pinmux() - 由 lisa_spi 驱动的 spi0 设备初始化时调用
其他外设依此类推

注意事项：

不要手动编辑生成的文件
如需修改引脚配置，应在工具中修改后重新生成

Step 5: 创建 Kconfig 文件（必需）

创建 Kconfig 文件，必须包含以下两个配置项：

# Board Configuration
#
# Copyright (c) 2025, LISTENAI
# SPDX-License-Identifier: Apache-2.0

config BOARD_NAME
    string
    default "my_board"
    prompt "Board Name"
    help
        Board Name

config BOARD_MY_BOARD
    bool
    default y
    help
        Board is my_board

重要提示：

将 my_board 替换为您的实际板型名称
第二个配置项名称格式为 BOARD_<板型名称大写>
例如板型名为 arcs_evb，则配置项为 BOARD_arcs_evb

Kconfig 说明：

必需配置项 1：BOARD_NAME - 板型名称（string 类型）
必需配置项 2：BOARD_<BOARD_NAME_UPPER> - 板型标识（bool 类型，默认 y）
构建系统会自动加载此文件并设置环境变量 BOARD_KCONFIG_PATH
外部板型和 SDK 内置板型享有相同的配置能力

Step 6: 编译验证

cd $ARCS_SDK_BASE
./build.sh -S samples/helloworld \
    -DBOARD=my_board \
    -DBOARD_SEARCH_PATH=/path/to/my_boards

重要提示： 外部板型文件已通过编译变量指定构建路径，无需在工程中额外添加构建。

Step 7: 检查构建日志

确认看到板型加载信息：

-- Target board: my_board
-- Board found (custom): my_board from /path/to/my_boards
-- Board loaded successfully: /path/to/my_boards/my_board

接口规范

board.h / board.c - 标准接口

板型必须实现以下标准接口：

const char* board_get_name(void) - 返回板型名称字符串

pinmux.h / pinmux.c - 引脚复用配置

重要说明：这两个文件由 Pinmux 配置工具生成，不应手动编辑。

详见 Step 4 的说明。

文件模板

board.h 模板

可参考：boards/arcs_evb/board.h

// ARCS BOARD SUPPORT
//
// Copyright (c) 2025, LISTENAI
// SPDX-License-Identifier: Apache-2.0

#ifndef _BOARD_MY_BOARD_H_
#define _BOARD_MY_BOARD_H_

/**
 * @brief Get the board name
 *
 * @return const char* Board name string
 */
const char* board_get_name(void);

#endif // _BOARD_MY_BOARD_H_

board.c 模板

可参考：boards/arcs_evb/board.c

// ARCS BOARD SUPPORT
//
// Copyright (c) 2025, LISTENAI
// SPDX-License-Identifier: Apache-2.0

#include "board.h"

const char* board_get_name(void)
{
    return "my_board";
}

Kconfig 模板

可参考：boards/arcs_evb/Kconfig

# Board Configuration
#
# Copyright (c) 2025, LISTENAI
# SPDX-License-Identifier: Apache-2.0

config BOARD_NAME
    string
    default "my_board"
    prompt "Board Name"
    help
        Board Name

config BOARD_MY_BOARD
    bool
    default y
    help
        Board is my_board

注意： 请将模板中的 my_board 和 MY_BOARD 替换为您的实际板型名称。

常见问题

Q: 是否可以不创建 Kconfig 文件？

不可以。Kconfig 文件是必需的，必须包含 BOARD_NAME 和 BOARD_<名称大写> 两个配置项。

Q: 可以手动编辑 pinmux.c 吗？

不建议。pinmux.h 和 pinmux.c 应该由 Pinmux 配置工具生成。如果需要修改引脚配置，应在工具中重新配置并生成新文件。

Q: board.c 中还需要实现其他函数吗？

当前只需要实现 board_get_name() 函数。未来如果有更多板级初始化需求，可能会增加其他接口。