GDB Server Plug-In for Eclipse-based ARM® IDEs

Debug Configuration User Guide, v.1.06

1 Introduction
This user guide describes the basic process for setting up your debug connection for PEmicro hardware in the
GDB Server Plug-in for Eclipse-based ARM IDEs.
Note: PEmicro’s GDB Server functionality is fully integrated into NXP’s MCUXpresso IDE. For MCUXpresso
configuration instructions, please consult: http://www.pemicro.com/blog/index.cfm?post_id=130

A quick start guide is followed by a section that describes the various settings that can be used to configure
your setup. The PEmicro GDB Server Plug-in is fully tested and supported on the following operating systems:
• Windows® 7
• Windows 8
• Windows 10
• macOS® 10.12 Sierra
• OS X® 10.11 El Capitan
• OS X 10.10 Yosemite
• Debian 9.6
• Ubuntu 16.04
• RHEL/CentOS 7.5

2 GDB Server Plug-In On A Linux System

Using PEmicro hardware via the USB port within the development environment requires the USB drivers.
During installation of your software tool, it should attempt to install the LibUSB drivers automatically. However,
if the driver installation fails during the install, use the following steps to manually install PEmicro’s USB drivers
correctly onto the Linux operating system.

2.1 Manually installing PEmicro’s LibUSB drivers

LibUSB relies on a version of LibUSB to be present on the Linux machine. The shared object PEmicro's
libraries rely on libusb-0.1.so.4. This must either be an actual library or a symlink to the appropriate LibUSB
library. The following steps demonstrate how to install the necessary resources on CentOS/RHEL 7.5 (64-bit)
and Ubuntu 16.04 (64-bit).

•CentOS/RHEL 7.5 (64-bit), Ubuntu 16.04 (64-bit)

1. Open a console (terminal) window.
2. Change to the directory containing the PEmicro drivers [somedirectory]/libusb_64_32.
3. Run the setup.sh shell script with super user privilege. This can be done after entering the superuser
(su) account with the following command : sh ./setup.sh while in the same directory as the shell script.
Alternately, if the sudo command is valid for your login, the sudo sh ./setup.sh command may be used.

©2014-19 P&E Microcomputer Systems, Inc. Windows is a registered trademark of Microsoft, Inc..
Kinetis is a registered trademark of NXP Semiconductors ARM is a registered trademark of ARM Limited.
2.2 Default Ethernet firewall configuration for CentOS/RHEL 7.5
The default configuration of CentOS/RHEL 7.5 may block two separate ports which are used by the GDB
server: (1) Cyclone Programmer UDP packets, and (2) GDB server TCP packets if configured for external
access. Assuming that the GDB server would be configured to run on port 7224, the following commands (run
in the superuser account) will unblock both ports:

iptables -I INPUT 1 -p udp --dport 4468 -j ACCEPT

iptables -I INPUT 1 -p tcp --dport 7224 -j ACCEPT

These changes to the firewall configuration are temporary and will disappear at the next reboot. These settings
can be made persistent as well.

3 GDB Server Plug-in for Eclipse-based ARM IDEs - Quick Start Guide Using
PEmicro Hardware Interfaces
Use the following steps to get started setting up your debug connection in MCUXpresso, Kinetis Design Studio,
S32 Design Studio, or any other Eclipse-based development studio for PEmicro hardware.
Note: Some IDEs such as MCUXpresso, S32 Design Studio and Kinetis Design Studio come with a project wizard
that generates a launch configuration that is pre-populated with all relavant PEmicro debug interface settings.

1. After creating and building your project, navigate to Run -> Debug Configurations from the menu bar.
2. Select “GDB PEMicro Interface Debugging” from the left panel. Click on the New Launch Configuration
button to create a debug configuration.

PEmicro GDB Server Plug-in for Eclipse-based ARM IDEs - Debug Configuration User Guide 2
Figure 3-1: New Launch Configuration Button

3. Click on the “Debugger” tab. A new panel will appear allowing the user to specify PEmicro hardware
and settings. The user is required to specify the Interface, Port, and select the Device Name and Core.
For most setups, the remaining settings may be left as default. Refer to Section 4 - Changing PEmi-
cro Connection Settings for more details about each option.

PEmicro GDB Server Plug-in for Eclipse-based ARM IDEs - Debug Configuration User Guide 3
Figure 3-2: Specify Interface, Port, and Select Device & Core

4. Click Apply and Debug.

PEmicro GDB Server Plug-in for Eclipse-based ARM IDEs - Debug Configuration User Guide 4
4 Changing PEmicro Connection Settings
Connection settings for PEmicro hardware interfaces are configured in the Debug Configurations dialog box.
Options 1-27 are labeled in Figure 4-1, ending at the Exception Catching Settings area. The Exception
Catching Settings area is labeled in Figure 4-2.

Figure 4-1: PEmicro Launch Configuration Dialog Box

PEmicro GDB Server Plug-in for Eclipse-based ARM IDEs - Debug Configuration User Guide 5
Figure 4-2: PEmicro Launch Configuration Dialog Box - Exception Catching Settings

Table 1.1 describes the options for this view.

Table 1.1 Connection Parameter Options

Option Description

[1] Interface Use this option to select the interface type. Select a supported
interface from the list box. The options are:
• USB Multilink, USB Multilink FX, Embedded OSBDM/OSJTAG - USB
Port
• Cyclone - Serial Port
• Cyclone - USB Port
• Cyclone - Ethernet Port
• TraceLink - USB Port
• TraceLink - Ethernet Port
• OpenSDA
NOTE: Click on the “Compatible Hardware” link to help you
determine which PEmicro hardware is most suitable for your
project.

[2] Port This option selects the port over which debug communications is
conducted.
Select an available port from the list box.

[3] Select Device Selects the ARM processor being debugged.

[4] Core Allows the user to specify a core when using a multi-core device.

[5] Refresh Click this button to have the workstation scan for a valid interface
and port. Valid interfaces and ports appear in the Interface
and Port list boxes.

PEmicro GDB Server Plug-in for Eclipse-based ARM IDEs - Debug Configuration User Guide 6
 Option Description

[6] Specify IP (Cyclone Ethernet and Use this option to specify the IP address of a hardware interface
TraceLink Ethernet only) outside of the local network. Click on the checkbox to enable the
textbox. This will also override the port dropdown box. Currently
supports IPv4 only.

[7] Specify Network Card IP Use this option to specify the local network card IP address if
(Cyclone Ethernet and TraceLink there are multiple cards on your computer.
Ethernet only)

[8] Emergency Kinetis Device Performs a mass erase of the internal flash immediately upon
Recovery By Full Chip Erase connection. This is used to recover a device which was
incorrectly programmed with junk data in its reset vector.

[9] Use SWD Protocol Uses the 2-pin serial wire debug (SWD) protocol instead of
JTAG. SWD requires 2 fewer pins than JTAG.
Note: Some ARM devices require SWD protocol. Please check
the documentation for your device.

[10] Advanced Options Opens the Advanced Options Dialog. Advanced Options include:
Custom Trim, Preserving Memory Ranges, Daisy Chain Debug
Configuration, EEPROM Partitioning, and Alternative Algorithm
Selection. See CHAPTER 8 - Advanced Debug &
Programming Options for detailed information on these
options.

[11] Provide power to target Check this option to have the CYCLONE/FX, Tracelink or USB
(CYCLONE/FX, USB Multilink Multilink Universal FX (circuitry) supply power to the hardware
Universal FX and TraceLink only) target.
Uncheck this option to not provide power.
Note: For CYCLONE/FX programmers, setting power jumpers
1,2,& 3 configures Cyclone for internal power generation
to be provided to target via corresponding JTAG/SWD
power pin.
Note: For USB Multilink Universal FX, use the jumper settings
located at JP10 to provide either 3.3V or 5V. For Tracelink,
use the jumper setting located at J2 to allow VCC to the
target.

[12] Power off target upon software Check this option to turn off the power when the program
exit (CYCLONE/FX, USB Multilink terminates.
Universal FX and TraceLink only)
Uncheck this option to leave the hardware target powered
continuously.

[13] Regulator Output Voltage This option adjusts the output voltage that powers the hardware
(CYCLONE/FX, Tracelink only) target.
Select a voltage value from this option’s list box.
CAUTION An improper voltage setting can damage the board.

PEmicro GDB Server Plug-in for Eclipse-based ARM IDEs - Debug Configuration User Guide 7
 Option Description

[14] Power down delay (CYCLONE/ This option specifies amount of time for which the target will be
FX, USB Multilink Universal FX and turned off during a RESET power cycling sequence.
TraceLink only)
Enter the delay interval (in milliseconds) in this option’s text box.

[15] Power up delay (CYCLONE/FX, This option specifies amount of time for which the target will
USB Multilink Universal FX and remain powered prior to a RESET power cycling sequence.
TraceLink only)
Enter the delay interval (in milliseconds) in this option’s text box.

[16] Debug Shift Freq. Specifies the debug shift frequency (in KHz) of PEmicro’s
hardware debug interfaces. Faster shift frequencies result in
faster debug operations such as memory reads and flash
programming. However, this frequency cannot exceed 1/6 of the
target processor’s bus frequency.

[17] Delay After Reset And Before Specifies a delay after the programmer resets the target that we
Communicating to Target For... check to see if the part has properly gone into background debug
mode. This is useful if the target has a reset driver which hold the
MCU in reset after the programmer releases the reset line. The n
value is a delay in milliseconds.

[18] Launch Server Locally Automatically starts and stops the PEmicro GDB Server locally
for each debug session. Otherwise, the PEmicro GDB Server
needs to be started manually. In this case, the GDB Server must
be running before launching a debug session.

[19] GDB IP Address Specifies the IP Address of the PEmicro GDB Server. This
parameter is not used if the server is launched locally.

[20] GDBMI Port Number .Specifies the port on which the GDBMI frontend is listening.

[21] Server Port Number Specifies the base port on which the PEmicro GDB Server is
listening (default is 7224). The PEmicro server reserves 6
consecutive port numbers with multiple of 2 offsets for multi-core
debugging. Hence, specifying GDB port of 7224, will result in
GDB server listening on ports 7224, 7226, 7228, 7230, 7232,
7234.
The number of GDB server ports open during a debug session is
equal to the number of device cores present on a given device.

[22] GDB Server Parameters Specifies additional command-line parameters when the
PEmicro GDB Server is launched locally.

[23] Executable Specifies the path to the GDB client executable.

[24] Other Options Specifies additional command-line parameters to the GDB client.

[25] Commands Specifies additional commands to be executed by the GDB client

at startup.

PEmicro GDB Server Plug-in for Eclipse-based ARM IDEs - Debug Configuration User Guide 8
 Option Description

[26] Enable Streaming [Multilink FX only] If checked when using SWO, will stream
power measurement data to the Power Measurement window.
See more info about real-time power in Section 9.2 - Real-Time
Power Measurement.
Note: Enable streaming applies to: Multilink FX Rev. B or higher,
Multilink Universal Rev. D or higher, Multilink ACP Rev. B
for SWO ITM and printf data capture. The SWO power
settings can only be captured via Multilink FX when the
Multilink is used to provide power to the target.

[27] Streaming Server Port Specifies the port to use for Power Measurement data streaming.
See more info about real-time power in Section 9.2 - Real-Time
Power Measurement .

[28] Enable Hardfault Catch When checked, processor will halt if any Hardfault exception is
hit. Information on the exception will appear in the console.

[29] Enable Exception Entry/Return When checked, processor will halt if any Exception Entry/Return
Catch exception is hit. Information on the exception will appear in the
console.

[30] Enable Busfault Catch When checked, processor will halt if any Busfault exception is hit.
Information on the exception will appear in the console.

[31] Enable State Information Error When checked, processor will halt if any State Information Error
Catch exception is hit. Information on the exception will appear in the
console.

[32] Enable Checking Error Catch When checked, processor will halt if any Checking Error
exception is hit. Information on the exception will appear in the
console.

[33] Enable No Coprocessor Catch When checked, processor will halt if any Coprocessor exception
is hit. Information on the exception will appear in the console.

[34] Enable MemManage Catch When checked, processor will halt if any MemManage exception
is hit. Information on the exception will appear in the console.

[35] Enable Reset Vector Catch When checked, processor will halt if any Reset Vector exception
is hit. Information on the exception will appear in the console.

[36] Force Thread List Update On Specifies whether CDT should ask the GDB client for updated
Suspend thread information each time the target processor is suspended.

5 Attach Debug Session

PEmicro's Eclipse plugin supports the "attach" type of debug session. During an "attach" the GDB client is
launched in a way that does not disturb the state of a target device, i.e. it skips the FLASH programming and
reset steps which are a part of a standard PEmicro debug session.
Below is a detailed description of how detach/kill buttons within the Eclipse IDE are implemented:

PEmicro GDB Server Plug-in for Eclipse-based ARM IDEs - Debug Configuration User Guide 9
 Detach/Disconnect - Debug session exits with the device in running state
Kill/Terminate - Debug session exits with the device in the debug (not running) state
Attach - Connection does not disturb the device. If it is running, PEmicro leaves it running
and shows it to the user as such. If it is stopped, PEmicro shows it as stopped.
Attach Debug Session is enabled from within the Startup tab in PEmicro's debug configuration dialog (see
Figure 9-5).

Figure 5-1: Enable Attach Debug Session

6 Multi-Core Project Debug Configuration Settings

When working in S32 Design Studio for ARM devices you will able able to generate projects for multi-core
devices, such as the S32V234 (Treerunner) or the 57D54H (Halo). The project wizard will generate multiple
projects, one for each core, when a multi-core project is created. To be able to debug multiple cores, the main
core’s debug session needs to flash program the ELF files for all cores. The PEmicro plug-in aggregates all

PEmicro GDB Server Plug-in for Eclipse-based ARM IDEs - Debug Configuration User Guide 10
 binary information for programming, however the debug session will only display debug information for the
specific core being debugged. Then an “attach debug session” is used to debug the other cores, otherwise
starting multiple debug sessions on different device cores without attaching will reprogram the flash.
Note: Ensure the main core’s project sets the reset vector and turns on the secondary cores. Otherwise the debug
session for the other cores will not work.

To properly debug all of the cores, follow these steps in order:

6.1 Main Core

1. Set up the debug configuration for the main core, if not already done by the project wizard. The main
core is responsible for programming the object files for all device cores. In the Main tab, the settings
for the main core must specify all of the ELF files to flash program. Use the Generate ELF Fields but-
ton to populate multiple lines and Browse to specify the ELF files for the other core. The main core’s
ELF file is already being loaded as the C/C++ Application setting which allows the debugger to load
debug information, in addition to object files for source-level run control debugging.

PEmicro GDB Server Plug-in for Eclipse-based ARM IDEs - Debug Configuration User Guide 11
Figure 6-1: Main Tab of Main Core Debug Configurations

2. Setup the PEmicro hardware interface on the main core. Within the Debugger tab, select the PEmicro
hardware interface and ensure that correct Device Name is selected and that the main core is
selected under the Core option. Please read CHAPTER 3 - GDB Server Plug-in for Eclipse-based
ARM IDEs - Quick Start Guide Using PEmicro Hardware Interfaces to learn about all of the set-
tings.
3. Check the Startup tab. For the main core, the checkbox for Attach to Running Target should not be
checked.
4. Click on the Debug button to start the main core’s debug session. The PEmicro plug-in will erase and
flash program all of the ELF files. The debug session will then load the object information from an ELF
file for the main core. Run or step past the initialization of the other cores so that they are enabled.

6.2 Secondary/Other Cores

5. Set up the debug configuration for the other cores. Each core needs to load its own debugging infor-

PEmicro GDB Server Plug-in for Eclipse-based ARM IDEs - Debug Configuration User Guide 12
 mation. Check the Main tab and check that the C/C++ Application setting is set to the correct ELF
file.

Figure 6-2: Main Tab of Secondary Core Debug Configurations

6. Setup the Debugger Tab for the other cores. If a flash programming and debug session has already
been launched on the main core, the other cores can be attached to the same PEmicro hardware inter-
face for a multi-core user experience. Ensure that the Device Name and Core settings are properly
set up for the correct core for each debug session.

PEmicro GDB Server Plug-in for Eclipse-based ARM IDEs - Debug Configuration User Guide 13
Figure 6-3: Startup Tab of Main Core Debug Configurations

Note: Multiple core debug sessions can be launched as both local or remote sessions. Our recommendation is for
the user to launch both debug sessions locally on the same IP address.

PEmicro GDB Server Plug-in for Eclipse-based ARM IDEs - Debug Configuration User Guide 14
Figure 6-4: Debugger Tab of Secondary Core Debug Configurations

7. Set up the Startup tab for the other cores. The checkbox for Attach to Running Target needs to be
checked, otherwise the debug session will erase and program the flash again, thereby disrupting an
ongoing debug session running on the main core.
Note: For RAM based projects, the user may want to specify a PC value as an entry point for a secondary debug
session. For FLASH based projects, please leave the Set PC checkbox and corresponding value box
unchecked.

PEmicro GDB Server Plug-in for Eclipse-based ARM IDEs - Debug Configuration User Guide 15
Figure 6-5: Startup Tab of Secondary Core Debug Configurations

8. Click on the Debug button to start the other core’s debug session. The attach session will only load the
debug information. If the other cores are set up to already be running when enabled, then the attach
session will start up as running.
Note: In the latest version of the software, terminating a single core debug session does not terminate debug
sessions for all cores. Running, stepping, setting breakpoints, and inspecting registers and variables will still
not affect the other cores and will only execute on the core in the currently selected project perspective.

PEmicro GDB Server Plug-in for Eclipse-based ARM IDEs - Debug Configuration User Guide 16
7 Debugging Multiple ARM devices In Parallel
The PEmicro GDB Server Plug-In for Eclipse-based ARM IDEs allows the user to debug multiple ARM devices
in parallel, as long as they are connected to different PEmicro hardware interfaces. In order to properly set up
this usage case, the user has to make sure that parallel GDB debug sessions are launched on multiple, non-
conflicting GDB server ports.

Figure 7-1: Multiple Devices In Parallel - Unique Base Ports

Please keep in mind that PEmicro's GDB server reserves 6 consecutive port numbers with offsets in multiples
of 2. Hence, specifying GDB port of 7224 will result in the GDB server listening on ports 7224, 7226, 7228,
7230, 7232, 7234. Therefore, if the base port 7224 was specified for the first debug session, the base port for

PEmicro GDB Server Plug-in for Eclipse-based ARM IDEs - Debug Configuration User Guide 17
 the second debug session has to start at the value of 7235 or higher.

8 Advanced Debug & Programming Options

PEmicro’s GDB Server Plug-ins for Eclipse-based ARM IDEs v.1.20 and higher support a collection of
advanced debug and FLASH programming features. The Advanced Options dialog can be opened from the
Launch Configuration Dialog of any MCUXpresso/KDS/S32 Design Studio (etc.) project.

Figure 8-1: Advanced Options Button

Advanced options include: Custom Trim, Preserving Memory Ranges, Daisy Chain Debug Configuration,
EEPROM Partitioning, and Alternative Algorithm Selection.

PEmicro GDB Server Plug-in for Eclipse-based ARM IDEs - Debug Configuration User Guide 18
Figure 8-2: Advanced Options Dialog

8.1 Custom Trim

NXP’s Kinetis devices can be trimmed to a specific center frequency within a frequency range specified in the
device manual. If the custom trim feature is enabled, PEmicro’s FLASH Programmer will calculate a trim value
for a given frequency with .02% accuracy. Trim value will then be programmed into dedicated non-volatile
memory registers. The user should then manually copy the trim value into the clock configuration registers to
update the device start-up initialization routine.

8.2 Preserve Range

PEmicro GDB Server Plug-in for Eclipse-based ARM IDEs - Debug Configuration User Guide 19
 You have the option of preserving up to three independent ranges of non-volatile memory.
Ranges that are designated as "preserved" are read before an erase and re-programmed immediately
afterwards, thereby preserving the data in these ranges. Any attempt to program data into a preserved range is
ignored. When entering an address into the preserved range field (hexadecimal input is expected) the values
are masked according to the row size of the device. This ensures that the re-programming of preserved data
does not cause any conditions that disturb programming.

8.3 EEPROM Partition

Setting the Enable Partitioning checkbox enables you to partition certain Kinetis chips. To set up partitioning
you must provide 16 bits in hexadecimal format.
The first set of 4 bits represents the EEPROM Split Factor (EEESPLIT), which determines the relative size of
the two EEPROM subsystems. This set must be in the range of 0x0 to 0x03.
The second set of 4 bits represents the EEPROM size (EEESIZE), which determines the total available
FlexRAM for EEPROM use. This set must be in the range of 0x0 to 0xF.
The last 8 bits represents the FlexNVM Partition Code (DEPART), which specifies how to split the FlexNVM
block between data flash and EEPROM backup memory supporting EEPROM functions. This must be in the
range of 0x00 to 0x0F.
Refer to the reference manual specific to the device you are working with for more information on how to
specify the EEPROM Data Set Size and FlexNVM Partition Code.
Note: This option is only available for Kinetis K-series devices with Flex memory.

8.4 Initialization Script Selection

Initialization Script Selection functionality allows the user to specify a custom initialization script to run at the
beginning of a debug session. This functionality can be helpful in initializing onboard resources such as
external memory or a watchdog timer outside of the actual debug project. In order to enable the Initialization
Script Selection feature, the user needs to check the Enable Initialization Script checkbox and point to an
initialization macro file with the .mac extension. Commands in the following format should further be used to
initialize desired registers with specific initialization values:

mm.l $register_location $new_register_value

Example:

REM /* Enable MMDC with CS0 */

mm.l $400A2000 $83010000 ;MMDC->MDCTL.R = 0x03010000 + 0x80000000;

8.5 Daisy Chain

JTAG Daisy Chaining allows users to communicate with multiple JTAG devices on the same bus by connecting
the TDO of one device to the TDI of the next device. This works because JTAG is essentially a series of shift
registers chained together where bits are shifted into TDI and out onto TDO. By keeping track of the number of
IR bits used by each device, the device being communicated with can be selected.
Two variables must be configured in order to use JTAG daisy chaining:
• jtag_tap_num The nth JTAG device of the daisy chain.

PEmicro GDB Server Plug-in for Eclipse-based ARM IDEs - Debug Configuration User Guide 20
 • jtag_numbits_pre_ir The number of IR bits following the selected TAP. ARM devices always
consume 4 IR bits each so this value can be determined as follows:
pre_ir = 4*(total_devices - tap_num)

Figure 8-3: Daisy Chain Configuration

8.6 Alternative Algorithm

Once you create a project for a specific ARM microprocessor the debugger specifies a default algorithm to use
during all Flash programming operations. The debugger uses this algorithm for nearly all programming
requirements. The default algorithm can be found in <Eclipse_IDE_Installation_Folder>/eclipse/plugins/
com.pemicro.debug.gdbjtag.pne_xxx/win32/gdi/P&E/supportFiles_ARM/NXP/<device_family>. However, you
can override the default algorithm via the Alternative Algorithm function. This feature can be used to select a
custom programming algorithm, or to select another one of PEmicro's many programming algorithms for use
with a specific project.

Warning: Selecting the incorrect programming algorithm may damage your device, lead to under/over programming
situations, or result in failure to program portions of the project file. Therefore it is recommended to use the
default algorithm unless there is a compelling reason to do otherwise.

9 SWO Debug Tools

PEmicro’s GDB Server can take advantage of four useful SWO debug tools:
• Power Measurement

PEmicro GDB Server Plug-in for Eclipse-based ARM IDEs - Debug Configuration User Guide 21
 • SWO ITM Console
• SWO Data capture
• Real-Time Expressions.
This section describes how to enable and use these features.
Note: To set up streaming for SWO debug features, the user should check the “Enable Streaming” checkbox in
Debug Configurations during setup. Then the port should be specified in the Streaming Server Port text box.
See Figure 4-1.

9.1 Hardware Requirements

The following versions (or later) of PEmicro hardware interfaces are required to take advantage of SWO
streaming functionality:

• Multilink FX Rev. C
• Multilink Universal Rev. D
• Multilink ACMP Rev. B

9.2 Real-Time Power Measurement

To enable Power Measurement capture, an active debug session must already be in process. Click the Gear
Icon on the title bar of the PEmicro "Power Measurement” window. Select the frequency of data capture and
check the Enable box. After clicking OK, Power Recording is now active.
Note: The Multilink FX debug probe is required for Real-Time Power Measurement

Figure 9-1: Power Configuration Dialog

The next time the target MCU is run, real-time power measurement readings will be shown.

PEmicro GDB Server Plug-in for Eclipse-based ARM IDEs - Debug Configuration User Guide 22
Figure 9-2: Data Streamed To Power Measurement Window

The user can start/stop power recording, zoom, export data, and more

9.3 SWO Printf Console

The SWO Printf Console will display messages which are streamed through the SWO pin and captured by the
Multilink. There are two main configuration steps needed to leverage this feature. First, the project must be
configured to re-direct the printf() statements to the SWO Printf peripheral. This is done at project creation
time.
Second, the green "Play" button on the SWO ITM Console needs to be clicked during an active debug session.
This will cause data collection of SWO printf information to occur on the next Resume. Once data is streaming,
the red “Stop” button will stop data streaming.

Figure 9-3: Printf() Statements Displayed In SWO ITM Console

The Multilink automatically measures the data communication rate on the SWO pin and adjusts to it
automatically. This auto-detect sequence is done each time the processor is stopped in debug mode. If the
running code changes the core frequency, a breakpoint should be set after the frequency change so the
Multilink can adjust to the new SWO communications rate (which is a function of the core frequency).

9.4 SWO Data capture

The SWO Data view allows the user to configure variables to be tracked such that any reads and writes to
these variables are captured and streamed to the Multilink via the SWO pin. This view shows all of the real-
time access which have occurred along with the timing of the different accesses.
For SWO data, there is a bit more setup. The user needs to select the 'Eyeglasses+' symbol which will bring

PEmicro GDB Server Plug-in for Eclipse-based ARM IDEs - Debug Configuration User Guide 23
 up a popup of Add datawatch items. Simply enter the information of the different variables to be tracked. Up to
four separate variables can be tracked simultaneously. In this example, we select that we wish to capture read
and writes of the ledsOn and seconds variables. Once added, the user needs to select which watches data will
be captured by checking the "Enable trace" boxes in the SWO Data window and then click the Green Arrow to
set the program to start capture on Resume.Upon resuming the application, the right side of the window will
show the access which are occurring. Note that this happens in real-time; the microcontroller is not stopped
when accesses occur (i.e. the is separate from data breakpoints).

Figure 9-4: Variable Read/Writes Displayed In Real Time

The Multilink automatically measures the data communication rate on the SWO pin and adjusts to it
automatically. This auto-detect sequence is done each time the processor is stopped in debug mode. If the
running code changes the core frequency, a breakpoint should be set after the frequency change so the
Multilink can adjust to the new SWO communications rate (which is a function of the core frequency).

9.5 Real-Time Expressions

This view is similar to the standard Eclipse "Expressions" window with the exception that its contents will
update in real-time without the device being halted in debug mode. Just add the appropriate variables to the
Real Time Expressions window and you will see them updating in real-time.

PEmicro GDB Server Plug-in for Eclipse-based ARM IDEs - Debug Configuration User Guide 24
Figure 9-5: Add Variables To Real-Time Expressions Windows

10 Attach Debug Session

PEmicro's Eclipse plugins v2.0.8 and higher now support the "attach" type of debug session. During an
"attach" the GDB client is launched in a way that does not disturb the state of a target device, i.e. it skips the
FLASH programming and reset steps which are a part of a standard PEmicro debug session.
Below is a detailed description of how detach/kill buttons within the Eclipse IDE are implemented:
Detach - Debug session exits with the device in running state
Kill - Debug session exits with the device in the debug (not running) state
Attach - Connection does not disturb the device. If it is running, PEmicro leaves it running and shows it
to the user as such. If it is stopped, PEmicro shows it as stopped.
Attach Debug Session is enabled from within the Startup tab in PEmicro's debug configuration dialog (see
Figure 9-5).

PEmicro GDB Server Plug-in for Eclipse-based ARM IDEs - Debug Configuration User Guide 25
Figure 10-1: Enable Attach Debug Session

11 PEmicro Semi-Hosting Support Configuration

Semihosting is a technique to do printf() debugging through an active debug connection. So instead of using a
physical connection like RS-232 or USB CDC, the connection to the host machine is through the debugger.
For the exact steps on how to create a sample semi-hosting project under an Eclipsde-based IDE, please view
the following informative blog post by Erich Styger:
http://mcuoneclipse.com/2014/06/06/semihosting-with-kinetis-design-studio/
To enable semi-hosting output please open the Debug Configurations dialog, then follow these steps:
1. In the Debug Configurations dialog, select the launch configuration under the “GDB PEMicro Interface
Debugging” group
2. Open the “Startup” tab and make sure that the “Enable semihosting” box is checked with a “Console
routed to Telnet” configuration

PEmicro GDB Server Plug-in for Eclipse-based ARM IDEs - Debug Configuration User Guide 26
Figure 11-1: Steps To Enable Semi-Hosting

12 Real Time Expressions View

PEmicro's Eclipse plug-ins v.2.8.1 and higher now include a “Real Time Expressions” view. The “Real Time
Expressions” view periodically updates the contents of global variables while the target is running. This view
also has the option to halt the variables’ refresh mechanism if needed. To show this view, please follow the
instructions below:
1. Navigate to Window -> Show View -> Other …

Figure 12-1: Navigate To Window -> Show View -> Other...

PEmicro GDB Server Plug-in for Eclipse-based ARM IDEs - Debug Configuration User Guide 27
 2. In the “Show View” dialog, select “Real Time Expressions” under the “PE Microcomputer Systems” cat-
egory

Figure 12-2: Select “Real Time Expressions”

The “Real-Time Expressions” view is shown below:

Figure 12-3: Real-Time Expressions View

PEmicro GDB Server Plug-in for Eclipse-based ARM IDEs - Debug Configuration User Guide 28
 Once the view is displayed, you can add global variables to the view. After that, no other configuration is
needed. The refresh mechanism is enabled by default when the target runs. Values that are refreshed are
highlighted in blue text.

Figure 12-4: Refreshed Values Highlighted In Blue

If there is a need to halt the refresh mechanism, the user may press the “Halt” button to freeze the values.

Figure 12-5: Halt Button Pauses Refresh

Pressing the button again will re-enable the refresh mechanism:

Figure 12-6: Halt Button When Refresh Is Paused Will Resume Refresh

12.1 Limitations
For pointers that are constantly changing values, the values from dereferencing the same pointer may not be

PEmicro GDB Server Plug-in for Eclipse-based ARM IDEs - Debug Configuration User Guide 29
 accurate. This limitation is highlighted in grey:

Figure 12-7: Dereferenced Pointer

Please note that the “Real Time Expressions” view is not currently available for the E200 architecture or Multi-
Core debugging.

13 FreeRTOS Support
PEmicro's kernel aware debugging support for FreeRTOS provides full thread context information in multi-
threaded applications.

13.1 Enabling FreeRTOS Kernel Aware Debugging

The GDB Server plug-in will automatically detect the presence of FreeRTOS by default and requires no action
from the user to enable it. Successful detection of the kernel depends on the ability to find debug symbol
information for the related data structures.

13.2 Disabling Kernel Aware Debugging

There may be situations where the user wishes to disable FreeRTOS support. For example, due to
performance concerns during an interactive debugging session when the application contains many active
threads. To do so, the user must add the option '-kernel=none' to the server parameters box as shown in
Figure 13-1 below.

PEmicro GDB Server Plug-in for Eclipse-based ARM IDEs - Debug Configuration User Guide 30
Figure 13-1: Use Server Parameters To Disable FreeRTOS Support

13.3 Using FreeRTOS support

Stack information for all executing threads is automatically added to the debug window. The user's code view
is automatically updated to the thread selected by the user in the debug window. Further, the registers inside
the register view will reflect the register state for the currently selected thread.
You can number these panels going clockwise starting from the top left
1. Debug window, this is where stack information is stored
2. Register view, this displays the registers for the thread selected in (1.)
3. Code view, this is what's automatically updated based on where you clicked in (1.)

PEmicro GDB Server Plug-in for Eclipse-based ARM IDEs - Debug Configuration User Guide 31
Figure 13-2: Counter-Clockwise From Top Left: Debug Window, Code View, Register View

13.4 Limitations
Our implementation is only guaranteed to work on FreeRTOS 9.0.0 and has been tested against all ARM
Cortex-M based ports. For the best results, use the official NXP ports of FreeRTOS.
There is no way to force a context switch. Step and resume functionality will always apply to the real thread at
which the processor is halted. To switch between threads, please set a breakpoint at the desired thread.
There are situations where Eclipse has not properly refreshed the debug views, which results in an incomplete
stack. Stepping the thread one instruction will force an accurate refresh.

14 Exception Catching
ARMv7-core devices have the ability to halt when specified exceptions occur. If exception catching is enabled,
the processor will halt when a user's code hits the corresponding fault handler. Exception catching serves as
an aid in development by alerting users in real-time about exceptions that occur in their code.
All of our plugins from v3.96 onward include options for exception catching, and return information to the user
about the exceptions that have occurred. By default, we enable exception catching on all types of faults.

14.1 Enabling Exception Catching

For ARMv7 cores, there is a register called the Debug Exception and Monitor Control Register (DEMCR), in
which bits [10:0] control stopping on different types of exceptions.
For example, if bit 4, VC_MMERR, is set, a halting debug trap is enabled on MemManage exceptions. If any
MemManage exception is hit, the processor will halt at the existing MemManage handler, if MemManage faults
are enabled. If MemManage faults are disabled, a MemManage exception will escalate to a HardFault, and
can be halted by setting the VC_HARDERR bit.

PEmicro GDB Server Plug-in for Eclipse-based ARM IDEs - Debug Configuration User Guide 32
 All of our plugins from v3.96 onward include options to halt on
• HardFaults,
• Exception Entry/Return,
• BusFaults,
• State Information Errors,
• Checking Errors,
• No-Coprocessor faults
• MemManage faults
• Resets.
By default, we enable exception catching on all types of faults. The user can view the Exception Catching
Settings in Figure 4-2.

14.2 Returning Information About Faults

In addition to exception catching, information about the types of faults that occurred and can be found in the
Configurable Fault Status Register (CFSR) and HardFault Status Register (HFSR) in the System Control Block
(SCB). Information about the addresses at which BusFaults and MemManage faults occur can be found in the
32-bit BusFault Address Register (BFAR) and MemManage Fault Address Register (MMFAR), respectively,
when their corresponding Address Register VALID bits in the CFSR are set.
For example, if the CFSR reads 0x00000082, you would know that a MemManage Fault occurred because
"the processor attempted a load or store at a location that does not permit the operation" (DACCVIOL) and that
the MMFAR contains the address at which this fault occurred (MMARVALID). More guidance on reading these
bits can be found in the Arm v7-M Architecture Reference Manual or in Keil's "Using Cortex-M3/M4/M7 Fault
Exceptions" application note.
All of our plugins from v3.96 onward will return fault information to the user. Each time the processor halts,
information on all exceptions that have occurred since the last halt will be printed in the Console. BusFaults
and MemManage faults will also include information about the location at which the fault occurred.

PEmicro GDB Server Plug-in for Eclipse-based ARM IDEs - Debug Configuration User Guide 33