Add kernel timestamp support

[michael-betz]

The linux kernel provides high resolution timestamps for received CAN frames.

This pull requests adds CanRaw.GetLastTimeStamp() to retrieve the timestamp of the last read frame.

The timestamp is in micro-seconds unix time.

Tested with an inno-maker USB2CAN dongle:

# Add virtual CAN interface called `vcan0`
sudo ip link add dev vcan0 type vcan
sudo ip link set up vcan0

dotnet run --project src/devices/SocketCan/samples/SocketCan.Samples.csproj receive vcan0

# in another window
cansend vcan0 123#DEADBEEF

# Console output
  Can.Samples.csproj receive vcan0
  Listening for any id
  Ts: 2025-08-24T17:59:17.9521580Z Id: 0x123 [SFF]: DEADBEEF
  Ts: 2025-08-24T17:59:18.2795050Z Id: 0x123 [SFF]: DEADBEEF
  Ts: 2025-08-24T17:59:19.2140580Z Id: 0x123 [SFF]: DEADBEEF

Microsoft Reviewers: Open in CodeFlow

[michael-betz]

@dotnet-policy-service agree

[krwq]

[Triage] Rather than adding GetTimeStamp API add another overload of TryReadFrame which out the timestamp or time. You should also make sure that when older version of kernel is used the error message tells you what version of kernel is required to use the new API. GetTimeStamp directly on CanRaw is very confusing.

[krwq]

there should be a comment that long is correct type only because we're using this in conjunction with latest kernel. Please double check this actually works with 32-bit OS-es (if not then please make sure to display correct error message)

[krwq]

note, you don't need to test it - just double check what type is defined in the latest kernel's .h file, if it's int64_t or equivalent we're good if it's platform specific like int then likely not

[michael-betz]

Okay, I did some digging. In C, the ioctl call returns:

       struct timeval {
           time_t       tv_sec;   /* Seconds */
           suseconds_t  tv_usec;  /* Microseconds */
       };

time_t can be a signed integer of 32 bit or 64 bit, depending on the platform.

In C#, I map this to a long type which is always a 64 bit signed integer.

If I run this on a 64 bit system, everything fits bit by bit.

If I run this on a 32-bit system, the C# runtime will promote the 32-bit return value to long properly.

Please correct me if I'm wrong.

I will look into testing this on a 32 bit system.

[raffaeler]

Is DateTime the correct for this timestamp?
When I see a DateTime, I expect this represent the "real" moment when the event occurred. I also expect to be able to compare this value with other DateTime instances coming from other sensors.

If instead this timestamp represents the time elapsed since the OS started, IMO the TimeSpan type would be more appropriate.

[michael-betz]

The kernel does indeed return the absolute value of the system clock when the CAN frame was received (microseconds since the 1.1.1970). So I think DateTime is a good type for this.

[raffaeler]

Good to know, thanks

[michael-betz]

You should also make sure that when older version of kernel is used the error message tells you what version of kernel is required to use the new API.

Okay, I did some research on this.
SocketCAN was merged into the mainline Linux kernel in version 2.6.25, which was released in April 2008.
This version already supports timestamps via ioctl(SIOCGSTAMP)

So seems like, if SocketCAN works, there is a very good chance that getting timestamps will also work.