Date:   Tue, 20 Oct 2020 12:59:24 +0200
From:   Marc Kleine-Budde <mkl@...gutronix.de>
To:     yegorslists@...glemail.com, linux-can@...r.kernel.org
Cc:     netdev@...r.kernel.org
Subject: Re: [PATCH] can: j1939: fix syntax and spelling

On 10/20/20 12:10 PM, yegorslists@...glemail.com wrote:
> From: Yegor Yefremov <yegorslists@...glemail.com>
> 
> Signed-off-by: Yegor Yefremov <yegorslists@...glemail.com>
> ---
>  Documentation/networking/j1939.rst | 34 +++++++++++++++---------------
>  1 file changed, 17 insertions(+), 17 deletions(-)
> 
> diff --git a/Documentation/networking/j1939.rst b/Documentation/networking/j1939.rst
> index 65b12abcc90a..8b3f4fbc3bbb 100644
> --- a/Documentation/networking/j1939.rst
> +++ b/Documentation/networking/j1939.rst
> @@ -10,9 +10,9 @@ Overview / What Is J1939
>  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 exist, which differ from the original
> -J1939 on the application level, like MilCAN A, NMEA2000 and especially
> +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
> +Transport Protocol) which, has been included in this implementation. This
                           ^^^
A comma before which, not after?

>  results in a maximum packet size of ((2 ^ 24) - 1) * 7 bytes == 111 MiB.
>  
>  Specifications used
> @@ -32,15 +32,15 @@ sockets, we found some reasons to justify a kernel implementation for the
>  addressing and transport methods used by J1939.
>  
>  * **Addressing:** when a process on an ECU communicates via J1939, it should
> -  not necessarily know its source address. Although at least one process per
> +  not necessarily know its source address. Although, at least one 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 do just one thing, and do
> +  closely related to the UNIX concept, where programs do just one thing and do
>    it well.
>  
>  * **Dynamic addressing:** Address Claiming in J1939 is time critical.
> -  Furthermore data transport should be handled properly during the address
> +  Furthermore, data transport should be handled properly during the address
>    negotiation. Putting this functionality in the kernel eliminates it as a
>    requirement for _every_ user space process that communicates via J1939. This
>    results in a consistent J1939 bus with proper addressing.
> @@ -58,10 +58,10 @@ Therefore, these parts are left to user space.
>  
>  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 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.
> +Since such a library does not communicate with the in-kernel implementation,
> +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.

I've kept the line endings as as, to the a better readable diff.

>  
>  J1939 concepts
>  ==============
> @@ -77,13 +77,13 @@ is composed as follows:
>  8 bits : PS (PDU Specific)
>  
>  In J1939-21 distinction is made between PDU1 format (where PF < 240) and PDU2
> -format (where PF >= 240). Furthermore, when using PDU2 format, the PS-field
> +format (where PF >= 240). Furthermore, when using the PDU2 format, the PS-field
>  contains a so-called Group Extension, which is part of the PGN. When using PDU2
>  format, the Group Extension is set in the PS-field.
>  
>  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 user space to kernel (or visa versa) and PDU2 format is used, the PS-field
> +from user space to kernel (or vice versa) and PDU2 format is used, the PS-field
>  of the PGN shall be set to zero. The Destination Address shall be set
>  elsewhere.
>  
> @@ -96,15 +96,15 @@ Addressing
>  
>  Both static and dynamic addressing methods can be used.
>  
> -For static addresses, no extra checks are made by the kernel, and provided
> +For static addresses, no extra checks are made by the kernel and provided
>  addresses are considered right. This responsibility is for the OEM or system
>  integrator.
>  
>  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
> +in the kernel. In J1939 any ECU is known by its 64-bit NAME. At the moment 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.
> +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
> @@ -153,8 +153,8 @@ 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
> +Different from CAN is that the payload data is just the data that get sends,

...that gets send...

> +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.
>  
> @@ -191,7 +191,7 @@ 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
> +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
> 

Marc

-- 
Pengutronix e.K.                 | Marc Kleine-Budde           |
Embedded Linux                   | https://www.pengutronix.de  |
Vertretung West/Dortmund         | Phone: +49-231-2826-924     |
Amtsgericht Hildesheim, HRA 2686 | Fax:   +49-5121-206917-5555 |



Download attachment "signature.asc" of type "application/pgp-signature" (489 bytes)

Powered by blists - more mailing lists