HOLTEK e-Link32 Pro MCU Debug Adapter User Guide
- July 5, 2024
- HOLTEK
Table of Contents
HOLTEK e-Link32 Pro MCU Debug Adapter
Specifications
- Model : HT32 MCU SWD Interface
- Version : AN0677EN V1.00
- Date : May 21, 2024
- Interface : SWD (Serial Wire Debug)
- Compatibility : e-Link32 Pro / Lite, Target MCU
Product Information
The HT32 MCU SWD Interface is designed for programming, offline
programming, and debugging of target MCUs. It utilizes the SWD communication
protocol for efficient data transmission and debugging.
SWD Pin Description
The SWD interface consists of two main pins:
- SWDIO (Serial Wire Data Input/Output): Bi-directional data line for debug information transmission and code/data programming.
- SWCLK (Serial Wire Clock): Clock signal for synchronous data transmission.
Connection Description/PCB Design
The SWD interface requires a 10-pin connector with the following pin
descriptions:
| Pin No. | Name | Description |
|---|---|---|
| 1, 3, 5, 8 | VCC, GND | Power supply connections for the debug adapter and |
target
MCU.
2, 4| SWDIO, SWCLK| Data and clock signals for communication.
6, 10| Reserved| No connection required.
7, 9| VCOM_RXD, VCOM_TXD| Virtual COM ports for serial communication.
If designing a custom board, it is recommended to include a 5-pin SWD connector with VDD, GND, SWDIO, SWCLK, and nRST connections for compatibility with e-Link32 Pro/Lite.
Debug Adapter Level Shift Description
When connecting the debug adapter to the MCU hardware board, ensure that the
preset conditions are met to avoid any hardware conflicts.
Product Usage Instructions
- Connect the SWD interface of e-Link32 Pro/Lite to the target MCU using the provided connector.
- Ensure proper power supply connections between the debug adapter and the target MCU.
- Use appropriate software tools like e-Link32 Pro User Guide or Starter Kit User Manual for programming and debugging.
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.
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 e-Link32 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.
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.
- 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.
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.
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.
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.
- Check whether the D1 USB LED of the e-Link32 Pro/Lite remains illuminated.
- 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.
If the USB debug adapter fails to connect to the PC, refer to “Troubleshooting Step 2”.
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”.
- Click on the “Utilities” tab
- Check “Use Debug Driver”
- Click on the “Debug” tab
- Use “CMSIS-DAP Debugger”
- Check “Load Application at Startup”
- Click “Settings” on the right to open the “Options for Target” dialog box
- If the debug adapter has connected to the PC successfully, “Serial No” will display. If not then refer to” Troubleshooting Step 2”
- Check “SWJ” and select “SW” as Port
- 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.
- Click on the “Flash Download” tab
- Select “Erase Full Chip” or “Erase Sectors” as Download Function, then check “Program” and “Verify”
- 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.
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”.
- 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.
- Select the “Setup” tab in “Debugger” and select “CMSIS DAP” as Driver
- Select the “Interface” tab in “CMSIS DAP” and select “SWD” as Interface
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.
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.
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.
- 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.
- 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.
Common Error Messages
The following table shows a summary of common error messages between Keil and IAR.
When the debug adapter fails to connect to the PC, refer to “Troubleshooting Step 2”.
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”.
Keil – Message “Error: Flash Download failed – “Cortex-Mx” ”
- First check whether the compiled “Code Size + RO-data + RW-data Size” exceeds the target MCU specifications.
- Check whether the Flash Loader settings in the Keil Programming Algorithm are correct. Refer to the “Keil Debug Settings” section for details.
- 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!”
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.”
Check whether the compiled “Code Size + RO-data + RW-data Size” exceeds the target MCU specifications.
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”
When the SWD communication fails, it means that the debug adapter has failed to connect to the MCU. The following shows the possible reasons:
- 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.
- 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:….”
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”.
Troubleshooting
If users encounter problems when using the SWD, use the following steps to check in sequence.
-
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. -
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. -
Re-plug the e-Link32 Pro/Lite USB port.
-
Check whether the USB cable is undamaged and can communicate with the PC.
-
Check whether the e-Link32 Pro/Lite USB port is not loose.
-
Check whether the PC USB Port can operate correctly or replace the connected USB Port.
-
Restart the PC and reconnect the USB port.
-
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”. -
Check whether the SWDIO/SWCLK wire is too long?
Shorten the wire to less than 20cm. -
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.
- IAR: click “CMSIS DAP” in “Project →Options” and click the “Interface” tab to adjust the interface speed, as shown in the following figure.
-
Check whether the power supply is normal?
Check the following power supply conditions: -
Check whether all the GND pins are connected together to ensure the same reference voltage
-
Check whether the power supply of the debug adapter such as the e-Link32 Lite Pro is normal (USB VBUS 5V).
-
Check whether the target board is correctly connected to the power supply
-
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.
-
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. -
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. -
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”. 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. -
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. -
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. -
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” IAR : “Project →Download →Erase memory” -
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. -
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.
Reference Material
For more information, consult the Holtek official website:
https://www.holtek.com.
Revision and Modification Information
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 endeavours 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.
FAQ
Q: What is SWD and how does it differ from JTAG?
A: SWD (Serial Wire Debug) is a two-pin debug interface that offers a
more efficient debugging solution compared to JTAG, which requires four pins
for communication.
Q: How to connect the SWD interface to a custom board?
A: Design a board with a 5-pin SWD connector containing VDD, GND, SWDIO,
SWCLK, and nRST pins for compatibility with e-Link32 Pro/Lite.
References
Read User Manual Online (PDF format)
Read User Manual Online (PDF format) >>