J Link / Trace User Guide Link, Manual Web
User Manual:
Open the PDF directly: View PDF .
Page Count: 367
Download | |
Open PDF In Browser | View PDF |
J-Link / J-Trace User Guide Document: UM08001 Software Version: 6.16d Revision: 0 Date: June 21, 2017 A product of SEGGER Microcontroller GmbH & Co. KG www.segger.com 2 Disclaimer Specifications written in this document are believed to be accurate, but are not guaranteed to be entirely free of error. The information in this manual is subject to change for functional or performance improvements without notice. Please make sure your manual is the latest edition. While the information herein is assumed to be accurate, SEGGER Microcontroller GmbH & Co. KG (SEGGER) assumes no responsibility for any errors or omissions. SEGGER makes and you receive no warranties or conditions, express, implied, statutory or in any communication with you. SEGGER specifically disclaims any implied warranty of merchantability or fitness for a particular purpose. Copyright notice You may not extract portions of this manual or modify the PDF file in any way without the prior written permission of SEGGER. The software described in this document is furnished under a license and may only be used or copied in accordance with the terms of such a license. © 2004-2017 SEGGER Microcontroller GmbH & Co. KG, Hilden / Germany Trademarks Names mentioned in this manual may be trademarks of their respective companies. Brand and product names are trademarks or registered trademarks of their respective holders. Contact address SEGGER Microcontroller GmbH & Co. KG In den Weiden 11 D-40721 Hilden Germany Tel. Fax. E-mail: Internet: +49 2103-2878-0 +49 2103-2878-28 support@segger.com www.segger.com J-Link / J-Trace (UM08001) © 2004-2017 SEGGER Microcontroller GmbH & Co. KG 3 Manual versions This manual describes the current software version. If you find an error in the manual or a problem in the software, please report it to us and we will try to assist you as soon as possible. Contact us for further information on topics or functions that are not yet documented. Print date: June 21, 2017 Manual Revision version Date By Description 6.14 6 170407 NV Chapter “Working with J-Link and J-Trace” * Section “J-Link scriptfiles”: Updated “ JLINK_ExecCommand()” description 6.14 5 170320 EL Chapter “J-Flash SPI” Updated screenshots NV Chapter “Working with J-Link and J-Trace” * Section “J-Link scriptfiles”: Added: “ JLINK_ExecCommand()” Section “Keil MDK-ARM” added for Command string execution NV Chapter “Working with J-Link and J-Trace” * Section “J-Link scriptfiles”: Added: “OnTraceStart()” and “ JLINK_TRACE_Portwidth” Chapter “Trace” * Added crossreference to “JLINK_TRACE_Portwidth” NV Chapter “Introduction” *Added Subsubsection “Software and Hardware Features Overview” to all device Subsections. *Edited Subsection “”J-Trace ARM. *Section “Target interfaces and adapters”: edited “RESET” to “nRESET” and updated description. NV Chapter “Working with J-Link and J-Trace” * Section “Exec Commands”: Updated SetResetPulseLen TraceSampleAdjust Chapter “Trace” * Section “Tracing via trace pins”: Updated 6.14 6.14 6.14 6.14 4 3 2 1 170317 170220 170216 170210 6.14 0 170201 AG Chapter “Working with J-Link” * Section “Exec Commands”: Updated SelectTraceSource SetRAWTRACEPinDelay ReadIntoTraceCache Chapter “Trace” added. 6.10a 0 160820 EL Chapter “Working With J-Link” * Section “Exec Commands”: Updated ExcludeFlashCacheRanges. 6.00i 0 160802 EL Chapter “Introduction” * Removed “Model Feature Lists” Chapter “Adding Support for New Devices”: renamed to “Open Flash Loader” Chapter “Open Flash Loader” updated. 6.00 1 160617 EL Chapter “J-Flash SPI” * Added chapter “Custom Command Sequences” 6.00 0 160519 AG Chapter “Adding Support for New Devices” added. 5.12f 0 160503 AB Chapter “Related Software” * Section “J-Link RTT Viewer” updated and moved from section “RTT”. 5.12d 1 160427 AG Chapter “Working with J-Link and J-Trace” * Section “J-Link script files” updated. 5.12d 0 160425 AG Chapter “Working with J-Link and J-Trace” * Section “J-Link script files” updated. 5.12c 0 160413 NG Chapter “Related Software” * Section “J-Link Commander” Typo fixed. 5.12c 1 160418 NG Chapter “Related Software” * Section “J-Link Commander” Commands and commandline options added. Chapter “Working with J-Link and J-Trace” J-Link / J-Trace (UM08001) © 2004-2017 SEGGER Microcontroller GmbH & Co. KG 4 Manual Revision version Date By Description * Section “Command strings” Command “SetRTTTelnetPort” added. Chapter “Flash Download” * Section “Debugging applications that change flash contents at runtime” added. 5.10u 0 160317 AG Chapter “Monitor Mode Debugging” * Section “Target application performs reset” added. 5.10t 0 160314 AG Chapter “Monitor Mode Debugging” * Section “Enable Monitor Debugging” updated. * Section “Forwarding of Monitor Interrupts” added. 5.10 3 160309 EL Chapter “J-Flash SPI” updated. 5.10 2 160215 AG Chapter “RTT” updated. 5.10 1 151204 AG Chapter “RDI” updated. Chapter “Semihosting” added. 5.10 0 151127 NG Chapter “Related Software” * Section “J-Scope” removed. 5.02m 0 151125 AG Chapter “Working with J-Link and J-Trace” * Section “The J-Link settings file” added. Chapter “Low Power Debugging” added. 5.02l 0 151123 AG Various Chapters * Some typos corrected. 5.02i 1 151106 RH Chapter “J-Flash SPI” * Section “Send custom commands” added. 5.02i 0 151105 RH Chapter “Related Software” * Section “J-Link Commander” exec command added. Chapter “Working with J-Link and J-Trace” * Section “Command strings” New commands added. 5.02f 1 151022 NG Chapter “Related Software” * Section “J-Scope” updated. 5.02f 1 151022 EL Chapter “Target interfaces and adapters” * Section “Reference voltage (VTref)” added. 5.02f 0 151007 RH Chapter “Working with J-Link and J-Trace” * Section “J-Link script files” updated. 5.02e 0 151001 AG Chapter “Working with J-Link and J-Trace” * Section “J-Link script files” updated 5.02c 1 150925 NG Chapter “Licensing” * Section “Original SEGGER products” updated. Chapter “Flash download” * Section “Setup for various debuggers (CFI flash)” updated. 5.02c 0 150916 RH Chapter “Flash download” * Section “Setup for various debuggers (SPIFI flash)” added. 5.02c 0 150914 RH Chapter “Introduction” * Section “J-Link / J-Trace models” updated. * Section “Supported OS” Added Windows 10 5.02a 0 150903 AG Chapter “Monitor Mode Debugging” added. 5.02 0 150820 AG Chapter “Working with J-Link and J-Trace” * Section “Command strings” “DisableCortexMXPSRAutoCorrectTBit” added. 5.02 0 150813 AG Chapter “Monitor Mode Debugging” added. 5.00 1 150728 NG Chapter “Related Software” * Section “J-Link Commander” Sub-Section “Command line options” updated. 5.00 0 150609 AG Chapter “Flash download” * Section “QSPI flash support” added. Chapter “Flash breakpoints” * Section “Flash Breakpoints in QSPI flash” added 5.00 0 150520 EL Chapter “J-Flash SPI” J-Link / J-Trace (UM08001) © 2004-2017 SEGGER Microcontroller GmbH & Co. KG 5 Manual Revision version Date By Description * Initial version added 4.99b 0 150520 EL Chapter “Related Software” * Section “J-Link STM32 Unlock” Added command line options 4.99a 0 150429 AG Chapter “Target interfaces and Adapters” Chapter “20-pin J-Link connector”, section “Pinout for SPI” added. 4.98d 0 150427 EL Chapter “Related Software” * Section “Configure SWO output after device reset” updated. 4.98b 0 150410 AG Chapter “Licensing” * Section “J-Trace for Cortex-M” updated. 4.98 0 150320 NG Chapter “Related Software” * Section “J-Link Commander” Sub-Section “Commands” added. Chapter “Working with J-Link and J-Trace” * Section “J-Link script files” updated 4.96f 0 150204 JL Chapter “Related Software” * Section “GDB Server” Exit code description added. 4.96 0 141219 JL Chapter “RTT” added. Chapter “Related Software” * Section “GDB Server” Command line option “-strict” added. Command line option “-timeout” added. 4.90d 0 141112 NG Chapter “Related Software” * Section “J-Link Remote Server” updated. * Section “J-Scope” updated. 4.90c 0 140924 JL Chapter “Related Software” * Section “JTAGLoad” updated. 4.90b 1 140813 EL Chapter “Working with J-Link and J-Trace” * Section “Connecting multiple J-Links / J-Traces to your PC” updated Chapter “J-Link software” * Section “J-Link Configurator” updated. 4.90b 0 140813 NG Chapter “Related Software” * Section “J-Scope” added. 4.86 2 140606 AG Chapter “Device specifics” * Section “Silicon Labs - EFM32 series devices” added 4.86 1 140527 JL Chapter “Related Software” * Section “GDB Server” Command line options -halt / -nohalt added. Description for GDB Server CL version added. 4.86 0 140519 AG Chapter “Flash download” Section “Mentor Sourcery CodeBench” added. EL Chapter “Working with J-Link” * Section “Virtual COM Port (VCOM) improved. Chapter ”Target interfaces and adapters“ * Section ”Pinout for SWD + Virtual COM Port (VCOM) added.“ 4.84 0 140321 4.82 1 140228 EL Chapter ”Related Software“ * Section ”Command line options“ Extended command line option -speed. Chapter ”J-Link software and documentation package“ * Section ”J-Link STR91x Commander“ Added command line option parameter to specify a customized scan-chain. Chapter ”Working with J-Link“ * Section ”Virtual COM Port (VCOM) added. Chapter “Setup” * Section “Getting started with J-Link and DS-5” 4.82 0 140218 JL Chapter “Related Software” * Section “GDB Server” Command line option -notimeout added. 4.80f 0 140204 JL Chapter “Related Software” * Section “GDB Server” Command line options and remote commands added. J-Link / J-Trace (UM08001) © 2004-2017 SEGGER Microcontroller GmbH & Co. KG 6 Manual Revision version Date By Description Chapter “Related Software” * Section “GDB Server” Remote commands and command line options description improved. Several corrections. 4.80 1 131219 JL/ NG 4.80 0 131105 JL Chapter “Related Software” * Section “GDB Server” SEGGER-specific GDB protocol extensions added. 4.76 3 130823 JL Chapter “Flash Download” * Replaced references to GDB Server manual. Chapter “Working with J-Link” * Replaced references to GDB Server manual. 4.76 2 130821 JL Chapter “Related Software” * Section “GDB Server” Remote commands added. 4.76 1 130819 JL Chapter “Related Software” * Section “SWO Viewer” Sample code updated. 4.76 0 130809 JL Chapter “Related Software” * Sections reordered and updated. Chapter “Setup” * Section “Using JLinkARM.dll moved here. 4.71b 0 130507 JL Chapter ”Related Software“ * Section ”SWO Viewer“ Added new command line options. 4.66 0 130221 JL Chapter ”Introduction“ * Section ”Supported OS“ Added Linux and Mac OSX 4.62b 0 130219 EL Chapter ”Introduction“ * Section ”J-Link / J-Trace models“ Clock rise and fall times updated. 4.62 0 130129 JL Chapter ”Introduction“ * Section ”J-Link / J-Trace models“ Sub-section ”J-link ULTRA“ updated. 4.62 0 130124 EL Chapter ”Target interfaces and adapters“ * Section ”9-pin JTAG/SWD connector“ Pinout description corrected. 4.58 1 121206 AG Chapter ”Introduction“ * Section ”J-Link / J-Trace models“ updated. 4.58 0 121126 JL Chapter ”Working with J-Link“ * Section ”J-Link script files“ Sub-section ”Executing J-Link script files“ updated. 4.56b 0 121112 JL Chapter ”Related Software“ * Section ”J-Link SWO Viewer“ Added sub-section ”Configure SWO output after device reset“ 4.56a 0 121106 JL Chapter ”Related Software“ * Section ”J-Link Commander“ Renamed ”Commander script files“ to ”Commander files“ and ”script mode“ to ”batch mode“. 4.56 0 121022 AG Renamed ”J-Link TCP/IP Server“ to ”J-Link Remote Server“ 4.54 1 121009 JL Chapter ”Related Software“ * Section ”TCP/IP Server“, subsection ”Tunneling Mode“ added. 4.54 0 120913 EL Chapter ”Flash Breakpoints“ * Section ”Licensing“ updated. Chapter ”Device specifics“ * Section ”Freescale“, subsection ”Data flash support“ added. 4.53c 0 120904 EL Chapter ”Licensing“ * Section ”Device-based license“ updated. EL Chapter ”Flash download“ * Section ”J-Link commander“ updated. Chapter ”Support and FAQs“ * Section ”Frequently asked questions“ updated. Chapter ”J-Link and J-Trace related software“ 4.51h 0 J-Link / J-Trace (UM08001) 120717 © 2004-2017 SEGGER Microcontroller GmbH & Co. KG 7 Manual Revision version Date By Description * Section ”J-Link Commander“ updated. 4.51e 1 120704 EL Chapter ”Working with J-Link“ * Section ”Reset strategies“ updated and corrected. Added reset type 8. 4.51e 0 120704 AG Chapter ”Device specifics“ * Section ”ST“ updated and corrected. 4.51b 0 120611 EL Chapter ”J-Link and J-Trace related software“ * Section ”SWO Viewer“ added. 4.51a 0 120606 EL Chapter ”Device specifics“ * Section ”ST“, subsection ”ETM init“ for some STM32 devices added. * Section ”Texas Instruments“ updated. Chapter ”Target interfaces and adapters“ * Section ”Pinout for SWD“ updated. 4.47a 0 120419 AG Chapter ”Device specifics“ * Section ”Texas Instruments“ updated. 4.46 0 120416 EL Chapter ”Support“ updated. 4.42 0 120214 EL Chapter ”Working with J-Link“ * Section ”J-Link script files“ updated. 4.36 1 110927 EL Chapter ”Flash download“ added. Chapter ”Flash breakpoints“ added. Chapter ”Target interfaces and adapters“ * Section ”20-pin JTAG/SWD connector“ updated. Chapter ”RDI“ added. Chapter ”Setup“ updated. Chapter ”Device specifics“ updated. 4.36 0 110909 AG Chapter ”Working with J-Link“ * Section ”J-Link script files“ updated. 4.26 1 110513 KN Chapter ”Introduction“ * Section ”J-Link / J-Trace models“ corrected. 4.26 0 110427 KN Several corrections. AG Chapter ”Introduction“ * Section ”J-Link / J-Trace models“ corrected. Chapter ”Device specifics“ * Section ”ST Microelectronics“ updated. 4.24 1 110228 4.24 0 110216 AG Chapter ”Device specifics“ * Section ”Samsung“ added. Chapter ”Working with J-Link“ * Section ”Reset strategies“ updated. Chapter ”Target interfaces and adapters“ * Section ”9-pin JTAG/SWD connector“ added. 4.23d 0 110202 AG Chapter ”J-Link and J-Trace related software“ * Section ”J-Link software and documentation package in detail“ updated. Chapter ”Introduction“ * Section ”Built-in intelligence for supported CPU-cores“ added. 4.21g 0 101130 AG Chapter ”Working with J-Link“ * Section ”Reset strategies“ updated. Chapter ”Device specifics“ * Section ”Freescale“ updated. Chapter ”Flash download and flash breakpoints * Section “Supported devices” updated * Section “Setup for different debuggers (CFI flash)” updated. 4.21 0 101025 AG Chapter “Device specifics” * Section “Freescale” updated. 4.20j 0 101019 AG Chapter “Working with J-Link” * Section “Reset strategies” updated. 4.20b 0 100923 AG Chapter “Working with J-Link” * Section “Reset strategies” updated. AG Chapter “Working with J-Link” * Section “J-Link script files” updated. * Section “Command strings” updated. Chapter “Target interfaces and adapters” * Section “19-pin JTAG/SWD and Trace connector” corrected. Chapter “Setup” 0.00 90 J-Link / J-Trace (UM08001) 100818 © 2004-2017 SEGGER Microcontroller GmbH & Co. KG 8 Manual Revision version Date By Description * Section “J-Link Configurator added.” 0.00 89 100630 AG Several corrections. 0.00 88 100622 AG Chapter “J-Link and J-Trace related software” * Section “SWO Analyzer” added. 0.00 87 100617 AG Several corrections. 0.00 86 100504 AG Chapter “Introduction” * Section “J-Link / J-Trace models” updated. Chapter “Target interfaces and adapters” * Section “Adapters” updated. 0.00 85 100428 AG Chapter “Introduction” * Section “J-Link / J-Trace models” updated. 0.00 84 100324 KN Chapter “Working with J-Link and J-Trace” * Several corrections Chapter Flash download & flash breakpoints * Section “Supported devices” updated 0.00 83 100223 KN Chapter “Introduction” * Section “J-Link / J-Trace models” updated. 0.00 82 100215 AG Chapter “Working with J-Link” * Section “J-Link script files” added. 0.00 81 100202 KN Chapter “Device Specifics” * Section “Luminary Micro” updated. Chapter “Flash download and flash breakpoints” * Section “Supported devices” updated. 0.00 80 100104 KN Chapter “Flash download and flash breakpoints * Section ”Supported devices“ updated 0.00 79 091201 AG Chapter ”Working with J-Link and J-Trace“ * Section ”Reset strategies“ updated. Chapter ”Licensing“ * Section ”J-Link OEM versions“ updated. 0.00 78 091023 AG Chapter ”Licensing“ * Section ”J-Link OEM versions“ updated. 0.00 77 090910 AG Chapter ”Introduction“ * Section ”J-Link / J-Trace models“ updated. KN Chapter ”Introduction“ * Section” Specifications“ updated * Section ”Hardware versions“ updated * Section ”Common features of the J-Link product family“ updated Chapter ”Target interfaces and adapters“ * Section ”5 Volt adapter“ updated AG Chapter ”Introduction“ * Section ”J-Link / J-Trace models“ updated. Chapter ”Working with J-Link and J-Trace“ * Section ”SWD interface“ updated. KN Chapter ”Introduction“ * Section ”Supported IDEs“ added * Section ”Supported CPU cores“ updated * Section ”Model comparison chart“ renamed to ”Model comparison“ * Section ”J-Link bundle comparison chart“ removed KN Chapter ”Introduction“ * Section ”J-Link and J-Trace models“ added * Sections ”Model comparison chart“ & ”J-Link bundle comparison chart“added Chapter ”J-Link and J-Trace models“ removed Chapter ”Hardware“ renamed to ”Target interfaces & adapters“ * Section ”JTAG Isolator“ added Chapter ”Target interfaces and adapters“ * Section ”Target board design“ updated Several corrections AG Chapter ”Working with J-Link“ * Section ”J-Link control panel“ updated. Chapter ”Flash download and flash breakpoints“ * Section ”Supported devices“ updated. 0.00 0.00 0.00 0.00 0.00 76 75 74 73 72 J-Link / J-Trace (UM08001) 090828 090729 090722 090701 090618 © 2004-2017 SEGGER Microcontroller GmbH & Co. KG 9 Manual Revision version Date By Description Chapter ”Device specifics“ * Section ”NXP“ updated. 0.00 71 090616 AG Chapter ”Device specifics“ * Section ”NXP“ updated. 0.00 70 090605 AG Chapter ”Introduction“ * Section ”Common features of the J-Link product family“ updated. AG Chapter ”Working with J-Link“ * Section ”Reset strategies“ updated. * Section ”Indicators“ updated. Chapter ”Flash download and flash breakpoints“ * Section ”Supported devices“ updated. 0.00 69 090515 0.00 68 090428 AG Chapter ”J-Link and J-Trace related software“ * Section ”J-Link STM32 Commander“ added. Chapter ”Working with J-Link“ * Section ”Reset strategies“ updated. 0.00 67 090402 AG Chapter ”Working with J-Link“ * Section ”Reset strategies“ updated. 0.00 66 090327 AG Chapter ”Background information“ * Section ”Embedded Trace Macrocell (ETM)“ updated. Chapter ”J-Link and J-Trace related software“ * Section ”Dedicated flash programming utilities for J-Link“ updated. 0.00 65 090320 AG Several changes in the manual structure. 0.00 64 090313 AG Chapter ”Working with J-Link“ * Section ”Indicators“ added. 0.00 63 090212 AG Chapter ”Hardware“ * Several corrections. * Section ”Hardware Versions“ Version 8.0 added. 0.00 62 090211 AG Chapter ”Working with J-Link and J-Trace“ * Section ”Reset strategies“ updated. Chapter J-Link and J-Trace related software * Section ”J-Link STR91x Commander (Command line tool)“ updated. Chapter ”Device specifics“ * Section ”ST Microelectronics“ updated. Chapter ”Hardware“ updated. 0.00 61 090120 TQ Chapter ”Working with J-Link“ * Section ”Cortex-M3 specific reset strategies“ 0.00 60 090114 AG Chapter ”Working with J-Link“ * Section ”Cortex-M3 specific reset strategies“ 0.00 59 090108 KN Chapter Hardware * Section ”Target board design for JTAG“ updated. * Section ”Target board design for SWD“ added. 0.00 58 090105 AG Chapter ”Working with J-Link Pro“ * Section ”Connecting J-Link Pro the first time“ updated. AG Chapter ”Working with J-Link Pro“ * Section ”Introduction“ updated. * Section ”Configuring J-Link Pro via web interface“ updated. Chapter ”Introduction“ * Section ”J-Link Pro overview“ updated. 0.00 57 081222 0.00 56 081219 AG Chapter ”Working with J-Link Pro“ * Section ”FAQs“ added. Chapter ”Support and FAQs“ * Section ”Frequently Asked Questions“ updated. 0.00 55 081218 AG Chapter ”Hardware“ updated. 0.00 54 081217 AG Chapter ”Working with J-Link and J-Trace“ * Section ”Command strings“ updated. 0.00 53 081216 AG Chapter ”Working with J-Link Pro“ updated. 0.00 52 081212 AG Chapter ”Working with J-Link Pro“ added. Chapter ”Licensing“ * Section ”Original SEGGER products“ updated. 0.00 51 081202 KN Several corrections. J-Link / J-Trace (UM08001) © 2004-2017 SEGGER Microcontroller GmbH & Co. KG 10 Manual Revision version Date By Description 0.00 50 081030 AG Chapter ”Flash download and flash breakpoints“ * Section ”Supported devices“ corrected. 0.00 49 081029 AG Several corrections. 0.00 48 080916 AG Chapter ”Working with J-Link and J-Trace“ * Section ”Connecting multiple J-Links / J-Traces to your PC“ updated. 0.00 47 080910 AG Chapter ”Licensing“ updated. 0.00 46 080904 AG Chapter ”Licensing“ added. Chapter ”Hardware“ Section ”J-Link OEM versions“ moved to chapter ”Licensing“ 0.00 45 080902 AG Chapter ”Hardware“ Section ”JTAG+Trace connector“ JTAG+Trace connector pinout corrected. Section ”J-Link OEM versions“ updated. 0.00 44 080827 AG Chapter ”J-Link control panel“ moved to chapter ”Working with J-Link“. Several corrections. 0.00 43 080826 AG Chapter ”Flash download and flash breakpoints“ Section ”Supported devices“ updated. 0.00 42 080820 AG Chapter ”Flash download and flash breakpoints“ Section ”Supported devices“ updated. 0.00 41 080811 AG Chapter ”Flash download and flash breakpoints“ updated. Chapter ”Flash download and flash breakpoints“, section ”Supported devices“ updated. 0.00 40 080630 AG Chapter ”Flash download and flash breakpoints“ updated. Chapter ”J-Link status window“ renamed to ”J-Link control panel“ Various corrections. AG Chapter ”Flash download and flash breakpoints“ Section ”Licensing“ updated. Section ”Using flash download and flash breakpoints with different debuggers“ updated. Chapter ”J-Link status window“ added. 0.00 39 080627 0.00 38 080618 AG Chapter ”Support and FAQs“ Section ”Frequently Asked Questions“ updated Chapter ”Reset strategies“ Section ”Cortex-M3 specific reset strategies“ updated. 0.00 37 080617 AG Chapter ”Reset strategies“ Section ”Cortex-M3 specific reset strategies“ updated. 0.00 36 080530 AG Chapter ”Hardware“ Section ”Differences between different versions“ updated. Chapter ”Working with J-Link and J-Trace“ Section ”Cortex-M3 specific reset strategies“ added. 0.00 35 080215 AG Chapter ”J-Link and J-Trace related software“ Section ”J-Link software and documentation package in detail“ updated. 0.00 34 080212 AG Chapter ”J-Link and J-Trace related software“ Section ”J-Link TCP/IP Server (Remote J-Link / J-Trace use)“ updated. Chapter ”Working with J-Link and J-Trace“ Section ”Command strings“ updated. Chapter ”Flash download and flash breakpoints“ Section ”Introduction“ updated. Section ”Licensing“ updated. Section ”Using flash download and flash breakpoints with different debuggers“ updated. 0.00 33 080207 AG Chapter ”Flash download and flash breakpoints“ added Chapter ”Device specifics:“ Section ”ATMEL - AT91SAM7 - Recommended init sequence“ added. 0.00 32 080129 SK Chapter ”Device specifics“: Section ”NXP - LPC - Fast GPIO bug“ list of device enhanced. 0.00 31 080103 SK Chapter ”Device specifics“: Section ”NXP - LPC - Fast GPIO bug“ updated. 0.00 30 071211 AG Chapter ”Device specifics“: Section ”Analog Devices“ updated. Section ”ATMEL“ updated. J-Link / J-Trace (UM08001) © 2004-2017 SEGGER Microcontroller GmbH & Co. KG 11 Manual Revision version Date By Description Section ”Freescale“ added. Section ”Luminary Micro“ added. Section ”NXP“ updated. Section ”OKI“ added. Section ”ST Microelectronics“ updated. Section ”Texas Instruments“ updated. Chapter ”Related software“: Section ”J-Link STR91x Commander“ updated 0.00 29 070912 SK Chapter ”Hardware“, section ”Target board design“ updated. 0.00 28 070912 SK Chapter ”Related software“: Section ”J-LinkSTR91x Commander“ added. Chapter ”Device specifics“: Section ”ST Microelectronics“ added. Section ”Texas Instruments“ added. Subsection ”AT91SAM9“ added. 0.00 28 070912 AG Chapter ”Working with J-Link/J-Trace“: Section ”Command strings“ updated. 0.00 27 070827 TQ Chapter ”Working with J-Link/J-Trace“: Section ”Command strings“ updated. SK Chapter ”Introduction“: Section ”Features of J-Link“ updated. Chapter ”Background Information“: Section ”Embedded Trace Macrocell“ added. Section ”Embedded Trace Buffer“ added. 0.00 26 070710 0.00 25 070516 SK Chapter ”Working with J-Link/J-Trace“: Section ”Reset strategies in detail“ - ”Software, for Analog Devices ADuC7xxx MCUs“ updated - ”Software, for ATMEL AT91SAM7 MCUs“ added. Chapter ”Device specifics“ Section ”Analog Devices“ added. Section ”ATMEL“ added. 0.00 24 070323 SK Chapter ”Setup“: ”Uninstalling the J-Link driver“ updated. ”Supported ARM cores“ updated. 0.00 23 070320 SK Chapter ”Hardware“: ”Using the JTAG connector with SWD“ updated. 0.00 22 070316 SK Chapter ”Hardware“: ”Using the JTAG connector with SWD“ added. 0.00 21 070312 SK Chapter ”Hardware“: ”Differences between different versions“ supplemented. 0.00 20 070307 SK Chapter ”J-Link / J-Trace related software“: ”J-Link GDB Server“ licensing updated. 0.00 19 070226 SK Chapter ”J-Link / J-Trace related software“ updated and reorganized. Chapter ”Hardware“ ”List of OEM products“ updated 0.00 18 070221 SK Chapter ”Device specifics“ added Subchapter ”Command strings“ added 0.00 17 070131 SK Chapter ”Hardware“: ”Version 5.3“: Current limits added ”Version 5.4“ added Chapter ”Setup“: ”Installating the J-Link USB driver“ removed. ”Installing the J-Link software and documentation pack“ added. Subchapter ”List of OEM products“ updated. ”OS support“ updated 0.00 16 061222 SK Chapter ”Preface“: ”Company description“ added. J-Link picture changed. 0.00 15 060914 OO Subchapter 1.5.1: Added target supply voltage and target supply current to specifications. Subchapter 5.2.1: Pictures of ways to connect J-Trace. 0.00 14 060818 TQ Subchapter 4.7 ”Using DCC for memory reads“ added. 0.00 13 060711 OO Subchapter 5.2.2: Corrected JTAG+Trace connector pinout table. J-Link / J-Trace (UM08001) © 2004-2017 SEGGER Microcontroller GmbH & Co. KG 12 Manual Revision version Date By Description 0.00 12 060628 OO Subchapter 4.1: Added ARM966E-S to List of supported ARM cores. 0.00 11 060607 SK Subchapter 5.5.2.2 changed. Subchapter 5.5.2.3 added. SK ARM9 download speed updated. Subchapter 8.2.1: Screenshot ”Start sequence“ updated. Subchapter 8.2.2 ”ID sequence“ removed. Chapter ”Support“ and ”FAQ“ merged. Various improvements 0.00 10 060526 0.00 9 060324 OO Chapter ”Literature and references“ added. Chapter ”Hardware“: Added common information trace signals. Added timing diagram for trace. Chapter ”Designing the target board for trace“ added. 0.00 8 060117 OO Chapter ”Related Software“: Added JLinkARM.dll. Screenshots updated. 0.00 7 051208 OO Chapter Working with J-Link: Sketch added. 0.00 6 051118 OO Chapter Working with J-Link: ”Connecting multiple J-Links to your PC“ added. Chapter Working with J-Link: ”Multi core debugging“ added. Chapter Background information: ”J-Link firmware“ added. 0.00 5 051103 TQ Chapter Setup: ”JTAG Speed“ added. 0.00 4 051025 OO Chapter Background information: ”Flash programming“ added. Chapter Setup: ”Scan chain configuration“ added. Some smaller changes. 0.00 3 051021 TQ Performance values updated. 0.00 2 051011 TQ Chapter ”Working with J-Link“ added. 0.00 1 050818 TW Initial Version J-Link / J-Trace (UM08001) © 2004-2017 SEGGER Microcontroller GmbH & Co. KG 13 About this document Assumptions This document assumes that you already have a solid knowledge of the following: • • • • The software tools used for building your application (assembler, linker, C compiler). The C programming language. The target processor. DOS command line. If you feel that your knowledge of C is not sufficient, we recommend The C Programming Language by Kernighan and Richie (ISBN 0–13–1103628), which describes the standard in C programming and, in newer editions, also covers the ANSI C standard. How to use this manual This manual explains all the functions and macros that the product offers. It assumes you have a working knowledge of the C language. Knowledge of assembly programming is not required. Typographic conventions for syntax This manual uses the following typographic conventions: Style Used for Body Body text. Keyword Text that you enter at the command prompt or that appears on the display (that is system functions, file- or pathnames). Parameter Parameters in API functions. Sample Sample code in program examples. Sample comment Comments in program examples. Reference Reference to chapters, sections, tables and figures or other documents. GUIElement Buttons, dialog boxes, menu names, menu commands. Emphasis Very important sections. J-Link / J-Trace (UM08001) © 2004-2017 SEGGER Microcontroller GmbH & Co. KG 14 J-Link / J-Trace (UM08001) © 2004-2017 SEGGER Microcontroller GmbH & Co. KG 15 Table of contents 1 Introduction ..................................................................................................................22 1.1 1.2 1.3 1.4 1.5 1.6 2 Licensing ..................................................................................................................... 30 2.1 2.2 2.3 3 Requirements .............................................................................................. 23 Supported OS .............................................................................................. 24 Common features of the J-Link product family ................................................. 25 Supported CPU cores ....................................................................................26 Built-in intelligence for supported CPU-cores ....................................................27 1.5.1 Intelligence in the J-Link firmware ...................................................... 27 1.5.2 Intelligence on the PC-side (DLL) ........................................................ 27 1.5.3 Firmware intelligence per model ..........................................................28 Where to find further information ...................................................................29 1.6.1 SEGGER debug probes .......................................................................29 1.6.2 Using a feature in a specific development environment .......................... 29 Components requiring a license ..................................................................... 31 Legal use of SEGGER J-Link software ............................................................. 32 2.2.1 Use of the software with 3rd party tools .............................................. 32 Illegal Clones ...............................................................................................33 J-Link software and documentation package ............................................................. 34 3.1 3.2 3.3 3.4 3.5 3.6 3.7 Software overview ........................................................................................35 J-Link Commander (Command line tool) ......................................................... 36 3.2.1 Commands ....................................................................................... 36 3.2.2 Command line options ....................................................................... 52 3.2.3 Using command files ......................................................................... 55 J-Link GDB Server ........................................................................................56 3.3.1 J-Link GDB Server CL (Windows, Linux, Mac) ........................................56 3.3.2 Debugging with J-Link GDB Server ...................................................... 56 3.3.3 Supported remote (monitor) commands ...............................................60 3.3.4 SEGGER-specific GDB protocol extensions ............................................ 72 3.3.5 Command line options ....................................................................... 76 3.3.6 Program termination ..........................................................................87 3.3.7 Semihosting ..................................................................................... 88 J-Link Remote Server ................................................................................... 89 3.4.1 List of available commands ................................................................ 89 3.4.2 Tunneling mode ................................................................................ 89 J-Mem Memory Viewer ................................................................................. 93 J-Flash ........................................................................................................ 94 J-Link RTT Viewer ........................................................................................ 95 J-Link / J-Trace (UM08001) © 2004-2017 SEGGER Microcontroller GmbH & Co. KG 16 3.8 3.9 3.10 3.11 3.12 3.13 4 Setup ......................................................................................................................... 119 4.1 4.2 4.3 4.4 4.5 4.6 4.7 5 3.7.1 RTT Viewer Startup ........................................................................... 95 3.7.2 Connection Settings ...........................................................................96 3.7.3 The Terminal Tabs ............................................................................. 96 3.7.4 Sending Input ...................................................................................97 3.7.5 Logging Terminal output .................................................................... 97 3.7.6 Logging Data .................................................................................... 97 3.7.7 Command line options ....................................................................... 98 3.7.8 Menus and Shortcuts ....................................................................... 100 3.7.9 Using "virtual" Terminals in RTT ........................................................ 101 3.7.10 Using Text Control Codes ................................................................101 J-Link SWO Viewer ..................................................................................... 103 3.8.1 Usage ............................................................................................ 104 3.8.2 List of available command line options ............................................... 104 3.8.3 Configure SWO output after device reset ............................................ 106 3.8.4 Target example code for terminal output ............................................ 107 SWO Analyzer ............................................................................................ 109 JTAGLoad (Command line tool) .................................................................. 110 J-Link RDI (Remote Debug Interface) ..........................................................111 3.11.1 Flash download and flash breakpoints .............................................. 111 Processor specific tools ..............................................................................112 3.12.1 J-Link STR91x Commander (Command line tool) ................................112 3.12.2 J-Link STM32 Unlock (Command line tool) ........................................ 115 J-Link Software Developer Kit (SDK) ........................................................... 118 Installing the J-Link software and documentation pack .................................... 120 4.1.1 Setup procedure ..............................................................................120 Setting up the USB interface ....................................................................... 121 4.2.1 Verifying correct driver installation .....................................................121 4.2.2 Uninstalling the J-Link USB driver ......................................................122 Setting up the IP interface .......................................................................... 124 4.3.1 Configuring J-Link using J-Link Configurator ........................................124 4.3.2 Configuring J-Link using the webinterface ........................................... 124 FAQs ......................................................................................................... 126 J-Link Configurator ..................................................................................... 127 4.5.1 Configure J-Links using the J-Link Configurator ................................... 127 J-Link USB identification ..............................................................................129 4.6.1 Connecting to different J-Links connected to the same host PC via USB ... 129 Using the J-Link DLL ...................................................................................130 4.7.1 What is the JLink DLL? .................................................................... 130 4.7.2 Updating the DLL in third-party programs ...........................................130 4.7.3 Determining the version of JLink DLL ................................................. 130 4.7.4 Determining which DLL is used by a program ......................................131 Working with J-Link and J-Trace .............................................................................. 132 5.1 5.2 5.3 5.4 Supported IDEs ..........................................................................................133 Connecting the target system ...................................................................... 134 5.2.1 Power-on sequence ..........................................................................134 5.2.2 Verifying target device connection ..................................................... 134 5.2.3 Problems ........................................................................................ 134 Indicators .................................................................................................. 135 5.3.1 Main indicator ................................................................................. 135 5.3.2 Input indicator ................................................................................ 135 5.3.3 Output indicator .............................................................................. 136 JTAG interface ............................................................................................137 5.4.1 Multiple devices in the scan chain ..................................................... 137 5.4.2 Sample configuration dialog boxes .....................................................137 5.4.3 Determining values for scan chain configuration .................................. 139 5.4.4 JTAG Speed .................................................................................... 140 J-Link / J-Trace (UM08001) © 2004-2017 SEGGER Microcontroller GmbH & Co. KG 17 5.5 5.6 5.7 5.8 5.9 5.10 5.11 5.12 5.13 5.14 5.15 5.16 6 Flash download .........................................................................................................205 6.1 6.2 6.3 6.4 6.5 6.6 6.7 6.8 6.9 7 SWD interface ............................................................................................141 5.5.1 SWD speed .....................................................................................141 5.5.2 SWO .............................................................................................. 141 Multi-core debugging .................................................................................. 143 5.6.1 How multi-core debugging works .......................................................143 5.6.2 Using multi-core debugging in detail .................................................. 144 5.6.3 Things you should be aware of ......................................................... 145 Connecting multiple J-Links / J-Traces to your PC ........................................... 146 5.7.1 How does it work? .......................................................................... 146 J-Link control panel .................................................................................... 148 5.8.1 Tabs ...............................................................................................148 Reset strategies ......................................................................................... 154 5.9.1 Strategies for ARM 7/9 devices ......................................................... 154 5.9.2 Strategies for Cortex-M devices .........................................................155 Using DCC for memory access ................................................................... 159 5.10.1 What is required? .......................................................................... 159 5.10.2 Target DCC handler ........................................................................159 5.10.3 Target DCC abort handler ............................................................... 159 The J-Link settings file .............................................................................. 160 5.11.1 SEGGER Embedded Studio ..............................................................160 5.11.2 Keil MDK-ARM (uVision) ................................................................. 160 5.11.3 IAR EWARM .................................................................................. 160 5.11.4 Mentor Sourcery CodeBench for ARM ............................................... 160 J-Link script files ...................................................................................... 161 5.12.1 Actions that can be customized ....................................................... 161 5.12.2 Script file API functions .................................................................. 163 5.12.3 Global DLL variables ...................................................................... 172 5.12.4 Global DLL constants ..................................................................... 176 5.12.5 Script file language ........................................................................ 178 5.12.6 Script file writing example .............................................................. 179 5.12.7 Executing J-Link script files .............................................................179 Command strings ..................................................................................... 180 5.13.1 List of available commands ............................................................. 180 5.13.2 Using command strings .................................................................. 199 Switching off CPU clock during debug ......................................................... 201 Cache handling .........................................................................................202 5.15.1 Cache coherency ........................................................................... 202 5.15.2 Cache clean area ........................................................................... 202 5.15.3 Cache handling of ARM7 cores ........................................................ 202 5.15.4 Cache handling of ARM9 cores ........................................................ 202 Virtual COM Port (VCOM) ...........................................................................203 5.16.1 Configuring Virtual COM Port ...........................................................203 Introduction ............................................................................................... 206 Licensing ................................................................................................... 207 Supported devices ...................................................................................... 208 Setup for various debuggers (internal flash) .................................................. 209 Setup for various debuggers (CFI flash) ........................................................ 210 Setup for various debuggers (SPIFI flash) ..................................................... 211 QSPI flash support ..................................................................................... 212 6.7.1 Setup the DLL for QSPI flash download .............................................. 212 Using the DLL flash loaders in custom applications ......................................... 213 Debugging applications that change flash contents at runtime .......................... 214 Flash breakpoints ......................................................................................................215 7.1 7.2 Introduction ............................................................................................... 216 Licensing ................................................................................................... 217 7.2.1 Free for evaluation and non-commercial use ....................................... 217 J-Link / J-Trace (UM08001) © 2004-2017 SEGGER Microcontroller GmbH & Co. KG 18 7.3 7.4 7.5 7.6 8 Monitor Mode Debugging ......................................................................................... 222 8.1 8.2 8.3 8.4 8.5 8.6 8.7 8.8 9 Introduction ............................................................................................... 223 Enable Monitor Debugging ........................................................................... 224 Availability and limitations of monitor mode ...................................................225 8.3.1 Cortex-M3 ...................................................................................... 225 8.3.2 Cortex-M4 ...................................................................................... 225 Monitor code ..............................................................................................226 Debugging interrupts .................................................................................. 227 Having servicing interrupts in debug mode .................................................... 228 Forwarding of Monitor Interrupts .................................................................. 229 Target application performs reset (Cortex-M) ................................................. 230 Low Power Debugging ..............................................................................................231 9.1 9.2 9.3 10 Supported devices ...................................................................................... 218 Setup & compatibility with various debuggers ................................................ 219 7.4.1 Setup .............................................................................................219 7.4.2 Compatibility with various debuggers ................................................. 219 Flash Breakpoints in QSPI flash ....................................................................220 7.5.1 Setup .............................................................................................220 FAQ .......................................................................................................... 221 Introduction ............................................................................................... 232 Activating low power mode handling for J-Link ............................................... 233 Restrictions ................................................................................................234 Open Flashloader ................................................................................................... 235 10.1 10.2 10.3 10.4 10.5 Introduction ............................................................................................. 236 General procedure .................................................................................... 237 Adding a new device .................................................................................238 Editing/Extending an Existing Device ...........................................................239 XML Tags and Attributes ............................................................................240 10.5.1..................................................................................240 10.5.2 ..................................................................................... 240 10.5.3 ................................................................................... 240 10.5.4 ........................................................................... 242 10.6 Example XML file ...................................................................................... 244 10.7 Add. Info / Considerations / Limitations ....................................................... 245 10.7.1 CMSIS Flash Algorithms Compatibility .............................................. 245 10.7.2 Customized Flash Banks ................................................................. 245 10.7.3 Supported Cores ............................................................................245 10.7.4 Information for Silicon Vendors ....................................................... 245 10.7.5 Template Projects and How To's ...................................................... 245 11 J-Flash SPI ............................................................................................................. 246 11.1 Introduction ............................................................................................. 247 11.1.1 What is J-Flash SPI? ...................................................................... 247 11.1.2 J-Flash SPI CL (Windows, Linux, Mac) .............................................. 247 11.1.3 Features ....................................................................................... 248 11.1.4 Requirements ................................................................................ 248 11.2 Licensing ................................................................................................. 249 11.2.1 Introduction .................................................................................. 249 11.3 Getting Started ........................................................................................ 250 11.3.1 Setup ........................................................................................... 250 11.3.2 Using J-Flash SPI for the first time .................................................. 250 11.3.3 Menu structure .............................................................................. 251 11.4 Settings ...................................................................................................254 11.4.1 Project Settings ............................................................................. 254 11.4.2 Global Settings ..............................................................................258 J-Link / J-Trace (UM08001) © 2004-2017 SEGGER Microcontroller GmbH & Co. KG 19 11.5 Command Line Interface ........................................................................... 260 11.5.1 Overview ...................................................................................... 260 11.5.2 Command line options ....................................................................260 11.5.3 Batch processing ........................................................................... 262 11.5.4 Programming multiple targets in parallel ...........................................262 11.6 Creating a new J-Flash SPI project ............................................................. 264 11.7 Custom Command Sequences .................................................................... 265 11.7.1 Init / Exit steps ............................................................................. 265 11.7.2 Example ....................................................................................... 265 11.7.3 J-Flash SPI Command Line Version .................................................. 266 11.8 Device specifics ........................................................................................ 269 11.8.1 SPI flashes with multiple erase commands ........................................ 269 11.9 Target systems .........................................................................................270 11.9.1 Which flash devices can be programmed? ......................................... 270 11.10 Performance ........................................................................................... 271 11.10.1 Performance values ...................................................................... 271 11.11 Background information ........................................................................... 272 11.11.1 SPI interface connection ............................................................... 272 11.12 Support ................................................................................................. 273 11.12.1 Troubleshooting ........................................................................... 273 11.12.2 Contacting support .......................................................................273 12 RDI .......................................................................................................................... 274 12.1 12.2 12.3 12.4 12.5 13 Introduction ............................................................................................. 275 12.1.1 Features ....................................................................................... 275 Licensing ................................................................................................. 276 Setup for various debuggers ...................................................................... 277 12.3.1 ARM AXD (ARM Developer Suite, ADS) ............................................. 277 12.3.2 ARM RVDS (RealView developer suite) ..............................................279 12.3.3 GHS MULTI ................................................................................... 284 Configuration ........................................................................................... 287 12.4.1 Configuration file JLinkRDI.ini ..........................................................287 12.4.2 Using different configurations .......................................................... 287 12.4.3 Using multiple J-Links simultaneously ...............................................287 12.4.4 Configuration dialog ....................................................................... 287 Semihosting ............................................................................................. 296 12.5.1 Unexpected / unhandled SWIs .........................................................296 RTT ......................................................................................................................... 297 13.1 13.2 13.3 13.4 13.5 13.6 13.7 Introduction ............................................................................................. 298 How RTT works ........................................................................................ 299 13.2.1 Target implementation ....................................................................299 13.2.2 Locating the Control Block .............................................................. 299 13.2.3 Internal structures ......................................................................... 299 13.2.4 Requirements ................................................................................ 300 13.2.5 Performance ..................................................................................300 13.2.6 Memory footprint ........................................................................... 300 RTT Communication .................................................................................. 301 13.3.1 RTT Viewer ................................................................................... 301 13.3.2 RTT Client .....................................................................................301 13.3.3 RTT Logger ................................................................................... 301 13.3.4 RTT in other host applications ......................................................... 301 Implementation ........................................................................................ 302 13.4.1 API functions ................................................................................ 302 13.4.2 Configuration defines ..................................................................... 308 ARM Cortex - Background memory access ................................................... 310 Example code .......................................................................................... 311 FAQ ........................................................................................................ 312 J-Link / J-Trace (UM08001) © 2004-2017 SEGGER Microcontroller GmbH & Co. KG 20 14 Trace ....................................................................................................................... 313 14.1 14.2 14.3 14.4 14.5 15 Target interfaces and adapters ...............................................................................321 15.1 15.2 15.3 15.4 15.5 16 20-pin J-Link connector ............................................................................. 322 15.1.1 Pinout for JTAG ............................................................................. 322 15.1.2 Pinout for SWD ............................................................................. 324 15.1.3 Pinout for SWD + Virtual COM Port (VCOM) ...................................... 325 15.1.4 Pinout for SPI ............................................................................... 326 19-pin JTAG/SWD and Trace connector ........................................................328 15.2.1 Target power supply ...................................................................... 328 9-pin JTAG/SWD connector ........................................................................ 330 Reference voltage (VTref) .......................................................................... 331 Adapters ..................................................................................................332 Background information .......................................................................................... 333 16.1 16.2 16.3 16.4 16.5 17 Introduction ............................................................................................. 314 14.1.1 What is backtrace? ........................................................................ 314 14.1.2 What is streaming trace? ................................................................314 14.1.3 What is code coverage? ..................................................................314 14.1.4 What is code profiling? ................................................................... 315 Tracing via trace pins ................................................................................ 316 14.2.1 Cortex-M specifics ..........................................................................316 14.2.2 Trace signal timing ........................................................................ 316 14.2.3 Adjusting trace signal timing on J-Trace ............................................316 14.2.4 J-Trace models with support for streaming trace ................................ 317 Tracing with on-chip trace buffer ................................................................ 318 14.3.1 CPUs that provide tracing via pins and on-chip buffer ......................... 318 Target devices with trace support ............................................................... 319 Streaming trace ....................................................................................... 320 14.5.1 Download and execution address differ .............................................320 14.5.2 Do streaming trace without prior download ....................................... 320 JTAG ....................................................................................................... 334 16.1.1 Test access port (TAP) ....................................................................334 16.1.2 Data registers ............................................................................... 334 16.1.3 Instruction register ........................................................................ 334 16.1.4 The TAP controller ......................................................................... 334 Embedded Trace Macrocell (ETM) ................................................................337 16.2.1 Trigger condition ............................................................................337 16.2.2 Code tracing and data tracing ......................................................... 337 16.2.3 J-Trace integration example - IAR Embedded Workbench for ARM ......... 337 Embedded Trace Buffer (ETB) .................................................................... 341 Flash programming ................................................................................... 342 16.4.1 How does flash programming via J-Link / J-Trace work? ...................... 342 16.4.2 Data download to RAM ................................................................... 342 16.4.3 Data download via DCC ..................................................................342 16.4.4 Available options for flash programming ........................................... 342 J-Link / J-Trace firmware ........................................................................... 344 16.5.1 Firmware update ........................................................................... 344 16.5.2 Invalidating the firmware ................................................................344 Designing the target board for trace .......................................................................346 17.1 Overview of high-speed board design ..........................................................347 17.1.1 Avoiding stubs ...............................................................................347 17.1.2 Minimizing Signal Skew (Balancing PCB Track Lengths) ....................... 347 17.1.3 Minimizing Crosstalk ...................................................................... 347 17.1.4 Using impedance matching and termination ...................................... 347 17.2 Terminating the trace signal .......................................................................348 17.2.1 Rules for series terminators ............................................................ 348 J-Link / J-Trace (UM08001) © 2004-2017 SEGGER Microcontroller GmbH & Co. KG 21 17.3 18 Semihosting .............................................................................................................350 18.1 18.2 18.3 18.4 18.5 18.6 19 Signal requirements .................................................................................. 349 Introduction ............................................................................................. 351 18.1.1 Advantages ................................................................................... 351 18.1.2 Disadvantages ............................................................................... 351 Debugger support .....................................................................................352 Implementation ........................................................................................ 353 18.3.1 SVC instruction ............................................................................. 353 18.3.2 Breakpoint instruction .................................................................... 353 18.3.3 J-Link GDBServer optimized version ................................................. 353 Communication protocol ............................................................................ 356 18.4.1 Register R0 ...................................................................................356 18.4.2 Command SYS_OPEN (0x01) .......................................................... 356 18.4.3 Command SYS_CLOSE (0x02) ......................................................... 357 18.4.4 Command SYS_WRITEC (0x03) ....................................................... 357 18.4.5 Command SYS_WRITE0 (0x04) ....................................................... 358 18.4.6 Command SYS_WRITE (0x05) ......................................................... 358 18.4.7 Command SYS_READ (0x06) .......................................................... 358 18.4.8 Command SYS_READC (0x07) .........................................................359 18.4.9 Command SYS_ISTTY (0x09) .......................................................... 359 18.4.10 Command SYS_SEEK (0x0A) ......................................................... 359 18.4.11 Command SYS_FLEN (0x0C) ......................................................... 360 18.4.12 Command SYS_REMOVE (0x0E) .....................................................360 18.4.13 Command SYS_RENAME (0x0F) ..................................................... 360 18.4.14 Command SYS_GET_CMDLINE (0x15) ............................................ 361 18.4.15 Command SYS_EXIT (0x18) .......................................................... 361 Enabling semihosting in J-Link GDBServer ................................................... 362 18.5.1 SVC variant .................................................................................. 362 18.5.2 Breakpoint variant ......................................................................... 362 18.5.3 J-Link GDBServer optimized variant ................................................. 362 Enabling Semihosting in J-Link RDI + AXD .................................................. 363 18.6.1 Using SWIs in your application ........................................................ 363 Support and FAQs .................................................................................................. 364 19.1 19.2 Measuring download speed ........................................................................ 365 Troubleshooting ........................................................................................ 366 19.2.1 General procedure ......................................................................... 366 19.3 Contacting support ................................................................................... 367 19.3.1 Contact Information ....................................................................... 367 J-Link / J-Trace (UM08001) © 2004-2017 SEGGER Microcontroller GmbH & Co. KG Chapter 1 Introduction This is the user documentation for owners of SEGGER debug probes, J-Link and J-Trace. This manual documents the software which with the J-Link Software and Documentation Package as well as advanced features of J-Link and J-Trace, like Real Time Transfer (RTT), J-Link Script Files or Trace. J-Link / J-Trace (UM08001) © 2004-2017 SEGGER Microcontroller GmbH & Co. KG 23 1.1 CHAPTER 1 Requirements Requirements Host System To use J-Link or J-Trace you need a host system running Windows 2000 or later. For a list of all operating systems which are supported by J-Link, please refer to Supported OS on page 24. Target System A target system with a supported CPU is required. You should make sure that the emulator you are looking at supports your target CPU. For more information about which J-Link features are supported by each emulator, please refer to SEGGER debug probes on page 29. J-Link / J-Trace (UM08001) © 2004-2017 SEGGER Microcontroller GmbH & Co. KG 24 CHAPTER 1 1.2 Supported OS Supported OS J-Link/J-Trace can be used on the following operating systems: • • • • • • • • • • • • • • • Microsoft Windows 2000 Microsoft Windows XP Microsoft Windows XP x64 Microsoft Windows 2003 Microsoft Windows 2003 x64 Microsoft Windows Vista Microsoft Windows Vista x64 Microsoft Windows 7 Microsoft Windows 7 x64 Microsoft Windows 8 Microsoft Windows 8 x64 Microsoft Windows 10 Microsoft Windows 10 x64 Linux macOS 10.5 and higher J-Link / J-Trace (UM08001) © 2004-2017 SEGGER Microcontroller GmbH & Co. KG 25 CHAPTER 1 1.3 Common features of the J-Link product family Common features of the J-Link product family • • • • • • • • • • • • • • • • • • • • • • • • USB 2.0 interface (Full-Speed/Hi-Speed, depends on J-Link model) Any ARM7/ARM9/ARM11 (including thumb mode), Cortex-A5/A7/A8/A9/A12/A15/A17, Cortex-M0/M1/M3/M4/M7/M23/M33, Cortex-R4/R5 core supported Automatic core recognition Maximum interface speed 15/50 MHz (depends on J-Link model) Seamless integration into all major IDEs ( List of supported IDEs ) No power supply required, powered through USB Support for adaptive clocking All JTAG signals can be monitored, target voltage can be measured Support for multiple devices Fully plug and play compatible Standard 20-pin JTAG/SWD connector, 19-pin JTAG/SWD and Trace connector, standard 38-pin JTAG+Trace connector USB and 20-pin ribbon cable included Memory viewer (J-Mem) included Remote server included, which allows using J-Trace via TCP/IP networks RDI interface available, which allows using J-Link with RDI compliant software Flash programming software (J-Flash) available Flash DLL available, which allows using flash functionality in custom applications Software Developer Kit (SDK) available 14-pin JTAG adapter available J-Link 19-pin Cortex-M Adapter available J-Link 9-pin Cortex-M Adapter available Adapter for 5V JTAG targets available for hardware revisions up to 5.3 Optical isolation adapter for JTAG/SWD interface available Target power supply via pin 19 of the JTAG/SWD interface (up to 300 mA to target with overload protection), alternatively on pins 11 and 13 of the Cortex-M 19-pin trace connector J-Link / J-Trace (UM08001) © 2004-2017 SEGGER Microcontroller GmbH & Co. KG 26 1.4 CHAPTER 1 Supported CPU cores Supported CPU cores J-Link / J-Trace supports any common ARM Cortex core, ARM legacy core, Microchip PIC32 core and Renesas RX core. For a detailed list, please refer to: SEGGER website: Supported Cores . If you experience problems with a particular core, do not hesitate to contact SEGGER. J-Link / J-Trace (UM08001) © 2004-2017 SEGGER Microcontroller GmbH & Co. KG 27 CHAPTER 1 1.5 Built-in intelligence for supported CPU-cores Built-in intelligence for supported CPU-cores In general, there are two ways to support a CPU-core in the J-Link software: 1. Intelligence in the J-Link firmware 2. Intelligence on the PC-side (DLL) Having the intelligence in the firmware is ideal since it is much more powerful and robust. The J-Link PC software automatically detects which implementation level is supported for the connected CPU-core. If intelligence in the firmware is available, it is used. If you are using a J-Link that does not have intelligence in the firmware and only PC-side intelligence is available for the connected CPU, a warning message is shown. 1.5.1 Intelligence in the J-Link firmware On newer J-Links, the intelligence for a new CPU-core is also available in the J-Link firmware which means that for these J-Links, the target sequences are no longer generated on the PCside but directly inside the J-Link. Having the intelligence in the firmware leads to improved stability and higher performance. 1.5.2 Intelligence on the PC-side (DLL) This is the basic implementation level for support of a CPU-core. This implementation is not J-Link model dependent, since no intelligence for the CPU-core is necessary in the JLink firmware. This means, all target sequences (JTAG/SWD/…) are generated on the PCside and the J-Link simply sends out these sequences and sends the result back to the DLL. Using this way of implementation also allows old J-Links to be used with new CPU cores as long as a DLL-Version is used which has intelligence for the CPU. But there is one big disadvantage of implementing the CPU core support on the DLL-side: For every sequence which shall be sent to the target a USB or Ethernet transaction is triggered. The long latency especially on a USB connection significantly affects the performance of J-Link. This is true especially when performing actions where J-Link has to wait for the CPU frequently. An example is a memory read/write operation which needs to be followed by status read operations or repeated until the memory operation is completed. Performing this kind of task with only PC-side intelligence requires to either make some assumption like: Operation is completed after a given number of cycles. Or it requires to make a lot of USB/Ethernet transactions. The first option (fast mode) will not work under some circumstances such as low CPU speeds, the second (slow mode) will be more reliable but very slow due to the high number of USB/Ethernet transactions. It simply boils down to: The best solution is having intelligence in the emulator itself! J-Link / J-Trace (UM08001) © 2004-2017 SEGGER Microcontroller GmbH & Co. KG 28 CHAPTER 1 1.5.2.1 • • • Built-in intelligence for supported CPU-cores Limitations of PC-side implementations Instability, especially on slow targets Due to the fact that a lot of USB transactions would cause a very bad performance of JLink, PC-side implementations are on the assumption that the CPU/Debug interface is fast enough to handle the commands/requests without the need of waiting. So, when using the PC-side-intelligence, stability cannot be guaranteed in all cases, especially if the target interface speed (JTAG/SWD/…) is significantly higher than the CPU speed. Poor performance Since a lot more data has to be transferred over the host interface (typically USB), the resulting download speed is typically much lower than for implementations with intelligence in the firmware, even if the number of transactions over the host interface is limited to a minimum (fast mode). No support Please understand that we cannot give any support if you are running into problems when using a PC-side implementation. Note Due to these limitations, we recommend to use PC-side implementations for evaluation only. 1.5.3 Firmware intelligence per model There are different models of J-Link / J-Trace which have built-in intelligence for different CPU-cores. Please refer to J-Link / J-Trace hardware revisions for further information. J-Link / J-Trace (UM08001) © 2004-2017 SEGGER Microcontroller GmbH & Co. KG 29 CHAPTER 1 1.6 Where to find further information Where to find further information The following items are not the scope of the J-Link / J-Trace User Guide (UM08001) and therefore documented elsewhere in the respective place described/listed below. 1.6.1 1.6.1.1 SEGGER debug probes J-Link / J-Trace current model overview In order to compare features, performance specifications, capabilities and included licenses of current J-Link / J-Trace or Flasher models, please refer to the SEGGER website: J-Link Model overview 1.6.1.2 J-Link / J-Trace hardware revisions For feature comparisons between different hardware revisions of J-Link / J-Trace or Flasher models, please refer to: SEGGER Wiki: J-Link / J-Trace / Flasher Software and Hardware features overview 1.6.1.3 J-Link / J-Trace hardware specifications For detailed general, mechanical and electrical specifications of a specific J-Link / J-Trace or Flasher model, please refer to: SEGGER Wiki: J-Link / J-Trace / Flasher general, mechanical, electrical specifications 1.6.2 Using a feature in a specific development environment For many features described in this manual, detailed explanations on how to use them with popular debuggers, IDEs and other applications are available in the SEGGER wiki. Therefore, for information on how to use a feature in a specific development environment, please refer to: SEGGER Wiki: Getting Started with Various IDEs . If a explanation is missing for the IDE used or the IDE used is not listed at all, please contact us. (see Contact Information ) J-Link / J-Trace (UM08001) © 2004-2017 SEGGER Microcontroller GmbH & Co. KG Chapter 2 Licensing This chapter describes the different license types of J-Link related software and the legal use of the J-Link software with original SEGGER and OEM products. J-Link / J-Trace (UM08001) © 2004-2017 SEGGER Microcontroller GmbH & Co. KG 31 2.1 CHAPTER 2 Components requiring a license Components requiring a license J-Link PLUS and higher are fully featured J-Links and come with all licenses included. Other models may do not come with all features enabled. For a detailed overview of the included licenses of the SEGGER debug probes, please refer to: J-Link Model overview: Licenses J-Link / J-Trace (UM08001) © 2004-2017 SEGGER Microcontroller GmbH & Co. KG 32 CHAPTER 2 2.2 Legal use of SEGGER J-Link software Legal use of SEGGER J-Link software The software consists of proprietary programs of SEGGER, protected under copyright and trade secret laws. All rights, title and interest in the software are and shall remain with SEGGER. For details, please refer to the license agreement which needs to be accepted when installing the software. The text of the license agreement is also available as entry in the start menu after installing the software. Use of software SEGGER J-Link software may only be used with original SEGGER products and authorized OEM products. The use of the licensed software to operate SEGGER product clones is prohibited and illegal. 2.2.1 Use of the software with 3rd party tools For simplicity, some components of the J-Link software are also distributed by partners with software tools designed to use J-Link. These tools are primarily debugging tools, but also memory viewers, flash programming utilities as well as software for other purposes. Distribution of the software components is legal for our partners, but the same rules as described above apply for their usage: They may only be used with original SEGGER products and authorized OEM products. The use of the licensed software to operate SEGGER product clones is prohibited and illegal. J-Link / J-Trace (UM08001) © 2004-2017 SEGGER Microcontroller GmbH & Co. KG 33 2.3 CHAPTER 2 Illegal Clones Illegal Clones Clones are copies of SEGGER products which use the copyrighted SEGGER Firmware without a license. It is strictly prohibited to use SEGGER J-Link software with illegal clones of SEGGER products. Manufacturing and selling these clones is an illegal act for various reasons, amongst them trademark, copyright and unfair business practice issues. The use of illegal J-Link clones with this software is a violation of US, European and other international laws and is prohibited. If you are in doubt if your unit may be legally used with SEGGER J-Link software, please get in touch with us. End users may be liable for illegal use of JLink software with clones. J-Link / J-Trace (UM08001) © 2004-2017 SEGGER Microcontroller GmbH & Co. KG Chapter 3 J-Link software and documentation package This chapter describes the contents of the J-Link Software and Documentation Package which can be downloaded from www.segger.com . J-Link / J-Trace (UM08001) © 2004-2017 SEGGER Microcontroller GmbH & Co. KG 35 CHAPTER 3 3.1 Software overview Software overview The J-Link Software and Documentation Package, which is available for download from segger.com/jlink-software.html , includes some applications to be used with J-Link. It also comes with USB-drivers for J-Link and documentations in pdf format. Software Description J-Link Commander Command-line tool with basic functionality for target analysis. J-Link GDB Server The J-Link GDB Server is a server connecting to the GNU Debugger (GDB) via TCP/IP. It is required for toolchains using the GDB protocol to connect to J-Link. J-Link GDB Server command line version Command line version of the J-Link GDB Server. Same functionality as the GUI version. J-Link Remote Server Utility which provides the possibility to use J-Link / J-Trace remotely via TCP/IP. J-Mem Memory Viewer Target memory viewer. Shows the memory content of a running target and allows editing as well. J-Flasha Stand-alone flash programming application. For more information about J-Flash please refer to J-Flash ARM User’s Guide (UM08003). J-Link RTT Viewer Free-of-charge utility for J-Link. Displays the terminal output of the target using RTT. Can be used in parallel with a debugger or stand-alone. J-Link SWO Viewer Free-of-charge utility for J-Link. Displays the terminal output of the target using the SWO pin. Can be used in parallel with a debugger or stand-alone. J-Link SWO Analyzer Command line tool that analyzes SWO RAW output and stores it into a file. JTAGLoad Command line tool that opens an svf file and sends the data in it via J-Link / J-Trace to the target. J-Link Configurator GUI-based configuration tool for J-Link. Allows configuration of USB identification as well as TCP/IP identification of J-Link. For more information about the J-Link Configurator, please refer to J-Link Configurator . RDI supporta Provides Remote Debug Interface (RDI) support. This allows the user to use J-Link with any RDI-compliant debugger. Processor specific tools Free command-line tools for handling specific processors. Included are: STR9 Commander and STM32 Unlock. a Full-featured J-Link (PLUS, PRO, ULTRA+) or an additional license for J-Link base model required. J-Link / J-Trace (UM08001) © 2004-2017 SEGGER Microcontroller GmbH & Co. KG 36 CHAPTER 3 3.2 J-Link Commander (Command line tool) J-Link Commander (Command line tool) J-Link Commander (JLink.exe) is a tool that can be used for verifying proper installation of the USB driver and to verify the connection to the target CPU, as well as for simple analysis of the target system. It permits some simple commands, such as memory dump, halt, step, go etc. to verify the target connection. J-Link Commander: JTAG connection 3.2.1 Commands The table below lists the available commands of J-Link Commander. All commands are listed in alphabetical order within their respective categories. Detailed descriptions of the commands can be found in the sections that follow. Command (short form) Explanation Basic clrBP Clear breakpoint. clrWP Clear watchpoint. device Selects a device. erase Erase internal flash of selected device. exec Execute command string. exit (qc, q) Closes J-Link Commander. exitonerror (eoe) Commander exits after error. f Prints firmware info. go (g) Starts the CPU core. halt (h) Halts the CPU core. hwinfo Show hardware info. is Scan chain select register length. loadfile Load data file into target memory. J-Link / J-Trace (UM08001) © 2004-2017 SEGGER Microcontroller GmbH & Co. KG 37 CHAPTER 3 Command (short form) J-Link Commander (Command line tool) Explanation log Enables log to file. mem Read memory. mem8 Read 8-bit items. mem16 Read 16-bit items. mem32 Read 32-bit items. mem64 Read 64-bit items. mr Measures reaction time of RTCK pin. ms Measures length of scan chain. power Switch power supply for target. r Resets and halts the target. readAP Reads from a CoreSight AP register. readDP Reads from a CoreSight DP register. regs Shows all current register values. rnh Resets without halting the target. rreg Shows a specific register value. rx Reset target with delay. savebin Saves target memory into binary file. setBP Set breakpoint. setPC Set the PC to specified value. setWP Set watchpoint. sleep Waits the given time (in milliseconds). speed Set target interface speed. st Shows the current hardware status. step (s) Single step the target chip. unlock Unlocks a device. verifybin Compares memory with data file. w1 Write 8-bit items. w2 Write 16-bit items. w4 Write 32-bit items. writeAP Writes to a CoreSight AP register. writeDP Writes to a CoreSight DP register. wreg Write register. Flasher I/O fdelete (fdel) Delete file on emulator. flist List directory on emulator. fread (frd) Read file from emulator. fshow Read and display file from emulator. fsize (fsz) Display size of file on emulator. fwrite (fwr) Write file to emulator. Connection ip Connect to J-Link Pro via TCP/IP. usb Connect to J-Link via USB. J-Link / J-Trace (UM08001) © 2004-2017 SEGGER Microcontroller GmbH & Co. KG 38 CHAPTER 3 3.2.1.1 J-Link Commander (Command line tool) clrBP This command removes a breakpoint set by J-Link. Syntax clrBP Parameter BP_Handle Meaning Handle of breakpoint to be removed. Example clrBP 1 3.2.1.2 clrWP This command removes a watchpoint set by J-Link. Syntax clrWP Parameter WP_Handle Meaning Handle of watchpoint to be removed. Example clrWP 0x2 3.2.1.3 device Selects a specific device J-Link shall connect to and performs a reconnect. In most cases explicit selection of the device is not necessary. Selecting a device enables the user to make use of the J-Link flash programming functionality as well as using unlimited breakpoints in flash memory. For some devices explicit device selection is mandatory in order to allow the DLL to perform special handling needed by the device. Some commands require that a device is set prior to use them. Syntax device Parameter DeviceName Meaning Valid device name: Device is selected. ?: Shows a device selection dialog. Example device stm32f407ig 3.2.1.4 erase Erases all flash sectors of the current device. A device has to be specified previously. Syntax erase 3.2.1.5 exec Execute command string. For more information about the usage of command strings please refer to Command strings . J-Link / J-Trace (UM08001) © 2004-2017 SEGGER Microcontroller GmbH & Co. KG 39 CHAPTER 3 J-Link Commander (Command line tool) Syntax exec Parameter Command Meaning Command string to be executed. Example exec SupplyPower = 1 3.2.1.6 exit This command closes the target connection, the connection to the J-Link and exits J-Link Commander. Syntax q 3.2.1.7 exitonerror This command toggles whether J-Link Commander exits on error or not. Syntax ExitOnError <1|0> Parameter Meaning 1: J-Link Commander will now exit on Error. 0: J-Link Commander will no longer exit on Error. <1|0> Example eoe 1 3.2.1.8 f Prints firmware and hardware version info. Please notice that minor hardware revisions may not be displayed, as they do not have any effect on the feature set. Syntax f 3.2.1.9 fdelete On emulators which support file I/O this command deletes a specific file. Syntax fdelete Parameter FileName Meaning File to delete from the Flasher. Example fdelete Flasher.dat 3.2.1.10 flist On emulators which support file I/O this command shows the directory tree of the Flasher. J-Link / J-Trace (UM08001) © 2004-2017 SEGGER Microcontroller GmbH & Co. KG 40 CHAPTER 3 J-Link Commander (Command line tool) Syntax flist 3.2.1.11 fread On emulators which support file I/O this command reads a specific file. Offset applies to both destination and source file. Syntax fread [ [ ]] Parameter Meaning EmuFile File name to read from. HostFile Destination file on the host. Offset Specifies the offset in the file, at which data reading is started. NumBytes Maximum number of bytes to read. Example fread Flasher.dat C:\Project\Flasher.dat 3.2.1.12 fshow On emulators which support file I/O this command reads and prints a specific file. Currently, only Flasher models support file I/O. Syntax fshow [-a] [ [ ]] Parameter Meaning FileName Source file name to read from the Flasher. a If set, Input will be parsed as text instead of being shown as hex. Offset Specifies the offset in the file, at which data reading is started. NumBytes Maximum number of bytes to read. Example fshow Flasher.dat 3.2.1.13 fsize On emulators which support file I/O this command gets the size of a specific file. Currently, only Flasher models support file I/O. Syntax fsize ] Parameter FileName Meaning Source file name to read from the Flasher. Example fsize Flasher.dat J-Link / J-Trace (UM08001) © 2004-2017 SEGGER Microcontroller GmbH & Co. KG 41 CHAPTER 3 3.2.1.14 J-Link Commander (Command line tool) fwrite On emulators which support file I/O this command writes a specific file. Currently, only Flasher models support file I/O. NumBytes is limited to 512 bytes at once. This means, if you want to write e.g. 1024 bytes, you have to send the command twice, using an appropriate offset when sending it the second time. Offset applies to both destination and source file. Syntax fwrite [ [ ]] Parameter Meaning EmuFile File name to write to. HostFile Source file on the host Offset Specifies the offset in the file, at which data writing is started. NumBytes Maximum number of bytes to write. Example fwrite Flasher.dat C:\Project\Flasher.dat 3.2.1.15 go Starts the CPU. In order to avoid setting breakpoints it allows to define a maximum number of instructions which can be simulated/emulated. This is particularly useful when the program is located in flash and flash breakpoints are used. Simulating instructions avoids to reprogram the flash and speeds up (single) stepping. Syntax Syntax go [ [ ]] Parameter Meaning NumSteps Maximum number of instructions allowed to be simulated. Instruction simulation stops whenever a breakpointed instruction is hit, an instruction which cannot be simulated/emulated is hit or when NumSteps is reached. Flags 0: Do not start the CPU if a BP is in range of NumSteps 1: Overstep BPs Example go //Simply starts the CPU go 20, 1 3.2.1.16 halt Halts the CPU Core. If successful, shows the current CPU registers. Syntax halt 3.2.1.17 hwinfo This command can be used to get information about the power consumption of the target (if the target is powered via J-Link). It also gives the information if an overcurrent happened. J-Link / J-Trace (UM08001) © 2004-2017 SEGGER Microcontroller GmbH & Co. KG 42 CHAPTER 3 J-Link Commander (Command line tool) Syntax hwinfo 3.2.1.18 ip Closes any existing connection to J-Link and opens a new one via TCP/IP. If no IP Address is specified, the Emulator selection dialog shows up. Syntax ip [ ] Parameter Meaning Valid values: IP Address: Connects the J-Link with the specified IP-Address Host Name: Resolves the host name and connects to it. *: Invokes the Emulator selection dialog. Addr Example ip 192.168.6.3 3.2.1.19 is This command returns information about the length of the scan chain select register. Syntax is 3.2.1.20 loadfile This command programs a given data file to a specified destination address. Currently supported data files are: • • • • • • *.mot *.srec *.s19 *.s *.hex *.bin Syntax loadfile [ ] Parameter Meaning Filename Source filename Addr Destination address (Required for *.bin files) Example loadfile C:\Work\test.bin 0x20000000 3.2.1.21 log Set path to logfile allowing the DLL to output logging information. If the logfile already exist, the contents of the current logfile will be overwritten. Syntax log J-Link / J-Trace (UM08001) © 2004-2017 SEGGER Microcontroller GmbH & Co. KG 43 CHAPTER 3 Parameter Filename J-Link Commander (Command line tool) Meaning Log filename Example log C:\Work\log.txt 3.2.1.22 mem The command reads memory from the target system. If necessary, the target CPU is halted in order to read memory. Syntax mem [ :] , (hex) Parameter Meaning Zone Name of memory zone to access. Addr Start address. Numbytes Number of bytes to read. Maximum is 0x100000. Example mem 0, 100 3.2.1.23 mem8 The command reads memory from the target system in units of bytes. If necessary, the target CPU is halted in order to read memory. Syntax mem [ :] , (hex) Parameter Meaning Zone Name of memory zone to access. Addr Start address. Numbytes Number of bytes to read. Maximum is 0x100000. Example mem8 0, 100 3.2.1.24 mem16 The command reads memory from the target system in units of 16-bits. If necessary, the target CPU is halted in order to read memory. Syntax mem [ :] , (hex) Parameter Meaning Zone Name of memory zone to access. Addr Start address. Numbytes Number of halfwords to read. Maximum is 0x80000. Example mem16 0, 100 J-Link / J-Trace (UM08001) © 2004-2017 SEGGER Microcontroller GmbH & Co. KG 44 CHAPTER 3 3.2.1.25 J-Link Commander (Command line tool) mem32 The command reads memory from the target system in units of 32-bits. If necessary, the target CPU is halted in order to read memory. Syntax mem [ :] , (hex) Parameter Meaning Zone Name of memory zone to access. Addr Start address. Numbytes Number of words to read. Maximum is 0x40000. Example mem32 0, 100 3.2.1.26 mem64 The command reads memory from the target system in units of 64-bits. If necessary, the target CPU is halted in order to read memory. Syntax mem [ :] , (hex) Parameter Meaning Zone Name of memory zone to access. Addr Start address. Numbytes Number of double words to read. Maximum is 0x20000. Example mem64 0, 100 3.2.1.27 mr Measure reaction time of RTCK pin. Syntax mr [ ] Parameter RepCount Meaning Number of times the test is repeated (Default: 1). Example mr 3 3.2.1.28 ms Measures the number of bits in the specified scan chain. Syntax ms Parameter ScanChain J-Link / J-Trace (UM08001) Meaning Scan chain to be measured. © 2004-2017 SEGGER Microcontroller GmbH & Co. KG 45 CHAPTER 3 J-Link Commander (Command line tool) Example ms 1 3.2.1.29 power This command sets the status of the power supply over pin 19 of the JTAG connector. The KS(Kickstart) versions of J-Link have the 5V supply over pin 19 activated by default. This feature is useful for some targets that can be powered over the JTAG connector. Syntax power [perm] Parameter Meaning State Valid values: On, Off perm Sets the specified State value as default. Example power on perm 3.2.1.30 r Resets and halts the target. Syntax r 3.2.1.31 readAP Reads from a CoreSight AP register. This command performs a full-qualified read which means that it tries to read until the read has been accepted or too many WAIT responses have been received. In case actual read data is returned on the next read request (this is the case for example with interface JTAG) this command performs the additional dummy read request automatically. Syntax ReadAP Parameter RegIndex Meaning Index of AP register to read Example // // Read AP[0], IDR (register 3, bank 15) // WriteDP 2, 0x000000F0 // Select AP[0] bank 15 ReadAP 3 // Read AP[0] IDR 3.2.1.32 readDP Reads from a CoreSight DP register. This command performs a full-qualified read which means that it tries to read until the read has been accepted or too many WAIT responses have been received. In case actual read data is returned on the next read request (this is the case for example with interface JTAG) this command performs the additional dummy read request automatically. J-Link / J-Trace (UM08001) © 2004-2017 SEGGER Microcontroller GmbH & Co. KG 46 CHAPTER 3 J-Link Commander (Command line tool) Syntax ReadDP Parameter RegIndex Meaning Index of DP register to read Example // // Read DP-CtrlStat // ReadDP 1 3.2.1.33 regs Shows all current register values. Syntax regs 3.2.1.34 rnh This command performs a reset but without halting the device. Syntax rnh 3.2.1.35 rreg The function prints the value of the specified CPU register. Syntax rreg Parameter RegIndex Meaning Register to read. Example rreg 15 3.2.1.36 rx Resets and halts the target. It is possible to define a delay in milliseconds after reset. This function is useful for some target devices which already contain an application or a boot loader and therefore need some time before the core is stopped, for example to initialize hardware, the memory management unit (MMU) or the external bus interface. Syntax rx Parameter DelayAfterReset Meaning Delay in ms. Example rx 10 J-Link / J-Trace (UM08001) © 2004-2017 SEGGER Microcontroller GmbH & Co. KG 47 CHAPTER 3 3.2.1.37 J-Link Commander (Command line tool) savebin Saves target memory into binary file. Syntax savebin , , (hex) Parameter Meaning Filename Destination file Addr Source address. NumBytes Number of bytes to read. Example savebin C:\Work\test.bin 0x0000000 0x100 3.2.1.38 setBP This command sets a breakpoint of a specific type at a specified address. Which breakpoint modes are available depends on the CPU that is used. Syntax setBP [[A/T]/[W/H]] [S/H] Parameter Meaning Addr Address to be breakpointed. A/T Only for ARM7/9/11 and Cortex-R4 devices: A: ARM mode T: THUMB mode W/H Only for MIPS devices: W: MIPS32 mode (Word) H: MIPS16 mode (Half-word) S/H S: Force software BP H: Force hardware BP Example setBP 0x8000036 3.2.1.39 setPC Sets the PC to the specified value. Syntax setpc Parameter Meaning Address the PC should be set to. Addr Example setpc 0x59C 3.2.1.40 setWP This command inserts a new watchpoint that matches the specified parameters. The enable bit for the watchpoint as well as the data access bit of the watchpoint unit are set automatically by this command. Moreover the bits DBGEXT, CHAIN and the RANGE bit (used to J-Link / J-Trace (UM08001) © 2004-2017 SEGGER Microcontroller GmbH & Co. KG 48 CHAPTER 3 J-Link Commander (Command line tool) connect one watchpoint with the other one) are automatically masked out. In order to use these bits you have to set the watchpoint by writing the ICE registers directly. Syntax setWP [ ] [ ] [ [ [ ]]] Parameter Meaning Addr Address to be watchpointed. Accesstype Specifies the control data on which data event has been set: R: read access W: write access Size Valid values: S8 | S16 | S32 Specifies to monitor an n-bit access width at the selected address. Data Specifies the Data on which watchpoint has been set. DataMask Specifies data mask used for comparison. Bits set to 1 are masked out, so not taken into consideration during data comparison. Please note that for certain cores not all Bit-Mask combinations are supported by the core-debug logic. On some cores only complete bytes can be masked out (e.g. PIC32) or similar. AddrMask Specifies the address mask used for comparison. Bits set to 1 are masked out, so not taken into consideration during address comparison. Please note that for certain cores not all Bit-Mask combinations are supported by the core-debug logic. On some cores only complete bytes can be masked out (e.g. PIC32) or similar. Example setWP 0x20000000 W S8 0xFF 3.2.1.41 sleep Waits the given time (in milliseconds). Syntax sleep Parameter Meaning Amount of time to sleep in ms. Delay Example sleep 200 3.2.1.42 speed This command sets the speed for communication with the CPU core. Syntax speed |auto|adaptive Parameter Meaning Freq Specifies the interface frequency in kHz. auto Selects auto detection of the interface speed. adaptive Selects adaptive clocking as JTAG speed. J-Link / J-Trace (UM08001) © 2004-2017 SEGGER Microcontroller GmbH & Co. KG 49 CHAPTER 3 J-Link Commander (Command line tool) Example speed 4000 speed auto 3.2.1.43 st This command prints the current hardware status. Prints the current status of TCK, TDI, TDO, TMS, TRES, TRST and the interface speeds supported by the target. Also shows the Target Voltage. Syntax st 3.2.1.44 step Target needs to be halted before calling this command. Executes a single step on the target. The instruction is overstepped even if it is breakpointed. Prints out the disassembly of the instruction to be stepped. Syntax step 3.2.1.45 unlock This command unlocks a device which has been accidentally locked by malfunction of user software. Syntax unlock Parameter DeviceName Meaning Name of the device family to unlock. Supported Devices: LM3Sxxx Kinetis EFM32Gxxx Example unlock Kinetis 3.2.1.46 usb Closes any existing connection to J-Link and opens a new one via USB. It is possible to select a specific J-Link by port number. Syntax usb [ ] Parameter Meaning Valid values: 0..3 Port Example usb 3.2.1.47 verifybin Verifies if the specified binary is already in the target memory at the specified address. J-Link / J-Trace (UM08001) © 2004-2017 SEGGER Microcontroller GmbH & Co. KG 50 CHAPTER 3 J-Link Commander (Command line tool) Syntax verifybin , Parameter Meaning Filename Sample bin. Addr Start address of memory to verify. Example verifybin C:\Work\test.bin 0x0000000 3.2.1.48 w1 The command writes one single byte to the target system. Syntax w1 [ :] , (hex) Parameter Meaning Zone Name of memory zone to access. Addr Start address. Data 8-bits of data to write. Example w1 0x10, 0xFF 3.2.1.49 w2 The command writes a unit of 16-bits to the target system. Syntax w2 [ :] , (hex) Parameter Meaning Zone Name of memory zone to access. Addr Start address. Data 16-bits of data to write. Example w2 0x0, 0xFFFF 3.2.1.50 w4 The command writes a unit of 32-bits to the target system. Syntax w4 [ :] , (hex) Parameter Meaning Zone Name of memory zone to access. Addr Start address. Data 32-bits of data to write. J-Link / J-Trace (UM08001) © 2004-2017 SEGGER Microcontroller GmbH & Co. KG 51 CHAPTER 3 J-Link Commander (Command line tool) Example w4 0x0, 0xAABBCCFF 3.2.1.51 writeAP Writes to a CoreSight AP register. This command performs a full-qualified write which means that it tries to write until the write has been accepted or too many WAIT responses have been received. Syntax WriteAP , Parameter Meaning RegIndex Index of AP register to write Data32Hex Data to write Example // // Select AHB-AP and configure it // WriteDP 2, 0x00000000 // Select AP[0] (AHB-AP) bank 0 WriteAP 4, 0x23000010 // Auto-increment, Private access, Access size: word} 3.2.1.52 writeDP Writes to a CoreSight DP register. This command performs a full-qualified write which means that it tries to write until the write has been accepted or too many WAIT responses have been received. Syntax WriteDP , Parameter Meaning RegIndex Index of DP register to write Data32Hex Data to write Example // // Write DP SELECT register: Select AP 0 bank 15 // WriteDP 2, 0x000000F0 3.2.1.53 wreg Writes into a register. The value is written into the register on CPU start. Syntax wreg , Parameter Meaning RegName Register to write to. Data Data to write to the specified register. J-Link / J-Trace (UM08001) © 2004-2017 SEGGER Microcontroller GmbH & Co. KG 52 CHAPTER 3 J-Link Commander (Command line tool) Example wreg R14, 0xFF 3.2.2 Command line options J-Link Commander can be started with different command line options for test and automation purposes. In the following, the command line options which are available for J-Link Commander are explained. All command line options are case insensitive. Command Explanation -AutoConnect Automatically start the target connect sequence -CommanderScript Passes a CommandFile to J-Link -CommandFile Passes a CommandFile to J-Link -Device Pre-selects the device J-Link Commander shall connect to -ExitOnError Commander exits after error. -If Pre-selects the target interface -IP Selects IP as host interface -JLinkScriptFile Passes a JLinkScriptFile to J-Link -JTAGConf Sets IRPre and DRPre -RTTTelnetPort Sets the RTT Telnetport -SelectEmuBySN Connects to a J-Link with a specific S/N over USB -SettingsFile Passes a SettingsFile to J-Link -Speed Starts J-Link Commander with a given initial speed 3.2.2.1 -AutoConnect This command can be used to let J-Link Commander automatically start the connect sequence for connecting to the target when entering interactive mode. Syntax -autoconnect <1|0> Example JLink.exe -autoconnect 1 3.2.2.2 -CommanderScript Similar to -CommandFile. 3.2.2.3 -CommandFile Selects a command file and starts J-Link Commander in batch mode. The batch mode of J-Link Commander is similar to the execution of a batch file. The command file is parsed line by line and one command is executed at a time. Syntax -CommandFile Example See Using command files on page 55. J-Link / J-Trace (UM08001) © 2004-2017 SEGGER Microcontroller GmbH & Co. KG 53 CHAPTER 3 3.2.2.4 J-Link Commander (Command line tool) -Device Pre-selects the device J-Link Commander shall connect to. For some devices, J-Link already needs to know the device at the time of connecting, since special handling is required for some of them. For a list of all supported device names, please refer to List of supported target devices . Syntax -Device Example JLink.exe -Device STM32F103ZE 3.2.2.5 -ExitOnError Similar to the exitonerror command. 3.2.2.6 -If Selects the target interface J-Link shall use to connect to the target. By default, J-Link Commander first tries to connect to the target using the target interface which is currently selected in the J-Link firmware. If connecting fails, J-Link Commander goes through all target interfaces supported by the connected J-Link and tries to connect to the device. Syntax -If Example JLink.exe -If SWD Additional information Currently, the following target interfaces are supported: • • 3.2.2.7 JTAG SWD -IP Selects IP as host interface to connect to J-Link. Default host interface is USB. Syntax -IP Example JLink.exe -IP 192.168.1.17 Additional information To select from a list of all available emulators on Ethernet, please use * as . 3.2.2.8 -JLinkScriptFile Passes the path of a J-Link script file to the J-Link Commander. 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 JLink Script Files . J-Link / J-Trace (UM08001) © 2004-2017 SEGGER Microcontroller GmbH & Co. KG 54 CHAPTER 3 J-Link Commander (Command line tool) Syntax JLink.exe -JLinkScriptFile Example JLink.exe -JLinkScriptFile “C:\My Projects\Default.JLinkScript” 3.2.2.9 -JTAGConf Passes IRPre and DRPre in order to select a specific device in a JTAG-chain. “-1,-1” can be used to let J-Link select a device automatically. Syntax -JTAGConf , Example JLink.exe -JTAGConf 4,1 JLink.exe -JTAGConf -1,-1 3.2.2.10 -SelectEmuBySN Connect to a J-Link with a specific serial number via USB. Useful if multiple J-Links are connected to the same PC and multiple instances of J-Link Commander shall run and each connects to another J-Link. Syntax -SelectEmuBySN Example JLink.exe -SelectEmuBySN 580011111 3.2.2.11 -RTTTelnetPort This command alters the RTT telnet port. Default is 19021. Syntax -RTTTelnetPort Example JLink.exe -RTTTelnetPort 9100 3.2.2.12 -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 Example JLink.exe -SettingsFile “C:\Work\settings.txt” 3.2.2.13 -Speed Starts J-Link Commander 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. Default interface speed is 100kHz. J-Link / J-Trace (UM08001) © 2004-2017 SEGGER Microcontroller GmbH & Co. KG 55 CHAPTER 3 J-Link Commander (Command line tool) Syntax -Speed Example JLink.exe -Speed 4000 3.2.3 Using command files J-Link commander can also be used in batch mode which allows the user to use J-Link commander for batch processing and without user interaction. Please do not confuse command file with J-Link script files (please refer to J-Link script files for more information about JLink script files). When using J-Link commander in batch mode, the path to a command file is passed to it. The syntax in the command file is the same as when using regular commands in J-Link commander (one line per command). SEGGER recommends to always pass the device name via command line option due some devices need special handling on connect/reset in order to guarantee proper function. Example JLink.exe -device STM32F103ZE -CommanderScript C:\CommandFile.jlink Contents of CommandFile.jlink: si 1 speed 4000 r h loadbin C:\\firmware.bin,0x08000000 J-Link / J-Trace (UM08001) © 2004-2017 SEGGER Microcontroller GmbH & Co. KG 56 CHAPTER 3 3.3 J-Link GDB Server J-Link GDB Server The GNU Project Debugger (GDB) is a freely available and open source debugger. It can be used in command line mode, but is also integrated in many IDEs like emIDE or Eclipse. 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. GDB Server and GDB communicate via a TCP/IP connection, using the standard GDB remote protocol. GDB Server receives the GDB commands, does 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 can be used. It also comes with some functionality not directly implemented in the GDB. These can be accessed via monitor commands, sent directly via GDB, too. J-Link GDB Server The GNU Project Debugger (GDB) is a freely available debugger, distributed under the terms of the GPL. The latest Unix version of the GDB is freely available from the GNU committee under: http://www.gnu.org/software/gdb/download/ J-Link GDB Server is distributed free of charge. 3.3.1 J-Link GDB Server CL (Windows, Linux, Mac) J-Link GDB Server CL is a commandline-only version of the GDB Server. The command line version is part of the Software and Documentation Package and also included in the Linux and MAC versions. Except for the missing GUI, J-Link GDB Server CL is identical to the normal version. All sub-chapters apply to the command line version, too. 3.3.2 Debugging with J-Link GDB Server With J-Link GDB Server programs can be debugged via GDB directly on the target device like a normal application. The application can be loaded into RAM or flash of the device. Before starting GDB Server make sure a J-Link and the target device are connected. J-Link / J-Trace (UM08001) © 2004-2017 SEGGER Microcontroller GmbH & Co. KG 57 CHAPTER 3 3.3.2.1 J-Link GDB Server Setting up GDB Server GUI version The GUI version of GDB Server is part of the Windows J-Link Software Package (JLinkGDBServer.exe). When starting GDB Server a configuration dialog pops up, letting you select the needed configurations to connect to J-Link and the target. J-Link GDB Server: Configuration All configurations can optionally be given in the 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. 3.3.2.2 Setting up GDB Server CL version The command line version of GDB Server is part of the J-Link Software Package for all supported platforms. On Windows its name is JLinkGDBServerCL.exe, on Linux and Mac it is JLinkGDBServer. Starting GDB Server on Windows To start GDB Server CL on Windows, open the ’Run’ prompt (Windows-R) or a command terminal (cmd) and enter \JLinkGDBServerCL.exe . J-Link / J-Trace (UM08001) © 2004-2017 SEGGER Microcontroller GmbH & Co. KG 58 CHAPTER 3 J-Link GDB Server Starting GDB Server on Linux / Mac To start GDB Server CL on Linux / Mac, open a terminal and call JLinkGDBServer 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 . 3.3.2.3 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. J-Link GDB Server: UI 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: • • • • • • 3.3.2.4 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. J-Link / J-Trace (UM08001) © 2004-2017 SEGGER Microcontroller GmbH & Co. KG 59 CHAPTER 3 J-Link GDB Server 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 GDB Server on start of the debug session. If it does not, or an older version of GDB Server starts, in emIDE click on JLink -> Run the JLink-plugin configuration. The screenshot below shows a debug session in IDE. For download and more information about emIDE, please refer to http://emide.org . Console GDB can be used stand-alone as a console application. J-Link / J-Trace (UM08001) © 2004-2017 SEGGER Microcontroller GmbH & Co. KG 60 CHAPTER 3 J-Link GDB Server To connect GDB to 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 http:// sourceware.org/gdb/current/onlinedocs/gdb/ . 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 ( http://www.eclipse.org/cdt/ ). CDT means “C/C++ Development Tooling” project and is designed to use the GDB as default debugger and works without any problems with the GDB Server. Refer to http://www.eclipse.org for detailed information about Eclipse. Note We only support problems directly related to the GDB Server. Problems and questions related to your remaining toolchain have to be solved on your own. 3.3.3 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. J-Link / J-Trace (UM08001) © 2004-2017 SEGGER Microcontroller GmbH & Co. KG 61 CHAPTER 3 Remote command J-Link GDB Server Explanation 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. 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. 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 J-Link / J-Trace (UM08001) © 2004-2017 SEGGER Microcontroller GmbH & Co. KG 62 CHAPTER 3 J-Link GDB Server The remote commands are case-insensitive. Note Optional parameters are set into square brackets. Note 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. 3.3.3.1 clrbp Removes an instruction breakpoint, where is the handle of breakpoint to be removed. If no handle is specified this command removes all pending breakpoints. Syntax ClrBP [ ] or ci [ ] Example > monitor clrbp 1 > monitor ci 1 3.3.3.2 cp15 Reads or writes from/to cp15 register. If 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 , , , [= ] 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 3.3.3.3 device Note Deprecated. Use command line option -device instead. J-Link / J-Trace (UM08001) © 2004-2017 SEGGER Microcontroller GmbH & Co. KG 63 CHAPTER 3 J-Link GDB Server Selects the specified target device. This is necessary for the connection and some special handling of the device. Note The device should be selected via commandline option -device when starting GDB Server. Syntax device Example > monitor device STM32F417IG < Selecting device: STM32F417IG 3.3.3.4 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 3.3.3.5 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 3.3.3.6 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 = Example #Disable Flash Breakpoints: > monitor flash breakpoints = 0 < Flash breakpoints disabled #Enable Flash Breakpoins: > monitor flash breakpoints = 1 < Flash breakpoints enabled 3.3.3.7 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. J-Link / J-Trace (UM08001) © 2004-2017 SEGGER Microcontroller GmbH & Co. KG 64 CHAPTER 3 J-Link GDB Server 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 3.3.3.8 go Starts the target CPU. Syntax go Example > monitor go 3.3.3.9 halt Halts the target CPU. Syntax halt Example > monitor halt 3.3.3.10 interface Note Deprecated. Use command line option -if instead. Selects the target interface used by J-Link / J-Trace. Syntax interface 3.3.3.11 jtagconf Configures a JTAG scan chain with multiple devices on it. 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. 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 J-Link / J-Trace (UM08001) © 2004-2017 SEGGER Microcontroller GmbH & Co. KG 65 CHAPTER 3 J-Link GDB Server 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 Example #Select the second device, where there is 1 device in front with IRLen 4 > monitor jtagconf 4 1 3.3.3.12 memU8 Reads or writes a byte from/to a given address. If is specified, this command writes the value to the given address. Otherwise this command reads from the given address. Syntax memU8 [= ] Example #Read: > monitor memU8 0x50000000 < Reading from address 0x50000000 (Data = 0x04) #Write: > monitor memU8 0x50000000 = 0xFF < Writing 0xFF @ address 0x50000000 3.3.3.13 memU16 Reads or writes a halfword from/to a given address. If is specified, this command writes the value to the given address. Otherwise this command reads from the given address. Syntax memU16 [= ] Example #Read: > monitor memU16 0x50000000 < Reading from address 0x50000000 (Data = 0x3004) #Write: > monitor memU16 0x50000000 = 0xFF00 < Writing 0xFF00 @ address 0x50000000 3.3.3.14 memU32 Reads or writes a word from/to a given address. If 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 [= ] J-Link / J-Trace (UM08001) © 2004-2017 SEGGER Microcontroller GmbH & Co. KG 66 CHAPTER 3 J-Link GDB Server Example #Read: > monitor memU32 0x50000000 < Reading from address 0x50000000 (Data = 0x10023004) #Write: > monitor memU32 0x50000000 = 0x10023004 < Writing 0x10023004 @ address 0x50000000 3.3.3.15 reg Reads or writes from/to given register. If is specified, this command writes the value into the given register. If is specified, this command writes the memory content at address to register . Otherwise this command reads the given register. Syntax reg [= ] or reg [= ()] 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) 3.3.3.16 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 J-Link / J-Trace (UM08001) © 2004-2017 SEGGER Microcontroller GmbH & Co. KG 67 CHAPTER 3 3.3.3.17 J-Link GDB Server 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 3.3.3.18 semihosting 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 Example #Enable breakOnError: > monitor semihosting breakOnError 1 3.3.3.19 semihosting 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 [ ] Example > monitor semihosting enable < Semihosting enabled (VectorAddr = 0x08) 3.3.3.20 semihosting 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. J-Link / J-Trace (UM08001) © 2004-2017 SEGGER Microcontroller GmbH & Co. KG 68 CHAPTER 3 J-Link GDB Server is • • • 1 for TELNET Client (Standard port 2333) (Default) 2 for GDB Client or 3 for both (Input via GDB Client) Syntax semihosting IOClient 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 3.3.3.21 semihosting ARMSWI Sets the SWI number used for semihosting in ARM mode. The default value for the ARMSWI is 0x123456. Syntax semihosting ARMSWI Example > monitor semihosting ARMSWI 0x123456 < Semihosting ARM SWI number set to 0x123456 3.3.3.22 semihosting ThumbSWI Sets the SWI number used for semihosting in thumb mode. The default value for the ThumbSWI is 0xAB Syntax semihosting ThumbSWI Example > monitor semihosting ThumbSWI 0xAB < Semihosting Thumb SWI number set to 0xAB 3.3.3.23 setargs Set arguments for the application, where all arguments are in one 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 is 512 characters. Syntax setargs J-Link / J-Trace (UM08001) © 2004-2017 SEGGER Microcontroller GmbH & Co. KG 69 CHAPTER 3 J-Link GDB Server Example > monitor setargs test 0 1 2 arg0=4 < Arguments: test 0 1 2 arg0=4 3.3.3.24 setbp Sets an instruction breakpoint at the given address, where 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 [ ] Example #Set a breakpoint (implicit for ARM instructions) > monitor setbp 0x00000000 #Set a breakpoint on a THUMB instruction > monitor setbp 0x00000100 0x01 3.3.3.25 sleep Sleeps for a given time, where is the time period in milliseconds to delay. While sleeping any communication is blocked until the command returns after the given period. Syntax sleep Example > monitor sleep 1000 < Sleep 1000ms 3.3.3.26 speed Note Deprecated. For setting the initial connection speed, use command line option -speed instead. Sets the JTAG speed of J-Link / J-Trace. Speed can be either fixed (in kHz), automatic recognition or adaptive. In general, Adaptive is recommended if the target has an RTCK signal which is connected to the corresponding RTCK pin of the device (S-cores only). For detailed information about the different modes, refer to JTAG Speed . The speed has to be set after selecting the interface, to change it from its default value. Syntax speed |auto|adaptive Example > monitor speed auto < Select auto target interface speed (8000 kHz) > monitor speed 4000 J-Link / J-Trace (UM08001) © 2004-2017 SEGGER Microcontroller GmbH & Co. KG 70 CHAPTER 3 J-Link GDB Server < Target interface speed set to 4000 kHz > monitor speed adaptive < Select adaptive clocking instead of fixed JTAG speed 3.3.3.27 step Performs one or more single instruction steps, where is the number of instruction steps to perform. If is not specified only one instruction step will be performed. Syntax step [ ] or si [ ] Example > monitor step 3 3.3.3.28 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 Example #Disable capturing SWO from stimulus ports 0 and 1 > monitor SWO DisableTarget 3 < SWO disabled successfully. 3.3.3.29 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 J-Link / J-Trace (UM08001) 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. 3.3.3.30 SWO GetMaxSpeed Prints the maximum SWO speed supported by and matching both, J-Link and the target CPU frequency. Syntax SWO GetMaxSpeed Example #Get SWO speed for 72MHz CPU speed > monitor SWO GetMaxSpeed 72000000 < Maximum supported SWO speed is 6000000 Hz. 3.3.3.31 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, ... 3.3.3.32 waithalt Waits for target to halt code execution, where is the maximum time period in milliseconds to wait. Syntax waithalt or wh Example #Wait for halt with a timeout of 2 seconds J-Link / J-Trace (UM08001) © 2004-2017 SEGGER Microcontroller GmbH & Co. KG 72 CHAPTER 3 J-Link GDB Server > monitor waithalt 2000 3.3.3.33 wice Writes to given IceBreaker register, where is the data to write. Syntax wice or rmib Example > monitor wice 0x0C 0x100 3.3.4 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. General query packets start with a ’q’. SEGGER-specific general queries are followed by the identifier ’Segger’ plus the command group, the actual command and its parameters. Following SEGGER-specific general query packets are available: Query Packet Explanation qSeggerSTRACE:config Configure STRACE for usage. qSeggerSTRACE:start Start STRACE. qSeggerSTRACE:stop Stop STRACE. qSeggerSTRACE:read Read STRACE data. qSeggerSWO:start Starts collecting SWO data. qSeggerSWO:stop Stops collecting SWO data. qSeggerSWO:read Reads data from SWO buffer. qSeggerSWO:GetNumBytes Returns the SWO buffer status. qSeggerSWO:GetSpeedInfo Returns info about supported speeds. 3.3.4.1 qSeggerSTRACE:config Configures STRACE for usage. Note For more information please refer to UM08002 (J-Link SDK user guide), chapter STRACE . Syntax qSeggerSTRACE:config: Parameter ConfigString J-Link / J-Trace (UM08001) Meaning String containing the configuration data separating settings by ’;’. © 2004-2017 SEGGER Microcontroller GmbH & Co. KG 73 CHAPTER 3 J-Link GDB Server Response ReturnValue is a 4 Byte signed integer. Value ReturnValue Meaning ≥ 0 O.K. <0 Error. Note ReturnValue is hex-encoded. Return value 0 is “00000000”, return value -1 is “FFFFFFFF”. 3.3.4.2 qSeggerSTRACE:start Starts capturing of STRACE data. Note For more information please refer to UM08002 (J-Link SDK user guide), chapter STRACE . Syntax qSeggerSTRACE:start Response ReturnValue is a 4 Byte signed integer. Value ReturnValue Meaning ≥ 0 O.K. <0 Error. Note ReturnValue is hex-encoded. Return value 0 is “00000000”, return value -1 is “FFFFFFFF”. 3.3.4.3 qSeggerSTRACE:stop Stops capturing of STRACE data. Note For more information please refer to UM08002 (J-Link SDK user guide), chapter STRACE . Syntax qSeggerSTRACE:stop Response ReturnValue is a 4 Byte signed integer. J-Link / J-Trace (UM08001) © 2004-2017 SEGGER Microcontroller GmbH & Co. KG 74 CHAPTER 3 Value ReturnValue J-Link GDB Server Meaning ≥ 0 O.K. <0 Error. Note ReturnValue is hex-encoded. Return value 0 is “00000000”, return value -1 is “FFFFFFFF”. 3.3.4.4 qSeggerSTRACE:read Reads the last recently called instruction addresses. The addresses are returned LIFO, meaning the last recent address is returned first. Note For more information please refer to UM08002 (J-Link SDK user guide), chapter STRACE . Syntax qSeggerSTRACE:read: Parameter NumItems Meaning Maximum number of trace data (addresses) to be read. Hexadecimal. Response [ …] ReturnValue is a 4 Byte signed integer. Value ReturnValue Meaning ≥ 0 Number of items read. <0 Error. Note ReturnValue and ItemN are hex-encoded. e.g. 3 Items read: 0x08000010, 0x08000014, 0x08000018 Response will be: 00000003080000100800001408000018 3.3.4.5 qSeggerSWO:start Starts collecting SWO data with the desired interface speed. The target is not being touched in any way, therefore you are responsible for doing the necessary target setup afterwards. Syntax qSeggerSWO:start: : Parameter Meaning Enc Encoding type, only 0 (“UART encoding”) is allowed. Hexadecimal. Freq The desired interface speed. Hexadecimal. Response ReturnValue is “OK” or empty on error. J-Link / J-Trace (UM08001) © 2004-2017 SEGGER Microcontroller GmbH & Co. KG 75 CHAPTER 3 3.3.4.6 J-Link GDB Server qSeggerSWO:stop Stops collecting SWO data and returns the remaining bytes to be read from the buffer. Syntax qSeggerSWO:stop Response ReturnValue is the hexadecimal number of bytes in the buffer or empty on error. 3.3.4.7 qSeggerSWO:read Reads the specified number of SWO data bytes from the buffer. Syntax qSeggerSWO:read: Parameter NumBytes Meaning Number of bytes to read (up to max. 64MB). Response ReturnValue is a hex-encoded string or empty on error. Note The function will always return as much data bytes as requested. If more bytes than available are requested, excessive data has undefined values. 3.3.4.8 qSeggerSWO:GetNumBytes Returns the amount of available bytes in the buffer. Syntax qSeggerSWO:GetNumBytes Response ReturnValue is the hexadecimal number of bytes in the buffer or empty on error. 3.3.4.9 qSeggerSWO:GetSpeedInfo Returns 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 qSeggerSTRACE:GetSpeedInfo: Parameter Enc Meaning Encoding type, only 0 (“UART encoding”) is allowed. Hexadecimal. Response , J-Link / J-Trace (UM08001) © 2004-2017 SEGGER Microcontroller GmbH & Co. KG 76 CHAPTER 3 Value J-Link GDB Server Meaning BaseFreq Base frequency of the connected J-Link. MinDiv Minimum divider of the connected J-Link. ReturnValue is empty on error. 3.3.5 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. J-Link / J-Trace (UM08001) © 2004-2017 SEGGER Microcontroller GmbH & Co. KG 77 CHAPTER 3 Command line option J-Link GDB Server Explanation -nologtofile Do not generate a GDB Server log file. (Default) -halt Halt the target on start of GDB Server. -nohalt Do not halt the target on start of GDB Server. (Default) -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. -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. 3.3.5.1 -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 Example jlinkgdbserver -CPU ARM7_9 Add. information The following table lists all valid values for : J-Link / J-Trace (UM08001) © 2004-2017 SEGGER Microcontroller GmbH & Co. KG 78 CHAPTER 3 J-Link GDB Server 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. 3.3.5.2 -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 Example jlinkgdbserver -device AT91SAM7SE256 Add. information For a list of all valid values for , please refer to List of supported target devices . 3.3.5.3 -endian Sets the endianness of the target where endianness can either be “little” or “big”. Syntax -endian Example jlinkgdbserver -endian little Note When using GDB Server CL this option is mandatory to correctly connect to the target, and should be given before connection via GDB. 3.3.5.4 -if Selects the target interface which is used by J-Link to connect to the device. The default value is JTAG. Syntax -if J-Link / J-Trace (UM08001) © 2004-2017 SEGGER Microcontroller GmbH & Co. KG 79 CHAPTER 3 J-Link GDB Server Example jlinkgdbserver -if SWD Add. information Currently, the following values are accepted for : • • • • JTAG SWD FINE 2-wire-JTAG-PIC32 3.3.5.5 -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. Example jlinkgdbserver -ir 3.3.5.6 -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. 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 Example jlinkgdbserver -excdbg 4 3.3.5.7 -jtagconf Configures a JTAG scan chain with multiple devices on it. 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. is the number of devices closer to TDI. For more detailed information J-Link / J-Trace (UM08001) © 2004-2017 SEGGER Microcontroller GmbH & Co. KG 80 CHAPTER 3 J-Link GDB Server of how to configure a scan chain with multiple devices please refer to Determining values for scan chain configuration . Syntax -jtagconf , Example #Select the second device, where there is 1 device in front with IRLen 4 jlinkgdbserver -jtagconf 4,1 3.3.5.8 -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 Example jlinkgdbserver -LocalhostOnly 0 //Listen on any IP address (Linux/MAC default) jlinkgdbserver -LocalhostOnly 1 //Listen on localhost only (Windows default) 3.3.5.9 -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 Example jlinkgdbserver -log “C:\my path\to\file.log” 3.3.5.10 -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 J-Link / J-Trace (UM08001) © 2004-2017 SEGGER Microcontroller GmbH & Co. KG 81 CHAPTER 3 J-Link GDB Server Example jlinkgdbserver -logtofile jlinkgdbserver -logtofile -log “C:\my path\to\file.log” 3.3.5.11 -halt Halts the target after connecting to it on start of 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 3.3.5.12 -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 3.3.5.13 -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 3.3.5.14 -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 GDB Server until changed via -nologtofile or the GUI. When this option is used after -log, no log file J-Link / J-Trace (UM08001) © 2004-2017 SEGGER Microcontroller GmbH & Co. KG 82 CHAPTER 3 J-Link GDB Server 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 3.3.5.15 -nohalt When connecting to the target after starting GDB Server, the target is not explicitly halted and the CPU registers will not be inited. 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 3.3.5.16 -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 3.3.5.17 -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. J-Link / J-Trace (UM08001) © 2004-2017 SEGGER Microcontroller GmbH & Co. KG 83 CHAPTER 3 J-Link GDB Server Syntax -nostayontop Example 3.3.5.18 -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 3.3.5.19 -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 -vd 3.3.5.20 -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 Example jlinkgdbserver -port 2345 3.3.5.21 -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 Package 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. J-Link / J-Trace (UM08001) © 2004-2017 SEGGER Microcontroller GmbH & Co. KG 84 CHAPTER 3 J-Link GDB Server Syntax -rtos [.dll|.so] Example jlinkgdbserver -rtos GDBServer\RTOSPlugin_embOS 3.3.5.22 -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 Example -jlinkscriptfile “C:\My Projects\Default.JLinkScript” 3.3.5.23 -select Specifies the host interface to be used to connect to J-Link. Currently, USB and TCP/IP are available. Syntax -select / 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. 3.3.5.24 -settingsfile Select a J-Link settings file to be used for the target device. The settings fail can contain all configurable options of the Settings tab in J-Link Control panel. Syntax -SettingsFile Example jlinkgdbserver -SettingsFile “C:\Temp\GDB Server.jlink” 3.3.5.25 -silent Starts the GDB Server in silent mode. No log window messages will be shown. Note J-Link / J-Trace (UM08001) © 2004-2017 SEGGER Microcontroller GmbH & Co. KG 85 CHAPTER 3 J-Link GDB Server 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 3.3.5.26 -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 3.3.5.27 -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 Example jlinkgdbserver -speed 2000 3.3.5.28 -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 3.3.5.29 -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. J-Link / J-Trace (UM08001) © 2004-2017 SEGGER Microcontroller GmbH & Co. KG 86 CHAPTER 3 J-Link GDB Server Note The recommended order is to power the target, connect it to J-Link and then start GDB Server. Syntax -timeout Example Allow target connection within 10 seconds. jlinkgdbserver -timeout 10000 3.3.5.30 -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 / OS X. jlinkgdbserver -device UnknownDeviceName 3.3.5.31 -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 Example jlinkgdbserver -SWOPort 2553 3.3.5.32 -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 J-Link / J-Trace (UM08001) © 2004-2017 SEGGER Microcontroller GmbH & Co. KG 87 CHAPTER 3 J-Link GDB Server Using multiple instances of GDB Server, setting custom values for this option is necessary. Syntax -TelnetPort Example jlinkgdbserver -TelnetPort 2554 3.3.5.33 -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 3.3.5.34 -x Starts the GDB Server with a gdbinit (configuration) file. In contrast to the -xc command line option the GDB Server runs the commands in the gdbinit file once only direct after the first connection of a client. Syntax -x Example jlinkgdbserver -x C:\MyProject\Sample.gdb 3.3.5.35 -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 Example jlinkgdbserver -xc C:\MyProject\Sample.gdb 3.3.6 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. J-Link / J-Trace (UM08001) © 2004-2017 SEGGER Microcontroller GmbH & Co. KG 88 CHAPTER 3 3.3.6.1 J-Link GDB Server 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. 3.3.7 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 . J-Link / J-Trace (UM08001) © 2004-2017 SEGGER Microcontroller GmbH & Co. KG 89 CHAPTER 3 3.4 J-Link Remote Server J-Link Remote Server J-Link Remote Server allows using J-Link / J-Trace remotely via TCP/IP. This enables you to connect to and fully use a J-Link / J-Trace from another computer. Performance is just slightly (about 10%) lower than with direct USB connection. J-Link Remote Server 3.4.1 List of available commands The table below lists the commands line options accepted by the J-Link Remote Server Command Description -port Selects the IP port on which the J-Link Remote Server is listening. -UseTunnel Starts J-Link Remote Server in tunneling mode -SelectEmuBySN Selects the J-Link to connect to by its serial number. 3.4.2 Tunneling mode The Remote server provides a tunneling mode which allows remote connection to a J-Link / J-Trace from any computer, even from outside the local network. To give access to a J-Link neither a remote desktop or VPN connection nor changing some difficult firewall settings is necessary. When started in tunneling mode the Remote server connects to the SEGGER tunnel server via port 19020 and registers with its serial number. To connect to the J-Link from the remote computer an also simple connection to tunnel: can be established and the debugger is connected to the J-Link. J-Link / J-Trace (UM08001) © 2004-2017 SEGGER Microcontroller GmbH & Co. KG 90 CHAPTER 3 J-Link Remote Server J-Link Remote Server: Connected to SEGGER tunnel server Example scenario A device vendor is developing a new device which shall be supported by J-Link. Because there is only one prototype, a shipment to SEGGER is not possible. Instead the vendor can connect the device via J-Link to a local computer and start the Remote server in tunneling mode. The serial number of the J-Link is then sent to a to an engineer at SEGGER. The engineer at SEGGER can use J-Link Commander or a debugger to test and debug the new device without the need to have the device on the desk. J-Link / J-Trace (UM08001) © 2004-2017 SEGGER Microcontroller GmbH & Co. KG 91 CHAPTER 3 J-Link Remote Server Start J-Link Remote Server in tunneling mode Connect to the J-Link / J-Trace via J-Link Commander J-Link Commander can be used to verify a connection to the J-Link can be established as follows: Start J-Link Commander From within J-Link Commander enter ip tunnel: If the connection was successful it should look like in this screenshot. J-Link / J-Trace (UM08001) © 2004-2017 SEGGER Microcontroller GmbH & Co. KG 92 CHAPTER 3 J-Link Remote Server Troubleshooting Problem Solution Remote server cannot connect to tunnel server. 1. Make sure the Remote server is not blocked by any firewall. 2. Make sure port 19020 is not blocked by any firewall. 3. Contact network admin. J-Link Commander cannot connect to tunnel server. 1. Make sure Remote server is started correctly. 2. Make sure the entered serial number is correct. 3. Make sure port 19020 is not blocked by any firewall. Contact network admin. To test whether a connection to the tunnel server can be established or not a network protocol analyzer like Wireshark can help. The network transfer of a successful connection should look like: J-Link / J-Trace (UM08001) © 2004-2017 SEGGER Microcontroller GmbH & Co. KG 93 3.5 CHAPTER 3 J-Mem Memory Viewer J-Mem Memory Viewer J-Mem displays memory contents of target systems and allows modifications of RAM and SFRs (Special Function Registers) while the target is running. This makes it possible to look into the memory of a target system at run-time; RAM can be modified and SFRs can be written. You can choose between 8/16/32-bit size for read and write accesses. J-Mem works nicely when modifying SFRs, especially because it writes the SFR only after the complete value has been entered. J-Link / J-Trace (UM08001) © 2004-2017 SEGGER Microcontroller GmbH & Co. KG 94 3.6 CHAPTER 3 J-Flash J-Flash J-Flash is an application to program data images to the flash of a target device. With JFlash the internal flash of all J-Link supported devices can be programmed, as well as common external flashes connected to the device. Beside flash programming all other flash operations like erase, blank check and flash content verification can be done. J-Flash requires an additional license from SEGGER to enable programming. For license keys, as well as evaluation licenses got to www.segger.com or contact us directly. J-Link / J-Trace (UM08001) © 2004-2017 SEGGER Microcontroller GmbH & Co. KG 95 CHAPTER 3 3.7 J-Link RTT Viewer J-Link RTT Viewer J-Link RTT Viewer is a Windows GUI application to use all features of RTT in one application. It supports: • • • • • • Displaying terminal output of Channel 0. Up to 16 virtual Terminals on Channel 0. Sending text input to Channel 0. Interpreting text control codes for colored text and controlling the Terminal. Logging terminal data into a file. Logging data on Channel 1. For general information about RTT, please refer to RTT on page 297. 3.7.1 RTT Viewer Startup Make sure J-Link and target device are connected and powered up. Start RTT Viewer by opening the executable (JLinkRTTViewer.exe) from the installation folder of the J-Link Software or the start menu. Unless the command line parameter – autoconnect is set, the Configuration Dialog will pop up. Configure the Connection Settings as described below and click OK. The connection settings and all in app configuration will be saved for the next start of J-Link RTT Viewer. J-Link / J-Trace (UM08001) © 2004-2017 SEGGER Microcontroller GmbH & Co. KG 96 CHAPTER 3 3.7.2 J-Link RTT Viewer Connection Settings RTT Viewer can be used in two modes: • • Stand-alone, opening an own connection to J-Link and target. In attach mode, connecting to an existing J-Link connection of a debugger. Stand-alone connection settings In stand-alone mode RTT Viewer needs to know some settings of J-Link and target device. Select USB or TCP/IP as the connection to J-Link. For USB a specific J-Link serial number can optionally be entered, for TCP/IP the IP or hostname of the J-Link has to be entered. Select the target device to connect to. This allows J-Link to search in the known RAM of the target. Select the target interface and its speed. The RTT Control Block can be searched for fully automatically, it can be set to a fixed address or it can be searched for in one or more specific memory ranges. Attaching to a connection In attach mode RTT Viewer does not need any settings. Select Existing Session. For attach mode a connection to J-Link has to be opened and configured by another application like a debugger or simply J-Link Commander. If the RTT Control Block cannot be found automatically, configuration of its location has to be done by the debugger / application. 3.7.3 The Terminal Tabs RTT Viewer allows displaying the output of Channel 0 in different “virtual” Terminals. The target application can switch between terminals with SEGGER_RTT_SetTerminal() and SEGGER_RTT_TerminalOut(). RTT Viewer displays the Terminals in different tabs. J-Link / J-Trace (UM08001) © 2004-2017 SEGGER Microcontroller GmbH & Co. KG 97 CHAPTER 3 J-Link RTT Viewer All Terminals The All Terminals tab displays the complete output of RTT Channel 0 and can display the user input (Check Input -> Echo input… -> Echo to “All Terminals”). Each output line is prefixed by the Terminal it has been sent to. Additionally, output on Terminal 1 is shown in red, output on Terminals 2 - 15 in gray. Terminal 0 - 15 Each tab Terminal 0 - Terminal 15 displays the output which has been sent to this Terminal. The Terminal tabs interpret and display Text Control Codes as sent by the application to show colored text or erase the screen. By default, if the RTT application does not set a Terminal Id, the output is displayed in Terminal 0. The Terminal 0 tab can additionally display the user input. (Check Input -> Echo input… -> Echo to “Terminal 0”) Each Terminal tab can be shown or hidden via the menu Terminals -> Terminals… or their respective shortcuts as described below. 3.7.4 Sending Input RTT Viewer supports sending user input to RTT Down Channel 0 which can be read by the target application with SEGGER_RTT_GetKey() and SEGGER_RTT_Read(). Input can be entered in the text box below the Terminal Tabs. RTT Viewer can be configured to directly send each character while typing or buffer it until Enter is pressed (Menu Input -> Sending…). In stand-alone mode RTT Viewer can retry to send input, in case the target input buffer is full, until all data could be sent to the target via Input -> Sending… -> Block if FIFO full. 3.7.5 Logging Terminal output The output of Channel 0 can be logged into a text file. The format is the same as used in the All Terminals tab. Terminal Logging can be started via Logging -> Start Terminal Logging… 3.7.6 Logging Data Additionally to displaying output of Channel 0, RTT Viewer can log data which is sent on RTT Channel 1 into a file. This can for example be used to sent instrumented event tracing data. The data log file contains header and footer and the binary data as received from the application. J-Link / J-Trace (UM08001) © 2004-2017 SEGGER Microcontroller GmbH & Co. KG 98 CHAPTER 3 J-Link RTT Viewer Data Logging can be started via Logging -> Start Data Logging… Note Data Logging is only available in stand-alone mode. 3.7.7 Command line options J-Link RTT Viewer can be configured via command line parameters. In the following, the command line options which are available for J-Link RTT Viewer are explained. All command line options are case insensitive. Short and long command names have the same syntax. Command line option Explanation -d, –device Select the connected target device. -ct, –connection Sets the connection type -if, –interface Sets the interface type -ip, –host The IP address of the J-Link -s, –speed Interface speed in kHz -sn, –serialnumber Select the J-Link with a specific S/N -ra, –rttaddr Sets the address of the RTT control block -rr, –rttrange Specify RTT search range -a, –autoconnect Automatically connect to target, suppress settings dialog 3.7.7.1 --device Selects the device J-Link RTT Viewer shall connect to. Syntax –device Example JLinkRTTViewer.exe –device STM32F103ZE 3.7.7.2 --connection Sets the connection type. The connection to the J-Link can either be made directly over USB, IP or using an existing running session (e.g. the IDE’s debug session). In case of using an existing session, no further configuration options are required. Syntax –connection Example JLinkRTTViewer.exe –connection ip 3.7.7.3 --interface Sets the interface J-Link shall use to connect to the target. As interface types FINE, JTAG and SWD are supported. Syntax –interface J-Link / J-Trace (UM08001) © 2004-2017 SEGGER Microcontroller GmbH & Co. KG 99 CHAPTER 3 J-Link RTT Viewer Example JLinkRTTViewer.exe –interface swd 3.7.7.4 --host Enter the IP address or hostname of the J-Link. This option only applies, if connection type IP is used. Use * as for a list of available J-Links in the local subnet. Syntax –host Example JLinkRTTViewer.exe –host 192.168.1.17 3.7.7.5 --speed Sets the interface speed in kHz for target communication. Syntax –speed Example JLinkRTTViewer.exe –speed 4000 3.7.7.6 --serialnumber Connect to a J-Link with a specific serial number via USB. Useful if multiple J-Links are connected to the same PC and multiple instances of J-Link RTT Viewer shall run and each connects to another J-Link. Syntax –serialnumber Example JLinkRTTViewer.exe –serialnumber 580011111 3.7.7.7 --rttaddr Sets a fixed address as location of the RTT control block. Automatic searching for the RTT control block is disabled. Syntax –rttaddr Example JLinkRTTViewer.exe -rttaddr 0x20000000 3.7.7.8 --rttrange Sets one or more memory ranges, where the J-Link DLL shall search for the RTT control block. Syntax –rttrange [, ]> J-Link / J-Trace (UM08001) © 2004-2017 SEGGER Microcontroller GmbH & Co. KG 100 CHAPTER 3 J-Link RTT Viewer Example JLinkRTTViewer.exe -rttrange “20000000 400” 3.7.7.9 --autoconnect Let J-Link RTT Viewer connect automatically to the target without showing the Connection Settings (see Connection Settings ). Syntax –autoconnect Example JLinkRTTViewer.exe –autoconnect 3.7.8 Menus and Shortcuts File menu elements Menu entry Contents Shortcut -> Connect… Opens the connect dialog and connects to the targets F2 -> Disconnect Disconnects from the target F3 -> Exit Closes connection and exit RTT Viewer. Alt-F4 Terminals menu elements Menu entry Contents Shortcut -> Add next terminal Opens the next available Terminal Tab. Alt-A -> Clear active terminal Clears the currently selected terminal tab. Alt-R -> Close active terminal Closes the active Terminal Tab. Alt-W -> Open Terminal on output If selected, a terminal is automatically created, if data for this terminal is received. -> Show Log Opens or closes the Log Tab. Alt-L Opens or closes the Terminal Tab. AltShift-0 AltShift-F Terminals -> Terminals… –> Terminal 0 - 15 Input menu elements Menu entry -> Clear input field Contents Clears the input field without sending entered data. Shortcut Button “Clear” Input -> Sending… –> Send on Input If selected, entered input will be sent directly to the target while typing. –> Send on Enter If selected, entered input will be sent when pressing Enter. –> Block if FIFO full If checked, RTT Viewer will retry to send all input to the target when the target buffer is full. Input -> End of line… J-Link / J-Trace (UM08001) © 2004-2017 SEGGER Microcontroller GmbH & Co. KG 101 CHAPTER 3 J-Link RTT Viewer Menu entry Contents –> Windows format (CR +LF) –> Unix format (LF) –> Mac format (CR) –> None Selects the end of line character to be sent on Enter. Shortcut Input -> Echo input… –> Echo to “All Terminals” If checked, sent input will be displayed in the All Terminals Tab. –> Echo to “Terminal 0” If checked, sent input will be displayed in the Terminal Tab 0. Logging menu elements Menu entry -> Start Terminal logging… Contents Starts logging terminal data to a file. Shortcut F5 -> Stop Terminal logging Stops logging terminal data and closes the file. Shift-F5 -> Start Data logging… Starts logging data of Channel 1 to a file. F6 -> Stop Data logging Stops logging data and closes the file. Shift-F6 Help menu elements Menu entry Contents Shortcut -> About… Shows version info of RTT Viewer. F12 -> J-Link Manual… Opens the J-Link Manual PDF file. F11 -> RTT Webpage… Opens the RTT webpage. F10 Tab context menu elements Menu entry Contents Shortcut -> Close Terminal Closes this Terminal Tab Alt-W -> Clear Terminal Clears the displayed output of this Terminal Tab. Alt-R 3.7.9 Using "virtual" Terminals in RTT For virtual Terminals the target application needs only Up Channel 0. This is especially important on targets with low RAM. If nothing is configured, all data is sent to Terminal 0. The Terminal to output all following via Write, WriteString or printf can be set with SEGGER_RTT_SetTerminal(). Output of only one string via a specific Terminal can be done with SEGGER_RTT_TerminalOut(). The sequences sent to change the Terminal are interpreted by RTT Viewer. Other applications like a Telnet Client will ignore them. 3.7.10 Using Text Control Codes RTT allows using Text Control Codes (ANSI escape codes) to configure the display of text. RTT Viewer supports changing the text color and background color and can erase the Terminal. These Control Codes are pre-defined in the RTT application and can easily be used in the application. J-Link / J-Trace (UM08001) © 2004-2017 SEGGER Microcontroller GmbH & Co. KG 102 CHAPTER 3 J-Link RTT Viewer Example 1 SEGGER_RTT_WriteString(0, RTT_CTRL_RESET"Red: " \ RTT_CTRL_TEXT_BRIGHT_RED"This text is red. " \ RTT_CTRL_TEXT_BLACK"" \ RTT_CTRL_BG_BRIGHT_RED"This background is red. " \ RTT_CTRL_RESET"Normal text again." ); Example 2 SEGGER_RTT_printf(0, "%sTime:%s%s %.7d\n", RTT_CTRL_RESET, RTT_CTRL_BG_BRIGHT_RED, RTT_CTRL_TEXT_BRIGHT_WHITE, 1111111 ); // // Clear the terminal. // The first line will not be shown after this command. // SEGGER_RTT_WriteString(0, RTT_CTRL_CLEAR); SEGGER_RTT_printf(0, "%sTime: %s%s%.7d\n", RTT_CTRL_RESET, RTT_CTRL_BG_BRIGHT_RED, RTT_CTRL_TEXT_BRIGHT_WHITE, 2222222 ); J-Link / J-Trace (UM08001) © 2004-2017 SEGGER Microcontroller GmbH & Co. KG 103 CHAPTER 3 3.8 J-Link SWO Viewer J-Link SWO Viewer Free-of-charge utility for J-Link. Displays the terminal output of the target using the SWO pin. The stimulus port(s) from which SWO data is received can be chosen by using the port checkboxes 0 to 31. Can be used in parallel with a debugger or stand-alone. This is especially useful when using debuggers which do not come with built-in support for SWO such as most GDB / GDB+Eclipse based debug environments. 3.8.0.1 J-Link SWO Viewer CL Command line-only version of SWO Viewer. All commands available for J-Link SWO Viewer can be used with J-Link SWO Viewer Cl. Similar to the GUI Version, J-Link SWO Viewer Cl asks for a device name or CPU clock speed at startup to be able to calculate the correct SWO speed or to connect to a running J-Link GDB Server. Using the syntax given below(see List of available command line options ), J-Link SWO Viewer Cl can be directly started with parameters. J-Link / J-Trace (UM08001) © 2004-2017 SEGGER Microcontroller GmbH & Co. KG 104 CHAPTER 3 3.8.1 J-Link SWO Viewer Usage J-Link SWO Viewer is available via the start menu. It asks for a device name or CPU clock speed at startup to be able to calculate the correct SWO speed or to connect to a running J-Link GDB Server. When running in normal mode J-Link SWO Viewer automatically performs the necessary initialization to enable SWO output on the target, in GDB Server mode the initialization has to be done by the debugger. 3.8.2 List of available command line options J-Link SWO Viewer can also be controlled from the command line if used in a automated test environment etc. When passing all necessary information to the utility via command line, the configuration dialog at startup is suppressed. Minimum information needed by JLink SWO Viewer is the device name (to enable CPU frequency auto detection) or the CPU clock speed. The table below lists the commands accepted by the J-Link SWO View Command Description -cpufreq Select the CPU frequency. -device Select the target device. -itmmask Selects a set of itm stimulus ports which should be used to listen to. -itmport Selects a itm stimulus port which should be used to listen to. -outputfile Print the output of SWO Viewer to the selected file. -settingsfile Specify a J-Link settings file. -swofreq Select the CPU frequency. 3.8.2.1 -cpufreq Defines the speed in Hz the CPU is running at. If the CPU is for example running at 96 MHz, the command line should look as below. Syntax -cpufreq Example -cpufreq 96000000 3.8.2.2 -device Select the target device to enable the CPU frequency auto detection of the J-Link DLL. To select a ST STM32F207IG as target device, the command line should look as below. For a list of all supported device names, please refer to: List of supported target devices J-Link / J-Trace (UM08001) © 2004-2017 SEGGER Microcontroller GmbH & Co. KG 105 CHAPTER 3 J-Link SWO Viewer Syntax -device Example -device STM32F207IG 3.8.2.3 -itmmask Defines a set of stimulusports from which SWO data is received and displayed by SWO Viewer. If itmmask is given, itmport will be ignored. Syntax -itmmask Example Listen on ports 0 and 2 -itmmask 0x5 3.8.2.4 -itmport Defines the stimulus port from which SWO data is received and displayed by the SWO Viewer. Default is stimulus port 0. The command line should look as below. Syntax -itmport Example -itmport 0 3.8.2.5 -outputfile Define a file to which the output of SWO Viewer is printed. Syntax -outputfile Example -outputfile “C:\Temp\Output.log” 3.8.2.6 -settingsfile Select a J-Link settings file to use for the target device. Syntax -settingsfile Example -settingsfile “C:\Temp\Settings.jlink” 3.8.2.7 -swofreq Define the SWO frequency that shall be used by J-Link SWO Viewer for sampling SWO data. Usually not necessary to define since optimal SWO speed is calculated automatically based on the CPU frequency and the capabilities of the connected J-Link. J-Link / J-Trace (UM08001) © 2004-2017 SEGGER Microcontroller GmbH & Co. KG 106 CHAPTER 3 J-Link SWO Viewer Syntax -swofreq Example -swofreq 6000 3.8.3 Configure SWO output after device reset In some situations it might happen that the target application is reset and it is desired to log the SWO output of the target after reset during the booting process. For such situations, the target application itself needs to initialize the CPU for SWO output, since the SWO Viewer is not restarted but continuously running. Example code for enabling SWO out of the target application #define ITM_ENA #define ITM_TPR (*(volatile unsigned int*)0xE0000E00) // ITM Enable (*(volatile unsigned int*)0xE0000E40) // Trace Privilege // Register #define ITM_TCR (*(volatile unsigned int*)0xE0000E80) // ITM Trace Control Reg. #define ITM_LSR (*(volatile unsigned int*)0xE0000FB0) // ITM Lock Status // Register #define DHCSR (*(volatile unsigned int*)0xE000EDF0) // Debug register #define DEMCR (*(volatile unsigned int*)0xE000EDFC) // Debug register #define TPIU_ACPR (*(volatile unsigned int*)0xE0040010) // Async Clock // prescaler register #define TPIU_SPPR (*(volatile unsigned int*)0xE00400F0) // Selected Pin Protocol // Register #define DWT_CTRL (*(volatile unsigned int*)0xE0001000) // DWT Control Register #define FFCR (*(volatile unsigned int*)0xE0040304) // Formatter and flush // Control Register U32 _ITMPort = 0; // The stimulus port from which SWO data is received // and displayed. U32 TargetDiv = 1; // Has to be calculated according to // the CPU speed and the output baud rate static void _EnableSWO() { U32 StimulusRegs; // // Enable access to SWO registers // DEMCR |= (1 << 24); ITM_LSR = 0xC5ACCE55; // // Initially disable ITM and stimulus port // To make sure that nothing is transferred via SWO // when changing the SWO prescaler etc. // StimulusRegs = ITM_ENA; StimulusRegs &= ~(1 << _ITMPort); ITM_ENA = StimulusRegs; // Disable ITM stimulus port ITM_TCR = 0; // Disable ITM // // Initialize SWO (prescaler, etc.) // TPIU_SPPR = 0x00000002; // Select NRZ mode TPIU_ACPR = TargetDiv - 1; // Example: 72/48 = 1,5 MHz ITM_TPR = 0x00000000; DWT_CTRL = 0x400003FE; FFCR = 0x00000100; // // Enable ITM and stimulus port // ITM_TCR = 0x1000D; // Enable ITM ITM_ENA = StimulusRegs | (1 << _ITMPort); // Enable ITM stimulus port J-Link / J-Trace (UM08001) © 2004-2017 SEGGER Microcontroller GmbH & Co. KG 107 CHAPTER 3 J-Link SWO Viewer } 3.8.4 Target example code for terminal output /********************************************************************* * SEGGER MICROCONTROLLER GmbH & Co KG * * Solutions for real time microcontroller applications * ********************************************************************** * * * (c) 2012-2017 SEGGER Microcontroller GmbH & Co KG * * * * www.segger.com Support: support@segger.com * * * ********************************************************************** ---------------------------------------------------------------------File : SWO.c Purpose : Simple implementation for output via SWO for Cortex-M processors. It can be used with any IDE. This sample implementation ensures that output via SWO is enabled in order to guarantee that the application does not hang. -------- END-OF-HEADER --------------------------------------------*/ /********************************************************************* * * Prototypes (to be placed in a header file such as SWO.h) */ void SWO_PrintChar (char c); void SWO_PrintString(const char *s); /********************************************************************* * * Defines for Cortex-M debug unit */ #define ITM_STIM_U32 (*(volatile unsigned int*)0xE0000000) // STIM word access #define ITM_STIM_U8 (*(volatile char*)0xE0000000) // STIM Byte access #define ITM_ENA (*(volatile unsigned int*)0xE0000E00) // ITM Enable Register #define ITM_TCR (*(volatile unsigned int*)0xE0000E80) // ITM Trace Control // Register /********************************************************************* * * SWO_PrintChar() * * Function description * Checks if SWO is set up. If it is not, return, * to avoid program hangs if no debugger is connected. * If it is set up, print a character to the ITM_STIM register * in order to provide data for SWO. * Parameters * c: The character to be printed. * Notes * Additional checks for device specific registers can be added. */ void SWO_PrintChar(char c) { // // Check if ITM_TCR.ITMENA is set // if ((ITM_TCR & 1) == 0) { return; } // // Check if stimulus port is enabled // J-Link / J-Trace (UM08001) © 2004-2017 SEGGER Microcontroller GmbH & Co. KG 108 CHAPTER 3 J-Link SWO Viewer if ((ITM_ENA & 1) == 0) { return; } // // Wait until STIMx is ready, // then send data // while ((ITM_STIM_U8 & 1) == 0); ITM_STIM_U8 = c; } /********************************************************************* * * SWO_PrintString() * * Function description * Print a string via SWO. * */ void SWO_PrintString(const char *s) { // // Print out character per character // while (*s) { SWO_PrintChar(*s++); } } J-Link / J-Trace (UM08001) © 2004-2017 SEGGER Microcontroller GmbH & Co. KG 109 3.9 CHAPTER 3 SWO Analyzer SWO Analyzer SWO Analyzer (SWOAnalyzer.exe) is a tool that analyzes SWO output. Status and summary of the analysis are output to standard out, the details of the analysis are stored in a file. Usage SWOAnalyzer.exe This can be achieved by simply dragging the SWO output file created by the J-Link DLL onto the executable. Creating an SWO output file In order to create the SWO output file, which is the input file for the SWO Analyzer, the JLink config file needs to be modified. It should contain the following lines: [SWO] SWOLogFile="C:\TestSWO.dat" J-Link / J-Trace (UM08001) © 2004-2017 SEGGER Microcontroller GmbH & Co. KG 110 CHAPTER 3 3.10 JTAGLoad (Command line tool) JTAGLoad (Command line tool) JTAGLoad is a tool that can be used to open and execute an svf (Serial vector format) file for JTAG boundary scan tests. The data in the file will be sent to the target via J-Link / J-Trace. SVF is a standard format for boundary scan vectors to be used with different tools and targets. SVF files contain human-readable ASCII SVF statements consisting of an SVF command, the data to be sent, the expected response, a mask for the response or additional information. JTAGLoad supports following SVF commands: • • • • • • • • • • • • • ENDDR ENDIR FREQUENCY HDR HIR PIOMAP PIO RUNTEST SDR SIR STATE TDR TIR A simple SVF file to read the JTAG ID of the target can look like following: ! Set JTAG frequency FREQUENCY 12000000HZ; ! Configure scan chain ! For a single device in chain, header and trailer data on DR and IR are 0 ! Set TAP to IDLE state STATE IDLE; ! Configure end state of DR and IR after scan operations ENDDR IDLE; ENDIR IDLE; ! Start of test ! 32 bit scan on DR, In: 32 0 bits, Expected out: Device ID (0x0BA00477) SDR 32 TDI (0) TDO (0BA00477) MASK (0FFFFFFF); ! Set TAP to IDLE state STATE IDLE; ! End of test SVD files allow even more complex tasks, basically everything which is possible via JTAG and the devices in the scan chain, like configuring an FPGA or loading data into memory. J-Link / J-Trace (UM08001) © 2004-2017 SEGGER Microcontroller GmbH & Co. KG 111 CHAPTER 3 3.11 J-Link RDI (Remote Debug Interface) J-Link RDI (Remote Debug Interface) The J-Link RDI software is a remote debug interface for J-Link. It makes it possible to use J-Link with any RDI compliant debugger. The main part of the software is an RDI-compliant DLL, which needs to be selected in the debugger. here are two additional features available which build on the RDI software foundation. Each additional feature requires an RDI license in addition to its own license. Evaluation licenses are available free of charge. For further information go to our website or contact us directly. Note The RDI software (as well as flash breakpoints and flash downloads) do not require a license if the target device is an LPC2xxx. In this case the software verifies that the target device is actually an LPC 2xxx and have a device-based license. 3.11.1 Flash download and flash breakpoints Flash download and flash breakpoints are supported by J-Link RDI. For more information about flash download and flash breakpoints, please refer to J-Link RDI User’s Guide (UM08004) , chapter Flash download and chapter Breakpoints in flash memory . J-Link / J-Trace (UM08001) © 2004-2017 SEGGER Microcontroller GmbH & Co. KG 112 CHAPTER 3 3.12 Processor specific tools Processor specific tools The J-Link Software and Documentation Package includes some tools which support processor specific functionalities, like unlocking a device. 3.12.1 J-Link STR91x Commander (Command line tool) J-Link STR91x Commander (JLinkSTR91x.exe) is a tool that can be used to configure STR91x cores. It permits some STR9 specific commands like: • • • • • Set the configuration register to boot from bank 0 or 1. Erase flash sectors. Read and write the OTP sector of the flash. Write-protect single flash sectors by setting the sector protection bits. Prevent flash from communicate via JTAG by setting the security bit. All of the actions performed by the commands, excluding writing the OTP sector and erasing the flash, can be undone. This tool can be used to erase the flash of the controller even if a program is in flash which causes the CPU core to stall. When starting the STR91x commander, a command sequence will be performed which brings MCU into Turbo Mode. “While enabling the Turbo Mode, a dedicated test mode signal is set and controls the GPIOs in output. The IOs are maintained in this state until a next JTAG instruction is sent.” (ST Microelectronics) Enabling Turbo Mode is necessary to guarantee proper function of all commands in the STR91x Commander. J-Link / J-Trace (UM08001) © 2004-2017 SEGGER Microcontroller GmbH & Co. KG 113 CHAPTER 3 Processor specific tools Commands Command Description fsize Set the size of the primary flash manually. Syntax: fsize 0|1|2|3, where 0 selects a 256 Kbytes device, 1 a 512 Kbytes device, 2 a 1024 KBytes device and 3 a 2048 Kbytes device showconf Show configuration register content and security status mem Read memory Syntax: mem , erase Erase flash sectors (OTP can not be erased). Syntax: erase , SectorMaskL = Bits 0-%d mask sectors 0-%d of bank 0 SectorMaskH = Bits 0-%d mask sectors 0-%d of bank 1 Bit 17 masks the configuration sector Bit 18 masks the User-Code sector All other bits are ignored erase bank0 Erase flash bank 0 erase bank1 Erase flash bank 1 erase all Perform a full chip erase setb Boot from flash bank x (0 and 1 are available) Syntax: setb setLVDth Set the LVD threshold to 2.7 V. clrLVDth Set the LVD threshold to 2.4 V. setLVDreset LVD Reset Out is generated by VDD or VDDQ inputs. clrLVDreset LVD Reset Out is generated by VDD input only. setLVDwarn LVD warning is generated by VDD or VDDQ inputs. clrLVDwarn LVD warning is generated by VDD input only. blank Blank check all flash sectors secure Set the security bit. Protects device from read or debug access through the JTAG port (can only be cleared by a full chip erase). unsecure Unsecure the device. Content of configuration register is saved. protect Protect flash sectors. Syntax: protect , Bank0SectorMask: Bits 0-%d mask flash sectors 0-%d of bank 0 Bank1SectorMask: Bits 0-%d mask flash sectors 0-%d of bank 1 unprotect Unprotect flash sectors. Syntax: unprotect , Bank0SectorMask: Bits 0-%d mask flash sectors 0-%d of bank 0 Bank1SectorMask: Bits 0-%d mask flash sectors 0-%d of bank 1 readotp Read OTP sectors writeotp Write words to the OTP sectors. Syntax: writeotp , [ , …, ] q Quit Command line options J-Link STR91x Commander can be started with different command line options for test and automation purposes. In the following, the command line options which are available for J-Link Commander are explained. All command line options are case insensitive. J-Link / J-Trace (UM08001) © 2004-2017 SEGGER Microcontroller GmbH & Co. KG 114 CHAPTER 3 Command Processor specific tools Explanation -CommanderScript Passes a CommandFile to J-Link -CommandFile Passes a CommandFile to J-Link -IP Selects IP as host interface -SelectEmuBySN Connects to a J-Link with a specific S/N over USB -IRPre Scan-Chain Configuration -IRPost Scan-Chain Configuration -DRPre Scan-Chain Configuration -DRPost Scan-Chain Configuration 3.12.1.1 -CommanderScript Similar to -CommandFile . 3.12.1.2 -CommandFile Selects a command file and starts J-Link STR91x Commander in batch mode. The batch mode of J-Link STR91x Commander is similar to the execution of a batch file. The command file is parsed line by line and one command is executed at a time. Syntax -CommandFile Example See Using command files . 3.12.1.3 tion ) -DRPre, -DRPost, -IRPre and -IRPost (Scan-Chain Configura- STR91x allows to configure a specific scan-chain via command-line. To use this feature four command line options have to be specified in order to allow a proper connection to the proper device. In case of passing an incomplete configuration, the utility tries to auto-detect. Syntax -DRPre -DRPost -IRPre -IRPost Example JLinkSTR91x.exe -DRPre 1 -DRPost 4 -IRPre 16 -IRPost 20 3.12.1.4 -IP Selects IP as host interface to connect to J-Link. Default host interface is USB. Syntax -IP Example JLinkSTR91x.exe -IP 192.168.1.17 Additional information To select from a list of all available emulators on Ethernet, please use * as . J-Link / J-Trace (UM08001) © 2004-2017 SEGGER Microcontroller GmbH & Co. KG 115 CHAPTER 3 3.12.1.5 Processor specific tools -SelectEmuBySN Connect to a J-Link with a specific serial number via USB. Useful if multiple J-Links are connected to the same PC and multiple instances of J-Link Commander shall run and each connects to another J-Link. Syntax -SelectEmuBySN Example JLinkSTR91x.exe -SelectEmuBySN 580011111 3.12.2 J-Link STM32 Unlock (Command line tool) J-Link STM32 Unlock (JLinkSTM32.exe) is a free command line tool which can be used to disable the hardware watchdog of STM32 devices which can be activated by programming the option bytes. Moreover the J-Link STM32 Commander unsecures a read-protected STM32 device by re-programming the option bytes. Note Unprotecting a secured device or will cause a mass erase of the flash memory. Command Line Options Command line option Explanation -IP Selects IP as host interface to connect to J-Link. Default host interface is USB. -SelectEmuBySN Connects to a J-Link with a specific S/N over USB -Speed Starts the J-Link STM32 Unlock Utility with a given initial interface speed. -SetPowerTarget Enables target power supply via pin 19. -SetDeviceFamily Specifies a device family J-Link / J-Trace (UM08001) © 2004-2017 SEGGER Microcontroller GmbH & Co. KG 116 CHAPTER 3 Command line option -Exit 3.12.2.1 Processor specific tools Explanation J-Link STM32 Unlock will close automatically -IP Selects IP as host interface to connect to J-Link. Default host interface is USB. Syntax -IP Example JLinkSTM32.exe -IP 192.168.1.17 Note To select from a list of all available emulators on Ethernet, please use * as