1 .. SPDX-License-Identifier: (GPL-2.0 OR BSD-3-Clause)
2
3 ====================
4 ISO 15765-2 (ISO-TP)
5 ====================
6
7 Overview
8 ========
9
10 ISO 15765-2, also known as ISO-TP, is a transport protocol specifically defined
11 for diagnostic communication on CAN. It is widely used in the automotive
12 industry, for example as the transport protocol for UDSonCAN (ISO 14229-3) or
13 emission-related diagnostic services (ISO 15031-5).
14
15 ISO-TP can be used both on CAN CC (aka Classical CAN) and CAN FD (CAN with
16 Flexible Datarate) based networks. It is also designed to be compatible with a
17 CAN network using SAE J1939 as data link layer (however, this is not a
18 requirement).
19
20 Specifications 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
26 Addressing
27 ----------
28
29 In its simplest form, ISO-TP is based on two kinds of addressing modes for the
30 nodes 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
38 Three 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
50 Transport protocol and associated frame types
51 ---------------------------------------------
52
53 When transmitting data using the ISO-TP protocol, the payload can either fit
54 inside one single CAN message or not, also considering the overhead the protocol
55 is generating and the optional extended addressing. In the first case, the data
56 is transmitted at once using a so-called Single Frame (SF). In the second case,
57 ISO-TP defines a multi-frame protocol, in which the sender provides (through a
58 First Frame - FF) the PDU length which is to be transmitted and also asks for a
59 Flow Control (FC) frame, which provides the maximum supported size of a macro
60 data block (``blocksize``) and the minimum time between the single CAN messages
61 composing such block (``stmin``). Once this information has been received, the
62 sender starts to send frames containing fragments of the data payload (called
63 Consecutive Frames - CF), stopping after every ``blocksize``-sized block to wait
64 confirmation from the receiver which should then send another Flow Control
65 frame to inform the sender about its availability to receive more data.
66
67 How to Use ISO-TP
68 =================
69
70 As with others CAN protocols, the ISO-TP stack support is built into the
71 Linux network subsystem for the CAN bus, aka. Linux-CAN or SocketCAN, and
72 thus follows the same socket API.
73
74 Creation and basic usage of an ISO-TP socket
75 --------------------------------------------
76
77 To use the ISO-TP stack, ``#include <linux/can/isotp.h>`` shall be used. A
78 socket can then be created using the ``PF_CAN`` protocol family, the
79 ``SOCK_DGRAM`` type (as the underlying protocol is datagram-based by design)
80 and the ``CAN_ISOTP`` protocol:
81
82 .. code-block:: C
83
84 s = socket(PF_CAN, SOCK_DGRAM, CAN_ISOTP);
85
86 After the socket has been successfully created, ``bind(2)`` shall be called to
87 bind 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
95 Once bound to an interface, the socket can be read from and written to using
96 the usual ``read(2)`` and ``write(2)`` system calls, as well as ``send(2)``,
97 ``sendmsg(2)``, ``recv(2)`` and ``recvmsg(2)``.
98 Unlike the CAN_RAW socket API, only the ISO-TP data field (the actual payload)
99 is sent and received by the userspace application using these calls. The address
100 information and the protocol information are automatically filled by the ISO-TP
101 stack using the configuration supplied during socket creation. In the same way,
102 the stack will use the transport mechanism when required (i.e., when the size
103 of the data payload exceeds the MTU of the underlying CAN bus).
104
105 The sockaddr structure used for SocketCAN has extensions for use with ISO-TP,
106 as 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
127 ISO-TP socket options
128 ---------------------
129
130 When creating an ISO-TP socket, reasonable defaults are set. Some options can
131 be modified with ``setsockopt(2)`` and/or read back with ``getsockopt(2)``.
132
133 General options
134 ~~~~~~~~~~~~~~~
135
136 General 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
143 where 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
223 Flow Control options
224 ~~~~~~~~~~~~~~~~~~~~
225
226 Flow Control (FC) options can be passed using the ``CAN_ISOTP_RECV_FC`` optname
227 to 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
234 where 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
255 Link Layer options
256 ~~~~~~~~~~~~~~~~~~
257
258 Link 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
265 where 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
285 Transmission stmin
286 ~~~~~~~~~~~~~~~~~~
287
288 The transmission minimum separation time (stmin) can be forced using the
289 ``CAN_ISOTP_TX_STMIN`` optname and providing an stmin value in microseconds as
290 a 32bit unsigned integer; this will overwrite the value sent by the receiver in
291 flow 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
298 Reception stmin
299 ~~~~~~~~~~~~~~~
300
301 The reception minimum separation time (stmin) can be forced using the
302 ``CAN_ISOTP_RX_STMIN`` optname and providing an stmin value in microseconds as
303 a 32bit unsigned integer; received Consecutive Frames (CF) which timestamps
304 differ 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
311 Multi-frame transport support
312 -----------------------------
313
314 The ISO-TP stack contained inside the Linux kernel supports the multi-frame
315 transport 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
327 Errors
328 ------
329
330 Following errors are reported to userspace:
331
332 RX 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
341 TX 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
350 Examples
351 ========
352
353 Basic node example
354 ------------------
355
356 Following example implements a node using "normal" physical addressing, with
357 RX ID equal to 0x18DAF142 and a TX ID equal to 0x18DA42F1. All options are left
358 to 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
381 Additional examples
382 -------------------
383
384 More complete (and complex) examples can be found inside the ``isotp*`` userland
385 tools, distributed as part of the ``can-utils`` utilities at:
386 https://github.com/linux-can/can-utils
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.