Segger J-Link User manual

A product of SEGGER Microcontroller GmbH & Co. KG
J-Link
Document RM08001-R2
Date: June 30, 2008
Reference manual for
J-Link USB Protocol
www.segger.com

2 CHAPTER
RM08001 Reference manual for J-Link USB Protocol © 2008 SEGGER Microcontroller GmbH & Co. KG
Disclaimer
Specifications written in this document are believed to be accurate, but are not guar-
anteed 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 (the manufacturer) assumes
no responsibility for any errors or omissions. The manufacturer makes and you
receive no warranties or conditions, express, implied, statutory or in any communica-
tion with you. The manufacturer specifically disclaims any implied warranty of mer-
chantability 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 the manufacturer. The software described in this doc-
ument is furnished under a license and may only be used or copied in accordance
with the terms of such a license.
©2008 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 respec-
tive holders.
Contact address
SEGGER Microcontroller GmbH & Co. KG
In den Weiden 11
D-40721 Hilden
Germany
Tel.+49 2103-2878-0
Fax.+49 2103-2878-28
Email: support@segger.com
Internet: http://www.segger.com
Document revisions
For further information on topics or routines not yet specified, please contact us.
Revision Date By Explanation
0 080523 OO Initial version
1 080526 OO
Chapter "Background information": Added JTAG
buffer description.
Some minor changes.
2 080527 OO Some minor changes.

RM08001 Reference manual for J-Link USB Protocol © 2008 SEGGER Microcontroller GmbH & Co. KG
3
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 com-
piler)
• The target processor.
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 program-
ming 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.
Reference Reference to chapters, sections, tables and figures or other docu-
ments.
GUIElement Buttons, dialog boxes, menu names, menu commands.
Emphasis Very important sections
Table 1.1: Typographic conventions

4
RM08001 Reference manual for J-Link USB Protocol © 2008 SEGGER Microcontroller GmbH & Co. KG

RM08001 Reference manual for J-Link USB Protocol © 2008 SEGGER Microcontroller GmbH & Co. KG
5
1 Introduction......................................................................................................................7
1.1 How to use this manual ..............................................................................8
1.2 Purpose of this document ...........................................................................8
1.3 Features of J-Link ARM ...............................................................................8
2 Licensing..........................................................................................................................9
2.1 License terms..........................................................................................10
3 Background information.................................................................................................11
3.1 JTAG scan chain values ............................................................................12
3.2 Emulator configuration .............................................................................14
3.3 JTAG data buffers ....................................................................................15
4 USB communication ......................................................................................................17
4.1 Communication protocol overview.............................................................. 18
4.2 Protocol commands..................................................................................19
4.3 Get system information functions...............................................................21
4.4 Get state information functions..................................................................27
4.5 JTAG & Hardware functions .......................................................................31
4.6 Target functions ......................................................................................45
4.7 Configuration functions............................................................................. 54
5 Glossary.........................................................................................................................57
6 Literature and references...............................................................................................61
Table of Contents

6
RM08001 Reference manual for J-Link USB Protocol © 2008 SEGGER Microcontroller GmbH & Co. KG

RM08001 Reference manual for J-Link USB Protocol © 2008 SEGGER Microcontroller GmbH & Co. KG
7
Chapter 1
Introduction
This chapter describes the purpose of this manual and the J-Link ARM emulator which
uses the J-Link USB Protocol.

8 CHAPTER 1 Introduction
RM08001 Reference manual for J-Link USB Protocol © 2008 SEGGER Microcontroller GmbH & Co. KG
1.1 How to use this manual
This manual describes the J-Link USB Protocol used in J-Link products and how it is
used.
In the course of this document the J-Link ARM is refered to as emulator.
1.2 Purpose of this document
The purpose of this document is to allow developers of open source software such as
OpenOCD to write software which uses J-Link as debug interface.
This document gives an overview about the J-Link USB communication and how it
can be used in your application. Sample communications to almost each command
description should give you an idea of the data transferred via USB between J-Link
and host.
1.3 Features of J-Link ARM
J-Link provides a feature rich list of functions to simplify the
debugging process. All important functions which are used by
the SEGGER software are useable via the USB protocol.
J-Link ARM has many features:
•USB 2.0 interface
•Any ARM7/ARM9 core supported, including thumb mode
•Automatic core recognition
•Maximum JTAG speed 12 MHz
•Download speed up to 720 Kbytes/second *
•DCC speed up to 800 Kbytes/second *
•No power supply required, powered through USB
•Auto speed recognition
•Support for adaptive clocking
•All JTAG signals can be monitored, target voltage can be mea-
sured
•Support for multiple devices
•Fully plug and play compatible
•A Standard 20-pin JTAG connector
•Optional 14-pin JTAG adapter available
•Wide target voltage range: 1.2V - 3.3V
•Optional adapter for 5V targets available
* = Measured with J-Link Rev.5, ARM7 @ 50 MHz, 12MHz JTAG speed.

RM08001 Reference manual for J-Link USB Protocol © 2008 SEGGER Microcontroller GmbH & Co. KG
9
Chapter 2
Licensing
This chapter gives information about the licensing terms under which this document
is published.

10 CHAPTER 2 Licensing
RM08001 Reference manual for J-Link USB Protocol © 2008 SEGGER Microcontroller GmbH & Co. KG
2.1 License terms
The information in this document may only be used when fully agreeing to the terms
mentioned in this chapter.
Please note that the SEGGER J-Link software is copyrighted and may be used with
original SEGGER J-Links and legal OEM versions only. For details, please refer to the
License terms in License.txt which comes with the J-Link software and documenta-
tion pack.
In case of doubt, please contact us: info@segger.com .
2.1.1 What you may do
You may use the information contained in this document to add support for the wide
spread SEGGER J-Link ARM emulator and OEM versions in open source software.
2.1.2 What you are not allowed to do
You are not allowed to use the information in this document to
• build J-Link clones
• build J-Link compatible emulators.

RM08001 Reference manual for J-Link USB Protocol © 2008 SEGGER Microcontroller GmbH & Co. KG
11
Chapter 1
Background information
This chapter provides information required to understand parameters for certain USB
commands when working with the J-Link emulator.

12 CHAPTER 1 Background information
RM08001 Reference manual for J-Link USB Protocol © 2008 SEGGER Microcontroller GmbH & Co. KG
1.1 JTAG scan chain values
Some JTAG-related commands need an IRpre and DevicePos parameter. These values
describe the position of a device in the scan chain and the shift count to reach that
device.
The diagram below shows a scan chain configuration sample with 2 devices con-
nected to the JTAG port.
1.1.1 IRPre
The IRPre value is the total number of bits in the instruction registers of the devices
before the DUT counted from nearest device to TDO. The position can usually be seen
in the schematic; the IR len can be found in the manual supplied by the manufactur-
ers of the other devices.
ARM7 and ARM9 have an IR len of four.
For systems with just a single device, IRPre is 0.
For an example using the IRpre value please refer to the paragraph Scan chain exam-
ple on page 13.
1.1.2 DevicePos
The DevicePos value of the DUT is the amount of devices in the scan chain before the
DUT, counted from nearest device to TDO.
For systems with just a single device, DevicePos is 0.
For an example using the DevicePos value please refer to the paragraph Scan chain
example on page 13.
Device 1 Device 0
TDI TDITDO TDO
TDI TDO
JTAG
TRST
TCK
TMS
TCK
TMS
TRST
TCK
TMS
TRST

RM08001 Reference manual for J-Link USB Protocol © 2008 SEGGER Microcontroller GmbH & Co. KG
13
1.1.3 Scan chain example
The following table shows a few sample configurations with 1,2 and 3 devices in dif-
ferent configurations. The DUT is marked in blue.
Device 0
(IR len)
Device 1
(IR len)
Device 2
(IR len) DevicePos IR len
(IRpre)
ARM(4) --00
ARM(4) Xilinx(8) - 0 0
Xilinx(8) ARM(4) -18
Xilinx(8) Xilinx(8) ARM(4) 216
ARM(4) Xilinx(8) ARM(4) 0 0
ARM(4) Xilinx(8) ARM(4) 212
Xilinx(8) ARM(4) Xilinx(8) 1 8
Table 1.1: Example scan chain

14 CHAPTER 1 Background information
RM08001 Reference manual for J-Link USB Protocol © 2008 SEGGER Microcontroller GmbH & Co. KG
1.2 Emulator configuration
Emulator configuration is a 256 byte non-volatile memory area which can be read
and written via USB. It holds the emulator configuration that was setup for your J-
Link. The following table shows the current configuration offsets and their meanings.
Offset Values Explanation
0x00 0x00 - 0x03 : USB-Address 0-3
0xFF : Default
USB-Address of the emulator.
Allows usage of more than one
J-Link at the same time.
0x01 - 0x03 0xFF Reserved
0x04 - 0x07
0xFFFFFFFF : Default, on if J-Link KS
0x00000000 : Off
0x00000001 : On
Kickstart power on JTAG-pin 19.
0x08 - 0x1F 0xFF Reserved
0x20 - 0x23 IP-Address in hex format.
0xFFFFFFFF if not configured. IP-Address (only for J-Link Pro).
0x24 - 0x27 Subnet mask in hex format.
0xFFFFFFFF if not configured.
Subnetmask (only for J-Link
Pro).
0x28 - 0x2F 0xFF Reserved
0x30 - 0x35 MAC-Address
0xFFFFFFFFFFFF if not configured.
MAC-Address (only for J-Link
Pro).
0x36 - 0xFF 0xFF Reserved
Table 1.2: Emulator configuration overview

RM08001 Reference manual for J-Link USB Protocol © 2008 SEGGER Microcontroller GmbH & Co. KG
15
1.3 JTAG data buffers
The J-Link has three JTAG data buffers. Two of these are output buffers used for TMS
and TDI, the third is an input buffer for TDO data. To work with the J-Link, an under-
standing of the buffers and the way the data is stored in them is quite useful.
1.3.1 Explanation of terms
In this document input and output buffers are seen from host perspective.
Input buffer
The input buffer stores the incoming TDO signals from the device.
Output buffer
Output buffers stores TMS and TDI signals which are transferred to the device.
1.3.2 Organization of buffers
Model of JTAG Buffer:
All three JTAG data buffers are organized the same way:
Bit n of the bit stream is stored in byte n/8, bit n%8. This means the first byte is sent
first, least significant bit (lsb) first.
The same thing is true for data received: The first bit received is the lsb of byte 0.
Size of buffers
All buffers are big enough to hold 2 KByte of data.
........................
b48..................b55
b40..................b47
b32..................b39
b24..................b31
b16..................b23
b8..................b15
b0..................b7
byte6
...
byte5
byte4
byte3
byte2
byte1
byte0

16 CHAPTER 1 Background information
RM08001 Reference manual for J-Link USB Protocol © 2008 SEGGER Microcontroller GmbH & Co. KG

RM08001 Reference manual for J-Link USB Protocol © 2008 SEGGER Microcontroller GmbH & Co. KG
17
Chapter 2
USB communication
This chapter explains the USB communication protocol used by the J-Link software to
communicate between host and emulator and how to use it.

18 CHAPTER 2 USB communication
RM08001 Reference manual for J-Link USB Protocol © 2008 SEGGER Microcontroller GmbH & Co. KG
2.1 Communication protocol overview
The J-Link firmware uses several commands to communicate with the host software.
The communication is always initiated by the host. The host sends an U8 command to
the emulator followed by parameters beeing known to be needed by this command.
The firmware retrieves the first byte from the buffer, containing the command and
executes the proper functions. The parameters expected are read from the communi-
cation buffer by the subroutines that are called through the command. Return values
are sent back via USB.
2.1.1 USB endpoints
J-Link uses 2 bulk endpoints, one for "IN" and one for "OUT" communication.
Depending on the operating system being used, there are different ways to com-
muincate with J-Link via USB. One way (under a Windows operating system) is to use
the J-Link USB driver. One other option is to use "USBLib", which is a freeware pack-
age available under different operating systems.
2.1.2 USB transactions
If multiple bytes are send to the emulator or send by the emulator, there is a choice:
The information can be send in a single transaction or in multiple transactions. So
both sides are free to send data in one or more transactions. However, due to the
long USB latencies, it is recommended to use as few transactions as possible.
2.1.3 USB latency
The two most important limiting factors in communication between the host and the
emulator are:
• USB Transmission speed
•USBlatency
The transmission speed is fixed to 12MHz and allows transmission of up to app.
1MByte/sec. This is sufficient for fast operation of the emulator.
The USB latency is more of a problem. Since the host schedules USB transactions in
frames of 1ms for full speed and 125us for high speed connections, the average
latency is 2ms for full speed and 250us for high speed connections. This means that
even a small transaction of 1byte typically takes 2ms on full speed connection and it
also means that minimizing the number of transactions to the minimum required is
desirable.
2.1.4 Endianess
All data units larger than a single byte are transferred little endian, meaning least
significant bytes are transferred first.
U16 Example
U16 data to send:
0xCDEF
Data sent via USB:
EF CD
U32 Example
U32 data to send:
0x12345678
Data sent via USB:
78 56 34 12

RM08001 Reference manual for J-Link USB Protocol © 2008 SEGGER Microcontroller GmbH & Co. KG
19
2.2 Protocol commands
The list below gives an overview about the usable commands:
Define Value Explanation
Get system information functions
EMU_CMD_VERSION 0x01 Retrieves the firmware version.
EMU_CMD_GET_SPEEDS 0xC0 Retrieves the base freq. and the min.
divider of the emulator CPU.
EMU_CMD_GET_MAX_MEM_BLOCK 0xD4 Retrieves the maximum memory block-
size.
EMU_CMD_GET_CAPS 0xE8 Retrieves capabilities of the emulator.
EMU_CMD_GET_HW_VERSION 0xF0 Retrieves the hardware version of the
emulator.
Get state information functions
EMU_CMD_GET_STATE 0x07 Retrieves voltage and JTAG pin states.
EMU_CMD_GET_HW_INFO 0xC1 Retrieves hardware information.
EMU_CMD_GET_COUNTERS 0xC2 Retrieves target connection counters.
EMU_CMD_MEASURE_RTCK_REACT 0xF6 Measures RTCK reaction time.
JTAG & Hardware functions
EMU_CMD_RESET_TRST 0x02 Resets TRST.
EMU_CMD_SET_SPEED 0x05 Sets the JTAG speed.
EMU_CMD_SET_KS_POWER 0x08 Sets KS power to on or off.
EMU_CMD_HW_CLOCK 0xC8 Generates one clock and retrieves TDI.
EMU_CMD_HW_TMS0 0xC9 Clears TMS.
EMU_CMD_HW_TMS1 0xCA Sets TMS.
EMU_CMD_HW_DATA0 0xCB Clears TDI.
EMU_CMD_HW_DATA1 0xCC Sets TDI.
EMU_CMD_HW_JTAG 0xCD Handles JTAG connection.
EMU_CMD_HW_JTAG2 0xCE Handles JTAG connection with word
aligned data transfers.
EMU_CMD_HW_JTAG3 0xCF
Handles JTAG connection with word
aligned data transfers and return
value.
EMU_CMD_HW_TRST0 0xDE Activates TRST.
EMU_CMD_HW_TRST1 0xDF Deactivates TRST.
EMU_CMD_WRITE_DCC 0xF1 Writes to JTAG using DCC.
Target functions
EMU_CMD_RESET_TARGET 0x03 Resets the target.
EMU_CMD_HW_RELEASE_RESET_ST
OP_EX 0xD0 Resets the CPU and halts as soon as its
possible or the timeout expires.
EMU_CMD_HW_RELEASE_RESET_ST
OP_TIMED 0XD1 Resets the CPU and halts as soon as its
possible or the timeout expires.
EMU_CMD_HW_RESET0 0xDC Activates target reset.
EMU_CMD_HW_RESET1 0xDD Deactivates target reset.
EMU_CMD_GET_CPU_CAPS 0xE9 Retrieves capabilities of the CPU.
EMU_CMD_EXEC_CPU_CMD 0xEA Executes a CPU command.
EMU_CMD_WRITE_MEM 0xF4 Writes to target memory.
EMU_CMD_READ_MEM 0xF5 Reads from target memory.
EMU_CMD_WRITE_MEM_ARM79 0xF7 Writes to target memory on ARM 7/9
targets.
EMU_CMD_READ_MEM_ARM79 0xF8 Reads from target memory on ARM 7/9
targets.
Table 2.1: Protocol command overview

20 CHAPTER 2 USB communication
RM08001 Reference manual for J-Link USB Protocol © 2008 SEGGER Microcontroller GmbH & Co. KG
Configuration functions
EMU_CMD_READ_CONFIG 0xF2 Reads the emulator configuration.
EMU_CMD_WRITE_CONFIG 0xF3 Writes the emulator configuration.
Define Value Explanation
Table 2.1: Protocol command overview
Other manuals for J-Link
8
Table of contents
Other Segger Motherboard manuals