Skip to content

docs(linux): AM64X: Add ICSSG PRP Mode Docs #348

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

Merged
jeevantelukula merged 2 commits into from
Jul 21, 2025
Merged

docs(linux): AM64X: Add ICSSG PRP Mode Docs #348

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
835a999
feat(ICSSG): Add PRP mode docs for AM64X
hm-ti Jul 14, 2025
0b78f93
feat(ICSSG): Update Release notes for AM64X
hm-ti Jul 14, 2025
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
1 change: 1 addition & 0 deletions configs/AM64X/AM64X_linux_toc.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -58,6 +58,7 @@ linux/Foundational_Components/Kernel/Kernel_Drivers/Network/CPSW-TSN-Tuning
linux/Foundational_Components/Kernel/Kernel_Drivers/Network/NETCONF-YANG
linux/Foundational_Components/Kernel/Kernel_Drivers/Network/HSR_PRP_Non_Offload
linux/Foundational_Components/Kernel/Kernel_Drivers/Network/HSR_Offload
linux/Foundational_Components/Kernel/Kernel_Drivers/Network/PRP_Offload
linux/Foundational_Components/Kernel/Kernel_Drivers/SPI
linux/Foundational_Components/Kernel/Kernel_Drivers/PCIe/PCIe_End_Point
linux/Foundational_Components/Kernel/Kernel_Drivers/PCIe/PCIe_Root_Complex
Expand Down
10 changes: 9 additions & 1 deletion source/devices/AM64X/linux/Release_Specific_Release_Notes.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -50,6 +50,9 @@ What's new
- Important Bug Fixes on top of Processor SDK 10.01.10.04 Release
- Review Issue Tracker Section for the new fixes.

- This release adds support for PRP Offload to the ICSSG prueth-driver. This allows to offload PRP functionality
to the ICSSG hardware, which helps in reducing load on the A53 cores.

**Key Release References:**

- RT Kernel : Real-Time Linux Interrupt Latency numbers here - :ref:`RT Interrupt Latencies <RT-linux-performance>`
Expand Down Expand Up @@ -193,9 +196,15 @@ Issues Resolved
"EXT_EP-12111","Linux SDK v10.0: TI-added support for W25N01JW SPI NAND breaks other existing Flash support"
"EXT_EP-12051","AM64x: Linux hangs on repetitive probe/removal of gadget zero"
"EXT_EP-12071","sdk-doc: missing SK-AM64B information in CDNS3 USB page"
"EXT_EP-12336","Last 1B of payload missing in forwarding scenario"
"EXT_EP-12337","ICSSG: TAPRIO - Firmware can’t handle base-time which is not a multiple of cycle-time."
"EXT_EP-12338","ICSSG: PA_STATS are not sequenced properly"
"EXT_EP-12339","Switch/MAC/HSR firmware does not drop corrupted packets"
"EXT_EP-12715","Local injection (TX) - Transmission failure due ""TX Pkt not available"""
"EXT_EP-12716","PRU - Task Manager disable during firmware init"
"EXT_EP-12717","Packets reception failure: 10Mbps speed"
"EXT_EP-12718","Non-recoverable TX underflow with Bidirectional traffic in 100M MII mode"
"EXT_EP-12719","Throughput drop: Software buffer pool implementation @1G speed"


Issues Open
Expand All @@ -209,5 +218,4 @@ Issues Open
"EXT_EP-12300","ICSSG: Ethernet: Promiscuous mode is always enabled in bridge mode"
"EXT_EP-12075","U-boot gets stuck when DDR size changed to 512 MB"
"EXT_EP-12060","AM64x: Lower core count on variant devices no supported"
"EXT_EP-12336","Last 1B of payload missing in forwarding scenario"

Binary file added source/images/AM64_PRP_Setup.jpg
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
358 changes: 358 additions & 0 deletions source/linux/Foundational_Components/Kernel/Kernel_Drivers/Network/PRP_Offload.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,358 @@
===================
PRP Offload

Check warning on line 2 in source/linux/Foundational_Components/Kernel/Kernel_Drivers/Network/PRP_Offload.rst

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[RedHat.Definitions] Define acronyms and abbreviations (such as 'PRP') on first occurrence if they're likely to be unfamiliar.

Raw Output:
{"message": "[RedHat.Definitions] Define acronyms and abbreviations (such as 'PRP') on first occurrence if they're likely to be unfamiliar.", "location": {"path": "source/linux/Foundational_Components/Kernel/Kernel_Drivers/Network/PRP_Offload.rst", "range": {"start": {"line": 2, "column": 1}}}, "severity": "INFO"}

Check warning on line 2 in source/linux/Foundational_Components/Kernel/Kernel_Drivers/Network/PRP_Offload.rst

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[RedHat.Headings] Use sentence-style capitalization in 'PRP Offload'.

Raw Output:
{"message": "[RedHat.Headings] Use sentence-style capitalization in 'PRP Offload'.", "location": {"path": "source/linux/Foundational_Components/Kernel/Kernel_Drivers/Network/PRP_Offload.rst", "range": {"start": {"line": 2, "column": 1}}}, "severity": "INFO"}
===================

.. rubric:: **Introduction**

HSR (High-availability Seamless Redundancy) framework in Linux supports HSR and PRP (Parallel Redundancy Protocol) modes of redundancy by using 2 ports.

Check warning on line 7 in source/linux/Foundational_Components/Kernel/Kernel_Drivers/Network/PRP_Offload.rst

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[RedHat.Definitions] Define acronyms and abbreviations (such as 'PRP') on first occurrence if they're likely to be unfamiliar.

Raw Output:
{"message": "[RedHat.Definitions] Define acronyms and abbreviations (such as 'PRP') on first occurrence if they're likely to be unfamiliar.", "location": {"path": "source/linux/Foundational_Components/Kernel/Kernel_Drivers/Network/PRP_Offload.rst", "range": {"start": {"line": 7, "column": 81}}}, "severity": "INFO"}

Check warning on line 7 in source/linux/Foundational_Components/Kernel/Kernel_Drivers/Network/PRP_Offload.rst

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[RedHat.Definitions] Define acronyms and abbreviations (such as 'HSR') on first occurrence if they're likely to be unfamiliar.

Raw Output:
{"message": "[RedHat.Definitions] Define acronyms and abbreviations (such as 'HSR') on first occurrence if they're likely to be unfamiliar.", "location": {"path": "source/linux/Foundational_Components/Kernel/Kernel_Drivers/Network/PRP_Offload.rst", "range": {"start": {"line": 7, "column": 73}}}, "severity": "INFO"}

Check warning on line 7 in source/linux/Foundational_Components/Kernel/Kernel_Drivers/Network/PRP_Offload.rst

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[RedHat.Definitions] Define acronyms and abbreviations (such as 'HSR') on first occurrence if they're likely to be unfamiliar.

Raw Output:
{"message": "[RedHat.Definitions] Define acronyms and abbreviations (such as 'HSR') on first occurrence if they're likely to be unfamiliar.", "location": {"path": "source/linux/Foundational_Components/Kernel/Kernel_Drivers/Network/PRP_Offload.rst", "range": {"start": {"line": 7, "column": 1}}}, "severity": "INFO"}
It also allows to offload the below functionalities of PRP mode to the underlying hardware/device:

Check warning on line 8 in source/linux/Foundational_Components/Kernel/Kernel_Drivers/Network/PRP_Offload.rst

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[RedHat.Slash] Use either 'or' or 'and' in 'hardware/device'

Raw Output:
{"message": "[RedHat.Slash] Use either 'or' or 'and' in 'hardware/device'", "location": {"path": "source/linux/Foundational_Components/Kernel/Kernel_Drivers/Network/PRP_Offload.rst", "range": {"start": {"line": 8, "column": 83}}}, "severity": "WARNING"}

Check warning on line 8 in source/linux/Foundational_Components/Kernel/Kernel_Drivers/Network/PRP_Offload.rst

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[RedHat.Definitions] Define acronyms and abbreviations (such as 'PRP') on first occurrence if they're likely to be unfamiliar.

Raw Output:
{"message": "[RedHat.Definitions] Define acronyms and abbreviations (such as 'PRP') on first occurrence if they're likely to be unfamiliar.", "location": {"path": "source/linux/Foundational_Components/Kernel/Kernel_Drivers/Network/PRP_Offload.rst", "range": {"start": {"line": 8, "column": 56}}}, "severity": "INFO"}

Check warning on line 8 in source/linux/Foundational_Components/Kernel/Kernel_Drivers/Network/PRP_Offload.rst

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[RedHat.TermsSuggestions] Depending on the context, consider using 'after', 'later', or 'following' rather than 'below'.

Raw Output:
{"message": "[RedHat.TermsSuggestions] Depending on the context, consider using 'after', 'later', or 'following' rather than 'below'.", "location": {"path": "source/linux/Foundational_Components/Kernel/Kernel_Drivers/Network/PRP_Offload.rst", "range": {"start": {"line": 8, "column": 31}}}, "severity": "INFO"}

- hsr-tag-ins-offload: Add PRP trailer to the frame

Check warning on line 10 in source/linux/Foundational_Components/Kernel/Kernel_Drivers/Network/PRP_Offload.rst

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[RedHat.Definitions] Define acronyms and abbreviations (such as 'PRP') on first occurrence if they're likely to be unfamiliar.

Raw Output:
{"message": "[RedHat.Definitions] Define acronyms and abbreviations (such as 'PRP') on first occurrence if they're likely to be unfamiliar.", "location": {"path": "source/linux/Foundational_Components/Kernel/Kernel_Drivers/Network/PRP_Offload.rst", "range": {"start": {"line": 10, "column": 28}}}, "severity": "INFO"}
- hsr-dup-offload: Duplicate the outgoing PRP frame

Check warning on line 11 in source/linux/Foundational_Components/Kernel/Kernel_Drivers/Network/PRP_Offload.rst

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[RedHat.Definitions] Define acronyms and abbreviations (such as 'PRP') on first occurrence if they're likely to be unfamiliar.

Raw Output:
{"message": "[RedHat.Definitions] Define acronyms and abbreviations (such as 'PRP') on first occurrence if they're likely to be unfamiliar.", "location": {"path": "source/linux/Foundational_Components/Kernel/Kernel_Drivers/Network/PRP_Offload.rst", "range": {"start": {"line": 11, "column": 43}}}, "severity": "INFO"}
- hsr-tag-rm-offload: Remove PRP trailer from the frame

The ICSSG PRP firmware supports offloading of all above functionalities saving overhead from the driver.

.. note::

The offload of functionality hsr-fwd-offload should also be enabled for correct driver configuration.

The below script sets up a PRP interface with all possible offload functionalities enabled

.. code-block:: bash

#!/bin/sh

#For non offload - sh prp_setup.sh prp_sw <INTF_A> <INTF_B> <PRP_INTF_IP_ADDR>
#For offload - sh prp_setup.sh prp_hw <INTF_A> <INTF_B> <PRP_INTF_IP_ADDR>

if [ "$#" != "4" ]
then
echo "$0 <prp_sw/prp_hw> <intf1> <intf2> <ip addr>"
exit
fi

if [ "$1" != "prp_sw" ] && [ "$1" != "prp_hw" ]
then
echo "$0 <prp_sw|prp_hw>"
exit
fi

if=prp0

ifa=$2
ifb=$3

ip=$4
mac=$(ifconfig "$ifa" | grep ether | cut -d " " -f 10)

echo "ip=$ip"
echo "if=$if"
echo "mac=$mac"
echo "slave-a=$ifa"
echo "slave-b=$ifb"

ip link set $if down
ip link delete $if 2> /dev/null

if [ "$1" = "prp_hw" ]
then
echo "Available offload features for $ifa: "
ethtool -k "$ifa" | grep hsr
ethtool -K "$ifa" hsr-fwd-offload on
ethtool -K "$ifa" hsr-dup-offload on
ethtool -K "$ifa" hsr-tag-ins-offload on
ethtool -K "$ifa" hsr-tag-rm-offload on
echo "Enabled offload features for $ifa: "
ethtool -k "$ifa" | grep hsr

echo "Available offload features for $ifb: "
ethtool -k "$ifb" | grep hsr
ethtool -K "$ifb" hsr-fwd-offload on
ethtool -K "$ifb" hsr-dup-offload on
ethtool -K "$ifb" hsr-tag-ins-offload on
ethtool -K "$ifb" hsr-tag-rm-offload on
echo "Enabled offload features for $ifb: "
ethtool -k "$ifb" | grep hsr
fi

ip link set dev "$ifa" address "$mac"
ip link set dev "$ifb" address "$mac"

ip link add name $if type hsr slave1 "$ifa" slave2 "$ifb" supervision 45 proto 1

sleep 3

ip addr add "$ip"/24 dev $if
ip link set $if up

To create PRP interface with IP address 192.168.1.10 using eth1 and eth2,
run the script by passing the arguments as below

.. code-block:: console

sh prp_setup.sh prp_hw eth1 eth2 192.168.1.10

.. rubric:: *Multicast Filtering*

All multi-cast addresses not registered will be filtered out.

.. rubric:: Multicast Add/Delete

Multicast MAC address can be added/deleted using ip maddr commands or Linux socket ioctl SIOCADDMULTI/SIOCDELMULTI.

.. rubric:: Show multicast address

Show current list of multicast address for the PRP interface

.. code-block:: console

ip maddr show dev <prp_intf>

Example:

.. code-block:: console

# ip maddr show dev prp0
7: prp0
link 33:33:00:00:00:01 users 3
link 01:80:c2:00:00:0e users 3 static
link 01:80:c2:00:00:03 users 3 static
link 01:80:c2:00:00:00 users 3 static
link 01:00:5e:00:00:01 users 3
link 33:33:ff:1e:a0:a8 users 3
link 01:00:5e:00:00:fb users 3
link 33:33:00:00:00:fb users 3
inet 224.0.0.251
inet 224.0.0.1
inet6 ff02::fb
inet6 ff02::1:ff1e:a0a8
inet6 ff02::1
inet6 ff01::1

.. rubric:: Add multicast address

Add a multicast address

.. code-block:: console

ip maddr add <multicast_mac_addr> dev <prp_intf>

Example: To add a multicast address and display the list in PRP and slave ports

.. code-block:: console

# ip maddr add 01:80:c4:00:00:0e dev prp0
# ip maddr show dev prp0
7: prp0
link 33:33:00:00:00:01 users 3
link 01:80:c2:00:00:0e users 3 static
link 01:80:c2:00:00:03 users 3 static
link 01:80:c2:00:00:00 users 3 static
link 01:00:5e:00:00:01 users 3
link 33:33:ff:1e:a0:a8 users 3
link 01:00:5e:00:00:fb users 3
link 33:33:00:00:00:fb users 3
link 01:80:c4:00:00:0e users 3 static
inet 224.0.0.251
inet 224.0.0.1
inet6 ff02::fb
inet6 ff02::1:ff1e:a0a8
inet6 ff02::1
inet6 ff01::1

# ip maddr show dev eth1
5: eth1
link 33:33:00:00:00:01 users 3
link 01:00:5e:00:00:01 users 3
link 01:80:c2:00:00:0e users 4 static
link 01:80:c2:00:00:03 users 4 static
link 01:80:c2:00:00:00 users 4 static
link 33:33:ff:1e:a0:a8 users 3
link 33:33:00:00:00:fb users 3
link 01:00:5e:00:00:fb users 2
link 01:80:c4:00:00:0e users 2
inet 224.0.0.1
inet6 ff02::fb
inet6 ff02::1:ff1e:a0a8
inet6 ff02::1 users 2
inet6 ff01::1

# ip maddr show dev eth2
6: eth2
link 33:33:00:00:00:01 users 3
link 01:00:5e:00:00:01 users 3
link 01:80:c2:00:00:0e users 4 static
link 01:80:c2:00:00:03 users 4 static
link 01:80:c2:00:00:00 users 4 static
link 33:33:ff:1e:a0:a7 users 2
link 33:33:00:00:00:fb users 3
link 33:33:ff:1e:a0:a8 users 2
link 01:00:5e:00:00:fb users 2
link 01:80:c4:00:00:0e users 2
inet 224.0.0.1
inet6 ff02::fb
inet6 ff02::1:ff1e:a0a7
inet6 ff02::1 users 2
inet6 ff01::1

.. rubric:: Delete multicast address

Delete a multicast address

.. code-block:: console

ip maddr del <multicast_mac_addr> dev <prp_intf>

Example: To delete an added multicast address and dislay the list of PRP and
slave intefaces.

.. code-block:: console

# ip maddr del 01:80:c4:00:00:0e dev prp0
# ip maddr show dev prp0
7: prp0
link 33:33:00:00:00:01 users 3
link 01:80:c2:00:00:0e users 3 static
link 01:80:c2:00:00:03 users 3 static
link 01:80:c2:00:00:00 users 3 static
link 01:00:5e:00:00:01 users 3
link 33:33:ff:1e:a0:a8 users 3
link 01:00:5e:00:00:fb users 3
link 33:33:00:00:00:fb users 3
inet 224.0.0.251
inet 224.0.0.1
inet6 ff02::fb
inet6 ff02::1:ff1e:a0a8
inet6 ff02::1
inet6 ff01::1

# ip maddr show dev eth1
5: eth1
link 33:33:00:00:00:01 users 3
link 01:00:5e:00:00:01 users 3
link 01:80:c2:00:00:0e users 4 static
link 01:80:c2:00:00:03 users 4 static
link 01:80:c2:00:00:00 users 4 static
link 33:33:ff:1e:a0:a8 users 3
link 33:33:00:00:00:fb users 3
link 01:00:5e:00:00:fb users 2
inet 224.0.0.1
inet6 ff02::fb
inet6 ff02::1:ff1e:a0a8
inet6 ff02::1 users 2
inet6 ff01::1

# ip maddr show dev eth2
6: eth2
link 33:33:00:00:00:01 users 3
link 01:00:5e:00:00:01 users 3
link 01:80:c2:00:00:0e users 4 static
link 01:80:c2:00:00:03 users 4 static
link 01:80:c2:00:00:00 users 4 static
link 33:33:ff:1e:a0:a7 users 2
link 33:33:00:00:00:fb users 3
link 33:33:ff:1e:a0:a8 users 2
link 01:00:5e:00:00:fb users 2
inet 224.0.0.1
inet6 ff02::fb
inet6 ff02::1:ff1e:a0a7
inet6 ff02::1 users 2
inet6 ff01::1

.. rubric:: *Multicast Filtering for VLAN Interfaces*

Multicast filtering for VLAN interfaces is also supported.

Show current list of multicast address for the PRP VLAN interface

.. code-block:: console

ip maddr show dev <prp_vlan_intf>

Example:

.. code-block:: console

# ip maddr show dev prp0.5

Add multicast address for the PRP VLAN interface

.. code-block:: console

ip maddr add <multicast_mac_addr> dev <prp_vlan_intf>

Example:

.. code-block:: console

# ip maddr add 01:80:c4:00:00:0e dev prp0.5

Delete multicast address for the PRP VLAN interface

.. code-block:: console

ip maddr del <multicast_mac_addr> dev <prp_vlan_intf>

Example:

.. code-block:: console

# ip maddr del 01:80:c4:00:00:0e dev prp0.5

.. rubric:: Performance

This section describes the throughput and CPU usage metrics in the offload case

.. rubric:: Setup

A sample test setup is as shown below

.. Image:: /images/AM64_PRP_Setup.jpg
:width: 400

.. rubric:: Test Procedure

#. Connect the LAN cables between the DANP DUTs as shown in the setup image

#. Execute the commands to setup and create PRP interface

.. code-block:: console

sh prp_setup.sh prp_hw <INTF_A> <INTF_B> <PRP_INTF_IP_ADDR>

#. Confirm ping across all Nodes

#. Node A < - - > Node B
#. Node B < - - > Node C
#. Node C < - - > Node A

#. Disconnect one of the cable for a node and retry

#. Monitor the CPU usage on DUTs

.. code-block:: console

mpstat -P ALL 1

#. Run iperf3 server on Node C

.. code-block:: console

iperf3 -s

#. Run iperf3 client on Node A for 60 secs

.. code-block:: console

iperf3 -c -t60 <Node_C_IP_Addr>

.. rubric:: Throughput at Node A

.. list-table:: Throughput performance
:widths: 25 25

* - Sender
- Receiver
* - 610 Mbits/sec
- 605 Mbits/sec
Loading
Loading