Difference between revisions of "J-Link GDB Server"
(→Supported remote (monitor) commands) |
(→Semihosting) |
||
Line 1,419: | Line 1,419: | ||
Semihosting can be used with J-Link GDBServer and GDB based debug environments but needs to be explicitly enabled. |
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 [[UM08001_J-Link#Enabling_semihosting_in_J-Link_GDBServer | Enabling semihosting in J-Link GDBServer]]. |
For more information, please refer to [[UM08001_J-Link#Enabling_semihosting_in_J-Link_GDBServer | Enabling semihosting in J-Link GDBServer]]. |
||
+ | |||
+ | = Cadence Xtensa Xplorer support = |
||
+ | Since V7.80 of the J-Link GDBServer, debugging of Cadence Xtensa LX based core (HiFi 1, HiFi 3, HiFi 4, ...) is supported. To use GDBServer as interface in Xtensa Xplorer IDE, all that needs to be done is starting GDB Server listening at port 20000 which is the default listener port of XOCD (Cadence's GDB Server). J-Link GDBServer actually replaces XOCD here which results in a big gain of debugging performance (both download and single stepping etc. speed). |
||
+ | |||
+ | To enable J-Link to detect and connect to Xtensa based cores, some settings need to be configured for J-Link. For more information about this, please refer to the [[J-Link_Xtensa_specifics | J-Link Xtensa specifics wiki article]]. |
||
= Troubleshooting = |
= Troubleshooting = |
Revision as of 23:13, 26 July 2022
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
- 1 J-Link GDB Server CL
- 2 Debugging with J-Link GDB Server
- 3 Supported remote (monitor) commands
- 3.1 clrbp
- 3.2 cp15
- 3.3 DisableChecks
- 3.4 EnableChecks
- 3.5 flash breakpoints
- 3.6 flash erase
- 3.7 getargs
- 3.8 go
- 3.9 halt
- 3.10 jtagconf
- 3.11 memU8
- 3.12 memU16
- 3.13 memU32
- 3.14 reg
- 3.15 regs
- 3.16 reset
- 3.17 breakOnError
- 3.18 enable
- 3.19 IOClient
- 3.20 ARMSWI
- 3.21 ThumbSWI
- 3.22 setargs
- 3.23 setbp
- 3.24 sleep
- 3.25 step
- 3.26 SWO DisableTarget
- 3.27 SWO EnableTarget
- 3.28 SWO GetMaxSpeed
- 3.29 SWO GetSpeedInfo
- 3.30 waithalt
- 3.31 wice
- 3.32 ReadAP
- 3.33 ReadAPEx
- 3.34 ReadMemAP
- 3.35 ReadCSR
- 3.36 ReadDP
- 3.37 WriteAP
- 3.38 WriteDP
- 4 SEGGER-specific GDB protocol extensions
- 5 Command line options
- 5.1 -cpu
- 5.2 -device
- 5.3 -endian
- 5.4 -gui
- 5.5 -if
- 5.6 -ir
- 5.7 -excdbg
- 5.8 -jtagconf
- 5.9 -localhostonly
- 5.10 -log
- 5.11 -logtofile
- 5.12 -halt
- 5.13 -nogui
- 5.14 -noir
- 5.15 -nolocalhostonly
- 5.16 -nologtofile
- 5.17 -nohalt
- 5.18 -noreset
- 5.19 -nosinglerun
- 5.20 -nosilent
- 5.21 -nostayontop
- 5.22 -notimeout
- 5.23 -novd
- 5.24 -port
- 5.25 -rtos
- 5.26 -JLinkDevicesXMLPath
- 5.27 -jlinkscriptfile
- 5.28 -powertarget
- 5.29 -select
- 5.30 -settingsfile
- 5.31 -silent
- 5.32 -singlerun
- 5.33 -speed
- 5.34 -stayontop
- 5.35 -timeout
- 5.36 -strict
- 5.37 -swoport
- 5.38 -telnetport
- 5.39 -vd
- 5.40 -x
- 5.41 -xc
- 5.42 -RTTTelnetPort
- 6 Program termination
- 7 Semihosting
- 8 Cadence Xtensa Xplorer support
- 9 Troubleshooting
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.
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
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 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. |
ReadAPEx | Reads the specified CoreSight DAP-AP register. |
ReadMemAP | Reads memory via the specified DAP-AP. |
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
- 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
- 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
ReadAPEx
Reads the specified CoreSight DAP-AP register.
Syntax
ReadAPEx <APBaseAddr>, <RegAddr>
Parameter | Meaning |
---|---|
APBaseAddr | Base address of AP that will be written to DAP-DP SELECT register. |
RegAddr | Specifies the address/offset of the AP register to read. For example for CoreSight SoC-400 and earlier, ARM specifies (amongst others) the following AHB-AP registers: |
Example
> monitor ReadAPEx 0x10000000 0x00 < O.K.:0x08000000
ReadMemAP
Reads memory via the specified DAP-AP.
AP type is auto-detected by function, before memory access is performed.
Syntax
ReadMemAP <APBaseAddr>, <Addr>, <NumItems>, <Flags>
Parameter | Meaning |
---|---|
APBaseAddr | Base address of AP that will be written to DAP-DP SELECT register. |
Addr | Address in AP memory space to read from. |
NumItems | Number of items to read. Item size depends on <Flags>[3:0]. |
Flags | [3:0] AccSize (0 == default == 32-bit, 1 == force bytes, 2 == force half-words, 3 == reserved, 4 == force words) [31:4] Reserved for future use. Should be 0 |
Example
> monitor ReadMemAP 0x10000000 0x00000000 1 0 < O.K.:0x12345678
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. |
-RTTTelnetPort | Sets the RTT TELNET port. |
-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
-RTTTelnetPort
Sets the RTT TELNET port. Default is 19021.
For additional information, please refer to the RTT main article.
Syntax
-RTTTelnetPort <Port>
Example
jlinkgdbserver -RTTTelnetPort 19022
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.
Cadence Xtensa Xplorer support
Since V7.80 of the J-Link GDBServer, debugging of Cadence Xtensa LX based core (HiFi 1, HiFi 3, HiFi 4, ...) is supported. To use GDBServer as interface in Xtensa Xplorer IDE, all that needs to be done is starting GDB Server listening at port 20000 which is the default listener port of XOCD (Cadence's GDB Server). J-Link GDBServer actually replaces XOCD here which results in a big gain of debugging performance (both download and single stepping etc. speed).
To enable J-Link to detect and connect to Xtensa based cores, some settings need to be configured for J-Link. For more information about this, please refer to the J-Link Xtensa specifics wiki article.
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.