3.1. PRU ICSS EthernetIP User Guide¶

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

3.1.2. System Requirements¶

3.1.2.1. Supported Devices¶

AM64x EVM

3.1.2.2. Component Version¶

Component	Version
Processor SDK for AM64X	1.0.0

3.1.3. Reference Documents¶

3.1.4. Directory Structure¶

|   |--- docs
|       |---EthernetIP_Adapter_Datasheet.pdf
|       |---PRU-ICSS-EthernetIP_Adapter_01.00.04_manifest.html
|   |--- examples
|       |--- board
|           | --- common
|           | --- evmAM64x
|           | --- include
|       |--- ethernetip_adapter
|           | --- stc
|       |--- osal
|   |--- protocols
|       |--- common
|           |--- include
|           |--- source
|       |--- ethernetip_adapter
|           |--- docs
|               |--- doxygen
|           |--- drivers
|           |--- eds
|           |--- firmware
|               |--- g_v1.0
|           |--- include
|           |--- projects
|       |--- timeSync
|           |--- drivers
|           |--- include
|   |--- third_party
|       |--- protocols
|           |--- ethernetip_adapter
|               |--- include
|               |--- stack_lib
|                   |--- am64x
|                       |--- r5f
|           |--- ptp
|               |--- lib
|                   |--- am64x
|                       |--- r5f

Note

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

3.1.5. Generating Project files¶

3.1.5.1. Steps to generate Project files¶

Setup the environment variables
- Edit the file [INSTALL-DIR]/protocols/ethernetip_adapter/projects/projectCreate_core_sdk.bat or .sh to align to the environment in your machine. All these paths should be accurate and mandatory; otherwise it will cause errors.
  - CCS_INSTALL_DIR - Set the path where the recommended version of CCS is installed in user machine. For example, if CCSv10.1.1 is installed in default path, set it to “C:\ti\ccs1011\ccs”.
  Note
  
  Use the path up to where the 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_core_sdk.bat)
  Note
  
  Use the path up to where the folder ‘ti’ is located.
  - 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/ethernetip_adapter/projects
Run projectCreate_core_sdk.bat or projectCreate_core_sdk.sh. The batch file takes three mandatory command line arguments (The mandatory arguments are case sensitive!)

Usage format: projectCreate_core_sdk.bat [SOC] [PROCESSOR] [PROJECT_NAME]

[SOC]
- The valid values for first command line argument [SOC] are
  - AM64x - To generate a project specific to AM64x
[PROCESSOR]
- The valid values for second command line argument [PROCESSOR] are
  - r5f - To generate a project specific to R5F 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
  - ethernetip_adapter_library_mode - to generate project for EtherNetIP adapter application in FWHAL library mode
  - ethernetip_adapter_fwhal_lib - to generate project for EtherNetIP adapter FWHAL library
  - timeSync_lib - to generate PTP library project
  Note
  
  For more details on FWHAL mode projects, please see FWHAL Library Mode Application section.

Note

Ensure that the workspace provided in CCS_WORKSPACE_LOC variable is not open in Code Composer Studio when executing projectCreate_core_sdk.bat or projectCreate_core_sdk.sh. If it is open, the eclipsec may throw errors

Usage example 1 : projectCreate_core_sdk.bat AM64x r5f ethernetip_adapter
- To generate the project files for EtherNetIP adapter application for AM64x platform
Usage example 2 : projectCreate_core_sdk.bat AM64x r5f ethernetip_adapter_library_mode
- To generate the project files for EtherNetIP adapter application in FWHAL library mode for AM64x platform
Usage example 3 : projectCreate_core_sdk.bat AM64x r5f timeSync_lib
- To generate the project files for PTP library project for AM64x platform

Note

If the project create is successful, the generated project files will be found in [INSTALL-DIR]/protocols/ethernetip_adapter/projects/[PROJECT_NAME]_[SOC]_[PROCESSOR]

Note

Default PRU-ICSSG instance used for EthernetIP Adapter is PRU-ICSSG1. For changing the PRU-ICSSG instance to be used, the PRUICSS_INSTANCE macro needs to be set accordingly in the [INSTALL-DIR]/examples/ethernetip_adapter/eip_soc.h file.

3.1.5.1.1. FWHAL Library Mode Application¶

ethernetip_adapter project includes files for application, driver and firmware in the project. In order to remove inclusion of driver and firmware from the project, there is a separate application mode which includes only application files and links a FWHAL library consisting of firmware and driver sources. This FWHAL library is present in [INSTALL-DIR]/protocols/ethernetip_adapter/lib/[SOC]/[PROCESSOR] folder. For creating applications with this mode, ethernetip_adapter_library_mode should be used for [PROJECT_NAME] while running projectCreate_core_sdk script. If you want to rebuild the FWHAL library, you can create the project using ethernetip_adapter_fwhal_lib for [PROJECT_NAME]. Building it will automatically update the library in [INSTALL-DIR]/protocols/ethernetip_adapter/lib/[SOC]/[PROCESSOR] folder.

3.1.5.2. More info¶

The projectCreate_core_sdk.bat or.sh utilizes the project arguments provides in [INSTALL-DIR]/protocols/ethernetip_adapter/projects/ccsproject_args to generate the project file

3.1.6. EtherNet/IP Adapter¶

Note

Permanent storage of Ethernet/IP device parameters are enabled and are stored in Board ID EEPROM memory at various offsets as defined in file eip_main.h

Note

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

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

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.

The example is an EtherNet/IP adapter demo application based on Molex 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

Start mode – Start stack in IO exchange mode
Stop mode – Stop IO exchange mode
Run mode – In this mode IO Data will be exchanged with scanner
Idle mode - No Data exchange with scanner. Only communication.
Copy in-out mode – Copy the data from scanner to the OUT data.
Increment mode – Stack will increment the OUT data periodically
Change IP Address - IP address of the device can be configured manually.
Erase Non Volatile Memory - This option will erase the stored device configurations from the non volatile memory

The stc file used for the ODVA CTT is provided along with the application in stc folder. The EDS file for the application is located at [INSTALL-DIR]/protocols/ethernetip_adapter/eds.

The Ethernet/IP Application uses TEST_LED2 as Module status LED and TEST_LED1 as network status LED. AM64x EVM does not have tri-color LEDs, these LEDs do not follow the specification. Following table lists various scenarios and corresponding LED patterns:

Scenario	TEST_LED2	TEST_LED1
Connection established	On	On
Connection timed out	On	Blink
IP Address assigned	On	Off
IP Address not assigned	Blink	Off
ACD conflict detected	Off	Blink

Ethernet/IP adapter has an integrated two-port cut-through learning switch. Switch is integrated to TCP/IP (NDK) stack.

For a quick checkout and demonstration of the EtherNet/IP functionality, an EIPTool, available for free from Molex, can be used to establish CIP connections and query or set CIP attributes.

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

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

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

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

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.

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

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