Lines Matching +full:address +full:- +full:address +full:- +full:data
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:
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
42 * **Dynamic addressing:** Address Claiming in J1939 is time critical.
43 Furthermore, data transport should be handled properly during the address
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
63 cannot share ECU addresses. A single ECU (or virtual ECU) address is used by
64 the library exclusively, or by the in-kernel system exclusively.
69 Data Sent to the J1939 Stack
70 ----------------------------
72 The data buffers sent to the J1939 stack from user space are not CAN frames
75 size of the buffer influences how the stack processes the data and determines
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
112 process the incoming data and acknowledge each step of the transfer.
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
120 the `MSG_DONTWAIT` flag. In this mode, the stack attempts to take as much data
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
137 side, making them easy to send without needing address claiming or
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 --------------------------------------------------
165 Priority PGN SA (Source Address)
173 ------------------------------------------------------------------
174 Bit positions within the CAN-ID
175 ------------------------------------------------------------------
178 R (Reserved) DP (Data Page) PF (PDU Format) PS (PDU Specific)
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 ----------------------------------------
193 00h ... EFh DA (Destination address)
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
207 Destination Address, which is _not_ part of the PGN. When communicating a PGN
208 from user space to kernel (or vice versa) and PDU1 format is used, the PS-field
209 of the PGN shall be set to zero. The Destination Address shall be set
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
227 a successful address claim, the kernel keeps track of both NAME and source
228 address being claimed. This serves as a base for filter schemes. By default,
231 Mixed mode packets (from a static to a dynamic address or vice versa) are
233 local & remote address and are applicable for J1939 sockets.
236 ---------
253 ---------
259 .. code-block:: C
275 In order to send data, a ``bind(2)`` must have been successful. ``bind(2)`` assigns a
276 local address to a socket.
278 Different from CAN is that the payload data is just the data that get sends,
285 .. code-block:: C
310 ``can_addr.j1939.name`` contains the 64-bit J1939 NAME.
312 ``can_addr.j1939.addr`` contains the address.
314 The ``bind(2)`` system call assigns the local address, i.e. the source address when
318 of the incoming packet. The NAME filter will work only if appropriate Address
322 On the other hand ``connect(2)`` assigns the remote address, i.e. the destination
323 address. The PGN from ``connect(2)`` is used as the default PGN when sending
328 Both ``write(2)`` and ``send(2)`` will send a packet with local address from ``bind(2)`` and the
329 remote address from ``connect(2)``. Use ``sendto(2)`` to overwrite the destination
330 address.
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.
401 Destination Address, name and packet priority (if applicable) are attached to
404 ``SCM_J1939_DEST_NAME`` or ``SCM_J1939_PRIO``. The returned data is a ``uint8_t`` for
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
437 single unicast or broadcast address. However, there are scenarios where finer
444 address or broadcast to the bus.
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
460 address is the same.
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
466 address, which might not be sufficient if the process needs to handle multiple
478 .. code-block:: c
487 Practical use case: **Monitoring Address Claiming**
489 One practical use case is monitoring the J1939 address claiming process by
490 filtering for specific PGNs related to address claiming. This allows a process
491 to monitor and handle address claims without processing unrelated messages.
495 .. code-block:: c
512 address claiming: ``J1939_PGN_ADDRESS_CLAIMED``, ``J1939_PGN_REQUEST``, and
514 you want to monitor and process address claims without being overwhelmed by
520 The ``SO_J1939_PROMISC`` option enables socket-level promiscuous mode. When
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
561 broadcasting refers to using a specific destination address field, where the
562 destination address is set to a value that indicates the message is intended
563 for all participants (usually a global address such as 0xFF). Enabling the
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
682 detailed diagnostic information, session tracking, and precise timing data 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
722 reception of a Data Page Offset (DPO) control frame.
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
775 received a Data Page Offset (DPO) control frame, which is part of the
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
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
845 timestamps alongside the data.
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 ------------------
881 Distinction has to be made between using the claimed address and doing an
882 address 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
884 earlier, all further messages being sent will use that address. And the
887 An exception on this is PGN 0x0ee00. This is the "Address Claim/Cannot Claim
888 Address" message and the kernel will use the ``j1939.addr`` member for that PGN if
891 To claim an address following code example can be used:
893 .. code-block:: C
907 /* for Address Claiming broadcast must be allowed */
911 /* configured advanced RX filter with PGN needed for Address Claiming */
936 /* Afterwards do a sendto(2) with data set to the NAME (Little Endian). If the
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
950 only ``j1939.addr`` changed to the new SA, and must then send a valid address claim
954 ``can-utils`` also include the ``j1939acd`` tool, so it can be used as code example or as
955 default Address Claiming daemon.
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
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
1018 happen if the requested data lies outside of the queued buffer. For example,
1020 because user space did not provide enough data.
1022 - ``EBUSY``: Device or resource is busy. For example, this occurs if an
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
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.
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
1076 to a broadcast address.
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
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