218 lines
5.4 KiB
ReStructuredText
218 lines
5.4 KiB
ReStructuredText
.. _getting_started:
|
||
|
||
================
|
||
快速入门
|
||
================
|
||
|
||
本文档介绍如何快速开始使用 ARCS SDK 进行开发，包括环境搭建、编译示例和烧录运行。
|
||
|
||
.. note::
|
||
目前仅支持 Linux 平台，推荐使用 Ubuntu 18.04 以上版本。
|
||
|
||
.. _environment_setup:
|
||
|
||
环境搭建
|
||
========
|
||
|
||
自动搭建（推荐）
|
||
----------------
|
||
|
||
1. **下载开发工具包**
|
||
|
||
在 SDK 根目录下运行脚本：
|
||
|
||
.. code-block:: shell
|
||
|
||
./prepare_listenai_tools.sh
|
||
|
||
2. **下载工具链**
|
||
|
||
运行脚本下载工具链：
|
||
|
||
.. code-block:: shell
|
||
|
||
./prepare_toolchain.sh
|
||
|
||
3. **设置环境变量**
|
||
|
||
.. code-block:: shell
|
||
|
||
# 设置工具链路径
|
||
export NUCLEI_TOOLCHAIN_PATH=/path/to/toolchain
|
||
|
||
# 设置 ListenAI 工具包路径
|
||
export LISTENAI_TOOLS_PATH=/path/to/listenai-tools
|
||
|
||
.. warning::
|
||
**必须使用绝对路径！** 环境变量的路径必须是绝对路径（如 ``/home/user/toolchain``），不能使用相对路径（如 ``./toolchain`` 或 ``../toolchain``），否则会导致编译失败。
|
||
|
||
其中：
|
||
|
||
- ``NUCLEI_TOOLCHAIN_PATH`` 指向解压后的工具链路径（绝对路径）
|
||
- ``LISTENAI_TOOLS_PATH`` 指向解压后的 ListenAI 工具包路径（绝对路径）
|
||
|
||
手动搭建
|
||
--------
|
||
|
||
如果自动搭建失败，可以手动搭建开发环境：
|
||
|
||
1. **下载工具链**
|
||
|
||
下载对应平台的工具链并解压（如果已存在工具链，可跳过此步骤）：
|
||
|
||
- `Linux 工具链下载地址 <http://listenai-firmware-delivery.oss-cn-beijing.aliyuncs.com/ARCS/tools/toolchain/linux-amd64/nuclei_riscv_newlibc_prebuilt_linux64_2025.02.tar.bz2>`_
|
||
|
||
2. **下载 ListenAI 开发工具包**
|
||
|
||
- `Linux 开发工具包下载地址 <http://listenai-firmware-delivery.oss-cn-beijing.aliyuncs.com/ARCS/tools/dev-tools/linux-amd64/v0.0.1/listenai-tools.tar.gz>`_
|
||
|
||
3. **设置环境变量**
|
||
|
||
.. code-block:: shell
|
||
|
||
# 设置工具链路径
|
||
export NUCLEI_TOOLCHAIN_PATH=/path/to/toolchain
|
||
|
||
# 设置 ListenAI 工具包路径
|
||
export LISTENAI_TOOLS_PATH=/path/to/listenai-tools
|
||
|
||
.. warning::
|
||
**必须使用绝对路径！** 环境变量的路径必须是绝对路径（如 ``/home/user/toolchain``），不能使用相对路径（如 ``./toolchain`` 或 ``../toolchain``），否则会导致编译失败。
|
||
|
||
其中：
|
||
|
||
- ``NUCLEI_TOOLCHAIN_PATH`` 指向解压后的工具链路径（绝对路径）
|
||
- ``LISTENAI_TOOLS_PATH`` 指向解压后的 ListenAI 工具包路径（绝对路径）
|
||
|
||
.. _quick_start:
|
||
|
||
快速开始
|
||
========
|
||
|
||
编译示例
|
||
--------
|
||
|
||
以 helloworld 工程为例，演示如何编译项目：
|
||
|
||
1. **编译命令**
|
||
|
||
在 SDK 根目录下执行：
|
||
|
||
.. code-block:: shell
|
||
|
||
./build.sh -C -S samples/helloworld -DBOARD=arcs_evb
|
||
|
||
命令参数说明：
|
||
|
||
- ``-S``: 指定项目源码路径
|
||
- ``-DBOARD``: 指定目标板型(必需参数,如 arcs_mini、arcs_evb 等)
|
||
- ``-C``: 清理构建目录(可选)
|
||
|
||
2. **编译输出**
|
||
|
||
编译成功后会在 ``build`` 目录下生成构建产物，包括：
|
||
|
||
- ``helloworld.bin``: 烧录文件
|
||
- ``helloworld.elf``: 调试文件
|
||
- 其他相关文件
|
||
|
||
.. _flashing:
|
||
|
||
烧录运行
|
||
========
|
||
|
||
准备工作
|
||
--------
|
||
|
||
1. **连接硬件**
|
||
|
||
将串口板连接到开发板：
|
||
|
||
- 开发板 TX 脚 (默认引脚PA2，注意查看板型文件) 连接串口板 RX
|
||
- 开发板 RX 脚 (默认引脚PA3，注意查看板型文件) 连接串口板 TX
|
||
- 开发板 GND 连接串口板 GND
|
||
|
||
2. **进入烧录模式**
|
||
|
||
按住 BOOT 脚后复位开发板，进入烧录模式。
|
||
|
||
.. note::
|
||
每次重新烧录前，都需要执行按住 BOOT 脚后复位开发板的操作。
|
||
|
||
自动烧录（推荐）
|
||
----------------
|
||
|
||
如果希望实现自动烧录，可以连接控制引脚：
|
||
|
||
- 开发板 BOOT 脚连接串口板 RTS 脚
|
||
- 开发板 RESET 脚连接串口板 DTR 脚
|
||
|
||
这样 cskburn 工具可以自动控制进入烧录模式。
|
||
|
||
烧录命令
|
||
--------
|
||
|
||
使用 cskburn 工具进行烧录：
|
||
|
||
.. code-block:: shell
|
||
|
||
./tools/burn/cskburn -s /dev/ttyUSB0 -b 3000000 0x0 build/helloworld.bin -C arcs
|
||
|
||
命令参数说明：
|
||
|
||
- ``-s``: 指定烧录设备（串口设备路径）
|
||
|
||
.. note::
|
||
请根据实际情况选择正确的串口设备：
|
||
|
||
- 使用 ``ls /dev/ttyUSB*`` 或 ``ls /dev/ttyACM*`` 查看可用设备
|
||
- 常见设备名：``/dev/ttyUSB0``、``/dev/ttyUSB1``、``/dev/ttyACM0`` 等
|
||
- 插入串口板时可使用 ``dmesg | tail`` 查看系统分配的设备名
|
||
|
||
- ``-b``: 指定烧录波特率（推荐使用 3000000）
|
||
- ``0x0``: 烧录起始地址（基于 0x30000000 flash 起始地址的偏移）
|
||
- ``build/helloworld.bin``: 烧录文件路径
|
||
- ``-C arcs``: 指定芯片类型
|
||
|
||
验证运行
|
||
--------
|
||
|
||
烧录完成后复位开发板，应该可以在串口控制台看到以下输出：
|
||
|
||
.. code-block:: text
|
||
|
||
Running on hart-id: 1
|
||
Hello, world!
|
||
|
||
.. _troubleshooting:
|
||
|
||
常见问题
|
||
========
|
||
|
||
1. **权限问题**
|
||
|
||
如果遇到串口权限问题，将当前用户添加到 dialout 组：
|
||
|
||
.. code-block:: shell
|
||
|
||
sudo usermod -a -G dialout $USER
|
||
|
||
然后重新登录。
|
||
|
||
2. **串口设备问题**
|
||
|
||
使用 ``dmesg`` 或 ``ls /dev/ttyUSB*`` 查看串口设备：
|
||
|
||
.. code-block:: shell
|
||
|
||
ls /dev/ttyUSB*
|
||
|
||
3. **环境变量问题**
|
||
|
||
确保已正确设置环境变量，可以使用以下命令检查：
|
||
|
||
.. code-block:: shell
|
||
|
||
echo $NUCLEI_TOOLCHAIN_PATH
|
||
echo $LISTENAI_TOOLS_PATH
|