MANUAL
Release 09.2021
TRACE32 JTAG Bridge
for Android
TRACE32 JTAG Bridge for Android | 2
©
1989-2021 Lauterbach GmbH
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 ......................................................................................1
Intended Audience ............................................................................................................... 4
Concept ................................................................................................................................. 4
Prerequisites ......................................................................................................................... 4
Patch and Build adb and adbd ............................................................................................ 5
Configure adbd (Android Target) ........................................................................................ 5
Static adbd Configuration (root file system) 5
Dynamic adbd Configuration (Terminal or ’adb shell’) 6
Running adbd in JTAG Bridge Mode on SMP Targets 7
Configure adb (Development Host) .................................................................................... 8
Linux 8
Windows 8
Configure TRACE32 ............................................................................................................. 9
Configure Eclipse ................................................................................................................. 9
Sample Debugging Sequence (HOST) ............................................................................... 10
Linux 10
Windows 11
Troubleshooting Tips ........................................................................................................... 12
Eclipse Warning 12
Logging adbd messages 12
Logging adb[.exe] messages 12
Pipe Communication Debugging 12
See DCC output from TRACE32 with od 12
Test Loop 13
Send Input to TRACE32/DCC 13
Patch breaks USB Debugging [host] 13
Patch breaks USB Debugging [target] 14
Android Application Install Fails 14
TRACE32 JTAG Bridge for Android | 3
©
1989-2021 Lauterbach GmbH
Backlog ................................................................................................................................. 15
Timeline ................................................................................................................................. 15
TRACE32 JTAG Bridge for Android | 4
©
1989-2021 Lauterbach GmbH
TRACE32 JTAG Bridge for Android
Version 04-Nov-2021
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 file system 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 www.lauterbach.com/vmandroid.html
TRACE32 JTAG Bridge for Android | 5
©
1989-2021 Lauterbach GmbH
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 file system 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
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):
service.adb.jtag=<Arm architecture version>
#
# 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
TRACE32 JTAG Bridge for Android | 6
©
1989-2021 Lauterbach GmbH
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 WCHAN PC NAME
root 1294 1 3464 208 ffffffff 00013c24 S /sbin/adbd
#
# kill 1294
disabling adb
# adb_release
enabling adb
# ps adbd
USER PID PPID VSIZE RSS WCHAN PC NAME
root 11540 1 3456 200 ffffffff 00013c24 S /sbin/adbd
#
Note: After any property change, adbd must be restarted.
TRACE32 JTAG Bridge for Android | 7
©
1989-2021 Lauterbach GmbH
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
TRACE32 JTAG Bridge for Android | 8
©
1989-2021 Lauterbach GmbH
Configure adb (Development Host)
Linux
For Linux, the default names for the named pipes used for communication with TRACE32 are:
The Linux adb will try to create the named pipe files if they don’t already exist.
They may also be created in advance in a command shell with:
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:
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.
/tmp/adb-t32 communication pipe from adb to TRACE32
/tmp/t32-ad communication pipe from TRACE32 to adb
% mkfifo /tmp/adb-t32
% mkfifo /tmp/t32-adb
\\.\pipe\adb-t32 communication pipe from adb to TRACE32
\\.\pipe\t32-adb communication pipe from TRACE32 to adb
TRACE32 JTAG Bridge for Android | 9
©
1989-2021 Lauterbach GmbH
Configure TRACE32
Before starting a PRACTICE script to set up 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 set up FDX for DCC and named pipes (startfdx.cmm):
For Windows, you have to adapt the pipe names in startfdx.cmm to the Windows naming scheme:
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 can’t 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.
FDX.RESet
FDX.METHOD DCC4D
FDX.OutChannel
FDX.PipeWRITE /tmp/t32-adb 4
FDX.InChannel
FDX.PipeREAD /tmp/adb-t32 4
ENDDO
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.
TRACE32 JTAG Bridge for Android | 10
©
1989-2021 Lauterbach GmbH
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
At this time, the list of devices is probably empty. Example output:
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”:
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:
6. Now start DDMS or debug your Dalvik VM Application via the TRACE32 JTAG Bridge in Eclipse.
user@ws:~$ adb kill-server
user@ws:~$ adb devices
user@ws:~$ adb devices
* daemon not running. starting it now *
* daemon started successfully *
List of devices attached
user@ws:~$
[B::] do startfdx.cmm
user@ws:~$ adb devices
List of devices attached
jtag-trace32-fdx-1 device
user@ws:~$
TRACE32 JTAG Bridge for Android | 11
©
1989-2021 Lauterbach GmbH
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
At this time, the list of devices is probably empty. Example output:
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:
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:
6. Now you can e.g. start Eclipse and use DDMS or debug your Dalvik VM Application via the
TRACE32 JTAG Bridge.
E:\sdk\platform-tools> adb kill-server
E:\sdk\platform-tools> adb devices
E:\sdk\platform-tools> adb devices
* daemon not running. starting it now *
* daemon started successfully *
List of devices attached
E:\sdk\platform-tools>
[B::] do startfdx.cmm
E:\sdk\platform-tools> adb devices
List of devices attached
jtag-trace32-fdx-1 device
E:\sdk\platform-tools>
TRACE32 JTAG Bridge for Android | 12
©
1989-2021 Lauterbach GmbH
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)
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:
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):
For Windows, you need to create an extra test program for this. Please consult the patch sources for ideas
how and what to do.
persist.adb.trace_mask=ffff
user@ws:~$ export ADB_TRACE=1
user@ws:~$ od -t x4 </tmp/t32-adb &
TRACE32 JTAG Bridge for Android | 13
©
1989-2021 Lauterbach GmbH
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.:
You can also use dd to write random data to a pipe, e.g.:
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:
On Windows (please note the mandatory quotation marks):
After adding the 0x0451 Vendor ID, an "adb kill-server", then "adb devices" should show the PandaBoard.
user@ws:~$ cat >/tmp/adb-t32
user@ws:~$ dd if=/dev/random of=/tmp/adb-t32 bs=4 count=1000 &
user@ws:~$ echo 0x0451 >>$HOME/.android/adb_usb.ini
E:\> echo 0x0451 >>"%USERPROFILE%\.android\adb_usb.ini"
TRACE32 JTAG Bridge for Android | 14
©
1989-2021 Lauterbach GmbH
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:
Android Application Install Fails
Symptom: You built your own Android root file system, now can’t install test applets anymore.
On the target, set /data/app owner:group to system (1000), and set the file permissions to 771:
# setprop service.adb.jtag 0
# getprop service.adb.jtag
0
# ps adbd
USER PID PPID VSIZE RSS WCHAN PC NAME
root 11540 1 3456 208 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 VSIZE RSS WCHAN PC NAME
root 12620 1 3456 200 ffffffff 00013c24 S /sbin/adbd
#
# chown system:system /data/app
# chmod 771 /data/app
#
TRACE32 JTAG Bridge for Android | 15
©
1989-2021 Lauterbach GmbH
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
