Lines Matching +full:echo +full:- +full:active +full:- +full:ms
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
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 ---------
253 ---------
259 .. code-block:: C
285 .. code-block:: C
310 ``can_addr.j1939.name`` contains the 64-bit J1939 NAME.
341 - ``SO_J1939_FILTER`` - configure array of filters
342 - ``SO_J1939_PROMISC`` - disable filters set by ``bind(2)`` and ``connect(2)``
347 .. code-block:: C
356 +--------------------+
358 +--------------------+
361 +--------------------+
363 +--------------------+
367 .---------' `---------.
369 +---------------------------+ |
372 +---------------------------+ |
374 |<---------------------'
376 +---------------------------+
378 +---------------------------+
381 +---------------------------+
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
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
520 The ``SO_J1939_PROMISC`` option enables socket-level promiscuous mode. When
531 active.
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
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
596 the `CAP_NET_ADMIN` capability. These are reserved for high-priority traffic
601 .. code-block:: c
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.
649 is only differentiated between ``0`` and non-zero. A value of ``0`` disables
651 non-zero value enables it.
655 .. code-block:: c
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
728 been sent and an echo confirmation has been received from the CAN
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.
954 ``can-utils`` also include the ``j1939acd`` tool, so it can be used as code example or as
958 -------------
967 .. code-block:: C
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
1008 that an active TP or ETP session exists, and an attempt was made to start a
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
1023 identical session is already active and the stack is unable to recover from
1026 - ``EACCES``: Permission denied. This error can occur, for example, when
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,
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
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
1086 - ``ENOENT``: No such file or directory. This can happen when the stack
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
1099 attempting to send a simple message, for example, when an echo message from
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