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.

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.

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.

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).

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.

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.

match USB connected - PowerDebug USB1.0/USB2.0/USB3.0/Ethernet/PRO/E40/X50 - PowerTrace - uTrace

Network devices support always UDP, the most recent devices e.g. PowerDebug X50 have an option to use TCP which enables LG_PROXY support.

On ARM (e.g. Raspian OS) runs a 32bit userspace (e.g. armhf) on a Aarch64/ARM64 machine. Thus `uname -m` might be misleading as it identifies the kernel and not the userspace. The introduced `get_uname_machine` checks the elf header of the python interpreter itself to detect the architecture for dynamically linked applications. The terms align with the debian/ubuntu architecture naming (arm/armhf/aarch64/amd64).

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.

start a debug session using the DebuggerProtocol

fixup endianness twist to detect HARDFP ABI for ARM

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

Alexander Merkle added 3 commits November 6, 2023 12:23

udev,suggest: add matching for Lauterbach PowerDebug devices

797f047

match USB connected - PowerDebug USB1.0/USB2.0/USB3.0/Ethernet/PRO/E40/X50 - PowerTrace - uTrace

resources: add RemoteUSBLauterbachDebugger & NetworkLauterbachDebugger

48c8166

Network devices support always UDP, the most recent devices e.g. PowerDebug X50 have an option to use TCP which enables LG_PROXY support.

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

userid0x0 force-pushed the trace32 branch 2 times, most recently from cff4278 to 9e9c57c Compare November 13, 2023 11:33

Alexander Merkle added 5 commits November 13, 2023 16:30

driver: introduce LauterbachDriver

b47083f

driver/lauterbachdriver: add Bootstrap protocol

7b39d95

client: add labgrid-client debugger command

ee4cc95

start a debug session using the DebuggerProtocol

doc: add documentation for Lauterbach TRACE32 components

fb5f6dc

Tests: add test for Lauterbach Resources and Driver

204a45c

userid0x0 force-pushed the trace32 branch 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

util: fix get_uname_machine

35ac4fc

fixup endianness twist to detect HARDFP ABI for ARM

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

add Trace32 debugger support #1267

add Trace32 debugger support #1267

userid0x0 commented Sep 8, 2023

codecov bot commented Sep 8, 2023 •

edited

userid0x0 commented Sep 21, 2023

Bastian-Krause left a comment •

edited

Bastian-Krause Oct 20, 2023

Bastian-Krause Oct 20, 2023

Bastian-Krause Oct 20, 2023

Bastian-Krause Oct 20, 2023

Bastian-Krause Oct 20, 2023

Bastian-Krause Oct 20, 2023

userid0x0 Nov 13, 2023

Bastian-Krause Oct 20, 2023

Bastian-Krause Oct 20, 2023

Bastian-Krause Oct 20, 2023

ep1cman commented Nov 8, 2023

userid0x0 commented Nov 13, 2023

add Trace32 debugger support #1267

Are you sure you want to change the base?

add Trace32 debugger support #1267

Conversation

userid0x0 commented Sep 8, 2023

codecov bot commented Sep 8, 2023 • edited

Codecov Report

userid0x0 commented Sep 21, 2023

Bastian-Krause left a comment • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ep1cman commented Nov 8, 2023

userid0x0 commented Nov 13, 2023

codecov bot commented Sep 8, 2023 •

edited

Bastian-Krause left a comment •

edited