TRACE32 JTAG Bridge for Android

TRACE32 Online Help

TRACE32 Directory
TRACE32 Index
TRACE32 Documents ......................................................................................................................

VM Debugging ...............................................................................................................................

Application Note for Android ....................................................................................................

TRACE32 JTAG Bridge for Android ......................................................................................

Intended Audience ...............................................................................................................

Concept .................................................................................................................................

Prerequisites .........................................................................................................................

Patch and Build adb and adbd ............................................................................................

Configure adbd (Android Target) ........................................................................................

Static adbd Configuration (root file system)

Dynamic adbd Configuration (Terminal or adb shell)

Running adbd in JTAG Bridge Mode on SMP Targets

Configure adb (Development Host) ....................................................................................

Linux

Windows

Configure TRACE32 .............................................................................................................

Configure Eclipse .................................................................................................................

Sample Debugging Sequence (HOST) ...............................................................................

Linux

Windows

10

Troubleshooting Tips ...........................................................................................................

Eclipse Warning

11
11

Logging adbd messages

11

Logging adb[.exe] messages

11

Pipe Communication Debugging

11

See DCC output from TRACE32 with od

11

Test Loop

12

Send Input to TRACE32/DCC

12

Patch breaks USB Debugging [host]

12

Patch breaks USB Debugging [target]

13

Android Application Install Fails

13

1989-2016 Lauterbach GmbH

TRACE32 JTAG Bridge for Android

Backlog .................................................................................................................................

14

Timeline .................................................................................................................................

14

1989-2016 Lauterbach GmbH

TRACE32 JTAG Bridge for Android

TRACE32 JTAG Bridge for Android

Version 24-May-2016

Intended Audience
This document is intended for Android System Developers who routinely do full Android system builds for
ARM platforms, who use TRACE32 for native Android debugging via JTAG, and now also want to debug
VM Applications using JTAG as data transport medium.
The TRACE32 JTAG bridge can also be used by Dalvik VM Application developers, once it is configured and
set up. But setup and configuration itself require expert knowledge about how to manage Android
repositories and how to build Android components.

Concept
The TRACE32 JTAG Bridge works by adding JTAG as an additional transport stream to the
Android Debug Bridge (adbd) and to the ADB host service (adb):

for the target, we extend adbd to use ARM/DCC for data transfer,

for the host, we extend adb to use named pipes to and from the TRACE32 FDX system.

Prerequisites
This document assumes

you already have a fully configured (up-and-running) TRACE32 Linux Awareness for your
Android installation

you have an Android repository and are able to build a full Android installation including SDK and
target root filesystem on Linux a development system

you can build the Android SDK for Windows (win_sdk) on your Linux development system
(only required if you have developers debugging on Windows host machines)

you download and install the required patches from http://www.lauterbach.com/vmandroid.html

1989-2016 Lauterbach GmbH

TRACE32 JTAG Bridge for Android

Intended Audience

Patch and Build adb and adbd

As an example, here is the sequence for Android 2.2 (FroYo):

in your Android repository, check out android-2.2.1_r1

(or the equivalent, at least for the git project system/core)

apply the provided JTAG Bridge patch to the system/core git repository
(the set of files starting with 0001/0002/... makes one patch)

build adbd (for your target) and adb (for your SDK host setup)

copy the updated adbd into your target root filesystem as /sbin/adbd

copy the updated adb into the..../platform-tools directory of your Android SDK (ADT)

Configure adbd (Android Target)

An unpatched adb daemon (adbd) can use USB or Ethernet to communicate with the adb host service
(adb). For the exact sequence, please see system/core/adb/adb.c.

Static adbd Configuration (root file system)

If you want to permanently set the adbd communication channel to JTAG, in your default.prop file on
the target root file system add a line of the form
service.adb.jtag=<ARM architecture version>

with <ARM architecture version> = { 9 | 10 | 11 }. A value of zero will disable JTAG connect attempts.
Example default.prop file for the ARM11 architecture of e.g., MEP-6410 (S3C6410):
#
# ADDITIONAL_DEFAULT_PROPERTIES
#
ro.secure=0
ro.allow.mock.location=1
ro.debuggable=1
persist.service.adb.enable=1
service.adb.jtag=11
#persist.adb.trace_mask=ffff
#

Note:

For Cortex platforms (e.g., Cortex-A9), use service.adb.jtag=11

1989-2016 Lauterbach GmbH

TRACE32 JTAG Bridge for Android

Patch and Build adb and adbd

Dynamic adbd Configuration (Terminal or adb shell)

If you have the patched adbd version installed on the target, but want to switch to JTAG bridge mode during
a debug session, you can set the service.adb.jtag property in a terminal window or in an adb shell:
# getprop service.adb.jtag
# setprop service.adb.jtag 11
# getprop service.adb.jtag
11
# ps adbd
USER
PID
PPID VSIZE RSS
root
1294 1
3464
208
#
# kill 1294
disabling adb
# adb_release
enabling adb
# ps adbd
USER
PID
PPID
root
11540 1
#

Note:

VSIZE
3456

WCHAN
PC
NAME
ffffffff 00013c24 S /sbin/adbd

RSS
200

WCHAN
PC
NAME
ffffffff 00013c24 S /sbin/adbd

After any property change, adbd must be restarted.

1989-2016 Lauterbach GmbH

TRACE32 JTAG Bridge for Android

Configure adbd (Android Target)

Running adbd in JTAG Bridge Mode on SMP Targets

On SMP systems, for JTAG Bridge Mode, adbd needs to run on the first core. To do this, we modify the Linux
task processor affinity for all adbd tasks before using FDX/DCC via this PRACTICE script:
;PRACTICE script affinity-adbd.cmm
local &magic &name &flag
if (run())
break
print "Changing adbd affinity..."
&flag=1
&magic=task.proc.magic("adbd")
if (&magic==0xffffffff)||(&magic==0)
&flag=0
while &flag==1
(
&name=task.proc.name(&magic)
if "&name"=="adbd"
var.set ((struct task_struct)*&magic).cpus_allowed = 1
&magic=task.proc.list(&magic)
if (&magic==0xffffffff)||(&magic==0)
&flag=0
)
if (!run())
go
enddo

1989-2016 Lauterbach GmbH

TRACE32 JTAG Bridge for Android

Configure adbd (Android Target)

Configure adb (Development Host)

Linux
For Linux, the default names for the named pipes used for communication with TRACE32 are:

/tmp/adb-t32

communication pipe from adb to TRACE32

/tmp/t32-ad

communication pipe from TRACE32 to adb

The Linux adb will try to create the named pipe files if they dont already exist.
They may also be created in advance in a command shell with:
% mkfifo /tmp/adb-t32
% mkfifo /tmp/t32-adb

You can override the default pipe names by setting and exporting the environment variables TRACE32PI
and TRACE32PO before (re-)starting adb.

Windows
For Windows, the default names for the named pipes used for communication with TRACE32 are:

\\.\pipe\adb-t32

communication pipe from adb to TRACE32

\\.\pipe\t32-adb

communication pipe from TRACE32 to adb

The Windows pipe mechanism is different from Linux. The adb host service executable (adb.exe) needs
to create the named pipes and then connects to them as a pipe server.
With the free tool PipeList from Microsoft Windows Sysinternals you can check if the named pipes exist.
As you can see in the patch file, you can also choose your own pipe names by setting the environment
variables TRACE32PI and TRACE32PO.

1989-2016 Lauterbach GmbH

TRACE32 JTAG Bridge for Android

Configure adb (Development Host)

Configure TRACE32
Before starting a PRACTICE script to setup TRACE32 FDX via a named pipe connection, an adb host
service instance needs to be running (otherwise TRACE32 may terminate with a SIGPIPE), because

on Linux, a write pipe needs an active reader to function

on Windows, a pipe server needs to create the named pipes and provide a connector for clients

So please make sure you have the updated adb host service executable running before you configure FDX!
Here is a PRACTICE sample script for Linux to setup FDX for DCC and named pipes (startfdx.cmm):
FDX.RESet
FDX.METHOD DCC4D
FDX.OutChannel
FDX.PipeWRITE /tmp/t32-adb 4
FDX.InChannel
FDX.PipeREAD /tmp/adb-t32 4
ENDDO

For Windows, you have to adapt the pipe names in startfdx.cmm to the Windows naming scheme:
FDX.RESet
FDX.METHOD DCC4D
FDX.OutChannel
FDX.PipeWRITE \\.\pipe\t32-adb 4
FDX.InChannel
FDX.PipeREAD \\.\pipe\adb-t32 4
ENDDO

Note:

Pipe connect order is important, adb first connects to the t32-adb pipe, then
to the adb-t32 pipe.

Configure Eclipse
When using the JTAG Bridge with some target/debugger combinations, the Eclipse JDWP timeout needs to
be increased. You will know you need to do it if the Thread Stack display is empty at a Java breakpoint and if
you cant single-step in the Eclipse Java Debug window.
Change the Eclipse setting in Window > Preferences > Java > Debug > Communication >
Debugger timeout (ms) from the default (3000) to 6000 or higher.

1989-2016 Lauterbach GmbH

TRACE32 JTAG Bridge for Android

Configure TRACE32

Sample Debugging Sequence (HOST)

Linux
1.

Start TRACE32 and then your PRACTICE script to download the Linux kernel into the target.
(For the inital 2011-04-08 version, you needed to create named pipes. From 2011-05-24, if you start
adb with sufficient rights, it will create the named pipes when it wants to open them.)

2.

[SMP TARGET ONLY] Run the script affinity-adb.cmm, to lock adbd to the first core.

3.

Start the patched version of the Android Debug Bridge host services with
user@ws:~$ adb kill-server
user@ws:~$ adb devices

At this time, the list of devices is probably empty. Example output:

user@ws:~$ adb devices
* daemon not running. starting it now *
* daemon started successfully *
List of devices attached
user@ws:~$

4.

Once the adb host service is running, activate TRACE32 FDX via DCC and named pipes. For
this, in TRACE32 we start the script from section Configure TRACE32:
[B::] do startfdx.cmm

5.

List the Android devices known to adb to test the connection. Here is the output with the patched
adbd installed and running on the Android target, adbd connected via FDX and pipes to
TRACE32, and the target in run mode:
user@ws:~$ adb devices
List of devices attached
jtag-trace32-fdx-1
device
user@ws:~$

6.

Now start DDMS or debug your Dalvik VM Application via the TRACE32 JTAG Bridge in Eclipse.

1989-2016 Lauterbach GmbH

TRACE32 JTAG Bridge for Android

Sample Debugging Sequence (HOST)

Windows
1.

Start TRACE32 and then your PRACTICE script to download the Linux kernel into the target.

2.

[SMP TARGET ONLY] Run the script affinity-adb.cmm, to lock adbd to the first core.

3.

Start the patched version of the Android Debug Bridge host services with
E:\sdk\platform-tools> adb kill-server
E:\sdk\platform-tools> adb devices

At this time, the list of devices is probably empty. Example output:

E:\sdk\platform-tools> adb devices
* daemon not running. starting it now *
* daemon started successfully *
List of devices attached
E:\sdk\platform-tools>

4.

Once the adb host service is running, activate TRACE32 FDX via DCC and named pipes. For
this we start the script from section Configure TRACE32 in TRACE32:
[B::] do startfdx.cmm

5.

List the Android devices known to adb to test the connection. Here is the output with the patched
adbd installed and running on the Android target, adbd connected via FDX and pipes to
TRACE32, and the target in run mode:
E:\sdk\platform-tools> adb devices
List of devices attached
jtag-trace32-fdx-1
device
E:\sdk\platform-tools>

6.

Now you can e.g. start Eclipse and use DDMS or debug your Dalvik VM Application via the
TRACE32 JTAG Bridge.

1989-2016 Lauterbach GmbH

TRACE32 JTAG Bridge for Android

10

Sample Debugging Sequence (HOST)

Troubleshooting Tips

Eclipse Warning
If the target stops (e.g. on a native breakpoint) during application debugging with Eclipse, after a few
seconds you might get a dialog box with a warning.
Usually Eclipse recovers gracefully if the target is in run mode again when you dismiss this dialog box.

Logging adbd messages

The target daemon adbd can write trace files in the directory /data/adb on the target.
To enable this, add this line in /default.prop (or set the property manually and restart adbd)
persist.adb.trace_mask=ffff

Please see the adb source files for the available mask bit values.

Logging adb[.exe] messages

For Linux and Windows, the adb host service writes a log file (e.g. to /tmp/adb.log) when you set the
environment variable ADB_TRACE. A full log is produced with:
user@ws:~$ export ADB_TRACE=1

Pipe Communication Debugging

See DCC output from TRACE32 with od
For Linux, if you suspect something goes wrong with a named pipe, you can watch target DCC output with
the od tool (with adb not running or using another named pipe):
user@ws:~$ od -t x4 </tmp/t32-adb &

For Windows, you need to create an extra test program for this. Please consult the patch sources for ideas
how and what to do.
1989-2016 Lauterbach GmbH

TRACE32 JTAG Bridge for Android

11

Troubleshooting Tips

Test Loop
For communication testing (also for performance tests), you can replace the standard adb and adbd
communication loops with a simple test thread that just transfers data from/to the DCC registers. (E.g., a
test-adbd could echo test data generated by a test-adb.)

Send Input to TRACE32/DCC

For Linux, you can type characters manually into a named pipe for testing, e.g.:
user@ws:~$ cat >/tmp/adb-t32

You can also use dd to write random data to a pipe, e.g.:

user@ws:~$ dd if=/dev/random of=/tmp/adb-t32 bs=4 count=1000 &

For Windows, you need to create an extra test program for this. Please consult the patch sources for ideas
how and what to do.

Patch breaks USB Debugging [host]

Symptom: After copying the patched adb[.exe] version into the platform-tools directory of the Android SDK,
the target device is not found anymore.
The problem is not the JTAG Bridge patch, but a missing USB Vendor ID. adb[.exe] only USB-connects to
devices from a "known vendor" list. This list is partially built-in, partially it is read from a file with the name
adb_usb.ini (see system/core/adb/usb_vendors.c for more information).
Example for Android 2.2 (froYo) and PandaBoard:
Android 2.2 does not have the Texas Instruments (VID 0x0451), which you need for debugging the
PandaBoard, in the "built-in vendor list" of adb[.exe]. This is how to add the TI to the external list:
On Linux:
user@ws:~$ echo 0x0451 >>$HOME/.android/adb_usb.ini

On Windows (please note the mandatory quotation marks):

E:\> echo 0x0451 >>"%USERPROFILE%\.android\adb_usb.ini"

After adding the 0x0451 Vendor ID, an "adb kill-server", then "adb devices" should show the PandaBoard.
1989-2016 Lauterbach GmbH

TRACE32 JTAG Bridge for Android

12

Troubleshooting Tips

Patch breaks USB Debugging [target]

Symptom: With the original adbd, USB debugging works, but when I copy the patched version to /sbin/adb
on the target, the Andropid SDK does not display my device anymore.
1.

If you are debugging with TRACE32, please make sure the target is running. The target can not
control the USB connection in stop mode.

2.

Make sure you have deactivated JTAG Bridge Mode and then restarted adbd:
# setprop service.adb.jtag 0
# getprop service.adb.jtag
0
# ps adbd
USER
PID
PPID VSIZE RSS
root
11540 1
3456
208

WCHAN
PC
NAME
ffffffff 00013c24 S /sbin/adbd

# kill 11540
disabling adb
adb_release
enabling adb
adb_open
android_usb gadget: high speed config #1: android
# ps adbd
USER
PID
PPID
root
12620 1
#

VSIZE
3456

RSS
200

WCHAN
PC
NAME
ffffffff 00013c24 S /sbin/adbd

Android Application Install Fails

Symptom: You built your own Android root file system, now cant install test applets anymore.
On the target, set /data/app owner:group to system (1000), and set the file permissions to 771:
# chown system:system /data/app
# chmod 771 /data/app
#

1989-2016 Lauterbach GmbH

TRACE32 JTAG Bridge for Android

13

Troubleshooting Tips

Backlog
1.

Move JTAG Bridge hardware dependencies from Android into a Linux Kernel Device.
(Makes JTAG debuggig and profiling easier for many embedded platforms, if allowed into the
central Linux Kernel Repository. A kernel device could also multiplex the run-time JTAG
connection and support FDX Terminal and System Trace at the same time as adbd.)

2.

Profile JTAG bridge connection: current bandwidth is lower than USB or Ethernet. (One likely
reason is the requirement to use the same packet size as DCC for the pipe connection.)

3.

Fix pipe connect order dependency by using individual threads for each pipe connect.

4.

Clarify environment variable names, e.g. PIPE_ADBT32 and PIPE_T32ADB.

Timeline
2011-07-12

Documentation added: Eclipse Java Debug Timeout

2011-06-10

Documentation update for multi-core targets (e.g. PandaBoard)

2011-05-24

Windows host support, change documentation to manual style

2011-04-08

Initial release: ARM/DCC targets, Linux debug hosts

1989-2016 Lauterbach GmbH

TRACE32 JTAG Bridge for Android

14

Backlog