CPSW Integration Guide

Table of Contents

Introduction


Jacinto 7 SoC (System on Chip) from Texas Instruments is targeted to address various ADAS (Advanced Driver Assistance Systems), In-Vehicle Infotainment (IVI) and Gateway markets. These devices are intended to be used in surround view systems, radar systems, vehicle compute, gateway (CAN to Ethernet, Ethernet to Ethernet), firewall and packet filtering use-cases.

Jacinto 7 family devices offer networking functionality through the Gigabit Ethernet MAC (MCU_CPSW0) and the Gigabit Ethernet Switch (CPSW0) subsystems. They provide Ethernet packet communication between the connected port(s) and the System on Chip. The total number of ports include host port which is an internal port providing the packet streaming interface to the device internal cores. The external ports are MAC ports supporting Media Independent Interface (MII) like MII, Gigabit Media Independent Interface (GMII), Reduced Media Independent Interface (RMII), Reduced Gigabit Media Independent Interface (RGMII), Serial Gigabit Media Independent Interface (SGMII) and Quad Serial Gigabit Media Independent Interface (QSGMII). The MII modes supported vary based on device variant.

MCU_CPSW0 is a two-port CPSW switch instance: one MAC port and a CPPI DMA host port. It's commonly referred to as CPSW2G.

CPSW0 is an integrated Ethernet switch IP with nine-port: eight MAC ports and a CPPI DMA host port. This CPSW instance is referred to as CPSW9G throughout most documentation and code. The CPSW9G switch facilitates the transfer of data between external ports along with internal traffic. Any core of Jacinto 7 devices can transmit/receive data to/from the switch.

CPSW9G is a shared resource and the Ethernet Switch Firmware is the software running on Main domain R5F of Jacinto 7, used for configuration, coordination and management of CPSW9G resources between internal processing cores and external ports. The Ethernet Switch Firmware software is mainly based on the PDK CPSW low-level driver (CPSW LLD), but also relies on other PDK drivers like UDMA for data transfers to the internal processing cores.

CPSW as a replacement to External Switch


The diagram below show the comparison of a typical automotive system using an external switch and an MCU, with a similar system on Jacinto 7 with integrated Ethernet switch.

CPSW_External_Switch_Replacement.png
CPSW as Replacement to External Switch Block Diagram

Back To Top

Ethernet Switch Software Architecture


The diagram below shows the overall software architecture of the CPSW 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. The CPSW driver consists of several software submodules that mirror those of the CPSW hardware, like DMA, ALE, MAC port, host port, MDIO, etc. Additionally, the CPSW driver also includes PHY driver support as well as a resource manager to administrate the CPSW resources.

CPSW LLD relies on other PDK drivers like UDMA for data transfer to/from the CPSW host port to the other processing cores inside the Jacinto 7 devices. For the lower level access to the CPSW hardware register, the CPSW LLD relies on the Chip Support Library (CSL).

CPSW-Software_Architecture_Diagram.png
CPSW Software Architecture Block Diagram

Back To Top

Examples


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

CPSW loopback Test

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 CPSW9G hardware 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, 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.

CPSW 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 the CPSW 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 CPSW LLD and gets an IP address using the NDK stack and opens transmit and receive ports.

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

Where IP address refers to the address of the Jacinto 7 processing core running the example, R5F or A72.

Back To Top

Getting Familiar with CPSW LLD APIs


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

The main APIs of the CPSW LLD are the following:

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.

IOCTL Iinterface


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

The Cpsw_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:

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

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

Back To Top

Integrating CPSW LLD into User's Application


Developers who wish to add network connectivity to the applications running on Jacinto 7 SoC, will have to integrate CPSW LLD by following the below sequence.

Open Sequence

  1. Initialize the CPSW configuration parameters with default values using Cpsw_initParams()
  2. Cpsw_Config structure includes configuration of various CPSW submodules as follows:

    These parameters can be changed as needed for the application.

  3. Once done with the configuration of the parameters, the UDMA driver has to be opened using CpswAppUtils_udmaOpen() and the UDMA driver handle has to be added to CpswDma_Config.
  4. The print functions are to be configured by providing the function pointers into the CpswUtils_Prms as done below:
     utilsPrms.printFxn = UART_printf;
     utilsPrms.traceFxn = UART_printf;
     utilsPrms.phyToVirtFxn = &CpswAppUtils_phyToVirtFxn;
     utilsPrms.virtToPhyFxn = &CpswAppUtils_virtToPhyFxn;
    
  5. OSAL parameters are to be initialized using Cpsw_initOsalPrms().
  6. After all the parameters are configured, the CPSW module can be initialized using the Cpsw_init() API as follows:
     Cpsw_init(cpswType, &osalPrms, &utilsPrms);
    
  7. Now, the CPSW driver is to be opened using the Cpsw_open() API. If the module is opened successfully, the API will return a valid handle pointer to the CPSW driver.
  8. Once the open succeeds, the application should attach the core with the Resource Manager (RM) using an IOCTL. To use IOCTLs in CPSW, the application must have the following:
    • Valid handle to the driver
    • Core ID, which can be obtained using CpswAppSoc_getCoreId()
    • Valid CPSW module IOCTL command
    • Valid pointer to the IOCTL parameters
  9. Once the application attaches the core with CPSW Resource Manager (RM), the IOCTL call will return core key which has to be used in all further RM-related calls.
  10. A MAC address for the host port is to be obtained using CpswAppUtils_allocMac() and the corresponding entry in the ALE table can be added using CpswAppUtils_addHostPortEntry().
  11. Allocate memory Ring Accelerators, Ethernet packets, etc. CPSW examples use CpswAppMemUtils to take care of all memory allocation and freeing operations. The developer can take this as reference or can implement their own memory allocation functions.
  12. CpswPhy and CpswMacPort are to be configured as below:
    • MAC-PHY link:
      • Set the port number in Cpsw_OpenPortLinkInArgs structure.
      • Using Cpsw_initMacPortParams() and CpswAppBoardUtils_setPhyConfig(), initialize and setup the configuration parameters as required.
      • If loopback is to be enabled, set enableLoopback flag in MAC configuration to true. For loopback to be functional the secure flag in host port ALE entry must be set to false. The host port entry update can be done using the CPSW_ALE_IOCTL_ADD_UNICAST command.
      • Once all the MAC and PHY configurations are done, the ports can be opened by calling the CPSW_IOCTL_OPEN_PORT_LINK command.
      • Note: To enable RMII on CPSW9G, external 50 MHz RMII clock from PHY is used on SOC RMII_REF_CLOCK pin. On GESI board, this clock is connected as resistor R225 is not populated. To get RMII_50MHZ_CLK, resistor R225 needs to be populated. We need to move R226 to R225 on GESI board to get this clock.
    • MAC-to-MAC link:
  13. If all the above steps succeeded without any errors, the CPSW driver is opened successfully.
  14. Next, the DMA channels to enable data transfer are to be opened. It can be done using the below steps:
  15. Set the ALE port state to Forward state using CPSW_ALE_IOCTL_SET_PORT_STATE IOCTL command.
  16. Enable the host port of CPSW by calling the CPSW_HOSTPORT_IOCTL_ENABLE command.
  17. Check for all the PHY's alive status using the CPSW_MDIO_IOCTL_GET_ALIVE_STATUS command.
  18. Now that CPSW and UDMA are configured, the application can start the data transfer.
    • To transmit data from application:
    • To receive packets that are queued up in the CPSW hardware which are ready to be received by the application:

Back To Top

Close Sequence

  1. Disable the host port using the CPSW_HOSTPORT_IOCTL_DISABLE command
  2. Close the opened Tx Channel and Rx flow:
    • Close the Rx flow using CpswAppUtils_closeRxFlow()
    • Close the Tx Channel using CpswAppUtils_closeTxCh()
  3. Detach the core from CPSW Resource Manager using the CPSW_IOCTL_DETACH_CORE command
  4. Close the MAC ports that were opened earlier using the CPSW_IOCTL_CLOSE_PORT_LINK IOCTL command.
  5. CPSW driver can now be closed and de-initialized using Cpsw_close() and Cpsw_deinit()
  6. Finally, close the UDMA driver using CpswAppUtils_udmaclose()

Back To Top

Integrating NDK into User's application using CPSW NIMU


A template file to integrate NDK in an application is added into cpsw/docs/main_tirtos_template.c, the developer can take this as reference.

Back To Top


Copyright 2020, Texas Instruments Incorporated