Re: [PATCH 1/1] Documentation: networking: document CAN ISO-TP

[Francesco Valla <valla.francesco@gmail.com>]

Hi Oliver,

On Thu, Mar 14, 2024 at 01:59:50PM +0100, Oliver Hartkopp wrote:
> > diff --git a/Documentation/networking/index.rst b/Documentation/networking/index.rst
> > index 473d72c36d61..ba22acfae389 100644
> > --- a/Documentation/networking/index.rst
> > +++ b/Documentation/networking/index.rst
> > @@ -19,6 +19,7 @@ Contents:
> >      caif/index
> >      ethtool-netlink
> >      ieee802154
> > +   isotp
> 
> I'm not sure whether to name this file "iso15765-2" instead of just "isotp".
> IIRC there are some more transport protocols inside the ISO universe.
>

This was my doubt as well, I decided to name it "isotp" to be aligned
with the source file that contains the implementation. But I can rename
it if you think is better / more understandable.

There are for sure other ISO protocols implementing a transport - first
that comes to my mind is the transport part inside ISO11783/ISOBUS.

> > +====================
> > +ISO-TP (ISO 15765-2) Transport Protocol
> 
> ISO 15765-2:2016
>

Noted.

> > +====================
> > +
> > +Overview
> > +=========================
> > +
> > +ISO-TP, also known as ISO 15765-2 from the ISO standard it is defined in, is a
> 
> CAN ISO-TP , also known as ISO 15765-2:2016 ...
>

Noted, as before.

> > +transport protocol specifically defined for diagnostic communication on CAN.
> > +It is widely used in the automotive industry, for example as the transport
> > +protocol for UDSonCAN (ISO 14229-3) or emission-related diagnostic services
> > +(ISO 15031-5).
> > +
> > +ISO-TP can be used both on classical (2.0B) CAN and CAN-FD based networks.
> 
> CAN CC (aka Classical CAN, CAN 2.0B) and CAN FD (CAN with Flexible Datarate)
> 

Ok

> > +It is also designed to be compatible with a CAN network using SAE J1939 as data
> > +link layer (however, this is not a requirement).
> > +
> > +Addressing
> > +----------
> > +
> > +In its simplest form, ISO-TP is based on two kinds of addresses for the nodes
> 
> two kinds of addressing-modes
>

Ok

> > +connected to the same network:
> > +
> > +- a physical address, which identifies a single node and is used in 1-to-1
> > +  communication
> 
> physical addressing is implemented by two node-specific addresses (CAN
> identifiers) and is used ...
> 

(see below)

> > +- a functional addess, which identifies a group of nodes and is used in 1-to-N
> > +  communication
> 
> functional addressing is implemented by one node-specific address (CAN
> identifier) and is used ...
>

(see below)

> > +
> > +In a so-called "normal" addressing scenario, both these addresses are
> > +represented by a single byte
> 
> No. The normal addressing always needs two CAN IDs (assigned to two
> different CAN nodes) or you have functional addressing which needs only the
> sender CAN ID for the 1:N unconfirmed transmission.
>

Here I was referring to the N_TA address defined by the standard, which is
defined as 8 bits long and can identify either one single node (in
physical addressing) or a group of nodes (in functional addressing). But
from the point of view of a user and not a network planner referring to
CAN IDs is probably a better approach.

> 
> 
> > However, in order to support larger networks, an "extended"
> > +addressing scheme can be adopted; in this case, the first byte of the data
> > +payload is used as an additional component of the address (both for the
> > +physical and functional cases).
> 
> Yes. This is called extended addressing.
> 
> It still needs the normal addressing scheme with the one or two CAN IDs.
>

I'll add this note to the description of the extended addressing.

> > +
> > +Transport protocol and associated frame types
> > +---------------------------------------------
> > +
> > +When transmitting data using the ISO-TP protocol, the payload can either fit
> > +inside one single CAN message or not, also considering the overhead the protocol
> > +is generating and the optional extended addressing. In the first case, the data
> > +is transmitted at once using a so-called Single Frame (SF). In the second case,
> > +ISO-TP defines a multi-frame protocol, in which the sender asks (through a First
> 
> ... in which the sender provided the PDU length which is to be transmitted
> and also asks for a Flow Control frame which provides the blocksize and
> stmin stuff
>

Ok

> > +
> > +Specifications used
> > +-------------------
> > +
> > +* ISO 15765-2 : Road vehicles - Diagnostic communication over Controller Area
> ISO 15765-2:2016
>

Noted

> > +
> > +How to Use ISO-TP
> > +=================
> > +
> > +As with others CAN protocols, the ISO-TP stack support is built as a variant of
> > +the SocketCAN communication, and thus uses the socket APIs.
> 
> As with others CAN protocols, the ISO-TP stack support is built into the
> Linux network subsystem for the CAN bus, aka. Linux-CAN or SocketCAN and
> thus follows the same socket API.
>

Ok

> > +After the socket has been successfully created, ``bind(2)`` shall be called to
> > +bind the socket to the desired CAN interface, either:
> > +
> > +* specifying at least one RX or TX address, as part of the sockaddr supplied
> > +  to the call itself, or
> > +* after specifying broadcast flags through socket option (explained below)
> 
> You always need at least ONE CAN ID for sending (tx_id).
> 
> When you do not use the broadcasting modes CAN_ISOTP_SF_BROADCAST nor
> CAN_ISOTP_CF_BROADCAST you need the rx_id (for receiving the FC) too.
>

Couldn't listen-only mode be used without specifying a tx_id?

Nevertheless, I'll reword "address" as "CAN ID".

> > +
> > +Once bound to an interface, the socket can be read from and written to using
> > +the usual ``read(2)`` and ``write(2)`` system calls, as well as ``send(2)``,
> > +``sendmsg(2)``, ``recv(2)`` and ``recvmsg(2)``.
> > +Unlike raw SocketCAN sockets, only the data payload shall be specified in all
> 
> Unlike the CAN_RAW socket API ...
>

Ok

> > +
> > +  - ``CAN_ISOTP_LISTEN_MODE``: listen only (do not send FC frames)
> a testing feature
>

I'll add "normally used as a testing feature".

> > +  - ``CAN_ISOTP_EXTEND_ADDR``: enable extended addressing, using the byte
> > +    specified in ``ext_address`` as additional address byte.
> > +  - ``CAN_ISOTP_TX_PADDING``: enable padding for tranmsitted frames, using
> > +    ``txpad_content`` as value for the padding bytes.
> > +  - ``CAN_ISOTP_RX_PADDING``: enable padding for the received frames, using
> > +    ``rxpad_content`` as value for the padding bytes.
> > +  - ``CAN_ISOTP_CHK_PAD_LEN``: check for correct padding length on the received
> > +    frames.
> > +  - ``CAN_ISOTP_CHK_PAD_DATA``: check padding bytes on the received frames
> > +    against ``rxpad_content``; if ``CAN_ISOTP_RX_PADDING`` is not specified,
> > +    this flag is ignored.
> > +  - ``CAN_ISOTP_HALF_DUPLEX``: force ISO-TP socket in half duples mode
> > +    (that is, transport mechanism can only be incoming or outgoing at the same
> > +    time, not both)
> > +  - ``CAN_ISOTP_FORCE_TXSTMIN``: ignore stmin from received FC
> a testing feature
>

(see above)

> > +  - ``CAN_ISOTP_FORCE_RXSTMIN``: ignore CFs depending on rx stmin
> a testing feature
> 

(again, see above)

> > +  - ``CAN_ISOTP_RX_EXT_ADDR``: use ``rx_ext_address`` instead of ``ext_address``
> > +    as extended addressing byte on the reception path.
> > +  - ``CAN_ISOTP_WAIT_TX_DONE``: wait until the frame is sent before returning
> > +    from ``write(2)`` and ``send(2)`` calls (i.e., blocking write operations).
> > +  - ``CAN_ISOTP_SF_BROADCAST``: use 1-to-N functional addressing (cannot be
> > +    specified alongside ``CAN_ISOTP_CF_BROADCAST``)
> > +  - ``CAN_ISOTP_CF_BROADCAST``: use 1-to-N transmission without flow control
> > +    (cannot be specified alongside ``CAN_ISOTP_SF_BROADCAST``)
> Btw. this mode is not covered by the ISO 15765-2 standard yet.
>

Good to know, I was wondering why this was introduced, as I was not
remembering it from when I read the standard a couple of years ago. Will
it be part of the next revision (which is saw is under publication)?

> > +
> > +Flow Control options
> > +~~~~~~~~~~~~~~~~~~~~
> > +
> > +Flow Control (FC) options can be passed using the ``CAN_ISOTP_RECV_FC`` optname:
> 
> to provide the communication parameters for receiving ISO-TP PDUs.
>

Ok

> > +
> > +* ``mtu``: generated and accepted CAN frame type, can be equal to ``CAN_MTU``
> > +  for classical CAN frames or ``CANFD_MTU`` for CAN FD frames.
> > +
> > +* ``tx_dl``: maximum payload length for transmitted frames, can have one value
> > +  among: 8, 12, 16, 20, 24, 32, 48, 64.
> 
> Values above 8 only apply to CAN FD traffic (mtu = CANFD_MTU).
>

Right, I'll add a note.

> > +
> > +* ``tx_flags``: flags set set into ``struct canfd_frame.flags`` at frame
> > +  creation.
> 
> Only applies to CAN FD traffic (mtu = CANFD_MTU).
>

(see above)

> > +
> > +Basic node example
> > +------------------
> > +
> > +Following example implements a node using "normal" physical addressing, with
> > +RX ID equal to 0x18DAF142 and a TX ID equal to 0x18DA42F1. All options are left
> > +to their default.
> > +
> > +.. code-block:: C
> > +
> > +  int s;
> > +  struct sockaddr_can addr;
> > +  int ret;
> > +
> > +  s = socket(PF_CAN, SOCK_DGRAM, CAN_ISOTP);
> > +  if (s < 0)
> > +      exit(1);
> > +
> > +  addr.can_family = AF_CAN;
> > +  addr.can_ifindex = if_nametoindex("can0");
> > +  addr.tp.tx_id = 0x18DA42F1;
> > +  addr.tp.rx_id = 0x18DAF142;
> 
> Shouldn't this be (0x18DA42F1 | CAN_EFF_FLAG) for 29 bit IDs?
> 
> When you provide an example with 11 bit IDs (e.g. 0x700 and 0x714) you don't
> need to care about the CAN_EFF_FLAG.
>

Correct, I always forget the CAN_EFF_FLAG.



Thank you for the very thorough review! I'll wait for other feedbacks (if
any) and then start working on the v2.

Regards,
Francesco