5.1. PRU ICSS HSR PRP User Guide¶
5.1.1. Introduction¶
PRU-ICSS HSR/PRP package is designed for the Sitara processor family (with PRU-ICSS IP) to enable customers add HSR PRP Dual Attached Node support to their system. The implementation consists of
- Firmware (provided as a binary)
- Driver
- TimeSync Driver
- HSR/PRP Driver
- Application
- SNMP support
There are plenty of resources to get started with the development. This page is meant to be a landing page for getting all the resources at one place. Please refer to the Reference Link section for links to all the resources.
The PTP module has been renamed to TimeSync but behavior remains the same, henceforth both the terms shall be used interchangeably.
5.1.3. Reference Documents¶
5.1.4. Directory Structure¶
| | ---docs
| | ---examples
| | | ---board
| | | | - --common
| | | | ---iceAM335x
| | | | ---idkAM437x
| | | | ---idkAM571x
| | | | ---idkAM572x
| | | | ---idkAM65xx
| | | | ---include
| | | ---hsr_prp
| | | | ---AM335x
| | | | ---AM437x
| | | | ---AM57xx
| | | | ---AM65xx
| | | | ---snmp
| | | ---osal
| | ---protocols
| | | ---common
| | | | ---include
| | | | ---source
| | | ---hsr_prp
| | | | ---docs
| | | | | ---doxygen
| | | | | ---html
| | | | ---drivers
| | | | ---firmware
| | | | | ---hsr
| | | | | | ---g_v1.0
| | | | | | | ---rgmii
| | | | | | ---v1.0
| | | | | | ---v2.1
| | | | | ---prp
| | | | | ---g_v1.0
| | | | | | ---rgmii
| | | | | ---v1.0
| | | | | ---v2.1
| | | | ---include
| | | | | ---v1.0
| | | | | ---v2.1
| | | | ---lib
| | | | | ---hsr
| | | | | | ---am335x
| | | | | | | ---a8
| | | | | | ---am437x
| | | | | | | ---a9
| | | | | | ---am57xx
| | | | | | | ---a15
| | | | | | ---am65xx
| | | | | | | ---a53
| | | | | ---prp
| | | | | ---am335x
| | | | | | ---a8
| | | | | ---am437x
| | | | | | ---a9
| | | | | ---am57xx
| | | | | | ---a15
| | | | | ---am65xx
| | | | | | ---a53
| | | | ---projects
| | | | ---ccsproject_args
| | | | ---AM335x
| | | | ---AM437x
| | | | ---AM571x
| | | | ---AM572x
| | | | ---AM57xx
| | | | ---AM65xx
| | | | ---AMIC11x
| | | ---pdk_patches
| | | | ---06.03.00
| | | ---snmp
| | | | ---drivers
| | | | ---include
| | | | ---projects
| | | | ---ccsproject_args
| | | | ---AM335x
| | | | ---AM437x
| | | | ---AM57xx
| | | | ---AM65xx
| | | ---timeSync
| | | ---drivers
| | | ---include
| | | ---projects
| | | ---ccsproject_args
| | | ---AM335x
| | | ---AM437x
| | | ---AM57xx
| | | ---AM65xx
| | ---third_party
| | ---protocols
| | ---ptp
| | | ---lib
| | | | ---am335x
| | | | | ---a8
| | | | ---am437x
| | | | | ---a9
| | | | ---am57xx
| | | | | ---a15
| | | | ---am65xx
| | | | | ---a53
| | | ---ptpd
| | | ---def
| | | | ---derivedData
| | | | ---managementTLV
| | | | ---message
| | | | ---signalingTLV
| | | ---dep
| | ---snmp
| | ---snmp_core
| | | ---source
| | ---source
| | | ---api
| | | ---config
| | | ---include
| | | ---oal
| | | | ---os
| | | ---psp
| | | | ---include
| | | | ---target
| | | | ---aligncheck
| | | | ---ip_config
| | | | ---rand
| | | | ---rtc
| | | | ---sockets
| | | | ---tick
| | | ---version
| | ---stack_lib
| | ---am335x
| | | ---a8
| | ---am437x
| | | ---a9
| | ---am57xx
| | | ---a15
| | ---am65xx
| | | ---a53
|
Note
Refer to install path to get updated view for any changes in directory structure
5.1.5. Generating Project files¶
5.1.5.1. Steps to generate Project files¶
- Setup the environment variables
- Edit the file
[INSTALL-DIR]/protocols/<protocol name>/projects/projectCreate.bat or .shto align to the environment in your machine. All these paths should be accurate and mandatory, and will cause errors otherwise.- CCS_INSTALL_DIR - Set the path where the recommended version of CCS is installed in user machine(The path upto where folder ‘eclipse’ is located.)
- CCS_WORKSPACE_LOC - Set the CCS workspace location. This folder will be created if it doesn’t exist already.
- Edit the file
- IA_SDK_HOME - Specify the IA_SDK_HOME based on the the directory where the industrial package is installed. If the package is installed in a custom directory, make sure this path is modified properly.
- PDK_INSTALL_PATH - Set the path where PDK RTOS package is installed (Refer to default path in projectCreate.bat)
- PROJECT_CREATE_DIR - Set the folder where the created project will be kept. User can import the projects from this directory to CCS
- PROJECT_CREATE_OPTIONS_FILE_DIR - Specify the directory where the project create options files are kept. This folder contains the *.txt files which specify the project settings (linked files, predefined symbols, compiler and linker options for a specific project)
- Open Command/Shell Prompt and navigate to
[INSTALL-DIR]/protocols/<protocol name>/projects - Run projectCreate.bat or projectCreate.sh. The batch file intakes three mandatory command line arguments (The mandatory arguments are case sensitive!)
Usage format: projectCreate.bat [SOC] [PROCESSOR] [PROJECT_NAME]
- [SOC]
- The valid values for first command line argument [SOC] are
- AM571x - To generate an application project specific to AM571x
- AM572x - To generate an application project specific to AM572x
- AM437x - To generate an application project specific to AM437x
- AM335x - To generate an application project specific to AM335x
- AMIC110 - To generate an application project specific to AMIC110
- AM57xx - To generate a library project common to both AM572x and AM571x
- AM65xx - To generate an application project specific to AM65xx
- The valid values for first command line argument [SOC] are
- [PROCESSOR]
- The valid values for second command line argument [PROCESSOR] are
- arm - To generate a project specific to ARM core
- The valid values for second command line argument [PROCESSOR] are
- [PROJECT_NAME]
- The valid values for second command line argument [PROJECT_NAME]
to be used with HSR PRP DAN installer package
- hsr_app - to generate HSR application project
- hsr_lib - to generate HSR library project
- prp_app - to generate PRP application project
- prp_lib - to generate PRP library project
- timeSync_lib - to generate PTP library project
- snmp_core_stack - to generate SNMP stack library project
- The valid values for second command line argument [PROJECT_NAME]
to be used with HSR PRP DAN installer package
Note
Ensure that Code Composer Studio is not running when executing projectCreate.bat or projectCreate.sh. If not, the eclipsec may throw errors
- Usage example 1 : projectCreate.bat AM572x arm hsr_app
- To generate the project files for HSR application for AM572x platform by overwriting the project if it is already existing in PROJECT_CREATE_DIR\PROJECT_NAME_SOC_PROCESSOR
- Usage example 2 : projectCreate.bat AM57xx arm timeSync_lib
- To generate the project files for PTP library project common for both AM572x and AM571x platforms by overwriting the project if it is already existing in PROJECT_CREATE_DIR\PROJECT_NAME_SOC_PROCESSOR
- Usage example 3 : projectCreate.bat AM437x arm snmp_core_stack
- To generate the project files for SNMP stack for AM437x ARM core by overwriting the project if it is already existing in PROJECT_CREATE_DIR\PROJECT_NAME_SOC_PROCESSOR
Note
If the project create is successful, the generated project files will be found in [INSTALL-DIR]/protocols/<protocol name>/projects/PROJECT_NAME_SOC_PROCESSOR`. To build the project, ensure the PDK patches if any in [INSTALL-DIR]/protocols/pdk_patches/06.03.00 are applied and the corresponding pdk components are rebuilt. This is an required step as there is dependency on baseline Processor SDK.
5.1.5.2. Patching and Rebuilding¶
- Follow the below steps to apply the patch and to rebuild the pdk components:
- Download Windows Patch Utility from gnuwin32 sourceforge.
Note
This is not a TI tool - See licensing information page for more details.
- Download Dos2Unix/Unix2Dos-Text file format converters from gnuwin32 sourceforge.
Note
This is not a TI tool - See licensing information page for more details.
- Launch DOS Command prompt ( Start->Run->cmd ).
- Execute unix2dos.exe as given below (Patch file is located in [INSTALL-DIR]/protocols/pdk_patches/06.03.00)
[Dos2Unix/Unix2Dos-DIR]/bin/unix2dos.exe [INSTALL-DIR]/protocols/pdk_patches/06.03.00/PRSDK-3086-HSRPRP_2_interrupts_PDK.patch
- CD to patch utility bin folder.
- Execute patch.exe as given below
patch.exe -i [INSTALL-DIR]/protocols/pdk_patches/06.03.00/PRSDK-3086-HSRPRP_2_interrupts_PDK.patch -d [PDK_INSTALL_DIR]pakages/ti/drv/icss_emac -N -p0 --verbose
Note
INSTALL-DIR is the PRU-ICSS-HSR-PRP-DAN installation directory. Example :
C:\ti\PRU-ICSS-HSR-PRP-DAN_01.00.05.01Note
PDK_INSTALL_DIR is the pdk installation directory. Example :
C:\ti\pdk_am335x_1_0_17- Similarly execute unix2dos.exe and patch.exe for timeSync_reconfigure_intr.patch as given below:
[Dos2Unix/Unix2Dos-DIR]/bin/unix2dos.exe [INSTALL-DIR]/protocols/pdk_patches/06.03.00/timeSync_reconfigure_intr.patch patch.exe -i [INSTALL-DIR]/protocols/pdk_patches/06.03.00/timeSync_reconfigure_intr.patch -d [PDK_INSTALL_DIR]pakages/ti/transport/timeSync/include -N -p0 --verbose
Rebuild the ‘icss_emac’, ‘nimu_icss’ and ‘timeSync’ components for the pdk
- Execute pdksetupenv.bat file as given below
cd [PDK_INSTALL_DIR]/pakages pdksetupenv.bat
CD to component folder and give build command for each respective components as given below
- icss_emac :
ti/drv/icss_emac - nimu_icss :
ti/transport/ndk/nimu_icss - timeSync :
ti/transport/timeSync
- icss_emac :
cd ti/drv/icss_emac gmake -sj clean gmake -sj all
Note
For detailed note see rebuilding pdk page.
5.1.5.3. More info¶
The projectCreate.bat or.sh utilizes the project arguments provides in [INSTALL-DIR]/protocols/<protocol name>/projects/ccsproject_args to generate the project file.
5.1.6. HSR/PRP DAN¶
The example is an HSR/PRP Dual Attached Node demo application using TI’s NDK TCP/IP stack. HSR and PRP are actually two separate examples which are available in the same package. They use the same files and based on the defined MACRO the application is taken. The macros are pre-defined in the project script and are automatically applied when the project is generated.
HSR and PRP are zero downtime industrial redundancy protocols that operate at Layer 2 and use commercial off-the-shelf Ethernet communication chips and physical media. HSR has a header attached to it that makes it incompatible with standard switches and routers but PRP can be supported using traditional switches. HSR and PRP are mainly used in the substation automation market and the target applications use IEC 61850 protocols. This application does not provide any IEC 61850 integrated examples but it’s easy to integrate one given the transparent nature of HSR/PRP implementation. For more details on integration of IEC 61850 stacks consult the TI designs mentioned in the reference links.
The application has a built in UART console menu. It allows the user to perform the following tasks
- View HSR/PRP statistics - Allows user to see number of packets forwarded to host, number of duplicates, number of packets transmitted by the host to the LRE (Link Redundancy Entity).
- View HSR/PRP LRE statistics - Allows user to see the stats reported by LRE (Link Redundancy Entity).
- View HSR/PRP Configuration - Allows user to see the configuration
- View HSR PRP Node Table - User can see the node table contents which keeps a track of all devices on the network which send HSR/PRP Supervision frames. Device MAC ID, table entry index can be viewed.
- Configure Multicast filter - User can configure the multicast filtering support using a UART driven submenu.
- Configure VLAN filter - User can configure the VLAN filtering support using a UART driven submenu.
- Configure Host Rx Interrupt pacing - User can configure the Host Rx Interrupt pacing support using a UART driven submenu.
- Assign an IP address - The IP address is stored at a fixed location in SPI flash at the offset defined by SPI_EEPROM_DEVICEIP_OFFSET. This IP address is taken at startup and user can also change the IP address.
- View PTP status - Shows basic PTP/1588 parameters like peer delay, clock jitter, absolute time and port on which master is connected. All values are in nanoseconds wherever applicable.
- Run Rx/Tx test : The application allows a simple visual check of redundancy. In an HSR ring or PRP star network with multiple devices one device is configured as receiver while the other devices are configured as transmitter. The transmitter sends a UDP frame with encoded payload. The receiver interprets this encoding and toggles the Digital IO LED’s on the board. The transmitter and receiver continue running this test till a timeout occurs. Users can break links and verify that the LED’s still toggle demonstrating redundancy.
- Configure storm prevention - User can configure(enable/disable) the storm prevention and set the credits indivdually for UC, BC and MC traffic.
Note
The queue priorities are modified temporarily for the Rx/Tx test as the frames need special handling to toggle the LEDs on the boards. This can affect the normal communication over the network.
5.1.6.1. PTP/1588¶
Both HSR and PRP support ordinary and transparent clock configurations in both slave and master mode. The implementation is compliant to PTP-1588 requirements specified in IEC 62439-3 Ed 2.0 except for the missing Best Master Clock Algorithm (see Limitations)
Since Best Master Clock Algorithm is not enabled in this release the slave/master configuration must be configured manually, this can be done through the application UART console. By default the application boots into slave mode.
5.1.6.1.1. UART Menu¶
See below for how the HSR/PRP menu looks like.
The option for selecting PTP submenu is ‘P/p’
Once that is selected the PTP submenu shows up. See above
The option ‘C/c’ is used to toggle the Master/Slave mode. If DUT is master then it will go to slave and vice-versa. See below for how it looks like when the mode changes to master
In slave mode the UART console looks like this when ‘S/s’ (status) is pressed
Here the fields of interest are
- Peer Delay on P1/P2 : Peer delay with adjacent node
- Clock Drift : Difference between successive offsets from Master
- Curr offset : Current offset from Master
- Min offset : Min value of offset with DUT synchronized
- Max offset : Max value of offset with DUT synchronized
- Num Sync Missed : Number of sync frames anticipated but not received
- UTC Offset : Value of seconds field in Sync/Announce message
- Master Connected on Port : If Master is connected to Port 1 value is 1. For Port 2 it’s 2
When DUT synchronizes the Min and Max offsets take a value other than the default values and Curr offset and Clock Drift values take sub 100 ns values. There is another visual indicator for synchronization but this is by far the most accurate. LED behavior is discussed below.
PTP/1588 support in HSR and PRP is enabled by default and can be tested using any HSR or PRP device which support PTP/1588 Master.
5.1.6.1.2. LED Indicators¶
The HSR-PRP application uses two LED indicators in addition to the UART console for easy debugging. There are a minimum of two LED indicators on all Industrial EVM’s AMICx/AM3/AM4/AM5/AM6.
- LED 0 : This is the PTP indicator.
- Boot Up : As slave with no master connected the behavior is a steady blinking green.
- Master connected/synchronizing : As slave while synchronizing the steady blink changes to fast blink.
- DUT synchronized : The LED stops blinking and is steady green
- sync loss : When sync is lost even once the LED turns Red in color. The blinking behavior stays the same, i.e. steady Red (device in sync), fast blinking Red (synchronizing), slow blinking (no master)
- DUT as master : The LED blinks steady yellow/blue (depending on board) and stays like that.
- LED 1 : This is the DUT indicator. It blinks steady green throughout to indicate that application is running
Pressing ‘r/R’ inside PTP sub-menu will reset the LED 0 indicator as well as the min and max offsets
For more details on the implementation and usage refer to the HSR PRP developer guide here and PTP/1588 developer guide here.
