7. PRU-ICSS Firmware

7.1. Dual EMAC and Switch

7.1.1. Introduction

The ICSS FIRMWARES serves as example to implement various network functionalities. Package includes source release for Dual_emac and basic switch firmwares.

7.1.2. DUAL_EMAC

ICSS DUAL EMAC FIRMWARE is a single port Ethernet MAC (Media Access Control) i.e. Layer 2 of OSI Model. It implements a 2 port ethernet mac supporting 10/100 Mbps. DUAL EMAC FIRMWARE is standardized to IEEE 802.1 Ethernet Standards. Primary use case of the protocol is to demonstrate basic ethernet functionality via both PRU cores on 10/100 Mbit Ethernet cable. ICSS DUAL EMAC FIRMWARE can be used independently on two PRU’s to implement two independent MAC’s with two different MAC addresses and two different IP addresses. To provide an analogy, this is somewhat similar to a two port Ethernet PCIe NIC card on a PC.Ethernet interface in this case is available along with Host processor on a single SoC. Following are high level features:

Requirements Remarks
1 ms buffering per port Supported
Host IRQ Supported
Ethernet QoS With 2 queues instead of 8. So, it is not a standard Ethernet QoS implementation.
Statistics Supported
Storm Prevention Supported
Promiscuous Mode Supported
TTS (Time Triggered Send) Supported
Error Handling Supported
Multicast filtering Supported
VLAN filtering Supported
PTP Handling Supported

7.1.3. SWITCH

ICSS SWITCH FIRMWARE is a three port learning Ethernet switch i.e. Layer 2 of OSI Model. It implements a 2 port cut through ethernet switch supporting at 100 Mbps. SWITCH FIRMWARE is standardized to IEEE 802.1 Ethernet Standards. The primary use case of the protocol is to use Ethernet to automate applications which require short cut-through latency and low hardware costs. ICSS SWITCH FIRMWARE uses two PRU to implement three port Ethernet switch with one single MAC and IP address. To provide an analogy, this is somewhat standard network switch only here the network functionality is available to the host core within the single SOC. The following are the high level features it supports.

Requirements Remarks
Cut-Through Supported
Store and Forward Supported
1 ms buffering per port Supported
Host IRQ Supported
Ethernet QoS With 4 queues instead of 8. So, it is not a standard Ethernet QoS implementation.
802.1 learning switch Supported
Statistics Supported
Queue-Contention Handling on each port Supported
Three-Port Switch Supported
Storm Prevention Supported
Error Handling Supported

7.1.4. Code Organization

Requirements Location in SDK Remarks
Common baseline code <PDK>/packages/ti/drv /icss_emac/firmware/icss_dualemac common code for dual_emac and switch
DUAL_EMAC <PDK>/packages/ti/drv /icss_emac/firmware/icss_dualemac dual_emac firmware specific code
SWITCH <PDK>/packages/ti/drv /icss_emac/firmware/icss_switch switch firmware specific code

7.1.5. Firmware Build Instruction

7.1.5.1. Build instruction from Processor SDK Release package

Pre-requisites to Building

Refer to the Processor SDK RTOS Building page for information on setting up build environment.

Compiling ICSS-EMAC FIRMWARES

  • cd <PDK>/packages/ti/drv/icss_emac
  • make firm

Firmware binaries at the end of the build will be located at:

  • <PDK>/packages/ti/drv/icss_emac/firmware/<FIRMWARE_TYPE>/bin/<SOC>/<HOST_CORE>/<REVISION>
  • <FIRMWARE_TYPE> indicates the firmware type i.e. icss_dualemac for DUAL_EMAC or icss_switch for SWITCH
  • <SOC> indicates the SOC type.
  • <HOST_CORE> indicates the Host core type on which the built binary can be loaded.
  • <REVISION> indicates the revision of the firmware binary based on core. (There are 2 revision of PRU ICSS core)

7.1.5.2. Build instruction from GIT

Following are the steps for building firmware from any external environment outside PROC SDK RTOS.

  • Creation of directories
    • Create a working directory e.g. <WORK_DIR>
    • Create a new directory named ti inside working directory. i.e. <WORK_DIR/ti>
    • Create a new directory called drv inside ti. i.e. <WORK_DIR/ti/drv>
  • Clone of Repos
    • Git clone pdk build repo into ti directory. i.e. <WORK_DIR/ti/build>
    • Git clone icss_emac repo into ti/drv directory. i.e. <WORK_DIR/ti/drv/icss_emac>
  • Setting Environment Variables
    • Export CLPRU install path. i.e. export CL_PRU_INSTALL_PATH=clpru toolchain directory
    • Export pdk install path. i.e. export PDK_INSTALL_PATH=<WORK_DIR>
    • Export LIMIT_SOCS Variable i.e. LIMIT_SOCS=<SOC> [Optional for limiting to some SOCs]
  • Build command
    • Run make firm/firm_clean to build/clean firmware from icss_emac directory i.e. <WORK_DIR/ti/drv/icss_emac>
  • Generated binaries
    • the firmware binaries which will be located in <WORK_DIR/ti/drv/icss_emac/firmware/<FIRMWARE_TYPE>/bin/<SOC>/<HOST_CORE>/<REVISION>>

7.1.6. Supported EVMs

The following is a list of EVMS supported and the PRU-ICSS ethernet ports to be used:

EVM Name PRU-ICSS Instance Supported PRU ICSS core revision
icev2AM335x PRU-ICSS instance 1 REV1
idkAM437x PRU-ICSS instance 2 REV1
idkAM571x PRU-ICSS instance 2 REV2
idkAM572x PRU-ICSS instance 2 REV1 & REV2 (Earlier version of AM572x soc had REV1 pru cores while later had REV2 pru cores)
iceK2G PRU-ICSS instance 2 REV2

7.1.7. Running ICSS-EMAC FIRMWARES Example

Please go through the following page for example demonstrating the use of the firmware via icss-emac driver. [1]


Firmware Design Guide

Document Location
ICSS DUAL EMAC FIRMWARE Design Guide <PDK>/packages/ti/drv/icss_emac/f irmware/icss_dualemac/docs/ICSS_D UAL_EMAC_Firmware_Design_Guide.pd f
ICSS SWITCH FIRMWARE Design Guide <PDK>/packages/ti/drv/icss_emac/f irmware/icss_switch/docs/ICSS_SWI TCH_Firmware_Design_Guide.pdf

NOTE: For normal use case, there is no need to refer this document. Unless you wish to go through the internal working for firmware and/or wanted to modify it.


7.2. ICSS-G Dual EMAC

7.2.1. Introduction

The ICSS-G FIRMWARE serves as example to implement various network functionalities. Package includes source release for DUAL EMAC

7.2.2. DUAL_EMAC

ICSS DUAL EMAC FIRMWARE is a single port Ethernet MAC (Media Access Control) i.e. Layer 2 of OSI Model. It implements a 2 port Ethernet mac supporting 100Mbps and 1Gbps. DUAL MAC FIRMWARE is standardized to IEEE 802.1 Ethernet Standards. Primary use case of the protocol is to demonstrate basic Ethernet functionality via both PRU/RTU cores. ICSS-G DUAL EMAC FIRMWARE can be used independently on two PRUs to implement two independent MACs with two different MAC addresses and two different IP addresses.

Following are high level features:

Requirements Remarks
4 egress DMA threads per port Supported
4 ingress “buckets” per port Supported
Statistics Supported
Storm Prevention Future
Promiscuous Mode Supported
TTS (Time Triggered Send) Future
Error Handling Supported
Multicast filtering Supported
VLAN filtering Future
PTP Handling Supported

7.2.3. Firmware Code Location and Build Instruction

Firmware is located at <PDK>packages/ti/drv/emac/firmware/icss_eth/src directory.

The CLPRU toolchain has to be used to build the firmware. The toolchain can be downloaded from <https://software-dl.ti.com/codegen/esd/cgt_public_sw/PRU/2.2.1/ti_cgt_pru_2.2.1_linux_installer_x86.bin>

To build the firmware:

  • cd to <PDK>packages/ti/drv/emac/firmware/icss_eth/src directory
  • make CLPRU_INSTALL_PATH=<dir_where_the_toolchain_installed>.

The firmware will be located in the <PDK>packages/ti/drv/emac/firmware/icss_eth/src/dm directory.


7.3. PRU-ICSS SORTE

7.3.1. Introduction

The Simple Open Real-time Ethernet protocol (SORTE) serves as an example for Texas Instruments programmable approach to real-time communication for input/output (IO) networks with a maximum of 254 devices. This protocol is fully documented and released in source code. It is open to customers to learn, adapt and enhance the protocol for their application requirements. SORTE is not bound to a given communication standard and breaks some of the limits of existing standards such as minimum Ethernet frame size, addressing and error detection. The primary use case of the protocol is to connect different end-equipment using Ethernet physical layer devices and 100 Mbit Ethernet cable.

7.3.2. Protocol Overview

The SORTE protocol is a TI-developed industrial Ethernet protocol that supports 4-µs cycle time. The SORTE protocol operates on the PRU-ICSS, which is an industrial peripheral within Sitara and KeyStone processors from Texas Instruments. SORTE protocol operates exclusively on the PRU-ICSS; therefore, the ARM Cortex-A8, A9 or A15 processors – depending on the device family – are available for industrial applications. The SORTE protocol differentiate between two network components: the master and one or more slave devices. For in depth details of the protocol please refer to the the design documents as listed in the References section below.

7.3.3. Code Organization

THE SORTE ARM application and firmware sources can be found under the following directory :

<PDK>/packages/ti/drv/pruss/example/apps/sorte/

Refer to the README.txt in this directory for details of directory layout.

In addition, there is a README.txt which provides high-level over of how the protocol is implmented for master and slave device network compoments which can be found at:

<PDK>/packages/ti/drv/pruss/example/apps/sorte/firmware/src/master/README.txt

<PDK>/packages/ti/drv/pruss/example/apps/sorte/firmware/src/slave/README.txt


7.3.4. Building the Examples

7.3.4.1. Pre-requisites to Building

  1. Set your environment using pdksetupenv.sh. Building the Firmware binaries and ARM application uses the same environment variables as the pruss driver library build. Refer to the Processor SDK RTOS Building page for information on setting up your build environment.

7.3.4.2. Compiling the PRUSS SORTE Firmware

To build the SORTE firmware binaries:

  1. cd <PDK>/packages/ti/drv/pruss
  2. make firm

This will make the firmware binaries which will be located in:

<PDK>/packages/ti/drv/pruss/example/apps/sorte/firmware/bin/<BOARD>


7.3.4.3. Compiling the PRUSS SORTE Application

To build the SORTE ARM applications:

  1. cd <PDK>/packages/ti/drv/pruss
  2. make apps

This will make the ARM applications for both master and slave device which will be located in:

<PDK>/packages/ti/drv/pruss/example/apps/sorte/slave<BOARD>

<PDK>/packages/ti/drv/pruss/example/apps/sorte/master<BOARD>


7.3.5. Supported EVMs

The following is a list of EVMS supported and the PRU-ICSS ethernet ports to be used:

EVM Name PRU-ICSS Instance Port0 Port1
icev2AM335x PRU-ICSS instance 1 J1 J2
idkAM437x PRU-ICSS instance 2 J6 J9
idkAM571x PRU-ICSS instance 2 J6 J8
idkAM572x PRU-ICSS instance 2 J6 J8
iceK2G PRU-ICSS instance 2 J8A J8B

7.3.6. Running the PRUSS SORTE Example

In order to run the SORTE applications, you will require 1 EVM running as master and 2 EVMs running as slave(slave1/slave2). Use CCS to load and run the master and slave applications respectively.

Prior to running the applications its best to connect the EVMS as follows:

Connect master Port0 to slave1 Port0. Connect slave1 Port1 to slave2 Port0.

Note that the master device will wait until it discovers 2 slave devices in the network. UART console on the master will print the following until 2 slave devices are detected:

sorte master: waiting for atleast 2 SLAVE devices connected

Once 2 slave devices are detected by the master, the following print will be seen on UART console and master will continue with state machine and protocol processing:

sorte master: 2 SLAVE devices connected

The slave device via the UART console will continuosly display the number of packets its received during input output exchange state of the protocol until pass criteria is reached as follows(as an example):

sorte slave: test in progress: current receive packet count: 35000

sorte slave: test in progress: current receive packet count: 40000

Once pass criteria number of packets have been received, the following print will be displayed on UART console:

All tests have passed



7.3.7. Additional Reference

Document Location
SORTE Master with PRU-ICSS Reference Design https://www.ti.com/tool/TIDEP-0085
SORTE Slave Device with PRU-ICSS Reference Design https://www.ti.com/tool/TIDEP-0086

7.4. PRU-ICSS I2C

7.4.1. Introduction

PRU-ICSS I2C serves as an example for firmware-based I2C peripheral support. The I2C firmware (I2C FW) allows additional I2C instances for SOCs beyond those supported by SOC hardware. The Processor SDK package includes full source code for I2C FW.

7.4.2. FIRMWARE FEATURES

I2C FW supports the standard two pin I2C interface through three GPIO pins from the PRU-ICSS module. The I2C SCL pin is implemented using a single GPIO configured in GPO mode. The I2C SDA pin is implemented using two GPIO pins: one pin configured in GPI mode for sampling SDA, and a second pin configured in GPO mode for driving the SDA. Depending on the I2C clock speed, I2C FW can emulate multiple I2C instances from a single PRU core. Following are high-level I2C FW features:

Feature Remarks
No. of instances

4 (Standard mode)

1 (Fast mode)

SMBus support Supported
Addressing modes 7/10-bit
Master mode Supported
I2C data transfer rate from 100 kbps up to 400 kbps 100 kHz / 400 kHz
Bit format transfer 8 bit
Number of host interrupts 1
Peripheral enable/disable capability Supported
Start/Restart/Stop Supported
Built-in configurable FIFOs (8, 16, 32, 64 bytes) for buffered read/write 8/16/32/64/128/256
8-bit-wide data access Supported
Slave reset feature Supported
Internal loopback feature Supported
Slave mode Not Supported
Combined Master-Slave mode/transaction Not Supported
DMA support Not Supported
Programmable clock generation Not Supported
Implement Auto Idle mechanism (SOC specific feature) Not Supported
Implement Idle Request/Idle Acknowledge handshake mechanism (SOC specific feature) Not Supported
Support for asynchronous wakeup mechanism Not Supported

7.4.3. Firmware Organization

FW Item Directory
Source code <PDK>/packages/ti/drv/i2c/firmware/icss_i2c/src
Design Guide <PDK>/packages/ti/drv/i2c/firmware/icss_i2c/docs
Firmware binaries <PDK>/packages/ti/drv/i2c/firmware/icss_i2c/bin

7.4.4. Firmware Build Instruction

7.4.4.1. Build instruction from Processor SDK Release package

Pre-requisites to Building

Refer to the Processor SDK RTOS Building page for information on setting up the build environment.

Compiling I2C FIRMWARE

  • cd <PDK>/packages/ti/drv/i2c
  • make firm

Firmware binaries at the end of the build will be located at:

  • <PDK>/packages/ti/drv/i2c/firmware/<FIRMWARE_TYPE>/bin/<SOC>/<HOST_CORE>/<REVISION>
  • <FIRMWARE_TYPE> indicates the firmware type i.e. icss_i2c
  • <SOC> indicates the SOC type, e.g. am437x
  • <HOST_CORE> indicates the Host core type on which the built binary can be loaded, e.g. a9host
  • <REVISION> indicates the revision of the firmware binary based on core (there are 2 revision of PRU-ICSS core), e.g. REV1.

7.4.4.2. Build instruction for GIT

Following are the steps for building firmware from any external environment outside Processor SDK RTOS package.

  • Creation of directories
    • Create a working directory e.g. <WORK_DIR>
    • Create a new directory named ti inside working directory. i.e. <WORK_DIR/ti>
    • Create a new directory called drv inside ti. i.e. <WORK_DIR/ti/drv>
  • Clone of Repos
    • Git clone pdk build repo into ti directory. i.e. <WORK_DIR/ti/build>
    • Git clone i2c repo into ti/drv directory. i.e. <WORK_DIR/ti/drv/i2c>
  • Setting Environment Variables
    • Export CLPRU install path. i.e. export CL_PRU_INSTALL_PATH=clpru toolchain directory
    • Export pdk install path. i.e. export PDK_INSTALL_PATH=<WORK_DIR>
    • Export LIMIT_SOCS Variable i.e. LIMIT_SOCS=<SOC> [Optional for limiting to some SOCs]
  • Build command
    • Run make firm_clean/firm to clean/build firmware from i2c directory i.e. <WORK_DIR/ti/drv/i2c>
  • Generated binaries
    • the firmware binaries which will be located in <WORK_DIR/ti/drv/i2c/firmware/<FIRMWARE_TYPE>/bin/<SOC>/<HOST_CORE>/<REVISION>>

7.4.5. Supported EVMs

Supported EVMs and pin configurations for these EVMs are listed below.

EVM Name PRU-ICSS Instances PRU-ICSS Revision
icev2AM335x 1 REV1
idkAM437x 2 REV1
idkAM574x 2 REV2
idkAM572x 2 REV2

icev2AM335x

ICSS PRU Instance Functional Pin PRU GPIO Pins EVM Port EVM Pin
ICSS1 PRU0 I2C0 SCL pr1_pru0_pru_r30_1 J3 14
SDA pr1_edio_data_out7 J4 21
pr1_pru0_pru_r31_0 J3 12

idkAM437x

ICSS PRU Instance Functional Pin PRU GPIO Pins EVM Port EVM Pin
ICSS1 PRU0 I2C0 SCL pr1_pru0_pru_r30_8 J3 6
SDA pr1_edio_data_out0 J3 5
pr1_pru0_pru_r31_9 J3 8
I2C1 SCL pr1_pru0_pru_r30_10 J16 46
SDA pr1_edio_data_out1 J3 7
pr1_pru0_pru_r31_11 J16 48
ICSS0 PRU0 I2C0 SCL pr0_pru0_pru_r30_8 J16 56
SDA pr1_edio_data_out0 J3 5
pr0_pru0_pru_r31_9 J16 37
I2C1 SCL pr0_pru0_pru_r30_10 J16 38
SDA pr1_edio_data_out1 J3 7
pr0_pru0_pru_r31_11 J16 58

idkAM572x/idkAM574x

ICSS PRU Instance Functional Pin PRU GPIO Pins EVM Port EVM Pin
ICSS1 PRU0 I2C0 SCL pr1_pru1_gpo1 J21 5
SDA pr1_edio_data_out1 J46 4
pr1_pru1_gpi0 J21 3

7.4.6. I2C FIRMWARE Example

Sample code for I2C transaction:

/* Refer to I2C FW Example for details */
...

/* Initialize the I2C FW configuration */
I2C_socInitFwCfg();

/* Get the default I2C init configuration */
I2C_socGetFwCfg(I2C_TEST_INSTANCE1, &i2c_cfg);

/* Modify the default I2C configurations if necessary */

/* Set the default I2C init configurations */
I2C_socSetFwCfg(I2C_TEST_INSTANCE1, &i2c_cfg);
...

Board_init(boardCfg);
...

I2C_init();

handle = I2C_open(I2C_TEST_INSTANCE1, &i2cParams);
...

/* Initiate I2C transfers */
I2C_transactionInit(&i2cTransaction);
i2cTransaction.slaveAddress = I2C_EEPROM_ADDR;
...

status = I2C_transfer(handle, &i2cTransaction);
if (status!= I2C_STS_SUCCESS) {
    /* I2C transaction failed */
}

Sample code for SMBus transaction:

/* Refer to I2C FW Test for details */
...

testCmd.transferCmd = SMBUS_WRITE_BYTE_CMD;
testCmd.cmdCode = WRITE_SMBUS_COMMAND_CODE;
controlStatus = I2C_control(handle, I2C_CMD_SMBUS_TYPE, ((void*)&testCmd));
I2C_transactionInit(&i2cTransaction);
...

status = I2C_transfer(handle, &i2cTransaction);
if (status != I2C_STS_SUCCESS) {
    /* I2C transaction failed */
}

Examples List

Refer to the Release Notes for details concerning I2C support across different EVMs.

Name Description Expected Results
I2C_FwExample Driver Firmware example application for I2C FW instances

Status messages will be displayed on console based based on pass/fail criteria:

Pass criteria:

I2C Test: Instance: Baud Rate 100KHz:

All tests have passed.


Firmware Design Guide

Document Location
I2C FIRMWARE Design Guide <PDK>/packages/ti/drv/i2c/firmware/icss_i2c/docs/I2C_FW_DESIGN_GUIDE.pdf

NOTE: For normal use of I2C FW, there is no need to refer to the design guide. This document can be cosulted in case of interest in details of internal firmware operation, or a desire to modify the firmware.