8.5. Developing Ethernet based applications with Linux + RTOS

8.5.1. Introduction

Common Port Switch (CPSW) provides Ethernet packet communication for the device & also acts as an Ethernet switch. The total ports includes the following:

  • Internal Host Port which provides the packet streaming interface to the device cores

  • External MAC Ports supporting the following:

    • Media Independent Interface (MII)

    • Gigabit Media Independent Interface (GMII)

    • Reduced Media Independent Interface (RMII)

    • Reduced Gigabit Media Independent Interface (RGMII)

    • Serial Gigabit Media Independent Interface (SGMII)

    • Quad Serial Gigabit Media Independent Interface (QSGMII)

The MII modes supported vary based on device variant.

  • J721E has 2 instances

    • 2-port (CPSW2G) in MCU domain (MCU_CPSW0)

    • 9-port (CPSW9G) switch (MAIN_CPSW1) in main domain.

Note

CPSW instance is commonly referred with number of ports suffixed to the CPSW. 2, 5, and 9 port instances are referred to as CPSW2G, CPSW5G, and CPSW9G, respectively.

8.5.2. CPSW Support Software

  • Ethernet firmware (EthFw) is software running on main domain R5 for control and configuration of CPSW9G instance. As CPSW9G is a shared resource, the EthFw co-ordinates and manages resources between these cores and facilitates the configuration using Enet LLD.

  • Enet LLD is low level driver residing in the PDK. It supports CPSW2G and CPSW9G IPs and provides HAL layer for higher level stacks. EthFw uses Enet LLD for CPSW9G switch configuration.

  • TCP/IP Stack - lwIP stack is the only TCP/IP stack supported starting with SDK 8.1.

    • lwIP network interface driver (lwipif) is adaptation layer connecting Enet LLD to lwIP stack. This lwIP adaptation layer is part of Enet LLD and enables using CPSW2G and CPSW9G with lwIP TCP/IP applications.

  • gPTP Stack - PDK includes gPTP stack used mainly to validate and demonstrate time synchronization integration with CPSW.

  • Virtual CPSW MAC driver which implements standard Linux netdev interface and uses RPC services provided by rpmsg-kdrv Eth switch device which provides RPC interface to the Eth switch firmware running on the one of R5F cores and fully controls CPSW9G hardware module. The name of this virtual CPSW MAC driver is j721e_virt_mac.

    Supported features:

    • ifconfig dev up/down

    • ifconfig dev <IP>

    • ifconfig dev hw ether <MAC> – only when interface is down

    • ethtool -k dev

The following block diagram shows the relevant components of the Ethernet Firmware which runs on the Main R5F core.

_images/EthFw_components.png

The scope of this developer note is to point to various documentation and source code resources available within the SDK (RTOS and Linux) to understand and use CPSW2G using Enet LLD & CPSW9G using EthFw in a user application.

8.5.3. Documentation References

SDK Component

Documentation

Description

Section

EthFw

LINK

EthFw introduction and architecture review

EthFw training

EthFw

LINK

EthFw API guide

API guide

EthFw

LINK

EthFw user guide

User guide

EthFw

LINK

EthFw demos

Demos user guide

PDK

LINK

Enet API guide

Enet Driver

PDK

LINK

Enet Module User’s Guide - driver, examples

Full document

PDK

LINK

Enet Integration Guide - further details about Enet LLD initialization

Full document

PDK

LINK

lwIP network interface User’s Guide and Migration Guide

Full document

PDK

LINK

PHY integration guide - to help integrating new PHY with Enet LLD

Implementing a New PHY Driver

PDK

LINK

Link Configuration Guidelines

Link Configuration Guidelines

PSDK LINUX

${PSDK_LINUX_PATH}/docs/linux/index.html

CPSW9G virtual mac driver user guide

Foundational Components > Kernel > Kernel Drivers

8.5.4. Source Code References

8.5.4.1. Enet LLD

SDK Component

File / Folder

Description

PDK

pdk/packages/ti/drv/enet/enet.h

Enet LLD interface for CPSW2G and CPSW9G

PDK

pdk/packages/ti/drv/enet/include/phy/enetphy.h

PHY LLD driver interface

PDK

pdk/packages/ti/drv/enet/lwipif/inc/lwipif2enet_appif.h

App interface of the Enet-based lwIP network interface driver

PDK

pdk/packages/ti/drv/board/

Board drivers for CPSW9G GESI board

8.5.4.2. lwIP

SDK Component

File / Folder

Description

PDK

pdk/packages/ti/transport/lwip/lwip-stack/src/include

lwIP TCP/IP header files

PDK

pdk/packages/ti/transport/lwip/lwip-contrib/apps

lwIP contrib application header files

8.5.4.3. EthFw

SDK Component

File / Folder

Description

EthFw

ethfw/ethremotecfg/protocol/rpmsg-kdrv-transport-ethswitch.h

EthFw remote config protocol interface

EthFw

ethfw/ethremotecfg/server/include/ethremotecfg_server.h

EthFw RTOS configuration server interface

EthFw

ethfw/ethremotecfg/client/include/ethremotecfg_client.h

EthFw RTOS configuration client interface

PDK

pdk/packages/ti/drv/enet/enet_cfgserver/enet_cfgserver.h

CPSW configuration tool (GUI) interface

8.5.4.4. Platform CPSW Virtual MAC

SDK Component

File / Folder

Description

PSDK_LINUX

${PSDK_LINUX_KERNEL_PATH}/drivers/net/ethernet/ti/j721e-cpsw-virt-mac.c

J721E CPSW Virtual MAC driver

8.5.4.5. Demo applications for EthFw

SDK Component

File / Folder

Decription

PDK

pdk/packages/ti/drv/enet/examples/enet_loopback_test

CPSW2G/9G internal loopback example on all supported cores (mcu2_0, mcu1_0, mcu2_1)

PDK

pdk/packages/ti/drv/enet/examples/enet_lwip_example

lwIP integration example for CPSW2G/9G. Supported core (mcu2_0, mcu1_0, mcu2_1)

EthFw

ethfw/apps/app_remoteswitchcfg_server

This is switch Firmware. Hosts EthFw resource manager & remote config library. Also runs cpsw config tool server.

EthFw

ethfw/apps/app_remoteswitchcfg_client

EthFw remote client on mcu2_1. Uses remote client to communicate to EthFw and get CPSW9G resources allocated to mcu2_1

8.5.5. EthFw boot flow

  • In PSDK LINUX and PSDK RTOS when Linux is used on A72, R5 SPL (tiboot3.bin) loads EthFw (/lib/firmware/j7-main-r5f0_0-fw). Linux Kernel late attaches with EthFw via remote proc.

  • In PSDK RTOS, EthFw running on mcu2_0 can also be booted by TI SBL.

8.5.6. Getting started on CPSW & EthFw

  • Refer to Enet module documentation [LINK] for information about Enet LLD key APIs and the Examples section for available examples on this platform.

  • Refer to Enet LLD integration guide [LINK] for a further details about the initialization of an Ethernet peripheral via Enet LLD.

8.5.6.1. Configuring Ethernet port mode

Based on your board configuration, port can be in RMII, RGMII etc. mode. You need to do below to configure port in required mode.

  • Configure port ENET control to required mode using board library.

  • Configure CPSW interface.

    For RMII, it should be configured to below:

    interface->layerType    = ENET_MAC_LAYER_MII;
    interface->sublayerType = ENET_MAC_SUBLAYER_REDUCED;
    interface->variantType  = ENET_MAC_VARIANT_NONE;
    

    For RGMII, it should be configured to below:

    interface->layerType    = ENET_MAC_LAYER_GMII;
    interface->sublayerType = ENET_MAC_SUBLAYER_REDUCED;
    interface->variantType  = ENET_MAC_VARIANT_NONE;
    

    For SGMII (1Gbps) or XAUI (2.5Gbps), it should be configured to below:

    interface->layerType    = ENET_MAC_LAYER_GMII;
    interface->sublayerType = ENET_MAC_SUBLAYER_SERIAL;
    interface->variantType  = ENET_MAC_VARIANT_NONE;
    

    For USXGMII (5 or 10Gbps) on the supported SoCs, it should be configured to below:

    interface->layerType    = ENET_MAC_LAYER_XGMII;
    interface->sublayerType = ENET_MAC_SUBLAYER_SERIAL;
    interface->variantType  = ENET_MAC_VARIANT_NONE;
    

8.5.6.2. Run Enet loopback example

  • We recommend running Enet loopback example first as this doesn’t have any dependency on board/EVM set up

  • See PDK user guide [LINK], section Build Steps for build steps

8.5.6.3. Run Enet lwIP example (TCP/IP example)

  • Once loopback example is run, you can run enet_lwip_example which uses lwIP stack for TCP/IP applications.

  • You need to connect EVM to PC running DHCP server. You should see IP printed on UART after running the example. The PDK Enet examples uses UART based on core it is running. Refer to PDK documentation for core-to-UART mapping. If you want to use static IP configuration, edit enet_lwip_example/lwipcfg.h to enable static IP.

  • You can ping to board using this IP address

  • You can also run iperf2 test (Enet LLD app is server, external PC is client).

8.5.6.4. Integrate new PHY in Enet

  • You need to add new PHY driver if existing PHY drivers present in enet/src/phy/* does not support PHY present on your Board.

  • Refer to PHY integration guide [LINK] which has details for adding support for new PHY in Enet LLD.

8.5.6.5. Modify the examples to support your board configuration

  • Modify examples to change PHY address, speed (10M/100M/1G etc.) setting, mode (RMII/RGMII etc.) settings.

  • Rebuild the example and run on your board. You should be able to see data transfer happening.

8.5.6.6. Use of GEL files for debug and diagnostics

  • Enet LLD includes debug and diagnostics gel files to help in integrating the CPSW in your app.

  • The gel files are present in the pdk/packages/ti/drv/enet/tools/debug_gels

    1. cpsw_stats_print_regs.gel - prints non-zero statistics for CPSW

    2. cpsw_mdio_config.gel - can be used to read/write PHY registers

    3. cpsw_ale_print_table.gel - prints all entries of ALE table

    4. cpsw_enetctrl_cfg.gel - makes sure that board mode matches the configured mode.

8.5.6.7. Using Linux Platform Virtual MAC

The virtual mac driver on Linux is auto loaded during the kernel boot. It is currently configured in DHCP mode so it acquires an IP via DHCP server running on PC connected to CPSW9G ports. To get an IP address of virtual mac driver, run “ifconfig”:

root@j7-evm:~# ifconfig

eth0      Link encap:Ethernet  HWaddr 50:51:A9:FB:F4:2E
          inet addr:172.24.190.24  Bcast:172.24.191.255  Mask:255.255.252.0
          inet6 addr: fe80::5251:a9ff:fefb:f42e/64 Scope:Link
          UP BROADCAST RUNNING MULTICAST  MTU:1500  Metric:1
          RX packets:1327 errors:0 dropped:120 overruns:0 frame:0
          TX packets:215 errors:0 dropped:0 overruns:0 carrier:0
          collisions:0 txqueuelen:1000
          RX bytes:177194 (173.0 KiB)  TX bytes:21218 (20.7 KiB)

eth1      Link encap:Ethernet  HWaddr 70:FF:76:1D:87:95
          inet addr:192.168.1.31  Bcast:192.168.1.255  Mask:255.255.255.0
          inet6 addr: fe80::72ff:76ff:fe1d:8795/64 Scope:Link
          UP BROADCAST RUNNING MULTICAST  MTU:1500  Metric:1
          RX packets:2 errors:0 dropped:0 overruns:0 frame:0
          TX packets:56 errors:0 dropped:0 overruns:0 carrier:0
          collisions:0 txqueuelen:1000
          RX bytes:684 (684.0 B)  TX bytes:10769 (10.5 KiB)

lo        Link encap:Local Loopback
          inet addr:127.0.0.1  Mask:255.0.0.0
          inet6 addr: ::1/128 Scope:Host
          UP LOOPBACK RUNNING  MTU:65536  Metric:1
          RX packets:2 errors:0 dropped:0 overruns:0 frame:0
          TX packets:2 errors:0 dropped:0 overruns:0 carrier:0
          collisions:0 txqueuelen:1000
          RX bytes:140 (140.0 B)  TX bytes:140 (140.0 B)

Below standard Linux command can be run on the virtual mac interface.

  • ifconfig dev up/down

  • ifconfig dev <IP>

  • ifconfig dev hw ether <MAC> – only when interface is down

  • ethtool -k dev