 |
Ethernet Firmware
|
|
Ethernet Firmware
|
This user guide presents the list of features supported by the Ethernet Firmware (EthFw) and describes the steps required to build and run the EthFw demo applications.
For additional information about EthFw refer to EthFw Introduction.
The EthFw demos showcase the integration and usage of the Ethernet Firmware which provides a high-level interface for applications to configure and use the integrated Ethernet switch peripheral (CPSW9G).
The following sample applications are key to demonstrate the capabilities of the CPSW9G/CPSW5G hardware as well as the EthFw stack.
| Demo | Comments |
|---|---|
| L2 Switching | Configures CPSW9G switch to enable switching between its external ports |
| L2/L3 address based classification | Illustrates traffic steering to A72 (Linux) and R5F (RTOS) based on Layer-2 Ethernet header. iperf tool and web servers are used to demonstrate traffic steering to/from PCs connected to the switch |
| Inter-VLAN Routing (SW) | Showcases inter-VLAN routing using lookup and forward operations being done in SW (R5F). It also showcases low-level lookup and forwarding on top of Enet LLD |
| Inter-VLAN Routing (HW) | Illustrates hardware offload support for inter-VLAN routing, demonstrating the CPSW5G/CPSW9G hardware capabilities to achieve line rate routing without additional impact on R5F CPU load |
This demo showcases switching capabilities of the integrated Ethernet Switch (CPSW9G or CPSW5G) found in J721E or J7200 devices for features like VLAN, Multicast, etc. It also demonstrates lwIP (TCP/IP stack) integration into the EthFw.
This demo illustrates hardware and software based inter-VLAN routing. The hardware inter-VLAN routing makes use of the CPSW9G/CPSW5G hardware features which enable line-rate inter-VLAN routing without any additional CPU load on the EthFw core. The software inter-VLAN routing is implemented as a fall-back alternative.
The hardware inter-VLAN route demo exercises the CPSW ALE classifier feature, which is used per flow to characterize the route and configure the egress operation.
Available egress operations:
For further information, please refer to the Ethernet Firmware differentiating features demos demo application documentation.
| Feature | Comments |
|---|---|
| L2 switching | Support for configuration of the Ethernet Switch to enable L2 switching between external ports with VLAN, multi-cast |
| Inter-VLAN routing | Inter-VLAN routing configuration in hardware with software fall-back support |
| lwIP integration | Integration of TCP/IP stack enabling TCP, UDP. |
| Remote configuration server | Firmware app hosting the IPC server to serve remote clients like Linux Virtual MAC driver |
| Resource management library | Resource management library for CPSW resource sharing across cores |
Dependencies can be categorized as follows:
Please note that the dependencies vary depending on the intended use (e.g. for integration vs running demo applications only).
EthFw is supported on the boards/EVM listed below
There are four RGMII PHYs in the J721E GESI board as shown in the following image. They will be referred to as MAC Port 0, MAC Port 1, MAC Port 2 and MAC Port 3 throughout this document.
Please refer to the SDK Description for details about installation and getting started of J721E EVM.
Note: GESI expansion board is also available in J7200 EVM, but only one MAC port is routed to the CPSW5G in J7200, hence GESI board is not enabled and used by default in the Ethernet Firmware for J7200.
There is one QSGMII PHY in the Quad Port Eth expansion board as shown in the following image. It enables four MAC ports which will be referred to as MAC Port 0, MAC Port 1, MAC Port 2 and MAC Port 3 throughout this document.
Please refer to the SDK Description for details about installation and getting started of J7200 EVM.
Note: Quad Port Eth expansion board is also available in J721E EVM, but it's not enabled by default in the Ethernet Firmware for J721E.
Below listed dependencies are part of Processor SDK package.
Platform Development Kit (PDK) is a component within the Processor SDK RTOS which provides Chip Support Library (CSL), Low-Level Drivers (LLD), Boot, Diagnostics, etc.
The following sections list the PDK subcomponents that are required by the EthFw package.
Please refer to the Release Notes that came with this release for the compatible version of PDK/SDK.
Chip Support Library (CSL) implements peripheral register level and functional level APIs. CSL also provides peripheral base addresses, register offset, C macros to program peripheral registers.
EthFw uses CSL to determine peripheral addresses and program peripheral registers.
Unified DMA (UDMA) is an integral part of the Jacinto 7 devices and is in charge of moving data between peripherals and memory.
PDK includes an UDMA LLD which provides APIs that the Enet LLD relies on to send and receive packets to the CPSW's host port.
This is Ethernet driver module used to program the CPSW5G or CPSW9G (Switch) IP. EthFw receives commands/configuration from application and uses Enet LLD to configure CPSW5G/CPSW9G.
Enet LLD supports other Ethernet peripherals available in TI SoCs and provides a unified interface to program them.
lwIP is a free TCP/IP stack developed by Adam Dunkels at the Swedish Institute of Computer Science (SICS) and licensed under a modified BSD license (completely open-source).
The focus of the LwIP TCP/IP implementation is to reduce RAM usage while keeping a full scale TCP/IP stack thus making it suitable for our requirements.
LwIP supports the following features:
Starting in SDK 8.0, Ethernet Firmware has been migrated to lwIP stack. The actual integration of lwIP into J721E/J7200 devices is done through Enet LLD, which implements the lwIP netif driver interface.
The Enet LLD lwIP driver interface implementation can be located at: <pdk>/packages/ti/drv/enet/lwipif/src.
The lwIP configuration file (lwipopts.h) contains the lwIP stack features that are enabled by default in the Enet LLD driver implementation, such as TCP, UDP, DHCP, etc. It's located at <pdk>/packages/ti/drv/enet/lwipif/ports/freertos/include/lwipopts.h. User should also refer to this file if interested on enabling any of the different lwIP debug options.
The lwIP pool configuration file (lwippools.h) contains the different pools and their sizes required by the Enet LLD lwIP interface implementation. This file is located at <pdk>/packages/ti/drv/enet/lwipif/ports/freertos/include/lwippools.h.
Enet LLD lwIP interface implementation provides a hook to let application process a packet and indicate whether the packet needs additional handling (i.e. be passed to the lwIP stack) or if the packet can be recycled (i.e. already handled by the application).
This feature enables Ethernet Firmware to implement Proxy ARP functionality needed to respond to ARP Request packets on behalf of Ethernet Firmware's remote core clients as broadcast packets are passed exclusively to Main R5F core 0, not to each individual remote core.
Ethernet Firmware sets up a dedicated UDMA RX flow where packets that have ARP EtherType and broadcast destination MAC address are routed to. While lwIP interface is processing packets from this RX flow, it will call the packet processing function registered by Ethernet Firmware. Ethernet Firmware then checks if the packet is meant for any of its remote core clients, if so, it responds on its behalf and packet is recycled as it needs not be passed to lwIP stack. If the packet is not meant to any of the remote cores, it's simply passed to the lwIP stack, ARP request packets meant for Ethernet Firmware itself fall into this processing category.
Ethernet Firmware and its dependencies are part of the SDK, separate installation is not required.
Post installation of SDK, the following directory would be created. Please note that this is an indicative snap-shot, modules could be added/modified.
The top-level EthFw makefile as well as the auxiliary makefiles for build flags (ethfw_build_flags.mak) and build paths (ethfw_tools_path.mak) can be found at the EthFw top-level directory.
The utils directory contains miscellaneous utilities required by the EthFw applications.
Source code of the EthFw demo applications is in the apps directory. For instance, below image shows the directory structure of the server application which implements L2 switch, inter-VLAN routing, etc.
Pre-compiled binaries are also provided as part of the EthFw release, which can be found in the out directory. For instance, below image shows the EthFw output directory structure with pre-compiled server and client binaries.
Refer to EthFw Demo Applications section for a full list of EthFw demo applications.
EthFw employs Concerto makefile-based build system. When building on a Windows based machine, tools such as Cygwin could be used.
The tool paths required by the build system are defined in the ethfw_tools_path.mak makefile. The default paths in ethfw_tools_path.mak are defined based on the assumption that the EthFw package has been installed inside the Processor SDK main directory.
Typically, the Processor SDK installation path is ~/ti in Linux-based systems. So, a typical EthFw installation would be at ~/ti/ti-processor-sdk-rtos-j721e-evm-08_xx_yy_zz. In this case, no additional environment setup steps are required.
If either Processor SDK or EthFw have been installed at different locations that those mentioned in previous paragraph, the following variables can be passed to the make command:
make <target> PSDK_PATH=<Processor SDK installation path> ETHFW_PATH=<EthFw installation path>
Please refer to the Build and Clean sections for a list of recommended targets. Alternatively, run the following command to get the full list of valid targets:
make help
The make commands listed below require the environment setup according to Setup Environment section.
Build EthFw components as well as its dependencies, including PDK, lwIP, etc.
make ethfw_all BUILD_SOC_LIST=J721E
or
make ethfw_all BUILD_SOC_LIST=J7200
Verbose build can be enabled by setting the SHOW_COMMANDS variable as shown below:
make ethfw_all BUILD_SOC_LIST=<SOC> SHOW_COMMANDS=1
On successful compilation, the output folder would be created at <ethfw>/out.
Build EthFw components for QNX OS integration running on A72.
make ethfw_all BUILD_SOC_LIST=<SOC> BUILD_QNX_A72=yes
For QNX integration, the BUILD_QNX_A72 flag will make sure that EthFW would not load the IPC resource table, unlike in Linux.
When building for Linux, the BUILD_QNX_A72 can be omitted.
The make commands listed below require the environment setup according to Setup Environment section.
Clean EthFw components as well as its dependencies:
make ethfw_all_clean
Remove EthFw build output directory only.
make scrub
make ethfw_all BUILD_SOC_LIST=<SOC> PROFILE=debug
make ethfw_all BUILD_SOC_LIST=<SOC> PROFILE=release
The example applications use different memories and this could be changed and/or re-configured via linker command files.
<ethfw_xx_yy_zz_bb>/apps/app_<name>/<core>/linker_mem_map.cmd<ethfw_xx_yy_zz_bb>/apps/app_<name>/<core>/linker.cmdRefer to EthFw Demo Applications section for a full list of EthFw demo applications.
For detailed steps to load and run the demo application, please refer to the Demo Setup section.
Delete the complete ethfw_xx_yy_zz_bb folder.
Please refer to the Ethernet Firmware Release Notes.
| Flag | Description |
|---|---|
-g | Default behavior. Enables symbolic debugging. The generation of debug information do not impact optimizations. Therefore, generating debug information is enabled by default. |
--endian=little | Little Endian |
-mv=7R5 | Processor Architecture Cortex-R5 |
--abi=eabi | Application binary interface - ELF |
-eo=.obj | Output Object file extension |
--float_support=vfpv3d16 | VFP co-processor is enabled |
--preproc_with_compile | Continue compilation after using -pp<X> options |
-D=TARGET_BUILD=2 | Identifies the build profile as 'debug' |
-D_DEBUG_=1 | Identifies as debug build |
-D=SOC_J721E | Identifies the J721E SoC type |
-D=J721E | Identifies the J721E device type |
-D=SOC_J7200 | Identifies the J7200 SoC type |
-D=J7200 | Identifies the J7200 device type |
-D=R5F="R5F" | Identifies the core type as ARM R5F |
-D=ARCH_32 | Identifies the architecture as 32-bit |
-D=SYSBIOS | Identifies as TI RTOS operating system build |
-D=FREERTOS | Identifies as FreeRTOS operating system build |
| Flag | Description |
|---|---|
--endian=little | Little Endian |
-mv=7R5 | Processor Architecture Cortex-R5 |
--abi=eabi | Application binary interface - ELF |
-eo=.obj | Output Object file extension |
--float_support=vfpv3d16 | VFP co-processor is enabled |
--preproc_with_compile | Continue compilation after using -pp<X> options |
--opt_level=3 | Optimization level 3 |
--gen_opt_info=2 | Generate optimizer information file at level 2 |
-D=TARGET_BUILD=1 | Identifies the build profile as 'release' |
-DNDEBUG | Disable standard-C assertions |
-D=SOC_J721E | Identifies the J721E SoC type |
-D=J721E | Identifies the J721E device type |
-D=SOC_J7200 | Identifies the J7200 SoC type |
-D=J7200 | Identifies the J7200 device type |
-D=R5F="R5F" | Identifies the core type as ARM R5F |
-D=ARCH_32 | Identifies the architecture as 32-bit |
-D=SYSBIOS | Identifies as TI RTOS operating system build |
-D=FREERTOS | Identifies as FreeRTOS operating system build |
| Device Family | Variant | Known by other names |
|---|---|---|
| Jacinto 7 | J721E, J7200 | - |
| Revision | Date | Author | Description |
|---|---|---|---|
| 0.1 | 01 Apr 2019 | Prasad J, Misael Lopez | Created for v.0.08.00 |
| 0.2 | 02 Apr 2019 | Prasad J | 0.8 Docs review meeting fixes |
| 0.3 | 12 Jun 2019 | Prasad J | Updates for EVM demo (.85 release) |
| 0.4 | 17 Jul 2019 | Misael Lopez | Updates for v.0.09.00 |
| 0.5 | 15 Oct 2019 | Misael Lopez, Santhana Bharathi | Updates for v.1.00.00 |
| 1.0 | 28 Jan 2020 | Misael Lopez | Updates for SDK 6.02.00 |
| 1.1 | 31 Aug 2020 | Misael Lopez | Added J7200 support for SDK 7.01 EA |
| 1.2 | 02 Nov 2020 | Misael Lopez | Updated for Enet LLD migration |
1.8.15