AT32 IDE User Manual

UM0009

AT32 IDE User Manual

Introduction
This user manual gives an overview of Artery AT32 IDE. AT32 IDE is a software development
environment for cross-platform ARM embedded system. It contains a series of Eclipse plug-ins and
tools. Eclipse plug-ins allow users to create, build and debug AT32 MCU in AT32 IDE. AT32 IDE has
the following features.
 Create projects using Artery project wizard: The New Project Wizard provides project template
for different target Artery MCUs.
 Build projects using GNU ARM toolchain: The toolchain contains ARM GCC compiler. Users can
easily use it to build projects.
 Debug projects using GDB: Users can pause, single-step debug, run and monitor the target chip.
SRAM and Flash access is allowed. Hardware breakpoints and detection points can be set. In
addition, users can erase the target chip and program user configuration.

List of applicable Artery MCUs:

Part number AT32 family

2024.10.30 1 Ver 1.0.9

 AT32 IDE User Manual

Contents
1 Introduction ................................................................................................................ 7

Environmental requirements......................................................................................... 7
Glossary ........................................................................................................................ 7

2 Installation .................................................................................................................. 8

Set up AT32 IDE on Windows ...................................................................................... 8

2.1.1 Run installer and select setup language ......................................................................8
2.1.2 Select destination location ...........................................................................................8
2.1.3 Select additional tasks..................................................................................................9
2.1.4 Ready for installation ....................................................................................................9
2.1.5 Installation complete.....................................................................................................9

Set up AT32 IDE on Linux .......................................................................................... 10

2.2.1 Unzip files ...................................................................................................................10
2.2.2 Set up GCC ................................................................................................................ 11
2.2.3 Configure udev access permission ............................................................................ 11
2.2.4 Set up HIDAPI library ................................................................................................. 11
2.2.5 Set up ncurses library.................................................................................................12
2.2.6 Run AT32 IDE .............................................................................................................12

Select Workspace ....................................................................................................... 13

3 Create new project................................................................................................... 14

New project wizard ..................................................................................................... 14

Target chip configurations ........................................................................................... 15
Debug configurations .................................................................................................. 15
GNU toolchain configuration....................................................................................... 16
Complete project creation........................................................................................... 17
Build project ................................................................................................................ 17
Project build configurations ........................................................................................ 19

4 Debug project ........................................................................................................... 20

AT-Link debug ............................................................................................................. 20

2024.10.30 2 Ver 1.0.9

 AT32 IDE User Manual
4.1.1 Main tab ......................................................................................................................20
4.1.2 Debugger tab ..............................................................................................................20

J-Link debug................................................................................................................ 21
4.2.1 Main tab ......................................................................................................................21
4.2.2 Debug tab ...................................................................................................................21

Start debugging........................................................................................................... 22
Download & Erase ...................................................................................................... 25
4.4.1 Download....................................................................................................................25
4.4.2 Erase ..........................................................................................................................25

5 ld linker ...................................................................................................................... 26

Basic concept.............................................................................................................. 26
5.1.1 Memory.......................................................................................................................26
5.1.2 Section ........................................................................................................................27

Linker script ................................................................................................................. 28

5.2.1 Example of linker script ..............................................................................................28
5.2.2 Entry point ..................................................................................................................29
5.2.3 Common commands ..................................................................................................29

6 Common functions .................................................................................................. 31

Install and upgrade AT32 IDE plug-ins ....................................................................... 31

6.1.1 Online installation and upgrade..................................................................................31
6.1.2 Offline installation and upgrade..................................................................................33

Language setting ........................................................................................................ 34

Open User Manual ...................................................................................................... 35
Resources update ....................................................................................................... 35
Import MDK project ..................................................................................................... 36

7 FAQs .......................................................................................................................... 40

Configuration ............................................................................................................... 40
Debugging ................................................................................................................... 40
Compilation ................................................................................................................. 40

8 Revision history ....................................................................................................... 42

2024.10.30 3 Ver 1.0.9

 AT32 IDE User Manual

List of tables
Table 1. Document revision history .................................................................................................... 42

2024.10.30 4 Ver 1.0.9

 AT32 IDE User Manual

List of figures
Figure 1. Select setup language .......................................................................................................... 8
Figure 2. Select destination location .................................................................................................... 8
Figure 3. Select additional tasks .......................................................................................................... 9
Figure 4. Installing AT32 IDE ............................................................................................................... 9
Figure 5. Installation complete ........................................................................................................... 10
Figure 6. Unzip files ........................................................................................................................... 10
Figure 7. GCC installation command ................................................................................................. 11
Figure 8. Configure udev access permission .................................................................................... 11
Figure 9. Set up HIDAPI library ......................................................................................................... 12
Figure 10. arm-gone-eabi-gdb execution fails ................................................................................... 12
Figure 11. Set up ncurses library ....................................................................................................... 12
Figure 12. Run AT32 IDE ................................................................................................................... 12
Figure 13. Select workspace ............................................................................................................. 13
Figure 14. Change file associations................................................................................................... 13
Figure 15. New project wizard ........................................................................................................... 14
Figure 16. Target chip configurations................................................................................................. 15
Figure 17. Debug configurations........................................................................................................ 16
Figure 18. GNU toolchain configurations ........................................................................................... 16
Figure 19. Complete project creation ................................................................................................ 17
Figure 20. Click toolbar to build a project .......................................................................................... 17
Figure 21. Build a project ................................................................................................................... 18
Figure 22. Project build result ............................................................................................................ 19
Figure 23. Project build configurations .............................................................................................. 19
Figure 24. AT-Link Main tab ............................................................................................................... 20
Figure 25. AT-Link Debugger tab ....................................................................................................... 21
Figure 26. J-Link Debugger tab ......................................................................................................... 22
Figure 27. J-Link SVD Path tab ......................................................................................................... 22
Figure 28. Start debugging ................................................................................................................ 23
Figure 29. Perspective switch ............................................................................................................ 23
Figure 30. Debug perspective............................................................................................................ 24
Figure 31. Install plug-ins online ........................................................................................................ 31
Figure 32. Installation progress ......................................................................................................... 32
Figure 33. Restart .............................................................................................................................. 32

2024.10.30 5 Ver 1.0.9

 AT32 IDE User Manual
Figure 34. Available Updates ............................................................................................................. 32
Figure 35. Add plug-in offline installation package ............................................................................ 33
Figure 36. List of plug-ins to be installed ........................................................................................... 33
Figure 37. Installation progress ......................................................................................................... 34
Figure 38. Restart .............................................................................................................................. 34
Figure 39. Change language ............................................................................................................. 35
Figure 40. Resources Manager ......................................................................................................... 35
Figure 41. Import BSP ....................................................................................................................... 36
Figure 42. Select an import wizard .................................................................................................... 37
Figure 43. Import a MDK project........................................................................................................ 38
Figure 44. AT32 IDE project directory ................................................................................................ 38
Figure 45. Project directory structure................................................................................................. 39
Figure 46. Linker Configuration ......................................................................................................... 41

2024.10.30 6 Ver 1.0.9

 AT32 IDE User Manual

1 Introduction
Environmental requirements
Software requirements
Windows 7 and above is required.
Linux distributions, including Ubuntu 18.4 and above, Fedora 34 and above, Centos 7 and above
are supported.
There is no need to install a driver when using the AT-Link simulator.
A driver is required when using the J-Link simulator. J-Link v6.20c and above is used. The version
below J-Link v6.20c will not work with this software.

Hardware requirements
AT-Link simulator
J-Link simulator
PC/AT compatible, Pentium or higher CPU
XVGA (1024*768) color display
At least 512M RAM
At least 20G disk space

Glossary
AT-Link simulator
AT-Link is a simulator developed by Artery to support the simulation of the kernel chip.

J-Link simulator
J-Link is a simulator developed by SEGGER to support the simulation of the kernel chip.

2024.10.30 7 Ver 1.0.9

 AT32 IDE User Manual

2 Installation
AT32 IDE provides an installer. The installer can be run directly and should be set up as prompted.
The installer consists of JRE runtime environment, ARM toolchain and GCC Make that do not need
to be installed separately.
Set up AT32 IDE on Windows
2.1.1 Run installer and select setup language
Run AT32IDE_V1.0.0_Setup.exe and select setup language as needed. Simplified Chinese and
English are available. Select the setup language and then click “OK”.

Figure 1. Select setup language

2.1.2 Select destination location

Select the installation position of AT32 IDE. The installation path shall not contain any spaces or
Chinese characters. Click “Next” to continue with the installation, as shown below.

Figure 2. Select destination location

2024.10.30 8 Ver 1.0.9

 AT32 IDE User Manual
2.1.3 Select additional tasks
Check the option to create a desktop shortcut. Click “Next” to continue with the installation.

Figure 3. Select additional tasks

2.1.4 Ready for installation

Click “Install” to install the AT32 IDE. A progress bar will appear and display the installation
progress.

Figure 4. Installing AT32 IDE

2.1.5 Installation complete

The AT32 IDE is installed successfully, as shown below.

2024.10.30 9 Ver 1.0.9

 AT32 IDE User Manual
Figure 5. Installation complete

Set up AT32 IDE on Linux

Linux distributions (including Ubuntu 18.4 and above, Fedora 34 and above, Centos 7 and above)
supported by the AT32 IDE are tested. Here, the Ubuntu 20.4 is used for demonstration.
2.2.1 Unzip files
Copy AT32IDE_for_Linux_V1.0.0.tar.gz to the Ubuntu system, and unzip by using the following
commands:
 $ mkdir AT32IDE
 $ tar –xvf AT32IDE.tar.gz –C AT32IDE

Figure 6. Unzip files

2024.10.30 10 Ver 1.0.9

 AT32 IDE User Manual
2.2.2 Set up GCC
Users need to set up GCC. If the GCC is already installed, please skip this section. Use the
command “gcc-version” to check whether GCC is set up.
GCC installation command is as follows:
Ubuntu:
 $ sudo apt update
 $ sudo apt install build-essential
Fedora:
 $ sudo yum install gcc
 $ sudo yum install gcc-c++
Centos:
 $ sudo yum install –y gcc gcc-c++

Figure 7. GCC installation command

2.2.3 Configure udev access permission

Only OpenOCD root user can access udev. Copy the 60-openocd.rules under OpenOCD/contrib to
the /etc/udev/rules.d directory, and the command is as follows:
 $ sudo cp AT32IDE/OpenOCD/contrib/60-openocd.rules /etc/udev/rules.d

Figure 8. Configure udev access permission

2.2.4 Set up HIDAPI library

CMSIS support requires HIDAPI library, which is installed by using the following commands:
Ubuntu:
 $ sudo apt install libhidapi-dev
Fedora:
 $ sudo dnf install hiadpi-devel
Centos:
 $ sudo yum install epel-release
 $ sudo yum install hidapi-devel

2024.10.30 11 Ver 1.0.9

 AT32 IDE User Manual
Figure 9. Set up HIDAPI library

2.2.5 Set up ncurses library

The arm-gone-eabi-gdb requires the ncurses library. The user can run arm-gone-eabi-gdb in the
terminal to check whether it can run normally. If the following interface appears, the user needs to
set up the ncurses library.

Figure 10. arm-gone-eabi-gdb execution fails

Installation commands:
Ubuntu:
 $ sudo apt install libncurses5
Fedora:
 $ sudo dnf install ncurses-compat-libs
Centos:
 $ sudo yum install ncurses-devel

Figure 11. Set up ncurses library

2.2.6 Run AT32 IDE

Enter the AT32IDE directory and input “. /AT32IDE” in the terminal to run AT32 IDE, or you can
double click AT32IDE to run it.

Figure 12. Run AT32 IDE

2024.10.30 12 Ver 1.0.9

 AT32 IDE User Manual
Select Workspace
When launching the AT32 IDE, pleas select a workspace that contains related projects and
constitutes an application. In addition, configuration settings of the AT32 IDE and related projects
are stored in the workspace. The configuration settings may vary for different computers. Therefore,
please create your own workspace instead of copying another user’s workspace. Only one
workspace can be active at a time. To switch the workspace, please click [File] -> [Switch
workspace].

Figure 13. Select workspace

After AT32 IDE setup, select “AT32 IDE” as the default file association for .project and .cproject
files. The file association is added in the Windows Registry during installation but does not take
effect immediately; therefore, it is recommended to restart the computer to apply the file association
or right click to select AT32IDE.exe.
Run the AT32 IDE, the project where the .project file is located will be automatically imported.

Figure 14. Change file associations

2024.10.30 13 Ver 1.0.9

 AT32 IDE User Manual

3 Create new project

New project wizard
The AT32IDE provides C project templates that support Artery MCUs, which is convenient for users
to create a new project quickly.
Click [File] > [New] > [C Project] to open the dialog box of new project wizard. Enter the project
name in the dialog. Take the AT32F403AVGT7 as an example. Enter AT32F403AVGT7 for the
project name, select AT32F403A_407 C Project for the project type, and select the toolchain Arm
Cross GCC by default. Then, click “Next” to continue.

Figure 15. New project wizard

Note:
1. The Project Name can only use uppercase letters, lowercase letters, digits and underscores. It
cannot contain Spaces.

2024.10.30 14 Ver 1.0.9

 AT32 IDE User Manual
2. If you run the AT32 IDE after installing it for the first time, you need to download the BSP
firmware before creating the project. See 6.4 to download the BSP firmware and then create the
new project.

Target chip configurations

According to the actual target MCU, select the target chip corresponding to AT32F403A. In this
example, select AT32F403AVGT7. The external clock is generally 0x8000000 by default. Other
configurations are set according to the actual situation.

Figure 16. Target chip configurations

Debug configurations
Select the default debug configuration. Click “Next” to continue.

2024.10.30 15 Ver 1.0.9

 AT32 IDE User Manual
Figure 17. Debug configurations

GNU toolchain configuration

For the GNU toolchain configuration, select GNU Tools for ARM Embedded Processors (arm-none-
eabi-gcc) by default. The toolchain path is integrated into AT32 IDE and does not need to be
selected separately. Click “Finish” to create the project.
If the toolchain path cannot be filled in automatically, please select it manually. The gcc-arm-none-
eabi and Build Tools are contained in IDE. The directories are shown below.
gcc-arm-none-eabi: AT32IDE\platform\tools\gcc-arm-none-eabi-10.3-2021.10\bin
Build Tools: AT32IDE\platform\tools\Build Tools\bin

Figure 18. GNU toolchain configurations

2024.10.30 16 Ver 1.0.9

 AT32 IDE User Manual
Complete project creation
After the AT32F403AVGT7 project is created, the box shown as below will appear.

Figure 19. Complete project creation

Build project
Right click on the target project and select “Build Project” in the pop-up menu, or select the target
project and click “Build Project” in the menu bar, to generate an elf file, as shown below.

Figure 20. Click toolbar to build a project

2024.10.30 17 Ver 1.0.9

 AT32 IDE User Manual
Figure 21. Build a project

The built project log is printed to the console, as shown below.

2024.10.30 18 Ver 1.0.9

 AT32 IDE User Manual
Figure 22. Project build result

Project build configurations

After the project is created, the project build can be reconfigured as needed. Select [Project] >
[Properties] or right click on the project and select [Properties], and then the Properties dialog box
will appear. Select C/C++ Build>Settings, change properties as needed, and then click “Apply and
Close” to apply the configurations. After setting these properties, we can rebuild the project based
on the current configurations.

Figure 23. Project build configurations

2024.10.30 19 Ver 1.0.9

 AT32 IDE User Manual

4 Debug project
Before debugging, please complete debug configurations that contain all the information required
for debugging.

AT-Link debug
Select [Run] > [Debug Configurations…] to open the debug configurations dialog box. Double-click
GDB AT-Link Debugging, the AT-Link debug configurations will be created automatically and
displayed on the right. All debug configurations are generated automatically and generally do not
need to be changed.
4.1.1 Main tab
In the Main tab, the project should have same name as the created project, and the name is
generated automatically. The C/C++ programs generally automatically search for elf files built in the
project. In this example, the Debug\xxxxx.elf is automatically filled in. If the project is not built in
advance and the elf file is not found, the Debug\${project_name}.elf will be automatically filled in.
The configurations also work when an elf file named after the project name is produced.

Figure 24. AT-Link Main tab

4.1.2 Debugger tab

The information in Debugger tab is also automatically configured when it is created. The
configuration paths of OpenOCD executable program and script files are relative paths, because
these tools are stored in the AT32 IDE installation files. In this example, the executable path and
SCD file path are automatically configured, and the Config options are configured according to the
chip type, which can be changed as needed. If you need to use WinUSB, please check the
“WinUSB”, and Config options will be automatically configured as “-f ./interface/atlink_dap_v2.cfg”,
as shown below.

2024.10.30 20 Ver 1.0.9

 AT32 IDE User Manual
Figure 25. AT-Link Debugger tab

J-Link debug
The following configurations are needed for J-Link debug.
 J-Link configuration
 GDB configuration
 SVD peripheral register configuration
You need to install the J-Link driver before using J-Link Debugging, and use the
“Segger_AT32MCU_AddOn” tool to import the AT32 MCU configuration , so that Segger tools can
identify the AT32 MCU.(You can download the “Segger_AT32MCU_AddOn” from the official
website.)
Select [Run] > [Debug Configurations…] to open the debug configurations dialog box. Double-click
GDB SEGGER J-Link Debugging, the J-Link debug configurations will be created automatically and
displayed on the right. All debug configurations are generated automatically and generally do not
need to be changed.

4.2.1 Main tab

Refer to 4.1.1.

4.2.2 Debug tab

1. Configure JlinkGDBServerCL automatically or click “Browse…” for modification. In AT32 IDE
V1.0.11 and above, the current device name is filled in automatically when the debugger is set
up. If the device name is not filled in automatically or an older AT32 IDE version is used, type in
the specific model to be debugged, for example, AT32F437ZMT7, AT32F413RCT7 and
AT32F415RCT7.
Note: Add a hyphen “-” to the front of the models (AT32F403/F403A/F407/F412/F415/F421/F425
/F435/F437/L021/WB415/A403A/A423 series), which is not required for other series.
2024.10.30 21 Ver 1.0.9
 AT32 IDE User Manual
Figure 26. J-Link Debugger tab

2. To set up GDB, select arm-none-eabi-gdb.exe under GCC directory.

3. Select SVD Path for debug register description. You can use the svd file in keil. When AT32 keil
Packet is installed, the svd file can be automatically copied to keil directory.

Figure 27. J-Link SVD Path tab

4. Debug configuration is done, then go to “Apply”->”Debug”.

Start debugging
Select the “AT32F403AVGT7 Debug” created in the previous step and click “Launch in ‘Debug’
mode” in the toolbar to start project debugging, as shown below.

2024.10.30 22 Ver 1.0.9

 AT32 IDE User Manual
Figure 28. Start debugging

The “Confirm Perspective Switch” dialog box pops up. Click “Switch” to switch to the Debugger
perspective, as shown below.

Figure 29. Perspective switch

Start project debugging and switch to Debug perspective. In Debug perspective, users can perform
debugging functions, such as viewing variable values, expression values, peripheral registers, etc.,
as shown below.

2024.10.30 23 Ver 1.0.9

 AT32 IDE User Manual
Figure 30. Debug perspective

2024.10.30 24 Ver 1.0.9

 AT32 IDE User Manual
Download & Erase
4.4.1 Download
After the project is built and AT-Link debugger is created, select the item to be downloaded and

click the download button ( ) in the toolbar to download the generated program to the device.

4.4.2 Erase
Select the item to be downloaded and click the erase button ( ) to perform erase operation to the
MCU Flash automatically.

2024.10.30 25 Ver 1.0.9

 AT32 IDE User Manual

5 ld linker
Every link is controlled by a linker script. The main purpose of the linker script is to describe how
the sections in the input files should be mapped into the output file, and to control the memory
layout of the output file. This section mainly introduces the use of GCC “*ld.” Linker (it is located in
the “ldscripts” file of the current project in AT32 IDE).
Basic concept
The “*.ld” linker combines objects and archive files, and relocate their data and bind symbolic
references. Generally, the last step in compiling a program is to run the “*.ld” linker. The linker
describes sections in the input files and how these sections are mapped into the output file, and the
memory layout of the output file.
5.1.1 Memory
Syntax:

MEMORY
{
Name [(attr)] : ORIGIN = origin, LENGTH = len
…
}

Note: The “attr” defines the attributes of a particular memory region. The valid attribute should be
made up of the following options.
R Read-only section
W Read/write section
X Executable section
A Allocatable section
I Initialized section
L Same as‘I’
! Invert the sense of any of the attributes that follow
Example:

/* Memories definition */
MEMORY
{
FLASH (rx) : ORIGIN = 0x08000000, LENGTH = 1024
RAM (xrw) : ORIGIN = 0x20000000, LENGTH = 96K
SPIM (rx) : ORIGIN = 0x08400000, LENGTH = 16384K

}
Note:
“rx”: “FLASH” area can be read and executed, and the FLASH start address is “0x08000000”, size:
1024 KB.
“xrw”: “RAM” area can be read, written and executed, and the RAM start address is “0x20000000”,
size: 96 KB.
“rx”: “SPIM” area can be read and executed, and the SPIM s tart address is “0x08400000”, size:
16384 KB.

2024.10.30 26 Ver 1.0.9

 AT32 IDE User Manual
5.1.2 Section
A section may be marked as loadable or allocatable.
Loadable: the contents should be loaded into memory when the program runs.
Allocatable: an area in memory should be set aside, but nothing in particular should be loaded
there (in some cases this memory must be zeroed out).
A section which is neither loadable nor allocatable typically contains some sort of debugging
information.
Every loadable or allocatable output section has two addresses, i.e., VMA and LMA.
VMA (the virtual memory address): This is the address the section will have when the output file is
run. The VMA is optional.
LMA (load memory address): This is the address at which the section will be loaded.
In most cases, the two addresses will be the same. An example of when they might be different is
when a data section is loaded into ROM, and then copied into RAM when the program starts up
(this technique is often used to initialize global variables in a ROM based system). In this case, the
ROM address would be the LMA, and the RAM address would be the VMA.
Syntax:

SECTIONS
{
Section [address] [(type)]:
{
[AT(Ima)]
[ALIGN(section_align) | ALIGN_WITH_INPUT]
[SUBALIGN(subsection_align)]
[constraint]
{
output-section-command
output-section-command
…
}
…
} [>region] [AT>Ima_region] [:phdr:phdr…] [=fillexp] [,]
…
}

Note: Most sections apply only some of the above attributes.

2024.10.30 27 Ver 1.0.9

 AT32 IDE User Manual

/* Sections */
SECTIONS
{
/* The startup code goes first into FLASH */
.isr_vector :
{
. = ALIGN(4);
KEEP(*(.isr_vector)) /* Startup code */
. =ALIGN(4)
} >FLASH

/* Initialized data sections goes into RAM, load LMA copy after code */
.data :
{
. = ALIGN(4);
_sdata = .; /* create a global symbol at data start */
*(.data) /* .data sections */
*(.data*) /* .data* sections */

. = ALIGN(4);
_edata = .; /* define a global symbol at data end */
} >RAM AT> FLASH
}

Note: The LMA and VMA of “.isr_vector” are the same. For the “.data” with “>RAM AT> FLASH”, the
“RAM” address (“.data” section) is the VMA, and the FLASH address is the LMA. In this case, the
content of “.data” section is stored in the FLASH, and then loaded to the RAM when the program
runs.

Linker script
A linker script contains a series of commands. Each command is either a keyword (possibly
followed by arguments) or an assignment to a symbol. Commands are separated by semicolons “;”.
A complete “*.ld” linker generally contains an entry point, memory and sections.
5.2.1 Example of linker script
Here is an example of a simple linker script.

SECTIONS
{
. = 0x10000;
.text : {*(.text)}
. = 0x8000000;
.data : {*(.data)}
.bss : {*(.bss)}
}

2024.10.30 28 Ver 1.0.9

 AT32 IDE User Manual
Note:
“. = 0x10000;”: The location counter is set to 0x10000 (the initial value is 0).
“.text : {*(.text)}”: Combine the “.text section” of all (“*” represents any input file) input files into
one “.text section”, and its address is specified by the location counter value, i.e., 0x10000.
“. = 0x8000000;”: Set the location counter value to 0x8000000.
“.data : {*(.data)}”: Combine the “.data section” of all input files into one “.data section”, and its
address is set to 0x8000000.
“.bss : {*(.bss)}”: Combine the “.bss section” of all input files into one “.bss section
“0x8000000+.data section”.
Every time the linker reads one section, the location counter value is incremented by the size of this
section.

5.2.2 Entry point

Syntax: ENTRY (symbol)
Definition: The first instruction to execute in a program is called the entry point.
Example:

/* Entry Point */
ENTRY(Reset_Handler)

Note: In AT32 projects, the default entry point is the “Reset_Handler” function.

5.2.3 Common commands

 ASSERT
Syntax: ASSERT(exp, message)
Ensure that “exp” is non-zero. If it is zero, then exit the linker with an error code, and print message.
Usage: Add an ASSERT when necessary to help locate problems.
Example:

/* The usage of ASSERT */

.test “
{
ASSERT ((_estack > (_Min_Stack_Size + _Min_Heap_Size)), “Error: There
is an ERR occurred”);
}

Note: An error message displays when the “_estack” is greater than the “_Min_Stack_Size +
_Min_Heap_Size”.
 PROVIDE
Syntax: PROVIDE(symbol = expression)
In some cases, it is desirable for a linker script to define a symbol only if it is referenced and is not
defined by any object included in the link.

2024.10.30 29 Ver 1.0.9

 AT32 IDE User Manual
Example:

PROVIDE (TEST_Symbol = .);

 HIDDEN
Syntax: HIDDEN(symbol = expression)
Usage: For the ELF target port, the symbol is hidden and not exported.
Example:

HIDDEN (TEST_Symbol = .);

 PROVIDE_HIDDEN
Syntax: PROVIDE _HIDDEN(symbol = expression)
Usage: It is used in the same way of PROVIDE, and it is the combination of PROVIDE and
HIDDEN.
Example:

PROVIDE _HIDDEN (__preinit_array_start = .);

 KEEP
Usage: When link-time garbage collection is in use (‘—gc-sections’), the KEEP() is often used to
mark sections that should not be eliminated.
Example:

/* The startup code goes first into FLASH */

.isr_vector :
{
. = ALIGN(4);
KEEP(*(.isr_vector)) /* Startup code */
. =ALIGN(4)
} >FLASH

2024.10.30 30 Ver 1.0.9

 AT32 IDE User Manual

6 Common functions
Install and upgrade AT32 IDE plug-ins
Artery continues developing new functions and MCUs supporting AT32 IDE to improve user
experience. This section introduces how to install and upgrade AT32 IDE plug-ins online and offline.
AT32 IDE plug-ins repository address: https://www.arterytek.com/download/at32ide_repository
6.1.1 Online installation and upgrade
Search for the desired plug-ins in the AT32 IDE plug-ins repository. Click [Help]>[Install New
Software…] to open the Install Dialog. Copy the plug-ins repository address to the “Work with:”, and
then AT32 IDE automatically starts to analyze all plug-ins in the plugin repository and then list all
plug-ins. Tick the plug-ins to be installed or upgraded, and untick “Contact all update sites during
install to find required software”; then click “Next” and “Finish to install the selected plug-ins.

Figure 31. Install plug-ins online

Click “Finish” to complete installation. Back to the AT32 IDE, there is an installation progress bar in
the lower right corner. Click “Progress” to view the installation progress. After the installation is
complete, the “Trust” dialog box will pop up. Click “Select All” and check “Always trust all content”.
Then, the “Always Trust Everything Configuration” dialog box pops up, and please click “Yes, I
Accept the Risk”. Go back to the “Trust” dialog box and click “Trust selected”, then the plug-in
upgrade is complete. The “Software Updates” dialog box pops up, and please click “Restart Now” to
restart AT32 IDE, as shown below.

2024.10.30 31 Ver 1.0.9

 AT32 IDE User Manual
Figure 32. Installation progress

Figure 33. Restart

If the plug-in has been installed, When the AT32 IDE starts, it will automatically detect whether the
plug-ins needs to be updated, or click [Help] > [Check for Updates] to perform the plug-ins update
detection. If a new version of the plug-in is detected, the “Available Updates” dialog box pops up,
listing all plug-ins that need to be updated.
Continue clicking “Next” and “Finish” to install the plug-ins.

Figure 34. Available Updates

2024.10.30 32 Ver 1.0.9

 AT32 IDE User Manual
6.1.2 Offline installation and upgrade
Download the offline installation package from Artery’s website:
Artery_AT32IDE_Plugins_Repository_V1.0.00.zip.
Select [Help]>[Install New Software…] to open a dialog box. Click “Add…” to open “Add Repository”
dialog box. Then, click “Archive…”, select “Artery_AT32IDE_Plugins_Repository_V1.0.00.zip”, and
click “Add”, as shown below.

Figure 35. Add plug-in offline installation package

The AT32 IDE will automatically analyze all the plug-ins in the project template zip package and
display them in the information list. Tick all items in the list and untick “Contact all update sites
during install to find required software”; then click “Next”, as shown below.

Figure 36. List of plug-ins to be installed

This list shows all the plug-ins that need to be installed. Click “Finish” to complete installation.

2024.10.30 33 Ver 1.0.9

 AT32 IDE User Manual
Back to the AT32 IDE, there is an installation progress bar in the lower right corner. Click “Progress”
to view the installation progress. After the installation is complete, the “Trust” dialog box will pop up.
Click “Select All” and check “Always trust all content”. Then, the “Always Trust Everything
Configuration” dialog box pops up, and please click “Yes, I Accept the Risk”. Go back to the “Trust”
dialog box and click “Trust selected”, then the plug-in upgrade is complete. The “Software Updates”
dialog box pops up, and please click “Restart Now” to restart AT32 IDE, as shown below.

Figure 37. Installation progress

Figure 38. Restart

Language setting
Select [Help] > [Change Language] to open the “Language” dialog box. Select the desired language
and click “OK”. Then, the “Restart” dialog box pops up, and please click “Yes” to restart AT32 IDE.
Finally, the language is set successfully, as shown below.

2024.10.30 34 Ver 1.0.9

 AT32 IDE User Manual
Figure 39. Change language

Open User Manual

Select [Help]>[Open User Manual] to open the AT32 IDE User Manual.

Resources update
Click “Resources update ” button in the toolbar, and the following interface pops up, as shown
below.

Figure 40. Resources Manager

The list in the dialog box displays the status of AT32 MCU BSP, where “Latest” represents the
current latest version, “Not Latest” indicates the current version is not the latest, and “Failed”
indicates updating failed.
For the “Not Latest”, tick the select box of this MCU, and then the “Update packages…” is available.
Click this button to automatically update BSP of the selected MCU. After successful updating, the
status becomes “Latest”. To delete the BSP, tick the MCU and then click the “Delete packages…”
button, and the BSP of this MCU is deleted.
To import local BSP package, select the MCU series and click “Import” in the toolbar, and then click
“Browse” in the pop-up “Import resource pack” (as shown in Figure 40) to select the BSP package;

2024.10.30 35 Ver 1.0.9

 AT32 IDE User Manual
then click “OK” to import and update the status automatically.

Figure 41. Import BSP

Note: The OpenOCD upgade will overwrite all existing files. If you have made modifications to the
configuration files, please back them up before upgrading your OpenOCD version.

Import MDK project

Users can directly import the AT32 MCU related MDK projects into AT32 IDE. After being imported,
MDK projects remain the original configuration, including the directory structure.
Note: Refer to the “Artery AT32 IDE Project Manager Tools” in Figure 30 in 5.1.1 for the import of
MDK projects. Currently, only mdk_v5 projects can be imported.

This section demos how to import a BSP mdk_v5 project into AT32 IDE.
MDK project directory:
AT32F423_Firmware_Library_V2.0.2\utilities\at32f423_boot_memory_ap_demo\read_write_boot_
memory\mdk_v5.

Right click (or click the [File]) in AT32 IDE project explorer window, click [Import] in the drop-down
menu and select “General->MDK5 Project into the Workspace” in the [Import] dialog, as shown
below.

2024.10.30 36 Ver 1.0.9

 AT32 IDE User Manual
Figure 42. Select an import wizard

Click [Browse…] to select the MCK projects (.uvprojx) to be imported, and the MDK project name is
filled in automatically in the “Project Name” (it can be modified by users as needed). Then, click
[Finish], and the MDK project is imported to AT32 IDE automatically and opened in the project
explorer, as shown below.

2024.10.30 37 Ver 1.0.9

 AT32 IDE User Manual
Figure 43. Import a MDK project

After the MDK project is imported successfully, a project directory named “at32_ide_proj” is created
in the sibling directory of the MDK project, as shown below.

Figure 44. AT32 IDE project directory

The project explorer displays the project directory structure, as shown below.

2024.10.30 38 Ver 1.0.9

 AT32 IDE User Manual
Figure 45. Project directory structure

After being imported, the MDK project can be compiled and debugged according to Section 3 and
Section 4.

2024.10.30 39 Ver 1.0.9

 AT32 IDE User Manual

7 FAQs
This section summarizes solutions to some common problems in use, which can be used as a
reference.
Configuration
1. Prompt information appears during compiling:
“Cannot run program “make”: Launching failed. Error: Program “make” not found in PATH”
Cause and solution: This is usually the case when the GCC Make is not configured properly. ARM
toolchain and GCC Make configuration paths are configured by default in AT32 IDE. If this prompt
information appears, it may be that the default configuration of GCC Make does not take effect.
In Windows system, the user needs to click on [Windows] -> [Preferences], and configure the
path as“${eclipse_home}/platform/tools/Build Tools/bin” in “Global Build Tools Path” of MCU
configuration. In addition, the Global Arm Toolchains Path is configured as
“${eclipse_home}/platform/tools/gcc-arm-none-eabi-10.3-2021.10/bin” by default.
In Linux system, it may be the case when GCC is not installed. In this case, the user needs to
set up GCC properly according to Section 2.2.2.

2. If you run the AT32 IDE after installing it for the first time, you need to download the BSP
firmware before creating the project. See 4.5.4 to download the BSP firmware and then create
the new project.

Debugging
1. Prompt information appears during debugging:
“Error: please select the matching algorithm
Error: auto_probe failed
Error: Connect failed. Consider setting up a gdb-attach event for the target to prepare target for
GDB connect, or use 'gdb_memory_map disable'.
Error: attempted 'gdb' connection rejected”
Cause and solution: Check if there are multiple AT-Link connections. If there are multiple AT-Link
connections, the MCU that needs to be debugged may not be found. If there is only one AT-Link
connection, check if the MCU is latched or if it is in a protected status.

2. Stuck during debugging, without error prompt.

Cause and solution: (1) Check whether the MCU part selected when building the project is the
same as the MCU part on the demo board.
(2) In the Debug configuration of ATLINK, the “Start GDB session” on the Debugger page is not
selected.
(3) Whether the Boot0 jumper is set to the high level in the development board.

Compilation
1. Error during compilation
Use GCC compiler to compile codes containing mathematical functions such as “sqrt()”, an error is
reported as below:

2024.10.30 40 Ver 1.0.9

 AT32 IDE User Manual
.../gcc-arm-none-eabi-10.3-2021.10/bin/../lib/gcc/arm-none-eabi/10.3.1/../../../../arm-none-
eabi/bin/ld.exe: ../gcc-arm-none-eabi-10.3-2021.10/bin/../lib/gcc/arm-none-eabi/10.3.1/../../../../arm-
none-eabi/lib/thumb/v7e-m+fp/hard\libm.a(lib_a-w_sqrt.o): in function `sqrt':
w_sqrt.c:(.text.sqrt+0x40): undefined reference to `__errno'
Cause analysis and solution:
GCC default header file does not include math library, that is, the math library is not a default library
file, which requires users to manually specify GCC to the math library during compilation.
Go to AT32 IDE project properties → GNU Arm Cross C Linker → Command lin pattern, and add
“-lm” to the end, as shown below.

Figure 46. Linker Configuration

2024.10.30 41 Ver 1.0.9

 AT32 IDE User Manual

8 Revision history
Table 1. Document revision history
Date Version Revision note
1. Added OpenOCD online updating function;
2. Added the function of double click .project and .cproject file to run AT32 IDE
2024.10.30 V1.0.9
and automati import of the current project;
3. Added the function of auto filling in the device name while setting up J-Link.
2024.02.05 V1.0.8 1. Added description of ld linker.
2023.11.17 V1.0.7 1. Added importing MDK_V5 projects for compiling and debugging.
2023.10.23 V1.0.6 1. The AT32 MCU project template creation plug-in supports automatic updates.
2023.09.05 V1.0.5 1. Support for AT32A403A/AT32F402/AT32F405.
2023.05.26 V1.0.4 1. Added the description of J-Link debugger configuration.
1. Added BSP online and offline updating functions;
2. Added download and erase functions;
2022.11.07 V1.0.3 3. Customize the folder name when creating the project;
4. Added automatic configurations of MCU (1024KB/4096KB Flash) profiles in AT-
Link debugger.
2022.09.26 V1.0.2 1. Added available Linux system.
2022.08.10 V1.0.1 1. Added Section 5 FAQs.
2022.05.26 V1.0.0 1. Initial release.

2024.10.30 42 Ver 1.0.9

 AT32 IDE User Manual

IMPORTANT NOTICE – PLEASE READ CAREFULLY

Purchasers are solely responsible for the selection and use of ARTERY’s products and services; ARTERY assumes no liability for
purchasers’ selection or use of the products and the relevant services.

No license, express or implied, to any intellectual property right is granted by ARTERY herein regardless of the existence of any previous
representation in any forms. If any part of this document involves third party’s products or services, it does NOT imply that ARTERY
authorizes the use of the third party’s products or services, or permits any of the intellectual property, or guarantees any uses of the third
party’s products or services or intellectual property in any way.

Except as provided in ARTERY’s terms and conditions of sale for such products, ARTERY disclaims any express or implied warranty,
relating to use and/or sale of the products, including but not restricted to liability or warranties relating to merchantability, fitness for a
particular purpose (based on the corresponding legal situation in any unjudicial districts), or infringement of any patent, copyright, or other
intellectual property right.

ARTERY’s products are not designed for the following purposes, and thus not intended for the following uses: (A) Applications that h ave
specific requirements on safety, for example: life-support applications, active implant devices, or systems that have specific requirements
on product function safety; (B) Aviation applications; (C) Aerospace applications or environment; (D) Weapons, and/or (E) Oth er
applications that may cause injuries, deaths or property damages. Since ARTERY products are not intended for the above-mentioned
purposes, if purchasers apply ARTERY products to these purposes, purchasers are solely responsible for any consequences or ri sks
caused, even if any written notice is sent to ARTERY by purchasers; in addition, purchasers are solely responsible for the compliance with
all statutory and regulatory requirements regarding these uses.

Any inconsistency of the sold ARTERY products with the statement and/or technical features specification desc ribed in this document will
immediately cause the invalidity of any warranty granted by ARTERY products or services stated in this document by ARTERY, an d
ARTERY disclaims any responsibility in any form.

© 2024 Artery Technology -All rights reserved

2024.10.30 43 Ver 1.0.9