4.6. ENET

4.6.1. Introduction

Enet LLD is an unified Ethernet driver that support Ethernet peripherals found in TI SoCs, such as CPSW and ICSSG. Enet LLD supports CPSW_2G, ICSSG Dual-MAC and ICSSG Switch in AM65xx devices.

The diagram below shows the overall software architecture of the Enet low-level driver. A top-level driver layer provides the interface that the applications can use to configure the switch and to send/receive Ethernet frames.

For instance, the CPSW support in the Enet driver consists of several software submodules that mirror those of the CPSW hardware, like DMA, ALE, MAC port, host port, MDIO, etc. Additionally, the Enet driver also includes PHY driver support as well as a resource manager to administrate the CPSW resources.

Enet LLD relies on other PDK drivers like UDMA for data transfer to/from the Ethernet peripheral’s host port to the other processing cores inside the TI SoC devices. For the lower level access to the hardware registers, Enet LLD relies on the Chip Support Library (CSL).

../_images/EnetLLD_Diagram.png

4.6. ICSSG

ICSSG Dual-MAC and Switch are both supported in Enet LLD on AM65xx devices. Currently, MCU R5F core is the only core where support has been added. Integration with TI NDK package has been enabled for ICSSG Dual-MAC, but not for ICSSG Switch.

The following tables summarize the features support by ICSSG Dual-MAC and Switch.

4.6. ICSSG Dual-MAC

Feature Remarks
VLAN classification and ingress filtering Supported
FDB Multicast filtering Supported
Ethernet QoS Support up to 8 queues
802.1as support Support Working Clock
Port state configuration Supported
Acceptable frame type configuration

Supported values are

  • Admit only VLAN-tagged frames
  • Admit only Untagged and priority-tagged frames
  • Admit all frames (default)
Statistics Supported

4.6. ICSSG Switch

Feature Remarks
2-Port cutthrough switch Supported
VLAN classification and ingress filtering Supported
FDB Multicast filtering Supported
Ethernet QoS Support up to 8 queues
Priority regeneration Supported
802.1as support Support Working Clock
802.1Q learning bridge for MAC addresses Supported - Shared VLAN configuration only
Buffering Validated up to 200us - Buffer configurable from application
Port State configuration Independently configurable on each port
Acceptable frame type configuration

Supported values are:

  • Admit only VLAN-tagged frames
  • Admit only Untagged and priority-tagged frames
  • Admit all frames (default)
Statistics Supported

4.6.2. User Interface

For details about individual fields of this library structure, see the PDK doxygen documentation

4.6.2.1. APIs

The Enet LLD APIs can be broadly divided into two categories: control and data path. The control APIs can be used to configure all Ethernet hardware submodules like FDB, MAC port, host port, MDIO, statistics, as well as PHY drivers and resource management. The data path APIs are exclusive for the DMA-based data transfers between the TI SoC processing cores and the Ethernet peripheral.

API reference for application:

#include <ti/drv/enet/enet.h>

The main APIs of the Enet LLD are the following:

  • Enet_open()
  • Enet_close()
  • Enet_ioctl()
  • Enet_poll()
  • Enet_periodicTick()

4.6.2.1.1. Data Path APIs

The main Enet LLD functions used to send and receive packets are:

  • EnetDma_openRxCh()
  • EnetDma_closeRxCh()
  • EnetDma_openTxCh()
  • EnetDma_closeTxCh()
  • EnetDma_retrieveRxPktQ()
  • EnetDma_submitRxPktQ()
  • EnetDma_retrieveTxPktQ()
  • EnetDma_submitTxPktQ()

It’s worth noting that the control path APIs are mainly IOCTL-based, and the data path APIs are direct functions in order to avoid any additional overhead associated with IOCTL calls as DMA data operations occur highly frequently.

4.6.2.1.2. IOCTL Interface

IOCTLs are system calls that take an argument specifying the command code and can take none or additional parameters via Enet_IoctlPrms argument. IOCTL are used by all Enet submodules except for DMA.

The Enet_IoctlPrms parameter structure consists of input and output argument pointers and their corresponding size. The following helper macros are provided to help construct the IOCTL params:

  • ENET_IOCTL_SET_NO_ARGS(prms). Used for IOCTL commands that take no parameters.
  • ENET_IOCTL_SET_IN_ARGS(prms, in). Used for IOCTL commands that take input parameters but don’t output any parameter.
  • ENET_IOCTL_SET_OUT_ARGS(prms, out). Used for IOCTL commands that don’t take input parameters but return output parameters.
  • ENET_IOCTL_SET_INOUT_ARGS(prms, in, out). Used for IOCTL commands that take input parameters and also return output parameters.

where prms in a pointer to Enet_IoctlPrms variable, in is the pointer to IOCTL input argument and out is the pointer to IOCTL output argument.

It’s recommended that the application doesn’t set the Enet_IoctlPrms members individually, but only through the helper macros listed above.

Please refer to the individual IOCTL command to find out if it requires input and/or output parameters.

4.6.3. lwIP Integration

See lwIP User’s Guide for further information about lwIP integration into PDK using Enet LLD, and NDK-to-lwIP migration guide.

4.6.4. Application

4.6.4.1. Examples

Enet LLD comes with a set of examples demonstrating the usage of driver APIs. The examples are:

  • enet_loopback: Internal (MAC port) or external loopback test.
  • enet_nimu_example: TCP/IP stack integration using TI NDK package.
  • enet_multiport: ICSSG and CPSW multiport test app.
Name Description Expected Results Cores Supported Peripherals
Loopback Enet Loopback example demonstrates basic packet send and receive on an Ethernet peripheral configured in MAC loopback or PHY loopback. All packets sent from the example application shall be received back after being looped in MAC or PHY. mcu1_0
  • CPSW_2G
NIMU Enet NIMU example demonstrates Enet driver integration with TI’s NDK TCP/IP stack. The example enables runs DHCP client, it can get an IP address when connected to a network. NIMU example application shall be able to get an IP address when connected to a network. User can test ‘ping’ and packet send/receive using NDK Winapps tools. mcu1_0
  • CPSW_2G
  • ICSSG0 Dual-MAC 1
  • ICSSG0 Dual-MAC 2
  • ICSSG1 Dual-MAC 1
  • ICSSG2 Dual-MAC 2
  • ICSSG3 Dual-MAC 1
  • ICSSG3 Dual-MAC 2
Multiport

Enet Multiport example demonstrates Enet driver capability to support multiple peripherals simultaneously. CPSW and all ICSSG peripherals can be opened simultaneously.

This example application implements an RX to TX loopback data path. Tx and RX packet timestamping is also demonstrated this example. A companion Linux host application is provided to facilitate packet send/receive to the device.

Multiport example app shall respond to all packets sent into a MAC port either via provided Linux host app or other traffic generator.

RX-to-TX timestamp difference shall be printed on UART terminal when packet timestamping is enabled via application’s menu.

mcu1_0
  • CPSW_2G
  • ICSSG0 Dual-MAC 1
  • ICSSG0 Dual-MAC 2
  • ICSSG1 Dual-MAC 1
  • ICSSG1 Dual-MAC 2
  • ICSSG2 Dual-MAC 1
  • ICSSG2 Dual-MAC 2
  • ICSSG0 Switch
  • ICSSG1 Switch
  • ICSSG2 Switch

4.6.4.1.1. Enet loopback

This example exercises the MAC loopback functionality of the hardware. The example is developed and tested on both bare metal and TI RTOS code base. The Ethernet peripheral is opened with default initialization parameters and the MAC loopback is enabled.

A Tx channel and a Rx flow are opened to enable data transfers. Packets are transmitted from the Switch R5F (Main R5F0_0) to the host port using the Tx channel. These packets are routed back to the host port by the switch hardware as the internal loopback feature is enabled. These packets are then transmitted to the Switch R5F by the Rx flow and the application is notified.

The Tx and Rx functions in the example are set to transmit and receive 10000 packets. After reaching the count of 10000, the application closes the Tx channel, Rx flow, peripheral (i.e. CPSW) and restarts the application for a configurable number of times. Restarting the loopback test application ensures that there aren’t any memory leaks, and the hardware is closed properly and can be reopened any time.

4.6.4.1.2. Enet LWIP

Building LWIP example

  • Enabling specific features in the test

    To configure what gets built in the example, navigate to the example directory pdk/packages/ti/drv/enet/examples/enet_lwip_example and find the lwipcfg.h file. Inside, change the macros corresponding to the program that you wish to build to 1.

    For example, if udpecho is required, set:

    #define LWIP_UDPECHO_APP        1
    

    Note

    The heap memory may need to be increased in the FreeRTOSConfig.h file to accomodate multiple apps.

  • To build the lwip example, issue the following command:

    make -s enet_lwip_example_freertos
    

Running LWIP example

  • Load and run the enet_lwip_example image from the corresponding binaries folder.

  • The setup requires a LAN cable to be connected between the device and a multiport-router for the link status to be UP and aquire an IP address.

  • Connect the LAN cable between the same router and Laptop/PC from where the ping/echo tests are run.

  • Wait until the local interface IP is assigned and printed on the console like below.

    Starting lwIP, local interface IP is dhcp-enabled
    CPSW_2G Test on MCU NAVSS
    EnetPhy_bindDriver: PHY 0: OUI:080028 Model:23 Ver:01 <-> 'dp83867' : OK
    PHY 0 is alive
    Host MAC address: 70:ff:76:01:02:03
    [LWIPIF_LWIP] CPSW has been started successfully
    [LWIPIF_LWIP] NETIF INIT SUCCESS
    status_callback==UP, local interface IP is 0.0.0.0
    Cpsw_handleLinkUp: Port 1: Link up: 100-Mbps Full-Duplex
    MAC Port 1: link up
    link_callback==UP
    status_callback==UP, local interface IP is 192.168.0.9
    Initializing apps
    UDP server listening on port 5001
    

Testing LWIP example

Prerequisites: LAN cable setup and device link is UP and Local interface IP is successfully aquired.

  • Ping test

    ping -t <ip_addr>
    ping -t 192.168.0.9
    
  • UDP/ TCP echo test

    Download echotool from this website and execute the commands to see the response.

    • UDP echo command:

      echotool.exe <ip_addr> /p udp /r 7 /n 0
      echotool.exe 192.168.0.9 /p udp /r 7 /n 0
      
    • TCP echo command:

      echotool.exe <ip_addr> /p tcp /r 7 /n 0
      echotool.exe 192.168.0.9 /p tcp /r 7 /n 0
      
  • iperf test

    Download iperf2 from iperf website and execute the commands to see the response.

    • iperf TCP test command:

      iperf.exe -c <ip_addr> -r
      iperf.exe -c 192.168.0.9 -r
      
    • iperf UDP test command:

      iperf.exe -c <ip_addr> -r -u
      iperf.exe -c 192.168.0.9 -r -u
      

Static IP

The Enet lwIP example uses DHCP by default. If static IP needs to be tested, the following two config options need to be disabled in examples/enet_lwip_example/lwipcfg.h.

#define USE_DHCP    0
#define USE_AUTOIP  0

The IP address, gateway and netmask can be set in the same lwipcfg.h file.

#define LWIP_PORT_INIT_IPADDR(addr)   IP4_ADDR((addr), 192,168,1,200)
#define LWIP_PORT_INIT_GW(addr)       IP4_ADDR((addr), 192,168,1,1)
#define LWIP_PORT_INIT_NETMASK(addr)  IP4_ADDR((addr), 255,255,255,0)

4.6.4.1.3. Enet NIMU Example

The Network Developer’s Kit (NDK) is a platform for development and demonstration of network enabled applications on TI embedded processors. The NDK stack serves as a rapid prototyping platform for the development of network and packet processing applications. It can be used to add network connectivity to existing applications for communications, configuration, and control. Using the components provided in the NDK, developers can quickly move from development concepts to working implementations attached to the network.

Network Interface Management Unit (NIMU) acts as an intermediate layer between Enet LLD and the TI-NDK (NDK is TI’s TCP/IP stack with http server, telnet support, etc).

The NIMU example uses the NIMU layer present in the Enet LLD and gets an IP address using the NDK stack and opens transmit and receive ports.

The send and receive functionalities of the Ethernet peripheral can be tested using the tools provided in NDK Winapps as follows:

  • Send test:

    cd ndk_<version>/packages/ti/ndk/winapps/
    ./send.x86U <IP address>
    
  • Receive test:

    cd ndk_<version>/packages/ti/ndk/winapps/
    ./recv.x86U <IP address>
    

Where IP address refers to the address of the processing core running the example, i.e. R5F, A72 or A53.

Note

Enet NIMU example is supported for CPSW_2G, CPSW_5G, CPSW_9G and ICSSG Dual-MAC. It’s not supported for ICSSG Switch.

4.6.4.1.4. Enet Multiport

The multiport example is dedicated to demonstrate simultaneous usage of Enet ICSSG peripherals operating in Dual-MAC mode. A total of up to 6 ICSSG MAC ports can be tested simultaneously with this example application.

This example application also supports CPSW2G peripheral present in AM65xx devices.

This example has two components:

  • Target-side application running on a Cortex R5F core.

    • One TX channel and one RX flow are opened for each available MAC port.
    • Application receives the packet, copies the payload into a new packet which is then sent back.
    • The application has a menu to enable/disable features, such as packet timestamping. This menu along with application logs are implemented via UART.
  • Host-side application.

    • This is a Linux command-line application meant to simplify testing of the multiport example, it uses a raw socket to send and receive packets.
    • Alternatively, other application could be used as well: packETH tool can be used to generate and send packets, Wireshark can be used to receive and verify packet contents.

The diagram below shows the enabled data paths for the Ethernet peripherals in AM65xx device. Note that the example application opens all these peripherals simultaneously, but it’s not mandatory to have all ports connected at the same time. Tests can be run with the connected ports.

../_images/MultiportApp.png

The data path enabled in this example is as follows:

  1. Host side (PC) application sends a packet to an AM65xx IDK MAC port.

    • By default, a broadcast packet is sent but the user can specify any other MAC address.
  2. Target side application receives the packet, updates the MAC addresses in the Layer-2 header and sends the packet back.

  3. Host side application receives the packet and checks if the payload matched what it had sent in step 1.

  4. Packet timestamping can be enabled/disabled at any time via target-side application menu. Enabling timestamping implies that both RX and TX timestamps will be enabled.

Note

Currently, this example is supported only in TI AM65xx Industrial Development Kit (IDK) which provides:

  • 6 x ICSSG MAC ports or 3 x ICSSG Switch peripherals
  • 1 x CPSW2G MAC port.