Yes we CAN... add new features

Have you ever experienced an otherwise fine product that is missing just the one feature you need for your application?

This is what happened when community member John Whittington debugged a CAN bus with his own fork of the original CandleLight Hardware design. He found that candump -H -t a only shows zeros in the hardware timestamp field, even though the firmware supports timestamping and opened an issue on github. While with conventional closed source products, this is the point where this story would end, for an open source project, this is where a journey starts. So let us have a look on how the firmware and driver of the open hardware project CandleLight got hardware timestamping support in a joint effort of community members.

Some stuffed bits of history

As for all good tales, the CandleLight's story begins quite some time ago. On Christmas Eve in 2013 (no, I am not kidding you) the first patch to support an USB-CAN adapter built by the company Geschwister Schneider UG was posted on the Linux-CAN mailing list. When Hubert Denkmair asked in 2016 on the linux-can mailinglist for an open protocol for USB CAN adapters, Max Schneider himself suggested to use the Geschwister Schneider implementation as a template and just extract the protocol definition from the existing driver and build a compatible device. Hubert Denkmair was hooked and later published his hardware design under the CERN Open Hardware License v1.2 and firmware under MIT License on Github. Over the years, several forks of the original design and the original firmware were added and modified, some featuring different micro-controllers, adding multichannel support or using USB-C.

Hardware Timestamping

For precise measurements of the timing behavior on a bus or for running timing protocols on a bus, it is very important to know the exact point in time when a packet (or frame, as they are called in the CAN-universe) is transmitted or received. Most modern Ethernet interfaces and some CAN controllers have this feature, as it is also used to increase the precision of timing protocols such as the Precision Time Protocol PTP on Ethernet or the SYNC protocol on CANopen. This requires the hardware handling the packets to do this measurement as close to the hardware as possible, to minimize jitter in the measurement. The most common method to achieve this is to have a constantly running hardware counter, which is latched into a register on the Receive- or Transmit-complete-interrupt by hardware.

To achieve the lowest possible jitter this latching should be implemented as a feature of the CAN hardware itself and be sampled at a known point in the CAN frame. Sadly the micro-controller in the CandleLight does not support this kind of extra-low-latency hardware timestamping on its CAN Interface. The CandleLight firmware can however add timestamps in its CAN receive interrupt routine, which gives a jitter-performance that is not as good as actual hardware timestamps but miles ahead of the timestamps Linux can generate on the other end of the USB connection, where it hat to travel through several layers of soft- and hardware. For simplicity's sake we will just call these timestamps generated in the firmware hardware timestamps to differentiate them from the timestamps generated in Linux which we will call software timestamps.

To see if your hardware supports timestamping, use ethtool --show-time-stamping <device> which will list the capabilities of your hardware. For a CAN interface with hardware timestamping support the result will for example look like

>ethtool --show-time-stamping can0
Time stamping parameters for can0:
Capabilities:
     hardware-transmit
     software-transmit
     hardware-receive
     software-receive
     software-system-clock
     hardware-raw-clock
PTP Hardware Clock: none
Hardware Transmit Timestamp Modes:
     on
Hardware Receive Filter Modes:
     all

Teaching an old driver new tricks

While the CandleLight firmware has support for hardware timestamps since 2016, the gs_usb driver used for the CandleLight did not read the timestamps transmitted over USB until recently. The fact that the firmware with hardware timestamping works with an older driver is due to a clever trick in the USB protocol: the protocol has a bit field for indicating additional features. Hardware timestamps is one of these features, but as long as said feature is not supported on both sides, it is simply ignored. This allows for forward and backward compatibility of new firmware and new driver features. With some pointers from the maintainers to other drivers implementing hardware timestamping, John added the required feature and published it on github. This work was also posted on the linux-can mailing list and then finally made its way mainline with the 6.1 kernel release.

The results are quite impressive: John shared some measurement results which show a significant improvement of the hardware timestamps over software timestamps.

In the diagram above the y-axis shows the observed timestamp jitter of the hardware timestamps on the left vs. the software timestamping performed in Linux.

Sharing is Caring

Not only did John share his driver patches, which allows all CandleLight users to also have this new cool feature available, but he also shared the script used for analysis and plot of the measurement results. He also presented the technical details and more detailed measurement results in a post on his own blog.

This entire story shows the benefits of active participation in open-source development. Not just using open source projects and making use of other peoples' efforts, but also adding new features and contributing back to the projects is what makes our everyday job so great.

Outlook

This new feature on the gs_usb driver allows for precise timing measurement, but there is also some other ongoing work in the CandleLight project:

  • adding CAN-FD to the firmware (the USB protocol already supports CAN-FD)
  • currently the transmit timestamps are generated when the packet is inserted into the TX FIFO. Using the TX Complete Interrupt will increase their precision even more.
  • at the moment timestamps have 1µs resolution. The internal micro-controller clock could allow for some more precision, which is to be evaluated.

If you want to participate in these tasks, you are more than welcome, just according to last year's Pengutronix Christmas card motto Send Patches!


Further Readings

First Steps using the candleLight

So you went and got yourself one of our fancy rocket-penguin branded CandleLight dongles or, being the die hard hacker you are, went and soldered one up in your toaster oven labeled "not food safe". What's next then? How do you use this thing? Let's answer these question by grabbing a Raspberry Pi and exploring some of the possibilities.


The USB-SD-Mux is now FAST

We have been distributing the USB-SD-Mux with our partner company Linux Automation GmbH since 2019. This has enabled us to make work easier for many embedded developers and improve software quality. At the same time, technology is advancing: micro SD cards are becoming faster and USB-C is now established as the standard.


Managing Complexity with Open Source

A few days ago, something exciting happened: I revisited my very first embedded system - a 34 year old stepper motor controller, driving the telescope mount of the Public Observatory Rothwesten, which was built by me back when I was in class 12 in highschool. Comparing those embedded systems from back in the days with the recent industrial systems, it is impressive to see that the latter ones are not managable any more without the use of open source software.


Pengutronix at FrOSCon 2024

On August 17th and 18th, 2024, it's that time again: FrOSCon will take place at the Bonn-Rhein-Sieg University of Applied Sciences in Sankt Augustin - and Pengutronix will be there again as a Partner.


Linux Automation's Optick: A Glass-to-Glass Latency Measurement Tool

New Linux Automation GmbH products are often inspired by needs we observe in our day-to-day development work at Pengutronix. Today's new product, the Optick, was inspired by our graphics team, that works with different kinds of video pipelines and optimizes them based on customer demands. One such demand is minimizing the latency of camera to display video pipelines.


candleLight FD - Open Hardware USB-to-CAN-FD interface

This week Linux Automation has released a CAN-FD version of the low-cost USB-to-CAN interface candleLight: the candleLight FD. And as the candleLight the candleLight FD is Open Hardware. Check the KiCad project on Github.


LXA USB-T1L ❤️ Beagle Play: Exploring Single Wire Ethernet

It seems everybody is talking about Single Pair Ethernet (SPE) these days. So we want to follow the trend and do the same :-) SPE is a class of Ethernet transmission standards that uses just a single pair of twisted pair cable for data transmission. There are multiple SPE variants spanning maximum data rates from a hand full MBit/s to multiple GBit/s and cable lengths from a hand full of meters to kilometers. The most interesting ones from our embedded-centric point of view are 10Base-T1L (point-to-point, up to 1 km), 10Base-T1S (multidrop, approx. 10 m) and 100Base-T1 (point-to-point, 15 m). The new Beagle Play comes with a 10Base-T1L PHY. This makes it a great peer to experiment with our Linux Automation USB-T1L. In this post we will explore the possibilities of 10Base-T1L on a recent Linux system.


DSA in Barebox

The v2022.05.0 Release of barebox introduced initial support for the Distributed Switch Architecture (DSA) Framework. DSA is originally a subsystem from the Linux Kernel, which exposes the individual ports of a network switch IC as virtual network interfaces.


Did you know? Initializing CAN interfaces with systemd-networkd

End of January systemd 250 was added to Debian bullseye backports. With a lots of new features and fixes now comes the possibility to set the timing of CAN bus interfaces with systemd-networkd. In this blogpost I will take a look at why this helps us maintain our embedded Linux labs.


labgrid Tutorials

This week, we started our series of YouTube labgrid tutorials. In the next few weeks we will publish more video tutorials showing you labgrid's features and giving you handy tips and tricks.