 |
AM243x INDUSTRIAL COMMUNICATIONS SDK
2026.00.00
|
|
|
AM243x INDUSTRIAL COMMUNICATIONS SDK
2026.00.00
|
|
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.
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 can be used to configure things mentioned below:
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 |
| 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.
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:
Please refer to Section 6.4.12 and Section 6.4.14.10 of the AM64x/AM243x Technical Reference Manual
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.
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:
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_subdevice/icss_fwhal/ for your corresponding device. Post this, you can rebuild the application to apply the latest FW changes.| Folder/Files | Description |
|---|---|
| ${SDK_INSTALL_PATH}/examples/industrial_comms | |
| ethercat_subdevice_demo/device_profiles/401_simple | EtherCAT SubDevice Simple Example (based on pre-integrated stack) |
| ethercat_subdevice_demo/device_profiles/402_cia | EtherCAT SubDevice CiA402 Example (based on pre-integrated stack) |
| ethercat_subdevice_demo/device_profiles/webserver | EtherCAT SubDevice Webserver Example (based on pre-integrated stack) |
| ethercat_subdevice_demo/device_profiles/401_simple_esi_parser | EtherCAT SubDevice Esi Parser 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_subdevice | |
| icss_fwhal/firmware/g_v1.3 | Firmware for the PRU cores in PRU-ICSS. Firmware Version : 6.5.79 |
| 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 |
Please see APIs for Ethercat SubDevice 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_subdevice/beckhoff_stack/stack_hal, which contains the stack adaptation APIs for Beckhoff SubDevice Stack Code(SSC).
| 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 | ||
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 |
This section describes the PRU-ICSS hardware resources used by the EtherCAT SubDevice firmware.
The EtherCAT SubDevice firmware runs on two PRU cores within the PRU-ICSS subsystem:
PRU Instruction RAM (IRAM):
| Resource | Total Size | Used (AM64x / AM243x) | Used (AM263x / AM263Px / AM261x) | Contents |
|---|---|---|---|---|
| PRU0 IRAM | 12 kB (0x3000) | 9320 bytes | 9276 bytes | Frame Handler firmware (ecat_frame_handler_bin.h) |
| PRU1 IRAM | 12 kB (0x3000) | 10708 bytes | 9876 bytes | Host Interface firmware (ecat_host_interface_bin.h) |
PRU Data RAM (DMEM):
| Resource | Size | PRU-local Base | Contents |
|---|---|---|---|
| PRU0 DMEM (DMEM0) | 8 kB | 0x00000000 | Host–PRU command interface, system time mirrors, SM state flags |
| PRU1 DMEM (DMEM1) | 8 kB | 0x00002000 (from PRU0 view) | ESC register write shadow (1 kB) and register permission/protection table (4 kB) |
Key layout within PRU0 DMEM:
| Offset | Size | Description |
|---|---|---|
| 0x0000 – 0x008F | 144 B | System state (reserved) |
| 0x0090 – 0x0093 | 4 B | System Time Low mirror |
| 0x0094 – 0x0097 | 4 B | System Time High mirror |
| 0x00A0 – 0x00A1 | 2 B | Command register (cmdlow) |
| 0x00A2 – 0x00A3 | 2 B | Command ACK register |
| 0x00A4 – 0x00A5 | 2 B | Command Parameter 1 |
| 0x00A6 – 0x00A7 | 2 B | Command Parameter 2 |
| 0x00A8 – 0x00A9 | 2 B | Command Response 1 |
| 0x00AA – 0x00AB | 2 B | Command Response 2 |
| 0x00EC – 0x00F7 | 12 B | SM process data array (6 × 4 B) |
| 0x0500 – 0x0529 | 42 B | Sync Permission Update registers |
Shared RAM:
| Resource | Size | PRU-local Base | Contents |
|---|---|---|---|
| Shared RAM | 32 kB | 0x00010000 | EtherCAT process data RAM, ESC emulation registers, FMMU/SM working area |
PRU Scratch PAD Banks:
The ICSS_G architecture provides hardware Scratch PAD (SPAD) banks for fast inter-PRU data exchange. These are accessed via XFR instructions and do not require DMEM reads/writes.
| Bank | XFR ID | Usage |
|---|---|---|
| SPAD Bank 0 | 10 | FMMU configuration temporary storage (20 bytes) |
| SPAD Bank 1 | 11 | SYNC start-time auto-activation, SM activate shadow values (8 bytes) |
| SPAD Bank 2 | 12 | Additional temporary storage |
The PRU-ICSS INTC is mapped at PRU-local address 0x00020000. The EtherCAT firmware configures the following system events:
System Events:
| Event | Direction | Description |
|---|---|---|
| IEP Timer/Capture/Compare | IEP → PRU1 | IEP timer event (DC synchronization, SYNC pulse timing) |
| PD Watchdog Expiry | ESC → PRU1 | Process data watchdog expired |
| PDI Watchdog Expiry | ESC → PRU1 | PDI watchdog expired |
| Latch0 Input | External → PRU1 | Latch0 timestamp capture trigger |
| Latch1 Input | External → PRU1 | Latch1 timestamp capture trigger |
| SYNC0 Output | PRU → ARM | DC SYNC0 pulse (exported as PRU_EVTOUT1) |
| SYNC1 Output | PRU → ARM | DC SYNC1 pulse (exported as PRU_EVTOUT2) |
| SYS_EVT_HOST_CMD | ARM → PRU1 | Host-to-firmware command trigger |
| SYS_EVT_HOST_CMD_LOW | ARM → PRU1 | Host-to-firmware low-priority command |
| SYS_EVT_AL_EVENT_REQUEST | PRU → ARM | AL event / PDI ISR (exported as PRU_EVTOUT3) |
| SYS_EVT_HOST_CMD_LOW_ACK | PRU → ARM | Firmware command completion ACK (exported as PRU_EVTOUT4) |
| PRU0/PRU1 RX Error / Overflow | MII → PRU | MII receive error and overflow events |
| MII Link0 / Link1 Event | MDIO → PRU | Port link state change events |
INTC Channel Mapping:
| Channel | Host Interrupt | Description |
|---|---|---|
| 0 | PRU0 internal | PRU0 self-interrupt |
| 1 | PRU1 internal | PRU1 self-interrupt (IEP, watchdog, link, latch events) |
| 2 | PRU_EVTOUT0 | Unused |
| 3 | PRU_EVTOUT1 | DC SYNC0 OUT to ARM host |
| 4 | PRU_EVTOUT2 | DC SYNC1 OUT to ARM host |
| 5 | PRU_EVTOUT3 | AL Event / PDI ISR to ARM host |
| 6 | PRU_EVTOUT4 | ESC Command ACK to ARM host |
| 7–9 | PRU_EVTOUT5–7 | Unused |
The IEP is the primary timing engine for the EtherCAT Distributed Clocks (DC) implementation. It is mapped at PRU-local address 0x0002E000.
IEP features used by EtherCAT firmware:
| Feature | IEP Register(s) | Description |
|---|---|---|
| 64-bit system time counter | COUNT_REG (offset 0x10–0x17) | DC time base; all EtherCAT timestamps are derived from this counter |
| Compare registers (CMP0–CMP7) | CMP_CFG_REG (0x70), CMP0–CMP7 (0x78–0xB0) | SYNC0 and SYNC1 pulse generation based on programmed start time and cycle time |
| Capture registers (CAPR0–CAPR7) | CAP_CFG_REG (0x18), CAPR0–CAPR7 (0x20–0x68) | Latch0 and Latch1 input event timestamping (rising/falling edge selectable) |
| DIGIO outputs | IEP EDIO registers | PDI ISR output to external SoC pin (selectable via vendor register 0xE0A) |
IEP clock frequency:
| Configuration | PRU Core Clock | IEP Clock |
|---|---|---|
| Configuration 1 (default) | 200 MHz | 200 MHz |
| Configuration 2 | 333 MHz | 333 MHz |
The active IEP clock frequency is reported in vendor-specific ESC register 0xED1.
The eCAP module is available within the PRU-ICSS subsystem at PRU-local address 0x00030000. It is defined in the PRU linker configuration but is not actively used by the EtherCAT SubDevice firmware. All latch timestamping and DC timing functionality is handled through the IEP capture and compare registers.
The EtherCAT SubDevice FWHAL uses the SoC hardware spinlock module to protect shared memory regions accessed concurrently by the ARM host processor and the PRU firmware.
| Spinlock Instance | Used By | Protected Region |
|---|---|---|
| Spinlock 0 | EtherCAT FWHAL | Latch0/Latch1 timestamp reads and other concurrent host/PRU shared memory accesses |
| Spinlocks 1–7 | Available | Free for custom application use |
The spinlock base address is configured via bsp_params.spinlock_base_address during bsp_init(). Spinlock acquire/release is handled through bsp_hwspinlock_lock(0) and bsp_hwspinlock_unlock(0).
The MII-RT configuration module is mapped at PRU-local address 0x00032000 and controls frame-level Ethernet timing parameters.
| Parameter | Register | Description |
|---|---|---|
| TX_START_DELAY (Port 0) | TXCFG0 | Process path transmit start delay (default 0x48/360 ns at 200 MHz; 0x50/400 ns at 333 MHz) |
| TX_START_DELAY (Port 1) | TXCFG1 | Autoforward path transmit start delay (default 0x38/280 ns at 200 MHz; 0x30/240 ns at 333 MHz) |
There is a vendor specific register which has the PDI ISR Timestamp:
| Register | Offset | Bits | Access | Default | Description |
|---|---|---|---|---|---|
| PDI ISR Time Register | 0x0E2C | 0-63 | RW | 0 | Register captures the System time when PDI ISR is triggered. |
You can map PDI ISR output to external SOC pin (via one of the PRU-ICSS digio outputs):
| Pin | Register Value (0x0E0A) |
|---|---|
| PRG1_IEP0_EDIO_DATA_IN_OUT31 | 0x80 |
| PRG1_IEP0_EDIO_DATA_IN_OUT30 | 0x40 |
| PRG1_IEP0_EDIO_DATA_IN_OUT29 | 0x20 |
| PRG1_IEP0_EDIO_DATA_IN_OUT28 | 0x10 |
For SYNC0 and SYNC1 timestamps, refer to the following registers:
These registers can be read to determine the exact timestamp when SYNC pulses occur, allowing for precise timing synchronization in your application.
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:
tiesc_ethphyInit() in tiescsoc.c file.
The TX_START_DELAY parameter is a critical timing configuration for EtherCAT SubDevices that affects network stability and performance. This section explains its purpose, behavior, and configuration options.
TX_START_DELAY defines the time interval between receiving a frame (RXDV active) and when the SubDevice begins transmitting the processed frame to the MII interface. Refer to MII_RT_TXCFG0 Register (for AM243x/AM64x) or ICSSM_PR1_MII_RT_PR1_MII_RT_CFG_TXCFG0 (for AM263x/AM263Px/AM261x) in the corresponding TRM for more details. This delay is measured in MII_RT clock cycles and serves several important purposes:
The TX_START_DELAY is configured through the following registers:
| Register | Offset | Bits | Access | Default Value | Description |
|---|---|---|---|---|---|
| Port0 TX Start Delay | 0x0E10 | 0-15 | RW | 0x48/0x50 | TX_START_DELAY for port 0. Modification from default values is not recommended. NOTE: Each increment of 1 corresponds to 5ns. Default values are:
|
| Port1 TX Start Delay | 0x0E12 | 0-15 | RW | 0x38/0x30 | TX_START_DELAY for port 1. Modification from default values is not recommended. NOTE: Each increment of 1 corresponds to 5ns. Default values are:
|
The EtherCAT firmware automatically adjusts these TX_START_DELAY values based on the FMMU configuration received from the EtherCAT MainDevice.
For complex FMMU configurations that require additional processing time, an increased TX_START_DELAY can be configured using:
| Register | Offset | Bits | Access | Default Value | Description |
|---|---|---|---|---|---|
| Increased TX Start Delay | 0x0ED0 | 0-7 | RW | 0x98/0xA0 | Configures the increased TX_START_DELAY for complex FMMU scenarios:
|
The firmware automatically detects the following scenarios and applies the increased TX_START_DELAY:
The EtherCAT firmware continuously monitors the FMMU configuration from the MainDevice and automatically adjusts the TX_START_DELAY as needed:
The value in register 0x0ED0 should be configured before the PRU cores start running. The default value of 0x98 (760ns) is suitable for most applications, but users can optimize this value for their specific network requirements.
If you observe malformed packets for LRD, LWR, or LRW datagrams in MainDevice logs or Wireshark captures, follow these steps:
| Register | Offset | Bits | Access | Description |
|---|---|---|---|---|
| MII_RT_TXCFG0 | 0x30032010 for ICSSG0 0x300B2010 for ICSSG1 | 16-25 | RW | TX_START_DELAY for port 0. Bits 16-25 show the current active delay value. |
TI EtherCAT SubDevice Controller Register List contains descriptions of the registers in TI's EtherCAT SubDevice Controller implementation.
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.
EtherCAT Debug Guide covers the most obvious use cases and debug scenarios encountered while using EtherCAT SubDevice.
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. |
1.8.20