| lists.openwall.net | lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC | |
|
Open Source and information security mailing list archives
| ||
|
Message-ID: <20260118144118.27487-1-rakuram.e96@gmail.com>
Date: Sun, 18 Jan 2026 20:11:18 +0530
From: Rakuram Eswaran <rakuram.e96@...il.com>
To: socketcan@...tkopp.net
Cc: corbet@....net,
linux-can@...r.kernel.org,
linux-doc@...r.kernel.org,
mailhol@...nel.org,
mkl@...gutronix.de,
netdev@...r.kernel.org,
rakuram.e96@...il.com
Subject: Re: [PATCH 2/2] docs: can: update SocketCAN documentation for CAN XL
On Tue, 13 Jan 2026 at 21:45, Oliver Hartkopp <socketcan@...tkopp.net> wrote:
>
> Hello Rakuram,
>
> many thanks for that update.
>
> I removed some netdev maintainers as this is a CAN & doc topic and we
> should not bother them with such patches IMO.
Thank you.
>
> On 31.12.25 19:13, Rakuram Eswaran wrote:
> > Extend the SocketCAN documentation to cover CAN XL support, including
> > the updated frame layout, MTU definitions, mixed-mode operation, and
> > bitrate/XBTR configuration. The new text also explains how error
> > signalling behaviour differs between CAN FD, CAN XL mixed-mode, and
> > CAN-XL-only operation, as implemented in the current kernel stack.
> >
> > In addition, provide example iproute2 "ip" tool commands demonstrating
> > how to configure CAN XL interfaces and corresponding bittiming
> > attributes.
> >
> > These updates align the documentation with the behaviour of recent
> > CAN XL implementations and help users and developers set up correct
> > test environments.
> >
> > Signed-off-by: Rakuram Eswaran <rakuram.e96@...il.com>
> > ---
> > Tested the documentation build with Sphinx; no errors or warnings.
> >
> > Used below command for testing:
> > make htmldocs SPHINX_WARNINGS_LOG=warnings.log
> >
> > Documentation/networking/can.rst | 615 +++++++++++++++++++++++++++++++++------
> > 1 file changed, 518 insertions(+), 97 deletions(-)
> >
> > diff --git a/Documentation/networking/can.rst b/Documentation/networking/can.rst
> > index 536ff411da1d1016fb84b82ff3bfeef3813bf98f..67c94e44dddfcb7c503b2f0d644d1662b7d66576 100644
> > --- a/Documentation/networking/can.rst
> > +++ b/Documentation/networking/can.rst
> > @@ -5,7 +5,7 @@ SocketCAN - Controller Area Network
> > Overview / What is SocketCAN
> > ============================
> >
> > -The socketcan package is an implementation of CAN protocols
> > +The SocketCAN package is an implementation of CAN protocols
> > (Controller Area Network) for Linux. CAN is a networking technology
> > which has widespread use in automation, embedded devices, and
> > automotive fields. While there have been other CAN implementations
> > @@ -16,6 +16,11 @@ as similar as possible to the TCP/IP protocols to allow programmers,
> > familiar with network programming, to easily learn how to use CAN
> > sockets.
> >
> > +SocketCAN covers Classical CAN (CAN 2.0B), CAN FD (Flexible Data Rate)
>
> CAN CC (Classical CAN aka CAN 2.0B), CAN FD (CAN with Flexible Data rate)
>
Ack.
> > +and CAN XL (CAN with eXtended frame Length). All three generations
> > +share the same protocol family PF_CAN and socket API concepts, but use
> > +different frame structures and MTUs as described below.
> > +
> >
> > .. _socketcan-motivation:
> >
> > @@ -109,11 +114,21 @@ As described in :ref:`socketcan-motivation` the main goal of SocketCAN is to
> > provide a socket interface to user space applications which builds
> > upon the Linux network layer. In contrast to the commonly known
> > TCP/IP and ethernet networking, the CAN bus is a broadcast-only(!)
> > -medium that has no MAC-layer addressing like ethernet. The CAN-identifier
> > -(can_id) is used for arbitration on the CAN-bus. Therefore the CAN-IDs
> > -have to be chosen uniquely on the bus. When designing a CAN-ECU
> > -network the CAN-IDs are mapped to be sent by a specific ECU.
> > -For this reason a CAN-ID can be treated best as a kind of source address.
> > +medium that has no MAC-layer addressing like ethernet.
> > +
> > +For Classical CAN and CAN FD the CAN identifier (can_id) is used for
>
> I would also go for "CAN CC and CAN FD" here
>
Ack.
> > +arbitration on the CAN-bus. The CAN-IDs have to be chosen uniquely on
> > +the bus.
>
> because of the CAN arbitration principle.
>
Ack.
> > When designing a CAN-ECU network the CAN-IDs are mapped to be
> > +sent by a specific ECU.
> > For this reason a CAN-ID can be treated best
> > +as a kind of source address.
> > +
> > +For CAN XL the arbitration is performed on an 11 bit *priority* field
> > +in the ``prio`` element of the CAN XL frame. The field shares the same
>
> arbitration priciple and
> > +bit width as Classical CAN
>
> CAN CC/FD
>
Ack.
> > standard identifiers and is restricted by
> > +``CANXL_PRIO_MASK`` / ``CANXL_PRIO_BITS``. The remaining bits of ``prio``
> > +
> > +can optionally carry an 8-bit Virtual CAN Network Identifier (VCID) for
> > +logical separation of traffic.
> >
> >
> > .. _socketcan-receive-lists:
> > @@ -228,8 +243,9 @@ send(2), sendto(2), sendmsg(2) and the recv* counterpart operations
> > on the socket as usual. There are also CAN specific socket options
> > described below.
> >
> > -The Classical CAN frame structure (aka CAN 2.0B), the CAN FD frame structure
> > -and the sockaddr structure are defined in include/linux/can.h:
> > +The Classical CAN frame structure (aka CAN 2.0B),
>
> CAN CC
>
> > the CAN FD frame structure,
> > +the CAN XL frame structure and the sockaddr structure are defined in
> > +include/uapi/linux/can.h:
> >
> > .. code-block:: C
> >
> > @@ -242,11 +258,11 @@ and the sockaddr structure are defined in include/linux/can.h:
> > */
> > __u8 len;
> > __u8 can_dlc; /* deprecated */
> > - };
> > - __u8 __pad; /* padding */
> > - __u8 __res0; /* reserved / padding */
> > + } __attribute__((packed)); /* disable padding added in some ABIs */
> > + __u8 __pad; /* padding */
> > + __u8 __res0; /* reserved / padding */
> > __u8 len8_dlc; /* optional DLC for 8 byte payload length (9 .. 15) */
> > - __u8 data[8] __attribute__((aligned(8)));
> > + __u8 data[CAN_MAX_DLEN] __attribute__((aligned(8)));
> > };
>
> Thanks for the update!
>
> >
> > Remark: The len element contains the payload length in bytes and should be
> > @@ -406,7 +422,7 @@ the CAN_RAW socket supports a new socket option CAN_RAW_FD_FRAMES that
> > switches the socket into a mode that allows the handling of CAN FD frames
> > and Classical CAN frames simultaneously (see :ref:`socketcan-rawfd`).
> >
> > -The struct canfd_frame is defined in include/linux/can.h:
> > +The struct canfd_frame is defined in include/uapi/linux/can.h:
> >
> > .. code-block:: C
> >
> > @@ -416,9 +432,23 @@ The struct canfd_frame is defined in include/linux/can.h:
> > __u8 flags; /* additional flags for CAN FD */
> > __u8 __res0; /* reserved / padding */
> > __u8 __res1; /* reserved / padding */
> > - __u8 data[64] __attribute__((aligned(8)));
> > + __u8 data[CANFD_MAX_DLEN] __attribute__((aligned(8)));
> > };
> >
> > +The following flag bits are defined for ``canfd_frame.flags``:
> > +
> > +.. code-block:: C
> > +
> > + #define CANFD_BRS 0x01 /* bit rate switch (second bitrate for payload data) */
> > + #define CANFD_ESI 0x02 /* error state indicator of the transmitting node */
> > + #define CANFD_FDF 0x04 /* mark CAN FD for dual use of struct canfd_frame */
> > +
> > +The use of ``struct canfd_frame`` implies the FD Frame (FDF) bit to be set
> > +on the wire. Since the introduction of CAN XL, the CANFD_FDF flag is set in
> > +all CAN FD frame structures provided by the CAN subsystem of the Linux
> > +kernel. Applications can use this flag to distinguish CAN FD content when
> > +``struct canfd_frame`` is used for mixed Classical CAN / CAN FD payload.
> > +
>
> Good.
>
> > The struct canfd_frame and the existing struct can_frame have the can_id,
> > the payload length and the payload data at the same offset inside their
> > structures. This allows to handle the different structures very similar.
> > @@ -432,16 +462,81 @@ the easy handling of the length information the canfd_frame.len element
> > contains a plain length value from 0 .. 64. So both canfd_frame.len and
> > can_frame.len are equal and contain a length information and no DLC.
> > For details about the distinction of CAN and CAN FD capable devices and
> > -the mapping to the bus-relevant data length code (DLC), see :ref:`socketcan-can-fd-driver`.
> > +the mapping to the bus-relevant data length code (DLC), see
> > +:ref:`socketcan-can-fd-driver`.
> >
> > The length of the two CAN(FD) frame structures define the maximum transfer
> > unit (MTU) of the CAN(FD) network interface and skbuff data length. Two
> > -definitions are specified for CAN specific MTUs in include/linux/can.h:
> > +definitions are specified for CAN specific MTUs in include/uapi/linux/can.h:
>
> No.
> From the user perspective he has to include include/linux/can.h
>
> Better "MTUs in the linux/can.h include file:"
>
Can I just incude linux/can.h or include/linux/can.h? As in the current
document include/linux/can.h is used.
> > +
> > +.. code-block:: C
> > +
> > + #define CAN_MTU (sizeof(struct can_frame)) /* Classical CAN frame */
> > + #define CANFD_MTU (sizeof(struct canfd_frame)) /* CAN FD frame */
> > +
> > +Remark about CAN XL (extended frame length) support:
> > +
> > +CAN XL extends the payload length beyond CAN FD. The UAPI defines the
> > +following constants for CAN XL payload and DLC according to ISO 11898-1:
> > +
> > +.. code-block:: C
> > +
> > + #define CANXL_MIN_DLC 0
> > + #define CANXL_MAX_DLC 2047
> > + #define CANXL_MAX_DLC_MASK 0x07FF
> > + #define CANXL_MIN_DLEN 1
> > + #define CANXL_MAX_DLEN 2048
> > +
> > +This means the CAN XL DLC ranges from 0 .. 2047 and maps to a data length
> > +range from 1 .. 2048 bytes. The CAN XL frame structure is defined as:
> >
> > .. code-block:: C
> >
> > - #define CAN_MTU (sizeof(struct can_frame)) == 16 => Classical CAN frame
> > - #define CANFD_MTU (sizeof(struct canfd_frame)) == 72 => CAN FD frame
> > + struct canxl_frame {
> > + canid_t prio; /* 11 bit priority for arbitration / 8 bit VCID */
> > + __u8 flags; /* additional flags for CAN XL */
> > + __u8 sdt; /* SDU (service data unit) type */
> > + __u16 len; /* frame payload length in byte */
> > + __u32 af; /* acceptance field */
> > + __u8 data[CANXL_MAX_DLEN];
> > + };
> > +
> > +The following flag bits are defined for ``canxl_frame.flags``:
> > +
> > +.. code-block:: C
> > +
> > + #define CANXL_XLF 0x80 /* mandatory CAN XL frame flag (must always be set!) */
> > + #define CANXL_SEC 0x01 /* Simple Extended Content (security/segmentation) */
> > + #define CANXL_RRS 0x02 /* Remote Request Substitution */
> > +
> > +The CANXL_XLF bit always needs to be set to indicate a valid CAN XL frame.
> > +Undefined bits in ``canxl_frame.flags`` are reserved and shall be set to
> > +zero. Setting CANXL_XLF intentionally breaks the length checks for Classical
>
> CAN CC
>
> > +CAN and CAN FD frames, which allows the stack to distinguish CAN XL frames
> > +from CAN(FD) traffic.
>
> CAN CC/FD traffic when analysing the received CAN content, e.g. from the
> CAN_RAW socket.
>
> > +
> > +The 8-bit VCID (Virtual CAN Network Identifier) is optionally placed in the
> > +prio element and is described by:
> > +
> > +.. code-block:: C
> > +
> > + #define CANXL_VCID_OFFSET 16
> > + #define CANXL_VCID_VAL_MASK 0xFFUL
> > + #define CANXL_VCID_MASK (CANXL_VCID_VAL_MASK << CANXL_VCID_OFFSET)
> > +
> > +The CAN XL MTU macros are:
> > +
> > +.. code-block:: C
> > +
> > + #define CANXL_MTU (sizeof(struct canxl_frame))
> > + #define CANXL_HDR_SIZE (offsetof(struct canxl_frame, data))
> > + #define CANXL_MIN_MTU (CANXL_HDR_SIZE + 64)
> > + #define CANXL_MAX_MTU CANXL_MTU
> > +
> > +Drivers for CAN XL-capable devices select an MTU in the inclusive range
> > +[CANXL_MIN_MTU, CANXL_MAX_MTU] depending on the maximum payload supported
> > +by the hardware. Applications should use CANXL_MTU and the related macros
> > +instead of hardcoding numerical values.
> >
> >
> > Returned Message Flags
> > @@ -490,7 +585,7 @@ RAW socket option CAN_RAW_FILTER
> > The reception of CAN frames using CAN_RAW sockets can be controlled
> > by defining 0 .. n filters with the CAN_RAW_FILTER socket option.
> >
> > -The CAN filter structure is defined in include/linux/can.h:
> > +The CAN filter structure is defined in include/uapi/linux/can.h:
>
> in the linux/can.h include file
>
> >
> > .. code-block:: C
> >
> > @@ -693,6 +788,10 @@ When sending to CAN devices make sure that the device is capable to handle
> > CAN FD frames by checking if the device maximum transfer unit is CANFD_MTU.
> > The CAN device MTU can be retrieved e.g. with a SIOCGIFMTU ioctl() syscall.
> >
> > +For CAN XL-capable devices, applications should additionally consider the
> > +MTU range [CANXL_MIN_MTU, CANXL_MAX_MTU] and use ``struct canxl_frame``
> > +when the corresponding protocol and socket semantics are available.
> > +
> >
> > RAW socket option CAN_RAW_JOIN_FILTERS
> > ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> > @@ -746,8 +845,9 @@ The broadcast manager sends responses to user space in the same form:
> > };
> >
> > The aligned payload 'frames' uses the same basic CAN frame structure defined
> > -at the beginning of :ref:`socketcan-rawfd` and in the include/linux/can.h include. All
>
> linux/can.h
>
> > -messages to the broadcast manager from user space have this structure.
> > +at the beginning of :ref:`socketcan-rawfd` and in the include/uapi/linux/can.h
>
> linux/can.h
>
> > +include. All messages to the broadcast manager from user space have this
> > +structure.
> >
> > Note a CAN_BCM socket must be connected instead of bound after socket
> > creation (example without error checking):
> > @@ -1072,7 +1172,7 @@ Writing Own CAN Protocol Modules
> > --------------------------------
> >
> > To implement a new protocol in the protocol family PF_CAN a new
> > -protocol has to be defined in include/linux/can.h .
> > +protocol has to be defined in include/uapi/linux/can.h .
>
> dito
>
> > The prototypes and definitions to use the SocketCAN core can be
> > accessed by including include/linux/can/core.h .
> > In addition to functions that register the CAN protocol and the
> > @@ -1111,8 +1211,9 @@ alloc_netdev_mqs(), to automatically take care of CAN-specific setup:
> >
> > dev = alloc_candev_mqs(...);
> >
> > -The struct can_frame or struct canfd_frame is the payload of each socket
> > -buffer (skbuff) in the protocol family PF_CAN.
> > +The struct can_frame, struct canfd_frame or struct canxl_frame is the payload
> > +of each socket buffer (skbuff) in the protocol family PF_CAN, depending on
> > +the device capabilities and the protocol in use.
> >
> >
> > .. _socketcan-local-loopback2:
> > @@ -1172,8 +1273,8 @@ Deactivate the terminating resistor::
> > To enable termination resistor support to a can-controller, either
> > implement in the controller's struct can-priv::
> >
> > - termination_const
> > termination_const_cnt
> > + termination_const
> > do_set_termination
> >
> > or add gpio control with the device tree entries from
> > @@ -1194,7 +1295,7 @@ so in common use cases more than one virtual CAN interface is needed.
> > The virtual CAN interfaces allow the transmission and reception of CAN
> > frames without real CAN controller hardware. Virtual CAN network
> > devices are usually named 'vcanX', like vcan0 vcan1 vcan2 ...
> > -When compiled as a module the virtual CAN driver module is called vcan.ko
> > +When compiled as a module, the virtual CAN driver module is called vcan.ko
> >
> > Since Linux Kernel version 2.6.24 the vcan driver supports the Kernel
> > netlink interface to create vcan network devices. The creation and
> > @@ -1237,52 +1338,164 @@ Setting CAN device properties::
> >
> > $ ip link set can0 type can help
> > 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 ] ]
> > -
> > - [ 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 } ]
> > -
> > - [ restart-ms TIME-MS ]
> > - [ restart ]
> > -
> > - Where: BITRATE := { 1..1000000 }
> > - SAMPLE-POINT := { 0.000..0.999 }
> > - TQ := { NUMBER }
> > - PROP-SEG := { 1..8 }
> > - PHASE-SEG1 := { 1..8 }
> > - PHASE-SEG2 := { 1..8 }
> > - SJW := { 1..4 }
> > - RESTART-MS := { 0 | NUMBER }
> > + [ 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 }
> > +
> > +Since IPROUTE2 version 6.18.0 the "ip" tool supports CAN XL devices
> > +and the following additional parameters.
> > +
> > +Setting CAN XL device properties::
> > +
> > + $ ip link set can0 type can help
> > + Usage: ip link set DEVICE type can
> > + ...
> > + [ xbitrate BITRATE [ xsample-point SAMPLE-POINT] ] |
> > + [ xtq TQ xprop-seg PROP_SEG xphase-seg1 PHASE-SEG1
> > + xphase-seg2 PHASE-SEG2 [ xsjw SJW ] ]
> > + [ xtdcv TDCV xtdco TDCO xtdcf TDCF pwms PWMS pwml PWML pwmo PWMO]
> > + ...
> > + [ restricted { on | off } ]
> > + [ xl { on | off } ]
> > + [ xtdc-mode { auto | manual | off } ]
> > + [ tms { on | off } ]
> > + ...
> > + Where:
> > + ...
> > + PWMS := { NUMBER in mtq }
> > + PWML := { NUMBER in mtq }
> > + PWMO := { NUMBER in mtq }
> > + RESTART-MS := { 0 | NUMBER in ms }
> > +
> > + Units:
> > + bps := bit per second
> > + ms := millisecond
> > + mtq := minimum time quanta
> > + ns := nanosecond
> > + tq := time quanta
> >
> > Display CAN device details and statistics::
> >
> > + $ ip link set can0 up type can bitrate 500000
> > +
> > + $ ip -details -statistics link show can0
> > + 2: can0: <NOARP,UP,LOWER_UP> mtu 16 qdisc pfifo_fast state UP mode DEFAULT group default qlen 10
> > + link/can promiscuity 0 allmulti 0 minmtu 16 maxmtu 16
> > + can state STOPPED restart-ms 0
> > + bitrate 500000 sample-point 0.875
> > + tq 12 prop-seg 69 phase-seg1 70 phase-seg2 20 sjw 10 brp 2
> > + dummy_can CC: tseg1 2..256 tseg2 2..128 sjw 1..128 brp 1..512 brp_inc 1
> > + dummy_can FD: dtseg1 2..256 dtseg2 2..128 dsjw 1..128 dbrp 1..512 dbrp_inc 1
> > + tdco 0..127 tdcf 0..127
> > + dummy_can XL: xtseg1 2..256 xtseg2 2..128 xsjw 1..128 xbrp 1..512 xbrp_inc 1
> > + xtdco 0..127 xtdcf 0..127
> > + pwms 1..8 pwml 2..24 pwmo 0..16
> > + termination 0 [ 0, 120 ]
> > + clock 160000000
> > + re-started bus-errors arbit-lost error-warn error-pass bus-off
> > + 0 0 0 0 0 0
> > + numtxqueues 1 numrxqueues 1 gso_max_size 65536 gso_max_segs 65535 tso_max_size 65536 \
> > + tso_max_segs 65535 gro_max_size 65536 gso_ipv4_max_size 65536 gro_ipv4_max_size 65536
> > + RX: bytes packets errors dropped missed mcast
> > + 0 0 0 0 0 0
> > + TX: bytes packets errors dropped carrier collsns
> > + 0 0 0 0 0 0
> > +
> > +Display CAN XL device details and statistics::
> > +
> > + $ ip link set can0 type can bitrate 1000000 dbitrate 2000000 fd on xbitrate 4000000 xl on
> > +
> > $ ip -details -statistics link show can0
> > - 2: can0: <NOARP,UP,LOWER_UP,ECHO> mtu 16 qdisc pfifo_fast state UP qlen 10
> > - link/can
> > - can <TRIPLE-SAMPLING> state ERROR-ACTIVE restart-ms 100
> > - bitrate 125000 sample_point 0.875
> > - tq 125 prop-seg 6 phase-seg1 7 phase-seg2 2 sjw 1
> > - sja1000: tseg1 1..16 tseg2 1..8 sjw 1..4 brp 1..64 brp-inc 1
> > - clock 8000000
> > - re-started bus-errors arbit-lost error-warn error-pass bus-off
> > - 41 17457 0 41 42 41
> > - RX: bytes packets errors dropped overrun mcast
> > - 140859 17608 17457 0 0 0
> > - TX: bytes packets errors dropped carrier collsns
> > - 861 112 0 41 0 0
> > + 3: can0: <NOARP,UP,LOWER_UP> mtu 2060 qdisc pfifo_fast state UP mode DEFAULT group default qlen 10
> > + link/can promiscuity 0 allmulti 0 minmtu 76 maxmtu 2060
> > + can <FD,TDC-AUTO,XL,XL-TDC-AUTO> state STOPPED restart-ms 0
> > + bitrate 1000000 sample-point 0.750
> > + tq 6 prop-seg 59 phase-seg1 60 phase-seg2 40 sjw 20 brp 1
> > + dummy_can CC: tseg1 2..256 tseg2 2..128 sjw 1..128 brp 1..512 brp_inc 1
> > + dbitrate 2000000 dsample-point 0.750
> > + dtq 6 dprop-seg 29 dphase-seg1 30 dphase-seg2 20 dsjw 10 dbrp 1
> > + tdco 60 tdcf 0
> > + dummy_can FD: dtseg1 2..256 dtseg2 2..128 dsjw 1..128 dbrp 1..512 dbrp_inc 1
> > + tdco 0..127 tdcf 0..127
> > + xbitrate 4000000 xsample-point 0.750
> > + xtq 6 xprop-seg 14 xphase-seg1 15 xphase-seg2 10 xsjw 5 xbrp 1
> > + xtdco 30 xtdcf 0
> > + dummy_can XL: xtseg1 2..256 xtseg2 2..128 xsjw 1..128 xbrp 1..512 xbrp_inc 1
> > + xtdco 0..127 xtdcf 0..127
> > + pwms 1..8 pwml 2..24 pwmo 0..16
> > + termination 0 [ 0, 120 ]
> > + clock 160000000
> > + re-started bus-errors arbit-lost error-warn error-pass bus-off
> > + 0 0 0 0 0 0
> > + addrgenmode eui64 numtxqueues 1 numrxqueues 1 gso_max_size 65536 gso_max_segs 65535 \
> > + tso_max_size 65536 tso_max_segs 65535 gro_max_size 65536 gso_ipv4_max_size 65536 gro_ipv4_max_size 65536
> > + RX: bytes packets errors dropped missed mcast
> > + 0 0 0 0 0 0
> > + TX: bytes packets errors dropped carrier collsns
> > + 0 0 0 49 0 0
> > +
> > +Display CAN XL with TMS device details and statistics::
>
> Display CAN XL-only device details and statistics (TMS mode)::
>
> > +
> > + $ ip link set can0 type can bitrate 1000000 xbitrate 12308000 xl on tms on fd off
> > +
> > + $ ip -details -statistics link show can0
> > + 3: can0: <NOARP,UP,LOWER_UP> mtu 2060 qdisc pfifo_fast state UP mode DEFAULT group default qlen 10
> > + link/can promiscuity 0 allmulti 0 minmtu 76 maxmtu 2060
> > + can <XL,TMS> state STOPPED restart-ms 0
> > + bitrate 1000000 sample-point 0.750
> > + tq 6 prop-seg 59 phase-seg1 60 phase-seg2 40 sjw 20 brp 1
> > + dummy_can CC: tseg1 2..256 tseg2 2..128 sjw 1..128 brp 1..512 brp_inc 1
> > + dummy_can FD: dtseg1 2..256 dtseg2 2..128 dsjw 1..128 dbrp 1..512 dbrp_inc 1
> > + tdco 0..127 tdcf 0..127
> > + xbitrate 12307692 xsample-point 0.538
> > + xtq 6 xprop-seg 3 xphase-seg1 3 xphase-seg2 6 xsjw 3 xbrp 1
> > + pwms 4 pwml 9 pwmo 4
> > + dummy_can XL: xtseg1 2..256 xtseg2 2..128 xsjw 1..128 xbrp 1..512 xbrp_inc 1
> > + xtdco 0..127 xtdcf 0..127
> > + pwms 1..8 pwml 2..24 pwmo 0..16
> > + termination 0 [ 0, 120 ]
> > + clock 160000000
> > + re-started bus-errors arbit-lost error-warn error-pass bus-off
> > + 0 0 0 0 0 0
> > + addrgenmode eui64 numtxqueues 1 numrxqueues 1 gso_max_size 65536 gso_max_segs 65535 \
> > + tso_max_size 65536 tso_max_segs 65535 gro_max_size 65536 gso_ipv4_max_size 65536 gro_ipv4_max_size 65536
> > + RX: bytes packets errors dropped missed mcast
> > + 0 0 0 0 0 0
> > + TX: bytes packets errors dropped carrier collsns
> > + 0 0 0 0 0 0
> >
> > More info to the above output:
> >
> > @@ -1445,19 +1658,23 @@ Example configuring 500 kbit/s arbitration bitrate and 4 Mbit/s data bitrate::
> > $ ip link set can0 up type can bitrate 500000 sample-point 0.75 \
> > dbitrate 4000000 dsample-point 0.8 fd on
> > $ ip -details link show can0
> > - 5: can0: <NOARP,UP,LOWER_UP,ECHO> mtu 72 qdisc pfifo_fast state UNKNOWN \
> > - mode DEFAULT group default qlen 10
> > - link/can promiscuity 0
> > - can <FD> state ERROR-ACTIVE (berr-counter tx 0 rx 0) restart-ms 0
> > - bitrate 500000 sample-point 0.750
> > - tq 50 prop-seg 14 phase-seg1 15 phase-seg2 10 sjw 1
> > - pcan_usb_pro_fd: tseg1 1..64 tseg2 1..16 sjw 1..16 brp 1..1024 \
> > - brp-inc 1
> > - dbitrate 4000000 dsample-point 0.800
> > - dtq 12 dprop-seg 7 dphase-seg1 8 dphase-seg2 4 dsjw 1
> > - pcan_usb_pro_fd: dtseg1 1..16 dtseg2 1..8 dsjw 1..4 dbrp 1..1024 \
> > - dbrp-inc 1
> > - clock 80000000
> > + 3: can0: <NOARP,UP,LOWER_UP> 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 STOPPED restart-ms 0
> > + bitrate 500000 sample-point 0.750
> > + tq 6 prop-seg 119 phase-seg1 120 phase-seg2 80 sjw 40 brp 1
> > + dummy_can CC: tseg1 2..256 tseg2 2..128 sjw 1..128 brp 1..512 brp_inc 1
> > + dbitrate 4000000 dsample-point 0.800
> > + dtq 6 dprop-seg 15 dphase-seg1 16 dphase-seg2 8 dsjw 4 dbrp 1
> > + tdco 32 tdcf 0
> > + dummy_can FD: dtseg1 2..256 dtseg2 2..128 dsjw 1..128 dbrp 1..512 dbrp_inc 1
> > + tdco 0..127 tdcf 0..127
> > + dummy_can XL: xtseg1 2..256 xtseg2 2..128 xsjw 1..128 xbrp 1..512 xbrp_inc 1
> > + xtdco 0..127 xtdcf 0..127
> > + pwms 1..8 pwml 2..24 pwmo 0..16
> > + termination 0 [ 0, 120 ]
> > + clock 160000000 numtxqueues 1 numrxqueues 1 gso_max_size 65536 gso_max_segs 65535 \
> > + tso_max_size 65536 tso_max_segs 65535 gro_max_size 65536 gso_ipv4_max_size 65536 gro_ipv4_max_size 65536
> >
> > Example when 'fd-non-iso on' is added on this switchable CAN FD adapter::
> >
> > @@ -1508,24 +1725,228 @@ 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
> > + 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
> > + 3: can0: <NOARP,UP,LOWER_UP> 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
> > + can <FD,TDC-AUTO> state STOPPED restart-ms 0
> > + bitrate 500000 sample-point 0.875
> > + tq 12 prop-seg 69 phase-seg1 70 phase-seg2 20 sjw 10 brp 2
> > + dummy_can CC: tseg1 2..256 tseg2 2..128 sjw 1..128 brp 1..512 brp_inc 1
> > + dbitrate 4000000 dsample-point 0.750
> > + dtq 6 dprop-seg 14 dphase-seg1 15 dphase-seg2 10 dsjw 5 dbrp 1
> > + tdco 15 tdcf 0
> > + dummy_can FD: dtseg1 2..256 dtseg2 2..128 dsjw 1..128 dbrp 1..512 dbrp_inc 1
> > + tdco 0..127 tdcf 0..127
> > + dummy_can XL: xtseg1 2..256 xtseg2 2..128 xsjw 1..128 xbrp 1..512 xbrp_inc 1
> > + xtdco 0..127 xtdcf 0..127
> > + pwms 1..8 pwml 2..24 pwmo 0..16
> > + termination 0 [ 0, 120 ]
> > + clock 160000000 numtxqueues 1 numrxqueues 1 gso_max_size 65536 gso_max_segs 65535 \
> > + tso_max_size 65536 tso_max_segs 65535 gro_max_size 65536 gso_ipv4_max_size 65536 gro_ipv4_max_size 65536
> > +
> > +
> > +.. _socketcan-can-xl-driver:
> > +
> > +CAN XL (Extended Frame Length) Driver Support
> > +---------------------------------------------
> > +
> > +CAN XL extends the CAN protocol family with support for payloads up to
> > +2048 bytes and additional header fields for service data unit (SDU)
> > +typing, security/segmentation and virtual channel identification (VCID).
>
> service data unit type (SDT), simple extended content (SEC) and virtual
> CAN identifier (VCID).
>
> > +These extensions enable more flexible and higher-bandwidth communication
> > +compared to Classical CAN and CAN FD.
>
> CAN CC and CAN FD.
>
> > +
> > +The CAN XL netdevice driver capabilities can be distinguished by the network
> > +devices maximum transfer unit (MTU)::
> > +
> > + Minimum MTU: CANXL_MIN_MTU (supports at least 64 bytes of payload)
> > + Maximum MTU: CANXL_MAX_MTU (supports up to 2048 bytes of payload)
> > +
> > +The MTU can be queried using SIOCGIFMTU, just like with Classical CAN and CAN FD.
> > +In a typical configuration you may see, for
> > +
> > +Example::
> > +
> > + can0: MTU: 2060
> > +
> > +This corresponds to a CAN XL frame with 2048 bytes of payload (plus protocol overhead).
> > +
> > +Configuring CAN XL bitrates and modes
> > +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> > +
> > +Similar to the existing "bitrate" and "dbitrate" parameters used for
> > +Classical CAN
>
> CAN CC
>
> > and CAN FD, CAN XL introduces a separate "xbitrate" used
> > +for the CAN XL data phase. In addition, CAN XL capable controllers can
> > +be configured in different operating modes:
> > +
> > +- Classical CAN / CAN FD / CAN XL mixed mode
> > +- CAN XL-only mode
> > +- Optional Transceiver Mode Switching (TMS) when supported
> > +
> > +Examples (assuming ``can0`` is a CAN XL capable interface, e.g. provided
> > +by the dummy_can driver):
>
> # modprobe dummy_can
> > +
> > +Mixed Classical CAN / FD / XL mode with CAN XL enabled and TMS disabled::
> > +
> > + # ip link set can0 type can bitrate 1000000 dbitrate 2000000 fd on \
> > + xbitrate 4000000 xl on
> > +
> > +CAN XL-only mode with TMS enabled and CAN FD disabled::
> > +
> > + # ip link set can0 type can bitrate 1000000 xbitrate 12308000 xl on \
> > + tms on fd off
> > +
> > +Enable the debugging to see the output in dmesg::
> > +
> > + # echo 'file drivers/net/can/dummy_can.c +p' > /sys/kernel/debug/dynamic_debug/control
> > +
> > +After setting the interface up with::
> > +
> > + # ip link set can0 up
> > +
> > +the controller configuration can be inspected in the kernel log, for
> > +example::
> > +
> > + can0: Clock frequency: 160000000
> > + can0: Maximum bitrate: 20000000
> > + can0: MTU: 2060
> > + can0:
> > + can0: Control modes:
> > + can0: supported: 0x0000ba2
> > + can0: enabled: 0x00003220
> > + can0: list:
> > + can0: LISTEN-ONLY: off
> > + can0: FD: on
> > + can0: TDC-AUTO: on
> > + can0: RESTRICTED: off
> > + can0: XL: on
> > + can0: XL-TDC-AUTO: on
> > + can0: TMS: off
> > + can0:
> > + can0: Classical CAN nominal bittiming:
> > + can0: bitrate: 1000000
> > + ...
> > + can0: CAN FD databittiming:
> > + can0: bitrate: 2000000
> > + ...
> > + can0: CAN FD TDC:
> > + ...
> > + can0:
> > + can0: CAN XL databittiming:
> > + can0: bitrate: 4000000
> > + can0: sample_point: 750
> > + can0: tq: 6
> > + can0: prop_seg: 14
> > + can0: phase_seg1: 15
> > + can0: phase_seg2: 10
> > + can0: sjw: 5
> > + can0: brp: 1
> > + can0: CAN XL TDC:
> > + can0: tdcv: 0
> > + can0: tdco: 30
> > + can0: tdcf: 0
> > + can0:
> > + can0: error-signalling is enabled
> > + can0: dummy-can is up
> > +
> > +This shows:
> > +
> > +- the configured MTU (here 2060, i.e. CANXL_MTU),
> > +- which control modes are enabled (FD, XL, XL-TDC-AUTO, TMS, etc.),
> > +- separate bit-timing blocks for Classical CAN, CAN FD and CAN XL, and
> > +- separate TDC information for CAN FD and CAN XL.
> > +
> > +Error Signalling Behaviour in CAN CC, CAN FD and CAN XL
> > +-------------------------------------------------------
> > +
> > +Classical CAN (CC)
>
> CAN CC
>
> > and CAN FD controllers implement mandatory
> > +error-signalling (ES) to report protocol and frame format violations
> > +by transmitting an error frame on the bus.
> > +
> > +With the introduction of CAN XL two operational models exist:
> > +
> > +* **Mixed-mode**: A CAN segment contains XL-tolerant CAN FD nodes and
> > + CAN XL nodes. In this mode the FD controllers may transmit CC/FD
> > + frames, while XL controllers may transmit CC/FD/XL frames. Error
> > + signalling remains enabled and is used consistently across all frame
> > + types.
> > +
> > +* **CANXL-only mode**:
>
> (move this sentence)
>
I didn't understand this. Shall I move the **CANXL-only mode** heading
to before the previous paragraph (**Mixed-mode**)?
> > + This mode allows transmission of CAN XL frames only and additionally
> > + supports the optional Transceiver Mode Switching (TMS).
>
> when CAN XL transceiver hardware is attached to the CAN XL controller.
>
> > CC and FD
> > + frames must not be sent in this mode.
>
> CAN CC and CAN FD frame cannot be sent in this mode.
>
> In the CANXL-only mode the CAN XL controller disables error-signalling.
>
> > +
> > +The operational mode is derived from the controller flags
> > +``CAN_CTRLMODE_FD`` and ``CAN_CTRLMODE_XL``:
> > +
> > ++---------+---------+---------------------------+-------+----------------------------+
> > +| FD | XL | Mode | ES | Notes |
> > ++=========+=========+===========================+=======+============================+
> > +| 0 | 0 | CC-only | 1 | Classical CAN |
> > ++---------+---------+---------------------------+-------+----------------------------+
> > +| 1 | 0 | FD/CC mixed-mode | 1 | Standard CAN FD operation |
> > ++---------+---------+---------------------------+-------+----------------------------+
> > +| 1 | 1 | XL/FD/CC mixed-mode | 1 | All frame types allowed |
> > ++---------+---------+---------------------------+-------+----------------------------+
> > +| 0 | 1 | CANXL-only | 0 | XL-only; TMS optional |
> > ++---------+---------+---------------------------+-------+----------------------------+
>
> Nice table!
>
> > +
> > +Note about error-signalling
> > +---------------------------
> > +
> > +The error-signalling behaviour is derived automatically from the selected
> > +mixed-mode or CANXL-only configuration
>
> "."
>
> > and is no longer controlled by an
> > +explicit netlink attribute.
>
> It was never in an official API so this part of the sentence can be removed.
>
> > +
> > +The effective state can be observed in the kernel log, for example::
>
> With the enabled debug output the error-signalling state of the
> dummy_can driver can be observed in the kernel log:
>
> > +
> > + can0: error-signalling is enabled
> > +
>
> > +Applications should rely on the controller mode and driver output rather
> > +than on an explicit ``err-signal`` configuration switch.
>
> remove this too
>
> > +
> > +CAN XL TDC (Transmitter Delay Compensation)
> > +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> > +
> > +Similar to CAN FD, the high data phase bitrates in CAN XL may require
> > +Transmitter Delay Compensation. CAN XL capable controllers can provide
> > +an XL-specific TDC configuration and may support an automatic mode.
> > +
> > +If supported by the device, the XL TDC settings (TDCV/TDCO/TDCF) are
> > +reported in the "CAN XL TDC" section in the kernel log, for example::
> > +
> > + can0: CAN XL TDC:
> > + can0: tdcv: 0
> > + can0: tdco: 30
> > + can0: tdcf: 0
> > +
> > +The precise netlink attributes and the corresponding "ip" options for
> > +XL TDC are controller specific and follow the same design as CAN FD TDC
> > +where possible. Users should consult the device driver documentation
> > +and the output of::
> > +
> > + $ ip -details link show can0
> > +
> > +for details on XL TDC support.
> > +
>
> What about the PWM settings here?
> When TMS is "on" the PWM values can be automatically calculated or set
> manually. There's also no CAN XL TDC when TMS=on as the TDC is a
> mixed-mode requirement for non-TMS transceivers.
>
Can I add the PWM settings under new heading (CAN XL PWM) or is it fine
to keep the content under the same heading (CAN XL TDC)?
> > +Application considerations for CAN XL
> > +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> > +
> > +For user space applications the following rules are important when
> > +handling CAN XL:
> > +
> > +- Use ``struct canxl_frame`` as basic data structure when CAN XL traffic
> > + is expected.
> > +- Set CANXL_XLF in ``canxl_frame.flags`` for all valid CAN XL frames.
> > +- Ensure that undefined bits in ``canxl_frame.flags`` are kept at zero.
> > +- Respect the configured device MTU; do not send frames larger than
> > + the MTU announced by the kernel.
> > +- For mixed-mode controllers, be prepared to handle Classical CAN,
> > + CAN FD and CAN XL frames on the same interface and choose the frame
> > + structure according to the socket/protocol semantics (e.g. dedicated
> > + CAN XL APIs when available).
>
> There's one big difference between CC/FD and XL frames when you
> read/write it to CAN_RAW sockets:
>
> For CAN CC and CAN FD you write struct can(fd)_frame's with CAN_MTU
> resp. CANFD_MTU lengths - no matter about the data length (cf->len).
>
> When you read/write CAN XL frames you are reading and writing the
> CANXL_HDR_SIZE + the length of the data.
>
> So only in the case of writing 2048 byte data, you write 2060 bytes.
>
> The minimum size for read/write is CANXL_HDR_SIZE + CANXL_MIN_DLEN == 13
>
Good point! I will add this information along with an example. I will go
through your code and decide what to add. Does the example code should
focus only on CAN XL frames or also on CC/FD frames?
On Wed, 14 Jan 2026 at 22:26, Oliver Hartkopp <socketcan@...tkopp.net> wrote:
>
> Hello Rakuram,
>
> On 13.01.26 17:14, Oliver Hartkopp wrote:
>
> >> +For user space applications the following rules are important when
> >> +handling CAN XL:
> >> +
> >> +- Use ``struct canxl_frame`` as basic data structure when CAN XL traffic
> >> + is expected.
> >> +- Set CANXL_XLF in ``canxl_frame.flags`` for all valid CAN XL frames.
> >> +- Ensure that undefined bits in ``canxl_frame.flags`` are kept at zero.
> >> +- Respect the configured device MTU; do not send frames larger than
> >> + the MTU announced by the kernel.
> >> +- For mixed-mode controllers, be prepared to handle Classical CAN,
> >> + CAN FD and CAN XL frames on the same interface and choose the frame
> >> + structure according to the socket/protocol semantics (e.g. dedicated
> >> + CAN XL APIs when available).
> >
> > There's one big difference between CC/FD and XL frames when you read/
> > write it to CAN_RAW sockets:
> >
> > For CAN CC and CAN FD you write struct can(fd)_frame's with CAN_MTU
> > resp. CANFD_MTU lengths - no matter about the data length (cf->len).
> >
> > When you read/write CAN XL frames you are reading and writing the
> > CANXL_HDR_SIZE + the length of the data.
> >
> > So only in the case of writing 2048 byte data, you write 2060 bytes.
> >
> > The minimum size for read/write is CANXL_HDR_SIZE + CANXL_MIN_DLEN == 13
> >
>
> Here is an example that I've been implemented recently that shows a good
> example how to handle CC/FD/XL frames, when they are all enabled on the
> CAN_RAW socket:
>
> https://github.com/hartkopp/can-utils/commit/bf0cae218af9b1c1f5eabad7f3704b88ab642e00
>
> Feel free to pick the code for some example.
>
> But please do not reference the commit as it is in my private repo and
> not yet integrated in the official can-utils repo.
>
Best Regards,
Rakuram.
Powered by blists - more mailing lists