holtek.comholtek.com/
User Guide for HOLTEK models including: e-Link32 Pro, e-Link32 Lite, e-Link32 Pro MCU Debug Adapter, e-Link32 Pro, MCU Debug Adapter, Debug Adapter, Adapter
21 mag 2024 — Holtek HT32 series of MCUs are based on an Arm Cortex -M core. The ... Refer to the e-Link32 Pro User Guide for details. ○ e-Link32 Lite: this is ...
File Info : application/pdf, 18 Pages, 4.49MB
DocumentDocumentTroubleshooting Guide for HT32 MCU SWD Interface Usage Problems
Troubleshooting Guide for HT32 MCU SWD Interface Usage Problems
D/N: AN0677EN
Introduction
Holtek HT32 series of MCUs are based on an Arm® Cortex®-M core. The core contains integrated Serial Wire Debug (SWD) ports namely SW-DP/SWJ-DP, which makes development, programming and debugging more convenient. However, during hardware design when using the SWD, users may encounter some abnormal situations, which affect project development. This application note provides users with a comprehensive troubleshooting guide for SWD interface problems and includes possible errors which may occur during connection, communication and other conditions. This guide will assist users to use the SWD interface more easily, saving development time to make the project more efficient.
Holtek has released a USB debugging tool named e-Link32 Pro/Lite, which has been developed based on the Arm® CMSIS-DAP reference design. By connecting the target board to the PC's USB port, users can program and debug the program on the target MCU via the SWD under the development environment or with a programming tool. The following figure shows the connection relations. This text will take the e-Link32 Pro/Lite as an example to introduce the SWD, common error messages and troubleshooting steps. The SWD related instructions and debug information are also used for a common USB debug adapter such as ULINK2 or J-Link.
Host PC
e-Link32 Pro / Lite
Target MCU
USB
SWD
USB Host
CMSIS-DAP
SW-DP
Figure 1. SWD Connection Diagram
AN0677EN V1.00
1 / 18
May 21, 2024
Troubleshooting Guide for HT32 MCU SWD Interface Usage Problems
Abbreviation description: SWD: Serial Wire Debug SW-DP: Serial Wire Debug Port SWJ-DP: Serial Wire and JTAG Debug Port CMSIS: Common Microcontroller Software Interface Standard DAP: Debug Access Port IDE: Integrated Development Environment
SWD Introduction
The SWD is a hardware interface widely used with the Arm® Cortex-M® series of MCUs for programming and debugging. The following section will illustrate the Holtek e-Link32 Pro and eLink32 Lite. The e-Link32 Pro has approximately the same architecture as the e-Link32 Lite, the main difference is that the e-Link32 Pro supports ICP offline programming. The following is a brief description: e-Link32 Pro: this is a Holtek standalone USB debug adapter, which supports In-Circuit
Programming, offline programming and debugging. Refer to the e-Link32 Pro User Guide for details. e-Link32 Lite: this is a Holtek Starter Kit internal USB Debug adapter, which can directly
program or debug on the target MCU without additional connections. Refer to the Starter Kit User Manual for details.
e-Link32 Pro
e-Link32 Lite
Figure 2. e-Link32 Pro and e-Link32 Lite
SWD Pin Description
There are two SWD communication pins: SWDIO (Serial Wire Data Input/Output): a bidirectional data line for debug information
transmission and code/data programming between the debug adapter and the target MCU.
AN0677EN V1.00
2 / 18
May 21, 2024
Troubleshooting Guide for HT32 MCU SWD Interface Usage Problems
SWCLK (Serial Wire Clock): a clock signal from the debug adapter for synchronous data transmission.
A traditional Joint Test Action Group (JTAG) interface requires four connection pins, while the SWD only requires two pins to communicate. Therefore, the SWD requires fewer pins and is more convenient to use.
Connection Description/PCB Design
The following figure shows the e-Link32 Pro/Lite interfaces.
Figure 3. SWD 10-Pin Connector
Pin No.
1
2 3 4 5 6 7 8 9
10
Name
Description
VCC
Debug adapter SWD interface Level Shift power supply by default, must be connected to the target MCU power supply
SWDIO Data signal, must be connected to the target MCU SWDIO pin
GND
Ground
SWCLK Clock signal, must be connected to the target MCU SWCLK pin
GND
Ground
Reserved Reserved pin, no connection required
VCOM_RXD The e-Link32 Pro/Lite provides two Virtual COM ports for serial communication. This is independent of the SWD. The connection is determined
VCOM_TXD based on the development environment and hardware requirements
GND
Ground
Reset
Used to control the target board reset signal - must be connected to the target MCU nRST pin
Table 1. SWD 10-Pin Description
If users need to design their own board, it is recommended to reserve an SWD connector, as shown in the following figure. The SWD interface must contain VDD, GND, SWDIO, SWCLK and nRST of the target MCU and which can then be connected to e-Link32 Pro/Lite via this connector for programming or debugging.
Figure 4. SWD 5-Pin Connector
AN0677EN V1.00
3 / 18
May 21, 2024
Troubleshooting Guide for HT32 MCU SWD Interface Usage Problems
Debug Adapter Level Shift Description
As the MCU may have different operating voltages in practical applications, the I/O logic voltage levels may also be different. The e-Link32 Pro/Lite provides a Level Shift circuit to adapt to different voltages. If the SWD Pin 1 VCC is used as a reference voltage in the above circuit, then the SWD pin input/output voltage on the e-Link32 Pro/Lite can be automatically adjusted according to the target MCU operating voltage, thus making it compatible with different MCU hardware board designs. Most debug adapters such as ULINK2 or J-Link have a similar design.
As can be seen from the above description, when the debug adapter is connected to the MCU
hardware board under a preset condition, it should be noted that the MCU hardware board will
provide power to the SWD VCC pin on the debug adapter, as shown in the following figure. This
means that the MCU hardware board must be connected to a power supply separately and the SWD
VCC pin on the debug adapter has no power output by default.
Target Board
Debug Adapter
MCU VDD
SWD 10-Pin Connector VCC
Figure 5. Target Board & Debug Adapter Power Supply Direction
The e-Link32 Pro/Lite Pin 1 VCC can also be set to output 3.3V to power the target MCU hardware board. However, it is important to pay attention to current and power supply limitations. Refer to the e-Link32 Pro User Guide for details.
Check whether the debug adapter USB is correctly connected
When the e-Link32 Pro/Lite is connected to the PC, check whether it is correctly connected using the following two methods.
1. Check whether the D1 USB LED of the e-Link32 Pro/Lite remains illuminated.
2. Press the "Win +R" buttons to call "Run" and enter "control printers" to run. When a "Printers & scanners" window appears, click on "Devices" and find "Other devices" from the drop-down menu. Then check whether a device named "CMSIS-DAP" or "Holtek CMSIS-DAP" appears, as shown in the following figure. It should be noted that different computer systems may have slightly different displays. Users can refer to this step to find and check whether this device appears.
Figure 6. CMSIS-DAP Device If the USB debug adapter fails to connect to the PC, refer to "Troubleshooting Step 2".
AN0677EN V1.00
4 / 18
May 21, 2024
Troubleshooting Guide for HT32 MCU SWD Interface Usage Problems
Keil Debug Settings
This section will take e-Link32 Pro/Lite as an example to illustrate the debug settings under the Keil development environment. Use the following steps to check step by step whether the settings are correct. First click on "Project Options for Target". 1. Click on the "Utilities" tab 2. Check "Use Debug Driver"
1
2
Figure 7. Keil - Options for Target - Utilities
3. Click on the "Debug" tab
4. Use "CMSIS-DAP Debugger"
5. Check "Load Application at Startup"
6. Click "Settings" on the right to open the "Options for Target" dialog box
3
4
6
5
Figure 8. Keil - Options for Target - Debug
7. If the debug adapter has connected to the PC successfully, "Serial No" will display. If not then refer to" Troubleshooting Step 2"
AN0677EN V1.00
5 / 18
May 21, 2024
Troubleshooting Guide for HT32 MCU SWD Interface Usage Problems
8. Check "SWJ" and select "SW" as Port 9. If the debug adapter has connected to the MCU successfully, the SWDIO table will display
"IDCODE" and "Device Name". Otherwise, refer to "Troubleshooting Step 3" and check each item sequentially from there.
7
9
8
Figure 9. Keil - Target Driver Setup - Debug
10. Click on the "Flash Download" tab 11. Select "Erase Full Chip" or "Erase Sectors" as Download Function, then check "Program" and
"Verify" 12. Check whether the HT32 Flash Loader exists in the Programming Algorithm. The following
shows the HT32 Flash Loader. HT32 Series Flash HT32 Series Flash Options If the HT32 Flash Loader does not exist, click "Add" to manually add it. If the HT32 Flash Loader cannot be found, install the Holtek DFP. Click on "Project - Manage - Pack Installer..." to find the Holtek DFP and install. Refer to the Arm Developer website or download the HT32 Firmware Library. Find "Holtek.HT32_DFP.latest.pack"in the root directory and install.
10 11
12
AN0677EN V1.00
Figure 10. Keil - Target Driver Setup - Flash Download
6 / 18
May 21, 2024
Troubleshooting Guide for HT32 MCU SWD Interface Usage Problems
IAR Debug Settings
This section will take the e-Link32 Pro/Lite as an example to illustrate the debug settings under the IAR development environment. Follow the following steps to check step by step whether the settings are correct. First click on "Project Options". 1. Click "General Options Target" and select the target MCU as the Device. If the
corresponding MCU cannot be found, download the "HT32_IAR_Package_Vx.x.x.exe" from the Holtek official website to install the IAR Support Package.
Figure 11. IAR - General Options 2. Select the "Setup" tab in "Debugger" and select "CMSIS DAP" as Driver
AN0677EN V1.00
Figure 12. IAR Debugger
7 / 18
May 21, 2024
Troubleshooting Guide for HT32 MCU SWD Interface Usage Problems
3. Select the "Interface" tab in "CMSIS DAP" and select "SWD" as Interface
Figure 13. IAR - CMSIS DAP
Check whether the SWD is correctly connected
When taking Keil as an example, click on "Project Options for Target" to select the "Debug" tab and click "Settings" on the right.
Figure 14. Keil - Options for Target - Debug
If the IDCODE and Device Name are displayed in the SWDIO table as shown in the following figure, it indicates that the SWD is correctly connected. Otherwise, if an error occurs, refer to the instructions in the "Connect Under Reset" section, or refer to the troubleshooting steps to check.
AN0677EN V1.00
8 / 18
May 21, 2024
Troubleshooting Guide for HT32 MCU SWD Interface Usage Problems
Figure 15. Keil - Target Driver Setup - Debug
Connect Under Reset
Connect Under Reset is a feature of the MCU core and SW-DP to pause the system before the program is executed. If a program behavior causes the SWD to be inaccessible, users can resolve the problem using this method. The common reasons why the SWD is inaccessible are as follows. 1. When the SWDIO/SWCLK pin-shared function is selected to have another function, such as
GPIO, the I/O will not be used for SWD communication. 2. When the MCU enters the Deep-Sleep mode or Power-Down mode, the MCU core will stop.
Therefore, it is not possible to communicate with the MCU core via the SWD for programming or debugging. Refer to Connect Under Reset settings below when using Keil. "Project" "Options for Target" "Debug" click "Settings" select "under Reset" as the Connect method, as shown in the following figure. Refer to "Troubleshooting Step 9" for the detailed Keil setting steps.
Figure 16. Keil - Connect Under Reset Setting
AN0677EN V1.00
9 / 18
May 21, 2024
Troubleshooting Guide for HT32 MCU SWD Interface Usage Problems
Common Error Messages
The following table shows a summary of common error messages between Keil and IAR.
IDE
Error Message
Troubleshooting
"No Debug Unit Device found"
Refer to "Troubleshooting Step 2"
"SWD/JTAG Communication Failure" Check one by one from "Troubleshooting Step 3"
"Error: Flash Download failed -
Keil Cortex-Mx"
(1) Check whether the image size exceeds the specification (2) Check the Keil - Flash Download setting (3) Refer to "Troubleshooting Step 10 and Step 11"
"Cannot Load Flash Programming Algorithm!"
Refer to "Troubleshooting Step 4 and Step 5"
"Flash Timeout. Reset the Target and try it again."
Check whether the image size exceeds the specification
"Fatal error: Probe not found"
Refer to "Troubleshooting Step 2 and Step 13"
IAR
(1) Check the IAR-MCU model "Fatal error: Failed to connect to CPU"
(2) Check one by one from "Troubleshooting Step 3"
"Failed to load flash loader:.... "
Refer to "Troubleshooting Step 4 and Step 5"
Table 2. Error Message Summary
Keil - Message "No Debug Unit Device found"
Figure 17. Keil - Message "No Debug Unit Device found" When the debug adapter fails to connect to the PC, refer to "Troubleshooting Step 2".
Keil - Message "SWD/JTAG Communication Failure"
Figure 18. Keil - Message "SWD/JTAG Communication Failure"
When the SWD communication fails, it means that the debug adapter has failed to connect to the MCU. Check one by one from "Troubleshooting Step 3".
AN0677EN V1.00
10 / 18
May 21, 2024
Troubleshooting Guide for HT32 MCU SWD Interface Usage Problems Keil - Message "Error: Flash Download failed - "Cortex-Mx" "
Figure 19. Keil - Message "Error: Flash Download failed - "Cortex-Mx" " 1. First check whether the compiled "Code Size + RO-data + RW-data Size" exceeds the target
MCU specifications. 2. Check whether the Flash Loader settings in the Keil Programming Algorithm are correct. Refer
to the "Keil Debug Settings" section for details. 3. Check whether the Page Erase/Program or Security protection is enabled. Refer to
"Troubleshooting Step 10 and Step 11" for details.
Keil - Message "Cannot Load Flash Programming Algorithm!"
Figure 20. Keil - Message "Cannot Load Flash Programming Algorithm!" Check whether the VCC and GND pins on the debug adapter are connected to that of the target MCU. Refer to "Troubleshooting Step 4" and "Step 5".
Keil - Message "Flash Timeout. Reset the Target and try it again."
Figure 21. Keil - Message "Flash Timeout. Reset the Target and try it again."
Check whether the compiled "Code Size + RO-data + RW-data Size" exceeds the target MCU specifications.
AN0677EN V1.00
11 / 18
May 21, 2024
Troubleshooting Guide for HT32 MCU SWD Interface Usage Problems IAR - Message "Fatal error: Probe not found"
Figure 22. IAR- Message "Fatal error: Probe not found" When the debug adapter is not connected to the PC, refer to "Troubleshooting Step 2" and "Step 13".
IAR - Message "Fatal error: Failed to connect to CPU"
Figure 23. IAR- Message "Fatal error: Failed to connect to CPU" When the SWD communication fails, it means that the debug adapter has failed to connect to the MCU. The following shows the possible reasons: 1. The target MCU model of the Device in "General Options" may be incorrect, refer to the "IAR
Debug Settings" section for details about how to modify this. 2. If the MCU cannot respond to the host via the SWD, check one by one from "Troubleshooting
Step 3".
IAR - Message "Failed to load flash loader:...."
Figure 24. IAR- Message "Failed to load flash loader:...." Check whether the VCC and GND pins on the debug adapter are connected to that of the target MCU. Refer to "Troubleshooting Step 4" and "Step 5".
AN0677EN V1.00
12 / 18
May 21, 2024
Troubleshooting Guide for HT32 MCU SWD Interface Usage Problems
Troubleshooting
If users encounter problems when using the SWD, use the following steps to check in sequence.
Step 1. Whether multiple USB debug adapters are connected to the system?
If multiple USB debug adapters such as e-Link32 Pro/Lite or ULINK2 are connected to the system simultaneously, remove them and retain only one group. This prevents misjudgment caused by simultaneous access of multiple debug adapters. Users can also select the debug adapter with a specific connection under the development environment.
Step 2. Check whether the debug adapter USB port is successfully connected?
If the D1 USB LED on the e-Link32 Pro/Lite is not illuminated or the corresponding device "CMSIS-DAP" is not found in "Printers & scanners", try to troubleshoot the error using the following method. 1. Re-plug the e-Link32 Pro/Lite USB port. 2. Check whether the USB cable is undamaged and can communicate with the PC. 3. Check whether the e-Link32 Pro/Lite USB port is not loose. 4. Check whether the PC USB Port can operate correctly or replace the connected USB Port. 5. Restart the PC and reconnect the USB port.
Step 3. Check whether the SWDIO/SWCLK/ nRST pins are connected?
Check whether the MCU SWDIO, SWCLK and nRST pins are actually connected to the debug adapter. Check whether the cable is not broken or the connection is disconnected. If the Holtek ESK32 Starter Kit is used, ensure that the Switch-S1 on the board is switched to "On".
Step 4. Check whether the SWDIO/SWCLK wire is too long?
Shorten the wire to less than 20cm.
Step 5. Check whether the SWDIO/SWCLK connect to protection components?
The serial protection components can cause SWD high-speed signal distortion, therefore the SWD transmission rate must be reduced. Adjust the transmission rate as follows: Keil: "Project Options for Target" select the "Debug" tab, and click "Settings" to adjust the Max Clock, as shown in the following figure.
AN0677EN V1.00
13 / 18
May 21, 2024
Troubleshooting Guide for HT32 MCU SWD Interface Usage Problems
Figure 25. Keil - Target Driver Setup - Max Clock IAR: click "CMSIS DAP" in "Project Options" and click the "Interface" tab to adjust the interface speed, as shown in the following figure.
Figure 26. IAR - CMSIS DAP - Interface speed
Step 6. Check whether the power supply is normal?
Check the following power supply conditions: 1. Check whether all the GND pins are connected together to ensure the same reference voltage 2. Check whether the power supply of the debug adapter such as the e-Link32 Lite Pro is normal
(USB VBUS 5V). 3. Check whether the target board is correctly connected to the power supply 4. Check whether the SWD Pin 1 VCC on the debug adapter is powered by the target board. Pin
1 VCC on the debug adapter connects to the VDD pin on the target MCU and should have an appropriate voltage.
AN0677EN V1.00
14 / 18
May 21, 2024
Troubleshooting Guide for HT32 MCU SWD Interface Usage Problems
Step 7. Check whether the Boot pin setting is correct
If the programming operation has been successful but the program does not execute, check whether the BOOT pin has been externally pulled-low. If yes, then remove this external signal. After a power-on or reset, the BOOT pin must be kept at a high level, after which the program in the Main Flash memory can execute normally. Refer to the MCU Datasheet for details on the BOOT pin position or the required level.
Step 8. Check whether the MCU configures SWDIO/SWCLK pin as GPIO or other functions?
If the SWDIO/SWCLK pin-shared function is selected to have a different function such as a GPIO by the MCU firmware, then when the program has executed to "AFIO switch SWDIO/SWCLK", the MCU will no longer respond to any SWD communication. This will make the target board present a state that cannot be programmed. In such cases, it can be restored by setting Connect under Reset. Refer to the Method 1 or Method 2 in Step 9 for details.
Step 9. Check whether the MCU has entered the power saving mode?
If the MCU has entered the Deep-Sleep mode or Power-Down mode by firmware, the registers in the MCU Cortex-M core cannot be accessed via the SWD. This makes the programming or debugging functions unavailable. Refer to the following two methods to restore this. The main principle here is to prevent the firmware in the Main Flash from operating, thus allowing the SWD communication to operate normally. Method 1 - Set the Connect Under Reset
Take Keil as an example for the IDE settings. Click on "Project Options for Target" to select the "Debug" tab, and then click on "Settings".
AN0677EN V1.00
Figure 27. Keil - Options for Target Debug
15 / 18
May 21, 2024
Troubleshooting Guide for HT32 MCU SWD Interface Usage Problems
Select Connect "under Reset", as shown in the following figure. Now the IDE can then program using the SWD normally. It is recommended to first erase the firmware in the Main Flash (refer to "Step 11" for the erase operation) to prevent from the SWDIO/SWCLK AFIO Switch or entering the power saving mode by the firmware.
Figure 28. Keil - Connect under Reset Setting Method 2
Pull-down the PA9 BOOT pin, reset or power it on again and execute an MCU Flash Erase. After the Erase has completed, release the PA9 pin. Refer to Step 11 for instructions on how to perform an erase via the IDE.
Step 10. Check whether the MCU has enabled Memory Page Erase/Write protection?
If the MCU has enabled Memory Page Erase protection, the protected memory page cannot be erased or modified. During an SWD page erase, when an error occurs because the protected page cannot be erased, a mass erase operation is required to resolve this problem. Here the MCU memory will be completely erased and removed from memory protection by a Mass Erase. Refer to "Step 11" for details.
Step 11. Check whether the MCU has enabled Security protection?
If the MCU has enabled Security protection, when an error occurs during an SWD page erase, a Mass Erase operation must be executed to erase the Option Byte to remove the memory protection. After a Mass Erase has completed, the MCU must reset or be powered on again. Keil: "Flash Erase"
AN0677EN V1.00
Figure 29. Keil - Mass Erase Method 16 / 18
May 21, 2024
Troubleshooting Guide for HT32 MCU SWD Interface Usage Problems
IAR: "Project Download Erase memory"
Figure 30. IAR - Mass Erase Method
Step 12. Check whether to reset the system after completing the programming?
After the program has been updated via the debug adapter, an MCU reset must be triggered before the system can start the program. The MCU reset can be triggered by either the nRST pin or by powering on again.
Step 13. Check whether the e-Link32 Pro/Lite firmware is the latest version?
If users still cannot program or debug using the SWD after completing the above troubleshooting steps, it is recommended to update the e-Link32 Pro/Lite firmware to the latest version. Download the new e-Link32 Pro ICP Tool from the Holtek official website and click on "Connect". If the e-Link32 Pro Lite version is older, an update message will automatically pop up, then click on "OK" to update the firmware.
Figure 31. e-Link32 Pro ICP Tool
AN0677EN V1.00
Figure 32. e-Link32 Pro/Lite Firmware Update Prompt Window
17 / 18
May 21, 2024
Troubleshooting Guide for HT32 MCU SWD Interface Usage Problems
Reference Material
For more information, consult the Holtek official website: https://www.holtek.com.
Revision and Modification Information
Date 2024.01.09
Author
Issue V1.00
Modification Information First Version
Disclaimer
All information, trademarks, logos, graphics, videos, audio clips, links and other items appearing on this website ('Information') are for reference only and is subject to change at any time without prior notice and at the discretion of Holtek Semiconductor Inc. and its related companies (hereinafter 'Holtek', 'the company', 'us', 'we' or 'our'). Whilst Holtek endeavors to ensure the accuracy of the Information on this website, no express or implied warranty is given by Holtek to the accuracy of the Information. Holtek shall bear no responsibility for any incorrectness or leakage.
Holtek shall not be liable for any damages (including but not limited to computer virus, system problems or data loss) whatsoever arising in using or in connection with the use of this website by any party. There may be links in this area, which allow you to visit the websites of other companies. These websites are not controlled by Holtek. Holtek will bear no responsibility and no guarantee to whatsoever Information displayed at such sites. Hyperlinks to other websites are at your own risk.
Limitation of Liability
In no event shall Holtek Limited be liable to any other party for any loss or damage whatsoever or howsoever caused directly or indirectly in connection with your access to or use of this website, the content thereon or any goods, materials or services.
Governing Law
The Disclaimer contained in the website shall be governed by and interpreted in accordance with the laws of the Republic of China. Users will submit to the non-exclusive jurisdiction of the Republic of China courts.
Update of Disclaimer
Holtek reserves the right to update the Disclaimer at any time with or without prior notice, all changes are effective immediately upon posting to the website.
AN0677EN V1.00
18 / 18
May 21, 2024