AM263Px MCU+ SDK: ICSS-EMAC Lwip Example

| AM263Px MCU+ SDK 26.00.00 |

ICSS-EMAC Lwip Example

# Introduction

Note
  lwIP features are made available as is from public lwIP project. SDK configuration may only enable and exercise a subset of these features.

This example is an ICSS-EMAC application using the LwIP networking stack.

The examples does the following:

- Initializes the ICSS-EMAC driver for the underlying HW
- Initializes the LwIP stack
- Allows users to run and test basic networking features like ping, iperf with TCP/UDP.
- Allows users to configure between ICSS_EMAC Switch and MAC modes.
- Example is configured to run in Switch mode.

# Supported Combinations

Parameter | Value
--- | ---
CPU + OS | r5fss0-0_freertos
Toolchain | ti-arm-clang
Boards | am263px-cc, am263px-lp
Example folder | examples/networking/lwip/icss_emac_lwip

# Configuring Syscfg

- The following Syscfg parameters in the ICSS-EMAC instance should be changed to swap between Switch and EMAC examples.

Parameter | Status/Value for MAC | Status/Value for Switch | Description | Remarks/Default Setting
--- | --- | --- | --- | ---
EMAC Mode | MAC1/MAC2/MAC1 of DUAL EMAC/MAC2 of DUAL EMAC | Switch | Parameter to choose between EMAC and Switch modes. | Default is Switch.
RT/NRT Priority Separation Queue | QUEUE1 | QUEUE4 | If packets are in Queue <= RT/NRT Priority separation queue, they will be forwarded to RT callback and others to NRT callback. | Default is QUEUE4.
Learning Enable | DISABLED | ENABLED | Learning only applicable for Switch | Default is ENABLED.

# Iperf using LWIP

- Iperf is a tool for network performance measurement and tuning. It is a cross-platform tool that can produce standardized performance measurements for any network. Iperf has client and server functionality, and can create data streams to measure the throughput between the two ends in one or both directions.
- Iperf version to be used is version 2.0.9-win64(on windows) and version 2.+ on linux(Ubuntu 18.04 64bit).
- The lwip app has iperf enabled by default.

## Important Iperf Arguments:

Argument | Meaning
--- | ---
-s | Run server
-c | Run Client [Ex: -c 192.168.1.102]
-u | UDP
-b | Bandwidth [Used in UDP, Ex: 100M M->Mbits]
-i | Output interval in Sec [Ex: -i1 1sec interval]
-t | Time in sec [Ex: -t60 60sec]
-p | Port number [Ex: -p 5555]
-w | Windows size [Ex: -w 1M M->Mbits]
-d | Bi-directional traffic
-l | Length [Ex: -l 1046 1046bytes]
-V | Used when IPv6 address is used instead of IPv4

# Steps to Run the Example

## Build the example

- When using CCS projects to build, import the CCS project for the required combination and build it using the CCS project menu (see Using SDK with CCS Projects).
- When using makefiles to build, note the required combination and build using make command (see Using SDK with Makefiles)

## HW Setup

Note
  Make sure you have setup the EVM with cable connections as shown here, EVM Setup. In addition do below steps.

## Create a network between EVM and host PC

- The EVM will get an IP address of 192.168.0.200. Make sure to connect the other end of the cable to a network which is in the same sub-network.
- To get started, create a simple local network between the EVM and the host PC as shown below.

Local network between PC and EVM

- After we run the example on the EVM (in the next step), it will be assigned an IP address using which the host can communicate with the EVM.

## Run the example

Attention
  If you need to reload and run again, a CPU power-cycle is MUST

- Launch a CCS debug session and run the example executable, see CCS Launch, Load and Run
- You will see logs in the UART terminal as shown in the next section.
- Note the IP address seen in the log, this is what we will use to communicate with the EVM.

## Sample output for ICSS-EMAC LWIP example

MII mode
Firmware load to PRU0 passed
Firmware load to PRU1 passed
Starting lwIP, local interface IP is 192.168.0.200
[LWIPIF_LWIP_EMAC]Link is down[LWIPIF_LWIP_EMAC] Interface layer handle is Initialised
[LWIPIF_LWIP_EMAC] NETIF INIT SUCCESS
status_callback==UP, local interface IP is 192.168.0.200
UDP server listening on port 5001
link_callback==UP
5.653s : CPU load = 1.39 %
10.653s : CPU load = 0.56 %

## Communicate with the EVM using ethernet

- Firstly you can try to reach the EVM using ping as shown below, using a command shell on the host PC

        > ping 192.168.0.200

- Next you can run `iperf` tests as shown below. Below steps have been tried with a Windows 10 host PC running.
  - Install `iperf` if not installed by doing below

         > sudo apt install iperf

  - Invoke iperf to test TCP bi-directional RX+TX connection as shown below
    > iperf -c 192.168.0.200 -i 5 -t 20 -d

## Measuring the throughput using Iperf:

- Once we get the IP after running the example, we can use following iperf command on windows to get the throughput.
  - iperf.exe -c 192.168.0.200 -r

## Sample output for iperf command

DUT side:

MII mode
Firmware load to PRU0 passed
Firmware load to PRU1 passed
Starting lwIP, local interface IP is 192.168.0.200
[LWIPIF_LWIP_EMAC]Link is down[LWIPIF_LWIP_EMAC] Interface layer handle is Initialised
[LWIPIF_LWIP_EMAC] NETIF INIT SUCCESS
status_callback==UP, local interface IP is 192.168.0.200
UDP server listening on port 5001
link_callback==UP
5.653s : CPU load = 1.39 %
10.653s : CPU load = 0.56 %
15.653s : CPU load = 0.56 %
20.653s : CPU load = 0.53 %
25.653s : CPU load = 0.53 %
30.653s : CPU load = 4.77 %
35.653s : CPU load = 90.97 %
IPERF report: type=0, remote: 192.168.0.33:53365, total bytes: 86114328, duration in ms: 10056, kbits/s: 68504
40.653s : CPU load = 90.87 %
45.653s : CPU load = 44.60 %
IPERF report: type=1, remote: 192.168.0.33:5001, total bytes: 55255064, duration in ms: 10000, kbits/s: 44200
50.653s : CPU load = 43.35 %
55.653s : CPU load = 0.54 %

PC Side:

C:\ti\iperf-2.0.9-win64>iperf -c 192.168.0.200 -r
------------------------------------------------------------
Server listening on TCP port 5001
TCP window size: 208 KByte (default)
------------------------------------------------------------
------------------------------------------------------------
Client connecting to 192.168.0.200, TCP port 5001
TCP window size: 208 KByte (default)
------------------------------------------------------------
[ 4] local 192.168.0.33 port 53365 connected with 192.168.0.200 port 5001
[ ID] Interval Transfer Bandwidth
[ 4] 0.0-10.0 sec 82.1 MBytes 68.8 Mbits/sec
[ 4] local 192.168.0.33 port 5001 connected with 192.168.0.200 port 54911
[ 4] 0.0-10.0 sec 52.7 MBytes 44.2 Mbits/sec

## Troubleshooting issues

- Refer to ICSS-EMAC Debug Guide for troubleshooting issues.

# See Also

Ethernet And Networking