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