From: Yegor Yefremov <yegorslists@xxxxxxxxxxxxxx>
Signed-off-by: Yegor Yefremov <yegorslists@xxxxxxxxxxxxxx>
---
Documentation/networking/j1939.rst | 128 +++++++++++++++--------------
1 file changed, 65 insertions(+), 63 deletions(-)
diff --git a/Documentation/networking/j1939.rst b/Documentation/networking/j1939.rst
index bd1584ec90f9..59596ef509c9 100644
--- a/Documentation/networking/j1939.rst
+++ b/Documentation/networking/j1939.rst
@@ -135,32 +135,32 @@ API Calls
---------
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:
+To use J1939, ``#include <linux/can/j1939.h>``. From there, ``<linux/can.h>``
+will be included too. To open a socket, use:
.. code-block:: C
s = socket(PF_CAN, SOCK_DGRAM, CAN_J1939);
-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 not
+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 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. 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.
+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. 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.
+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 sends,
without its 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.
+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:
@@ -184,47 +184,49 @@ The sockaddr structure has extensions for use with J1939 as specified below:
} can_addr;
}
-can_family & can_ifindex serve the same purpose as for other SocketCAN sockets.
+``can_family`` & ``can_ifindex`` serve the same purpose as for other SocketCAN
+sockets.
-can_addr.j1939.pgn specifies the PGN (max 0x3ffff). Individual bits are
+``can_addr.j1939.pgn`` specifies the PGN (max 0x3ffff). Individual bits are
specified above.
-can_addr.j1939.name contains the 64-bit J1939 NAME.
+``can_addr.j1939.name`` contains the 64-bit J1939 NAME.
-can_addr.j1939.addr contains the address.
+``can_addr.j1939.addr`` contains the address.
-The bind(2) system call assigns the local address, i.e. the source address when
-sending packages. 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 an ADDR or NAME is set
-it is used as a receive filter, too. It will match the destination NAME or ADDR
-of the incoming packet. The NAME filter will work only if appropriate Address
-Claiming for this name was done on the CAN bus and registered/cached by the
-kernel.
+The ``bind(2)`` system call assigns the local address, i.e. the source address
+when sending packages. 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 an ADDR or
+NAME is set it is used as a receive filter, too. It will match the destination
+NAME or ADDR of the incoming packet. The NAME filter will work only if
+appropriate Address Claiming for this name was done on the CAN bus and
+registered/cached by the kernel.
-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.
+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(2) and
-the remote address from connect(2). Use sendto(2) to overwrite the destination
-address.
+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.
-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.
+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 are set. Some options can be
-modified with setsockopt(2) & getsockopt(2).
+modified with ``setsockopt(2)`` & ``getsockopt(2)``.
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_FILTER`` - configure array of filters
+- ``SO_J1939_PROMISC`` - disable filters set by ``bind(2)`` and ``connect(2)``
By default no broadcast packets can be send or received. To enable sending or
-receiving broadcast packets use the socket option SO_BROADCAST:
+receiving broadcast packets use the socket option ``SO_BROADCAST``:
.. code-block:: C
@@ -265,26 +267,26 @@ The following diagram illustrates the RX path:
+---------------------------+
TX path related options:
-SO_J1939_SEND_PRIO - change default send priority for the socket
+``SO_J1939_SEND_PRIO`` - change default send priority for the socket
Message Flags during send() and Related System Calls
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-send(2), sendto(2) and sendmsg(2) take a 'flags' argument. Currently
+``send(2)``, ``sendto(2)`` and ``sendmsg(2)`` take a 'flags' argument. Currently
supported flags are:
-* MSG_DONTWAIT, i.e. non-blocking operation.
+* ``MSG_DONTWAIT``, i.e. non-blocking operation.
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
+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_PRIO. The returned data is a uint8_t for
-priority and dst_addr, and uint64_t for dst_name.
+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_PRIO``. The returned data is a ``uint8_t`` for
+``priority`` and ``dst_addr``, and ``uint64_t`` for ``dst_name``.
.. code-block:: C
@@ -309,13 +311,13 @@ Dynamic Addressing
Distinction has to be made between 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 messages being sent will use that address. And the
-j1939.addr member will be ignored.
+``j1939.name`` member and provide it to ``bind(2)``. If the name had claimed an
+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
-Address" message and the kernel will use the j1939.addr member for that PGN if
-necessary.
+Address" message and the kernel will use the ``j1939.addr`` member for that PGN
+if necessary.
To claim an address following code example can be used:
@@ -375,13 +377,13 @@ NAME can send packets.
If another ECU claims the address, the kernel will mark the NAME-SA expired.
No socket bound to the NAME can send packets (other than address claims). To
-claim another address, some socket bound to NAME, must bind(2) again, but with
-only j1939.addr changed to the new SA, and must then send a valid address claim
-packet. This restarts the state machine in the kernel (and any other
-participant on the bus) for this NAME.
+claim another address, some socket bound to NAME, must ``bind(2)`` again, but
+with only ``j1939.addr`` changed to the new SA, and must then send a 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 j1939acd tool, so it can be used as code example or as
-default Address Claiming daemon.
+``can-utils`` also include the ``j1939acd`` tool, so it can be used as code
+example or as default Address Claiming daemon.
Send Examples
-------------
@@ -407,8 +409,8 @@ Bind:
bind(sock, (struct sockaddr *)&baddr, sizeof(baddr));
-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).
+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:
--
2.17.0
