FILE
j1939.rst
File preview with syntax highlighting.
linux-6.19.14/Documentation/networking/j1939.rst
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 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 a 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 69Data Sent to the J1939 Stack 70---------------------------- 71 72The data buffers sent to the J1939 stack from user space are not CAN frames 73themselves. Instead, they are payloads that the J1939 stack converts into 74proper CAN frames based on the size of the buffer and the type of transfer. The 75size of the buffer influences how the stack processes the data and determines 76the internal code path used for the transfer. 77 78**Handling of Different Buffer Sizes:** 79 80- **Buffers with a size of 8 bytes or less:** 81 82 - These are handled as simple sessions internally within the stack. 83 84 - The stack converts the buffer directly into a single CAN frame without 85 fragmentation. 86 87 - This type of transfer does not require an actual client (receiver) on the 88 receiving side. 89 90- **Buffers up to 1785 bytes:** 91 92 - These are automatically handled as J1939 Transport Protocol (TP) transfers. 93 94 - Internally, the stack splits the buffer into multiple 8-byte CAN frames. 95 96 - TP transfers can be unicast or broadcast. 97 98 - **Broadcast TP:** Does not require a receiver on the other side and can be 99 used in broadcast scenarios. 100 101 - **Unicast TP:** Requires an active receiver (client) on the other side to 102 acknowledge the transfer. 103 104- **Buffers from 1786 bytes up to 111 MiB:** 105 106 - These are handled as ISO 11783 Extended Transport Protocol (ETP) transfers. 107 108 - ETP transfers are used for larger payloads and are split into multiple CAN 109 frames internally. 110 111 - **ETP transfers (unicast):** Require a receiver on the other side to 112 process the incoming data and acknowledge each step of the transfer. 113 114 - ETP transfers cannot be broadcast like TP transfers, and always require a 115 receiver for operation. 116 117**Non-Blocking Operation with `MSG_DONTWAIT`:** 118 119The J1939 stack supports non-blocking operation when used in combination with 120the `MSG_DONTWAIT` flag. In this mode, the stack attempts to take as much data 121as the available memory for the socket allows. It returns the amount of data 122that was successfully taken, and it is the responsibility of user space to 123monitor this value and handle partial transfers. 124 125- If the stack cannot take the entire buffer, it returns the number of bytes 126 successfully taken, and user space should handle the remainder. 127 128- **Error handling:** When using `MSG_DONTWAIT`, the user must rely on the 129 error queue to detect transfer errors. See the **SO_J1939_ERRQUEUE** section 130 for details on how to subscribe to error notifications. Without the error 131 queue, there is no other way for user space to be notified of transfer errors 132 during non-blocking operations. 133 134**Behavior and Requirements:** 135 136- **Simple transfers (<= 8 bytes):** Do not require a receiver on the other 137 side, making them easy to send without needing address claiming or 138 coordination with a destination. 139 140- **Unicast TP/ETP:** Requires a receiver on the other side to complete the 141 transfer. The receiver must acknowledge the transfer for the session to 142 proceed successfully. 143 144- **Broadcast TP:** Allows sending data without a receiver, but only works for 145 TP transfers. ETP cannot be broadcast and always needs a receiving client. 146 147These different behaviors depend heavily on the size of the buffer provided to 148the stack, and the appropriate transport mechanism (TP or ETP) is selected 149based on the payload size. The stack automatically manages the fragmentation 150and reassembly of large payloads and ensures that the correct CAN frames are 151generated and transmitted for each session. 152 153PGN 154--- 155 156The J1939 protocol uses the 29-bit CAN identifier with the following structure: 157 158 ============ ============== ==================== 159 29 bit CAN-ID 160 -------------------------------------------------- 161 Bit positions within the CAN-ID 162 -------------------------------------------------- 163 28 ... 26 25 ... 8 7 ... 0 164 ============ ============== ==================== 165 Priority PGN SA (Source Address) 166 ============ ============== ==================== 167 168The PGN (Parameter Group Number) is a number to identify a packet. The PGN 169is composed as follows: 170 171 ============ ============== ================= ================= 172 PGN 173 ------------------------------------------------------------------ 174 Bit positions within the CAN-ID 175 ------------------------------------------------------------------ 176 25 24 23 ... 16 15 ... 8 177 ============ ============== ================= ================= 178 R (Reserved) DP (Data Page) PF (PDU Format) PS (PDU Specific) 179 ============ ============== ================= ================= 180 181In J1939-21 distinction is made between PDU1 format (where PF < 240) and PDU2 182format (where PF >= 240). Furthermore, when using the PDU2 format, the PS-field 183contains a so-called Group Extension, which is part of the PGN. When using PDU2 184format, the Group Extension is set in the PS-field. 185 186 ============== ======================== 187 PDU1 Format (specific) (peer to peer) 188 ---------------------------------------- 189 Bit positions within the CAN-ID 190 ---------------------------------------- 191 23 ... 16 15 ... 8 192 ============== ======================== 193 00h ... EFh DA (Destination address) 194 ============== ======================== 195 196 ============== ======================== 197 PDU2 Format (global) (broadcast) 198 ---------------------------------------- 199 Bit positions within the CAN-ID 200 ---------------------------------------- 201 23 ... 16 15 ... 8 202 ============== ======================== 203 F0h ... FFh GE (Group Extension) 204 ============== ======================== 205 206On the other hand, when using PDU1 format, the PS-field contains a so-called 207Destination Address, which is _not_ part of the PGN. When communicating a PGN 208from user space to kernel (or vice versa) and PDU1 format is used, the PS-field 209of the PGN shall be set to zero. The Destination Address shall be set 210elsewhere. 211 212Regarding PGN mapping to 29-bit CAN identifier, the Destination Address shall 213be get/set from/to the appropriate bits of the identifier by the kernel. 214 215 216Addressing 217---------- 218 219Both static and dynamic addressing methods can be used. 220 221For static addresses, no extra checks are made by the kernel and provided 222addresses are considered right. This responsibility is for the OEM or system 223integrator. 224 225For dynamic addressing, so-called Address Claiming, extra support is foreseen 226in the kernel. In J1939 any ECU is known by its 64-bit NAME. At the moment of 227a successful address claim, the kernel keeps track of both NAME and source 228address being claimed. This serves as a base for filter schemes. By default, 229packets with a destination that is not locally will be rejected. 230 231Mixed mode packets (from a static to a dynamic address or vice versa) are 232allowed. The BSD sockets define separate API calls for getting/setting the 233local & remote address and are applicable for J1939 sockets. 234 235Filtering 236--------- 237 238J1939 defines white list filters per socket that a user can set in order to 239receive a subset of the J1939 traffic. Filtering can be based on: 240 241* SA 242* SOURCE_NAME 243* PGN 244 245When multiple filters are in place for a single socket, and a packet comes in 246that matches several of those filters, the packet is only received once for 247that socket. 248 249How to Use J1939 250================ 251 252API Calls 253--------- 254 255On CAN, you first need to open a socket for communicating over a CAN network. 256To use J1939, ``#include <linux/can/j1939.h>``. From there, ``<linux/can.h>`` will be 257included too. To open a socket, use: 258 259.. code-block:: C 260 261 s = socket(PF_CAN, SOCK_DGRAM, CAN_J1939); 262 263J1939 does use ``SOCK_DGRAM`` sockets. In the J1939 specification, connections are 264mentioned in the context of transport protocol sessions. These still deliver 265packets to the other end (using several CAN packets). ``SOCK_STREAM`` is not 266supported. 267 268After the successful creation of the socket, you would normally use the ``bind(2)`` 269and/or ``connect(2)`` system call to bind the socket to a CAN interface. After 270binding and/or connecting the socket, you can ``read(2)`` and ``write(2)`` from/to the 271socket or use ``send(2)``, ``sendto(2)``, ``sendmsg(2)`` and the ``recv*()`` counterpart 272operations on the socket as usual. There are also J1939 specific socket options 273described below. 274 275In order to send data, a ``bind(2)`` must have been successful. ``bind(2)`` assigns a 276local address to a socket. 277 278Different from CAN is that the payload data is just the data that get sends, 279without its header info. The header info is derived from the sockaddr supplied 280to ``bind(2)``, ``connect(2)``, ``sendto(2)`` and ``recvfrom(2)``. A ``write(2)`` with size 4 will 281result in a packet with 4 bytes. 282 283The sockaddr structure has extensions for use with J1939 as specified below: 284 285.. code-block:: C 286 287 struct sockaddr_can { 288 sa_family_t can_family; 289 int can_ifindex; 290 union { 291 struct { 292 __u64 name; 293 /* pgn: 294 * 8 bit: PS in PDU2 case, else 0 295 * 8 bit: PF 296 * 1 bit: DP 297 * 1 bit: reserved 298 */ 299 __u32 pgn; 300 __u8 addr; 301 } j1939; 302 } can_addr; 303 } 304 305``can_family`` & ``can_ifindex`` serve the same purpose as for other SocketCAN sockets. 306 307``can_addr.j1939.pgn`` specifies the PGN (max 0x3ffff). Individual bits are 308specified above. 309 310``can_addr.j1939.name`` contains the 64-bit J1939 NAME. 311 312``can_addr.j1939.addr`` contains the address. 313 314The ``bind(2)`` system call assigns the local address, i.e. the source address when 315sending packages. If a PGN during ``bind(2)`` is set, it's used as a RX filter. 316I.e. only packets with a matching PGN are received. If an ADDR or NAME is set 317it is used as a receive filter, too. It will match the destination NAME or ADDR 318of the incoming packet. The NAME filter will work only if appropriate Address 319Claiming for this name was done on the CAN bus and registered/cached by the 320kernel. 321 322On the other hand ``connect(2)`` assigns the remote address, i.e. the destination 323address. The PGN from ``connect(2)`` is used as the default PGN when sending 324packets. If ADDR or NAME is set it will be used as the default destination ADDR 325or NAME. Further a set ADDR or NAME during ``connect(2)`` is used as a receive 326filter. It will match the source NAME or ADDR of the incoming packet. 327 328Both ``write(2)`` and ``send(2)`` will send a packet with local address from ``bind(2)`` and the 329remote address from ``connect(2)``. Use ``sendto(2)`` to overwrite the destination 330address. 331 332If ``can_addr.j1939.name`` is set (!= 0) the NAME is looked up by the kernel and 333the corresponding ADDR is used. If ``can_addr.j1939.name`` is not set (== 0), 334``can_addr.j1939.addr`` is used. 335 336When creating a socket, reasonable defaults are set. Some options can be 337modified with ``setsockopt(2)`` & ``getsockopt(2)``. 338 339RX path related options: 340 341- ``SO_J1939_FILTER`` - configure array of filters 342- ``SO_J1939_PROMISC`` - disable filters set by ``bind(2)`` and ``connect(2)`` 343 344By default no broadcast packets can be send or received. To enable sending or 345receiving broadcast packets use the socket option ``SO_BROADCAST``: 346 347.. code-block:: C 348 349 int value = 1; 350 setsockopt(sock, SOL_SOCKET, SO_BROADCAST, &value, sizeof(value)); 351 352The following diagram illustrates the RX path: 353 354.. code:: 355 356 +--------------------+ 357 | incoming packet | 358 +--------------------+ 359 | 360 V 361 +--------------------+ 362 | SO_J1939_PROMISC? | 363 +--------------------+ 364 | | 365 no | | yes 366 | | 367 .---------' `---------. 368 | | 369 +---------------------------+ | 370 | bind() + connect() + | | 371 | SOCK_BROADCAST filter | | 372 +---------------------------+ | 373 | | 374 |<---------------------' 375 V 376 +---------------------------+ 377 | SO_J1939_FILTER | 378 +---------------------------+ 379 | 380 V 381 +---------------------------+ 382 | socket recv() | 383 +---------------------------+ 384 385TX path related options: 386``SO_J1939_SEND_PRIO`` - change default send priority for the socket 387 388Message Flags during send() and Related System Calls 389^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 390 391``send(2)``, ``sendto(2)`` and ``sendmsg(2)`` take a 'flags' argument. Currently 392supported flags are: 393 394* ``MSG_DONTWAIT``, i.e. non-blocking operation. 395 396recvmsg(2) 397^^^^^^^^^^ 398 399In most cases ``recvmsg(2)`` is needed if you want to extract more information than 400``recvfrom(2)`` can provide. For example package priority and timestamp. The 401Destination Address, name and packet priority (if applicable) are attached to 402the msghdr in the ``recvmsg(2)`` call. They can be extracted using ``cmsg(3)`` macros, 403with ``cmsg_level == SOL_J1939 && cmsg_type == SCM_J1939_DEST_ADDR``, 404``SCM_J1939_DEST_NAME`` or ``SCM_J1939_PRIO``. The returned data is a ``uint8_t`` for 405``priority`` and ``dst_addr``, and ``uint64_t`` for ``dst_name``. 406 407.. code-block:: C 408 409 uint8_t priority, dst_addr; 410 uint64_t dst_name; 411 412 for (cmsg = CMSG_FIRSTHDR(&msg); cmsg; cmsg = CMSG_NXTHDR(&msg, cmsg)) { 413 switch (cmsg->cmsg_level) { 414 case SOL_CAN_J1939: 415 if (cmsg->cmsg_type == SCM_J1939_DEST_ADDR) 416 dst_addr = *CMSG_DATA(cmsg); 417 else if (cmsg->cmsg_type == SCM_J1939_DEST_NAME) 418 memcpy(&dst_name, CMSG_DATA(cmsg), cmsg->cmsg_len - CMSG_LEN(0)); 419 else if (cmsg->cmsg_type == SCM_J1939_PRIO) 420 priority = *CMSG_DATA(cmsg); 421 break; 422 } 423 } 424 425setsockopt(2) 426^^^^^^^^^^^^^ 427 428The ``setsockopt(2)`` function is used to configure various socket-level 429options for J1939 communication. The following options are supported: 430 431``SO_J1939_FILTER`` 432~~~~~~~~~~~~~~~~~~~ 433 434The ``SO_J1939_FILTER`` option is essential when the default behavior of 435``bind(2)`` and ``connect(2)`` is insufficient for specific use cases. By 436default, ``bind(2)`` and ``connect(2)`` allow a socket to be associated with a 437single unicast or broadcast address. However, there are scenarios where finer 438control over the incoming messages is required, such as filtering by Parameter 439Group Number (PGN) rather than by addresses. 440 441For example, in a system where multiple types of J1939 messages are being 442transmitted, a process might only be interested in a subset of those messages, 443such as specific PGNs, and not want to receive all messages destined for its 444address or broadcast to the bus. 445 446By applying the ``SO_J1939_FILTER`` option, you can filter messages based on: 447 448- **Source Address (SA)**: Filter messages coming from specific source 449 addresses. 450 451- **Source Name**: Filter messages coming from ECUs with specific NAME 452 identifiers. 453 454- **Parameter Group Number (PGN)**: Focus on receiving messages with specific 455 PGNs, filtering out irrelevant ones. 456 457This filtering mechanism is particularly useful when: 458 459- You want to receive a subset of messages based on their PGNs, even if the 460 address is the same. 461 462- You need to handle both broadcast and unicast messages but only care about 463 certain message types or parameters. 464 465- The ``bind(2)`` and ``connect(2)`` functions only allow binding to a single 466 address, which might not be sufficient if the process needs to handle multiple 467 PGNs but does not want to open multiple sockets. 468 469To remove existing filters, you can pass ``optval == NULL`` or ``optlen == 0`` 470to ``setsockopt(2)``. This will clear all currently set filters. If you want to 471**update** the set of filters, you must pass the updated filter set to 472``setsockopt(2)``, as the new filter set will **replace** the old one entirely. 473This behavior ensures that any previous filter configuration is discarded and 474only the new set is applied. 475 476Example of removing all filters: 477 478.. code-block:: c 479 480 setsockopt(sock, SOL_CAN_J1939, SO_J1939_FILTER, NULL, 0); 481 482**Maximum number of filters:** The maximum amount of filters that can be 483applied using ``SO_J1939_FILTER`` is defined by ``J1939_FILTER_MAX``, which is 484set to 512. This means you can configure up to 512 individual filters to match 485your specific filtering needs. 486 487Practical use case: **Monitoring Address Claiming** 488 489One practical use case is monitoring the J1939 address claiming process by 490filtering for specific PGNs related to address claiming. This allows a process 491to monitor and handle address claims without processing unrelated messages. 492 493Example: 494 495.. code-block:: c 496 497 struct j1939_filter filt[] = { 498 { 499 .pgn = J1939_PGN_ADDRESS_CLAIMED, 500 .pgn_mask = J1939_PGN_PDU1_MAX, 501 }, { 502 .pgn = J1939_PGN_REQUEST, 503 .pgn_mask = J1939_PGN_PDU1_MAX, 504 }, { 505 .pgn = J1939_PGN_ADDRESS_COMMANDED, 506 .pgn_mask = J1939_PGN_MAX, 507 }, 508 }; 509 setsockopt(sock, SOL_CAN_J1939, SO_J1939_FILTER, &filt, sizeof(filt)); 510 511In this example, the socket will only receive messages with the PGNs related to 512address claiming: ``J1939_PGN_ADDRESS_CLAIMED``, ``J1939_PGN_REQUEST``, and 513``J1939_PGN_ADDRESS_COMMANDED``. This is particularly useful in scenarios where 514you want to monitor and process address claims without being overwhelmed by 515other traffic on the J1939 network. 516 517``SO_J1939_PROMISC`` 518~~~~~~~~~~~~~~~~~~~~ 519 520The ``SO_J1939_PROMISC`` option enables socket-level promiscuous mode. When 521this option is enabled, the socket will receive all J1939 traffic, regardless 522of any filters set by ``bind()`` or ``connect()``. This is analogous to 523enabling promiscuous mode for an Ethernet interface, where all traffic on the 524network segment is captured. 525 526However, **`SO_J1939_FILTER` has a higher priority** compared to 527``SO_J1939_PROMISC``. This means that even in promiscuous mode, you can reduce 528the number of packets received by applying specific filters with 529`SO_J1939_FILTER`. The filters will limit which packets are passed to the 530socket, allowing for more refined traffic selection while promiscuous mode is 531active. 532 533The acceptable value size for this option is ``sizeof(int)``, and the value is 534only differentiated between `0` and non-zero. A value of `0` disables 535promiscuous mode, while any non-zero value enables it. 536 537This combination can be useful for debugging or monitoring specific types of 538traffic while still capturing a broad set of messages. 539 540Example: 541 542.. code-block:: c 543 544 int value = 1; 545 setsockopt(sock, SOL_CAN_J1939, SO_J1939_PROMISC, &value, sizeof(value)); 546 547In this example, setting ``value`` to any non-zero value (e.g., `1`) enables 548promiscuous mode, allowing the socket to receive all J1939 traffic on the 549network. 550 551``SO_BROADCAST`` 552~~~~~~~~~~~~~~~~ 553 554The ``SO_BROADCAST`` option enables the sending and receiving of broadcast 555messages. By default, broadcast messages are disabled for J1939 sockets. When 556this option is enabled, the socket will be allowed to send and receive 557broadcast packets on the J1939 network. 558 559Due to the nature of the CAN bus as a shared medium, all messages transmitted 560on the bus are visible to all participants. In the context of J1939, 561broadcasting refers to using a specific destination address field, where the 562destination address is set to a value that indicates the message is intended 563for all participants (usually a global address such as 0xFF). Enabling the 564broadcast option allows the socket to send and receive such broadcast messages. 565 566The acceptable value size for this option is ``sizeof(int)``, and the value is 567only differentiated between `0` and non-zero. A value of `0` disables the 568ability to send and receive broadcast messages, while any non-zero value 569enables it. 570 571Example: 572 573.. code-block:: c 574 575 int value = 1; 576 setsockopt(sock, SOL_SOCKET, SO_BROADCAST, &value, sizeof(value)); 577 578In this example, setting ``value`` to any non-zero value (e.g., `1`) enables 579the socket to send and receive broadcast messages. 580 581``SO_J1939_SEND_PRIO`` 582~~~~~~~~~~~~~~~~~~~~~~ 583 584The ``SO_J1939_SEND_PRIO`` option sets the priority of outgoing J1939 messages 585for the socket. In J1939, messages can have different priorities, and lower 586numerical values indicate higher priority. This option allows the user to 587control the priority of messages sent from the socket by adjusting the priority 588bits in the CAN identifier. 589 590The acceptable value **size** for this option is ``sizeof(int)``, and the value 591is expected to be in the range of 0 to 7, where `0` is the highest priority, 592and `7` is the lowest. By default, the priority is set to `6` if this option is 593not explicitly configured. 594 595Note that the priority values `0` and `1` can only be set if the process has 596the `CAP_NET_ADMIN` capability. These are reserved for high-priority traffic 597and require administrative privileges. 598 599Example: 600 601.. code-block:: c 602 603 int prio = 3; // Priority value between 0 (highest) and 7 (lowest) 604 setsockopt(sock, SOL_CAN_J1939, SO_J1939_SEND_PRIO, &prio, sizeof(prio)); 605 606In this example, the priority is set to `3`, meaning the outgoing messages will 607be sent with a moderate priority level. 608 609``SO_J1939_ERRQUEUE`` 610~~~~~~~~~~~~~~~~~~~~~ 611 612The ``SO_J1939_ERRQUEUE`` option enables the socket to receive error messages 613from the error queue, providing diagnostic information about transmission 614failures, protocol violations, or other issues that occur during J1939 615communication. Once this option is set, user space is required to handle 616``MSG_ERRQUEUE`` messages. 617 618Setting ``SO_J1939_ERRQUEUE`` to ``0`` will purge any currently present error 619messages in the error queue. When enabled, error messages can be retrieved 620using the ``recvmsg(2)`` system call. 621 622When subscribing to the error queue, the following error events can be 623accessed: 624 625- **``J1939_EE_INFO_TX_ABORT``**: Transmission abort errors. 626- **``J1939_EE_INFO_RX_RTS``**: Reception of RTS (Request to Send) control 627 frames. 628- **``J1939_EE_INFO_RX_DPO``**: Reception of data packets with Data Page Offset 629 (DPO). 630- **``J1939_EE_INFO_RX_ABORT``**: Reception abort errors. 631 632The error queue can be used to correlate errors with specific message transfer 633sessions using the session ID (``tskey``). The session ID is assigned via the 634``SOF_TIMESTAMPING_OPT_ID`` flag, which is set by enabling the 635``SO_TIMESTAMPING`` option. 636 637If ``SO_J1939_ERRQUEUE`` is activated, the user is required to pull messages 638from the error queue, meaning that using plain ``recv(2)`` is not sufficient 639anymore. The user must use ``recvmsg(2)`` with appropriate flags to handle 640error messages. Failure to do so can result in the socket becoming blocked with 641unprocessed error messages in the queue. 642 643It is **recommended** that ``SO_J1939_ERRQUEUE`` be used in combination with 644``SO_TIMESTAMPING`` in most cases. This enables proper error handling along 645with session tracking and timestamping, providing a more detailed analysis of 646message transfers and errors. 647 648The acceptable value **size** for this option is ``sizeof(int)``, and the value 649is only differentiated between ``0`` and non-zero. A value of ``0`` disables 650error queue reception and purges any existing error messages, while any 651non-zero value enables it. 652 653Example: 654 655.. code-block:: c 656 657 int enable = 1; // Enable error queue reception 658 setsockopt(sock, SOL_CAN_J1939, SO_J1939_ERRQUEUE, &enable, sizeof(enable)); 659 660 // Enable timestamping with session tracking via tskey 661 int timestamping = SOF_TIMESTAMPING_OPT_ID | SOF_TIMESTAMPING_TX_ACK | 662 SOF_TIMESTAMPING_TX_SCHED | 663 SOF_TIMESTAMPING_RX_SOFTWARE | SOF_TIMESTAMPING_OPT_CMSG; 664 setsockopt(sock, SOL_SOCKET, SO_TIMESTAMPING, ×tamping, 665 sizeof(timestamping)); 666 667When enabled, error messages can be retrieved using ``recvmsg(2)``. By 668combining ``SO_J1939_ERRQUEUE`` with ``SO_TIMESTAMPING`` (with 669``SOF_TIMESTAMPING_OPT_ID`` and ``SOF_TIMESTAMPING_OPT_CMSG`` enabled), the 670user can track message transfers, retrieve precise timestamps, and correlate 671errors with specific sessions. 672 673For more information on enabling timestamps and session tracking, refer to the 674`SO_TIMESTAMPING` section. 675 676``SO_TIMESTAMPING`` 677~~~~~~~~~~~~~~~~~~~ 678 679The ``SO_TIMESTAMPING`` option allows the socket to receive timestamps for 680various events related to message transmissions and receptions in J1939. This 681option is often used in combination with ``SO_J1939_ERRQUEUE`` to provide 682detailed diagnostic information, session tracking, and precise timing data for 683message transfers. 684 685In J1939, all payloads provided by user space, regardless of size, are 686processed by the kernel as **sessions**. This includes both single-frame 687messages (up to 8 bytes) and multi-frame protocols such as the Transport 688Protocol (TP) and Extended Transport Protocol (ETP). Even for small, 689single-frame messages, the kernel creates a session to manage the transmission 690and reception. The concept of sessions allows the kernel to manage various 691aspects of the protocol, such as reassembling multi-frame messages and tracking 692the status of transmissions. 693 694When receiving extended error messages from the error queue, the error 695information is delivered through a `struct sock_extended_err`, accessible via 696the control message (``cmsg``) retrieved using the ``recvmsg(2)`` system call. 697 698There are two typical origins for the extended error messages in J1939: 699 7001. ``serr->ee_origin == SO_EE_ORIGIN_TIMESTAMPING``: 701 702 In this case, the `serr->ee_info` field will contain one of the following 703 timestamp types: 704 705 - ``SCM_TSTAMP_SCHED``: This timestamp is valid for Extended Transport 706 Protocol (ETP) transfers and simple transfers (8 bytes or less). It 707 indicates when a message or set of frames has been scheduled for 708 transmission. 709 710 - For simple transfers (8 bytes or less), it marks the point when the 711 message is queued and ready to be sent onto the CAN bus. 712 713 - For ETP transfers, it is sent after receiving a CTS (Clear to Send) 714 frame on the sender side, indicating that a new set of frames has been 715 scheduled for transmission. 716 717 - The Transport Protocol (TP) case is currently not implemented for this 718 timestamp. 719 720 - On the receiver side, the counterpart to this event for ETP is 721 represented by the ``J1939_EE_INFO_RX_DPO`` message, which indicates the 722 reception of a Data Page Offset (DPO) control frame. 723 724 - ``SCM_TSTAMP_ACK``: This timestamp indicates the acknowledgment of the 725 message or session. 726 727 - For simple transfers (8 bytes or less), it marks when the message has 728 been sent and an echo confirmation has been received from the CAN 729 controller, indicating that the frame was transmitted onto the bus. 730 731 - For multi-frame transfers (TP or ETP), it signifies that the entire 732 session has been acknowledged, typically after receiving the End of 733 Message Acknowledgment (EOMA) packet. 734 7352. ``serr->ee_origin == SO_EE_ORIGIN_LOCAL``: 736 737 In this case, the `serr->ee_info` field will contain one of the following 738 J1939 stack-specific message types: 739 740 - ``J1939_EE_INFO_TX_ABORT``: This message indicates that the transmission 741 of a message or session was aborted. The cause of the abort can come from 742 various sources: 743 744 - **CAN stack failure**: The J1939 stack was unable to pass the frame to 745 the CAN framework for transmission. 746 747 - **Echo failure**: The J1939 stack did not receive an echo confirmation 748 from the CAN controller, meaning the frame may not have been successfully 749 transmitted to the CAN bus. 750 751 - **Protocol-level issues**: For multi-frame transfers (TP/ETP), this 752 could include protocol-related errors, such as an abort signaled by the 753 receiver or a timeout at the protocol level, which causes the session to 754 terminate prematurely. 755 756 - The corresponding error code is stored in ``serr->ee_data`` 757 (``session->err`` on kernel side), providing additional details about 758 the specific reason for the abort. 759 760 - ``J1939_EE_INFO_RX_RTS``: This message indicates that the J1939 stack has 761 received a Request to Send (RTS) control frame, signaling the start of a 762 multi-frame transfer using the Transport Protocol (TP) or Extended 763 Transport Protocol (ETP). 764 765 - It informs the receiver that the sender is ready to transmit a 766 multi-frame message and includes details about the total message size 767 and the number of frames to be sent. 768 769 - Statistics such as ``J1939_NLA_TOTAL_SIZE``, ``J1939_NLA_PGN``, 770 ``J1939_NLA_SRC_NAME``, and ``J1939_NLA_DEST_NAME`` are provided along 771 with the ``J1939_EE_INFO_RX_RTS`` message, giving detailed information 772 about the incoming transfer. 773 774 - ``J1939_EE_INFO_RX_DPO``: This message indicates that the J1939 stack has 775 received a Data Page Offset (DPO) control frame, which is part of the 776 Extended Transport Protocol (ETP). 777 778 - The DPO frame signals the continuation of an ETP multi-frame message by 779 indicating the offset position in the data being transferred. It helps 780 the receiver manage large data sets by identifying which portion of the 781 message is being received. 782 783 - It is typically paired with a corresponding ``SCM_TSTAMP_SCHED`` event 784 on the sender side, which indicates when the next set of frames is 785 scheduled for transmission. 786 787 - This event includes statistics such as ``J1939_NLA_BYTES_ACKED``, which 788 tracks the number of bytes acknowledged up to that point in the session. 789 790 - ``J1939_EE_INFO_RX_ABORT``: This message indicates that the reception of a 791 multi-frame message (Transport Protocol or Extended Transport Protocol) has 792 been aborted. 793 794 - The abort can be triggered by protocol-level errors such as timeouts, an 795 unexpected frame, or a specific abort request from the sender. 796 797 - This message signals that the receiver cannot continue processing the 798 transfer, and the session is terminated. 799 800 - The corresponding error code is stored in ``serr->ee_data`` 801 (``session->err`` on kernel side ), providing further details about the 802 reason for the abort, such as protocol violations or timeouts. 803 804 - After receiving this message, the receiver discards the partially received 805 frames, and the multi-frame session is considered incomplete. 806 807In both cases, if ``SOF_TIMESTAMPING_OPT_ID`` is enabled, ``serr->ee_data`` 808will be set to the session’s unique identifier (``session->tskey``). This 809allows user space to track message transfers by their session identifier across 810multiple frames or stages. 811 812In all other cases, ``serr->ee_errno`` will be set to ``ENOMSG``, except for 813the ``J1939_EE_INFO_TX_ABORT`` and ``J1939_EE_INFO_RX_ABORT`` cases, where the 814kernel sets ``serr->ee_data`` to the error stored in ``session->err``. All 815protocol-specific errors are converted to standard kernel error values and 816stored in ``session->err``. These error values are unified across system calls 817and ``serr->ee_errno``. Some of the known error values are described in the 818`Error Codes in the J1939 Stack` section. 819 820When the `J1939_EE_INFO_RX_RTS` message is provided, it will include the 821following statistics for multi-frame messages (TP and ETP): 822 823 - ``J1939_NLA_TOTAL_SIZE``: Total size of the message in the session. 824 - ``J1939_NLA_PGN``: Parameter Group Number (PGN) identifying the message type. 825 - ``J1939_NLA_SRC_NAME``: 64-bit name of the source ECU. 826 - ``J1939_NLA_DEST_NAME``: 64-bit name of the destination ECU. 827 - ``J1939_NLA_SRC_ADDR``: 8-bit source address of the sending ECU. 828 - ``J1939_NLA_DEST_ADDR``: 8-bit destination address of the receiving ECU. 829 830- For other messages (including single-frame messages), only the following 831 statistic is included: 832 833 - ``J1939_NLA_BYTES_ACKED``: Number of bytes successfully acknowledged in the 834 session. 835 836The key flags for ``SO_TIMESTAMPING`` include: 837 838- ``SOF_TIMESTAMPING_OPT_ID``: Enables the use of a unique session identifier 839 (``tskey``) for each transfer. This identifier helps track message transfers 840 and errors as distinct sessions in user space. When this option is enabled, 841 ``serr->ee_data`` will be set to ``session->tskey``. 842 843- ``SOF_TIMESTAMPING_OPT_CMSG``: Sends timestamp information through control 844 messages (``struct scm_timestamping``), allowing the application to retrieve 845 timestamps alongside the data. 846 847- ``SOF_TIMESTAMPING_TX_SCHED``: Provides the timestamp for when a message is 848 scheduled for transmission (``SCM_TSTAMP_SCHED``). 849 850- ``SOF_TIMESTAMPING_TX_ACK``: Provides the timestamp for when a message 851 transmission is fully acknowledged (``SCM_TSTAMP_ACK``). 852 853- ``SOF_TIMESTAMPING_RX_SOFTWARE``: Provides timestamps for reception-related 854 events (e.g., ``J1939_EE_INFO_RX_RTS``, ``J1939_EE_INFO_RX_DPO``, 855 ``J1939_EE_INFO_RX_ABORT``). 856 857These flags enable detailed monitoring of message lifecycles, including 858transmission scheduling, acknowledgments, reception timestamps, and gathering 859detailed statistics about the communication session, especially for multi-frame 860payloads like TP and ETP. 861 862Example: 863 864.. code-block:: c 865 866 // Enable timestamping with various options, including session tracking and 867 // statistics 868 int sock_opt = SOF_TIMESTAMPING_OPT_CMSG | 869 SOF_TIMESTAMPING_TX_ACK | 870 SOF_TIMESTAMPING_TX_SCHED | 871 SOF_TIMESTAMPING_OPT_ID | 872 SOF_TIMESTAMPING_RX_SOFTWARE; 873 874 setsockopt(sock, SOL_SOCKET, SO_TIMESTAMPING, &sock_opt, sizeof(sock_opt)); 875 876 877 878Dynamic Addressing 879------------------ 880 881Distinction has to be made between using the claimed address and doing an 882address claim. To use an already claimed address, one has to fill in the 883``j1939.name`` member and provide it to ``bind(2)``. If the name had claimed an address 884earlier, all further messages being sent will use that address. And the 885``j1939.addr`` member will be ignored. 886 887An exception on this is PGN 0x0ee00. This is the "Address Claim/Cannot Claim 888Address" message and the kernel will use the ``j1939.addr`` member for that PGN if 889necessary. 890 891To claim an address following code example can be used: 892 893.. code-block:: C 894 895 struct sockaddr_can baddr = { 896 .can_family = AF_CAN, 897 .can_addr.j1939 = { 898 .name = name, 899 .addr = J1939_IDLE_ADDR, 900 .pgn = J1939_NO_PGN, /* to disable bind() rx filter for PGN */ 901 }, 902 .can_ifindex = if_nametoindex("can0"), 903 }; 904 905 bind(sock, (struct sockaddr *)&baddr, sizeof(baddr)); 906 907 /* for Address Claiming broadcast must be allowed */ 908 int value = 1; 909 setsockopt(sock, SOL_SOCKET, SO_BROADCAST, &value, sizeof(value)); 910 911 /* configured advanced RX filter with PGN needed for Address Claiming */ 912 const struct j1939_filter filt[] = { 913 { 914 .pgn = J1939_PGN_ADDRESS_CLAIMED, 915 .pgn_mask = J1939_PGN_PDU1_MAX, 916 }, { 917 .pgn = J1939_PGN_REQUEST, 918 .pgn_mask = J1939_PGN_PDU1_MAX, 919 }, { 920 .pgn = J1939_PGN_ADDRESS_COMMANDED, 921 .pgn_mask = J1939_PGN_MAX, 922 }, 923 }; 924 925 setsockopt(sock, SOL_CAN_J1939, SO_J1939_FILTER, &filt, sizeof(filt)); 926 927 uint64_t dat = htole64(name); 928 const struct sockaddr_can saddr = { 929 .can_family = AF_CAN, 930 .can_addr.j1939 = { 931 .pgn = J1939_PGN_ADDRESS_CLAIMED, 932 .addr = J1939_NO_ADDR, 933 }, 934 }; 935 936 /* Afterwards do a sendto(2) with data set to the NAME (Little Endian). If the 937 * NAME provided, does not match the j1939.name provided to bind(2), EPROTO 938 * will be returned. 939 */ 940 sendto(sock, dat, sizeof(dat), 0, (const struct sockaddr *)&saddr, sizeof(saddr)); 941 942If no-one else contests the address claim within 250ms after transmission, the 943kernel marks the NAME-SA assignment as valid. The valid assignment will be kept 944among other valid NAME-SA assignments. From that point, any socket bound to the 945NAME can send packets. 946 947If another ECU claims the address, the kernel will mark the NAME-SA expired. 948No socket bound to the NAME can send packets (other than address claims). To 949claim another address, some socket bound to NAME, must ``bind(2)`` again, but with 950only ``j1939.addr`` changed to the new SA, and must then send a valid address claim 951packet. This restarts the state machine in the kernel (and any other 952participant on the bus) for this NAME. 953 954``can-utils`` also include the ``j1939acd`` tool, so it can be used as code example or as 955default Address Claiming daemon. 956 957Send Examples 958------------- 959 960Static Addressing 961^^^^^^^^^^^^^^^^^ 962 963This example will send a PGN (0x12300) from SA 0x20 to DA 0x30. 964 965Bind: 966 967.. code-block:: C 968 969 struct sockaddr_can baddr = { 970 .can_family = AF_CAN, 971 .can_addr.j1939 = { 972 .name = J1939_NO_NAME, 973 .addr = 0x20, 974 .pgn = J1939_NO_PGN, 975 }, 976 .can_ifindex = if_nametoindex("can0"), 977 }; 978 979 bind(sock, (struct sockaddr *)&baddr, sizeof(baddr)); 980 981Now, the socket 'sock' is bound to the SA 0x20. Since no ``connect(2)`` was called, 982at this point we can use only ``sendto(2)`` or ``sendmsg(2)``. 983 984Send: 985 986.. code-block:: C 987 988 const struct sockaddr_can saddr = { 989 .can_family = AF_CAN, 990 .can_addr.j1939 = { 991 .name = J1939_NO_NAME; 992 .addr = 0x30, 993 .pgn = 0x12300, 994 }, 995 }; 996 997 sendto(sock, dat, sizeof(dat), 0, (const struct sockaddr *)&saddr, sizeof(saddr)); 998 999 1000Error Codes in the J1939 Stack 1001------------------------------ 1002 1003This section lists all potential kernel error codes that can be exposed to user 1004space when interacting with the J1939 stack. It includes both standard error 1005codes and those derived from protocol-specific abort codes. 1006 1007- ``EAGAIN``: Operation would block; retry may succeed. One common reason is 1008 that an active TP or ETP session exists, and an attempt was made to start a 1009 new overlapping TP or ETP session between the same peers. 1010 1011- ``ENETDOWN``: Network is down. This occurs when the CAN interface is switched 1012 to the "down" state. 1013 1014- ``ENOBUFS``: No buffer space available. This error occurs when the CAN 1015 interface's transmit (TX) queue is full, and no more messages can be queued. 1016 1017- ``EOVERFLOW``: Value too large for defined data type. In J1939, this can 1018 happen if the requested data lies outside of the queued buffer. For example, 1019 if a CTS (Clear to Send) requests an offset not available in the kernel buffer 1020 because user space did not provide enough data. 1021 1022- ``EBUSY``: Device or resource is busy. For example, this occurs if an 1023 identical session is already active and the stack is unable to recover from 1024 the condition. 1025 1026- ``EACCES``: Permission denied. This error can occur, for example, when 1027 attempting to send broadcast messages, but the socket is not configured with 1028 ``SO_BROADCAST``. 1029 1030- ``EADDRNOTAVAIL``: Address not available. This error occurs in cases such as: 1031 1032 - When attempting to use ``getsockname(2)`` to retrieve the peer's address, 1033 but the socket is not connected. 1034 1035 - When trying to send data to or from a NAME, but address claiming for the 1036 NAME was not performed or detected by the stack. 1037 1038- ``EBADFD``: File descriptor in bad state. This error can occur if: 1039 1040 - Attempting to send data to an unbound socket. 1041 1042 - The socket is bound but has no source name, and the source address is 1043 ``J1939_NO_ADDR``. 1044 1045 - The ``can_ifindex`` is incorrect. 1046 1047- ``EFAULT``: Bad address. Occurs mostly when the stack can't copy from or to a 1048 sockptr, when there is insufficient data from user space, or when the buffer 1049 provided by user space is not large enough for the requested data. 1050 1051- ``EINTR``: A signal occurred before any data was transmitted; see ``signal(7)``. 1052 1053- ``EINVAL``: Invalid argument passed. For example: 1054 1055 - ``msg->msg_namelen`` is less than ``J1939_MIN_NAMELEN``. 1056 1057 - ``addr->can_family`` is not equal to ``AF_CAN``. 1058 1059 - An incorrect PGN was provided. 1060 1061- ``ENODEV``: No such device. This happens when the CAN network device cannot 1062 be found for the provided ``can_ifindex`` or if ``can_ifindex`` is 0. 1063 1064- ``ENOMEM``: Out of memory. Typically related to issues with memory allocation 1065 in the stack. 1066 1067- ``ENOPROTOOPT``: Protocol not available. This can occur when using 1068 ``getsockopt(2)`` or ``setsockopt(2)`` if the requested socket option is not 1069 available. 1070 1071- ``EDESTADDRREQ``: Destination address required. This error occurs: 1072 1073 - In the case of ``connect(2)``, if the ``struct sockaddr *uaddr`` is ``NULL``. 1074 1075 - In the case of ``send*(2)``, if there is an attempt to send an ETP message 1076 to a broadcast address. 1077 1078- ``EDOM``: Argument out of domain. This error may happen if attempting to send 1079 a TP or ETP message to a PGN that is reserved for control PGNs for TP or ETP 1080 operations. 1081 1082- ``EIO``: I/O error. This can occur if the amount of data provided to the 1083 socket for a TP or ETP session does not match the announced amount of data for 1084 the session. 1085 1086- ``ENOENT``: No such file or directory. This can happen when the stack 1087 attempts to transfer CTS or EOMA but cannot find a matching receiving socket 1088 anymore. 1089 1090- ``ENOIOCTLCMD``: No ioctls are available for the socket layer. 1091 1092- ``EPERM``: Operation not permitted. For example, this can occur if a 1093 requested action requires ``CAP_NET_ADMIN`` privileges. 1094 1095- ``ENETUNREACH``: Network unreachable. Most likely, this occurs when frames 1096 cannot be transmitted to the CAN bus. 1097 1098- ``ETIME``: Timer expired. This can happen if a timeout occurs while 1099 attempting to send a simple message, for example, when an echo message from 1100 the controller is not received. 1101 1102- ``EPROTO``: Protocol error. 1103 1104 - Used for various protocol-level errors in J1939, including: 1105 1106 - Duplicate sequence number. 1107 1108 - Unexpected EDPO or ECTS packet. 1109 1110 - Invalid PGN or offset in EDPO/ECTS. 1111 1112 - Number of EDPO packets exceeded CTS allowance. 1113 1114 - Any other protocol-level error. 1115 1116- ``EMSGSIZE``: Message too long. 1117 1118- ``ENOMSG``: No message available. 1119 1120- ``EALREADY``: The ECU is already engaged in one or more connection-managed 1121 sessions and cannot support another. 1122 1123- ``EHOSTUNREACH``: A timeout occurred, and the session was aborted. 1124 1125- ``EBADMSG``: CTS (Clear to Send) messages were received during an active data 1126 transfer, causing an abort. 1127 1128- ``ENOTRECOVERABLE``: The maximum retransmission request limit was reached, 1129 and the session cannot recover. 1130 1131- ``ENOTCONN``: An unexpected data transfer packet was received. 1132 1133- ``EILSEQ``: A bad sequence number was received, and the software could not 1134 recover. 1135
~/
Read-only file preview.