Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update LINKTYPE_CAN_SOCKETCAN #40

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Update LINKTYPE_CAN_SOCKETCAN #40

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
82 changes: 37 additions & 45 deletions htmlsrc/linktypes/LINKTYPE_CAN_SOCKETCAN.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ <h2 class="title">
</h2>

<p>
This format supports CAN CC (classic CAN), CAN FD, and CAN XL frames.
This format supports CAN CC (Classical CAN), CAN FD, and CAN XL frames.
The same header is used for CAN CC and CAN FD frames; a different header
is used for CAN XL frames.
</p>
Expand All @@ -25,13 +25,13 @@ <h4>Packet structure</h4>
| Payload length |
| (1 Octet) |
+---------------------------+
| FD flags |
| FD flags (CAN FD) |
| (1 Octet) |
+---------------------------+
| Reserved/Padding |
| (1 Octet) |
+---------------------------+
| Reserved/Padding |
| Len 8 DLC (CAN CC) |
| (1 Octet) |
+---------------------------+
| Payload |
Expand All @@ -53,8 +53,8 @@ <h4>Description</h4>
The remaining bits are:
</p>
<ul>
<li><code>0x20000000</code> - set if the frame is an error message rather than a data frame.</li>
<li><code>0x40000000</code> - set if the frame is a remote transmission request frame.</li>
<li><code>0x20000000</code> - set if the frame is an error message rather than a data frame (CAN CC only).</li>
<li><code>0x40000000</code> - set if the frame is a remote transmission request frame (CAN CC only).</li>
<li><code>0x80000000</code> - set if the frame is an extended 29-bit frame rather than a standard 11-bit frame.</li>
</ul>

Expand All @@ -65,63 +65,48 @@ <h4>Description</h4>
</p>

<p>
The FD flags field contains CAN FD specific flags; for CAN CC frames,
this field is 0. The bits are:
</p>
The CAN frame types CAN CC and CAN FD can be distinguished by the frame length:
<ul>
<li><code>CANFD_BRS</code> (<code>0x01</code>) - bit rate switch (second bitrate for payload data).</li>
<li><code>CANFD_ESI</code> (<code>0x02</code>) - error state indicator of the transmitting node.</li>
<li><code>CANFD_FDF</code> (<code>0x04</code>) - if set, the frame is a CAN FD frame; if not set,
the frame may be a CAN CC frame or a CAN FD frame.</li>
<li>if the frame size (including the header and padding) is 16, it's a CAN CC frame
<li>if the frame size (including the header and padding) is 72, it's a CAN FD frame
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What if the frame size is neither 16 nor 72? As noted, there may be files in which that's the case.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What if the frame size is neither 16 nor 72? As noted, there may be files in which that's the case.

As in existing files, so adding an ex post facto restriction that the frame size for CAN CC frames must be 16 and CAN FD frames must be 72 doesn't fix that problem.

</ul>
</p>

<p>
Older software and firmware writing packets with this link type did not
use the <code>CANFD_FDF</code> flag for CAN FD frames, so if the
<code>CANFD_FDF</code> flag is not set, the frame is not guaranteed to
be a CAN CC frame. If that flag is not set:
The FD flags field contains CAN FD specific flags; for CAN CC frames, this
field is 0. The bits are:
</p>
<ul>
<li>if the frame size (including the header and padding) is 16, it's
a CAN CC frame;
<li>if the frame size (including the header and padding) is 72, it's
a CAN FD frame.
<li><code>CANFD_BRS</code> (<code>0x01</code>) - bit rate switch (second bitrate for payload data).</li>
<li><code>CANFD_ESI</code> (<code>0x02</code>) - error state indicator of the transmitting node.</li>
<li><code>CANFD_FDF</code> (<code>0x04</code>) - mark CAN FD for dual use of struct canfd_frame.</li>
</ul>

<p>
In addition, older software and firmware may not have explicitly set
that field, so that the bit corresponding to the <code>CANFD_FDF</code>
flag might be set even for CAN CC frames. Therefore, code that reads
<code>LINKTYPE_CAN_SOCKETCAN</code> frames must perform some heuristic
checks to make sure that it doesn't incorrectly interpret a CAN CC frame
as a CAN FD frame, and code that generates
<code>LINKTYPE_CAN_SOCKETCAN</code> frames must follow certain rules to
make sure that those checks don't cause software that reads those fromes
to treat a CAN FD frame as a CAN CC frame.
As the <code>CANFD_FDF</code> flag for CAN FD frames is not set reliably by the Linux kernel,
this flag can be used to identify CAN FD frames when using the struct canfd_frame as a container
for CAN FD and CAN CC frames in user space applications.
</p>

<p>
Software that reads <code>LINKTYPE_CAN_SOCKETCAN</code> frames must not
treat a frame with the <code>CANFD_FDF</code> bit set as a CAN FD frame
if any bits other than <code>CANFD_BRS</code> and <code>CANFD_ESI</code>
are set in that field, or if either of the Reserved/Padding fields are
non-zero, as that is an indication that the header fields might not have
been explicitly set, and the <code>CANFD_FDF</code> flag might happen to
be set even thugh the frame is not a CAN FD frame.
Software that reads <code>LINKTYPE_CAN_SOCKETCAN</code> frames must distinguish between CAN CC and CAN FD
ONLY by the frame length (16 or 72). Additionally the <code>0x80</code> bit of the fifth octet of the
Copy link
Member

@guyharris guyharris Jan 20, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The algorithm for frame type detection in Wireshark, proposed in this comment on Wireshark merge request 18710, does use the CANFD_FDF flag to distinguish between CAN CC and CAN FD frames; the code is (pseudo-code):

IF frame length == 72 OR FD flags has CANFD_FDF set
    IF frame length >= 8 AND frame length <= 72
        frame is CAN FD
    ELSE
        frame is invalid
    ENDIF
ELSE IF frame_length >= 8 AND frame length <= 16
    frame is CAN CC
ELSE
    frame is invalid
ENDIF

header has to be clear for CAN CC and CAN FD frames.
</p>

<p>
Software that generates <code>LINKTYPE_CAN_SOCKETCAN</code> frames:
Software that generates <code>LINKTYPE_CAN_SOCKETCAN</code> CAN CC and CAN FD frames:
</p>
<ul>
<li>Must check the frame MTU when receiving frames from the Linux
kernel in order to classify them as CAN CC frames or CAN FD frames.</li>
<li>Must create a the frame length according to the Linux kernel MTU definitions in order
to classify them as CAN CC frames (MTU = 16) or CAN FD frames (MTU = 72).</li>
<li>Must make the "FD flags" field 0 for CAN CC frames.</li>
<li>Must set the <code>CANFD_FDF</code> bit of the "FD flags" field in CAN FD frames,
and don't set any bits in that field other than the <code>CANFD_BRS</code> and <code>CANFD_ESI</code> bits
unless and until Linux assigns them a meaning.</li>
and <code>CANFD_BRS</code> and <code>CANFD_ESI</code> bits when needed. Unassigned bits in
the "FD flags" field should be set to 0</li>
<li>Must make the "Reserved/Padding" fields 0 unless and until Linux assigns
that particular field a meaning.</li>
that particular field a meaning.</li>
<li>Might set a Len 8 DLC value for CAN CC frames or set this field to 0.</li>
<li>May strip trailing padding bytes to save disk space if all above statements are satisfied.</li>
</ul>

Expand All @@ -131,8 +116,15 @@ <h4>Description</h4>
<p>

<p>
For a remote retransmission request, the payload length must be 0, so
the payload is empty.
A remote retransmission request (RTR) is only possible with CAN CC frames and the
(real) payload length on the CAN bus is always 0.
But as the 4-bit DLC value is always send inside a CAN CC frame all possible values (0 .. 15)
can be defined by the Linktype protocol.
<ul>
<li> DLC 0 .. 8: The data length value is set to 0 .. 8. The Len 8 DLC value is set to 0.</li>
<li> DLC 9 .. 15: The data length value is set to 8. The Len 8 DLC value is set to 9 .. 15.</li>
</ul>
The Len 8 DLC value is applicable to CAN CC data frames and CAN CC RTR frames.
<p>

<p>
Expand Down Expand Up @@ -209,7 +201,7 @@ <h4>Description</h4>
The flags field contains CAN XL specific flags. The bits are:
</p>
<ul>
<li><code>CANFD_SEC</code> (<code>0x01</code>) - Simple Extended Context.</li>
<li><code>CANXL_SEC</code> (<code>0x01</code>) - Simple Extended Context.</li>
<li><code>CANXL_XLF</code> (<code>0x80</code>) - if set, the frame is a CAN XL frame; if not set,
the frame is a CAN CC frame or a CAN FD frame.</li>
</ul>
Expand Down
82 changes: 37 additions & 45 deletions linktypes/LINKTYPE_CAN_SOCKETCAN.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -49,7 +49,7 @@ <h2 class="title">
</h2>

<p>
This format supports CAN CC (classic CAN), CAN FD, and CAN XL frames.
This format supports CAN CC (Classical CAN), CAN FD, and CAN XL frames.
The same header is used for CAN CC and CAN FD frames; a different header
is used for CAN XL frames.
</p>
Expand All @@ -69,13 +69,13 @@ <h4>Packet structure</h4>
| Payload length |
| (1 Octet) |
+---------------------------+
| FD flags |
| FD flags (CAN FD) |
| (1 Octet) |
+---------------------------+
| Reserved/Padding |
| (1 Octet) |
+---------------------------+
| Reserved/Padding |
| Len 8 DLC (CAN CC) |
| (1 Octet) |
+---------------------------+
| Payload |
Expand All @@ -97,8 +97,8 @@ <h4>Description</h4>
The remaining bits are:
</p>
<ul>
<li><code>0x20000000</code> - set if the frame is an error message rather than a data frame.</li>
<li><code>0x40000000</code> - set if the frame is a remote transmission request frame.</li>
<li><code>0x20000000</code> - set if the frame is an error message rather than a data frame (CAN CC only).</li>
<li><code>0x40000000</code> - set if the frame is a remote transmission request frame (CAN CC only).</li>
<li><code>0x80000000</code> - set if the frame is an extended 29-bit frame rather than a standard 11-bit frame.</li>
</ul>

Expand All @@ -109,63 +109,48 @@ <h4>Description</h4>
</p>

<p>
The FD flags field contains CAN FD specific flags; for CAN CC frames,
this field is 0. The bits are:
</p>
The CAN frame types CAN CC and CAN FD can be distinguished by the frame length:
<ul>
<li><code>CANFD_BRS</code> (<code>0x01</code>) - bit rate switch (second bitrate for payload data).</li>
<li><code>CANFD_ESI</code> (<code>0x02</code>) - error state indicator of the transmitting node.</li>
<li><code>CANFD_FDF</code> (<code>0x04</code>) - if set, the frame is a CAN FD frame; if not set,
the frame may be a CAN CC frame or a CAN FD frame.</li>
<li>if the frame size (including the header and padding) is 16, it's a CAN CC frame
<li>if the frame size (including the header and padding) is 72, it's a CAN FD frame
</ul>
</p>

<p>
Older software and firmware writing packets with this link type did not
use the <code>CANFD_FDF</code> flag for CAN FD frames, so if the
<code>CANFD_FDF</code> flag is not set, the frame is not guaranteed to
be a CAN CC frame. If that flag is not set:
The FD flags field contains CAN FD specific flags; for CAN CC frames, this
field is 0. The bits are:
</p>
<ul>
<li>if the frame size (including the header and padding) is 16, it's
a CAN CC frame;
<li>if the frame size (including the header and padding) is 72, it's
a CAN FD frame.
<li><code>CANFD_BRS</code> (<code>0x01</code>) - bit rate switch (second bitrate for payload data).</li>
<li><code>CANFD_ESI</code> (<code>0x02</code>) - error state indicator of the transmitting node.</li>
<li><code>CANFD_FDF</code> (<code>0x04</code>) - mark CAN FD for dual use of struct canfd_frame.</li>
</ul>

<p>
In addition, older software and firmware may not have explicitly set
that field, so that the bit corresponding to the <code>CANFD_FDF</code>
flag might be set even for CAN CC frames. Therefore, code that reads
<code>LINKTYPE_CAN_SOCKETCAN</code> frames must perform some heuristic
checks to make sure that it doesn't incorrectly interpret a CAN CC frame
as a CAN FD frame, and code that generates
<code>LINKTYPE_CAN_SOCKETCAN</code> frames must follow certain rules to
make sure that those checks don't cause software that reads those fromes
to treat a CAN FD frame as a CAN CC frame.
As the <code>CANFD_FDF</code> flag for CAN FD frames is not set reliably by the Linux kernel,
this flag can be used to identify CAN FD frames when using the struct canfd_frame as a container
for CAN FD and CAN CC frames in user space applications.
</p>

<p>
Software that reads <code>LINKTYPE_CAN_SOCKETCAN</code> frames must not
treat a frame with the <code>CANFD_FDF</code> bit set as a CAN FD frame
if any bits other than <code>CANFD_BRS</code> and <code>CANFD_ESI</code>
are set in that field, or if either of the Reserved/Padding fields are
non-zero, as that is an indication that the header fields might not have
been explicitly set, and the <code>CANFD_FDF</code> flag might happen to
be set even thugh the frame is not a CAN FD frame.
Software that reads <code>LINKTYPE_CAN_SOCKETCAN</code> frames must distinguish between CAN CC and CAN FD
ONLY by the frame length (16 or 72). Additionally the <code>0x80</code> bit of the fifth octet of the
header has to be clear for CAN CC and CAN FD frames.
</p>

<p>
Software that generates <code>LINKTYPE_CAN_SOCKETCAN</code> frames:
Software that generates <code>LINKTYPE_CAN_SOCKETCAN</code> CAN CC and CAN FD frames:
</p>
<ul>
<li>Must check the frame MTU when receiving frames from the Linux
kernel in order to classify them as CAN CC frames or CAN FD frames.</li>
<li>Must create a the frame length according to the Linux kernel MTU definitions in order
to classify them as CAN CC frames (MTU = 16) or CAN FD frames (MTU = 72).</li>
<li>Must make the "FD flags" field 0 for CAN CC frames.</li>
<li>Must set the <code>CANFD_FDF</code> bit of the "FD flags" field in CAN FD frames,
and don't set any bits in that field other than the <code>CANFD_BRS</code> and <code>CANFD_ESI</code> bits
unless and until Linux assigns them a meaning.</li>
and <code>CANFD_BRS</code> and <code>CANFD_ESI</code> bits when needed. Unassigned bits in
the "FD flags" field should be set to 0</li>
<li>Must make the "Reserved/Padding" fields 0 unless and until Linux assigns
that particular field a meaning.</li>
that particular field a meaning.</li>
<li>Might set a Len 8 DLC value for CAN CC frames or set this field to 0.</li>
<li>May strip trailing padding bytes to save disk space if all above statements are satisfied.</li>
</ul>

Expand All @@ -175,8 +160,15 @@ <h4>Description</h4>
<p>

<p>
For a remote retransmission request, the payload length must be 0, so
the payload is empty.
A remote retransmission request (RTR) is only possible with CAN CC frames and the
(real) payload length on the CAN bus is always 0.
But as the 4-bit DLC value is always send inside a CAN CC frame all possible values (0 .. 15)
can be defined by the Linktype protocol.
<ul>
<li> DLC 0 .. 8: The data length value is set to 0 .. 8. The Len 8 DLC value is set to 0.</li>
<li> DLC 9 .. 15: The data length value is set to 8. The Len 8 DLC value is set to 9 .. 15.</li>
</ul>
The Len 8 DLC value is applicable to CAN CC data frames and CAN CC RTR frames.
<p>

<p>
Expand Down Expand Up @@ -253,7 +245,7 @@ <h4>Description</h4>
The flags field contains CAN XL specific flags. The bits are:
</p>
<ul>
<li><code>CANFD_SEC</code> (<code>0x01</code>) - Simple Extended Context.</li>
<li><code>CANXL_SEC</code> (<code>0x01</code>) - Simple Extended Context.</li>
<li><code>CANXL_XLF</code> (<code>0x80</code>) - if set, the frame is a CAN XL frame; if not set,
the frame is a CAN CC frame or a CAN FD frame.</li>
</ul>
Expand Down