Introduction

This chapter illustrates how to build Realtek’s SDK under GCC environment. It focuses on both Windows platform and Linux distribution. The build and download procedures are quite similar between Windows and Linux operating systems.

  • For Windows, Windows 10 64-bit is used as a platform.

  • For Linux server, Ubuntu 16.04 64-bit is used as a platform.

Preparing GCC Environment

Windows

For Windows, use MSYS2 and MinGW as the GCC environment.

  • MSYS2 is a collection of tools and libraries providing an easy-to-use environment for building, installing, and running native Windows software.

  • MinGW is an advancement of the original mingw.org project. It is created to support the GCC compiler on Windows system.

The steps to prepare GCC environment are as follows:

  1. Download MSYS2 from its official website https://www.msys2.org.

  2. Run the installer. MSYS2 requires 64-bit Windows 7 or later.

  1. Enter your desired Installation Folder (ASCII, no accents, spaces nor symlinks, short path)

  2. When done, tick Run MSYS2 now.

    ../../../_images/windows_gcc_msy32_installation.svg

  3. Update the package database and base packages with:

    pacman -Syu

    When Proceed with installation? [Y/n] is displayed, type Y and continue until the package installation is done.

    ../../../_images/proceed_with_installation.svg

    Caution

    After installation of MSYS2, there will be four start modes:

    • MSYS2 MinGW 32-bit

    • MSYS2 MinGW 64-bit

    • MSYS2 MinGW UCRT 64-bit

    • MSYS2 MSYS

    Because the toolchain release will base on 64-bit MinGW, choose MSYS2 MinGW 64-bit when starting the MinGW terminal.

  4. Run MSYS2 MinGW 64-bit from Start menu. Update the rest of the base packages with:

    pacman -Syu

    When Proceed with installation? [Y/n] is displayed, type Y and continue until the package installation is done.

    ../../../_images/proceed_with_installation_y.png

  5. Install the necessary software packages with the commands below in order:

    pacman –S make
pacman –S unzip
pacman –S gcc
pacman –S python
pacman –S ncurses-devel
pacman –S openssl-devel
pacman -S mingw-w64-x86_64-gcc-libs

    When Proceed with installation? [Y/n] is displayed, type Y and continue until each software package installation is done.

  6. Search the needed packages (used to compile TF-M) in and install them as you need with the commands below.

    pacman -S diffutils
pacman -S vim
pacman -S python-pip
pacman -S cmake
pip install Jinja2

  7. Remove the file path length limit by editing the registry to allow the file paths longer than 260 characters.

    1. Press Win+R keys to open the Run dialog box, then type regedit and press Enter to open the Registry Editor.

    2. Navigate to the registry key: Computer\HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\FileSystem.

    3. Search and check if the LongPathsEnabled item exists. If not, continue to step d; otherwise, go to step e.

    1. Right-click on an empty space in the right pane, then select New > DWORD (32-bit) Value, and name it LongPathsEnabled.

    1. Double-click on LongPathsEnabled and set its value to 1, then click OK to save.

Linux

On Linux, 32-bit Linux is not supported because of the toolchain.

The packages listed below should be installed for the GCC environment:

  • gcc

  • libncurses5

  • bash

  • make

  • libssl-dev

  • binutils

  • python3

Some of the packages above may have been pre-installed in your operating system. You can either use package manager or type the corresponding version command on terminal to check whether these packages have already existed. If not, make them installed.

  • $ls -l /bin/sh

    Starting from Ubuntu 6.10, dash is used by default instead of bash. You can use $ls -l /bin/sh command to check whether the system shell is bash or dash.

    • (Optional) If the system shell is dash, use $sudo dpkg-reconfigure dash command to switch from dash to bash.

    • If the system shell is bash, continue to do the subsequent operations.

    ../../../_images/switching_from_dash_to_bash.png

  • $make -v

    ../../../_images/make_v.png

  • $sudo apt-get install libssl-dev

    ../../../_images/libssl_dev.png

  • binutils

    Use ld -v command to check if binutils has been installed. If not, the following error may occur.

    ../../../_images/binutils.png

Troubleshooting

  • MSYS2 pacman is responsible for managing and installing software, which is similar to apt-get in ubuntu. When bash:XXX:command not found appears, you can try instruction pacman -S <package_name> to install.

  • For detailed information of one package, try pacman -Si <package_name>.

  • If system head files are not found when building tool, No such file or directory error will show up. You can try pacman -Fy <FILE_NAME> to check which package is lost, and install the lost package. If too many packages are lost, look for detailed information about the packages to decide which to install.

  • For multi-version python host, command update-alternatives --install /usr/bin/python python /usr/bin/python3.x 1 can be used to select python of specific version 3.x, where x represents a desired version number.

  • If the error command 'python' not found appears during compilation, type command ln -s /usr/bin/python3 /usr/bin/python first to make sure that python3 is used when running python.

Installing Toolchain

The toolchain will be installed automatically when building the project at the first time. And the toolchain will be intalled in /opt/rtk-toolchain by default.

  1. During the compilation, we will check if the toolchain exists and if the version of the toolchain match the lastest version. Once error occurs, you should fix the error according to the prompts on the screen and try again with make.

  1. The toolchain will be downloaded from github when building the project at the first time. If find the download speed from github is too slow or download failed, please execute command make toolchain URL=aliyun or make toolchain URL=github first to get toolchain before building project. We recommend use make toolchain URL=aliyun to download toolchain from aliyun to improve the download speed.

  1. The default directory for the toolchain installation is /opt/rtk-toolchain. If you want to change the installation path, modify the TOOLCHAINDIR defined in Makefile.include.gen which is located both in project_km0 and project_km4.

Note

  • If an error Create Toolchain Dir Failed. May Not Have Permission appears, please create the installation directory by manual. If still fails, please refer to 3 above to change the installtion directory.

  • If an error Download Failed appears, please check if the network connection is accessible first. If still fails, please refer to 2 above to intall the toolchain again.

  • If an error Current Toolchain Version Mismatched appears, please delete the current toochain and retry with make, and the latest toolchain will be installed automatically during building the project.

If the installation still fails, try with the manual installation steps shown in below.

Windows

This section introduces the steps to prepare the toolchain environment manually.

  1. Acquire the zip files of RTL8721Dx toolchain from Realtek.

  1. Create a new directory rtk-toolchain under the path {MSYS2_path}\opt.

    For example, if your MSYS2 installation path is as set in Section Windows step 3, the rtk-toolchain should be in C:\msys64\opt.

    ../../../_images/windows_rtk_toolchain_1.png

  2. Unzip asdk-10.3.x-mingw32-newlib-build-xxxx.zip and place the toolchain folder asdk-10.3.x to the folder rtk-toolchain created in step 2.

    ../../../_images/windows_rtk_toolchain_2.png

Note

  • The unzip folders should stay the same with the figure above and do NOT change them, otherwise you need to modify the toolchain directory in makefile to customize the path.

Linux

This section introduces the steps to prepare the toolchain environment manually.

  1. Acquire the zip files of RTL8721Dx toolchain from Realtek.

  2. Create a new directory rtk-toolchain under the path /opt.

    ../../../_images/linux_rtk_toolchain_1.png

  3. Unzip asdk-10.3.x-linux-newlib-build-xxxx.tar.bz2 to /opt/rtk-toolchain , then you can get the directory below:

    ../../../_images/linux_rtk_toolchain_2.png

Note

  • The unzip folders should stay the same with the figure above and do NOT change them, otherwise you need to modify the toolchain directory in makefile to customize the path.

Configuring SDK

This section illustrates how to change SDK configurations.

User can configure SDK options for KM0 and KM4 at the same time through $make menuconfig command.

  1. Switch to the directory {SDK}\amebadplus_gcc_project

  2. Run $make menuconfig command on MSYS2 MinGW 64-bit (Windows) or terminal (Linux)

Note

The command $make menuconfig is only supported under {SDK}\amebadplus_gcc_project, but not supported under other paths.

The main configurable options are divided into four parts:

  • General Config: the shared kernel configurations for KM4 and KM0. The configurations will take effect in both KM4 and KM0.

  • Network Config: the shared kernel configurations for KM4 and KM0. The configurations will take effect in both KM4 and KM0.

  • KM4 Config: the exclusive kernel configurations for KM4. The configurations will take effect only in KM4 but not in KM0.

  • KM0 Config: the exclusive kernel configurations for KM0. The configurations will take effect only in KM0 but not in KM4.

The following figure is the menuconfig UI, and the options in red may be used frequently.

Building Code

This section illustrates how to build SDK for both Windows and Linux. The following table lists all the GCC project directories of SDK.

GCC project

Directory

KM4

{SDK}\amebadplus_gcc_project\project_km4

KM0

{SDK}\amebadplus_gcc_project\project_km0

Note

Replace the {SDK} with your own SDK directory.

There are two ways to build the SDK, you can choose either of them.

Build One by One

Follow these steps to build the SDK of KM4 and KM0 project one by one:

  1. Use $cd command to switch to the project directories of SDK on Windows or Linux.

    For example, you can type $cd {SDK}\amebadplus_gcc_project\project_km4 to switch to the KM4 project, the same operation for the KM0 project.

  2. Build SDK under the KM0 or KM4 project directory on Windows or Linux.

    • For normal image, simply use $make all command to build SDK.

    • For MP image, refer to Section How to Build MP Image to build SDK.

  3. Check the command execution results. If somehow failed, type $make clean to clean and then redo the make procedure.

    • For KM4 project, if the terminal contains target_img2.axf and Image manipulating end message (see KM4 project make all), it means that KM4 images have been built successfully. You can find them under \amebadplus_gcc_project\project_km4\asdk\image (see KM4 image generation).

      ../../../_images/km4_project_make_all.png

      KM4 project make all

      ../../../_images/km4_image_generation.png

      KM4 image generation

    • For KM0 project, if the terminal contains target_img2.axf and Image manipulating end message (see KM0 project make all), it means that KM0 image has been built successfully. You can find it under \amebadplus_gcc_project\project_km0\asdk\image (see KM0 image generation).

      ../../../_images/km0_project_make_all.png

      KM0 project make all

      ../../../_images/km0_image_generation.png

      KM0 image generation

Build Together

In order to improve the efficiency of building SDK, you can also execute $make all command once under \amebadplus_gcc_project, instead of executing $make all command separately under the KM0 project and KM4 project.

  • If the terminal contains target_img2.axf and Image manipulating end message (see KM4 & KM0 projects make all), it means that all the images have been built successfully. The image files are generated under \amebadplus_gcc_project (see KM4 & KM0 image generation). You can also find them under \amebadplus_gcc_project\project_km0\asdk\image and \amebadplus_gcc_project\project_km4\asdk\image.

  • If somehow failed, type $make clean to clean and then redo the make procedure.

    ../../../_images/km4_km0_projects_make_all.png

    KM4 & KM0 projects make all

    ../../../_images/km4_km0_image_generation.png

    KM4 & KM0 image generation

Note

If you want to search some .map files for debugging, get them under the directory \amebadplus_gcc_project\project_km0\asdk\image or \amebadplus_gcc_project\project_km4\asdk\image, but not \amebadplus_gcc_project.

Setting Debugger

Downloading Image to Flash

There are two ways to download image to Flash:

  1. Image Tool, a software provided by Realtek (recommended). For more information, refer to Image Tool for more information.

  2. GDB Server, mainly used for GDB debug user case.

This section illustrates the second method to download images to Flash.

To download software into Device Board, make sure the steps mentioned in Section Building Code are done, and then type $make flash command on MSYS2 (Windows) or terminal (Linux).

Images are downloaded only under KM4 by this command. This command downloads the software into Flash and it will take several seconds to finish, as shown below.

../../../_images/downloading_image_to_flash.png

Downloading Image to Flash

../../../_images/download_codes_success.png

Download codes success log

To check whether the image is downloaded correctly into memory, you can select verify download before downloading images, and during image download process, verified OK log will be shown.

../../../_images/verify_download.png

Verify download

After download is successful, press Reset button and you will see that the device boots with the new image.

Note

The command is only supported to use in KM4 project, and km4_boot_all.bin & KM0_km4_app.bin can be downloaded to Flash.

Entering Debug Mode

GDB Server

To enter GDB debugger mode, follow the steps below:

  1. Make sure that the steps mentioned in Sections Configuring SDK to Setting Debugger are finished, then reset the device.

  2. Change the directory to target project which can be project_km4 or project_km0, and type $make debug on MSYS2 (Windows) or terminal (Linux).

J-Link

Steps

  1. Press Win+R on your keyboard. Hold down the Windows key on your keyboard, and press the R button. This will open the Run tool in a new pop-up window. Alternatively, you can find and click Run on the Start menu.

  2. Type cmd in the Run window. This shortcut will open the Command Prompt terminal.

  3. Click OK in the Run window. This will run your shortcut command, and open the Command Prompt terminal in a new window.

  4. Copy the J-Link script command below for specific target:

  • For KM4:

    "{Jlink_path}\JLink.exe" -device Cortex-M33 -if SWD -speed 4000 -autoconnect 1

  • For KM0:

    "{Jlink_path}\JLink.exe" -device Cortex-M23 -if SWD -speed 4000 -autoconnect 1

Note

The J-Link connection command path mentioned above are:

  • {Jlink_path}: the path your Segger J-Link installed, default is C:\Program Files (x86)\SEGGER\JLink.

  • {script path}: {SDK}\amebadplus_gcc_project\utils\jlink_script.

Commands

The following commands are often used when the program is stuck. All commands are accepted case insensitive.

Often used commands

Command (long)

Command (short)

Syntax

Explanation

Halt

H

Halt CPU

Go

G

Start CPU if halted

Mem

Mem <Addr> <NumBytes>

Read memory and show corresponding ASCII values

SaveBin

SaveBin <FileName> <Addr> <NumBytes>

Save target memory range into binary file

Exit

Close J-Link connection and quit

For more information, you can visit https://wiki.segger.com/J-Link_Commander.

Note

  • You can type H and G several times and record the PC, then look for the PC in which function in asm file. This function might be where you get stuck.

  • You can also use mem to dump some address after sp, from these addresses you can find the function call stack.

Command Lists

The commands mentioned above are listed in the following table.

Command lists

Usage

Command

Description

all

$make all

Compile the project to generate ram_all.bin

setup

$make setup GDB_SERVER= jlink

Select GDB_SERVER

flash

$make flash

Download ram_all.bin to Flash

clean

$make clean

Remove compile file (xx.bin, xx.o, …)

debug

$make debug

Enter debug mode

GDB Debugger Basic Usage

GDB, the GNU project debugger, allows you to examine the program while it executes, and it helps catch bugs. Section Entering Debug Mode has described how to enter GDB debugger mode, and this section illustrates some basic usage of GDB commands.

For more information on GDB debugger, click https://www.gnu.org/software/gdb/. The following table describes commonly used instructions and their functions, and specific usage can be found in GDB User Manual of website https://www.sourceware.org/gdb/documentation/.

GDB debugger command list

Usage

Command

Description

Breakpoint

$break

Breakpoints are set with the break command (abbreviated b).

The usage can be found at Setting Breakpoints section.

Watchpoint

$watch

You can use a watchpoint to stop execution whenever the value of an expression changes. The related commands include watch, rwatch, and awatch.

The usage of these commands can be found at Setting Watchpoints section.

Note

Keep the range of watchpoints less than 20 bytes.

Print breakpoints & watchpoints

$info

To print a table of all breakpoints, watchpoints set and not deleted, use the info command. You can simply type info to know its usage.

Delete breakpoints

$delete

To eliminate the breakpoints, use the delete command (abbreviated d).

The usage can be found at Deleting Breakpoints section.

Continue

$continue

To resume program execution, use the continue command (abbreviated c).

The usage can be found at Continue and Stepping section.

Step

$step

To step into a function call, use the step command (abbreviated s). It will continue running your program until the control reaches a different source line.

The usage can be found at Continue and Stepping section.

Next

$next

To step through the program, use the next command (abbreviated n). The execution will stop when the control reaches a different line of code at the original stack level.

The usage can be found at Continue and Stepping section.

Quit

$quit

To exit GDB debugger, use the quit command (abbreviated q), or type an end-of-file character (usually Ctrl-d). The usage can be found at Quitting GDB section.

Backtrace

$backtrace

A backtrace is a summary of how your program got where it is. You can use backtrace command (abbreviated bt) to print a backtrace of the entire stack.

The usage can be found at Backtraces section.

Print source lines

$list

To print lines from a source file, use the list command (abbreviated l).

The usage can be found at Printing Source Lines section.

Examine data

$print

To examine data in your program, you can use print command (abbreviated p). It evaluates and prints the value of an expression.

The usage can be found at Examining Data section.