DSP Build and Flashing

Firmware Composition

Ameba SoC uses a heterogeneous multi-core architecture, where system firmware consists of both MCU and DSP firmware. DSP and MCU share Flash and memory resources. Before building firmware, you must plan the Flash partitioning and Memory Layout (SRAM, PSRAM, and IPC shared memory) in advance, which is the foundation for proper collaboration between the two.

Users can choose different firmware packaging and flashing methods at different stages:

Firmware Type	Filename	Applicable Stage	Functional Description
Bootloader	`km4_boot_all.bin`	Universal	System boot loader, responsible for loading MCU and DSP firmware.
DSP Standalone Firmware	`dsp_all.bin`	Development Stage	Standalone DSP firmware with header information, can be directly flashed to the DSP partition of Flash.
MCU Standalone Firmware	`kr4_km4_app.bin`	Development Stage	Contains only MCU application firmware. DSP firmware is flashed separately, the two are decoupled.
DSP Raw Firmware	`dsp.bin`	Production Stage	Pure binary code, must be copied to MCU SDK and merged as a sub-firmware into the complete MCU firmware.
MCU DSP Unified Firmware	`kr4_km4_dsp_app.bin`	Production Stage	All-in-One application firmware. MCU firmware has DSP firmware embedded, supports overall OTA upgrade and secure boot.

Build Process

Ameba SDK supports two build methods: Separate Packaging is suitable for development debugging; Merged Packaging is suitable for final production release.

The following diagram shows the complete process from source code compilation to firmware generation:

Based on the project stage, please select the appropriate mode:

Development Stage: Separate Packaging Mode
- Features: DSP and MCU firmware files are separated, flashed to different Flash addresses respectively.
- Advantages:
  - Fast debugging: After modifying DSP algorithms, only the smaller dsp_all.bin needs to be compiled and re-flashed, no need to rebuild MCU.
  - Decoupled: Suitable for DSP algorithm engineers to develop independently, without relying on MCU code base.
- Operation: Disable DSP within APP option in MCU SDK Menuconfig.
Production Stage: Merged Packaging Mode
- Features: DSP firmware and MCU firmware are concatenated to generate a single file.
- Advantages:
  - Supports OTA: During system upgrade, MCU and DSP are updated as a whole version atomically, ensuring compatibility.
  - Supports Secure Boot: DSP firmware can be verified through MCU’s Secure Boot, providing higher security.
- Operation:
  - Must copy dsp.bin to the specified directory in MCU SDK.
  - Enable DSP within APP option in MCU SDK Menuconfig.

The following sections describe configuration details and operation methods:

DSP Firmware Build

First, build the DSP firmware. The DSP SDK provides two build methods. Please choose according to your development environment.

Applicable scenarios: Linux servers, automated build workflows, when project configuration is difficult to modify.

1. Environment Preparation

Before using scripts to build the project, you must add the Xtensa toolchain path to the system environment variable PATH.
# Example path (please adjust according to actual installation location)
export PATH=$PATH:/opt/xtensa/XtDevTools/install/tools/RI-2021.8-linux/XtensaTools/bin

2. Build Configuration

The automatic build script determines build parameters by reading the project/auto_build/dsp_batch.xml file. Please open this file and select the appropriate Configuration according to project requirements:

HIFI5_PROD_1123_asic_wUPG (Window ABI): Suitable for scenarios where code and data are located within the same 1GB address space.

HIFI5_PROD_1123_asic_UPG (Call0 ABI): Suitable for scenarios involving cross-memory function calls (e.g., jumping between SRAM and PSRAM).

For in-depth technical details about ABI, please refer to DSP ABI Selection .

3. Execute Build

Navigate to the automatic build directory and run the script:
cd project/auto_build/
chmod +x auto_build.sh
./auto_build.sh
Warning

Workspace Reset Warning: This script automatically creates a temporary workspace named auto_ws and copies project_dsp into it for building. Do not modify code in the auto_ws directory, as it will be cleared and overwritten the next time the script runs. All code modifications should be made in the original project_dsp directory.

4. Verify Output

After a successful build, the firmware is stored at the following path:

Output directory: <dsp_sdk>/project/image/

Key files:

dsp_all.bin (for development stage flashing)

dsp.bin (for production stage merging)

Applicable scenarios: Windows environment, or when modifying project configuration.

1. Environment Preparation

Xtensa toolchain: Must add the path to the system environment variable PATH.

(Windows default: C:\usr\xtensa\XtDevTools\install\tools\RI-2021.8-win32\XtensaTools\bin)

Python environment: Ensure Python (3.8+) is installed and added to environment variables.

Tip

If your system command is python3 instead of python, please adjust the command to python3 in the Post-build step of the project properties (as shown in the red box in the figure below).

2. Import Project

Open Xtensa Xplorer and set Workspace to <dsp_sdk>\project.

Click menu File > Import, select General > Existing Projects into Workspace.

Check project_dsp (source code project) and RTK_lsp (linker script project), click Finish.

3. Build Configuration

In the Xplorer toolbar, set the Build Active parameters:

P (Project): Select project_dsp

C (Config): Select ABI configuration according to project configuration:

HIFI5_PROD_1123_asic_wUPG (Window ABI)

HIFI5_PROD_1123_asic_UPG (Call0 ABI)

T (Target): Select Release.

4. Execute Build

Click the Build Active icon in the toolbar to start building.

5. Verify Output

After a successful build, the firmware is stored at the following path:

Output directory: <dsp_sdk>\project\image\

Key files:

dsp_all.bin (for development stage flashing)

dsp.bin (for production stage merging)

MCU Firmware Compilation and Flashing

After completing the DSP SDK compilation, proceed with the MCU SDK compilation.

Step 1: Configure MCU SDK

Regardless of the packaging mode, the MCU must adjust the memory layout to accommodate DSP operation. SRAM is faster than PSRAM. To accelerate DSP calculations, the default SDK allocates most of the SRAM to the DSP. Therefore, the MCU data segment must be relocated to PSRAM.

Refer to Configure SDK (menuconfig) to enter menuconfig.
Navigate to the CONFIG Link Option menu and configure as follows:
```
CONFIG Link Option --->
   IMG2 Data and Heap in SRAM or PSRAM?
   ( ) SRAM
   (X) PSRAM
```
- PSRAM: Required option. The MCU heap and data segment will be stored in PSRAM.
- Code segment: Recommended to keep the default XIP mode (MCU executes code directly from Flash).

Step 2: Compile MCU Firmware

Objective: Generate standalone MCU firmware, isolated from DSP firmware, for rapid iteration.

Disable Integration Option:

Enter menuconfig and ensure that DSP within APP image is unchecked.

CONFIG DSP Enable --->
   [*] Enable DSP
   [ ] DSP within APP image  <-- Ensure unchecked

Execute Compilation: Save the configuration and exit, then execute the compilation command.
- Output artifact: <mcu_sdk>/amebalite_gcc_project/kr4_km4_app.bin
- Characteristics: This firmware contains only MCU code, without DSP binary data.

Objective: Merge DSP firmware as a data segment into MCU firmware to generate a single firmware file.

Prepare DSP Firmware (Critical Step): Copy the pure data firmware dsp.bin generated by DSP SDK compilation to the MCU SDK component directory.
- Source file: <dsp_sdk>/project/image/dsp.bin
- Destination: <mcu_sdk>/component/dsp/dsp.bin (Assumed path, please adjust according to the actual path configured in Kconfig below)
Enable Integration Option: Enter menuconfig, check the integration option, and specify the path.
```
CONFIG DSP Enable --->
   [*] Enable DSP
   [*]   DSP within APP image
   (../component/dsp) DSP_IMAGE_TARGET_DIR
```
Path configuration notes: DSP_IMAGE_TARGET_DIR is a relative path to the MCU project directory (<mcu_sdk>/amebalite_gcc_project).
- Default configuration is typically ../component/dsp
- Please verify the .config file to confirm correct path resolution: CONFIG_DSP_IMAGE_TARGET_DIR="../component/dsp"
Execute Compilation:

Save the configuration and exit, then execute the MCU SDK compilation command normally.
- Output artifact: <mcu_sdk>/project/.../kr4_km4_dsp_app.bin
- Characteristics: This firmware contains complete DSP binary data and supports unified OTA.

Step 3: Flash Firmware

Corresponds to the separate packaging mode mentioned above. In this mode, there is an independent DSP partition in Flash, requiring two files to be flashed separately. Flashing list:

Firmware File	Target Partition (Flash Layout)	Description
`km4_boot_all.bin`	IMG_BOOT	Bootloader
`kr4_km4_app.bin`	IMG_APP	MCU application
`dsp_all.bin`	IMG_DSP	DSP complete firmware (with Header)

Warning

This mode does not support OTA upgrades and firmware tamper verification. It is intended for laboratory development only.

Corresponds to the merged packaging mode mentioned above. In this mode, DSP firmware is embedded within the MCU firmware, requiring only one file to be flashed. Flashing list:

Firmware File	Target Partition (Flash Layout)	Description
`km4_boot_all.bin`	IMG_BOOT	Bootloader
`kr4_km4_dsp_app.bin`	IMG_APP	MCU + DSP merged firmware

Step 4: Reset and Verification

After completing the flashing, please press the reset button to restart the development board and view logs through the UART serial tool.

Check Boot Logs:

Observe whether DSP initialization-related prints appear.
Verify Success Indicators:

Under normal circumstances, you should see output similar to the following:
```
Hello DSP World
```
Since KM4, KR4, and DSP cores share the same physical serial output, logs may be interleaved. It is recommended to add specific prefixes (such as [DSP]) to print messages in DSP code, or use multi-line printing to facilitate differentiation and debugging.

Compilation and Debugging Files

In addition to binary firmware, compilation can also generate disassembly files and Map files for debugging analysis:

Disassembly Files

Disassembly files translate machine code back to assembly language, used for low-level code analysis and Crash localization. The SDK disables disassembly generation by default. To enable it, follow these steps:

Open the post-processing script: <dsp_sdk>/project/img_utility/code_analyze.py

Find the configuration option ENABLE_Disassembler and change it to 1:

# User Configuration
ENABLE_Disassembler = 1  # 0: Disable (Default), 1: Enable

Re-execute the compilation process. Disassembly file locations:

Compilation Method	Disassembly File Path
Command-line Compilation	`<dsp_sdk>/auto_ws/project/dsp/bin/HIFI5_PROD_1123_asic_<ABI>/UPG/Release/project_dsp.asm`
Xplorer GUI Compilation	`<dsp_sdk>/project/project_dsp/bin/HIFI5_PROD_1123_asic_<ABI>/Release/project_dsp.asm`

Map Files

Map files record the runtime addresses of symbols (functions, variables) and the size of each section in detail, making them a powerful tool for analyzing firmware structure and troubleshooting address errors. Map file locations:

Compilation Method	Map File Path
Linux Command-line Compilation	`<dsp_sdk>/auto_ws/project/dsp/bin/HIFI5_PROD_1123_asic_<ABI>/Release/project_dsp.map`
Xplorer GUI Compilation	`<dsp_sdk>/project/project_dsp/bin/HIFI5_PROD_1123_asic_<ABI>/Release/project_dsp.map`

Common Issues

Q: Compilation failed with “xt-* command not found”?

A: Please check if the Xtensa Tools directory has been added to the PATH environment variable.

Q: Python error during GUI compilation?

A: Check if the Python version is 3.8+, and confirm the Python command path in Xplorer project properties.

Q: Command-line compilation is slow?

A: Command-line compilation performs a full build each time. For incremental compilation, please use the GUI method.

Q: How to switch between Call0 and Window ABI?

A: In GUI compilation, switch through the C (Configuration) dropdown; in command-line compilation, modify the dsp_batch.xml configuration file.

Q: No “Hello DSP World” output?

A: Possible causes:

DSP firmware not flashed correctly

DSP not enabled in menuconfig

DSP boot failed (check map file or disassembly file for debugging)

DSP logs mixed with MCU logs; it is recommended to enable AGG in MCU SDK to distinguish serial output cores