4.1. PRU ICSS EthernetIP User Guide

4.1.1. Introduction

PRU-ICSS Ethernet/IP package is designed for the Sitara processor family (with PRU-ICSS IP) to enable customers add Ethernet/IP Adapter support to their system. The implementation consists of

  • Firmware (provided as a binary)
  • Driver
    • PTP Driver
    • EtherNet/IP Driver (includes DLR)
  • Application

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.


4.1.2. Release 01.00.04

Released November 2023


4.1.3. System Requirements

1.0.4 release uses the PROCESSOR-SDK-RTOS 06_03_00_106 for AM335x and AM437x families and PROCESSOR-SDK-RTOS 08_01_00_19 for AM57xx family which are available at:

Alternatively one can follow “Previous SDK Link” from Processor SDK RTOS release page for AM335x and AM437x families( https://software-dl.ti.com/processor-sdk-rtos/esd/<Soc>/latest/index_FDS.html )

For AM57xx family of devices, one can select an older version to download under “Select a version” from the Processor SDK RTOS AM57X release page( https://www.ti.com/tool/download/PROCESSOR-SDK-RTOS-AM57X )

1.0.4 release uses the EtherNet/IP stack version 3.7.0.0

4.1.5. Directory Structure

|   |--- docs
|       |---Industrial_Protocol_Package_Getting_Started_Guide.pdf
|       |---Industrial_Protocol_Package_Software_Developer_Guide.pdf
|       |---PRU_ICSS_EthernetIP_User_Guide.pdf
|       |---PRU_ICSS_EthernetIP_Release_Notes.pdf
|   |--- examples
|       |--- board
|           | --- common
|           | --- iceAM335x
|           | --- iceAM437x
|           | --- idkAM571x
|           | --- idkAM572x
|           | --- include
|       |--- ethernetip_adapter
|           | --- soc
|       |--- osal
|   |--- protocols
|       |--- common
|               |--- include
|               |--- source
|       |--- ethernetip_adapter
|               |--- docs
|                       |--- doxygen
|               |--- drivers
|               |--- eds
|               |--- firmware
|                       |--- v1.0
|                       |--- v2.1
|               |--- include
|               |--- projects
|       |--- timeSync
|               |--- drivers
|               |--- include
|       |--- pdk_patches
|               |--- 06.03.00
|               |--- 08.01.00
|   |--- third_party
|       |--- protocols
|               |--- ethernetip_adapter
|                           |--- include
|                           |--- stack_lib
|                                |--- am57xx
|                                     |--- a15
|                                |--- am437x
|                                     |--- a9
|                                |--- am335x
|                                     |--- a8
|               |--- ptp
|                           |--- lib
|                                |--- am57xx
|                                     |--- a15
|                                |--- am437x
|                                     |--- a9
|                                |--- am335x
|                                     |--- a8

Note

Refer to install path to get updated view for any changes in directory structure


4.1.6. Generating Project files

4.1.6.1. Steps to generate Project files

  • Setup the environment variables
    • Edit the file [INSTALL-DIR]/protocols/<protocol name>/projects/projectCreate.bat or .sh to 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.
  • 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
  • [PROCESSOR]
    • The valid values for second command line argument [PROCESSOR] are
      • arm - To generate a project specific to ARM core
  • [PROJECT_NAME]
    • The valid values for second command line argument [PROJECT_NAME] to be used with EtherNetIP installer package
      • ethernetip_adapter - to generate EtherNetIP adapter application project
      • timeSync_lib - to generate PTP library project

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 ethernetip_adapter
    • To generate the project files for EtherNetIP adapter 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 ethernetip_adapter
  • To generate the project files for EtherNetIP adapter application 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


4.1.6.2. Patching and Rebuilding

Follow the below steps to apply the patch and to rebuild the pdk components:

Note

This is not a TI tool - See licensing information page for more details.

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 for AM335x and AM437x and [INSTALL-DIR]/protocols/pdk_patches/08.01.00 for AM57xx)
[Dos2Unix/Unix2Dos-DIR]/bin/unix2dos.exe [INSTALL-DIR]/protocols/pdk_patches/06.03.00/icss_emac_phy_status_fix.patch
  • CD to patch utility bin folder.
  • Execute patch.exe as given below
patch.exe -i  [INSTALL-DIR]/protocols/pdk_patches/06.03.00/icss_emac_phy_status_fix.patch -d [PDK_INSTALL_DIR]/pakages/ti/drv/icss_emac -N -p0 --verbose

Note

INSTALL-DIR is the PRU-ICSS-EthernetIP_Adapter installation directory. Example : C:\ti\PRU-ICSS-EthernetIP_Adapter_01.00.04.10

Note

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
  • Similarly execute unix2dos.exe and patch.exe for ethernetip_timeSync_fixes_from_SDK.patch as given below:
[Dos2Unix/Unix2Dos-DIR]/bin/unix2dos.exe [INSTALL-DIR]/protocols/pdk_patches/06.03.00/ethernetip_timeSync_fixes_from_SDK.patch
patch.exe -i  [INSTALL-DIR]/protocols/pdk_patches/06.03.00/ethernetip_timeSync_fixes_from_SDK.patch  -d [PDK_INSTALL_DIR]/pakages/ti/transport/timeSync -N -p1 --verbose
  • In case of AM57xx, execute unix2dos.exe and patch.exe for i2c_version_update.patch as given below:
[Dos2Unix/Unix2Dos-DIR]/bin/unix2dos.exe [INSTALL-DIR]/protocols/pdk_patches/08.01.00/i2c_version_update.patch
patch.exe -i  [INSTALL-DIR]/protocols/pdk_patches/08.01.00/i2c_version_update.patch  -d [PDK_INSTALL_DIR]/pakages/ti/drv/i2c -N --verbose

  • Rebuild the ‘icss_emac’, ‘nimu_icss’, ‘timeSync’ and ‘i2c’ (in case of AM57xx) 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
      cd ti/drv/icss_emac
gmake -sj clean
gmake -sj all
      • nimu_icss : ti/transport/ndk/nimu_icss
      cd ti/transport/ndk/nimu_icss
gmake -sj clean
gmake -sj all
      • i2c : ti/drv/i2c
      cd ti/drv/i2c
gmake -sj clean
gmake -sj all
      • timeSync : ti/transport/timeSync
      cd ti/transport/timeSync
gmake -sj clean
gmake -sj all

Note

For detailed note see rebuilding pdk page.

4.1.6.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


4.1.7. EtherNet/IP Adapter

  • NOTE 1:
    Permanent storage of Ethernet/IP device parameters are enabled and are stored in SPI Flash at various offsets as defined in file eip_main.h
  • NOTE 2:
    To add ACD(Address Conflict Detection) support in the application, a legacy method is used for configuring NDK parameters. In this approach configuring of NDK is done using the Configuration APIs rather than the XGCONF configuration tool within CCS. This is because a configuration added through XGCONF tool will be overridden. Please refer the link for more information on this approach.
  • NOTE 3:
    For passing the Subnet Mask tests (Test 4.1) specified in ODVA Conformance test report, rebuilding of the NDK is required. Macro _INCLUDE_ACD_SUPPORT must be defined in the file NDK_INSTALL_DIR\packages\ti\ndk\stack\lli\lliin.c. Then the NDK is rebuilt
  • NOTE 4:
    The Ethernet/IP application can be modified to work as a Switch application by removing the Ethernet/IP dependencies. The steps to create Switch application can be found here
  • NOTE 5:
    The NDK performance of the ICSS Emac Driver can be improved by increasing Queue size (Prioriy Queue 4 in case of Ethernet/IP). To enable this improvement change the macro QUEUE_4_SIZE in icss_switch.h from 97(3KB) to 194(6KB). However it is important that the total Queue size is not more than 12KB.
  • NOTE 6
    To use PRU-ICSS1 on the AM571x IDK, the #define PRUICSS_INSTANCE need to set to 1 in [INSTALL-DIR]/examples/ethernetip_adapter/main.c
  • NOTE 7
    The AM335x and AMIC11x application uses DMTimer4 as the clock source for the SYSBIOS Ticks (Refer to cfg file for details). The DMTimer module should be enabled for the application to load properly with the change. This needs to be done in the GEL file. Make the following changes in GEL File to enable DMTimer4
    • Add the line inside hotmenu AM3359_ICE_Initialization()
      • WR_MEM_32(CM_PER_TIMER4_CLKCTRL, PRCM_MODULEMODE_ENABLE);
    • Add the defines in the GEL File
      • #define CM_PER_TIMER4_CLKCTRL (PRCM_BASE_ADDR + 0x88)
      • #define PRCM_MODULEMODE_ENABLE (2U)

The example is an EtherNet/IP adapter demo application based on TMG EtherNet/IP stack on top of NDK TCP/IP stack  . The EtherNet/IP is an industrial networking standard that takes advantage of commercial off-the-shelf Ethernet communication chips and physical media. The EtherNet/IP uses an open protocol (CIP) at the application layer. This example is a limited demo application that is constrained so that a user will be allowed to execute it for one hour only. The EtherNet/IP adapter application is implemented over the low latency cut-thru switch implementation on ICSS


The ACD(Address Conflict Detection) feature is enabled in the example. Upon startup, the application checks for the ACD enable bit stored in the SPI Flash (at offset SPI_EEPROM_ACD_OFFSET). If disabled, the application starts immediately, otherwise it waits for the link to come up. Once the link is established, the ACD mechanism is started. The IP Address is obtained once the ARP probing is done and no duplicate IP Address is detected.


This application allows the user to carry out the following actions and can be configured via the serial console

  1. Start mode – Start stack in IO exchange mode
  2. Stop mode – Stop IO exchange mode
  3. Run mode – In this mode IO Data will be exchanged with scanner
  4. Idle mode - No Data exchange with scanner. Only communication.
  5. Copy in-out mode – Copy the data from scanner to the OUT data.
  6. Increment mode – Stack will increment the OUT data periodically
  7. Change IP Address - IP address of the device can be configured manually.
  8. Erase Non Volatile Memory - This option will erase the stored device configurations from the non volatile memory
  9. Configure ACD status - This option can be used to set or clear the ACD bit in the flash.
  10. Read Media Counters - This option can be used to read the firmware media counters.
  11. Clean Media Counters - This option can be used to clear the firmware media counters.
  12. Multicast filter handling - This option can be used to enable or disable Multicast filter and Storm Prevention, add or remove the multicast MAC address and configure the hash mask.
  13. PTP status - This option can be used to see the synchronization status of the DUT.

The soc file used for the ODVA CTT is provided along with the application in soc folder. It is located at [INSTALL-DIR]/examples/ethernetip_adapter/soc. The EDS file for the application is located at [INSTALL-DIR]/protocols/ethernetip_adapter/eds.The Ethernet/IP Application uses Industrial LED0 as Module status LED and Industrial LED1 as network status LED.

Ethernet/IP adapter has an integrated two-port cut-through learning switch. Switch is integrated to TCP/IP (NDK) stack.Please see ICSS-EMAC LLD for more details on switch driver.

The Ethernet/IP Driver API guide is available here - [INSTALL-DIR]/protocols/ethernetip_adapter/docs/API_documetation.html

4.1.7.1. Half Duplex Support

Half Duplex support is not mandated in the latest version of the spec. Kindly refer to the spec for more info.

4.1.7.2. Device Level Ring

The Ethernet/IP on Industrial Communication SubSystem (ICSS) supports Beacon based DLR (Device Level Ring) node which is a ring redundancy protocol specified by ODVA, the main features of this implementation are

  • Supports 200 us beacon interval and 400 us beacon timeout interval
  • Supports learning table exception for Supervisor
  • Dynamic start and stop. User can enable or disable DLR on the fly
  • No user configuration required. The ring parameters get configured on their own.

To test DLR capability a DLR capable device is required. EtherNet/IP application is tested using a Rockwell PLC, part number 1769 L18ERM and a 3 port ETAP part number 1783-TD001


4.1.7.3. PTP/1588

Ethernet/IP adapter supports Annex D of PTP/1588 in End to End configuration. The application supports both Transparent and Ordinary Clock functionalities. Ethernet/IP adapter does not support PTP Master mode. The example makes use of PTPD stack to enable BMCA and Management messages support. The stack comes with a BSD style licensing.

PTP/1588 implementation can be tested using open source PTP implementations like Linux PTP or PTPd, they must be configured in Annex D or PTP over UDP mode and as End 2 End Clock.

In the application it’s possible to see the synchronization status of DUT. To do so press “p” in the EIP UART Menu. If a PTP master is connected and everything is ok, the following menu pops up in debug mode

../../../_images/PTP_EIP_sample_UI1.png

Here the master is connected on Port 2 and current offset with master is in the order of 129 nanoseconds. In release mode of the application the min and max offsets are not visible, rest is unchanged.

4.1.7.3.1. Limitations

BMCA is currently disabled in the PTP stack. So if the device is configured as a slave then it will sync to the first master it connects to, if another master comes online then it will become the new master. This will keep happening in a ping pong fashion so it’s best to enable only one Master for testing.

  • BMCA support is not supported in this release.
  • Multi domain support is not supported in this release.
  • PTP support is not enabled for K2G platform

For more details on the implementation and usage refer to the PTP/1588 developer guide here.


4.1.7.4. Archives



../../../_images/E2e5.jpg

For technical support please post your questions at http://e2e.ti.com