[PATCH 0/2] can: add Transmitter Delay Compensation (TDC) documentation

[PATCH 0/2] can: add Transmitter Delay Compensation (TDC) documentation

[Vincent Mailhol]

TDC was added to the kernel in 2021 but I never took time to update
the documentation. The year is now 2025... As we say: "better late
than never"!

The first patch is a small clean up which fixes an incorrect statement
concerning the CAN DLC, the second patch is the real thing and adds
the documentation of how to use the ip tool to configure the TDC.

Signed-off-by: Vincent Mailhol <mailhol@kernel.org>
---
Vincent Mailhol (2):
      can: remove false statement about 1:1 mapping between DLC and length
      can: add Transmitter Delay Compensation (TDC) documentation

 Documentation/networking/can.rst | 67 +++++++++++++++++++++++++++++++++++++---
 1 file changed, 63 insertions(+), 4 deletions(-)
---
base-commit: 67029a49db6c1f21106a1b5fcdd0ea234a6e0711
change-id: 20251012-can-fd-doc-692e7bdd6369

Best regards,
-- 
Vincent Mailhol <mailhol@kernel.org>

[PATCH 1/2] can: remove false statement about 1:1 mapping between DLC and length

[Vincent Mailhol]

The CAN-FD section of can.rst still states that there is a 1:1 mapping
between the Classical CAN DLC and its length. This is only true for
the DLC values up to 8. Beyond that point, the length remains at 8.

For reference, the mapping between the CAN DLC and the length is given
in below table [1]:

	 DLC value	CBFF and CEFF	FBFF and FEFF
	 [decimal]	    [byte]	    [byte]
	----------------------------------------------
		 0		 0		 0
		 1		 1		 1
		 2		 2		 2
		 3		 3		 3
		 4		 4		 4
		 5		 5		 5
		 6		 6		 6
		 7		 7		 7
		 8		 8		 8
		 9		 8		12
		10		 8		16
		11		 8		20
		12		 8		24
		13		 8		32
		14		 8		48
		15		 8		64

Remove the erroneous statement. Instead just state that the length of
a Classical CAN frame ranges from 0 to 8.

[1] ISO 11898-1:2024, Table 5 -- DLC: coding of the four LSB

Signed-off-by: Vincent Mailhol <mailhol@kernel.org>
---
 Documentation/networking/can.rst | 7 +++----
 1 file changed, 3 insertions(+), 4 deletions(-)

diff --git a/Documentation/networking/can.rst b/Documentation/networking/can.rst
index f93049f03a37..58c026d51d94 100644
--- a/Documentation/networking/can.rst
+++ b/Documentation/networking/can.rst
@@ -1398,10 +1398,9 @@ second bit timing has to be specified in order to enable the CAN FD bitrate.
 Additionally CAN FD capable CAN controllers support up to 64 bytes of
 payload. The representation of this length in can_frame.len and
 canfd_frame.len for userspace applications and inside the Linux network
-layer is a plain value from 0 .. 64 instead of the CAN 'data length code'.
-The data length code was a 1:1 mapping to the payload length in the Classical
-CAN frames anyway. The payload length to the bus-relevant DLC mapping is
-only performed inside the CAN drivers, preferably with the helper
+layer is a plain value from 0 .. 64 instead of the Classical CAN length
+which ranges from 0 to 8. The payload length to the bus-relevant DLC mapping
+is only performed inside the CAN drivers, preferably with the helper
 functions can_fd_dlc2len() and can_fd_len2dlc().
 
 The CAN netdevice driver capabilities can be distinguished by the network

-- 
2.49.1

[PATCH 2/2] can: add Transmitter Delay Compensation (TDC) documentation

[Vincent Mailhol]

Back in 2021, support for CAN TDC was added to the kernel in series [1]
and in iproute2 in series [2]. However, the documentation was never
updated.

Add a new sub-section under CAN-FD driver support to document how to
configure the TDC using the "ip tool".

[1] add the netlink interface for CAN-FD Transmitter Delay Compensation (TDC)
Link: https://lore.kernel.org/all/20210918095637.20108-1-mailhol.vincent@wanadoo.fr/

[2] iplink_can: cleaning, fixes and adding TDC support
Link: https://lore.kernel.org/all/20211103164428.692722-1-mailhol.vincent@wanadoo.fr/

Signed-off-by: Vincent Mailhol <mailhol@kernel.org>
---
 Documentation/networking/can.rst | 60 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 60 insertions(+)

diff --git a/Documentation/networking/can.rst b/Documentation/networking/can.rst
index 58c026d51d94..de9e7549859f 100644
--- a/Documentation/networking/can.rst
+++ b/Documentation/networking/can.rst
@@ -1464,6 +1464,66 @@ Example when 'fd-non-iso on' is added on this switchable CAN FD adapter::
    can <FD,FD-NON-ISO> state ERROR-ACTIVE (berr-counter tx 0 rx 0) restart-ms 0
 
 
+Transmitter Delay Compensation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+At high bit rates, the propagation delay from the TX pin to the RX pin of
+the transceiver might become greater than the actual bit time causing
+measurement errors: the RX pin would still be measuring the previous bit.
+
+The Transmitter Delay Compensation (thereafter, TDC) resolves this problem
+by introducing a Secondary Sample Point (SSP) equal to the distance, in
+minimum time quantum, from the start of the bit time on the TX pin to the
+actual measurement on the RX pin. The SSP is calculated as the sum of two
+configurable values: the TDC Value (TDCV) and the TDC offset (TDCO).
+
+TDC, if supported by the device, can be configured together with CAN-FD
+using the ip tool's "tdc-mode" argument as follow::
+
+- **omitted**: when no "tdc-mode" option is provided, the kernel will
+  automatically decide whether TDC should be turned on, in which case it
+  will calculate a default TDCO and use the TDCV as measured by the
+  device. This is the recommended method to use TDC.
+
+- **"tdc-mode off"**: TDC is explicitly disabled.
+
+- **"tdc-mode auto"**: the user must provide the "tdco" argument. The TDCV
+  will be automatically calculated by the device. This option is only
+  available if the device supports the TDC-AUTO CAN controller mode.
+
+- **"tdc-mode manual"**: the user must provide both the "tdco" and "tdcv"
+  arguments. This option is only available if the device supports the
+  TDC-MANUAL CAN controller mode.
+
+Note that some devices may offer an additional parameter: "tdcf" (TDC Filter
+window). If supported by your device, this can be added as an optional
+argument to either "tdc-mode auto" or "tdc-mode manual".
+
+Example configuring a 500 kbit/s arbitration bitrate, a 5 Mbit/s data
+bitrate, a TDCO of 15 minimum time quantum and a TDCV automatically measured
+by the device::
+
+    $ ip link set can0 up type can bitrate 500000 \
+                                   fd on dbitrate 4000000 \
+				   tdc-mode auto tdco 15
+    $ ip -details link show can0
+    5: can0: <NOARP,UP,LOWER_UP,ECHO> mtu 72 qdisc pfifo_fast state UP \
+             mode DEFAULT group default qlen 10
+        link/can  promiscuity 0 allmulti 0 minmtu 72 maxmtu 72
+        can <FD,TDC-AUTO> state ERROR-ACTIVE restart-ms 0
+          bitrate 500000 sample-point 0.875
+          tq 12 prop-seg 69 phase-seg1 70 phase-seg2 20 sjw 10 brp 1
+          ES582.1/ES584.1: tseg1 2..256 tseg2 2..128 sjw 1..128 brp 1..512 \
+          brp_inc 1
+          dbitrate 4000000 dsample-point 0.750
+          dtq 12 dprop-seg 7 dphase-seg1 7 dphase-seg2 5 dsjw 2 dbrp 1
+          tdco 15 tdcf 0
+          ES582.1/ES584.1: dtseg1 2..32 dtseg2 1..16 dsjw 1..8 dbrp 1..32 \
+          dbrp_inc 1
+          tdco 0..127 tdcf 0..127
+          clock 80000000
+
+
 Supported CAN Hardware
 ----------------------
 

-- 
2.49.1

Re: [PATCH 2/2] can: add Transmitter Delay Compensation (TDC) documentation

[Andrew Lunn]

On Sun, Oct 12, 2025 at 08:23:43PM +0900, Vincent Mailhol wrote:
> Back in 2021, support for CAN TDC was added to the kernel in series [1]
> and in iproute2 in series [2]. However, the documentation was never
> updated.

Hi Vincent

I also don't see anything in man ip-link, nor ip link help. Maybe you
can add this documentation as well?

	Andrew

Re: [PATCH 2/2] can: add Transmitter Delay Compensation (TDC) documentation

[Vincent Mailhol]

Hi Andrew,

On 12/10/2025 at 23:47, Andrew Lunn wrote:
> On Sun, Oct 12, 2025 at 08:23:43PM +0900, Vincent Mailhol wrote:
>> Back in 2021, support for CAN TDC was added to the kernel in series [1]
>> and in iproute2 in series [2]. However, the documentation was never
>> updated.
> 
> Hi Vincent
> 
> I also don't see anything in man ip-link, nor ip link help. Maybe you
> can add this documentation as well?

The help is indeed not directly visible. But I think this is intended
because can is a sub type. The can is simply listed in man ip-link
under the Link types enumeration.

The can help then be obtain by providing that can type:

  $ ip link help can
  Usage: ip link set DEVICE type can
  	[ bitrate BITRATE [ sample-point SAMPLE-POINT] ] |
  	[ tq TQ prop-seg PROP_SEG phase-seg1 PHASE-SEG1
   	  phase-seg2 PHASE-SEG2 [ sjw SJW ] ]

  	[ dbitrate BITRATE [ dsample-point SAMPLE-POINT] ] |
  	[ dtq TQ dprop-seg PROP_SEG dphase-seg1 PHASE-SEG1
   	  dphase-seg2 PHASE-SEG2 [ dsjw SJW ] ]
  	[ tdcv TDCV tdco TDCO tdcf TDCF ]

  	[ loopback { on | off } ]
  	[ listen-only { on | off } ]
  	[ triple-sampling { on | off } ]
  	[ one-shot { on | off } ]
  	[ berr-reporting { on | off } ]
  	[ fd { on | off } ]
  	[ fd-non-iso { on | off } ]
  	[ presume-ack { on | off } ]
  	[ cc-len8-dlc { on | off } ]
  	[ tdc-mode { auto | manual | off } ]

  	[ restart-ms TIME-MS ]
  	[ restart ]

  	[ termination { 0..65535 } ]

  	Where: BITRATE	:= { NUMBER in bps }
  		  SAMPLE-POINT	:= { 0.000..0.999 }
  		  TQ		:= { NUMBER in ns }
  		  PROP-SEG	:= { NUMBER in tq }
  		  PHASE-SEG1	:= { NUMBER in tq }
  		  PHASE-SEG2	:= { NUMBER in tq }
  		  SJW		:= { NUMBER in tq }
  		  TDCV		:= { NUMBER in tc }
  		  TDCO		:= { NUMBER in tc }
  		  TDCF		:= { NUMBER in tc }
  		  RESTART-MS	:= { 0 | NUMBER in ms }

Does this make sense?


Yours sincerely,
Vincent Mailhol

Re: [PATCH 2/2] can: add Transmitter Delay Compensation (TDC) documentation

[Andrew Lunn]

On Mon, Oct 13, 2025 at 01:01:15AM +0900, Vincent Mailhol wrote:
> Hi Andrew,
> 
> On 12/10/2025 at 23:47, Andrew Lunn wrote:
> > On Sun, Oct 12, 2025 at 08:23:43PM +0900, Vincent Mailhol wrote:
> >> Back in 2021, support for CAN TDC was added to the kernel in series [1]
> >> and in iproute2 in series [2]. However, the documentation was never
> >> updated.
> > 
> > Hi Vincent
> > 
> > I also don't see anything in man ip-link, nor ip link help. Maybe you
> > can add this documentation as well?
> 
> The help is indeed not directly visible. But I think this is intended
> because can is a sub type. The can is simply listed in man ip-link
> under the Link types enumeration.
> 
> The can help then be obtain by providing that can type:
> 
>   $ ip link help can
>   Usage: ip link set DEVICE type can
>   	[ bitrate BITRATE [ sample-point SAMPLE-POINT] ] |
>   	[ tq TQ prop-seg PROP_SEG phase-seg1 PHASE-SEG1
>    	  phase-seg2 PHASE-SEG2 [ sjw SJW ] ]
>   	[ dbitrate BITRATE [ dsample-point SAMPLE-POINT] ] |
>   	[ dtq TQ dprop-seg PROP_SEG dphase-seg1 PHASE-SEG1
>    	  dphase-seg2 PHASE-SEG2 [ dsjw SJW ] ]
>   	[ tdcv TDCV tdco TDCO tdcf TDCF ]

O.K. Great, thanks for pointing this out.

	Andrew

Re: [PATCH 2/2] can: add Transmitter Delay Compensation (TDC) documentation

[Simon Horman]

On Sun, Oct 12, 2025 at 08:23:43PM +0900, Vincent Mailhol wrote:

...

> @@ -1464,6 +1464,66 @@ Example when 'fd-non-iso on' is added on this switchable CAN FD adapter::
>     can <FD,FD-NON-ISO> state ERROR-ACTIVE (berr-counter tx 0 rx 0) restart-ms 0
>  
>  
> +Transmitter Delay Compensation
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +At high bit rates, the propagation delay from the TX pin to the RX pin of
> +the transceiver might become greater than the actual bit time causing
> +measurement errors: the RX pin would still be measuring the previous bit.
> +
> +The Transmitter Delay Compensation (thereafter, TDC) resolves this problem
> +by introducing a Secondary Sample Point (SSP) equal to the distance, in
> +minimum time quantum, from the start of the bit time on the TX pin to the
> +actual measurement on the RX pin. The SSP is calculated as the sum of two
> +configurable values: the TDC Value (TDCV) and the TDC offset (TDCO).
> +
> +TDC, if supported by the device, can be configured together with CAN-FD
> +using the ip tool's "tdc-mode" argument as follow::
> +
> +- **omitted**: when no "tdc-mode" option is provided, the kernel will

Hi Vincent,

I'm unsure why, but make htmldocs reports:

.../can.rst:1484: ERROR: Unexpected indentation. [docutils]

> +  automatically decide whether TDC should be turned on, in which case it
> +  will calculate a default TDCO and use the TDCV as measured by the
> +  device. This is the recommended method to use TDC.

...

Re: [PATCH 0/2] can: add Transmitter Delay Compensation (TDC) documentation

[Marc Kleine-Budde]

[-- Attachment #1: Type: text/plain, Size: 790 bytes --]

On 12.10.2025 20:23:41, Vincent Mailhol wrote:
> TDC was added to the kernel in 2021 but I never took time to update
> the documentation. The year is now 2025... As we say: "better late
> than never"!
> 
> The first patch is a small clean up which fixes an incorrect statement
> concerning the CAN DLC, the second patch is the real thing and adds
> the documentation of how to use the ip tool to configure the TDC.
> 
> Signed-off-by: Vincent Mailhol <mailhol@kernel.org>

Added to linux-can.

Thanks,
Marc

-- 
Pengutronix e.K.                 | Marc Kleine-Budde          |
Embedded Linux                   | https://www.pengutronix.de |
Vertretung Nürnberg              | Phone: +49-5121-206917-129 |
Amtsgericht Hildesheim, HRA 2686 | Fax:   +49-5121-206917-9   |

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 488 bytes --]