SO_J1939_FILTER¶

TheSO_J1939_FILTER option is essential when the default behavior ofbind(2) andconnect(2) is insufficient for specific use cases. Bydefault,bind(2) andconnect(2) allow a socket to be associated with asingle unicast or broadcast address. However, there are scenarios where finercontrol over the incoming messages is required, such as filtering by ParameterGroup Number (PGN) rather than by addresses.

For example, in a system where multiple types of J1939 messages are beingtransmitted, a process might only be interested in a subset of those messages,such as specific PGNs, and not want to receive all messages destined for itsaddress or broadcast to the bus.

By applying theSO_J1939_FILTER option, you can filter messages based on:

• Source Address (SA): Filter messages coming from specific sourceaddresses.

• Source Name: Filter messages coming from ECUs with specific NAMEidentifiers.

• Parameter Group Number (PGN): Focus on receiving messages with specificPGNs, filtering out irrelevant ones.

This filtering mechanism is particularly useful when:

• You want to receive a subset of messages based on their PGNs, even if theaddress is the same.

• You need to handle both broadcast and unicast messages but only care aboutcertain message types or parameters.

• Thebind(2) andconnect(2) functions only allow binding to a singleaddress, which might not be sufficient if the process needs to handle multiplePGNs but does not want to open multiple sockets.

To remove existing filters, you can passoptval==NULL oroptlen==0tosetsockopt(2). This will clear all currently set filters. If you want toupdate the set of filters, you must pass the updated filter set tosetsockopt(2), as the new filter set willreplace the old one entirely.This behavior ensures that any previous filter configuration is discarded andonly the new set is applied.

Example of removing all filters:

setsockopt(sock,SOL_CAN_J1939,SO_J1939_FILTER,NULL,0);

Maximum number of filters: The maximum amount of filters that can beapplied usingSO_J1939_FILTER is defined byJ1939_FILTER_MAX, which isset to 512. This means you can configure up to 512 individual filters to matchyour specific filtering needs.

Practical use case:Monitoring Address Claiming

One practical use case is monitoring the J1939 address claiming process byfiltering for specific PGNs related to address claiming. This allows a processto monitor and handle address claims without processing unrelated messages.

Example:

structj1939_filterfilt[]={{.pgn=J1939_PGN_ADDRESS_CLAIMED,.pgn_mask=J1939_PGN_PDU1_MAX,},{.pgn=J1939_PGN_REQUEST,.pgn_mask=J1939_PGN_PDU1_MAX,},{.pgn=J1939_PGN_ADDRESS_COMMANDED,.pgn_mask=J1939_PGN_MAX,},};setsockopt(sock,SOL_CAN_J1939,SO_J1939_FILTER,&filt,sizeof(filt));

In this example, the socket will only receive messages with the PGNs related toaddress claiming:J1939_PGN_ADDRESS_CLAIMED,J1939_PGN_REQUEST, andJ1939_PGN_ADDRESS_COMMANDED. This is particularly useful in scenarios whereyou want to monitor and process address claims without being overwhelmed byother traffic on the J1939 network.

SO_J1939_PROMISC¶

TheSO_J1939_PROMISC option enables socket-level promiscuous mode. Whenthis option is enabled, the socket will receive all J1939 traffic, regardlessof any filters set bybind() orconnect(). This is analogous toenabling promiscuous mode for an Ethernet interface, where all traffic on thenetwork segment is captured.

However,`SO_J1939_FILTER` has a higher priority compared toSO_J1939_PROMISC. This means that even in promiscuous mode, you can reducethe number of packets received by applying specific filters withSO_J1939_FILTER. The filters will limit which packets are passed to thesocket, allowing for more refined traffic selection while promiscuous mode isactive.

The acceptable value size for this option issizeof(int), and the value isonly differentiated between0 and non-zero. A value of0 disablespromiscuous mode, while any non-zero value enables it.

This combination can be useful for debugging or monitoring specific types oftraffic while still capturing a broad set of messages.

Example:

intvalue=1;setsockopt(sock,SOL_CAN_J1939,SO_J1939_PROMISC,&value,sizeof(value));

In this example, settingvalue to any non-zero value (e.g.,1) enablespromiscuous mode, allowing the socket to receive all J1939 traffic on thenetwork.

SO_BROADCAST¶

TheSO_BROADCAST option enables the sending and receiving of broadcastmessages. By default, broadcast messages are disabled for J1939 sockets. Whenthis option is enabled, the socket will be allowed to send and receivebroadcast packets on the J1939 network.

Due to the nature of the CAN bus as a shared medium, all messages transmittedon the bus are visible to all participants. In the context of J1939,broadcasting refers to using a specific destination address field, where thedestination address is set to a value that indicates the message is intendedfor all participants (usually a global address such as 0xFF). Enabling thebroadcast option allows the socket to send and receive such broadcast messages.

The acceptable value size for this option issizeof(int), and the value isonly differentiated between0 and non-zero. A value of0 disables theability to send and receive broadcast messages, while any non-zero valueenables it.

Example:

intvalue=1;setsockopt(sock,SOL_SOCKET,SO_BROADCAST,&value,sizeof(value));

In this example, settingvalue to any non-zero value (e.g.,1) enablesthe socket to send and receive broadcast messages.

SO_J1939_SEND_PRIO¶

TheSO_J1939_SEND_PRIO option sets the priority of outgoing J1939 messagesfor the socket. In J1939, messages can have different priorities, and lowernumerical values indicate higher priority. This option allows the user tocontrol the priority of messages sent from the socket by adjusting the prioritybits in the CAN identifier.

The acceptable valuesize for this option issizeof(int), and the valueis expected to be in the range of 0 to 7, where0 is the highest priority,and7 is the lowest. By default, the priority is set to6 if this option isnot explicitly configured.

Note that the priority values0 and1 can only be set if the process hastheCAP_NET_ADMIN capability. These are reserved for high-priority trafficand require administrative privileges.

Example:

intprio=3;// Priority value between 0 (highest) and 7 (lowest)setsockopt(sock,SOL_CAN_J1939,SO_J1939_SEND_PRIO,&prio,sizeof(prio));

In this example, the priority is set to3, meaning the outgoing messages willbe sent with a moderate priority level.

SO_J1939_ERRQUEUE¶

TheSO_J1939_ERRQUEUE option enables the socket to receive error messagesfrom the error queue, providing diagnostic information about transmissionfailures, protocol violations, or other issues that occur during J1939communication. Once this option is set, user space is required to handleMSG_ERRQUEUE messages.

SettingSO_J1939_ERRQUEUE to0 will purge any currently present errormessages in the error queue. When enabled, error messages can be retrievedusing therecvmsg(2) system call.

When subscribing to the error queue, the following error events can beaccessed:

• ``J1939_EE_INFO_TX_ABORT``: Transmission abort errors.

• ``J1939_EE_INFO_RX_RTS``: Reception of RTS (Request to Send) controlframes.

• ``J1939_EE_INFO_RX_DPO``: Reception of data packets with Data Page Offset(DPO).

• ``J1939_EE_INFO_RX_ABORT``: Reception abort errors.

The error queue can be used to correlate errors with specific message transfersessions using the session ID (tskey). The session ID is assigned via theSOF_TIMESTAMPING_OPT_ID flag, which is set by enabling theSO_TIMESTAMPING option.

IfSO_J1939_ERRQUEUE is activated, the user is required to pull messagesfrom the error queue, meaning that using plainrecv(2) is not sufficientanymore. The user must userecvmsg(2) with appropriate flags to handleerror messages. Failure to do so can result in the socket becoming blocked withunprocessed error messages in the queue.

It isrecommended thatSO_J1939_ERRQUEUE be used in combination withSO_TIMESTAMPING in most cases. This enables proper error handling alongwith session tracking and timestamping, providing a more detailed analysis ofmessage transfers and errors.

The acceptable valuesize for this option issizeof(int), and the valueis only differentiated between0 and non-zero. A value of0 disableserror queue reception and purges any existing error messages, while anynon-zero value enables it.

Example:

intenable=1;// Enable error queue receptionsetsockopt(sock,SOL_CAN_J1939,SO_J1939_ERRQUEUE,&enable,sizeof(enable));// Enable timestamping with session tracking via tskeyinttimestamping=SOF_TIMESTAMPING_OPT_ID|SOF_TIMESTAMPING_TX_ACK|SOF_TIMESTAMPING_TX_SCHED|SOF_TIMESTAMPING_RX_SOFTWARE|SOF_TIMESTAMPING_OPT_CMSG;setsockopt(sock,SOL_SOCKET,SO_TIMESTAMPING,&timestamping,sizeof(timestamping));

When enabled, error messages can be retrieved usingrecvmsg(2). BycombiningSO_J1939_ERRQUEUE withSO_TIMESTAMPING (withSOF_TIMESTAMPING_OPT_ID andSOF_TIMESTAMPING_OPT_CMSG enabled), theuser can track message transfers, retrieve precise timestamps, and correlateerrors with specific sessions.

For more information on enabling timestamps and session tracking, refer to theSO_TIMESTAMPING section.

SO_TIMESTAMPING¶

TheSO_TIMESTAMPING option allows the socket to receive timestamps forvarious events related to message transmissions and receptions in J1939. Thisoption is often used in combination withSO_J1939_ERRQUEUE to providedetailed diagnostic information, session tracking, and precise timing data formessage transfers.

In J1939, all payloads provided by user space, regardless of size, areprocessed by the kernel assessions. This includes both single-framemessages (up to 8 bytes) and multi-frame protocols such as the TransportProtocol (TP) and Extended Transport Protocol (ETP). Even for small,single-frame messages, the kernel creates a session to manage the transmissionand reception. The concept of sessions allows the kernel to manage variousaspects of the protocol, such as reassembling multi-frame messages and trackingthe status of transmissions.

When receiving extended error messages from the error queue, the errorinformation is delivered through astructsock_extended_err, accessible viathe control message (cmsg) retrieved using therecvmsg(2) system call.

There are two typical origins for the extended error messages in J1939:

1. serr->ee_origin==SO_EE_ORIGIN_TIMESTAMPING:

   In this case, theserr->ee_info field will contain one of the followingtimestamp types:

   • SCM_TSTAMP_SCHED: This timestamp is valid for Extended TransportProtocol (ETP) transfers and simple transfers (8 bytes or less). Itindicates when a message or set of frames has been scheduled fortransmission.

     • For simple transfers (8 bytes or less), it marks the point when themessage is queued and ready to be sent onto the CAN bus.

     • For ETP transfers, it is sent after receiving a CTS (Clear to Send)frame on the sender side, indicating that a new set of frames has beenscheduled for transmission.

     • The Transport Protocol (TP) case is currently not implemented for thistimestamp.

     • On the receiver side, the counterpart to this event for ETP isrepresented by theJ1939_EE_INFO_RX_DPO message, which indicates thereception of a Data Page Offset (DPO) control frame.

   • SCM_TSTAMP_ACK: This timestamp indicates the acknowledgment of themessage or session.

     • For simple transfers (8 bytes or less), it marks when the message hasbeen sent and an echo confirmation has been received from the CANcontroller, indicating that the frame was transmitted onto the bus.

     • For multi-frame transfers (TP or ETP), it signifies that the entiresession has been acknowledged, typically after receiving the End ofMessage Acknowledgment (EOMA) packet.

2. serr->ee_origin==SO_EE_ORIGIN_LOCAL:

   In this case, theserr->ee_info field will contain one of the followingJ1939 stack-specific message types:

   • J1939_EE_INFO_TX_ABORT: This message indicates that the transmissionof a message or session was aborted. The cause of the abort can come fromvarious sources:

     • CAN stack failure: The J1939 stack was unable to pass the frame tothe CAN framework for transmission.

     • Echo failure: The J1939 stack did not receive an echo confirmationfrom the CAN controller, meaning the frame may not have been successfullytransmitted to the CAN bus.

     • Protocol-level issues: For multi-frame transfers (TP/ETP), thiscould include protocol-related errors, such as an abort signaled by thereceiver or a timeout at the protocol level, which causes the session toterminate prematurely.

     • The corresponding error code is stored inserr->ee_data(session->err on kernel side), providing additional details aboutthe specific reason for the abort.

   • J1939_EE_INFO_RX_RTS: This message indicates that the J1939 stack hasreceived a Request to Send (RTS) control frame, signaling the start of amulti-frame transfer using the Transport Protocol (TP) or ExtendedTransport Protocol (ETP).

     • It informs the receiver that the sender is ready to transmit amulti-frame message and includes details about the total message sizeand the number of frames to be sent.

     • Statistics such asJ1939_NLA_TOTAL_SIZE,J1939_NLA_PGN,J1939_NLA_SRC_NAME, andJ1939_NLA_DEST_NAME are provided alongwith theJ1939_EE_INFO_RX_RTS message, giving detailed informationabout the incoming transfer.

   • J1939_EE_INFO_RX_DPO: This message indicates that the J1939 stack hasreceived a Data Page Offset (DPO) control frame, which is part of theExtended Transport Protocol (ETP).

     • The DPO frame signals the continuation of an ETP multi-frame message byindicating the offset position in the data being transferred. It helpsthe receiver manage large data sets by identifying which portion of themessage is being received.

     • It is typically paired with a correspondingSCM_TSTAMP_SCHED eventon the sender side, which indicates when the next set of frames isscheduled for transmission.

     • This event includes statistics such asJ1939_NLA_BYTES_ACKED, whichtracks the number of bytes acknowledged up to that point in the session.

   • J1939_EE_INFO_RX_ABORT: This message indicates that the reception of amulti-frame message (Transport Protocol or Extended Transport Protocol) hasbeen aborted.

     • The abort can be triggered by protocol-level errors such as timeouts, anunexpected frame, or a specific abort request from the sender.

     • This message signals that the receiver cannot continue processing thetransfer, and the session is terminated.

     • The corresponding error code is stored inserr->ee_data(session->err on kernel side ), providing further details about thereason for the abort, such as protocol violations or timeouts.

     • After receiving this message, the receiver discards the partially receivedframes, and the multi-frame session is considered incomplete.

In both cases, ifSOF_TIMESTAMPING_OPT_ID is enabled,serr->ee_datawill be set to the session’s unique identifier (session->tskey). Thisallows user space to track message transfers by their session identifier acrossmultiple frames or stages.

In all other cases,serr->ee_errno will be set toENOMSG, except fortheJ1939_EE_INFO_TX_ABORT andJ1939_EE_INFO_RX_ABORT cases, where thekernel setsserr->ee_data to the error stored insession->err. Allprotocol-specific errors are converted to standard kernel error values andstored insession->err. These error values are unified across system callsandserr->ee_errno. Some of the known error values are described in theError Codes in the J1939 Stack section.

When theJ1939_EE_INFO_RX_RTS message is provided, it will include thefollowing statistics for multi-frame messages (TP and ETP):

• J1939_NLA_TOTAL_SIZE: Total size of the message in the session.

• J1939_NLA_PGN: Parameter Group Number (PGN) identifying the message type.

• J1939_NLA_SRC_NAME: 64-bit name of the source ECU.

• J1939_NLA_DEST_NAME: 64-bit name of the destination ECU.

• J1939_NLA_SRC_ADDR: 8-bit source address of the sending ECU.

• J1939_NLA_DEST_ADDR: 8-bit destination address of the receiving ECU.

• For other messages (including single-frame messages), only the followingstatistic is included:

  • J1939_NLA_BYTES_ACKED: Number of bytes successfully acknowledged in thesession.

The key flags forSO_TIMESTAMPING include:

• SOF_TIMESTAMPING_OPT_ID: Enables the use of a unique session identifier(tskey) for each transfer. This identifier helps track message transfersand errors as distinct sessions in user space. When this option is enabled,serr->ee_data will be set tosession->tskey.

• SOF_TIMESTAMPING_OPT_CMSG: Sends timestamp information through controlmessages (structscm_timestamping), allowing the application to retrievetimestamps alongside the data.

• SOF_TIMESTAMPING_TX_SCHED: Provides the timestamp for when a message isscheduled for transmission (SCM_TSTAMP_SCHED).

• SOF_TIMESTAMPING_TX_ACK: Provides the timestamp for when a messagetransmission is fully acknowledged (SCM_TSTAMP_ACK).

• SOF_TIMESTAMPING_RX_SOFTWARE: Provides timestamps for reception-relatedevents (e.g.,J1939_EE_INFO_RX_RTS,J1939_EE_INFO_RX_DPO,J1939_EE_INFO_RX_ABORT).

These flags enable detailed monitoring of message lifecycles, includingtransmission scheduling, acknowledgments, reception timestamps, and gatheringdetailed statistics about the communication session, especially for multi-framepayloads like TP and ETP.

Example:

// Enable timestamping with various options, including session tracking and// statisticsintsock_opt=SOF_TIMESTAMPING_OPT_CMSG|SOF_TIMESTAMPING_TX_ACK|SOF_TIMESTAMPING_TX_SCHED|SOF_TIMESTAMPING_OPT_ID|SOF_TIMESTAMPING_RX_SOFTWARE;setsockopt(sock,SOL_SOCKET,SO_TIMESTAMPING,&sock_opt,sizeof(sock_opt));