AM64x INDUSTRIAL COMMUNICATIONS SDK  11.00.00
EtherCAT SubDevice FWHAL

Table of Contents

Introduction

This software is designed for the TI SoCs with PRU-ICSS IP to enable customers add EtherCAT SubDevice protocol support to their system. It implements EtherCAT SubDevice Controller(ESC) Layer 2 functionality with two MII ports (one IN and one OUT port per PRU-ICSS) in accordance with ETG.1000.4 Data Link Layer protocol specification. This provides EtherCAT ASIC like functionality integrated into TI SoCs.

Software Architecture

EtherCAT firmware for PRU-ICSS is a black box product maintained by TI. EtherCAT SubDevice FWHAL(Firmware and Hardware Abstraction Layer) allows loading and running the EtherCAT firmware and acts as an interface with ESC firmware. FWHAL implements the key interface between EtherCAT SubDevice Controller Emulation firmware and EtherCAT stack.

SysConfig Features

Note
It is strongly recommend to use SysConfig where it is available instead of using direct SW API calls. This will help simplify the SW application and also catch common mistakes early in the development cycle.

SysConfig can be used to configure things mentioned below:

  • Selecting the PRU-ICSS instance
  • Configuring PINMUX needed for MII mode
  • Configuring ETHPHY for the two PHY ports of PRU-ICSS
  • Configuring Enhanced Link Detection
  • Configuring MDIO Manual Mode (for enabling work-around for issue "i2329 - MDIO: MDIO interface corruption (CPSW and PRU-ICSS)" described in AM64x/AM243x Processor Silicon Revision 1.0, 2.0 (Rev. E))

PRU-ICSS EtherCAT SubDevice Firmware

Features Supported

  • All EtherCAT Commands (NOP, APRD, APWR, APRW, FPRD, FPWR, FPRW, BRD, BWR, BRW, LRD, LWR, LRW, ARMW and FRMW)
  • 8 FMMU support
  • 8 SM support
  • 59KB of Process Data RAM
  • Distributed clocks
    • 64-bit DC
    • SYNC0 out generation single shot and cyclic mode support
    • SYNC1 out generation
      • SYNC1 cycle time multiple of SYNC0 cycle time
      • SYNC1 shift with respect to SYNC0
    • Latch0 and Latch1 inputs
    • System Time PDI control
  • DL Loop Control
    • Using MII_RX_LINK (fast - depending on PHY link loss detection latency) - mandatory for cable redundancy support
    • Using PRU-ICSS MDIO state machine - not recommended for cable redundancy support
  • Interrupts - AL/ECAT events
    • SYNC0, SYNC1 and PDI interrupt events on external SOC pins
  • Watchdog - PDI and SM
  • Error Counters
    • RX Invalid Frame Counter Port 0/1
    • RX ERR Counter Port 0/1
    • Forwarded Error Counter Port 0/1
    • ECAT Processing Unit Error Counter
  • LED - Run, Error and Port0/1 activity
  • EEPROM Emulation for ESI EEPROM support
  • Management Interface for PHY over EtherCAT
  • PHY address configuration and host side API for PHY programming
  • Cable redundancy support
  • Firmware based on 200 MHz or 333 MHz clock frequency for PRU-ICSS Core Clock and IEP Clock

Key Performance Parameters

Sync Jitter measurement done using TwinCAT 3.1 along with C6015-0020 (Beckhoff PLC) with cycle time at 50μs. Note that PRU Core Clock is running at 200MHz, unless mentioned otherwise.

Feature Detail Value
Distributed Clock Sync Jitter 15ns (Capture Duration = 65 hours)
Latency Process Path (PRU Clock Frequency @ 200MHz) Average = 400ns, Max = 410ns
Auto Forward Path (Reverse Path) (PRU Clock Frequency @ 200MHz) Average = 340ns, Max = 360ns
Process Path (PRU Clock Frequency @ 333MHz) Average = 280ns, Max = 300ns
Auto Forward Path (Reverse Path) (PRU Clock Frequency @ 333MHz) Average = 220ns, Max = 240ns

Release Notes

Industrial Communications SDK Version 11.00

  • Firmware Version : x.5.54
  • Fix for PINDSW-8428 : Configure SYNC1 Shift with respect to SYNC0 signal
  • Fix for PINDSW-8429 : Optimizing Host Handshake During Redundant State Change, that is, if the Main Device sets the Subdevice to its current state (no actual state change), the host handshake is skipped to optimize communication.

Industrial Communications SDK Version 09.02 (Not available in 09.02.00.15)

  • Firmware Version : x.5.50
  • Fix for PINDSW-47 : Single datagram accessing multiple FMMU mapped areas using LRD/LWR commands from a single SubDevice.
    • Do note that if this feature is enabled, then the Process Path latency will be dynamically increased to take care of the timing constraints. Please refer to Register 0xED0 of Vendor Specific Register in TI EtherCAT SubDevice Controller Register List
  • Fix for PINDSW-141 : LRW access to non-interleaved input and output process data of multiple SubDevices does not work.
    • This will make EtherCAT SubDevice compatibile with default mode of few open source EtherCAT MainDevice like SOEM and IgH.
    • Do note that if this feature is enabled, then the Process Path latency will be dynamically increased to take care of the timing constraints. Please refer to Register 0xED0 of Vendor Specific Register in TI EtherCAT SubDevice Controller Register List
  • Bug-fix for PINDSW-8246 : Triple buffer issue - Not getting the latest data from buffer during free-run mode.
  • Bug-fix for PINDSW-8115 : Watchdog error while using LRD and LWR with same logical address.

MCU+ SDK Version 08.05.00

  • Firmware Version : x.5.12
  • Bug-fix for PINDSW-5384 : ESC DL Status register is not initialized correctly
  • Bug-fix for PINDSW-5385 : Next SYNC1 Pulse register is not updated correctly
  • Bug-fix for PINDSW-5401 : SYNC1 Pulse is generated one SYNC0 cycle time late

MCU+ SDK Version 08.04.00

  • Firmware Version : x.5.8
  • Added the support for enabling MDIO Manual Mode. New vendor specific registers are added for this purpose. (See TI EtherCAT SubDevice Controller Register List for more details)
  • Bug-fix for PINDSW-5369 : Write to System Time Delay (0x0928) register works only once

MCU+ SDK Version 08.03.00

  • Firmware Version : x.5.6
  • Added selection of 200 MHz or 333 MHz clock frequency for PRU-ICSS Core Clock and IEP Clock used by EtherCAT SubDevice Firmware using PRU Clock Frequency Selection Register (0x0E34)
  • Added PDI ISR Time Register (0x0E2C)
  • Changed default value of Bit 3 and Bit 7 in Sync/Latch PDI Configuration Register (0x0151) to 0
  • Bug-fixes in implementation of RX Error Counter

MCU+ SDK Version 08.02.00

  • Firmware Version : x.5.1
  • EtherCAT SubDevice Firmware based on 333 MHz (instead of 200 MHz) clock frequency for PRU-ICSS Core Clock and IEP Clock for better process path latency
  • Add PHY RX Error Counter Register (0x0E28) for improving RX Error Counter accuracy (See Register Exceptions for more details)
  • Bug-fixes for PINDSW-3120, PINDSW-5194, PINDSW-5229 and PINDSW-5267

Features Not Supported

  • EtherCAT SubDevice Controller
    • ECAT side register protection when using LRD command
    • APRW/FPRW/BRW for SM mapped area
  • EtherCAT G
  • Reset Isolation

Known Issues

Record ID Details Workaround
PINDSW-72 PDI/PD watchdog counter incremented by 1 whenever PDI/PD watchdog is disabled None
PINDSW-74 LRD access on unused registers increment WKC - no register protection while using LRD None
PINDSW-2204 Frames with no SFD not counted as errors if received on reverse path None
PINDSW-2360 System time of next Sync0 pulse register (0x990:0x993) is not instantaneous, resulting in read of incorrect value if read immediately after sync pulse None
PINDSW-5135 Read permissions and byte level write permissions for RW type commands are not checked None
PINDSW-5145 RX_ER counter does not count errors outside frame in MII RX_CLK units precisely Added PHY RX Error Counter Register (0x0E28) for improving RX Error Counter accuracy. Configuring this register will track RX_ERs within a frame precisely using PHY registers. Refer Register Exceptions for more details.
PINDSW-5414 Link Lost Counter is incorrectly incremented once for ports with polarity of RXLINK input as “Active Low” during initialization Use Active High Polarity for LED_LINK/SPEED connected to MII0/MII1 Receive Link (RXLINK) pin of PRU-ICSS

For more details, please see the EtherCAT SubDevice Errata document.

How MDIO Works for Link Detection

In EtherCAT networks, fast detection of link status changes is crucial to maintain real-time communication and network integrity. MDIO enables the processor to read status registers from connected PHYs, allowing the system to:

  • Detect link up/down events.
  • Monitor PHY status.
  • Configure PHY settings as needed. This information is vital for the EtherCAT Slave Controller (ESC) to manage port states and ensure timely data transmission. The MDIO interface communicates with external PHYs using the standard IEEE 802.3 Clause 22 protocol. Each PHY on the board is connected to the MDIO bus and is accessible via a unique PHY address The MDIO module allows communication with a wide range of PHYs with some of the following features:
  • PHY Addressing: Each PHY is assigned a unique address (0–31) on the MDIO bus.
  • Clock Configuration: The MDIO clock (MDC) must be configured to operate within the PHY’s specified frequency range.
  • Register Access: The MDIO Module reads and writes to the PHY Register for EtherCAT specific requirements to determine link status and enable other functionalities. In scenarios where a port was never connected, the ESC may keep it in an “ALWAYS CLOSED” state until a valid link is detected via MDIO. This behavior ensures that the ESC only activates ports with confirmed physical connections, preventing potential communication issues. The MDIO Alive Register (MDIO_ALIVE_REG) indicates the status of the PHY along with the corresponding MDIO PHY Address. The MDIO Link Register indicates whether a valid link is detected on the corresponding PHY Address.

Please refer to Section 6.4.12 and Section 6.4.14.10 of the AM64x/AM243x Technical Reference Manual

Fast Link Detection Mechanism

To meet the stringent timing requirements of EtherCAT networks, the AM64x/AM243x platforms implement a fast link detection mechanism using the MDIO MLINK signal. This approach bypasses the standard state machine, allowing for quicker detection of link changes (10µs), which is essential for maintaining low-latency communication and effective cable redundancy. Refer to Enhanced Link for more details.

EtherCAT Firmware Migration guide

If your project is based on an older SDK and if you want to upgrade to the latest EtherCAT PRU firmware, follow the steps outlined below to ensure a smooth transition with minimal disruption to your existing codebase and system behavior:

  • The latest EtherCAT firmware can be taken from latest SDK released.
  • Copy the ecat_frame_handler_bin.h and ecat_host_interface_bin.h from {SDK_INSTALL_PATH}/source/industrial_comms/ethercat_slave/icss_fwhal/firmware/g_v1.3/ and replace the same in the SDK you are using.
  • Once the new firmware headers are in place, rebuild the libraries by running the FWHAL makefile, for example, gmake -s -f makefile.am243x.r5f.ti-arm-clang (for RELEASE build) and gmake -s -f makefile.am243x.r5f.ti-arm-clang PROFILE=debug (for DEBUG build) at {SDK_INSTALL_PATH}/source/industrial_comms/ethercat_slave/icss_fwhal/ for your corresponding device. Post this, you can rebuild the application to apply the latest FW changes.

Important Files and Directory Structure

Folder/Files Description
${SDK_INSTALL_PATH}/examples/industrial_comms
ethercat_subdevice_demo/simple EtherCAT SubDevice Simple Example (based on pre-integrated stack)
ethercat_subdevice_demo/cia402 EtherCAT SubDevice CiA402 Example (based on pre-integrated stack)
ethercat_subdevice_demo/ctt EtherCAT SubDevice CTT Example (based on pre-integrated stack)
ethercat_subdevice_beckhoff_ssc_demo EtherCAT SubDevice Example based on Beckhoff SSC
${SDK_INSTALL_PATH}/source/industrial_comms/ethercat_slave
icss_fwhal/firmware/g_v1.3 Firmware for the PRU cores in PRU-ICSS. Firmware Version : 6.5.54
icss_fwhal/lib/ FWHAL library for EtherCAT SubDevice
icss_fwhal/tiescbsp.h FWHAL interface file
stack/*.lib Evaluation libraries for EtherCAT SubDevice Stack
stack/esi ESI XML files for EtherCAT SubDevice Simple Example and EtherCAT SubDevice CiA402 Example
stack/inc Stack header files for evaluation stack
beckhoff_stack/esi ESI XML file for Beckhoff SubDevice Stack Code(SSC) based example
beckhoff_stack/patch Patch file for Beckhoff SubDevice Stack Code(SSC) sources
beckhoff_stack/stack_hal Stack adaptation APIs for Beckhoff SubDevice Stack Code(SSC)
beckhoff_stack/stack_sources Folder where Beckhoff SubDevice Stack Code(SSC) sources should be copied. Stack sources are not packaged in the SDK

API Documentation

Please see APIs for Ethercat Slave FWHAL for API documentation.

It is recommended to use these FWHAL APIs in the stack adaptation files. For example, see ${SDK_INSTALL_PATH}/source/industrial_comms/ethercat_slave/beckhoff_stack/stack_hal, which contains the stack adaptation APIs for Beckhoff SubDevice Stack Code(SSC).

Procedure to kick-off the EtherCAT SubDevice Controller(ESC)

  • Initialize memories (register protection, register reset values, EEPROM cache) and PRU-ICSS INTC module. This is done by FWHAL(Firmware and Hardware Abstraction Layer).
  • Load firmware into PRUs of PRU-ICSS. This is done by FWHAL.
  • Enable the PRU cores. This is done by FWHAL.
  • Initialize the EtherCAT SubDevice stack.
  • Wait for AL Event Request and SYNC (in DC synchronous mode) interrupts from PRU and run EtherCAT stack main loop for handling mailbox and ESC state machine.
  • Handle the events as needed. Note that this is handled by the stack.

Hardware Requirements

  • Sitara Processor with PRU-ICSS IP and EtherCAT support
  • Current implementation uses only Spinlock 0. Spinlocks 1 to 7 are free for use.
  • HW signals required to implement EtherCAT subdevice functionality is shown below, this info needs to be used in conjunction with SYSCONFIG:
    Signal Name Requirement

    Description

    PRU-ICSS MDIO
    PRGx_MDIO0_MDC Mandatory MDIO clock
    PRGx_MDIO0_MDIO Mandatory MDIO Data
    PRU-ICSS Distributed Clocks (Network Clock synchronization)
    PRGx_IEP0_EDC_SYNC_OUT0 Recommmended (for DC capable SubDevices) SYNC0 out - Time synchronized OUT0
    PRGx_IEP0_EDC_SYNC_OUT1 Optional (depends on customer application)) SYNC1 out - Time synchronized OUT1 (depends on SYNC0)
    PRGx_IEP0_EDC_LATCH_IN0 Optional LATCH0 in (Time stamp latch input0)
    PRGx_IEP0_EDC_LATCH_IN1 Optional LATCH1 in (Time stamp latch input1)
    PRU-ICSS MII PDI Interrupt
    PRGx_IEP0_EDIO_DATA_IN_OUT28 Optional PDI ISR output to external SOC pin (via one of the 4 PRU-ICSS digio outputs).
    PDI ISR pin can be selected via vendor specific register at offset 0xE0A.
    PRGx_IEP0_EDIO_DATA_IN_OUT29
    PRGx_IEP0_EDIO_DATA_IN_OUT30

    PRGx_IEP0_EDIO_DATA_IN_OUT31

    PRU-ICSS MII Port0 (IN Port) & PRU-ICSS MII Port1 (OUT Port)
    PRx_MII0_RXD0 Mandatory MII0 and MII1 Receive Data0
    PRx_MII1_RXD0
    PRx_MII0_RXD1 Mandatory MII0 and MII1 Receive Data1
    PRx_MII1_RXD1
    PRx_MII0_RXD2 Mandatory MII0 and MII1 Receive Data2
    PRx_MII1_RXD2
    PRx_MII0_RXD3 Mandatory MII0 and MII1 Receive Data3
    PRx_MII1_RXD3
    PRx_MII0_RXDV Mandatory MII0 and MII1 RX Data Valid
    PRx_MII1_RXDV
    PRx_MII0_RXER Optional if PHY supports Enhanced Link detection MII0 and MII1 RXERR
    PRx_MII1_RXER
    PRx_MII0_TXD0 Mandatory MII0 and MII1 Transmit Data0
    PRx_MII1_TXD0
    PRx_MII0_TXD1 Mandatory MII0 and MII1 Transmit Data1
    PRx_MII1_TXD1
    PRx_MII0_TXD2 Mandatory MII0 and MII1 Transmit Data2
    PRx_MII1_TXD2
    PRx_MII0_TXD3 Mandatory MII0 and MII1 Transmit Data3
    PRx_MII1_TXD3
    PRx_MII0_TXEN Mandatory MII0 and MII1 TX enable
    PRx_MII1_TXEN
    PRx_MII_MR0_CLK Mandatory MII0 and MII1 Receive clock
    PRx_MII_MR1_CLK
    PRx_MII_MT0_CLK Mandatory MII0 and MII1 Transmit clock
    PRx_MII_MT1_CLK
    PRx_MII0_RXLINK Mandatory for cable redundancy support Enhanced link detection. Redundancy support: connect LED_LINK/LED_SPEED from PHY here

    PRx_MII1_RXLINK

Interrupts

EtherCAT SubDevice Controller firmware generates the following interrupts.

8 Host Interrupts (Host Interrupts 2 through 9) are exported from the PRU_ICSSG internal INTC for signaling the device level interrupt controllers. PRU_EVTOUT0 to PRU_EVTOUT7 correspond to these eight interrupts in the following table. Please check PRUICSS Interrupt Controller section for more details.

Name Host Interrupt Description
DC SYNC0 OUT PRU_EVTOUT1 Used in DC mode for syncing the application
DC SYNC1 OUT PRU_EVTOUT2 Used in DC mode for syncing the application
PDI Interrupt PRU_EVTOUT3 AL event/PDI interrupt to host stack
ESC Command Acknowledgement PRU_EVTOUT4 ESC firmware command completion acknowledgement to Host

Enhanced Link

  • This feature ensures that the link signal is checked every approximately 10 µs.
  • Enhanced MII link detection will additionally disconnect a link if at least 32 RX errors (RX_ER) occur in a fixed interval of ~10 μs. Refer to Section 5.6.2 of Hardware Data Sheet Section I for more details.
  • For this feature to work, enhancedlink_enable of bsp_params should be set to TIESC_MDIO_RX_LINK_ENABLE while initializing the EtherCAT SubDevice FWHAL. This configuration is done in tiesc_socParamsInit() in tiescsoc.c file. In the current implementation, this feature is enabled by default and configurable through the EtherCAT module in SysConfig for ease of use:

Syscfg EnhancedLink Configuration

Enhanced Link Detection Procedure

  • Firstly, make sure the PHY supports Enhanced Link capability.
  • Make sure RXLINK pin is connected properly.
  • For this feature to work, LED pin is to be configured correctly within the application. Refer to ETHPHY_DP83826E_LED0 configuration in tiesc_ethphyInit() in tiescsoc.c file.
  • Check PRU MDIO registers for the PHY alive and link status. Refer to Section 6.4.14.10.3 (MDIO_ALIVE_REG Register) and Section 6.4.14.10.4 (MDIO_LINK_REG Register) of AM64x/AM243x Technical Reference Manual.
  • MDIO_ALIVE_REG: Each of the 32 bits of this register is set if the most recent access to the PHY with address corresponding to the register bit number was acknowledged by the PHY, the bit is reset if the PHY fails to acknowledge the access. Both the user and polling accesses to a PHY will cause the corresponding alive bit to be updated. The alive bits are only meant to be used to give an indication of the presence or not of a PHY with the corresponding address. Check to see if the expected bits are set.
  • MDIO_LINK_REG: This register is updated after a read of the Generic Status Register of a PHY. The bit is set/reset if the PHY with the corresponding address has link and the PHY acknowledges the read transaction. Check to see if the expected bits are set.
    • Do note that this register is dependent on the link polarity if the EnhancedLink feature is enabled. If the bits in this register are getting reset while connecting to an active network, it implies the polarity is active low. If the bits in this register are getting set while connecting to an active network, it implies the polarity is active high. This needs to be configured for TIESC_LINK0_POL and TIESC_LINK1_POL in tiescsoc.c file. Vendor specific ESC Register ESC_ADDR_TI_PHY_LINK_POLARITY can also be used to identify the polarity.
  • Make sure that the set bit address is configured as MDIO Phy Address in Syscfg -> ETHPHY for the corresponding PHY instances. The configured PHY address can be seen in Vendor Specific ESC Register ESC_ADDR_TI_PORT0_PHYADDR and ESC_ADDR_TI_PORT1_PHYADDR.
    Syscfg PHY Configuration
  • Check the PHY status: The MDIO module includes a user access register (MDIO_USER_ACCESS_REG_j) to directly access a specified Phy. This is described in MDIO Register offset 0x80 of the TRM for Reading and Writing Data from/to a PHY Register
  • Check frame couter and error counter vendor specific registers: ESC Register 0x0300 (RX Error Counter) is to be monitored for RX errors and Vendor specific ESC Register ESC_ADDR_TI_PORT0_ACTIVITY and ESC_ADDR_TI_PORT1_ACTIVITY should be monitored for number of valid frames at Port0 and Port1 respectively.
  • Once successful, build and load the application and try scanning with TwinCAT or any other EtherCAT MainDevices.
  • Refer to Testing Cable Redundancy for testing this feature using TwinCAT.

EtherCAT SubDevice Controller(ESC) Register List

TI EtherCAT SubDevice Controller Register List contains descriptions of the registers in TI's EtherCAT SubDevice Controller implementation.

EtherCAT SubDevice Controller(ESC) Exceptions

TI EtherCAT SubDevice Controller Exceptions lists the exceptions TI's EtherCAT SubDevice Controller implementation when compared with ET1100 ASIC. Please note that TI ESC is a 2 port EtherCAT SubDevice and it does not support E-bus interface and all the corresponding register fields are not implemented.

Debug Guide

EtherCAT Debug Guide covers the most obvious use cases and debug scenarios encountered while using EtherCAT SubDevice.

Additional References

Please refer to below documents to understand more about EtherCAT SubDevice on TI platforms and EtherCAT SubDevice protocol specifications.

Document Description
EtherCAT on Sitara Processors Application note by TI on the EtherCAT SubDevice implementation on TI's Sitara Processors.
PRU-ICSS EtherCAT SubDevice Troubleshooting Guide This troubleshooting guide is intended to provide guidance on how to set up and debug the EtherCAT SubDevice implemented on TI's Sitara processors.
EtherCAT ESC Datasheet Section 1 - Technology Section 1 of Beckhoff's EtherCAT SubDevice Controller (ESC) documentation which describes basic EtherCAT technology.
EtherCAT ESC Datasheet Section 2 - Register Description Section 2 of Beckhoff's EtherCAT SubDevice Controller (ESC) documentation which contains ESC register descriptions.
Application Note ET9300 (EtherCAT SubDevice Stack Code) This contains details on how to start EtherCAT SubDevice development with SubDevice Stack Code.
EtherCAT SubDevice Implementation Guide from EtherCAT Technology Group This contains information on how to develop an EtherCAT SubDevice implementation.
EtherCAT SubDevice Design Quick Guide from Beckhoff This contains information on modifying PDO when using Beckhoff SSC Tool for code generation.

See also