Lines Matching +full:multi +full:- +full:socket
1 .. SPDX-License-Identifier: (GPL-2.0 OR MIT)
14 ISO-11783 (ISOBUS). This last one specifies the so-called ETP (Extended
16 results in a maximum packet size of ((2 ^ 24) - 1) * 7 bytes == 111 MiB.
19 -------------------
21 * SAE J1939-21 : data link layer
22 * SAE J1939-81 : network management
23 * ISO 11783-6 : Virtual Terminal (Extended Transport Protocol)
25 .. _j1939-motivation:
56 ...). In-kernel code for these would not contribute to protocol stability.
61 Since such a library does not communicate with the in-kernel implementation, care
64 the library exclusively, or by the in-kernel system exclusively.
70 ----------------------------
80 - **Buffers with a size of 8 bytes or less:**
82 - These are handled as simple sessions internally within the stack.
84 - The stack converts the buffer directly into a single CAN frame without
87 - This type of transfer does not require an actual client (receiver) on the
90 - **Buffers up to 1785 bytes:**
92 - These are automatically handled as J1939 Transport Protocol (TP) transfers.
94 - Internally, the stack splits the buffer into multiple 8-byte CAN frames.
96 - TP transfers can be unicast or broadcast.
98 - **Broadcast TP:** Does not require a receiver on the other side and can be
101 - **Unicast TP:** Requires an active receiver (client) on the other side to
104 - **Buffers from 1786 bytes up to 111 MiB:**
106 - These are handled as ISO 11783 Extended Transport Protocol (ETP) transfers.
108 - ETP transfers are used for larger payloads and are split into multiple CAN
111 - **ETP transfers (unicast):** Require a receiver on the other side to
114 - ETP transfers cannot be broadcast like TP transfers, and always require a
117 **Non-Blocking Operation with `MSG_DONTWAIT`:**
119 The J1939 stack supports non-blocking operation when used in combination with
121 as the available memory for the socket allows. It returns the amount of data
125 - If the stack cannot take the entire buffer, it returns the number of bytes
128 - **Error handling:** When using `MSG_DONTWAIT`, the user must rely on the
132 during non-blocking operations.
136 - **Simple transfers (<= 8 bytes):** Do not require a receiver on the other
140 - **Unicast TP/ETP:** Requires a receiver on the other side to complete the
144 - **Broadcast TP:** Allows sending data without a receiver, but only works for
154 ---
156 The J1939 protocol uses the 29-bit CAN identifier with the following structure:
159 29 bit CAN-ID
160 --------------------------------------------------
161 Bit positions within the CAN-ID
162 --------------------------------------------------
173 ------------------------------------------------------------------
174 Bit positions within the CAN-ID
175 ------------------------------------------------------------------
181 In J1939-21 distinction is made between PDU1 format (where PF < 240) and PDU2
182 format (where PF >= 240). Furthermore, when using the PDU2 format, the PS-field
183 contains a so-called Group Extension, which is part of the PGN. When using PDU2
184 format, the Group Extension is set in the PS-field.
188 ----------------------------------------
189 Bit positions within the CAN-ID
190 ----------------------------------------
198 ----------------------------------------
199 Bit positions within the CAN-ID
200 ----------------------------------------
206 On the other hand, when using PDU1 format, the PS-field contains a so-called
208 from user space to kernel (or vice versa) and PDU1 format is used, the PS-field
212 Regarding PGN mapping to 29-bit CAN identifier, the Destination Address shall
217 ----------
225 For dynamic addressing, so-called Address Claiming, extra support is foreseen
226 in the kernel. In J1939 any ECU is known by its 64-bit NAME. At the moment of
236 ---------
238 J1939 defines white list filters per socket that a user can set in order to
245 When multiple filters are in place for a single socket, and a packet comes in
247 that socket.
253 ---------
255 On CAN, you first need to open a socket for communicating over a CAN network.
257 included too. To open a socket, use:
259 .. code-block:: C
261 s = socket(PF_CAN, SOCK_DGRAM, CAN_J1939);
268 After the successful creation of the socket, you would normally use the ``bind(2)``
269 and/or ``connect(2)`` system call to bind the socket to a CAN interface. After
270 binding and/or connecting the socket, you can ``read(2)`` and ``write(2)`` from/to the
271 socket or use ``send(2)``, ``sendto(2)``, ``sendmsg(2)`` and the ``recv*()`` counterpart
272 operations on the socket as usual. There are also J1939 specific socket options
276 local address to a socket.
285 .. code-block:: C
310 ``can_addr.j1939.name`` contains the 64-bit J1939 NAME.
336 When creating a socket, reasonable defaults are set. Some options can be
341 - ``SO_J1939_FILTER`` - configure array of filters
342 - ``SO_J1939_PROMISC`` - disable filters set by ``bind(2)`` and ``connect(2)``
345 receiving broadcast packets use the socket option ``SO_BROADCAST``:
347 .. code-block:: C
356 +--------------------+
358 +--------------------+
361 +--------------------+
363 +--------------------+
367 .---------' `---------.
369 +---------------------------+ |
372 +---------------------------+ |
374 |<---------------------'
376 +---------------------------+
378 +---------------------------+
381 +---------------------------+
382 | socket recv() |
383 +---------------------------+
386 ``SO_J1939_SEND_PRIO`` - change default send priority for the socket
394 * ``MSG_DONTWAIT``, i.e. non-blocking operation.
407 .. code-block:: C
413 switch (cmsg->cmsg_level) {
415 if (cmsg->cmsg_type == SCM_J1939_DEST_ADDR)
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)
428 The ``setsockopt(2)`` function is used to configure various socket-level
436 default, ``bind(2)`` and ``connect(2)`` allow a socket to be associated with a
448 - **Source Address (SA)**: Filter messages coming from specific source
451 - **Source Name**: Filter messages coming from ECUs with specific NAME
454 - **Parameter Group Number (PGN)**: Focus on receiving messages with specific
459 - You want to receive a subset of messages based on their PGNs, even if the
462 - You need to handle both broadcast and unicast messages but only care about
465 - The ``bind(2)`` and ``connect(2)`` functions only allow binding to a single
478 .. code-block:: c
495 .. code-block:: c
511 In this example, the socket will only receive messages with the PGNs related to
520 The ``SO_J1939_PROMISC`` option enables socket-level promiscuous mode. When
521 this option is enabled, the socket will receive all J1939 traffic, regardless
530 socket, allowing for more refined traffic selection while promiscuous mode is
534 only differentiated between `0` and non-zero. A value of `0` disables
535 promiscuous mode, while any non-zero value enables it.
542 .. code-block:: c
547 In this example, setting ``value`` to any non-zero value (e.g., `1`) enables
548 promiscuous mode, allowing the socket to receive all J1939 traffic on the
556 this option is enabled, the socket will be allowed to send and receive
564 broadcast option allows the socket to send and receive such broadcast messages.
567 only differentiated between `0` and non-zero. A value of `0` disables the
568 ability to send and receive broadcast messages, while any non-zero value
573 .. code-block:: c
578 In this example, setting ``value`` to any non-zero value (e.g., `1`) enables
579 the socket to send and receive broadcast messages.
585 for the socket. In J1939, messages can have different priorities, and lower
587 control the priority of messages sent from the socket by adjusting the priority
596 the `CAP_NET_ADMIN` capability. These are reserved for high-priority traffic
601 .. code-block:: c
612 The ``SO_J1939_ERRQUEUE`` option enables the socket to receive error messages
625 - **``J1939_EE_INFO_TX_ABORT``**: Transmission abort errors.
626 - **``J1939_EE_INFO_RX_RTS``**: Reception of RTS (Request to Send) control
628 - **``J1939_EE_INFO_RX_DPO``**: Reception of data packets with Data Page Offset
630 - **``J1939_EE_INFO_RX_ABORT``**: Reception abort errors.
640 error messages. Failure to do so can result in the socket becoming blocked with
649 is only differentiated between ``0`` and non-zero. A value of ``0`` disables
651 non-zero value enables it.
655 .. code-block:: c
679 The ``SO_TIMESTAMPING`` option allows the socket to receive timestamps for
686 processed by the kernel as **sessions**. This includes both single-frame
687 messages (up to 8 bytes) and multi-frame protocols such as the Transport
689 single-frame messages, the kernel creates a session to manage the transmission
691 aspects of the protocol, such as reassembling multi-frame messages and tracking
700 1. ``serr->ee_origin == SO_EE_ORIGIN_TIMESTAMPING``:
702 In this case, the `serr->ee_info` field will contain one of the following
705 - ``SCM_TSTAMP_SCHED``: This timestamp is valid for Extended Transport
710 - For simple transfers (8 bytes or less), it marks the point when the
713 - For ETP transfers, it is sent after receiving a CTS (Clear to Send)
717 - The Transport Protocol (TP) case is currently not implemented for this
720 - On the receiver side, the counterpart to this event for ETP is
724 - ``SCM_TSTAMP_ACK``: This timestamp indicates the acknowledgment of the
727 - For simple transfers (8 bytes or less), it marks when the message has
731 - For multi-frame transfers (TP or ETP), it signifies that the entire
735 2. ``serr->ee_origin == SO_EE_ORIGIN_LOCAL``:
737 In this case, the `serr->ee_info` field will contain one of the following
738 J1939 stack-specific message types:
740 - ``J1939_EE_INFO_TX_ABORT``: This message indicates that the transmission
744 - **CAN stack failure**: The J1939 stack was unable to pass the frame to
747 - **Echo failure**: The J1939 stack did not receive an echo confirmation
751 - **Protocol-level issues**: For multi-frame transfers (TP/ETP), this
752 could include protocol-related errors, such as an abort signaled by the
756 - The corresponding error code is stored in ``serr->ee_data``
757 (``session->err`` on kernel side), providing additional details about
760 - ``J1939_EE_INFO_RX_RTS``: This message indicates that the J1939 stack has
762 multi-frame transfer using the Transport Protocol (TP) or Extended
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
769 - Statistics such as ``J1939_NLA_TOTAL_SIZE``, ``J1939_NLA_PGN``,
774 - ``J1939_EE_INFO_RX_DPO``: This message indicates that the J1939 stack has
778 - The DPO frame signals the continuation of an ETP multi-frame message by
783 - It is typically paired with a corresponding ``SCM_TSTAMP_SCHED`` event
787 - This event includes statistics such as ``J1939_NLA_BYTES_ACKED``, which
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
794 - The abort can be triggered by protocol-level errors such as timeouts, an
797 - This message signals that the receiver cannot continue processing the
800 - The corresponding error code is stored in ``serr->ee_data``
801 (``session->err`` on kernel side ), providing further details about the
804 - After receiving this message, the receiver discards the partially received
805 frames, and the multi-frame session is considered incomplete.
807 In both cases, if ``SOF_TIMESTAMPING_OPT_ID`` is enabled, ``serr->ee_data``
808 will be set to the session’s unique identifier (``session->tskey``). This
812 In all other cases, ``serr->ee_errno`` will be set to ``ENOMSG``, except for
814 kernel sets ``serr->ee_data`` to the error stored in ``session->err``. All
815 protocol-specific errors are converted to standard kernel error values and
816 stored in ``session->err``. These error values are unified across system calls
817 and ``serr->ee_errno``. Some of the known error values are described in the
821 following statistics for multi-frame messages (TP and ETP):
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.
830 - For other messages (including single-frame messages), only the following
833 - ``J1939_NLA_BYTES_ACKED``: Number of bytes successfully acknowledged in the
838 - ``SOF_TIMESTAMPING_OPT_ID``: Enables the use of a unique session identifier
841 ``serr->ee_data`` will be set to ``session->tskey``.
843 - ``SOF_TIMESTAMPING_OPT_CMSG``: Sends timestamp information through control
847 - ``SOF_TIMESTAMPING_TX_SCHED``: Provides the timestamp for when a message is
850 - ``SOF_TIMESTAMPING_TX_ACK``: Provides the timestamp for when a message
853 - ``SOF_TIMESTAMPING_RX_SOFTWARE``: Provides timestamps for reception-related
859 detailed statistics about the communication session, especially for multi-frame
864 .. code-block:: c
879 ------------------
893 .. code-block:: C
942 If no-one else contests the address claim within 250ms after transmission, the
943 kernel marks the NAME-SA assignment as valid. The valid assignment will be kept
944 among other valid NAME-SA assignments. From that point, any socket bound to the
947 If another ECU claims the address, the kernel will mark the NAME-SA expired.
948 No socket bound to the NAME can send packets (other than address claims). To
949 claim another address, some socket bound to NAME, must ``bind(2)`` again, but with
954 ``can-utils`` also include the ``j1939acd`` tool, so it can be used as code example or as
958 -------------
967 .. code-block:: C
981 Now, the socket 'sock' is bound to the SA 0x20. Since no ``connect(2)`` was called,
986 .. code-block:: C
1001 ------------------------------
1005 codes and those derived from protocol-specific abort codes.
1007 - ``EAGAIN``: Operation would block; retry may succeed. One common reason is
1011 - ``ENETDOWN``: Network is down. This occurs when the CAN interface is switched
1014 - ``ENOBUFS``: No buffer space available. This error occurs when the CAN
1017 - ``EOVERFLOW``: Value too large for defined data type. In J1939, this can
1022 - ``EBUSY``: Device or resource is busy. For example, this occurs if an
1026 - ``EACCES``: Permission denied. This error can occur, for example, when
1027 attempting to send broadcast messages, but the socket is not configured with
1030 - ``EADDRNOTAVAIL``: Address not available. This error occurs in cases such as:
1032 - When attempting to use ``getsockname(2)`` to retrieve the peer's address,
1033 but the socket is not connected.
1035 - When trying to send data to or from a NAME, but address claiming for the
1038 - ``EBADFD``: File descriptor in bad state. This error can occur if:
1040 - Attempting to send data to an unbound socket.
1042 - The socket is bound but has no source name, and the source address is
1045 - The ``can_ifindex`` is incorrect.
1047 - ``EFAULT``: Bad address. Occurs mostly when the stack can't copy from or to a
1051 - ``EINTR``: A signal occurred before any data was transmitted; see ``signal(7)``.
1053 - ``EINVAL``: Invalid argument passed. For example:
1055 - ``msg->msg_namelen`` is less than ``J1939_MIN_NAMELEN``.
1057 - ``addr->can_family`` is not equal to ``AF_CAN``.
1059 - An incorrect PGN was provided.
1061 - ``ENODEV``: No such device. This happens when the CAN network device cannot
1064 - ``ENOMEM``: Out of memory. Typically related to issues with memory allocation
1067 - ``ENOPROTOOPT``: Protocol not available. This can occur when using
1068 ``getsockopt(2)`` or ``setsockopt(2)`` if the requested socket option is not
1071 - ``EDESTADDRREQ``: Destination address required. This error occurs:
1073 - In the case of ``connect(2)``, if the ``struct sockaddr *uaddr`` is ``NULL``.
1075 - In the case of ``send*(2)``, if there is an attempt to send an ETP message
1078 - ``EDOM``: Argument out of domain. This error may happen if attempting to send
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
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
1090 - ``ENOIOCTLCMD``: No ioctls are available for the socket layer.
1092 - ``EPERM``: Operation not permitted. For example, this can occur if a
1095 - ``ENETUNREACH``: Network unreachable. Most likely, this occurs when frames
1098 - ``ETIME``: Timer expired. This can happen if a timeout occurs while
1102 - ``EPROTO``: Protocol error.
1104 - Used for various protocol-level errors in J1939, including:
1106 - Duplicate sequence number.
1108 - Unexpected EDPO or ECTS packet.
1110 - Invalid PGN or offset in EDPO/ECTS.
1112 - Number of EDPO packets exceeded CTS allowance.
1114 - Any other protocol-level error.
1116 - ``EMSGSIZE``: Message too long.
1118 - ``ENOMSG``: No message available.
1120 - ``EALREADY``: The ECU is already engaged in one or more connection-managed
1123 - ``EHOSTUNREACH``: A timeout occurred, and the session was aborted.
1125 - ``EBADMSG``: CTS (Clear to Send) messages were received during an active data
1128 - ``ENOTRECOVERABLE``: The maximum retransmission request limit was reached,
1131 - ``ENOTCONN``: An unexpected data transfer packet was received.
1133 - ``EILSEQ``: A bad sequence number was received, and the software could not