Sync it with current code state
Signed-off-by: Oleksij Rempel <o.rempel@xxxxxxxxxxxxxx>
---
Documentation/networking/j1939.txt | 454 ++++++++++++++---------------
1 file changed, 218 insertions(+), 236 deletions(-)
diff --git a/Documentation/networking/j1939.txt b/Documentation/networking/j1939.txt
index 4e28689299cf..2b5cffe48999 100644
--- a/Documentation/networking/j1939.txt
+++ b/Documentation/networking/j1939.txt
@@ -6,7 +6,7 @@ Readme file for the J1939 Protocol
This file contains
- 1 Overview / What is j1939
+ 1 Overview / What is J1939
1.1 specifications used
2 Motivation
@@ -45,12 +45,12 @@ This file contains
SAE J1939 defines a higher layer protocol on CAN. It implements a more
sophisticated addressing scheme and extends the maximum packet size above
- 8 bytes. Several derived specifications exists, which differ from the
- original j1939 on the application level, like MilCAN A, NMEA2000 and
+ 8 bytes. Several derived specifications exist, which differ from the
+ original J1939 on the application level, like MilCAN A, NMEA2000 and
especially ISO-11783 (ISOBUS). This last one specifies the so-called ETP
(Extended Transport Protocol) which is has been included in this
- implementation. This inclusion results in a maximum packet size of
- ((2^24)-1)*7 bytes
+ implementation. This results in a maximum packet size of
+ ((2 ^ 24) - 1) * 7 bytes == 111 MiB.
1.1 specifications used
@@ -68,37 +68,37 @@ This file contains
addressing and transport methods used by J1939.
* addressing:
- When a process on an ECU communicates via j1939, it should not necessarily
+ When a process on an ECU communicates via J1939, it should not necessarily
know its source address. Although at least 1 process per ECU should know
the source address. Other processes should be able to reuse that address.
This way, address parameters for different processes cooperating for the
same ECU, are not duplicated.
- This way of working is closely related to the unix concept where programs
+ This way of working is closely related to the UNIX concept where programs
do just 1 thing, and do it well.
* dynamic addressing:
Address Claiming in J1939 is time critical. Furthermore data transport
should be handled properly during the address negotiation. Putting these
functionality in the kernel eliminates this functionality as a requirement
- for _every_ userspace process that communicates via J1939. This results in
+ for _every_ user space process that communicates via J1939. This results in
a consistent J1939 bus with proper addressing.
* transport:
- Both TP & ETP reuse some PGN's to relay big packets over them. Different
- processes may thus use the same TP & ETP PGN's without actually knowing it.
+ Both TP & ETP reuse some PGNs to relay big packets over them. Different
+ processes may thus use the same TP & ETP PGNs without actually knowing it.
The individual TP & ETP sessions _must_ be serialized (synchronised)
between different processes. The kernel solves this problem properly, and
- eliminates the serialisation (synchronisation) as a requirement for
- _every_ userspace process that communicates via J1939.
+ eliminates the serialization (synchronization) as a requirement for
+ _every_ user space process that communicates via J1939.
- J1939 defines some other features (relaying, gateway, Fast Packet transport,
+ J1939 defines some other features (relaying, gateway, fast packet transport,
...). In-kernel code for these would not contribute to protocol stability.
- Therefore, these parts are left to userspace.
+ Therefore, these parts are left to user space.
- The j1939 sockets operate on CAN network devices (see SocketCAN). Any j1939
- userspace library operating on CAN raw sockets will still operate properly.
+ The J1939 sockets operate on CAN network devices (see SocketCAN). Any J1939
+ user space library operating on CAN raw sockets will still operate properly.
Since such library does not communicate with the in-kernel implementation,
- care must be taken that these 2 do not interfere. In practice, this means
+ care must be taken that these two do not interfere. In practice, this means
they cannot share ECU addresses. A single ECU (or virtual ECU) address is
used by the library exclusively, or by the in-kernel system exclusively.
@@ -122,7 +122,7 @@ This file contains
On the other hand, when using PDU1 Format, the PS-field contains a so-called
Destination Address, which is _not_ part of the PGN. When communicating a
- PGN from userspace to kernel (or visa versa) and PDU2 Format is used, the
+ PGN from user space to kernel (or visa versa) and PDU2 Format is used, the
PS-field of the PGN shall be set to zero. The Destination Address shall be
set elsewhere.
@@ -138,12 +138,11 @@ This file contains
addresses are considered right. This responsibility is for the OEM or system
integrator.
- For dynamic addressing, so-called Address Claiming, extra support is forseen
+ For dynamic addressing, so-called Address Claiming, extra support is foreseen
in the kernel. In J1939 any ECU is known by it's 64-bit NAME. At the moment
- of succesfull address claim, the kernel keeps track of both NAME and source
+ of a successful address claim, the kernel keeps track of both NAME and source
address being claimed. This serves as a base for filter schemes. By default,
- packets with a destination that is not locally, will be rejected soon after
- reception.
+ packets with a destination that is not locally, will be rejected.
Mixed mode packets (from a static to a dynamic address or vice versa) are
allowed. The BSD sockets define separate API calls for getting/setting the
@@ -152,25 +151,16 @@ This file contains
3.3 Filtering
- Similar to SocketCAN, j1939 defines filters per socket that a user can set
- in order to receive a subset of the j1939 traffic. Filtering can base on
+ J1939 defines white list filters per socket that a user can set in order to
+ receive a subset of the J1939 traffic. Filtering can be based on:
+
* SA
- * NAME
+ * SOURCE_NAME
* PGN
- There is a semantic difference with SocketCAN with regard to filtering.
When multiple filters are in place for a single socket, and a packet comes
in that matches several of those filters, the packet is only received once
for that socket.
- The rationale behind this difference originates in the filter capabilities.
- Where SocketCAN filters on only 1 orthogonal (can id), J1939 can filter
- on 3 orthogonal properties (sa, name, pgn).
-
- When a filter on the SA is set, j1939 traffic with a matching SA, but with
- its NAME set (aka having claimed SA successfully) will match, although
- the filter would not match its NAME.
-
- Filtering on priority is _not_ supported.
4. How to use J1939
@@ -178,43 +168,46 @@ This file contains
4.1 API calls
- Like TCP/IP and CAN, you first need to open a socket for communicating over a
- CAN network. To use j1939, include <include/linux/j1939.h>. From there,
- <include/linux/can.h> will be included too.
- To open a socket, you would write
+ On CAN, you first need to open a socket for communicating over a
+ CAN network. To use J1939, #include <linux/can/j1939.h>. From there,
+ <linux/can.h> will be included too.
+ To open a socket, use:
s = socket(PF_CAN, SOCK_DGRAM, CAN_J1939);
- J1939 does use SOCK_DGRAM sockets. In the j1939 specification, connections are
+ J1939 does use SOCK_DGRAM sockets. In the J1939 specification, connections are
mentioned in the context of transport protocol sessions. These still deliver
packets to the other end (using several CAN packets).
- SOCK_STREAM is never appropriate.
+ SOCK_STREAM is not supported.
After the successful creation of the socket, you would normally use the
- bind(2) and/or connect(2) system call to bind the socket to a CAN interface
- (which is different from TCP/IP due to different addressing) After binding
- and/or connecting the socket, you can read(2) and write(2) from/to the socket
- or use send(2), sendto(2), sendmsg(2) and the recv* counterpart operations on
- the socket as usual. There are also J1939 specific socket options described
- below.
-
- In order to send data, a bind(2) must have succeeded. bind(2) assigns a local
- address to a socket. For this to succeed, you can only choose addresses
- that have been assigned earlier (see 4.1). When an empty address is assigned
- (ie. SA=0xff && name=0), a default is taken for the device that is bound to.
+ bind(2) and/or connect(2) system call to bind the socket to a CAN interface.
+ After binding and/or connecting the socket, you can read(2) and write(2)
+ from/to the socket or use send(2), sendto(2), sendmsg(2) and the recv*()
+ counterpart operations on the socket as usual. There are also J1939 specific
+ socket options described below.
+
+ In order to send data, a bind(2) must have been successful. bind(2) assigns a
+ local address to a socket.
Different from CAN is that the payload data is just the data that get send,
without it's header info. The header info is derived from the sockaddr
supplied to bind(2), connect(2), sendto(2) and recvfrom(2). A write(2) with
size 4 will result in a packet with 4 bytes.
- The sockaddr structure has extensions for use with j1939 as specified below:
+ The sockaddr structure has extensions for use with J1939 as specified below:
struct sockaddr_can {
sa_family_t can_family;
int can_ifindex;
union {
struct {
__u64 name;
+ /* pgn:
+ * 8 bit: PS in PDU2 case, else 0
+ * 8 bit: PF
+ * 1 bit: DP
+ * 1 bit: reserved
+ */
__u32 pgn;
__u8 addr;
} j1939;
@@ -228,77 +221,174 @@ This file contains
can_addr.j1939.name contains the 64-bit J1939 NAME.
- can_addr.j1939.addr contains the source address.
+ can_addr.j1939.addr contains the address.
- When sending data, the source address is applied as follows: If
- can_addr.j1939.name != 0 the NAME is looked up by the kernel and the
- corresponding Source Address is used. If can_addr.j1939.name == 0,
- can_addr.j1939.addr is used.
+ The bind(2) system call assigns the local address is assigned, i.e. the
+ source address. If a PGN during bind(2) is set, it's used as a RX filter. I.e.
+ only packets with a matching PGN are received. If a ADDR or NAME is set it used
+ as a receive filter too. It will match the destination NAME or ADDR of the
+ incoming packet.
- After a bind(2), the local address is assigned, i.e. the source address.
- After a connect(2), the remote address is assigned, i.e. the destination
- address.
+ On the other hand connect(2) assigns the remote address, i.e. the destination
+ address. The PGN from connect(2) is used as the default PGN when sending
+ packets. If ADDR or NAME is set it will be used as the default destination ADDR
+ or NAME. Further a set ADDR or NAME during connect(2) is used as a receive
+ filter. It will match the source NAME or ADDR of the incoming packet.
- Both write(2) and send(2) will send a packet with local address from bind,
- remote address from connect(2). When the address was not set, a broadcast is
- sent. The PGN is used from bind(2) or overruled with sendto(2), which will
- override the destination address when valid, and the PGN when valid.
+ Both write(2) and send(2) will send a packet with local address from bind(2) and
+ the remote address from connect(2). Use sendto(2) to overwrite the destination
+ address.
- Both read(2) and recv(2) will receive packets matching the sockets filters.
- recvfrom(2) will receive these packets with originator's address.
+ If can_addr.j1939.name is set (!= 0) the NAME is looked up by the kernel and
+ the corresponding ADDR is used. If can_addr.j1939.name is not set (== 0),
+ can_addr.j1939.addr is used.
When creating a socket, reasonable defaults have been set. Some options can be
modified with setsockopt(2) & getsockopt(2).
-4.1.1 Message flags during sendmsg
-
- send(2), sendto(2) and sendmsg(2) take a 'flags' argument. J1939 interpretes
- these flags during outgoing traffic:
+ RX path related options:
+ SO_J1939_FILTER - configure array of filters
+ SO_J1939_PROMISC - disable filters set by bind(2) and connect(2)
+ SO_J1939_RECV_OWN - receive packets that have been sent on this socket
+
+ By default no broadcast packets can't be send or received. To enable sending
+ or receiving broadcast packets use the socket option SO_BROADCAST:
+
+ int value = 1;
+ setsockopt(sock, SOL_SOCKET, SO_BROADCAST, &value, sizeof(value));
+
+ The following diagram illustrates the RX path:
+
+ +--------------------+
+ | incoming packet |
+ +--------------------+
+ |
+ V
+ +--------------------+
+ | SO_J1939_RECV_OWN? |
+ +--------------------+
+ |
+ v
+ +--------------------+
+ | SO_J1939_PROMISC? |
+ +--------------------+
+ | |
+ no | | yes
+ | |
+ .---------' `---------.
+ | |
+ +---------------------------+ |
+ | bind() + connect() + | |
+ | SOCK_BROADCAST filter | |
+ +---------------------------+ |
+ | |
+ |<---------------------'
+ V
+ +---------------------------+
+ | SO_J1939_FILTER |
+ +---------------------------+
+ |
+ V
+ +---------------------------+
+ | socket recv() |
+ +---------------------------+
+
+ TX path realated options:
+ SO_J1939_SEND_PRIO - change default send priority for the socket
+
+4.1.1 Message flags during send() and related system calls
+
+ send(2), sendto(2) and sendmsg(2) take a 'flags' argument. Currently
+ supported flags are:
* MSG_DONTWAIT, i.e. non-blocking operation.
-4.1.2 SCM_J1939_DEST_ADDR & SCM_J1939_DEST_NAME
-
- Different received j1939 packets could have had different destionations:
- - broadcast packet, i.e. no destination address
- - destination address that matches the sockets local address
- - destination address that matches _a_ local address on the system, and the
- socket had no local address defined.
- - SO_J1939_PROMISC was set
-
- The destination address & destination name (if applicable) are attached
- to the msghdr in the recvmsg(2) call. It can be extracted using cmsg(3) macros,
- with cmsg_level == SOL_J1939 && cmsg_type == SCM_J1939_DEST_ADDR
- or SCM_J1939_DEST_NAME. The returned data is a uint8_t/uint64_t.
-
-4.1.3 SCM_J1939_PRIORITY
-
- Attached to the msghdr is also the packet's priority on the bus. This is a
- uint8_t, packed as cmsg_type == SCM_J1939_PRIORITY.
+4.1.2 recvmsg(2)
+
+ In most cases recvmsg(2) is needed if you want to extract more information
+ than recvfrom(2) can provide. For example package priority and timestamp. The
+ destination address, name and packet priority (if applicable) are attached to
+ the msghdr in the recvmsg(2) call. They can be extracted using cmsg(3) macros,
+ with cmsg_level == SOL_J1939 && cmsg_type == SCM_J1939_DEST_ADDR,
+ SCM_J1939_DEST_NAME or SCM_J1939_PRIORITY. The returned data is a uint8_t for
+ priority and dst_addr, and uint64_t for dst_name.
+
+ uint8_t priority, dst_addr;
+ uint64_t dst_name;
+
+ for (cmsg = CMSG_FIRSTHDR(&msg); cmsg; cmsg = CMSG_NXTHDR(&msg, cmsg)) {
+ switch (cmsg->cmsg_level) {
+ case SOL_CAN_J1939:
+ if (cmsg->cmsg_type == SCM_J1939_DEST_ADDR)
+ dst_addr = *CMSG_DATA(cmsg);
+ else if (cmsg->cmsg_type == SCM_J1939_DEST_NAME)
+ memcpy(&dst_name, CMSG_DATA(cmsg), cmsg->cmsg_len - CMSG_LEN(0));
+ else if (cmsg->cmsg_type == SCM_J1939_PRIO)
+ priority = *CMSG_DATA(cmsg);
+ break;
+ }
+ }
4.2 Dynamic Addressing
Distinction has to be made in and using the claimed address and doing an
address claim. To use an already claimed address, one has to fill in the
j1939.name member and provide it to bind(2). If the name had claimed an
- address earlier, all further PGN's being sent will use that address. And the
+ address earlier, all further messages being sent will use that address. And the
j1939.addr member will be ignored.
- An exception on this is pgn 0x0ee00. This is the "Address Claim/Cannot Claim
+ An exception on this is PGN 0x0ee00. This is the "Address Claim/Cannot Claim
Address" message and when the kernel will use the j1939.addr member for that
- pgn if necessary.
-
- To claim an address, bind(2) with:
- j1939.pgn set to 0x0ee00
- j1939.addr set to the desired Source Address.
- j1939.name set to the NAME you want the Source Address to claim to.
-
- Afterwards do a write(2) with data set to the NAME (Little Endian). If the
- NAME provided, does not match the j1939.name provided to bind(2), EPROTO
- will be returned. One might use sendto(2) also to send the Address Claim. In
- that case, the j1939.addr member must be set to the broadcast address (255)
- and the j1939.pgn must be set to 0x0ee00. If This combination is not given,
- EPROTO is returned.
+ PGN if necessary.
+
+ To claim an address following code example can be used:
+
+ struct sockaddr_can baddr = {
+ .can_family = AF_CAN,
+ .can_addr.j1939 = {
+ .name = name,
+ .addr = J1939_IDLE_ADDR,
+ .pgn = J1939_NO_PGN, /* to disable bind() rx filter for PGN */
+ },
+ .can_ifindex = if_nametoindex("can0"),
+ };
+
+ bind(sock, (struct sockaddr *)&baddr, sizeof(baddr));
+
+ /* for address claiming broadcast must be allowed */
+ int value = 1;
+ setsockopt(sock, SOL_SOCKET, SO_BROADCAST, &value, sizeof(value));
+
+ /* configured advanced RX filter with PGN needed for address claiming */
+ const struct j1939_filter filt[] = {
+ {
+ .pgn = J1939_PGN_ADDRESS_CLAIMED,
+ .pgn_mask = J1939_PGN_PDU1_MAX,
+ }, {
+ .pgn = J1939_PGN_ADDRESS_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));
+
+ uint64_t dat = htole64(name);
+ const struct sockaddr_can saddr = {
+ .can_family = AF_CAN,
+ .can_addr.j1939 = {
+ .pgn = J1939_PGN_ADDRESS_CLAIMED,
+ .addr = J1939_NO_ADDR,
+ },
+ };
+
+ /* Afterwards do a sendto(2) with data set to the NAME (Little Endian). If the
+ * NAME provided, does not match the j1939.name provided to bind(2), EPROTO
+ * will be returned.
+ */
+ sendto(sock, dat, sizeof(dat), 0, (const struct sockaddr *)&saddr, sizeof(saddr));
If no-one else contest the address claim within 250ms after transmission, the
kernel marks the NAME-SA assignment as valid. The valid assignment will be
@@ -312,148 +402,40 @@ This file contains
valid address claim packet. This restarts the state machine in the kernel
(and any other participant on the bus) for this NAME.
+ can-utils also include the jacd tool, so it can be used as code example or
+ as default address claiming daemon.
4.3 Send Examples
4.3.1 Static addressing
- This example will send a pgn (0x12300) from SA 0x20 to DA 0x30.
+ This example will send a PGN (0x12300) from SA 0x20 to DA 0x30.
Bind:
- struct sockaddr_can addr;
+ struct sockaddr_can baddr = {
+ .can_family = AF_CAN,
+ .can_addr.j1939 = {
+ .name = J1939_NO_NAME,
+ .addr = 0x20,
+ .pgn = J1939_NO_PGN,
+ },
+ .can_ifindex = if_nametoindex("can0"),
+ };
- memset(&addr, 0, sizeof(addr));
- addr.can_ifindex = ifindex("can0"); // ifindex is a substitute.
- addr.can_addr.j1939.name = J1939_NO_NAME;
- addr.can_addr.j1939.addr = 0x20;
- addr.can_addr.j1939.pgn = J1939_NO_PGN;
+ bind(sock, (struct sockaddr *)&baddr, sizeof(baddr));
- bind(sk, (void *)&addr, sizeof(addr));
-
- Now, the socket 'sk' is bound to the address 0x20. Since no pgn
- was specified during bound, a pgn will be necessary during sendto() operations.
- Alternatively, specifying addr.can_addr.j1939.pgn during bind() allows
- for using send() & write(), since a default pgn (the pgn specified during bind())
- can be used then.
-
- Send:
- struct sockaddr_can addr;
-
- memset(&addr, 0, sizeof(addr));
- addr.can_addr.j1939.name = J1939_NO_NAME;
- addr.can_addr.j1939.addr = 0x30;
- addr.can_addr.j1939.pgn = 0x12300;
- // addr.can_ifindex is not necessary here.
-
- sendto(sk, data, sizeof(data), 0, (void *)&addr, sizeof(addr));
-
-4.3.2 Dynamic addressing
-
- This example will send a pgn (0x12300) from 12345678 to 9ABCDEF
-
- Start an address claiming daemon (e.g. jacd)
- $ jacd -r 0x20-0x30 12345678 can0 &
-
- Bind:
- struct sockaddr_can addr;
-
- memset(&addr, 0, sizeof(addr));
- addr.can_ifindex = if_nametoindex("can0");
- addr.can_addr.j1939.name = 0x12345678ULL;
- addr.can_addr.j1939.addr = J1939_NO_ADDR;
- addr.can_addr.j1939.pgn = J1939_NO_PGN;
-
- bind(sk, (void *)&addr, sizeof(addr));
+ Now, the socket 'sock' is bound to the SA 0x20. Since no connect(2) was called,
+ at this point we can use only sendto(2) or sendmsg(2).
Send:
- struct sockaddr_can addr;
-
- memset(&addr, 0, sizeof(addr));
- addr.can_addr.j1939.name = 0x9ABCDEFULL;
- addr.can_addr.j1939. = J1939_NO_ADDR;
- addr.can_addr.j1939.pgn = 0x12300;
-
- sendto(sk, data, sizeof(data), 0, (void *)&addr, sizeof(addr));
+ const struct sockaddr_can saddr = {
+ .can_family = AF_CAN,
+ .can_addr.j1939 = {
+ .name = J1939_NO_NAME;
+ .pgn = 0x30,
+ .addr = 0x12300,
+ },
+ };
-4.3.3 Mixed mode
-
- A scenario that sends a packet from a static address to a dynamic address
- or vice versa is called 'mixed mode' here.
-
- Combining the setup of the static address with a sendto() to a dynamic
- address from the above examples is legal, and implements such mixed mode
- addressing. The same applies for the setup of the dynamic address combined
- with the sendto() towards a dynamic address.
-
-
-5 Socket Options
---------------------------------
-
- j1939 sockets have some options that are configurable via setsockopt(2).
- Each of those options is initialized with a reasonable default.
-
-
-5.1 SO_J1939_FILTER
-
- As mentioned above, J1939 supports filtering in both NAME, Source Address
- and PGN. All members must match.
-
- struct j1939_filter filter = {
- .name = ...
- .name_mask = ...
- .addr = ...
- .addr_mask = ...
- .pgn = ...
- .pgn_mask = ...
- }
-
- setsockopt(s, SOL_CAN_J1939, SO_J1939_FILTER, &filter, sizeof(filter));
-
-
-5.2 SO_J1939_PROMISC
-
- When set, j1939 will receive all packets, not just those with a destination
- on the local system.
- default off.
-
- int promisc = 1; /* 0 = disabled (default), 1 = enabled */
-
- setsockopt(s, SOL_CAN_J1939, SO_J1939_PROMISC, &promisc, sizeof(promisc));
-
-
-5.3 SO_J1939_RECV_OWN
-
- All the sent j1939 packets are looped back in the system.
- The reception of the j1939 packets on the same socket that was
- sending the j1939 packet is assumed to be unwanted and therefore
- disabled by default. This default behaviour may be changed on
- demand:
-
- int recv_own_msgs = 1; /* 0 = disabled (default), 1 = enabled */
-
- setsockopt(s, SOL_CAN_J1939, SO_J1939_RECV_OWN,
- &recv_own_msgs, sizeof(recv_own_msgs));
-
-
-5.4 SO_J1939_SEND_PRIO
-
- To set the priority field for outgoing packets, the SO_J1939_SEND_PRIO can
- be changed. This int field specifies the priority that will be used.
- j1939 defines a priority between 0 and 7 inclusive,
- with 7 the lowest priority.
- Per default, the priority is set to 6 (conforming J1939).
- This priority socket option operates on the same value that is modified
- with
-
- setsockopt(s, SOL_SOCKET, SO_PRIORITY, &pri, sizeof(pri))
-
- socketoption, with a difference that SOL_SOCKET/SO_PRIORITY is defined with
- 0 the lowest priority. SOL_CAN_J1939/SO_J1939_SEND_PRIO inverts this value
- for you.
-
-
-6. Credits
---------------------------------
+ sendto(sock, dat, sizeof(dat), 0, (const struct sockaddr *)&saddr, sizeof(saddr));
- Kurt Van Dijck (j1939 core, transport protocol, API)
- Pieter Beyens (j1939 core, address claiming)
--
2.20.1
