1.. SPDX-License-Identifier: (GPL-2.0 OR MIT)
2
3===================
4J1939 Documentation
5===================
6
7Overview / What Is J1939
8========================
9
10SAE J1939 defines a higher layer protocol on CAN. It implements a more
11sophisticated addressing scheme and extends the maximum packet size above 8
12bytes. Several derived specifications exist, which differ from the original
13J1939 on the application level, like MilCAN A, NMEA2000 and especially
14ISO-11783 (ISOBUS). This last one specifies the so-called ETP (Extended
15Transport Protocol) which is has been included in this implementation. This
16results in a maximum packet size of ((2 ^ 24) - 1) * 7 bytes == 111 MiB.
17
18Specifications used
19-------------------
20
21* SAE J1939-21 : data link layer
22* SAE J1939-81 : network management
23* ISO 11783-6  : Virtual Terminal (Extended Transport Protocol)
24
25.. _j1939-motivation:
26
27Motivation
28==========
29
30Given the fact there's something like SocketCAN with an API similar to BSD
31sockets, we found some reasons to justify a kernel implementation for the
32addressing and transport methods used by J1939.
33
34* **Addressing:** when a process on an ECU communicates via J1939, it should
35  not necessarily know its source address. Although at least one process per
36  ECU should know the source address. Other processes should be able to reuse
37  that address. This way, address parameters for different processes
38  cooperating for the same ECU, are not duplicated. This way of working is
39  closely related to the UNIX concept where programs do just one thing, and do
40  it well.
41
42* **Dynamic addressing:** Address Claiming in J1939 is time critical.
43  Furthermore data transport should be handled properly during the address
44  negotiation. Putting this functionality in the kernel eliminates it as a
45  requirement for _every_ user space process that communicates via J1939. This
46  results in a consistent J1939 bus with proper addressing.
47
48* **Transport:** both TP & ETP reuse some PGNs to relay big packets over them.
49  Different processes may thus use the same TP & ETP PGNs without actually
50  knowing it. The individual TP & ETP sessions _must_ be serialized
51  (synchronized) between different processes. The kernel solves this problem
52  properly and eliminates the serialization (synchronization) as a requirement
53  for _every_ user space process that communicates via J1939.
54
55J1939 defines some other features (relaying, gateway, fast packet transport,
56...). In-kernel code for these would not contribute to protocol stability.
57Therefore, these parts are left to user space.
58
59The J1939 sockets operate on CAN network devices (see SocketCAN). Any J1939
60user space library operating on CAN raw sockets will still operate properly.
61Since such library does not communicate with the in-kernel implementation, care
62must be taken that these two do not interfere. In practice, this means they
63cannot share ECU addresses. A single ECU (or virtual ECU) address is used by
64the library exclusively, or by the in-kernel system exclusively.
65
66J1939 concepts
67==============
68
69PGN
70---
71
72The PGN (Parameter Group Number) is a number to identify a packet. The PGN
73is composed as follows:
741 bit  : Reserved Bit
751 bit  : Data Page
768 bits : PF (PDU Format)
778 bits : PS (PDU Specific)
78
79In J1939-21 distinction is made between PDU1 format (where PF < 240) and PDU2
80format (where PF >= 240). Furthermore, when using PDU2 format, the PS-field
81contains a so-called Group Extension, which is part of the PGN. When using PDU2
82format, the Group Extension is set in the PS-field.
83
84On the other hand, when using PDU1 format, the PS-field contains a so-called
85Destination Address, which is _not_ part of the PGN. When communicating a PGN
86from user space to kernel (or visa versa) and PDU2 format is used, the PS-field
87of the PGN shall be set to zero. The Destination Address shall be set
88elsewhere.
89
90Regarding PGN mapping to 29-bit CAN identifier, the Destination Address shall
91be get/set from/to the appropriate bits of the identifier by the kernel.
92
93
94Addressing
95----------
96
97Both static and dynamic addressing methods can be used.
98
99For static addresses, no extra checks are made by the kernel, and provided
100addresses are considered right. This responsibility is for the OEM or system
101integrator.
102
103For dynamic addressing, so-called Address Claiming, extra support is foreseen
104in the kernel. In J1939 any ECU is known by it's 64-bit NAME. At the moment of
105a successful address claim, the kernel keeps track of both NAME and source
106address being claimed. This serves as a base for filter schemes. By default,
107packets with a destination that is not locally, will be rejected.
108
109Mixed mode packets (from a static to a dynamic address or vice versa) are
110allowed. The BSD sockets define separate API calls for getting/setting the
111local & remote address and are applicable for J1939 sockets.
112
113Filtering
114---------
115
116J1939 defines white list filters per socket that a user can set in order to
117receive a subset of the J1939 traffic. Filtering can be based on:
118
119* SA
120* SOURCE_NAME
121* PGN
122
123When multiple filters are in place for a single socket, and a packet comes in
124that matches several of those filters, the packet is only received once for
125that socket.
126
127How to Use J1939
128================
129
130API Calls
131---------
132
133On CAN, you first need to open a socket for communicating over a CAN network.
134To use J1939, #include <linux/can/j1939.h>. From there, <linux/can.h> will be
135included too. To open a socket, use:
136
137.. code-block:: C
138
139    s = socket(PF_CAN, SOCK_DGRAM, CAN_J1939);
140
141J1939 does use SOCK_DGRAM sockets. In the J1939 specification, connections are
142mentioned in the context of transport protocol sessions. These still deliver
143packets to the other end (using several CAN packets). SOCK_STREAM is not
144supported.
145
146After the successful creation of the socket, you would normally use the bind(2)
147and/or connect(2) system call to bind the socket to a CAN interface.  After
148binding and/or connecting the socket, you can read(2) and write(2) from/to the
149socket or use send(2), sendto(2), sendmsg(2) and the recv*() counterpart
150operations on the socket as usual. There are also J1939 specific socket options
151described below.
152
153In order to send data, a bind(2) must have been successful. bind(2) assigns a
154local address to a socket.
155
156Different from CAN is that the payload data is just the data that get send,
157without it's header info. The header info is derived from the sockaddr supplied
158to bind(2), connect(2), sendto(2) and recvfrom(2). A write(2) with size 4 will
159result in a packet with 4 bytes.
160
161The sockaddr structure has extensions for use with J1939 as specified below:
162
163.. code-block:: C
164
165      struct sockaddr_can {
166         sa_family_t can_family;
167         int         can_ifindex;
168         union {
169            struct {
170               __u64 name;
171                        /* pgn:
172                         * 8 bit: PS in PDU2 case, else 0
173                         * 8 bit: PF
174                         * 1 bit: DP
175                         * 1 bit: reserved
176                         */
177               __u32 pgn;
178               __u8  addr;
179            } j1939;
180         } can_addr;
181      }
182
183can_family & can_ifindex serve the same purpose as for other SocketCAN sockets.
184
185can_addr.j1939.pgn specifies the PGN (max 0x3ffff). Individual bits are
186specified above.
187
188can_addr.j1939.name contains the 64-bit J1939 NAME.
189
190can_addr.j1939.addr contains the address.
191
192The bind(2) system call assigns the local address, i.e. the source address when
193sending packages. If a PGN during bind(2) is set, it's used as a RX filter.
194I.e.  only packets with a matching PGN are received. If an ADDR or NAME is set
195it is used as a receive filter, too. It will match the destination NAME or ADDR
196of the incoming packet. The NAME filter will work only if appropriate Address
197Claiming for this name was done on the CAN bus and registered/cached by the
198kernel.
199
200On the other hand connect(2) assigns the remote address, i.e. the destination
201address. The PGN from connect(2) is used as the default PGN when sending
202packets. If ADDR or NAME is set it will be used as the default destination ADDR
203or NAME. Further a set ADDR or NAME during connect(2) is used as a receive
204filter. It will match the source NAME or ADDR of the incoming packet.
205
206Both write(2) and send(2) will send a packet with local address from bind(2) and
207the remote address from connect(2). Use sendto(2) to overwrite the destination
208address.
209
210If can_addr.j1939.name is set (!= 0) the NAME is looked up by the kernel and
211the corresponding ADDR is used. If can_addr.j1939.name is not set (== 0),
212can_addr.j1939.addr is used.
213
214When creating a socket, reasonable defaults are set. Some options can be
215modified with setsockopt(2) & getsockopt(2).
216
217RX path related options:
218
219- SO_J1939_FILTER - configure array of filters
220- SO_J1939_PROMISC - disable filters set by bind(2) and connect(2)
221
222By default no broadcast packets can be send or received. To enable sending or
223receiving broadcast packets use the socket option SO_BROADCAST:
224
225.. code-block:: C
226
227     int value = 1;
228     setsockopt(sock, SOL_SOCKET, SO_BROADCAST, &value, sizeof(value));
229
230The following diagram illustrates the RX path:
231
232.. code::
233
234                    +--------------------+
235                    |  incoming packet   |
236                    +--------------------+
237                              |
238                              V
239                    +--------------------+
240                    | SO_J1939_PROMISC?  |
241                    +--------------------+
242                             |  |
243                         no  |  | yes
244                             |  |
245                   .---------'  `---------.
246                   |                      |
247     +---------------------------+        |
248     | bind() + connect() +      |        |
249     | SOCK_BROADCAST filter     |        |
250     +---------------------------+        |
251                   |                      |
252                   |<---------------------'
253                   V
254     +---------------------------+
255     |      SO_J1939_FILTER      |
256     +---------------------------+
257                   |
258                   V
259     +---------------------------+
260     |        socket recv()      |
261     +---------------------------+
262
263TX path related options:
264SO_J1939_SEND_PRIO - change default send priority for the socket
265
266Message Flags during send() and Related System Calls
267^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
268
269send(2), sendto(2) and sendmsg(2) take a 'flags' argument. Currently
270supported flags are:
271
272* MSG_DONTWAIT, i.e. non-blocking operation.
273
274recvmsg(2)
275^^^^^^^^^
276
277In most cases recvmsg(2) is needed if you want to extract more information than
278recvfrom(2) can provide. For example package priority and timestamp. The
279Destination Address, name and packet priority (if applicable) are attached to
280the msghdr in the recvmsg(2) call. They can be extracted using cmsg(3) macros,
281with cmsg_level == SOL_J1939 && cmsg_type == SCM_J1939_DEST_ADDR,
282SCM_J1939_DEST_NAME or SCM_J1939_PRIO. The returned data is a uint8_t for
283priority and dst_addr, and uint64_t for dst_name.
284
285.. code-block:: C
286
287	uint8_t priority, dst_addr;
288	uint64_t dst_name;
289
290	for (cmsg = CMSG_FIRSTHDR(&msg); cmsg; cmsg = CMSG_NXTHDR(&msg, cmsg)) {
291		switch (cmsg->cmsg_level) {
292		case SOL_CAN_J1939:
293			if (cmsg->cmsg_type == SCM_J1939_DEST_ADDR)
294				dst_addr = *CMSG_DATA(cmsg);
295			else if (cmsg->cmsg_type == SCM_J1939_DEST_NAME)
296				memcpy(&dst_name, CMSG_DATA(cmsg), cmsg->cmsg_len - CMSG_LEN(0));
297			else if (cmsg->cmsg_type == SCM_J1939_PRIO)
298				priority = *CMSG_DATA(cmsg);
299			break;
300		}
301	}
302
303Dynamic Addressing
304------------------
305
306Distinction has to be made between using the claimed address and doing an
307address claim. To use an already claimed address, one has to fill in the
308j1939.name member and provide it to bind(2). If the name had claimed an address
309earlier, all further messages being sent will use that address. And the
310j1939.addr member will be ignored.
311
312An exception on this is PGN 0x0ee00. This is the "Address Claim/Cannot Claim
313Address" message and the kernel will use the j1939.addr member for that PGN if
314necessary.
315
316To claim an address following code example can be used:
317
318.. code-block:: C
319
320	struct sockaddr_can baddr = {
321		.can_family = AF_CAN,
322		.can_addr.j1939 = {
323			.name = name,
324			.addr = J1939_IDLE_ADDR,
325			.pgn = J1939_NO_PGN,	/* to disable bind() rx filter for PGN */
326		},
327		.can_ifindex = if_nametoindex("can0"),
328	};
329
330	bind(sock, (struct sockaddr *)&baddr, sizeof(baddr));
331
332	/* for Address Claiming broadcast must be allowed */
333	int value = 1;
334	setsockopt(sock, SOL_SOCKET, SO_BROADCAST, &value, sizeof(value));
335
336	/* configured advanced RX filter with PGN needed for Address Claiming */
337	const struct j1939_filter filt[] = {
338		{
339			.pgn = J1939_PGN_ADDRESS_CLAIMED,
340			.pgn_mask = J1939_PGN_PDU1_MAX,
341		}, {
342			.pgn = J1939_PGN_ADDRESS_REQUEST,
343			.pgn_mask = J1939_PGN_PDU1_MAX,
344		}, {
345			.pgn = J1939_PGN_ADDRESS_COMMANDED,
346			.pgn_mask = J1939_PGN_MAX,
347		},
348	};
349
350	setsockopt(sock, SOL_CAN_J1939, SO_J1939_FILTER, &filt, sizeof(filt));
351
352	uint64_t dat = htole64(name);
353	const struct sockaddr_can saddr = {
354		.can_family = AF_CAN,
355		.can_addr.j1939 = {
356			.pgn = J1939_PGN_ADDRESS_CLAIMED,
357			.addr = J1939_NO_ADDR,
358		},
359	};
360
361	/* Afterwards do a sendto(2) with data set to the NAME (Little Endian). If the
362	 * NAME provided, does not match the j1939.name provided to bind(2), EPROTO
363	 * will be returned.
364	 */
365	sendto(sock, dat, sizeof(dat), 0, (const struct sockaddr *)&saddr, sizeof(saddr));
366
367If no-one else contests the address claim within 250ms after transmission, the
368kernel marks the NAME-SA assignment as valid. The valid assignment will be kept
369among other valid NAME-SA assignments. From that point, any socket bound to the
370NAME can send packets.
371
372If another ECU claims the address, the kernel will mark the NAME-SA expired.
373No socket bound to the NAME can send packets (other than address claims). To
374claim another address, some socket bound to NAME, must bind(2) again, but with
375only j1939.addr changed to the new SA, and must then send a valid address claim
376packet. This restarts the state machine in the kernel (and any other
377participant on the bus) for this NAME.
378
379can-utils also include the jacd tool, so it can be used as code example or as
380default Address Claiming daemon.
381
382Send Examples
383-------------
384
385Static Addressing
386^^^^^^^^^^^^^^^^^
387
388This example will send a PGN (0x12300) from SA 0x20 to DA 0x30.
389
390Bind:
391
392.. code-block:: C
393
394	struct sockaddr_can baddr = {
395		.can_family = AF_CAN,
396		.can_addr.j1939 = {
397			.name = J1939_NO_NAME,
398			.addr = 0x20,
399			.pgn = J1939_NO_PGN,
400		},
401		.can_ifindex = if_nametoindex("can0"),
402	};
403
404	bind(sock, (struct sockaddr *)&baddr, sizeof(baddr));
405
406Now, the socket 'sock' is bound to the SA 0x20. Since no connect(2) was called,
407at this point we can use only sendto(2) or sendmsg(2).
408
409Send:
410
411.. code-block:: C
412
413	const struct sockaddr_can saddr = {
414		.can_family = AF_CAN,
415		.can_addr.j1939 = {
416			.name = J1939_NO_NAME;
417			.pgn = 0x30,
418			.addr = 0x12300,
419		},
420	};
421
422	sendto(sock, dat, sizeof(dat), 0, (const struct sockaddr *)&saddr, sizeof(saddr));
423