1.. SPDX-License-Identifier: (GPL-2.0 OR BSD-3-Clause) 2 3==================== 4ISO 15765-2 (ISO-TP) 5==================== 6 7Overview 8======== 9 10ISO 15765-2, also known as ISO-TP, is a transport protocol specifically defined 11for diagnostic communication on CAN. It is widely used in the automotive 12industry, for example as the transport protocol for UDSonCAN (ISO 14229-3) or 13emission-related diagnostic services (ISO 15031-5). 14 15ISO-TP can be used both on CAN CC (aka Classical CAN) and CAN FD (CAN with 16Flexible Datarate) based networks. It is also designed to be compatible with a 17CAN network using SAE J1939 as data link layer (however, this is not a 18requirement). 19 20Specifications used 21------------------- 22 23* ISO 15765-2:2024 : Road vehicles - Diagnostic communication over Controller 24 Area Network (DoCAN). Part 2: Transport protocol and network layer services. 25 26Addressing 27---------- 28 29In its simplest form, ISO-TP is based on two kinds of addressing modes for the 30nodes connected to the same network: 31 32* physical addressing is implemented by two node-specific addresses and is used 33 in 1-to-1 communication. 34 35* functional addressing is implemented by one node-specific address and is used 36 in 1-to-N communication. 37 38Three different addressing formats can be employed: 39 40* "normal" : each address is represented simply by a CAN ID. 41 42* "extended": each address is represented by a CAN ID plus the first byte of 43 the CAN payload; both the CAN ID and the byte inside the payload shall be 44 different between two addresses. 45 46* "mixed": each address is represented by a CAN ID plus the first byte of 47 the CAN payload; the CAN ID is different between two addresses, but the 48 additional byte is the same. 49 50Transport protocol and associated frame types 51--------------------------------------------- 52 53When transmitting data using the ISO-TP protocol, the payload can either fit 54inside one single CAN message or not, also considering the overhead the protocol 55is generating and the optional extended addressing. In the first case, the data 56is transmitted at once using a so-called Single Frame (SF). In the second case, 57ISO-TP defines a multi-frame protocol, in which the sender provides (through a 58First Frame - FF) the PDU length which is to be transmitted and also asks for a 59Flow Control (FC) frame, which provides the maximum supported size of a macro 60data block (``blocksize``) and the minimum time between the single CAN messages 61composing such block (``stmin``). Once this information has been received, the 62sender starts to send frames containing fragments of the data payload (called 63Consecutive Frames - CF), stopping after every ``blocksize``-sized block to wait 64confirmation from the receiver which should then send another Flow Control 65frame to inform the sender about its availability to receive more data. 66 67How to Use ISO-TP 68================= 69 70As with others CAN protocols, the ISO-TP stack support is built into the 71Linux network subsystem for the CAN bus, aka. Linux-CAN or SocketCAN, and 72thus follows the same socket API. 73 74Creation and basic usage of an ISO-TP socket 75-------------------------------------------- 76 77To use the ISO-TP stack, ``#include <linux/can/isotp.h>`` shall be used. A 78socket can then be created using the ``PF_CAN`` protocol family, the 79``SOCK_DGRAM`` type (as the underlying protocol is datagram-based by design) 80and the ``CAN_ISOTP`` protocol: 81 82.. code-block:: C 83 84 s = socket(PF_CAN, SOCK_DGRAM, CAN_ISOTP); 85 86After the socket has been successfully created, ``bind(2)`` shall be called to 87bind the socket to the desired CAN interface; to do so: 88 89* a TX CAN ID shall be specified as part of the sockaddr supplied to the call 90 itself. 91 92* a RX CAN ID shall also be specified, unless broadcast flags have been set 93 through socket option (explained below). 94 95Once bound to an interface, the socket can be read from and written to using 96the usual ``read(2)`` and ``write(2)`` system calls, as well as ``send(2)``, 97``sendmsg(2)``, ``recv(2)`` and ``recvmsg(2)``. 98Unlike the CAN_RAW socket API, only the ISO-TP data field (the actual payload) 99is sent and received by the userspace application using these calls. The address 100information and the protocol information are automatically filled by the ISO-TP 101stack using the configuration supplied during socket creation. In the same way, 102the stack will use the transport mechanism when required (i.e., when the size 103of the data payload exceeds the MTU of the underlying CAN bus). 104 105The sockaddr structure used for SocketCAN has extensions for use with ISO-TP, 106as specified below: 107 108.. code-block:: C 109 110 struct sockaddr_can { 111 sa_family_t can_family; 112 int can_ifindex; 113 union { 114 struct { canid_t rx_id, tx_id; } tp; 115 ... 116 } can_addr; 117 } 118 119* ``can_family`` and ``can_ifindex`` serve the same purpose as for other 120 SocketCAN sockets. 121 122* ``can_addr.tp.rx_id`` specifies the receive (RX) CAN ID and will be used as 123 a RX filter. 124 125* ``can_addr.tp.tx_id`` specifies the transmit (TX) CAN ID 126 127ISO-TP socket options 128--------------------- 129 130When creating an ISO-TP socket, reasonable defaults are set. Some options can 131be modified with ``setsockopt(2)`` and/or read back with ``getsockopt(2)``. 132 133General options 134~~~~~~~~~~~~~~~ 135 136General socket options can be passed using the ``CAN_ISOTP_OPTS`` optname: 137 138.. code-block:: C 139 140 struct can_isotp_options opts; 141 ret = setsockopt(s, SOL_CAN_ISOTP, CAN_ISOTP_OPTS, &opts, sizeof(opts)) 142 143where the ``can_isotp_options`` structure has the following contents: 144 145.. code-block:: C 146 147 struct can_isotp_options { 148 u32 flags; 149 u32 frame_txtime; 150 u8 ext_address; 151 u8 txpad_content; 152 u8 rxpad_content; 153 u8 rx_ext_address; 154 }; 155 156* ``flags``: modifiers to be applied to the default behaviour of the ISO-TP 157 stack. Following flags are available: 158 159 * ``CAN_ISOTP_LISTEN_MODE``: listen only (do not send FC frames); normally 160 used as a testing feature. 161 162 * ``CAN_ISOTP_EXTEND_ADDR``: use the byte specified in ``ext_address`` as an 163 additional address component. This enables the "mixed" addressing format if 164 used alone, or the "extended" addressing format if used in conjunction with 165 ``CAN_ISOTP_RX_EXT_ADDR``. 166 167 * ``CAN_ISOTP_TX_PADDING``: enable padding for transmitted frames, using 168 ``txpad_content`` as value for the padding bytes. 169 170 * ``CAN_ISOTP_RX_PADDING``: enable padding for the received frames, using 171 ``rxpad_content`` as value for the padding bytes. 172 173 * ``CAN_ISOTP_CHK_PAD_LEN``: check for correct padding length on the received 174 frames. 175 176 * ``CAN_ISOTP_CHK_PAD_DATA``: check padding bytes on the received frames 177 against ``rxpad_content``; if ``CAN_ISOTP_RX_PADDING`` is not specified, 178 this flag is ignored. 179 180 * ``CAN_ISOTP_HALF_DUPLEX``: force ISO-TP socket in half duplex mode 181 (that is, transport mechanism can only be incoming or outgoing at the same 182 time, not both). 183 184 * ``CAN_ISOTP_FORCE_TXSTMIN``: ignore stmin from received FC; normally 185 used as a testing feature. 186 187 * ``CAN_ISOTP_FORCE_RXSTMIN``: ignore CFs depending on rx stmin; normally 188 used as a testing feature. 189 190 * ``CAN_ISOTP_RX_EXT_ADDR``: use ``rx_ext_address`` instead of ``ext_address`` 191 as extended addressing byte on the reception path. If used in conjunction 192 with ``CAN_ISOTP_EXTEND_ADDR``, this flag effectively enables the "extended" 193 addressing format. 194 195 * ``CAN_ISOTP_WAIT_TX_DONE``: wait until the frame is sent before returning 196 from ``write(2)`` and ``send(2)`` calls (i.e., blocking write operations). 197 198 * ``CAN_ISOTP_SF_BROADCAST``: use 1-to-N functional addressing (cannot be 199 specified alongside ``CAN_ISOTP_CF_BROADCAST``). 200 201 * ``CAN_ISOTP_CF_BROADCAST``: use 1-to-N transmission without flow control 202 (cannot be specified alongside ``CAN_ISOTP_SF_BROADCAST``). 203 NOTE: this is not covered by the ISO 15765-2 standard. 204 205 * ``CAN_ISOTP_DYN_FC_PARMS``: enable dynamic update of flow control 206 parameters. 207 208* ``frame_txtime``: frame transmission time (defined as N_As/N_Ar inside the 209 ISO standard); if ``0``, the default (or the last set value) is used. 210 To set the transmission time to ``0``, the ``CAN_ISOTP_FRAME_TXTIME_ZERO`` 211 macro (equal to 0xFFFFFFFF) shall be used. 212 213* ``ext_address``: extended addressing byte, used if the 214 ``CAN_ISOTP_EXTEND_ADDR`` flag is specified. 215 216* ``txpad_content``: byte used as padding value for transmitted frames. 217 218* ``rxpad_content``: byte used as padding value for received frames. 219 220* ``rx_ext_address``: extended addressing byte for the reception path, used if 221 the ``CAN_ISOTP_RX_EXT_ADDR`` flag is specified. 222 223Flow Control options 224~~~~~~~~~~~~~~~~~~~~ 225 226Flow Control (FC) options can be passed using the ``CAN_ISOTP_RECV_FC`` optname 227to provide the communication parameters for receiving ISO-TP PDUs. 228 229.. code-block:: C 230 231 struct can_isotp_fc_options fc_opts; 232 ret = setsockopt(s, SOL_CAN_ISOTP, CAN_ISOTP_RECV_FC, &fc_opts, sizeof(fc_opts)); 233 234where the ``can_isotp_fc_options`` structure has the following contents: 235 236.. code-block:: C 237 238 struct can_isotp_options { 239 u8 bs; 240 u8 stmin; 241 u8 wftmax; 242 }; 243 244* ``bs``: blocksize provided in flow control frames. 245 246* ``stmin``: minimum separation time provided in flow control frames; can 247 have the following values (others are reserved): 248 249 * 0x00 - 0x7F : 0 - 127 ms 250 251 * 0xF1 - 0xF9 : 100 us - 900 us 252 253* ``wftmax``: maximum number of wait frames provided in flow control frames. 254 255Link Layer options 256~~~~~~~~~~~~~~~~~~ 257 258Link Layer (LL) options can be passed using the ``CAN_ISOTP_LL_OPTS`` optname: 259 260.. code-block:: C 261 262 struct can_isotp_ll_options ll_opts; 263 ret = setsockopt(s, SOL_CAN_ISOTP, CAN_ISOTP_LL_OPTS, &ll_opts, sizeof(ll_opts)); 264 265where the ``can_isotp_ll_options`` structure has the following contents: 266 267.. code-block:: C 268 269 struct can_isotp_ll_options { 270 u8 mtu; 271 u8 tx_dl; 272 u8 tx_flags; 273 }; 274 275* ``mtu``: generated and accepted CAN frame type, can be equal to ``CAN_MTU`` 276 for classical CAN frames or ``CANFD_MTU`` for CAN FD frames. 277 278* ``tx_dl``: maximum payload length for transmitted frames, can have one value 279 among: 8, 12, 16, 20, 24, 32, 48, 64. Values above 8 only apply to CAN FD 280 traffic (i.e.: ``mtu = CANFD_MTU``). 281 282* ``tx_flags``: flags set into ``struct canfd_frame.flags`` at frame creation. 283 Only applies to CAN FD traffic (i.e.: ``mtu = CANFD_MTU``). 284 285Transmission stmin 286~~~~~~~~~~~~~~~~~~ 287 288The transmission minimum separation time (stmin) can be forced using the 289``CAN_ISOTP_TX_STMIN`` optname and providing an stmin value in microseconds as 290a 32bit unsigned integer; this will overwrite the value sent by the receiver in 291flow control frames: 292 293.. code-block:: C 294 295 uint32_t stmin; 296 ret = setsockopt(s, SOL_CAN_ISOTP, CAN_ISOTP_TX_STMIN, &stmin, sizeof(stmin)); 297 298Reception stmin 299~~~~~~~~~~~~~~~ 300 301The reception minimum separation time (stmin) can be forced using the 302``CAN_ISOTP_RX_STMIN`` optname and providing an stmin value in microseconds as 303a 32bit unsigned integer; received Consecutive Frames (CF) which timestamps 304differ less than this value will be ignored: 305 306.. code-block:: C 307 308 uint32_t stmin; 309 ret = setsockopt(s, SOL_CAN_ISOTP, CAN_ISOTP_RX_STMIN, &stmin, sizeof(stmin)); 310 311Multi-frame transport support 312----------------------------- 313 314The ISO-TP stack contained inside the Linux kernel supports the multi-frame 315transport mechanism defined by the standard, with the following constraints: 316 317* the maximum size of a PDU is defined by a module parameter, with an hard 318 limit imposed at build time. 319 320* when a transmission is in progress, subsequent calls to ``write(2)`` will 321 block, while calls to ``send(2)`` will either block or fail depending on the 322 presence of the ``MSG_DONTWAIT`` flag. 323 324* no support is present for sending "wait frames": whether a PDU can be fully 325 received or not is decided when the First Frame is received. 326 327Errors 328------ 329 330Following errors are reported to userspace: 331 332RX path errors 333~~~~~~~~~~~~~~ 334 335============ =============================================================== 336-ETIMEDOUT timeout of data reception 337-EILSEQ sequence number mismatch during a multi-frame reception 338-EBADMSG data reception with wrong padding 339============ =============================================================== 340 341TX path errors 342~~~~~~~~~~~~~~ 343 344========== ================================================================= 345-ECOMM flow control reception timeout 346-EMSGSIZE flow control reception overflow 347-EBADMSG flow control reception with wrong layout/padding 348========== ================================================================= 349 350Examples 351======== 352 353Basic node example 354------------------ 355 356Following example implements a node using "normal" physical addressing, with 357RX ID equal to 0x18DAF142 and a TX ID equal to 0x18DA42F1. All options are left 358to their default. 359 360.. code-block:: C 361 362 int s; 363 struct sockaddr_can addr; 364 int ret; 365 366 s = socket(PF_CAN, SOCK_DGRAM, CAN_ISOTP); 367 if (s < 0) 368 exit(1); 369 370 addr.can_family = AF_CAN; 371 addr.can_ifindex = if_nametoindex("can0"); 372 addr.tp.tx_id = 0x18DA42F1 | CAN_EFF_FLAG; 373 addr.tp.rx_id = 0x18DAF142 | CAN_EFF_FLAG; 374 375 ret = bind(s, (struct sockaddr *)&addr, sizeof(addr)); 376 if (ret < 0) 377 exit(1); 378 379 /* Data can now be received using read(s, ...) and sent using write(s, ...) */ 380 381Additional examples 382------------------- 383 384More complete (and complex) examples can be found inside the ``isotp*`` userland 385tools, distributed as part of the ``can-utils`` utilities at: 386https://github.com/linux-can/can-utils 387