* [RFC PATCH 0/1] Documentation: networking: document CAN ISO-TP
@ 2024-03-13 22:34 Francesco Valla
2024-03-13 22:34 ` [PATCH 1/1] " Francesco Valla
0 siblings, 1 reply; 11+ messages in thread
From: Francesco Valla @ 2024-03-13 22:34 UTC (permalink / raw
To: Oliver Hartkopp, Marc Kleine-Budde, David S. Miller, Eric Dumazet,
Jakub Kicinski, Paolo Abeni
Cc: fabio, linux-can, netdev, linux-kernel, Francesco Valla
While the in-kernel ISO-TP stack is fully functional and easy to use, no
documentation exists for it. This patch adds such documentation,
containing the very basics of the protocol, the APIs and a basic
example.
Sending as RFC because my experience with the stack is as user and not
as its developer, and also because it's my first kernel contribution.
Thank you,
Francesco
Francesco Valla (1):
Documentation: networking: document CAN ISO-TP
Documentation/networking/index.rst | 1 +
Documentation/networking/isotp.rst | 347 +++++++++++++++++++++++++++++
2 files changed, 348 insertions(+)
create mode 100644 Documentation/networking/isotp.rst
--
2.44.0
^ permalink raw reply [flat|nested] 11+ messages in thread
* [PATCH 1/1] Documentation: networking: document CAN ISO-TP
2024-03-13 22:34 [RFC PATCH 0/1] Documentation: networking: document CAN ISO-TP Francesco Valla
@ 2024-03-13 22:34 ` Francesco Valla
2024-03-14 11:20 ` Marc Kleine-Budde
` (3 more replies)
0 siblings, 4 replies; 11+ messages in thread
From: Francesco Valla @ 2024-03-13 22:34 UTC (permalink / raw
To: Oliver Hartkopp, Marc Kleine-Budde, David S. Miller, Eric Dumazet,
Jakub Kicinski, Paolo Abeni
Cc: fabio, linux-can, netdev, linux-kernel, Francesco Valla
Document basic concepts, APIs and behaviour of the CAN ISO-TP (ISO
15765-2) stack.
Signed-off-by: Francesco Valla <valla.francesco@gmail.com>
---
Documentation/networking/index.rst | 1 +
Documentation/networking/isotp.rst | 347 +++++++++++++++++++++++++++++
2 files changed, 348 insertions(+)
create mode 100644 Documentation/networking/isotp.rst
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
j1939
kapi
msg_zerocopy
diff --git a/Documentation/networking/isotp.rst b/Documentation/networking/isotp.rst
new file mode 100644
index 000000000000..d0c49fd1f5c9
--- /dev/null
+++ b/Documentation/networking/isotp.rst
@@ -0,0 +1,347 @@
+.. SPDX-License-Identifier: (GPL-2.0 OR BSD-3-Clause)
+
+====================
+ISO-TP (ISO 15765-2) Transport Protocol
+====================
+
+Overview
+=========================
+
+ISO-TP, also known as ISO 15765-2 from the ISO standard it is defined in, is a
+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.
+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
+connected to the same network:
+
+- a physical address, which identifies a single node and is used in 1-to-1
+ communication
+- a functional addess, which identifies a group of nodes and is used in 1-to-N
+ communication
+
+In a so-called "normal" addressing scenario, both these addresses are
+represented by a single byte and can be inserted inside the 29-bit version of
+the CAN ID. 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).
+
+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
+Frame - FF) to the receiver the maximum supported size of a macro data block
+(``blocksize``) and the minimum time time between the single CAN messages
+composing such block (``stmin``). Once these informations have been received,
+the sender starts to send frames containing fragments of the data payload
+(called Consecutive Frames - CF), stopping after every ``blocksize``-sized block
+to wait confirmation from the receiver (which should then send a Flow Control
+frame - FC - to inform the sender about its availability to receive more data).
+
+Specifications used
+-------------------
+
+* ISO 15765-2 : Road vehicles - Diagnostic communication over Controller Area
+ Network (DoCAN). Part 2: Transport protocol and network layer services.
+
+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.
+
+Creation and basic usage of an ISO-TP socket
+--------------------------------------------
+
+To use the ISO-TP stack, ``#include <linux/can/isotp.h>`` shall be used. A
+socket can then be created using the ``PF_CAN`` protocol family, the
+``SOCK_DGRAM`` type (as the underlying protocol is datagram-based by design)
+and the ``CAN_ISOTP`` protocol:
+
+.. code-block:: C
+
+ s = socket(PF_CAN, SOCK_DGRAM, CAN_ISOTP);
+
+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)
+
+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
+these calls, as the CAN header is automatically filled by the ISO-TP stack
+using information supplied during socket creation. In the same way, the stack
+will use the transport mechanism when required (i.e., when the size of the data
+payload exceeds the MTU of the underlying CAN bus).
+
+The sockaddr structure used for SocketCAN has extensions for use with ISO-TP,
+as specified below:
+
+.. code-block:: C
+
+ struct sockaddr_can {
+ sa_family_t can_family;
+ int can_ifindex;
+ union {
+ struct { canid_t rx_id, tx_id; } tp;
+ ...
+ } can_addr;
+ }
+
+* ``can_family`` and ``can_ifindex`` serve the same purpose as for other
+ SocketCAN sockets.
+
+* ``can_addr.tp.rx_id`` specifies the receive (RX) CAN ID and will be used as
+ a RX filter.
+
+* ``can_addr.tp.tx_id`` specifies the transmit (TX) CAN ID
+
+ISO-TP socket options
+---------------------
+
+When creating an ISO-TP socket, reasonable defaults are set. Some options can
+be modified with ``setsockopt(2)`` and/or read back with ``getsockopt(2)``.
+
+General options
+~~~~~~~~~~~~~~~
+
+General socket options can be passed using the ``CAN_ISOTP_OPTS`` optname:
+
+.. code-block:: C
+
+ struct can_isotp_options opts;
+ ret = setsockopt(s, SOL_CAN_ISOTP, CAN_ISOTP_OPTS, &opts, sizeof(opts))
+
+where the ``can_isotp_options`` structure has the following contents:
+
+.. code-block:: C
+
+ struct can_isotp_options {
+ u32 flags;
+ u32 frame_txtime;
+ u8 ext_address;
+ u8 txpad_content;
+ u8 rxpad_content;
+ u8 rx_ext_address;
+ };
+
+* ``flags``: modifiers to be applied to the default behaviour of the ISO-TP
+ stack. Following flags are available:
+
+ - ``CAN_ISOTP_LISTEN_MODE``: listen only (do not send FC frames)
+ - ``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
+ - ``CAN_ISOTP_FORCE_RXSTMIN``: ignore CFs depending on rx stmin
+ - ``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``)
+ - ``CAN_ISOTP_DYN_FC_PARMS``: enable dynamic update of flow control parameters
+
+* ``frame_txtime``: frame transmission time (defined as N_As/N_Ar inside the
+ ISO standard); if ``0``, the default (or the last set value) is used.
+ To set the transmission time to ``0``, the ``CAN_ISOTP_FRAME_TXTIME_ZERO``
+ macro (equal to 0xFFFFFFFF) shall be used.
+
+* ``ext_address``: extended addressing byte, used if the
+ ``CAN_ISOTP_EXTEND_ADDR`` flag is specified.
+
+* ``txpad_content``: byte used as padding value for transmitted frames
+
+* ``rxpad_content``: byte used as padding value for received frames
+
+* ``rx_ext_address``: extended addressing byte for the reception path, used if
+ the ``CAN_ISOTP_RX_EXT_ADDR`` flag is specified.
+
+Flow Control options
+~~~~~~~~~~~~~~~~~~~~
+
+Flow Control (FC) options can be passed using the ``CAN_ISOTP_RECV_FC`` optname:
+
+.. code-block:: C
+
+ struct can_isotp_fc_options fc_opts;
+ ret = setsockopt(s, SOL_CAN_ISOTP, CAN_ISOTP_RECV_FC, &fc_opts, sizeof(fc_opts));
+
+where the ``can_isotp_fc_options`` structure has the following contents:
+
+.. code-block:: C
+
+ struct can_isotp_options {
+ u8 bs;
+ u8 stmin;
+ u8 wftmax;
+ };
+
+* ``bs``: blocksize provided in flow control frames.
+
+* ``stmin``: minimum separation time provided in flow control frames; can
+ have the following values (others are reserved):
+ - 0x00 - 0x7F : 0 - 127 ms
+ - 0xF1 - 0xF9 : 100 us - 900 us
+
+* ``wftmax``: maximum number of wait frames provided in flow control frames.
+
+Link Layer options
+~~~~~~~~~~~~~~~~~~
+
+Link Layer (LL) options can be passed using the ``CAN_ISOTP_LL_OPTS`` optname:
+
+.. code-block:: C
+
+ struct can_isotp_ll_options ll_opts;
+ ret = setsockopt(s, SOL_CAN_ISOTP, CAN_ISOTP_LL_OPTS, &ll_opts, sizeof(ll_opts));
+
+where the ``can_isotp_ll_options`` structure has the following contents:
+
+.. code-block:: C
+
+ struct can_isotp_ll_options {
+ u8 mtu;
+ u8 tx_dl;
+ u8 tx_flags;
+ };
+
+* ``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.
+
+* ``tx_flags``: flags set set into ``struct canfd_frame.flags`` at frame
+ creation.
+
+Transmission stmin
+~~~~~~~~~~~~~~~~~~
+
+The transmission minimum separaton time (stmin) can be forced using the
+``CAN_ISOTP_TX_STMIN`` optname and providing an stmin value in microseconds as
+a 32bit unsigned integer; this will overwrite the value sent by the receiver in
+flow control frames:
+
+.. code-block:: C
+
+ uint32_t stmin;
+ ret = setsockopt(s, SOL_CAN_ISOTP, CAN_ISOTP_TX_STMIN, &stmin, sizeof(stmin));
+
+Reception stmin
+~~~~~~~~~~~~~~~
+
+The reception minimum separaton time (stmin) can be forced using the
+``CAN_ISOTP_RX_STMIN`` optname and providing an stmin value in microseconds as
+a 32bit unsigned integer; received Consecutive Frames (CF) which timestamps
+differ less than this value will be ignored:
+
+.. code-block:: C
+
+ uint32_t stmin;
+ ret = setsockopt(s, SOL_CAN_ISOTP, CAN_ISOTP_RX_STMIN, &stmin, sizeof(stmin));
+
+Multi-frame transport support
+--------------------------
+
+The ISO-TP stack contained inside the Linux kernel supports the multi-frame
+transport mechanism defined by the standard, with the following contraints:
+
+* the maximum size of a PDU is defined by a module parameter, with an hard
+ limit imposed at build time
+* when a transmission is in progress, subsequent calls to ``write(2)`` will
+ block, while calls to ``send(2)`` will either block or fail depending on the
+ presence of the ``MSG_DONTWAIT`` flag
+* no support is present for sending "wait frames": wheter a PDU can be fully
+ received or not is decided when the First Frame is received
+
+Errors
+------
+
+Following errors are reported to userspace:
+
+RX path errors
+~~~~~~~~~~~~~~
+
+============ =================================================================
+-ETIMEDOUT timeout of data reception
+-EILSEQ sequence number mismatch during a multi-frame reception
+-EBADMSG data reception with wrong padding
+============ =================================================================
+
+TX path errors
+~~~~~~~~~~~~~~
+
+========== =================================================================
+-ECOMM flow control reception timeout
+-EMSGSIZE flow control reception overflow
+-EBADMSG flow control reception with wrong layout/padding
+========== =================================================================
+
+Examples
+========
+
+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;
+
+ ret = bind(s, (struct sockaddr *)&addr, sizeof(addr));
+ if (ret < 0)
+ exit(1);
+
+ // Data can now be received using read(s, ...) and sent using write(s, ...)
+
+Additional examples
+-------------------
+
+More complete (and complex) examples can be found inside the ``isotp*`` userland
+tools, distributed as part of the ``can-utils`` utilities at:
+https://github.com/linux-can/can-utils
--
2.44.0
^ permalink raw reply related [flat|nested] 11+ messages in thread
* Re: [PATCH 1/1] Documentation: networking: document CAN ISO-TP
2024-03-13 22:34 ` [PATCH 1/1] " Francesco Valla
@ 2024-03-14 11:20 ` Marc Kleine-Budde
2024-03-14 21:12 ` Francesco Valla
2024-03-14 12:59 ` Oliver Hartkopp
` (2 subsequent siblings)
3 siblings, 1 reply; 11+ messages in thread
From: Marc Kleine-Budde @ 2024-03-14 11:20 UTC (permalink / raw
To: Francesco Valla
Cc: Oliver Hartkopp, David S. Miller, Eric Dumazet, Jakub Kicinski,
Paolo Abeni, fabio, linux-can, netdev, linux-kernel
[-- Attachment #1: Type: text/plain, Size: 2260 bytes --]
Hello Francesco,
thanks for your contribution! I've some remarks to make it a valid rst
file.
On 13.03.2024 23:34:31, Francesco Valla wrote:
> Document basic concepts, APIs and behaviour of the CAN ISO-TP (ISO
> 15765-2) stack.
>
> Signed-off-by: Francesco Valla <valla.francesco@gmail.com>
> ---
> Documentation/networking/index.rst | 1 +
> Documentation/networking/isotp.rst | 347 +++++++++++++++++++++++++++++
> 2 files changed, 348 insertions(+)
> create mode 100644 Documentation/networking/isotp.rst
>
> 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
> j1939
> kapi
> msg_zerocopy
> diff --git a/Documentation/networking/isotp.rst b/Documentation/networking/isotp.rst
> new file mode 100644
> index 000000000000..d0c49fd1f5c9
> --- /dev/null
> +++ b/Documentation/networking/isotp.rst
> @@ -0,0 +1,347 @@
> +.. SPDX-License-Identifier: (GPL-2.0 OR BSD-3-Clause)
> +
> +====================
> +ISO-TP (ISO 15765-2) Transport Protocol
> +====================
Please make the "=" as long as the text it encloses.
> +
> +Overview
> +=========================
Same here
[...]
> +Reception stmin
> +~~~~~~~~~~~~~~~
> +
> +The reception minimum separaton time (stmin) can be forced using the
> +``CAN_ISOTP_RX_STMIN`` optname and providing an stmin value in microseconds as
> +a 32bit unsigned integer; received Consecutive Frames (CF) which timestamps
> +differ less than this value will be ignored:
> +
> +.. code-block:: C
> +
> + uint32_t stmin;
> + ret = setsockopt(s, SOL_CAN_ISOTP, CAN_ISOTP_RX_STMIN, &stmin, sizeof(stmin));
> +
> +Multi-frame transport support
> +--------------------------
same here
regards,
Marc
--
Pengutronix e.K. | Marc Kleine-Budde |
Embedded Linux | https://www.pengutronix.de |
Vertretung Nürnberg | Phone: +49-5121-206917-129 |
Amtsgericht Hildesheim, HRA 2686 | Fax: +49-5121-206917-9 |
[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 488 bytes --]
^ permalink raw reply [flat|nested] 11+ messages in thread
* Re: [PATCH 1/1] Documentation: networking: document CAN ISO-TP
2024-03-13 22:34 ` [PATCH 1/1] " Francesco Valla
2024-03-14 11:20 ` Marc Kleine-Budde
@ 2024-03-14 12:59 ` Oliver Hartkopp
2024-03-14 22:38 ` Francesco Valla
2024-03-15 4:55 ` Bagas Sanjaya
2024-03-19 12:06 ` Simon Horman
3 siblings, 1 reply; 11+ messages in thread
From: Oliver Hartkopp @ 2024-03-14 12:59 UTC (permalink / raw
To: Francesco Valla, Marc Kleine-Budde; +Cc: fabio, linux-can
-- (reduced the distribution list to Linux-CAN relevant receivers)
Hello Francesco,
many thanks for your contribution!
Additionally to the editorial remarks from Marc I would like to add some
technical feedback.
On 2024-03-13 23:34, Francesco Valla wrote:
> Document basic concepts, APIs and behaviour of the CAN ISO-TP (ISO
> 15765-2) stack.
>
> Signed-off-by: Francesco Valla <valla.francesco@gmail.com>
> ---
> Documentation/networking/index.rst | 1 +
> Documentation/networking/isotp.rst | 347 +++++++++++++++++++++++++++++
> 2 files changed, 348 insertions(+)
> create mode 100644 Documentation/networking/isotp.rst
>
> 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.
> j1939
> kapi
> msg_zerocopy
> diff --git a/Documentation/networking/isotp.rst b/Documentation/networking/isotp.rst
> new file mode 100644
> index 000000000000..d0c49fd1f5c9
> --- /dev/null
> +++ b/Documentation/networking/isotp.rst
> @@ -0,0 +1,347 @@
> +.. SPDX-License-Identifier: (GPL-2.0 OR BSD-3-Clause)
> +
> +====================
> +ISO-TP (ISO 15765-2) Transport Protocol
ISO 15765-2:2016
> +====================
> +
> +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 ...
> +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)
> +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
> +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 ...
> +- 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 ...
> +
> +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.
and can be inserted inside the 29-bit version of
> +the CAN ID.
> 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.
> +
> +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
> +Frame - FF) to the receiver the maximum supported size of a macro data block
> +(``blocksize``) and the minimum time time between the single CAN messages
> +composing such block (``stmin``). Once these informations have been received,
> +the sender starts to send frames containing fragments of the data payload
> +(called Consecutive Frames - CF), stopping after every ``blocksize``-sized block
> +to wait confirmation from the receiver (which should then send a Flow Control
> +frame - FC - to inform the sender about its availability to receive more data).
> +
> +Specifications used
> +-------------------
> +
> +* ISO 15765-2 : Road vehicles - Diagnostic communication over Controller Area
ISO 15765-2:2016
> + Network (DoCAN). Part 2: Transport protocol and network layer services.
> +
> +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.
> +
> +Creation and basic usage of an ISO-TP socket
> +--------------------------------------------
> +
> +To use the ISO-TP stack, ``#include <linux/can/isotp.h>`` shall be used. A
> +socket can then be created using the ``PF_CAN`` protocol family, the
> +``SOCK_DGRAM`` type (as the underlying protocol is datagram-based by design)
> +and the ``CAN_ISOTP`` protocol:
> +
> +.. code-block:: C
> +
> + s = socket(PF_CAN, SOCK_DGRAM, CAN_ISOTP);
> +
> +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.
> +
> +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 ...
> +these calls, as the CAN header is automatically filled by the ISO-TP stack
> +using information supplied during socket creation. In the same way, the stack
> +will use the transport mechanism when required (i.e., when the size of the data
> +payload exceeds the MTU of the underlying CAN bus).
> +
> +The sockaddr structure used for SocketCAN has extensions for use with ISO-TP,
> +as specified below:
> +
> +.. code-block:: C
> +
> + struct sockaddr_can {
> + sa_family_t can_family;
> + int can_ifindex;
> + union {
> + struct { canid_t rx_id, tx_id; } tp;
> + ...
> + } can_addr;
> + }
> +
> +* ``can_family`` and ``can_ifindex`` serve the same purpose as for other
> + SocketCAN sockets.
> +
> +* ``can_addr.tp.rx_id`` specifies the receive (RX) CAN ID and will be used as
> + a RX filter.
> +
> +* ``can_addr.tp.tx_id`` specifies the transmit (TX) CAN ID
> +
> +ISO-TP socket options
> +---------------------
> +
> +When creating an ISO-TP socket, reasonable defaults are set. Some options can
> +be modified with ``setsockopt(2)`` and/or read back with ``getsockopt(2)``.
> +
> +General options
> +~~~~~~~~~~~~~~~
> +
> +General socket options can be passed using the ``CAN_ISOTP_OPTS`` optname:
> +
> +.. code-block:: C
> +
> + struct can_isotp_options opts;
> + ret = setsockopt(s, SOL_CAN_ISOTP, CAN_ISOTP_OPTS, &opts, sizeof(opts))
> +
> +where the ``can_isotp_options`` structure has the following contents:
> +
> +.. code-block:: C
> +
> + struct can_isotp_options {
> + u32 flags;
> + u32 frame_txtime;
> + u8 ext_address;
> + u8 txpad_content;
> + u8 rxpad_content;
> + u8 rx_ext_address;
> + };
> +
> +* ``flags``: modifiers to be applied to the default behaviour of the ISO-TP
> + stack. Following flags are available:
> +
> + - ``CAN_ISOTP_LISTEN_MODE``: listen only (do not send FC frames)
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
> + - ``CAN_ISOTP_FORCE_RXSTMIN``: ignore CFs depending on rx stmin
a testing feature
> + - ``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.
> + - ``CAN_ISOTP_DYN_FC_PARMS``: enable dynamic update of flow control parameters
> +
> +* ``frame_txtime``: frame transmission time (defined as N_As/N_Ar inside the
> + ISO standard); if ``0``, the default (or the last set value) is used.
> + To set the transmission time to ``0``, the ``CAN_ISOTP_FRAME_TXTIME_ZERO``
> + macro (equal to 0xFFFFFFFF) shall be used.
> +
> +* ``ext_address``: extended addressing byte, used if the
> + ``CAN_ISOTP_EXTEND_ADDR`` flag is specified.
> +
> +* ``txpad_content``: byte used as padding value for transmitted frames
> +
> +* ``rxpad_content``: byte used as padding value for received frames
> +
> +* ``rx_ext_address``: extended addressing byte for the reception path, used if
> + the ``CAN_ISOTP_RX_EXT_ADDR`` flag is specified.
> +
> +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.
> +
> +.. code-block:: C
> +
> + struct can_isotp_fc_options fc_opts;
> + ret = setsockopt(s, SOL_CAN_ISOTP, CAN_ISOTP_RECV_FC, &fc_opts, sizeof(fc_opts));
> +
> +where the ``can_isotp_fc_options`` structure has the following contents:
> +
> +.. code-block:: C
> +
> + struct can_isotp_options {
> + u8 bs;
> + u8 stmin;
> + u8 wftmax;
> + };
> +
> +* ``bs``: blocksize provided in flow control frames.
> +
> +* ``stmin``: minimum separation time provided in flow control frames; can
> + have the following values (others are reserved):
> + - 0x00 - 0x7F : 0 - 127 ms
> + - 0xF1 - 0xF9 : 100 us - 900 us
> +
> +* ``wftmax``: maximum number of wait frames provided in flow control frames.
> +
> +Link Layer options
> +~~~~~~~~~~~~~~~~~~
> +
> +Link Layer (LL) options can be passed using the ``CAN_ISOTP_LL_OPTS`` optname:
> +
> +.. code-block:: C
> +
> + struct can_isotp_ll_options ll_opts;
> + ret = setsockopt(s, SOL_CAN_ISOTP, CAN_ISOTP_LL_OPTS, &ll_opts, sizeof(ll_opts));
> +
> +where the ``can_isotp_ll_options`` structure has the following contents:
> +
> +.. code-block:: C
> +
> + struct can_isotp_ll_options {
> + u8 mtu;
> + u8 tx_dl;
> + u8 tx_flags;
> + };
> +
> +* ``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).
> +
> +* ``tx_flags``: flags set set into ``struct canfd_frame.flags`` at frame
> + creation.
Only applies to CAN FD traffic (mtu = CANFD_MTU).
> +
> +Transmission stmin
> +~~~~~~~~~~~~~~~~~~
> +
> +The transmission minimum separaton time (stmin) can be forced using the
> +``CAN_ISOTP_TX_STMIN`` optname and providing an stmin value in microseconds as
> +a 32bit unsigned integer; this will overwrite the value sent by the receiver in
> +flow control frames:
> +
> +.. code-block:: C
> +
> + uint32_t stmin;
> + ret = setsockopt(s, SOL_CAN_ISOTP, CAN_ISOTP_TX_STMIN, &stmin, sizeof(stmin));
> +
> +Reception stmin
> +~~~~~~~~~~~~~~~
> +
> +The reception minimum separaton time (stmin) can be forced using the
> +``CAN_ISOTP_RX_STMIN`` optname and providing an stmin value in microseconds as
> +a 32bit unsigned integer; received Consecutive Frames (CF) which timestamps
> +differ less than this value will be ignored:
> +
> +.. code-block:: C
> +
> + uint32_t stmin;
> + ret = setsockopt(s, SOL_CAN_ISOTP, CAN_ISOTP_RX_STMIN, &stmin, sizeof(stmin));
> +
> +Multi-frame transport support
> +--------------------------
> +
> +The ISO-TP stack contained inside the Linux kernel supports the multi-frame
> +transport mechanism defined by the standard, with the following contraints:
> +
> +* the maximum size of a PDU is defined by a module parameter, with an hard
> + limit imposed at build time
> +* when a transmission is in progress, subsequent calls to ``write(2)`` will
> + block, while calls to ``send(2)`` will either block or fail depending on the
> + presence of the ``MSG_DONTWAIT`` flag
> +* no support is present for sending "wait frames": wheter a PDU can be fully
> + received or not is decided when the First Frame is received
> +
> +Errors
> +------
> +
> +Following errors are reported to userspace:
> +
> +RX path errors
> +~~~~~~~~~~~~~~
> +
> +============ =================================================================
> +-ETIMEDOUT timeout of data reception
> +-EILSEQ sequence number mismatch during a multi-frame reception
> +-EBADMSG data reception with wrong padding
> +============ =================================================================
> +
> +TX path errors
> +~~~~~~~~~~~~~~
> +
> +========== =================================================================
> +-ECOMM flow control reception timeout
> +-EMSGSIZE flow control reception overflow
> +-EBADMSG flow control reception with wrong layout/padding
> +========== =================================================================
> +
> +Examples
> +========
> +
> +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.
> +
> + ret = bind(s, (struct sockaddr *)&addr, sizeof(addr));
> + if (ret < 0)
> + exit(1);
> +
> + // Data can now be received using read(s, ...) and sent using write(s, ...)
> +
> +Additional examples
> +-------------------
> +
> +More complete (and complex) examples can be found inside the ``isotp*`` userland
> +tools, distributed as part of the ``can-utils`` utilities at:
> +https://github.com/linux-can/can-utils
Many thanks,
Oliver
^ permalink raw reply [flat|nested] 11+ messages in thread
* Re: [PATCH 1/1] Documentation: networking: document CAN ISO-TP
2024-03-14 11:20 ` Marc Kleine-Budde
@ 2024-03-14 21:12 ` Francesco Valla
0 siblings, 0 replies; 11+ messages in thread
From: Francesco Valla @ 2024-03-14 21:12 UTC (permalink / raw
To: Marc Kleine-Budde
Cc: Oliver Hartkopp, David S. Miller, Eric Dumazet, Jakub Kicinski,
Paolo Abeni, fabio, linux-can, netdev, linux-kernel
On Thu, Mar 14, 2024 at 12:20:10PM +0100, Marc Kleine-Budde wrote:
> Hello Francesco,
>
> thanks for your contribution! I've some remarks to make it a valid rst
> file.
>
I did a bit of rework on section titles just before sending and obviously
forgot to update the separators. Will do that in the v2 patch.
Thanks for the review!
Regards,
Francesco
^ permalink raw reply [flat|nested] 11+ messages in thread
* Re: [PATCH 1/1] Documentation: networking: document CAN ISO-TP
2024-03-14 12:59 ` Oliver Hartkopp
@ 2024-03-14 22:38 ` Francesco Valla
0 siblings, 0 replies; 11+ messages in thread
From: Francesco Valla @ 2024-03-14 22:38 UTC (permalink / raw
To: Oliver Hartkopp; +Cc: Marc Kleine-Budde, fabio, linux-can
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
^ permalink raw reply [flat|nested] 11+ messages in thread
* Re: [PATCH 1/1] Documentation: networking: document CAN ISO-TP
2024-03-13 22:34 ` [PATCH 1/1] " Francesco Valla
2024-03-14 11:20 ` Marc Kleine-Budde
2024-03-14 12:59 ` Oliver Hartkopp
@ 2024-03-15 4:55 ` Bagas Sanjaya
2024-03-15 16:36 ` Francesco Valla
2024-03-19 12:06 ` Simon Horman
3 siblings, 1 reply; 11+ messages in thread
From: Bagas Sanjaya @ 2024-03-15 4:55 UTC (permalink / raw
To: Francesco Valla, Oliver Hartkopp, Marc Kleine-Budde,
David S. Miller, Eric Dumazet, Jakub Kicinski, Paolo Abeni
Cc: fabio, Linux CAN, Linux Networking, Linux Kernel Mailing List
[-- Attachment #1: Type: text/plain, Size: 3116 bytes --]
On Wed, Mar 13, 2024 at 11:34:31PM +0100, Francesco Valla wrote:
> Document basic concepts, APIs and behaviour of the CAN ISO-TP (ISO
> 15765-2) stack.
>
> Signed-off-by: Francesco Valla <valla.francesco@gmail.com>
> ---
> Documentation/networking/index.rst | 1 +
> Documentation/networking/isotp.rst | 347 +++++++++++++++++++++++++++++
> 2 files changed, 348 insertions(+)
> create mode 100644 Documentation/networking/isotp.rst
>
> 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
> j1939
> kapi
> msg_zerocopy
> diff --git a/Documentation/networking/isotp.rst b/Documentation/networking/isotp.rst
> new file mode 100644
> index 000000000000..d0c49fd1f5c9
> --- /dev/null
> +++ b/Documentation/networking/isotp.rst
> @@ -0,0 +1,347 @@
> +.. SPDX-License-Identifier: (GPL-2.0 OR BSD-3-Clause)
> +
> +====================
> +ISO-TP (ISO 15765-2) Transport Protocol
> +====================
> +
> +Overview
> +=========================
> +
<snipped>...
> +Multi-frame transport support
> +--------------------------
> +
htmldocs build reports new warnings:
/home/bagas/repo/linux-kernel/Documentation/networking/isotp.rst:3: WARNING: Title overline too short.
====================
ISO-TP (ISO 15765-2) Transport Protocol
====================
/home/bagas/repo/linux-kernel/Documentation/networking/isotp.rst:275: WARNING: Title underline too short.
Multi-frame transport support
--------------------------
/home/bagas/repo/linux-kernel/Documentation/networking/isotp.rst:275: WARNING: Title underline too short.
Multi-frame transport support
--------------------------
I have applied the fixup:
---- >8 ----
diff --git a/Documentation/networking/isotp.rst b/Documentation/networking/isotp.rst
index d0c49fd1f5c976..a104322ddb6c5e 100644
--- a/Documentation/networking/isotp.rst
+++ b/Documentation/networking/isotp.rst
@@ -1,11 +1,11 @@
.. SPDX-License-Identifier: (GPL-2.0 OR BSD-3-Clause)
-====================
+=======================================
ISO-TP (ISO 15765-2) Transport Protocol
-====================
+=======================================
Overview
-=========================
+========
ISO-TP, also known as ISO 15765-2 from the ISO standard it is defined in, is a
transport protocol specifically defined for diagnostic communication on CAN.
@@ -272,7 +272,7 @@ differ less than this value will be ignored:
ret = setsockopt(s, SOL_CAN_ISOTP, CAN_ISOTP_RX_STMIN, &stmin, sizeof(stmin));
Multi-frame transport support
---------------------------
+-----------------------------
The ISO-TP stack contained inside the Linux kernel supports the multi-frame
transport mechanism defined by the standard, with the following contraints:
Thanks.
--
An old man doll... just what I always wanted! - Clara
[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]
^ permalink raw reply related [flat|nested] 11+ messages in thread
* Re: [PATCH 1/1] Documentation: networking: document CAN ISO-TP
2024-03-15 4:55 ` Bagas Sanjaya
@ 2024-03-15 16:36 ` Francesco Valla
0 siblings, 0 replies; 11+ messages in thread
From: Francesco Valla @ 2024-03-15 16:36 UTC (permalink / raw
To: Bagas Sanjaya
Cc: Oliver Hartkopp, Marc Kleine-Budde, David S. Miller, Eric Dumazet,
Jakub Kicinski, Paolo Abeni, fabio, Linux CAN, Linux Networking,
Linux Kernel Mailing List
On Fri, Mar 15, 2024 at 11:55:04AM +0700, Bagas Sanjaya wrote:
<snip>
>
> htmldocs build reports new warnings:
>
> /home/bagas/repo/linux-kernel/Documentation/networking/isotp.rst:3: WARNING: Title overline too short.
>
> ====================
> ISO-TP (ISO 15765-2) Transport Protocol
> ====================
> /home/bagas/repo/linux-kernel/Documentation/networking/isotp.rst:275: WARNING: Title underline too short.
>
> Multi-frame transport support
> --------------------------
> /home/bagas/repo/linux-kernel/Documentation/networking/isotp.rst:275: WARNING: Title underline too short.
>
> Multi-frame transport support
> --------------------------
>
> I have applied the fixup:
>
> ---- >8 ----
> diff --git a/Documentation/networking/isotp.rst b/Documentation/networking/isotp.rst
> index d0c49fd1f5c976..a104322ddb6c5e 100644
> --- a/Documentation/networking/isotp.rst
> +++ b/Documentation/networking/isotp.rst
> @@ -1,11 +1,11 @@
> .. SPDX-License-Identifier: (GPL-2.0 OR BSD-3-Clause)
>
> -====================
> +=======================================
> ISO-TP (ISO 15765-2) Transport Protocol
> -====================
> +=======================================
>
> Overview
> -=========================
> +========
>
> ISO-TP, also known as ISO 15765-2 from the ISO standard it is defined in, is a
> transport protocol specifically defined for diagnostic communication on CAN.
> @@ -272,7 +272,7 @@ differ less than this value will be ignored:
> ret = setsockopt(s, SOL_CAN_ISOTP, CAN_ISOTP_RX_STMIN, &stmin, sizeof(stmin));
>
> Multi-frame transport support
> ---------------------------
> +-----------------------------
>
> The ISO-TP stack contained inside the Linux kernel supports the multi-frame
> transport mechanism defined by the standard, with the following contraints:
>
> Thanks.
>
> --
> An old man doll... just what I always wanted! - Clara
Thank you! Fixes (along with some rework) will be applied to the v2.
Regards,
Francesco
^ permalink raw reply [flat|nested] 11+ messages in thread
* Re: [PATCH 1/1] Documentation: networking: document CAN ISO-TP
2024-03-13 22:34 ` [PATCH 1/1] " Francesco Valla
` (2 preceding siblings ...)
2024-03-15 4:55 ` Bagas Sanjaya
@ 2024-03-19 12:06 ` Simon Horman
2024-03-20 22:35 ` Francesco Valla
3 siblings, 1 reply; 11+ messages in thread
From: Simon Horman @ 2024-03-19 12:06 UTC (permalink / raw
To: Francesco Valla
Cc: Oliver Hartkopp, Marc Kleine-Budde, David S. Miller, Eric Dumazet,
Jakub Kicinski, Paolo Abeni, fabio, linux-can, netdev,
linux-kernel
On Wed, Mar 13, 2024 at 11:34:31PM +0100, Francesco Valla wrote:
> Document basic concepts, APIs and behaviour of the CAN ISO-TP (ISO
> 15765-2) stack.
>
> Signed-off-by: Francesco Valla <valla.francesco@gmail.com>
Hi Francesco,
As it looks like there will be a v2 of this patchset
please consider running checkpatch.pl --codespell
and addressing the warnings it reports.
...
> +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
> +Frame - FF) to the receiver the maximum supported size of a macro data block
> +(``blocksize``) and the minimum time time between the single CAN messages
> +composing such block (``stmin``). Once these informations have been received,
nit: Once this information has
> +the sender starts to send frames containing fragments of the data payload
> +(called Consecutive Frames - CF), stopping after every ``blocksize``-sized block
> +to wait confirmation from the receiver (which should then send a Flow Control
> +frame - FC - to inform the sender about its availability to receive more data).
> +
...
^ permalink raw reply [flat|nested] 11+ messages in thread
* Re: [PATCH 1/1] Documentation: networking: document CAN ISO-TP
2024-03-19 12:06 ` Simon Horman
@ 2024-03-20 22:35 ` Francesco Valla
2024-03-21 12:34 ` Simon Horman
0 siblings, 1 reply; 11+ messages in thread
From: Francesco Valla @ 2024-03-20 22:35 UTC (permalink / raw
To: Simon Horman
Cc: Oliver Hartkopp, Marc Kleine-Budde, David S. Miller, Eric Dumazet,
Jakub Kicinski, Paolo Abeni, fabio, linux-can, netdev,
linux-kernel
Hi Simon,
On Tue, Mar 19, 2024 at 12:06:25PM +0000, Simon Horman wrote:
> On Wed, Mar 13, 2024 at 11:34:31PM +0100, Francesco Valla wrote:
> > Document basic concepts, APIs and behaviour of the CAN ISO-TP (ISO
> > 15765-2) stack.
> >
> > Signed-off-by: Francesco Valla <valla.francesco@gmail.com>
>
> Hi Francesco,
>
> As it looks like there will be a v2 of this patchset
> please consider running checkpatch.pl --codespell
> and addressing the warnings it reports.
>
Will do before v2, thanks for the suggestion.
> ...
>
> > +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
> > +Frame - FF) to the receiver the maximum supported size of a macro data block
> > +(``blocksize``) and the minimum time time between the single CAN messages
> > +composing such block (``stmin``). Once these informations have been received,
>
> nit: Once this information has
I never grasped the usage of "information" in English, which is not my
first language. I'll make this correction here.
>
> > +the sender starts to send frames containing fragments of the data payload
> > +(called Consecutive Frames - CF), stopping after every ``blocksize``-sized block
> > +to wait confirmation from the receiver (which should then send a Flow Control
> > +frame - FC - to inform the sender about its availability to receive more data).
> > +
>
> ...
Thanks for the review!
Regards,
Francesco
^ permalink raw reply [flat|nested] 11+ messages in thread
* Re: [PATCH 1/1] Documentation: networking: document CAN ISO-TP
2024-03-20 22:35 ` Francesco Valla
@ 2024-03-21 12:34 ` Simon Horman
0 siblings, 0 replies; 11+ messages in thread
From: Simon Horman @ 2024-03-21 12:34 UTC (permalink / raw
To: Francesco Valla
Cc: Oliver Hartkopp, Marc Kleine-Budde, David S. Miller, Eric Dumazet,
Jakub Kicinski, Paolo Abeni, fabio, linux-can, netdev,
linux-kernel
On Wed, Mar 20, 2024 at 11:35:05PM +0100, Francesco Valla wrote:
>
> Hi Simon,
>
> On Tue, Mar 19, 2024 at 12:06:25PM +0000, Simon Horman wrote:
> > On Wed, Mar 13, 2024 at 11:34:31PM +0100, Francesco Valla wrote:
> > > Document basic concepts, APIs and behaviour of the CAN ISO-TP (ISO
> > > 15765-2) stack.
> > >
> > > Signed-off-by: Francesco Valla <valla.francesco@gmail.com>
> >
> > Hi Francesco,
> >
> > As it looks like there will be a v2 of this patchset
> > please consider running checkpatch.pl --codespell
> > and addressing the warnings it reports.
> >
>
> Will do before v2, thanks for the suggestion.
>
> > ...
> >
> > > +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
> > > +Frame - FF) to the receiver the maximum supported size of a macro data block
> > > +(``blocksize``) and the minimum time time between the single CAN messages
> > > +composing such block (``stmin``). Once these informations have been received,
> >
> > nit: Once this information has
>
> I never grasped the usage of "information" in English, which is not my
> first language. I'll make this correction here.
I can't explain it properly, but my basic understanding
is that in English information is non-countable and thus has no plural.
Water is another example of a non-countable noun.
> > > +the sender starts to send frames containing fragments of the data payload
> > > +(called Consecutive Frames - CF), stopping after every ``blocksize``-sized block
> > > +to wait confirmation from the receiver (which should then send a Flow Control
> > > +frame - FC - to inform the sender about its availability to receive more data).
> > > +
> >
> > ...
>
> Thanks for the review!
>
> Regards,
> Francesco
>
^ permalink raw reply [flat|nested] 11+ messages in thread
end of thread, other threads:[~2024-03-21 12:34 UTC | newest]
Thread overview: 11+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2024-03-13 22:34 [RFC PATCH 0/1] Documentation: networking: document CAN ISO-TP Francesco Valla
2024-03-13 22:34 ` [PATCH 1/1] " Francesco Valla
2024-03-14 11:20 ` Marc Kleine-Budde
2024-03-14 21:12 ` Francesco Valla
2024-03-14 12:59 ` Oliver Hartkopp
2024-03-14 22:38 ` Francesco Valla
2024-03-15 4:55 ` Bagas Sanjaya
2024-03-15 16:36 ` Francesco Valla
2024-03-19 12:06 ` Simon Horman
2024-03-20 22:35 ` Francesco Valla
2024-03-21 12:34 ` Simon Horman
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.