add Trace32 debugger support #1267

userid0x0 · 2023-09-08T06:32:14Z

Hi,
as previously discussed we are working on adding a TRACE32 debugger support into Labgrid. The pull request is not yet finished thus I did not add any signed-off's to the commit.
Nevertheless I want to sum up the status of what the work does:

it supports our Lauterbach uTrace/PowerDebug/PowerTrace devices connected via USB (both via exporter and direct) and Ethernet
for USB devices exported via the exporter a agent t32tcpusb is required to forward the USB traffic to a TCP port
- resource NetworkUSBLauterbachDebug
- this agent needs to somehow match the version of TRACE32 PowerView - for that reason it's uploaded on every activate
the DebuggerProtocol allows to start a debugger session

Future work:

add support for pyrcl to integrate TRACE32 into pytest
add BootstrapProtocol

Questions:

related to t32tcpusb
- any ideas how I can ensure that t32tcpusb is cleaned up on the exporter e.g. implementing a USBLauterbachDebuggerExport._stop()
- how can I detect unused ports on the exporter?
- is there a clean way to add -tt to the command_prefix of a RemoteUSBResource? Without that I cannot terminate a process started on the exporter
related to tests
- is it possible to test a NetworkUSB.. resource?

Checklist

Documentation for the feature
Tests for the feature

The arguments and description in doc/configuration.rst have been updated

Add a section on how to use the feature to doc/usage.rst

Add a section on how to use the feature to doc/development.rst

PR has been tested

Man pages have been regenerated

codecov · 2023-09-08T06:50:35Z

Codecov Report

Attention: 130 lines in your changes are missing coverage. Please review.

Comparison is base (d08687c) 63.0% compared to head (645b923) 62.7%.
Report is 68 commits behind head on master.

❗ Current head 645b923 differs from pull request most recent head 35ac4fc. Consider uploading reports for the commit 35ac4fc to get more accurate results

Files	Patch %	Lines
labgrid/remote/exporter.py	12.2%	86 Missing ⚠️
labgrid/driver/lauterbachdriver.py	70.6%	17 Missing ⚠️
labgrid/remote/client.py	22.7%	17 Missing ⚠️
labgrid/resource/lauterbach.py	82.6%	4 Missing ⚠️
labgrid/resource/udev.py	50.0%	4 Missing ⚠️
labgrid/resource/suggest.py	0.0%	1 Missing ⚠️
labgrid/util/helper.py	95.0%	1 Missing ⚠️

Additional details and impacted files

@@           Coverage Diff            @@
##           master   #1267     +/-   ##
========================================
- Coverage    63.0%   62.7%   -0.4%     
========================================
  Files         160     163      +3     
  Lines       11901   12145    +244     
========================================
+ Hits         7502    7616    +114     
- Misses       4399    4529    +130

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

userid0x0 · 2023-09-21T12:48:57Z

Hi,
I want to share a second strategy how to handle the 'which ports are available on the exporter' problem in ecda73d. The solution is more like ser2net. The exporter itself handles the start of the t32tcpusb agent and thus handles the tcp port reservation. This solution is already used since a couple of months.
Let me know which variant you prefer.

Regards,
Alex

Bastian-Krause

I want to share a second strategy how to handle the 'which ports are available on the exporter' problem in ecda73d. The solution is more like ser2net. The exporter itself handles the start of the t32tcpusb agent and thus handles the tcp port reservation. This solution is already used since a couple of months. Let me know which variant you prefer.

The initial approach looks much better to us. In most setup, the exporter runs as a different user. That user should not run arbitrary code. There is also a life cycle conflict there: _start() is called on acquire, but the corresponding binary is not present, yet (maybe from the last run). The hack using _get_start_params() for finding the symlink change is pretty clever, but not the intended approach. It's used for cases where the USB connection changes and ser2net has to be restarted.

Let's start with a rather high level review. When we figured out the rough direction for this PR, we will take a more detailed look.

Bastian-Krause · 2023-10-20T13:21:42Z

labgrid/protocol/debuggerprotocol.py

+import abc
+
+
+class DebuggerProtocol(abc.ABC):
+    """Abstract class for the DebuggerProtocol"""
+
+    @abc.abstractmethod
+    def start(self):
+        """
+        Start a debugger session
+        """
+        raise NotImplementedError


I think that's not really useful, yet. Let's add a protocol when another driver with similar functionality is added. Until then, just drop this.

The debugger protocol implementation has been dropped.

Bastian-Krause · 2023-10-20T13:22:30Z

labgrid/resource/udev.py

+
+@target_factory.reg_resource
+@attr.s(eq=False)
+class USBLauterbachDebugger(USBResource):
+    def filter_match(self, device):
+        # udevadm info --attribute-walk /dev/lauterbach/trace32/*
+        match = (device.properties.get('ID_VENDOR_ID'), device.properties.get('ID_MODEL_ID'))
+
+        if match not in [("0897", "0002"),  # PowerDebug USB1.0/USB2.0/Ethernet/II + PowerTrace
+                         ("0897", "0004"),  # PowerDebug USB3.0 + uTrace
+                         ("0897", "0005"),  # PowerDebug PRO/E40
+                         ("0897", "0006")   # PowerDebug X50
+                         ]:
+            return False
+
+        return super().filter_match(device)


Looks good.

Bastian-Krause · 2023-10-20T13:26:52Z

labgrid/resource/lauterbach.py

+    Args:
+        architecture (str): Architecture of the exporter userspace
+    """
+    architecture = attr.ib(validator=attr.validators.instance_of(str))


The architecture should be handled in the driver, see review comments there.

The Lauterbach driver has been extended to detect the processor architecture of the exporter on activation.

Bastian-Krause · 2023-10-20T13:31:16Z

labgrid/util/helper.py

+
+def get_uname_machine():
+    if hasattr(get_uname_machine, "architecture"):
+        return get_uname_machine.architecture
+
+    # translate `uname -m` output to debian/ubuntu architecture terms
+    uname_translate = {
+        "x86_64": "amd64"
+    }
+    # default: use ``uname -m``
+    get_uname_machine.architecture = processwrapper.check_output(["uname","-m"]).decode("utf-8").rstrip()
+    get_uname_machine.architecture = uname_translate.get(get_uname_machine.architecture, get_uname_machine.architecture)
+
+    # check ELF header - inspired by /proc/sys/fs/binfmt_misc/qemu-*
+    # Why? e.g. a AARCH64 Kernel can run a armhf userspace (buzzword: Raspian OS)
+    binfmt = {
+        "arm":     (b'\x7f\x45\x4c\x46\x01\x01\x01\x00\x00\x00\x00\x00\x00\x00\x00\x00' # e_ident
+                    b'\x02\x00\x28\x00'                                                 # e_type + e_machine
+                    b'\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00' # e_<version,entry,phoff,shoff>
+                    b'\x00\x00\x00\x00',                                                # e_flags
+                    b'\xff\xff\xff\xff\xff\xff\xff\x00\xff\xff\xff\xff\xff\xff\xff\xff'
+                    b'\xfe\xff\xff\xff'
+                    b'\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00'
+                    b'\x00\x00\x04\x00'),
+        "armhf":   (b'\x7f\x45\x4c\x46\x01\x01\x01\x00\x00\x00\x00\x00\x00\x00\x00\x00'
+                    b'\x02\x00\x28\x00'
+                    b'\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00'
+                    b'\x00\x00\x04\x00',
+                    b'\xff\xff\xff\xff\xff\xff\xff\x00\xff\xff\xff\xff\xff\xff\xff\xff'
+                    b'\xfe\xff\xff\xff'
+                    b'\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00'
+                    b'\x00\x00\x04\x00'),
+        "aarch64": (b'\x7f\x45\x4c\x46\x02\x01\x01\x00\x00\x00\x00\x00\x00\x00\x00\x00'
+                    b'\x02\x00\xb7\x00',
+                    b'\xff\xff\xff\xff\xff\xff\xff\x00\xff\xff\xff\xff\xff\xff\xff\xff'
+                    b'\xfe\xff\xff\xff'),
+        "amd64":   (b'\x7f\x45\x4c\x46\x02\x01\x01\x00\x00\x00\x00\x00\x00\x00\x00\x00'
+                    b'\x02\x00\x3e\x00',
+                    b'\xff\xff\xff\xff\xff\xff\xff\x00\xff\xff\xff\xff\xff\xff\xff\xff'
+                    b'\xfe\xff\xff\xff'),
+    }
+
+    elfheader = b''
+    with open("/proc/self/exe", "rb") as exe:
+        elfheader = exe.read(40)
+    for arch, compare in binfmt.items():
+        magic = compare[0]
+        mask = compare[1]
+
+        match = True
+        for i in range(min(len(elfheader),len(magic),len(mask))):
+            match = match and ((elfheader[i] & mask[i]) == magic[i])
+
+        if match:
+            get_uname_machine.architecture=arch
+            break
+
+    return get_uname_machine.architecture
+
+


Move this into a dedicated Lauterbach agent (labgrid/util/agents/). Agents are copied to the exporter on-the-fly and executed there via AgentWrapper. See labgrid/driver/gpiodriver.py for an example.

Code has been moved to labgrid/util/agents/hosttools.py.

Bastian-Krause · 2023-10-20T13:34:55Z

labgrid/resource/lauterbach.py

+
+@target_factory.reg_resource
+@attr.s(eq=False)
+class NetworkUSBLauterbachDebugger(RemoteUSBResource):


This should be RemoteUSBLauterbachDebugger. We tend to use the "Remote" prefix for resources which also exist as a local variant (USBLauterbachDebugger in this case) and the "Network" prefix for stand-alone network resources (such as the NetworkLauterbachDebugger).

Class has been renamed.

labgrid/driver/lauterbachdriver.py

Bastian-Krause · 2023-10-20T14:06:22Z

labgrid/driver/lauterbachdriver.py

+            "amd64":   "bin/pc_linux64",
+            "armhf":   "bin/linux-armhf"
+            }
+        self.t32sys = os.environ.get("T32SYS", "/opt/t32")


Other drivers use something like:

if self.target.env: self.tool = self.target.env.config.get_tool('mybinary') else: self.tool = 'mybinary'

Since there is no single binary in this case, maybe use a path from paths: via self.target.env.config.get_path() from https://labgrid.readthedocs.io/en/latest/configuration.html#environment-configuration instead?

The pystart library expects only the basename of the executable and handles the rest internally including e.g. host architecture detection. This is put into t32_bin now.
The t32_sys is used to specify the base installation folder.
I reworked that completely in the latests force push.

Bastian-Krause · 2023-10-20T14:09:11Z

labgrid/driver/lauterbachdriver.py

+            "NetworkLauterbachDebugger"
+        },
+    }
+    t32_bin = attr.ib(default="t32marm", validator=attr.validators.instance_of(str))


Maybe have a look at the QEMUDriver's qemu_bin attribute.

The dependency pystart will resolve the given executable basename to a full path.

Bastian-Krause · 2023-10-20T14:13:19Z

labgrid/remote/client.py

+
+        drv = None
+        try:
+            drv = target.get_driver("DebuggerProtocol", name=name)


Ah, that's where the protocol is useful. I guess until a second debugger driver is added, we can simply reference the driver directly.

Bastian-Krause · 2023-10-20T14:17:06Z

labgrid/remote/client.py

+
+    def debugger(self):
+        place = self.get_acquired_place()
+        target = self._get_target(place)
+        name = self.args.name
+        from ..resource.lauterbach import (NetworkLauterbachDebugger, NetworkUSBLauterbachDebugger)
+        from ..resource.udev import (USBLauterbachDebugger)
+
+        drv = None
+        try:
+            drv = target.get_driver("DebuggerProtocol", name=name)
+        except NoDriverFoundError:
+            for resource in target.resources:
+                if isinstance(resource, (NetworkLauterbachDebugger, NetworkUSBLauterbachDebugger, USBLauterbachDebugger)):
+                    drv = self._get_driver_or_new(target, "LauterbachDriver", activate=False,
+                                                  name=name)
+                if drv:
+                    break
+
+        if not drv:
+            raise UserError("target has no compatible resource available")
+        target.activate(drv)
+        drv.start()


Suggested change

def debugger(self):

place = self.get_acquired_place()

target = self._get_target(place)

name = self.args.name

from ..resource.lauterbach import (NetworkLauterbachDebugger, NetworkUSBLauterbachDebugger)

from ..resource.udev import (USBLauterbachDebugger)

drv = None

try:

drv = target.get_driver("DebuggerProtocol", name=name)

except NoDriverFoundError:

for resource in target.resources:

if isinstance(resource, (NetworkLauterbachDebugger, NetworkUSBLauterbachDebugger, USBLauterbachDebugger)):

drv = self._get_driver_or_new(target, "LauterbachDriver", activate=False,

name=name)

if drv:

break

if not drv:

raise UserError("target has no compatible resource available")

target.activate(drv)

drv.start()

def debugger(self):

place = self.get_acquired_place()

target = self._get_target(place)

name = self.args.name

drv = self._get_driver_or_new(target, "LauterbachDriver", name=name)

drv.start()

This should be sufficient.

Updated according to your suggestion.

ep1cman · 2023-11-08T12:13:41Z

Looking at this PR I am wondering if it might make sense to split it into two stages?

Firstly get DebuggerProtocol implemented since is useful in more than one place:

PR Resource: add Segger J-Link support #1175 is adding JLink support, it could quite easily match this proposed protocol (this is the end usecase I am currently looking at)
The already built in OpenOCDDriver that currently only supports writing firmware to devices not active debugging sessions which could be added via GDB server.

Once this is upstreamed, the Trace32 support can be merged separately

userid0x0 · 2023-11-13T10:25:26Z

Hi,
I included the feedback and did a force push to my fork. Let me know what you think.
Again I didn't include the signed-offs.

Adds driver for Lauterbach TRACE32 debug devices. Both interactive debugging and automation are supported. `examples/lauterbach` demonstrates the workflow for some local and remote use cases. Signed-off-by: Christoph Sax <[email protected]>

userid0x0 force-pushed the trace32 branch 2 times, most recently from d9d75bb to f21d593 Compare September 8, 2023 06:43

userid0x0 marked this pull request as draft September 21, 2023 13:04

Bastian-Krause added the enhancement label Oct 9, 2023

Bastian-Krause assigned jluebbe and Bastian-Krause Oct 9, 2023

Bastian-Krause requested changes Oct 20, 2023

View reviewed changes

userid0x0 force-pushed the trace32 branch from ecda73d to 645b923 Compare November 13, 2023 10:16

userid0x0 force-pushed the trace32 branch 3 times, most recently from 9e9c57c to 204a45c Compare November 13, 2023 15:33

jluebbe removed their assignment Dec 15, 2023

jluebbe requested a review from Bastian-Krause December 15, 2023 14:29

xasc force-pushed the trace32 branch 4 times, most recently from d148263 to 9ec723b Compare August 5, 2025 12:49

userid0x0 marked this pull request as ready for review August 5, 2025 13:11

Add support for Lauterbach PowerDebug devices

2079d89

Adds driver for Lauterbach TRACE32 debug devices. Both interactive debugging and automation are supported. `examples/lauterbach` demonstrates the workflow for some local and remote use cases. Signed-off-by: Christoph Sax <[email protected]>

xasc force-pushed the trace32 branch from 9ec723b to 2079d89 Compare September 19, 2025 12:09

add Trace32 debugger support #1267

Are you sure you want to change the base?

add Trace32 debugger support #1267

Uh oh!

Conversation

userid0x0 commented Sep 8, 2023

Uh oh!

codecov bot commented Sep 8, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

userid0x0 commented Sep 21, 2023

Uh oh!

Bastian-Krause left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ep1cman commented Nov 8, 2023

Uh oh!

userid0x0 commented Nov 13, 2023

Uh oh!

Uh oh!

codecov bot commented Sep 8, 2023 •

edited

Loading

Bastian-Krause left a comment •

edited

Loading