ISO 15765-2 (ISO-TP)

규격, addressing과 frame 흐름

ISO-TP는 CAN 진단 통신용 transport protocol로 UDSonCAN과 배출가스 진단에 널리 쓰입니다. Classical CAN과 CAN FD에서 모두 동작하고 SAE J1939 data link와도 호환되도록 설계되었습니다. 문서는 ISO 15765-2:2024를 기준으로 합니다.

physical addressing은 node별 TX/RX address 두 개를 써 1:1 통신하고 functional addressing은 node-specific address 하나로 1:N 통신합니다. normal format은 CAN ID만, extended는 CAN ID와 payload 첫 byte를 모두 서로 다르게, mixed는 CAN ID는 다르지만 추가 byte는 같게 사용합니다.

payload가 한 CAN message에 들어가면 Single Frame으로 보냅니다. 더 크면 sender가 First Frame으로 PDU length를 알리고 receiver가 Flow Control의 `blocksize`와 `stmin`을 답합니다. sender는 Consecutive Frame을 `blocksize`만큼 보낸 뒤 다음 FC를 기다립니다.

.. SPDX-License-Identifier: (GPL-2.0 OR BSD-3-Clause)

====================
ISO 15765-2 (ISO-TP)
====================

Overview
========

ISO 15765-2, also known as ISO-TP, is a transport protocol specifically defined
for diagnostic communication on CAN. It is widely used in the automotive
industry, for example as the transport protocol for UDSonCAN (ISO 14229-3) or
emission-related diagnostic services (ISO 15031-5).

ISO-TP can be used both on CAN CC (aka Classical CAN) and CAN FD (CAN with
Flexible Datarate) based networks. It is also designed to be compatible with a
CAN network using SAE J1939 as data link layer (however, this is not a
requirement).

Specifications used
-------------------

* ISO 15765-2:2024 : Road vehicles - Diagnostic communication over Controller
  Area Network (DoCAN). Part 2: Transport protocol and network layer services.

Addressing
----------

In its simplest form, ISO-TP is based on two kinds of addressing modes for the
nodes connected to the same network:

* physical addressing is implemented by two node-specific addresses and is used
  in 1-to-1 communication.

* functional addressing is implemented by one node-specific address and is used
  in 1-to-N communication.

Three different addressing formats can be employed:

* "normal" : each address is represented simply by a CAN ID.

* "extended": each address is represented by a CAN ID plus the first byte of
  the CAN payload; both the CAN ID and the byte inside the payload shall be
  different between two addresses.

* "mixed": each address is represented by a CAN ID plus the first byte of
  the CAN payload; the CAN ID is different between two addresses, but the
  additional byte is the same.

Transport protocol and associated frame types
---------------------------------------------

When transmitting data using the ISO-TP protocol, the payload can either fit
inside one single CAN message or not, also considering the overhead the protocol
is generating and the optional extended addressing. In the first case, the data
is transmitted at once using a so-called Single Frame (SF). In the second case,
ISO-TP defines a multi-frame protocol, in which the sender provides (through a
First Frame - FF) the PDU length which is to be transmitted and also asks for a
Flow Control (FC) frame, which provides the maximum supported size of a macro
data block (``blocksize``) and the minimum time between the single CAN messages
composing such block (``stmin``). Once this information has been received, the
sender starts to send frames containing fragments of the data payload (called
Consecutive Frames - CF), stopping after every ``blocksize``-sized block to wait
confirmation from the receiver which should then send another Flow Control
frame to inform the sender about its availability to receive more data.

Socket 생성, bind와 payload I/O

Linux ISO-TP는 SocketCAN에 포함되며 `<linux/can/isotp.h>`를 include하고 `socket(PF_CAN, SOCK_DGRAM, CAN_ISOTP)`로 만듭니다. `bind(2)`에는 CAN interface와 TX CAN ID를 주며 broadcast option이 없으면 RX CAN ID도 지정합니다.

bind 후 `read`, `write`, `send`, `sendmsg`, `recv`, `recvmsg`를 씁니다. CAN_RAW와 달리 application은 ISO-TP payload만 주고받고 address와 protocol field, CAN MTU를 넘을 때의 transport segmentation은 stack이 처리합니다.

`sockaddr_can.can_ifindex`는 interface, `can_addr.tp.rx_id`는 receive filter가 될 RX CAN ID, `can_addr.tp.tx_id`는 transmit CAN ID입니다.

How to Use ISO-TP
=================

As with others CAN protocols, the ISO-TP stack support is built into the
Linux network subsystem for the CAN bus, aka. Linux-CAN or SocketCAN, and
thus follows the same socket API.

Creation and basic usage of an ISO-TP socket
--------------------------------------------

To use the ISO-TP stack, ``#include <linux/can/isotp.h>`` shall be used. A
socket can then be created using the ``PF_CAN`` protocol family, the
``SOCK_DGRAM`` type (as the underlying protocol is datagram-based by design)
and the ``CAN_ISOTP`` protocol:

.. code-block:: C

    s = socket(PF_CAN, SOCK_DGRAM, CAN_ISOTP);

After the socket has been successfully created, ``bind(2)`` shall be called to
bind the socket to the desired CAN interface; to do so:

* a TX CAN ID shall be specified as part of the sockaddr supplied to the call
  itself.

* a RX CAN ID shall also be specified, unless broadcast flags have been set
  through socket option (explained below).

Once bound to an interface, the socket can be read from and written to using
the usual ``read(2)`` and ``write(2)`` system calls, as well as ``send(2)``,
``sendmsg(2)``, ``recv(2)`` and ``recvmsg(2)``.
Unlike the CAN_RAW socket API, only the ISO-TP data field (the actual payload)
is sent and received by the userspace application using these calls. The address
information and the protocol information are automatically filled by the ISO-TP
stack using the configuration supplied during socket creation. In the same way,
the stack will use the transport mechanism when required (i.e., when the size
of the data payload exceeds the MTU of the underlying CAN bus).

The sockaddr structure used for SocketCAN has extensions for use with ISO-TP,
as specified below:

.. code-block:: C

    struct sockaddr_can {
        sa_family_t can_family;
        int         can_ifindex;
        union {
            struct { canid_t rx_id, tx_id; } tp;
        ...
        } can_addr;
    }

* ``can_family`` and ``can_ifindex`` serve the same purpose as for other
  SocketCAN sockets.

* ``can_addr.tp.rx_id`` specifies the receive (RX) CAN ID and will be used as
  a RX filter.

* ``can_addr.tp.tx_id`` specifies the transmit (TX) CAN ID

일반 ISO-TP socket option

`CAN_ISOTP_OPTS`의 `can_isotp_options`는 `flags`, frame transmission time, extended address, TX/RX padding byte와 receive extended address를 담습니다. `CAN_ISOTP_LISTEN_MODE`는 FC를 보내지 않는 test용 listen-only, `CAN_ISOTP_EXTEND_ADDR`는 추가 address byte를 켜 mixed format을 사용하며 RX flag와 함께 쓰면 extended format입니다.

TX/RX padding flag는 지정 byte로 padding하고 `CAN_ISOTP_CHK_PAD_LEN`과 `CAN_ISOTP_CHK_PAD_DATA`는 수신 길이와 값을 검증합니다. `CAN_ISOTP_HALF_DUPLEX`는 동시에 한 방향 transport만 허용합니다. FORCE_TXSTMIN과 FORCE_RXSTMIN은 FC 또는 incoming CF timing을 무시하는 test 기능입니다. `CAN_ISOTP_RX_EXT_ADDR`는 RX path에 별도 `rx_ext_address`를 씁니다.

`CAN_ISOTP_WAIT_TX_DONE`은 `write`/`send`가 실제 frame 송신까지 기다리게 합니다. `CAN_ISOTP_SF_BROADCAST`는 Single Frame 1:N functional addressing, `CAN_ISOTP_CF_BROADCAST`는 표준 밖의 flow-control 없는 multi-frame 1:N이며 둘을 같이 쓸 수 없습니다. `CAN_ISOTP_DYN_FC_PARMS`는 FC parameter의 동적 갱신을 허용합니다.

`frame_txtime`은 N_As/N_Ar이며 0은 기존값을 유지하고 실제 0을 설정하려면 값 0xffffffff인 `CAN_ISOTP_FRAME_TXTIME_ZERO`를 써야 합니다. 나머지 field는 TX/RX extended address와 padding byte를 제공합니다.

ISO-TP socket options
---------------------

When creating an ISO-TP socket, reasonable defaults are set. Some options can
be modified with ``setsockopt(2)`` and/or read back with ``getsockopt(2)``.

General options
~~~~~~~~~~~~~~~

General socket options can be passed using the ``CAN_ISOTP_OPTS`` optname:

.. code-block:: C

    struct can_isotp_options opts;
    ret = setsockopt(s, SOL_CAN_ISOTP, CAN_ISOTP_OPTS, &opts, sizeof(opts))

where the ``can_isotp_options`` structure has the following contents:

.. code-block:: C

    struct can_isotp_options {
        u32 flags;
        u32 frame_txtime;
        u8  ext_address;
        u8  txpad_content;
        u8  rxpad_content;
        u8  rx_ext_address;
    };

* ``flags``: modifiers to be applied to the default behaviour of the ISO-TP
  stack. Following flags are available:

  * ``CAN_ISOTP_LISTEN_MODE``: listen only (do not send FC frames); normally
    used as a testing feature.

  * ``CAN_ISOTP_EXTEND_ADDR``: use the byte specified in ``ext_address`` as an
    additional address component. This enables the "mixed" addressing format if
    used alone, or the "extended" addressing format if used in conjunction with
    ``CAN_ISOTP_RX_EXT_ADDR``.

  * ``CAN_ISOTP_TX_PADDING``: enable padding for transmitted frames, using
    ``txpad_content`` as value for the padding bytes.

  * ``CAN_ISOTP_RX_PADDING``: enable padding for the received frames, using
    ``rxpad_content`` as value for the padding bytes.

  * ``CAN_ISOTP_CHK_PAD_LEN``: check for correct padding length on the received
    frames.

  * ``CAN_ISOTP_CHK_PAD_DATA``: check padding bytes on the received frames
    against ``rxpad_content``; if ``CAN_ISOTP_RX_PADDING`` is not specified,
    this flag is ignored.

  * ``CAN_ISOTP_HALF_DUPLEX``: force ISO-TP socket in half duplex mode
    (that is, transport mechanism can only be incoming or outgoing at the same
    time, not both).

  * ``CAN_ISOTP_FORCE_TXSTMIN``: ignore stmin from received FC; normally
    used as a testing feature.

  * ``CAN_ISOTP_FORCE_RXSTMIN``: ignore CFs depending on rx stmin; normally
    used as a testing feature.

  * ``CAN_ISOTP_RX_EXT_ADDR``: use ``rx_ext_address`` instead of ``ext_address``
    as extended addressing byte on the reception path. If used in conjunction
    with ``CAN_ISOTP_EXTEND_ADDR``, this flag effectively enables the "extended"
    addressing format.

  * ``CAN_ISOTP_WAIT_TX_DONE``: wait until the frame is sent before returning
    from ``write(2)`` and ``send(2)`` calls (i.e., blocking write operations).

  * ``CAN_ISOTP_SF_BROADCAST``: use 1-to-N functional addressing (cannot be
    specified alongside ``CAN_ISOTP_CF_BROADCAST``).

  * ``CAN_ISOTP_CF_BROADCAST``: use 1-to-N transmission without flow control
    (cannot be specified alongside ``CAN_ISOTP_SF_BROADCAST``).
    NOTE: this is not covered by the ISO 15765-2 standard.

  * ``CAN_ISOTP_DYN_FC_PARMS``: enable dynamic update of flow control
    parameters.

* ``frame_txtime``: frame transmission time (defined as N_As/N_Ar inside the
  ISO standard); if ``0``, the default (or the last set value) is used.
  To set the transmission time to ``0``, the ``CAN_ISOTP_FRAME_TXTIME_ZERO``
  macro (equal to 0xFFFFFFFF) shall be used.

* ``ext_address``: extended addressing byte, used if the
  ``CAN_ISOTP_EXTEND_ADDR`` flag is specified.

* ``txpad_content``: byte used as padding value for transmitted frames.

* ``rxpad_content``: byte used as padding value for received frames.

* ``rx_ext_address``: extended addressing byte for the reception path, used if
  the ``CAN_ISOTP_RX_EXT_ADDR`` flag is specified.

Flow Control option

`CAN_ISOTP_RECV_FC`로 receiver가 보낼 FC parameter를 설정합니다. `bs`는 block size, `stmin`은 CF 사이 최소 간격, `wftmax`는 최대 wait frame 수입니다. `stmin` 0x00~0x7f는 0~127 ms, 0xf1~0xf9는 100~900 us이고 다른 값은 예약입니다.

Flow Control options
~~~~~~~~~~~~~~~~~~~~

Flow Control (FC) options can be passed using the ``CAN_ISOTP_RECV_FC`` optname
to provide the communication parameters for receiving ISO-TP PDUs.

.. code-block:: C

    struct can_isotp_fc_options fc_opts;
    ret = setsockopt(s, SOL_CAN_ISOTP, CAN_ISOTP_RECV_FC, &fc_opts, sizeof(fc_opts));

where the ``can_isotp_fc_options`` structure has the following contents:

.. code-block:: C

    struct can_isotp_options {
        u8 bs;
        u8 stmin;
        u8 wftmax;
    };

* ``bs``: blocksize provided in flow control frames.

* ``stmin``: minimum separation time provided in flow control frames; can
  have the following values (others are reserved):

  * 0x00 - 0x7F : 0 - 127 ms

  * 0xF1 - 0xF9 : 100 us - 900 us

* ``wftmax``: maximum number of wait frames provided in flow control frames.

Link layer와 강제 separation time

`CAN_ISOTP_LL_OPTS`의 `mtu`는 Classical CAN용 `CAN_MTU` 또는 CAN FD용 `CANFD_MTU`입니다. `tx_dl`은 transmit frame의 최대 payload 길이로 8, 12, 16, 20, 24, 32, 48, 64 중 하나이며 8 초과는 CAN FD에서만 유효합니다. `tx_flags`도 CAN FD frame 생성 때 `canfd_frame.flags`에 넣습니다.

`CAN_ISOTP_TX_STMIN`은 microsecond 단위 u32로 sender의 separation time을 강제해 receiver FC 값을 override합니다. `CAN_ISOTP_RX_STMIN`은 receive 측 최소 간격을 강제하고 timestamp 차이가 이 값보다 작은 Consecutive Frame을 무시합니다.

Link Layer options
~~~~~~~~~~~~~~~~~~

Link Layer (LL) options can be passed using the ``CAN_ISOTP_LL_OPTS`` optname:

.. code-block:: C

    struct can_isotp_ll_options ll_opts;
    ret = setsockopt(s, SOL_CAN_ISOTP, CAN_ISOTP_LL_OPTS, &ll_opts, sizeof(ll_opts));

where the ``can_isotp_ll_options`` structure has the following contents:

.. code-block:: C

    struct can_isotp_ll_options {
        u8 mtu;
        u8 tx_dl;
        u8 tx_flags;
    };

* ``mtu``: generated and accepted CAN frame type, can be equal to ``CAN_MTU``
  for classical CAN frames or ``CANFD_MTU`` for CAN FD frames.

* ``tx_dl``: maximum payload length for transmitted frames, can have one value
  among: 8, 12, 16, 20, 24, 32, 48, 64. Values above 8 only apply to CAN FD
  traffic (i.e.: ``mtu = CANFD_MTU``).

* ``tx_flags``: flags set into ``struct canfd_frame.flags`` at frame creation.
  Only applies to CAN FD traffic (i.e.: ``mtu = CANFD_MTU``).

Transmission stmin
~~~~~~~~~~~~~~~~~~

The transmission minimum separation time (stmin) can be forced using the
``CAN_ISOTP_TX_STMIN`` optname and providing an stmin value in microseconds as
a 32bit unsigned integer; this will overwrite the value sent by the receiver in
flow control frames:

.. code-block:: C

    uint32_t stmin;
    ret = setsockopt(s, SOL_CAN_ISOTP, CAN_ISOTP_TX_STMIN, &stmin, sizeof(stmin));

Reception stmin
~~~~~~~~~~~~~~~

The reception minimum separation time (stmin) can be forced using the
``CAN_ISOTP_RX_STMIN`` optname and providing an stmin value in microseconds as
a 32bit unsigned integer; received Consecutive Frames (CF) which timestamps
differ less than this value will be ignored:

.. code-block:: C

    uint32_t stmin;
    ret = setsockopt(s, SOL_CAN_ISOTP, CAN_ISOTP_RX_STMIN, &stmin, sizeof(stmin));

Multi-frame 제약과 오류

kernel stack이 지원하는 PDU 최대 크기는 module parameter와 build-time hard limit으로 제한됩니다. 전송 중 후속 `write`는 block하고 `send`는 `MSG_DONTWAIT` 여부에 따라 block하거나 실패합니다. wait frame 송신은 지원하지 않으며 First Frame을 받는 시점에 PDU 전체 수신 가능 여부를 결정합니다.

RX 오류는 data timeout `-ETIMEDOUT`, multi-frame sequence mismatch `-EILSEQ`, 잘못된 padding `-EBADMSG`입니다. TX 오류는 FC timeout `-ECOMM`, FC overflow `-EMSGSIZE`, FC layout/padding 오류 `-EBADMSG`입니다.

Multi-frame transport support
-----------------------------

The ISO-TP stack contained inside the Linux kernel supports the multi-frame
transport mechanism defined by the standard, with the following constraints:

* the maximum size of a PDU is defined by a module parameter, with an hard
  limit imposed at build time.

* when a transmission is in progress, subsequent calls to ``write(2)`` will
  block, while calls to ``send(2)`` will either block or fail depending on the
  presence of the ``MSG_DONTWAIT`` flag.

* no support is present for sending "wait frames": whether a PDU can be fully
  received or not is decided when the First Frame is received.

Errors
------

Following errors are reported to userspace:

RX path errors
~~~~~~~~~~~~~~

============ ===============================================================
-ETIMEDOUT   timeout of data reception
-EILSEQ      sequence number mismatch during a multi-frame reception
-EBADMSG     data reception with wrong padding
============ ===============================================================

TX path errors
~~~~~~~~~~~~~~

========== =================================================================
-ECOMM     flow control reception timeout
-EMSGSIZE  flow control reception overflow
-EBADMSG   flow control reception with wrong layout/padding
========== =================================================================

Normal physical addressing 예제

예제는 RX ID `0x18DAF142`, TX ID `0x18DA42F1`인 normal physical addressing node를 기본 option으로 만듭니다. `can0`의 ifindex를 얻고 두 extended CAN ID에 `CAN_EFF_FLAG`를 붙여 `sockaddr_can`에 넣은 뒤 bind합니다. 이후 payload는 `read`와 `write`로 송수신합니다.

더 완전한 예제는 `can-utils`의 `isotp*` userland tool에 있습니다. 원문의 C code와 URL은 아래 보존 블록에서 그대로 확인할 수 있습니다.

Examples
========

Basic node example
------------------

Following example implements a node using "normal" physical addressing, with
RX ID equal to 0x18DAF142 and a TX ID equal to 0x18DA42F1. All options are left
to their default.

.. code-block:: C

  int s;
  struct sockaddr_can addr;
  int ret;

  s = socket(PF_CAN, SOCK_DGRAM, CAN_ISOTP);
  if (s < 0)
      exit(1);

  addr.can_family = AF_CAN;
  addr.can_ifindex = if_nametoindex("can0");
  addr.can_addr.tp.tx_id = 0x18DA42F1 | CAN_EFF_FLAG;
  addr.can_addr.tp.rx_id = 0x18DAF142 | CAN_EFF_FLAG;

  ret = bind(s, (struct sockaddr *)&addr, sizeof(addr));
  if (ret < 0)
      exit(1);

  /* Data can now be received using read(s, ...) and sent using write(s, ...) */

Additional examples
-------------------

More complete (and complex) examples can be found inside the ``isotp*`` userland
tools, distributed as part of the ``can-utils`` utilities at:
https://github.com/linux-can/can-utils