J-Link GDB Server

From SEGGER Wiki
Jump to: navigation, search
J-Link GDB Server UI

The GNU Project Debugger (GDB) is a freely available and open source debugger, distributed under the terms of the GPL. It can be used in command line mode, but is also integrated in many IDEs like emIDE or Eclipse. The latest Unix version of the GDB is freely available from the GNU committee under: GNU.org

J-Link GDB Server is a remote server for GDB making it possible for GDB to connect to and communicate with the target device via J-Link. It is free of charge and part of the J-Link Software and Documentation Pack, which is available for download on the SEGGER webpage. J-Link GDB Server and GDB communicate via a TCP/IP connection, using the standard GDB remote protocol. The J-Link GDB Server receives the GDB commands, handles the J-Link communication and replies with the answer to GDB.

With J-Link GDB Server debugging in ROM and Flash of the target device is possible and the Unlimited Flash Breakpoints feature is available, if supported by the used J-Link. The J-Link GDB Server also supports some functionality not directly implemented in the GDB, but accessible via monitor commands, sent directly with GDB.

Both, the GUI and the CL version, are available for Windows, Linux and Mac.

Contents


J-Link GDB Server CL

J-Link GDB Server CL is a commandline-only version of the GDB Server. The command line version is also part of the J-Link Software and Documentation Pack.

Except for the missing GUI, J-Link GDB Server CL is identical to the normal version. Therefore, all sub-chapters apply to the command line version, too.

Debugging with J-Link GDB Server

Before starting J-Link GDB Server make sure a J-Link is connected to the computer and the target device is powered and connected to the J-Link. With J-Link GDB Server, programs can be debugged via GDB directly on the target, similar to when debugging with a direct connection. The application can be loaded into RAM or flash of the device.

Setting up GDB Server GUI version

The GUI version of the J-Link GDB Server (JLinkGDBServer.exe/JLinkGDBServerExe) is part of the J-Link Software and Documentation Pack . When starting J-Link GDB Server a configuration dialog pops up, letting you select the needed configurations to connect to J-Link and target.

J-Link GDB Server: Configuration dialog


All configurations can optionally be passed via command line options.

NOTE: To make sure the connection to the target device can be established correctly, the device, as well as the interface and interface speed have to be given on start of GDB Server, either via command line options or the configuration dialog. If the target device option -device is given, the configuration dialog will not pop up.

Setting up GDB Server CL version

Calling under Windows

To start J-Link GDB Server CL on Windows, open the 'Run' prompt (Windows-R) or a command terminal (cmd) and enter

<PathToJLinkSoftware>\JLinkGDBServerCL.exe <CommandLineOptions>.

Calling under Linux / Mac

To start J-Link GDB Server CL on Linux / Mac, open a terminal and call JLinkGDBServer <CommandLineOptions>

Note regarding command line options:
When using GDB Server CL, at least the mandatory command line options have to be given. Additional command line options can be given to change the default behavior of GDB Server. For more information about the available command line options, please refer to Command line options.

GDB Server user interface

J-Link GDB Server: UI (waiting for conenction)

The J-Link GDB Server's user interface shows information about the debugging process and the target and allows to configure some settings during execution.
It shows following information:

  • The IP address of host running debugger.
  • Connection status of J-Link.
  • Information about the target core.
  • Measured target voltage.
  • Bytes that have been downloaded.
  • Status of target.
  • Log output of the GDB Server (optional, if Show log window is checked).
  • Initial and current target interface speed.
  • Target endianness.

These configurations can be made from inside GDB Server:

  • Localhost only: If checked only connections from 127.0.0.1 are accepted.
  • Stay on top
  • Show log window.
  • Generate logfile: If checked, a log file with the GDB <-> GDB Server <-> J-Link communication will be created.
  • Verify download: If checked, the memory on the target will be verified after download.
  • Init regs on start: If checked, the register values of the target will be set to a reasonable value before on start of GDB Server.

Running GDB from different programs

We assume that you already have a solid knowledge of the software tools used for building your application (assembler, linker, C compiler) and especially the debugger and the debugger frontend of your choice. We do not answer questions about how to install and use the chosen toolchain.

GDB is included in many IDEs and most commonly used in connection with the GCC compiler toolchain. This chapter shows how to configure some programs to use GDB and connect to GDB Server. For more information about any program using GDB, please refer to its user manual.

emIDE

emIDE debug session

emIDE is a full-featured, free and open source IDE for embedded development including support for debugging with J-Link.

To connect to GDB Server with emIDE, the GDB Server configurations need to be set in the project options at Project -> Properties... -> Debugger. Select the target device you are using, the target connection, endianness and speed and enter the additional GDB start commands. The typically required GDB commands are:

#Initially reset the target
monitor reset
#Load the application
load

Other commands to set up the target (e.g. Set PC to RAM, initialize external flashes) can be entered here, too.
emIDE will automatically start the J-Link GDB Server on start of the debug session. If it does not, or an older version of J-Link GDB Server starts, in emIDE click on JLink -> Run the JLink-plugin configuration.
For download and more information about emIDE, please refer to emide.org.

Console

GDB can be used stand-alone as a console application.
To connect GDB to J-Link GDB Server enter target remote localhost:2331 into the running GDB. Within GDB all GDB commands and the remote monitor commands are available. For more information about debugging with GDB refer to its online manual available at sourceware.org.
A typical startup of a debugging session can be like:

(gdb) file C:/temp/Blinky.elf
Reading symbols from C:/temp/Blinky.elf...done.
(gdb) target remote localhost:2331
Remote debugging using localhost:2331
0x00000000 in ?? ()
(gdb) monitor reset
Resetting target
(gdb) load
Loading section .isr_vector, size 0x188 lma 0x8000000
Loading section .text, size 0x568 lma 0x8000188
Loading section .init_array, size 0x8 lma 0x80006f0
Loading section .fini_array, size 0x4 lma 0x80006f8
Loading section .data, size 0x428 lma 0x80006fc
Start address 0x8000485, load size 2852
Transfer rate: 146 KB/sec, 570 bytes/write.
(gdb) break main
Breakpoint 1 at 0x800037a: file Src\main.c, line 38.
(gdb) continue
Continuing.
Breakpoint 1, main () at Src\main.c:38
38 Cnt = 0;
(gdb)

Eclipse (CDT)

Eclipse is an open source platform-independent software framework, which has typically been used to develop integrated development environment (IDE). Therefore Eclipse can be used as C/C++ IDE, if you extend it with the CDT plug-in (eclipse.org/cdt/).
CDT means "C/C++ Development Tooling" project. It is designed to use the GDB as default debugger and works without any problems with the J-Link GDB Server. Refer to eclipse.org for detailed information about Eclipse.
NOTE: We only support problems directly related to the J-Link GDB Server. Problems and questions related to your remaining toolchain will not be answered and resolved by SEGGER.

Supported remote (monitor) commands

J-Link GDB Server comes with some functionalities which are not part of the standard GDB. These functions can be called either via a gdbinit file passed to GDB Server or via monitor commands passed directly to GDB, forwarding them to GDB Server.

To indicate to GDB to forward the command to GDB Server 'monitor' has to be prepended to the call. For example a reset can be triggered in the gdbinit file with "reset" or via GDB with "monitor reset".

The following remote commands are available:

Remote command Explanation
clrbp Removes an instruction breakpoint.
cp15 Reads or writes from/to cp15 register.
device Select the specified target device.
DisableChecks Do not check if an abort occurred after memory read (ARM7/9 only).
EnableChecks Check if an abort occurred after memory read (ARM7/9 only).
flash breakpoints Enables/Disables flash breakpoints.
flash erase Erases the flash memory of the target device.
getargs Get the arguments for the application.
go Starts the target CPU.
halt Halts the target CPU.
jtagconf Configures a JTAG scan chain with multiple devices on it.
memU8 Reads or writes a byte from/to given address.
memU16 Reads or writes a halfword from/to given address.
memU32 Reads or writes a word from/to given address.
reg Reads or writes from/to given register.
regs Reads and displays all CPU registers.
reset Resets and halts the target CPU.
semihosting breakOnError Enable or disable halting the target on semihosting error.
semihosting enable Enables semihosting.
semihosting IOClient Set semihosting I/O to be handled via Telnet port or GDB.
semihosting ARMSWI Sets the SWI number used for semihosting in ARM mode.
semihosting ThumbSWI Sets the SWI number used for semihosting in thumb mode.
setargs Set the arguments for the application.
setbp Sets an instruction breakpoint at a given address.
sleep Sleeps for a given time period.
speed Sets the JTAG speed of J-Link / J-Trace.
step Performs one or more single instruction steps.
SWO DisableTarget Undo target configuration for SWO and disable it in J-Link.
SWO EnableTarget Configure target for SWO and enable it in J-Link.
SWO GetMaxSpeed Prints the maximum supported SWO speed for J-Link and Target CPU.
SWO GetSpeedInfo Prints the available SWO speed and its minimum divider.
waithalt Waits for target to halt code execution.
wice Writes to given IceBreaker register.
ReadAP Reads the specified CoreSight DAP-AP register.
ReadDP Reads the specified CoreSight DAP-DP register.
ReadCSR Reads CSR register on a RISC-V based target.
WriteAP Writes the specified CoreSight DAP-AP register.
WriteDP Writes the specified CoreSight DAP-DP register.
WriteCSR Writes CSR register on a RISC-V based target.

The Following remote commands are deprecated and only available for backward compatibility:

Remote command Explanation
device Selects the specified target device.
Note: Use command line option -device instead.
interface Selects the target interface.
Note: Use command line option -if instead.
speed Sets the JTAG speed of J-Link / J-Trace.
Note: For the initial connection speed, use command line option -speed instead.

NOTE:

  • The remote commands are case-insensitive.
  • Optional parameters are set into square brackets.
  • The examples are described as follows:
    • Lines starting with '#' are comments and not used in GDB / GDB Server.
    • Lines starting with '>' are input commands from the GDB.
    • Lines starting with '<' is the output from GDB Server as printed in GDB.

clrbp

Removes an instruction breakpoint, where <BPHandle> is the handle of breakpoint to be removed. If no handle is specified this command removes all pending breakpoints.

Syntax

ClrBP [<BPHandle>]

or

ci [<BPHandle>]

Example

> monitor clrbp 1
> monitor ci 1

cp15

Reads or writes from/to cp15 register. If <data> is specified, this command writes the data to the cp15 register. Otherwise this command reads from the cp15 register. For further information please refer to the ARM reference manual.

Syntax

cp15 <CRn>, <CRm>, <op1>, <op2> [= <data>]

The parameters of the function are equivalent to the MCR instructions described in the ARM documents.

Example

#Read:
> monitor cp15 1, 2, 6, 7
< Reading CP15 register (1,2,6,7 = 0x0460B77D)

#Write:
> monitor cp15 1, 2, 6, 7 = 0xFFFFFFFF

DisableChecks

Disables checking if a memory read caused an abort (ARM7/9 devices only). On some CPUs during the init sequence for enabling access to the internal memory (for example on the TMS470) some dummy reads of memory are required which will cause an abort as long as the access-init is not completed.

Syntax

DisableChecks

Example

> monitor DisableChecks

EnableChecks

Enables checking if a memory read caused an abort (ARM7/9 devices only). On some CPUs during the init sequence for enabling access to the internal memory (for example on the TMS470) some dummy reads of memory are required which will cause an abort as long as the access-init is not completed. The default state is: Checks enabled.

Syntax

EnableChecks

Example

> monitor EnableChecks

flash breakpoints

This command enables/disables the Flash Breakpoints feature. By default Flash Breakpoints are enabled and can be used for evaluation.

Syntax

monitor flash breakpoints = <value>

Example

#Disable Flash Breakpoints:
> monitor flash breakpoints = 0
< Flash breakpoints disabled
#Enable Flash Breakpoins:
> monitor flash breakpoints = 1
< Flash breakpoints enabled

flash erase

This command erases the flash memory of the target device.

Syntax

flash erase

Example

> monitor flash erase

getargs

Get the currently set argument list which will be given to the application when calling semihosting command SYS_GET_CMDLINE (0x15). The argument list is given as one string.

Syntax

getargs

Example

#No arguments set via setargs:
> monitor getargs
< No arguments.
#Arguments set via setargs:
> monitor getargs
< Arguments: test 0 1 2 arg0=4

go

Starts the target CPU.

Syntax

go

Example

> monitor go

halt

Halts the target CPU.

Syntax

halt

Example

> monitor halt

jtagconf

Configures a JTAG scan chain with multiple devices on it. <IRPre> is the sum of IRLens of all devices closer to TDI, where IRLen is the number of bits in the IR (Instruction Register) of one device. <DRPre> is the number of devices closer to TDI. For more detailed information of how to configure a scan chain with multiple devices please refer to Determining values for scan chain configuration.
Note: To make sure the connection to the device can be established correctly, it is recommended to configure the JTAG scan chain via command line options at the start of GDB Server.

Syntax

jtagconf <IRPre> <DRPre>

Example

#Select the second device, where there is 1 device in front with IRLen 4
> monitor jtagconf 4 1

memU8

Reads or writes a byte from/to a given address. If <value> is specified, this command writes the value to the given address. Otherwise this command reads from the given address.

Syntax

memU8 <address> [= <value>]

Example

#Read:
> monitor memU8 0x50000000
< Reading from address 0x50000000 (Data = 0x04)

#Write:
> monitor memU8 0x50000000 = 0xFF
< Writing 0xFF @ address 0x50000000

memU16

Reads or writes a halfword from/to a given address. If <value> is specified, this command writes the value to the given address. Otherwise this command reads from the given address.

Syntax

memU16 <address> [= <value>]

Example

#Read:
> monitor memU16 0x50000000
< Reading from address 0x50000000 (Data = 0x3004)

#Write:
> monitor memU16 0x50000000 = 0xFF00
< Writing 0xFF00 @ address 0x50000000

memU32

Reads or writes a word from/to a given address. If <value> is specified, this command writes the value to the given address. Otherwise this command reads from the given address. This command is similar to the long command.

Syntax

memU32 <address> [= <value>]

Example

#Read:
> monitor memU32 0x50000000
< Reading from address 0x50000000 (Data = 0x10023004)

#Write:
> monitor memU32 0x50000000 = 0x10023004
< Writing 0x10023004 @ address 0x50000000

reg

Reads or writes from/to given register. If <value> is specified, this command writes the value into the given register. If <address> is specified, this command writes the memory content at address <address> to register <RegName>. Otherwise this command reads the given register.

Syntax

reg <RegName> [= <value>] 

or

reg <RegName> [= (<address>)] 

Example

#Write value to register:
> monitor reg pc = 0x00100230
< Writing register (PC = 0x00100230)

#Write value from address to register:
> monitor reg r0 = (0x00000040)
< Writing register (R0 = 0x14813004)

#Read register value:
> monitor reg PC
< Reading register (PC = 0x00100230)

regs

Reads all CPU registers.

Syntax

regs

Example

> monitor regs
< PC = 00100230, CPSR = 20000013 (SVC mode, ARM)
R0 = 14813004, R1 = 00000001, R2 = 00000001, R3 = 000003B5
R4 = 00000000, R5 = 00000000, R6 = 00000000, R7 = 00000000
USR: R8 =00000000, R9 =00000000, R10=00000000, R11 =00000000, R12 =00000000
R13=00000000, R14=00000000
FIQ: R8 =00000000, R9 =00000000, R10=00000000, R11 =00000000, R12 =00000000
R13=00200000, R14=00000000, SPSR=00000010
SVC: R13=002004E8, R14=0010025C, SPSR=00000010
ABT: R13=00200100, R14=00000000, SPSR=00000010
IRQ: R13=00200100, R14=00000000, SPSR=00000010
UND: R13=00200100, R14=00000000, SPSR=00000010

reset

Resets and halts the target CPU. Make sure the device is selected prior to using this command to make use of the correct reset strategy.

Note: There are different reset strategies for different CPUs. Moreover, the reset strategies which are available differ from CPU core to CPU core. J-Link can perform various reset strategies and always selects the best fitting strategy for the selected device.

Syntax

reset

Example

> monitor reset
< Resetting target

breakOnError

Enables or disables halting the target at the semihosting breakpoint / in SVC handler if an error occurred during a semihosting command, for example a bad file handle for SYS_WRITE. The GDB Server log window always shows a warning in these cases. breakOnError is disabled by default.

Syntax

semihosting breakOnerror <Value> 

Example

#Enable breakOnError:
> monitor semihosting breakOnError 1

enable

Enables semihosting with the specified vector address. If no vector address is specified, the SWI vector (at address 0x8) will be used. GDBServer will output semihosting terminal data from the target via a separate connection on port 2333. Some IDEs already establish a connection automatically on this port and show terminal data in a specific window in the IDE. For IDEs which do not support semihosting terminal output directly, the easiest way to view semihosting output is to open a telnet connection to the GDBServer on port 2333. The connection on this port can be opened all the time as soon as GDBServer is started, even before this remote command is executed.

Syntax

semihosting enable [<VectorAddr>]

Example

> monitor semihosting enable
< Semihosting enabled (VectorAddr = 0x08)

IOClient

GDB itself can handle (file) I/O operations, too. With this command it is selected whether to print output via TELNET port (2333), GDB, or both.
<ClientMask> is

  • 1 for TELNET Client (Standard port 2333) (Default)
  • 2 for GDB Client
  • 3 for both (Input via GDB Client)

Syntax

semihosting IOClient <ClientMask>

Example

#Select TELNET port as output source
> monitor semihosting ioclient 1
< Semihosting I/O set to TELNET Client

#Select GDB as output source
> monitor semihosting ioclient 2
< Semihosting I/O set to GDB Client

#Select TELNET port and GDB as output source
> monitor semihosting ioclient 3
< Semihosting I/O set to TELNET and GDB Client

ARMSWI

Sets the SWI number used for semihosting in ARM mode. The default value for the ARMSWI is 0x123456.

Syntax

semihosting ARMSWI <Value>

Example

> monitor semihosting ARMSWI 0x123456
< Semihosting ARM SWI number set to 0x123456

ThumbSWI

Sets the SWI number used for semihosting in thumb mode. The default value for the ThumbSWI is 0xAB

Syntax

semihosting ThumbSWI <Value>

Example

> monitor semihosting ThumbSWI 0xAB
< Semihosting Thumb SWI number set to 0xAB

setargs

Set arguments for the application, where all arguments are in one <ArgumentString> separated by whitespaces. The argument string can be gotten by the application via semihosting command SYS_GET_CMDLINE (0x15). Semihosting has to be enabled for getting the argumentstring (see semihosting enable). "monitor setargs" can be used before enabling semihosting. The maximum length for <ArgumentString> is 512 characters.

Syntax

setargs <ArgumentString>

Example

> monitor setargs test 0 1 2 arg0=4
< Arguments: test 0 1 2 arg0=4

setbp

Sets an instruction breakpoint at the given address, where <Mask> can be 0x03 for ARM instruction breakpoints (Instruction width 4 Byte, mask out lower 2 bits) or 0x01 for THUMB instruction breakpoints (Instruction width 2 Byte, mask out lower bit). If no mask is given, an ARM instruction breakpoint will be set.

Syntax

setbp <Addr> [<Mask>]

Example

#Set a breakpoint (implicit for ARM instructions)
> monitor setbp 0x00000000

#Set a breakpoint on a THUMB instruction
> monitor setbp 0x00000100 0x01

sleep

Sleeps for a given time, where <Delay> is the time period in milliseconds to delay. While sleeping any communication is blocked until the command returns after the given period.

Syntax

sleep <Delay>

Example

> monitor sleep 1000
< Sleep 1000ms

step

Performs one or more single instruction steps, where <NumSteps> is the number of instruction steps to perform. If <NumSteps> is not specified only one instruction step will be performed.

Syntax

step [<NumSteps>]

or

si [<NumSteps>]

Example

> monitor step 3

SWO DisableTarget

Disables the output of SWO data on the target (Undoes changes from SWO EnableTarget) and stops J-Link to capture it.

Syntax

SWO DisableTarget <PortMask[0x01-0xFFFFFFFF]>

Example

  1. Disable capturing SWO from stimulus ports 0 and 1
> monitor SWO DisableTarget 3
< SWO disabled successfully.

SWO EnableTarget

Configures the target to be able to output SWO data and starts J-Link to capture it. CPU and SWO frequency can be 0 for auto-detection.If CPUFreq is 0, J-Link will measure the current CPU speed. If SWOFreq is 0, J-Link will use the highest available SWO speed for the selected / measured CPU speed.
Note: CPUFreq has to be the speed at which the target will be running when doing SWO. If the speed is different from the current speed when issuing CPU speed auto-detection, getting SWO data might fail. SWOFreq has to be a quotient of the CPU and SWO speeds and their prescalers. To get available speed, use SWO GetSpeedInfo. PortMask can be a decimal or hexadecimal Value. Values starting with the Prefix "0x" are handled hexadecimal.

Syntax

SWO EnableTarget <CPUFreq[Hz]> <SWOFreq[Hz]> <PortMask[0x01-0xFFFFFFFF] <Mode[0]>

Example

#Configure SWO for stimulus port 0, measure CPU frequency and calculate SWO frequency
> monitor SWO EnableTarget 0 0 1 0
< SWO enabled successfully.

#Configure SWO for stimulus ports 0-2, fixed SWO frequency and measure CPU frequency
> monitor SWO EnableTarget 0 1200000 5 0
< SWO enabled successfully.

#Configure SWO for stimulus ports 0-255, fixed CPU and SWO frequency
> monitor SWO EnableTarget 72000000 6000000 0xFF 0
< SWO enabled successfully.

SWO GetMaxSpeed

Prints the maximum SWO speed supported by and matching both, J-Link and the target CPU frequency.

Syntax

SWO GetMaxSpeed <CPUFrequency [Hz]>

Example

  1. Get SWO speed for 72MHz CPU speed
> monitor SWO GetMaxSpeed 72000000
< Maximum supported SWO speed is 6000000 Hz.

SWO GetSpeedInfo

Prints the base frequency and the minimum divider of the connected J-Link. With this information, the available SWO speeds for J-Link can be calculated and the matching one for the target CPU frequency can be selected.

Syntax

SWO GetSpeedInfo

Example

> monitor SWO GetSpeedInfo
< Base frequency: 60000000Hz, MinDiv: 8
# Available SWO speeds for J-Link are: 7.5MHz, 6.66MHz, 6MHz, ...

waithalt

Waits for target to halt code execution, where <Timeout> is the maximum time period in milliseconds to wait.

Syntax

waithalt <Timeout>

or

wh <Timeout>

Example

#Wait for halt with a timeout of 2 seconds
> monitor waithalt 2000

wice

Writes to given IceBreaker register, where <value> is the data to write.

Syntax

wice <RegIndex> <value>

or

rmib <RegIndex> <value>

Example

> monitor wice 0x0C 0x100

ReadAP

Reads the specified CoreSight DAP-AP register.
Note:

  • ARM specifies register addresses for JTAG (0x0, 0x4, 0x8, ...) and register indexes for SWD (0, 1, 2, ...).
    This API always works with register indexes, so:
  • Addr 0x0 = RegIndex 0
  • Addr 0x4 = RegIndex 1
  • Addr 0x8 = RegIndex 2
  • Addr 0xC = RegIndex 3
  • In case a WAIT response is received from the DAP, J-Link will retry the access until OK/FAULT is received or the operation times out (100ms).
  • Performs a fully qualified read. This means that for AP accesses which are "registered", J-Link performs an implicit read of AP-RDBUFF after the AP access, to get the actual value.

Syntax

ReadAP [<RegIndex>]

Example

> # Select AP[0] (AHB-AP) AP bank 0
> monitor WriteDP 2 0x00000000
< O.K.
> # Read AHB-AP TAR
> monitor ReadAP 1
< O.K.:0x08000000

ReadCSR

Reads a specific CSR (Control Status Register) on a RISC-V based target.

Syntax

ReadCSR <RegIndex>[,<RegSizeBytes>]
Parameter Meaning
RegIndex Index of CSR register to read
RegSizeBytes Optional. Specifies length of CSR register in bytes. If omitted RegSize is assumed to be XLEN (32-bit on RV32, 64-bit on RV64).

Example

monitor ReadCSR 0x300
or
monitor ReadCSR 0x300, 8

ReadDP

Reads the specified CoreSight DAP-DP register.
Note:

  • ARM specifies register addresses for JTAG (0x0, 0x4, 0x8, ...) and register indexes for SWD (0, 1, 2, ...).
    This API always works with register indexes, so:
  • Addr 0x0 = RegIndex 0
  • Addr 0x4 = RegIndex 1
  • Addr 0x8 = RegIndex 2
  • Addr 0xC = RegIndex 3
  • In case a WAIT response is received from the DAP, J-Link will retry the access until OK/FAULT is received or the operation times out (100ms).
  • Performs a fully qualified read. This means that for AP accesses which are "registered", J-Link performs an implicit read of AP-RDBUFF after the AP access, to get the actual value.

Syntax

ReadDP [<RegIndex>]

Example

> # Read CTRL/STAT
> monitor ReadDP 1
< O.K.:0xF0000000

WriteAP

Writes the specified CoreSight DAP-AP register.
Note:

  • ARM specifies register addresses for JTAG (0x0, 0x4, 0x8, ...) and register indexes for SWD (0, 1, 2, ...).
    This API always works with register indexes, so:
  • Addr 0x0 = RegIndex 0
  • Addr 0x4 = RegIndex 1
  • Addr 0x8 = RegIndex 2
  • Addr 0xC = RegIndex 3
  • In case a WAIT response is received from the DAP, J-Link will retry the access until OK/FAULT is received or the operation times out (100ms).

Syntax

WriteAP [<RegIndex>, <Data>]

Example

> # Select AP[0] (AHB-AP) AP bank 0
> monitor WriteDP 2 0x00000000
< O.K.
> # Write AHB-AP TAR
> monitor WriteAP 1 0x08000000
< O.K.

WriteDP

Writes the specified CoreSight DAP-DP register.
Note:

  • ARM specifies register addresses for JTAG (0x0, 0x4, 0x8, ...) and register indexes for SWD (0, 1, 2, ...).
    This API always works with register indexes, so:
  • Addr 0x0 = RegIndex 0
  • Addr 0x4 = RegIndex 1
  • Addr 0x8 = RegIndex 2
  • Addr 0xC = RegIndex 3
  • In case a WAIT response is received from the DAP, J-Link will retry the access until OK/FAULT is received or the operation times out (100ms).

Syntax

WriteDP [<RegIndex>, <Data>]

Example

> # Write SELECT register: Select AP[0] (AHB-AP) AP bank 15
> monitor WriteDP 2 0x000000F0
< O.K.

WriteCSR

Writes a specific CSR (Control Status Register) on a RISC-V based target.

Note
Writes to known CSRs (like X1) may not be written to HW directly but with the next g or s command.

Syntax

WriteCSR <RegIndex>, [,<RegSizeBytes>]
Parameter Meaning
RegIndex Index of CSR register to write
Data Data to write
RegSizeBytes Optional. Specifies length of CSR register in bytes. If omitted RegSize is assumed to be XLEN (32-bit on RV32, 64-bit on RV64).

Example

monitor WriteCSR 0x1001, 0x11223344
or
monitor WriteCSR 0x1001, 0x11223344, 8

SEGGER-specific GDB protocol extensions

J-Link GDB Server implements some functionality which are not part of the standard GDB remote protocol in general query packets. These SEGGER-specific general query packets can be sent to GDB Server on the low-level of GDB, via maintenance commands, or with a custom client connected to GDB Server.

As these extensions are not of interest for the regular user, they have been added to a separate manual that describes the SEGGER-specific GDB protocol extensions that have been added to J-Link GDB Server. The manual is available for download on the SEGGER website: UM08036

Command line options

There are several command line options available for the GDB Server which allow configuration of the GDB Server before any connection to a J-Link is attempted or any connection from a GDB client is accepted.

Note: Using GDB Server CL, device, interface, endian and speed are mandatory options to correctly connect to the target, and should be given before connection via GDB. Using GDB Server GUI the mandatory options can also be selected in the configuration dialog.

Command line option Explanation
-device Selects the connected target device.
-endian Selects the device endianness.
-if Selects the interface to connect to the target.
-speed Selects the target communication speed.

Note: Using multiple instances of GDB Server, setting custom values for port, SWOPort and TelnetPort is necessary.

Command line option Explanation
-port Select the port to listen for GDB clients.
-swoport Select the port to listen for clients for SWO RAW output.
-telnetport Select the port to listen for clients for printf output.

The GDB Server GUI version uses persistent settings which are saved across different instances and sessions of GDB Server. These settings can be toggled via the checkboxes in the GUI.

Note: GDB Server CL always starts with the settings marked as default.

For GUI and CL, the settings can be changed with following command line options. For all persistent settings there is a pair of options to enable or disable the feature.

Command line option Explanation
-ir Initialize the CPU registers on start of GDB Server. (Default)
-noir Do not initialize CPU registers on start of GDB Server.
-localhostonly Allow only localhost connections (Windows default)
-nolocalhostonly Allow connections from outside localhost (Linux default)
-logtofile Generate a GDB Server log file.
-nologtofile Do not generate a GDB Server log file. (Default)
-halt Halt the target on start of GDB Server. (Default)
-nohalt Do not halt the target on start of GDB Server.
-silent Do not show log output.
-nosilent Show log output. (Default)
-stayontop Set the GDB Server GUI to be the topmost window.
-nostayontop Do not be the topmost window. (Default)
-timeout Set the time after which the target has to be connected.
-notimeout Set infinite timeout for target connection.
-vd Verify after downloading.
-novd Do not verify after downloading. (Default)

Following additional command line options are available. These options are temporary for each start of GDB Server.

Command line option Explanation
-excdbg Enable exception debugging.
-jtagconf Configures a JTAG scan chain with multiple devices on it.
-log Logs the GDB Server communication to a specific file.
-rtos Selects a RTOS plugin (DLL file)
-singlerun Starts GDB Server in single run mode.
-s Same as -singlerun
-nosinglerun Starts GDB Server in no single run mode. (Default)
-nos Same as -nosinglerun
-noreset Starts GDB Server in no reset mode.
-JLinkDevicesXMLPath Specifies a search path where to look for a <JLinkDevices.xml> file that might specify additional devices
-powertarget Power target after specified delay (1-9). 0 turns off power.
-gui Do not suppress DLL dialogs. (Default)
-nogui Suppress DLL Dialogs.
-jlinkscriptfile Specifies a J-Link script file.
-select Selects the interface to connect to J-Link (USB/IP).
-settingsfile Selects the J-Link Settings File.
-strict Starts GDB Server in strict mode.
-x Executes a gdb file on first connection.
-xc Executes a gdb file on every connection.
-cpu Selects the CPU core. Deprecated, use -device instead.

-cpu

Pre-select the CPU core of the connected device, so the GDB Server already knows the register set, even before having established a connection to the CPU.
Note: Deprecated, please use -device instead. Anyhow, it does not hurt if this option is set, too.

Syntax

-CPU <CPUCore>

Example

jlinkgdbserver -CPU ARM7_9

Additional information

The following table lists all valid values for <CPUCore> :

<CPUCore> Supported CPU cores
CPU_FAMILY_ARM7_9 Pre-select ARM7 and ARM9 as CPU cores.
CPU_FAMILY_CORTEX_A_R Pre-select Cortex-A and Cortex-R as CPU cores.
CPU_FAMILY_CORTEX_M Pre-select Cortex-M as CPU core.
CPU_FAMILY_RX600 Pre-select Renesas RX600 as CPU core.

-device

Tells GDBServer to which device J-Link is connected before the connect sequence is actually performed. It is recommended to use the command line option to select the device instead of using the remote command since for some devices J-Link already needs to know the device at the time of connecting to it since some devices need special connect sequences (e.g. devices with TI ICEPick modules). In such cases, it is not possible to select the device via remote commands since they are configured after the GDB client already connected to GDBServer and requested the target registers which already requires a connection to the target.
Note: Using GDB Server CL this option is mandatory to correctly connect to the target, and should be given before connection via GDB.

Syntax

-device <DeviceName>

Example

jlinkgdbserver -device AT91SAM7SE256

Additional information

For a list of all valid values for <DeviceName> , please refer to the Supported devices page.

-endian

Sets the endianness of the target where endianness can either be "little" or "big".
Note: When using GDB Server CL this option is mandatory to correctly connect to the target, and should be given before connection via GDB.

Syntax

-endian <endianness>

Example

jlinkgdbserver -endian little

-gui

Do not suppress DLL dialogs.

Syntax

-gui

Example

jlinkgdbserver -gui

-if

Selects the target interface which is used by J-Link to connect to the device. The default value is JTAG.

Syntax

-if <Interface>

Example

jlinkgdbserver -if SWD

Additional information

Currently, the following values are accepted for <Interface>:

  • JTAG
  • SWD
  • FINE
  • 2-wire-JTAG-PIC32

-ir

Initializes the CPU register with default values on startup.
Note: For the GUI version, this setting is persistent for following uses of GDB Server until changed via -noir or the GUI.

Syntax

-ir

Example

jlinkgdbserver -ir

-excdbg

Enables exception debugging. Exceptions on ARM CPUs are handled by exception handlers. Exception debugging makes the debugging of exceptions more user-friendly by passing a signal to the GDB client and returning to the causative instruction. In order to do this, a special exception handler is required as follows:

__attribute((naked)) void OnHardFault(void) {
  __asm volatile (
    " bkpt 10 \n"
    " bx lr \n"
  );
}

The signal passed to the GDB client is the immediate value (10 in the example) of the software breakpoint instruction. <nSteps> specifies, how many instructions need to be executed until the exception return occurs. In most cases this will be 2 (which is the default value), if the handler function is set as the exception handler. If it is called indirectly as a subroutine from the exception handler, there may be more steps required. It is mandatory to have the function declared with the "naked" attribute and to have the bx lr instruction immediately after the software breakpoint instruction. Otherwise the software breakpoint will be treated as a usual breakpoint.

Syntax

-excdbg <nSteps>

Example

jlinkgdbserver -excdbg 4

-jtagconf

Configures a JTAG scan chain with multiple devices on it. <IRPre> is the sum of IRLens of all devices closer to TDI, where IRLen is the number of bits in the IR (Instruction Register) of one device. <DRPre> is the number of devices closer to TDI. For more detailed information of how to configure a scan chain with multiple devices please refer to Determining values for scan chain configuration.

Syntax

-jtagconf <IRPre>,<DRPre>

Example

#Select the second device, where there is 1 device in front with IRLen 4
jlinkgdbserver -jtagconf 4,1

-localhostonly

Starts the GDB Server with the option to listen on localhost only (This means that only TCP/IP connections from localhost are accepted) or on any IP address. To allow remote debugging (connecting to GDBServer from another PC), deactivate this option. If no parameter is given, it will be set to 1 (active).
Note: For the GUI version, this setting is persistent for following uses of GDB Server until changed via command line option or the GUI.

Syntax

-LocalhostOnly <State>

Example

jlinkgdbserver -LocalhostOnly 0 //Listen on any IP address (Linux/MAC default)
jlinkgdbserver -LocalhostOnly 1 //Listen on localhost only (Windows default)

-log

Starts the GDB Server with the option to write the output into a given log file. The file will be created if it does not exist. If it exists the previous content will be removed. Paths including spaces need to be set between quotes.

Syntax

-log <LogFilePath>

Example

jlinkgdbserver -log "C:\my path\to\file.log"

-logtofile

Starts the GDB Server with the option to write the output into a log file. If no file is given via -log , the log file will be created in the GDB Server application directory.
Note: For the GUI version, this setting is persistent for following uses of GDB Server until changed via -nologtofile or the GUI.

Syntax

logtofile

Example

jlinkgdbserver -logtofile
jlinkgdbserver -logtofile -log "C:\my path\to\file.log"

-halt

Halts the target after connecting to it on start of J-Link GDB Server. For most IDEs this option is mandatory since they rely on the target to be halted after connecting to GDB Server.
Note: For the GUI version, this setting is persistent for following uses of GDB Server until changed via -nohalt or the GUI.

Syntax

-halt

Example

jlinkgdbserver -halt

-nogui

Suppresses DLL dialogs, except for License dialogs.

Syntax

-nogui

Example

jlinkgdbserver -nogui

-noir

Do not initialize the CPU registers on startup.
Note: For the GUI version, this setting is persistent for following uses of GDB Server until changed via -ir or the GUI.

Syntax

-noir

Example

jlinkgdbserver -noir

-nolocalhostonly

Starts GDB Server with the option to allow remote connections (from outside localhost). Same as -localhostonly 0.
Note: For the GUI version, this setting is persistent for following uses of GDB Server until changed via command line option or the GUI.

Syntax

-nolocalhostonly

Example

jlinkgdbserver -nolocalhostonly

-nologtofile

Starts the GDB Server with the option to not write the output into a log file.
Note: For the GUI version, this setting is persistent for following uses of J-Link GDB Server until changed via -nologtofile or the GUI. When this option is used after -log, no log file will be generated, when -log is used after this option,a log file will be generated and this setting will be overridden.

Syntax

-nologtofile

Example

jlinkgdbserver -nologtofile                           // Will not generate a log file
jlinkgdbserver -nologtofile -log "C:\pathto\file.log" // Will generate a log file
jlinkgdbserver -log "C:\pathto\file.log" -nologtofile // Will not generate a log file

-nohalt

When connecting to the target after starting GDB Server, the target is not explicitly halted and the CPU registers will not be initiated. After closing all GDB connections the target is started again and continues running. Some IDEs rely on the target to be halted after connect. In this case do not use -nohalt, but -halt.
Note: For the GUI version, this setting is persistent for following uses of GDB Server until changed via -halt or the GUI.

Syntax

-nohalt

Example

jlinkgdbserver -nohalt

-noreset

Perform no reset on connect, just halt the CPU

Syntax

-noreset

Example

jlinkgdbserver -norest

-nosinglerun

Single run mode turned off. (Default)

Syntax

-nosinglerun

Example

jlinkgdbserver -nosinglerun

-nosilent

Starts the GDB Server in non-silent mode. All log window messages will be shown.
Note: For the GUI version, this setting is persistent for following uses of GDB Server until changed via command line option or the GUI.

Syntax

-nosilent

Example

jlinkgdbserver -nosilent

-nostayontop

Starts the GDB Server in non-topmost mode. All windows can be placed above it.
Note: For the CL version this setting has no effect. For the GUI version, this setting is persistent for following uses of GDB Server until changed via command line option or the GUI.

Syntax

-nostayontop

Example

jlinkgdbserver -nostayontop

-notimeout

GDB Server automatically closes after a timeout of 5 seconds when no target voltage can be measured or connection to target fails. This command line option prevents GDB Server from closing, to allow connecting a target after starting GDB Server.
Note: The recommended order is to power the target, connect it to J-Link and then start GDB Server.

Syntax

-notimeout

Example

jlinkgdbserver -notimeout

-novd

Do not explicitly verify downloaded data.
Note: For the GUI version, this setting is persistent for following uses of GDB Server until changed via command line option or the GUI.

Syntax

-novd

Example

jlinkgdbserver -novd

-port

Starts GDB Server listening on a specified port. This option overrides the default listening port of the GDB Server. The default port is 2331.
Note: Using multiple instances of GDB Server, setting custom values for this option is necessary.

Syntax

-port <Port>

Example

jlinkgdbserver -port 2345

-rtos

Specifies a RTOS plug-in (.DLL file for Windows, .SO file for Linux and Mac). If the file-name extension is not specified, it is automatically added depending on the PC's operating system. The J-Link Software and Documentation Pack comes with RTOS plug-ins for embOS and FreeRTOS pre-installed in the sub-directory "GDBServer". A software development kit (SDK) for creating your own plug-ins is also available upon request on our website

Syntax

-rtos <filename>[.dll|.so]

Example

jlinkgdbserver -rtos GDBServer\RTOSPlugin_embOS

-JLinkDevicesXMLPath

Specifies a search path where to look for a <JLinkDevices.xml> file. The given path may be absolute or relative to the location of the JLinkARM.dll. This is mainly used for preliminary / special devices where a vendor ships a <JLinkDevices.xml> file to specific customers and this file defines new devices that are not publicly available yet.

Syntax

-JLinkDevicesXMLPath <SearchPath>

Example

jlinkgdbserver -JLinkDevicesXMLPath C:\Work\MyDevices\

-jlinkscriptfile

Passes the path of a J-Link script file to the GDB Server. This scriptfile is executed before the GDB Server starts the debugging / identifying communication with the target. J-Link scriptfiles are mainly used to connect to targets which need a special connection sequence before communication with the core is possible. For more information about J-Link script files, please refer to J-Link script files.

Syntax

-jlinkscriptfile <ScriptFilePath>

Example

-jlinkscriptfile "C:\My Projects\Default.JLinkScript"

-powertarget

Power target after specified delay (1-9 ms). 0 turns off power.

Syntax

-powertarget <Value>

Value can can range from 0-9.

Example

jlinkgdbserver -powertarget 1

-select

Specifies the host interface to be used to connect to J-Link. Currently, USB and TCP/IP are available.

Syntax

-select <Interface>=<SerialNo>/<IPAddr>

Example

jlinkgdbserver -select usb=580011111
jlinkgdbserver -select ip=192.168.1.10

Additional information

For backward compatibility, when USB is used as interface serial numbers from 0-3 are accepted as USB=0-3 to support the old method of connecting multiple J-Links to a PC. This method is no longer recommended to be used. Please use the "connect via emulator serial number" method instead.

-settingsfile

Select a J-Link settings file to be used for the target device. The settings file can contain all configurable options of the Settings tab in J-Link Control panel.

Syntax

-SettingsFile <PathToFile>

Example

jlinkgdbserver -SettingsFile "C:\Temp\GDB Server.jlink"

-silent

Starts the GDB Server in silent mode. No log window messages will be shown.
Note: For the GUI version, this setting is persistent for following uses of GDB Server until changed via command line option or the GUI.

Syntax

-silent

Example

jlinkgdbserver -silent

-singlerun

Starts GDB Server in single run mode. When active, GDB Server will close when all client connections are closed. In normal run mode GDB Server will stay open and wait for new connections. When started in single run mode GDB Server will close immediately when connecting to the target fails. Make sure it is powered and connected to J-Link before starting GDB Server.

Syntax

-s
-singlerun

Example

jlinkgdbserver -s
jlinkgdbserver -singlerun

-speed

Starts GDB Server with a given initial speed. Available parameters are "adaptive", "auto" or a freely selectable integer value in kHz. It is recommended to use either a fixed speed or, if it is available on the target, adaptive speeds.
Note: Using GDB Server CL this option is mandatory to correctly connect to the target, and should be given before connection via GDB.

Syntax

-speed <Speed_kHz>

Example

jlinkgdbserver -speed 2000

-stayontop

Starts the GDB Server in topmost mode. It will be placed above all non-topmost windows and maintains it position even when it is deactivated.
Note: For the CL version this setting has no effect. For the GUI version, this setting is persistent for following uses of GDB Server until changed via command line option or the GUI.

Syntax

-stayontop
=== Example ===
jlinkgdbserver -stayontop

-timeout

Set the timeout after which the target connection has to be established. If no connection could be established GDB Server will close. The default timeout is 5 seconds for the GUI version and 0 for the command line version.
Note: The recommended order is to power the target, connect it to J-Link and then start GDB Server.

Syntax

-timeout <Timeout[ms]>

Example

jlinkgdbserver -timeout 10000

Allows target connection within 10 seconds.

-strict

Starts GDB Server in strict mode. When strict mode is active GDB Server checks the correctness of settings and exits in case of a failure. Currently the device name is checked. If no device name is given or the device is unknown to the J-Link, GDB Server exits instead of selecting "Unspecified" as device or showing the device selection dialog.

Syntax

-strict

Example

Following executions of GDB Server (CL) will cause exit of GDB Server:

jlinkgdbserver -strict -device UnknownDeviceName
jlinkgdbservercl -strict

Following execution of GDB Server will show the device selection dialog under Windows or select "Unspecified" directly under Linux / macOS:

jlinkgdbserver -device UnknownDeviceName

-swoport

Set up port on which GDB Server should listen for an incoming connection that reads the SWO data from GDB Server. Default port is 2332.
Note: Using multiple instances of GDB Server, setting custom values for this option is necessary.

Syntax

-SWOPort <Port>

Example

jlinkgdbserver -SWOPort 2553

-telnetport

Set up port on which GDB Server should listen for an incoming connection that gets target's printf data (Semihosting and analyzed SWO data). Default port is 2333.
Note: Using multiple instances of GDB Server, setting custom values for this option is necessary.

Syntax

-TelnetPort <Port>

Example

jlinkgdbserver -TelnetPort 2554

-vd

Verifies the data after downloading it.
Note: For the GUI version, this setting is persistent for following uses of GDB Server until changed via command line option or the GUI.

Syntax

-vd

Example

jlinkgdbserver -vd

-x

Starts the GDB Server with a gdbinit (configuration) file. In contrast to the -xc command line option the J-Link GDB Server runs the commands in the gdbinit file once only direct after the first connection of a client.

Syntax

-x <ConfigurationFilePath>

Example

jlinkgdbserver -x C:\MyProject\Sample.gdb

-xc

Starts the GDB Server with a gdbinit (configuration) file. GDB Server executes the commands specified in the gdbinit file with every connection of a client / start of a debugging session.

Syntax

-xc <ConfigurationFilePath>

Example

jlinkgdbserver -xc C:\MyProject\Sample.gdb

Program termination

J-Link GDB Server is normally terminated by a close or Ctrl-C event. When the single run mode is active it will also close when an error occurred during start or after all connections to GDB Server are closed.

On termination GDB Server will close all connections and disconnect from the target device, letting it run.

Exit codes

J-Link GDB Server terminates with an exit code indicating an error by a non-zero exit code.
The following table describes the defined exit codes of GDB Server.

Exit code Description
0 No error. GDB Server closed normally.
-1 Unknown error. Should not happen.
-2 Failed to open listener port (Default: 2331)
-3 Could not connect to target. No target voltage detected or connection failed.
-4 Failed to accept a connection from GDB.
-5 Failed to parse the command line options, wrong or missing command line parameter.
-6 Unknown or no device name set.
-7 Failed to connect to J-Link.

Semihosting

Semihosting can be used with J-Link GDBServer and GDB based debug environments but needs to be explicitly enabled. For more information, please refer to Enabling semihosting in J-Link GDBServer.

Troubleshooting

Port reserved by Hyper-V

There is a WIndows 10 20H2 issue where Hyper-V reserves a large number of ports which also include port 2331 used by J-Link GDB Server. You can see the reserved ports with the following command:

netsh int ipv4 show excludedportrange tcp

The output might look like this:

Protocol tcp Port Exclusion Ranges

Start Port    End Port
----------    --------
      2185        2503
      5357        5357
      9800        9800
      9801        9801
     49671       49770
     49871       49970
     50000       50059     *
     61117       61216
     61220       61319
     61902       62001

* - Administered port exclusions.

If the port 2331 lies within those Port Exclusion Ranges (like in the example above), you should try turning off Hyper-V, use this command:

bcdedit /set {current} hypervisorlaunchtype off

After rebooting the port 2331 should be free to use again.