 |
MCUSW
|
|
MCUSW
|
This document details AUTOSAR BSW ETH module implementation when ETH driver is configured to operate in virtual mac mode
The ETH module is documented in the ETH module user guide.[3] This user guide complements the ETH module user guide and documents the virtual mac mode operation of the ETH module. The ETH module user guide should be read in its entirety before reading this user guide.
Following section provides background info on the virtual MAC mode.
The J721E and J7200 SoC includes an integrated Ethernet switch called Common Platform Switch (CPSW). CPSW supports multiple external MAC ports and one host port. CPSW in J721E has 8 MAC ports and CPSW in J7200 has 4 MAC ports.
Applications running on different cores in the Jacinto 7 SoC send and receive Ethernet frames via the host port. Applications running on different cores can simultaneously transmit to / receive from host port. In order to transmit and receive frames, an application on a core requires the following:
As illustrated above there exits direct data path to CPSW switch host port from all cores
As illustrated previously, there is designated master core. All CPSW configuration is exclusively done from this master core. The master core (called switch R5) is responsible for managing the pool of free Tx DMA channels Rx flows, destination MAC addresses.
Any application running on remote core that wants to establish a data path must send an IPC message to the master core to allocate resources such as Tx channel, Rx flow, destination MAC address. Application running on remote must also send IPC message to master core for the following:
The master core runs a TI RTOS application called Ethernet Firmware.
Ethernet Firmware (ethfw) functionality:
The application running on remote core is said to operate in virtual MAC mode configuration.
The Ethernet Remote Device RPC Client is layer under the Ethernet Driver which uses CddIpc to send RPC msgs to the Ethernet Firmware and process the response. The Ethernet Firmware hosts a Ethernet Remote Device RPC Server service for servicing remote cores.
The Eth Driver uses the CddIpc MCAL to send msg to and recv msg from Ethernet Firmware.
Typical Eth Rpc sequence is illustrated below.
The rpcCmdComplete callback is a function pointer populated in Eth_ConfigType structure.
Application may choose to configure the Eth Driver to check for msgs to be processed in Eth_MainFunction(). In this case, it will regularly schedule calls to Eth_MainFunction() instead of invoking Eth_NotifyVirtmacMsgReceived() from CddIpcNewMessageNotify.
Ethernet MCAL APIs Eth_DispatchVirtmacXXX are asynchronous APIs that dispatch RPC msg to Ethernet Firmware. The application needs to wait for rpcCmdComplete callback as shown to determine completion of API and the status (SUCCESS/FAIL)
The data path setup sequence of the Ethernet Virtual MAC driver is as below.
The ETH driver in virtual MAC mode does not control any of the CPSW submodules like MAC/MDIO/ALE/STATS unlike the standard ETH driver.
The ETH driver in virtual MAC mode supports transmission and reception of packets like the ETH driver in non-virtual MAC mode. The ETH driver uses the UDMA driver APIs to setup data transfers to/from the host port.
The ETH driver implements single UDMA channel for data transmission and single rx flow for data reception. Interrupts can be enabled for DMA transmit and receive completion events.
The DMA transfers are based on descriptors called Host Mode Packet Descriptors (HMPD). The descriptors are given to and retrieved from the UDMA via Ring Accelerators. There are three rings used per data direction in this implementation:
The depth of each ring as well as its associated memory is configurable. The ring memories can be any memory in the system, but it's recommended that they are placed in a fast memory (i.e. OCMRAM or MSMC3). The depth of these rings is determined by the number of TX and RX buffers set in the driver configuration (EthTxBufTotal and EthRxBufTotal).
Similarly, the HMPDs can be placed in any memory of the system, but it's recommended that they are placed in OCMRAM or MSMC3 as well.
The following table lists the mapping between Ethernet interrupts and the corresponding interrupt service routines.
| Interrupt Number | Description | Associated ISR |
|---|---|---|
| Configurable | DMA RX Completion | Eth_RxIrqHdlr_0 |
| Configurable | DMA TX Completion | Eth_TxIrqHdlr_0 |
The DMA interrupt numbers can be set via the Ethernet driver configuration parameters dmaTxChIntrNum and dmaRxChIntrNum.
The interrupt numbers passed to the Ethernet driver configuration must be within the range allocated for the core by the Udma LLD resource manager, otherwise the interrupt allocation will fail while enabling the Ethernet controller.
Please refer to the UDMA Driver Resource Manager allocation for further details.
In virtual MAC mode, the ETHTRCV module should not be used as the PHY management is under ownership of Ethernet Firmware.
The Eth Driver implementation in this release only supports the Pre-Compile variant. The driver expects generated Eth_Cfg.h and Eth_Cfg.c to be present at the locations specified in the Eth File Structure section.
APIs not support by the Eth Drvier in non-virtual MAC mode mentioned in Eth Driver user guide [3] are not supported in virtual MAC mode as well. Additionally the following APIs are not supported in virtual MAC mode
The reason for having a new set of Eth_DispatchVirtmacXXX instead of invoking the RPC APIs inside the existing Eth_UpdatePhysAddrFilter API is as follows:
As the RPC APIs are asynchronous dispatch APIs it is not possible to abstract their calls from the Eth Driver Client by invoking the APIs within an existing API, such as Eth_UpdatePhysAddrFilter(). It would require blocking in the API until response from Ethernet Firmware is received. Blocking would abstract the Ethernet Client from virtual MAC / native MAC mode operation but would pose problems with error handling, hence a new set of APIs which must be explicitly invoked by the Ethernet Driver Client have been implemented.
As explained in the section Functional Description, the depth of Rx and Tx DMA queues is determined by the number of TX and RX buffers set in the driver configuration (EthTxBufTotal and EthRxBufTotal).
As per AUTOSAR spec [1] the maximum value of EthTxBufTotal and EthRxBufTotal is 255. However the UDMA supports a buffer depth of upto 1048575 entries (2^20 - 1) To support usecases that require queue depth greater that 255 buffers, the MCAL configurator for ETH module allows greater than 255 buffers for EthTxBufTotal and EthRxBufTotal.
Ethernet Transceiver should not be used in virtual MAC mode of the Ethernet Driver Hence none of the API of Ethernet Transceiver are supported.
The following vendor specific extension APIs are supported in virtual MAC mode
Refer the Ethernet driver API guide for details of these APIs
The Ethernet driver doesn't register any interrupt handlers (ISR), it is expected that consumer of this driver registers the required interrupt handler.
The Ethernet interrupts are:
Other CPSW interrupts (like the Statistics Pending interrupt, MDIO interrupt) are not handled by the driver.
Please refer to the EthApp_InterruptConfig() function in Eth virtual MAC demo application for the implementation details of the interrupt registration.
The driver doesn't configure the functional clock and power for the Ethernet module. It is expected that the Secondary Bootloader (SBL) powers up the required modules. Please refer SBL documentation.
Example application to illustrate use of Eth Driver in virtual MAC mode is included in mcal examples.
Example app name: eth_virtmac_app Source code : ${MCUSW}/mcal_drv/mcal/examples/Eth/eth_app/target/EthVirtmacApp.c
** J721E ** Eth Driver Configuration: mcal_drv/mcal/examples_config/Eth_Demo_Cfg/output/generated/soc/j721e/mcu2_1 CddIpc Driver Configuration: mcal_drv/mcal/examples_config/CddIpc_Demo_Cfg/output/generated/soc/j721e/mcu2_1
** J7200 ** Eth Driver Configuration: mcal_drv/mcal/examples_config/Eth_Demo_Cfg/output/generated/soc/j7200/mcu2_1 CddIpc Driver Configuration: mcal_drv/mcal/examples_config/CddIpc_Demo_Cfg/output/generated/soc/j7200/mcu2_1
The steps to build the virtual MAC mode application:
** J721E **
$ cd mcusw/build/ $ make eth_virtmac_app CORE:=mcu2_1 BOARD:=j721e_evm
** J7200 **
$ cd mcusw/build/ $ make eth_virtmac_app CORE:=mcu2_1 BOARD:=j7200_evm
The example binary will be available at:
** J721E **
mcusw/binary/eth_virtmac_app/bin/j721e_evm/eth_virtmac_app_mcu2_1_${build_profile}.xer5f
** J7200 **
mcusw/binary/eth_virtmac_app/bin/j7200_evm/eth_virtmac_app_mcu2_1_${build_profile}.xer5f
Note on the CddIpc Driver Configuration:
In this release, the application demonstrating virtual MAC mode of operation of the Eth Driver is supported only on mcu2_1 core.
The GCC compiler is required to build the host-side application.
The steps to build the host-side application in Linux are listed below:
$ cd mcal_drv/mcal/examples/Eth/eth_app/host/ $ make
Unlike the Eth example, virtual MAC mode application does not support internal loopback test. This is because the MAC needs to be configured for loopback mode and the MAC configuration is under control of Ethernet Firmware and cannot be configured from Ethernet driver in virtual MAC mode.
This test consists of two applications: host-side application that runs on a Linux machine, and a target-side application that is loaded to the device (DUT).
Please refer to the Building the host-side example application section for instructions to build the host-side application.
$ ifconfig -s
$ cd mcal_drv/mcal/examples/Eth/eth_app/host/ $ sudo ./EthHostApp -i eth2
The example applications on either side (host or target) will report a fail status if any test Ethernet frames is lost. So even frames which are lost due to physical link will cause the example application to report as a failure.
This implementation depends on the DET in order to report development errors and can be turned OFF. Refer to the Development Error Reporting section for detailed error codes.
This implementation requires 1 level of exclusive access to guard critical sections. Invokes SchM_Enter_Eth_ETH_EXCLUSIVE_AREA_0(), SchM_Exit_Eth_ETH_EXCLUSIVE_AREA_0() to enter critical section and exit.
In the example implementation (SchM_Eth.c), all the interrupts on CPU are disabled. However, disabling of the enabled Ethernet related interrupts should suffice.
Inorder to send Rpc messages to the Ethernet Firmware core, the CddIpc module is used by the Ethernet driver in virtual MAC mode. The IPC channel configuration to communicate with Ethernet Firmware is given below
{
.id = CddIpcConf_IpcComChanId_Cdd_IpcMcu20_EthDevice,
/**< Unique identifiers for a channel */
.localEp = 11U,
/**< Local End Point identifier, on which MCAL/AUTOSAR is hosted */
.remoteEp = 28U,
/**< Remote End Point identifier, on remote cores */
.remoteProcId = CDD_IPC_CORE_MCU2_0,
/**< Remote Processor Identifier */
.numMsgQueued = 256U,
/**< Number of buffer allocated to this communication channel */
.maxMsgSize = 512,
/**< Defines the pointer to memory */
.reserved = 0U,
/**< Future use if any */
},
It is required to initialize IPC (Cdd_IpcInit()) before Eth_init() is invoked.
Development errors are reported to the DET using the service Det_ReportError(), when enabled. The driver interface files Eth.h lists the service IDs.
Production error are reported to DET via Det_ReportError(). Only the error codes in the Ethernet and Ethernet Transceiver driver specifications are reported which are listed below. There are no implementation specific error codes being reported.
| Type of Error | Related Error code | Value (Hex) |
| Invalid controller index | ETH_E_INV_CTRL_IDX | 0x01 |
| Eth module was not initialized | ETH_E_UNINIT | 0x02 |
| Invalid pointer in parameter list | ETH_E_PARAM_POINTER | 0x03 |
| Invalid parameter | ETH_E_INV_PARAM | 0x04 |
| Initialization failure | ETH_E_INIT_FAILED | 0x05 |
| Invalid mode | ETH_E_INV_MODE | 0x06 |
| Mismatch in API version supported by Ethernet Firmware and Autosar Ethernet Driver | ETH_E_VIRTMAC_APIMISMATCH | 0x07 |
| Dispatch of Virtual MAC RPC command failed | ETH_E_VIRTMAC_RPCCMDFAILED | 0x08 |
| Ethernet MCAL RPC client received unhandled notify from Ethernet Firmware server | ETH_E_VIRTMAC_UNSUPPORTECLIENTNOTIFY | 0x09 |
| Rpc Command sent by client not supported by server | ETH_E_VIRTMAC_UNSUPPORTEDSRVCMD | 0x0A |
Production error are reported to DEM via the service DEM_ReportErrorStatus(). There are no implementation specific error codes being reported. Only the error codes in the Ethernet and Ethernet Transceiver driver specifications are reported which are listed below.
| Type of Error | Related Error code |
| Ethernet Controller Access Failure | ETH_E_ACCESS |
| Ethernet Frames Lost | ETH_E_RX_FRAMES_LOST |
| CRC Failure | ETH_E_CRC |
| Frame Size Underflow | ETH_E_UNDERSIZEFRAME |
| Frame Size Overflow | ETH_E_OVERSIZEFRAME |
| Frame Alignment Error | ETH_E_ALIGNMENT |
| Single Frame Collision | ETH_E_SINGLECOLLISION |
| Multiple Frame Collision | ETH_E_MULTIPLECOLLISION |
| Late Frame Collision | ETH_E_LATECOLLISION |
The AUTOSAR BSW Eth Driver specification details the APIs [1].
The additional vendor specific APIs for virtual MAC mode are documented in the API guide The APIs not supported in virtual MAC mode are documented at Ethernet APIs Not Supported
The example application demonstrate use of Eth module in virtual MAC mode.
The example consists of an application that runs on the J721E or J7200 device (DUT) and an application that runs on a Linux PC (host). The host and target (DUT) applications communicate with each other to start the different stages of the example tests.
The Eth example relies on shared utils which provide helper functions (i.e. filling an Ethernet frame with test data, verifying frame contents, etc) which are useful on the DUT and host sides.
The following table summarizes the different tests implemented by the example application.
| Test ID | Summary | Description |
| test_0001 | Basic DUT frame reception | Host will send 1000 Ethernet frames, the DUT will receive and verify that the frame content matches the expected patterns |
| test_0002 | Basic DUT frame transmission | The DUT will send 1000 non-VLAN tagged frames without TX confirmation. The host PC will check that all frames are received and that the frame content matches the expected patterns |
| test_0003 | External loopback | The DUT will send frames to the host, the host will receive the frames and will send them back to the DUT |
| test_0004 | Default filter operation | Host will send 500 frames with DUT's MAC address and 500 frames with other MAC address. The DUT will reject the 500 frames that don't matches DUT's address |
| test_0005 | Different filter configurations | This test is split in different stages that will exercise different filter operations like adding/removing unicast address. The virtual MAC mode does not support promiscouse mode as that would involve changing the switch configuration affection other clients. |
| test_0006 | DUT frame transmission with confirmation | The DUT will send 1000 non-VLAN tagged frames and will request TX confirmation. The host PC will check that all frames are received and that the frame content matches the expected patterns. |
| test_0007 | Transmission of VLAN tagged frames | The DUT will send 1000 VLAN tagged frames and will request TX confirmation. The host PC will check that all frames are received and that the frame content matches the expected patterns |
| test_0008 | Transmission of different frame lengths | The DUT will send non-VLAN tagged frames of different lengths, including short frames. The host PC will check that all frames are received and that the frame content matches the expected patterns |
| test_0009 | VLAN tagged frame reception | Host will send 1000 VLAN tagged Ethernet frames, the DUT will receive and verify that the frame content matches the expected patterns |
| test_0010 | Controller mode changes | The application will set the controller to DOWN mode and then back to ACTIVE mode. Ethernet frame transmission and reception tests will be run afterwards. 10 iterations of these steps will be executed. |
| test_0100 | Transmit throughput | DUT transmit throughput is measured over 150,000 Ethernet frames sent from the host PC. |
The following list identifies key steps performed by the DUT side application:
The host application steps are not presented in this guide, but can be found documented in the host side code. Please refer to the File Structure section for the directory where the HostApp.c file can be found.
The configuration files are present can be found at the directories shown in the File Structure section.
[MAIN_Cortex_R5_0_1] Eth Application Starts CDD IPC MCAL Version Info --------------------- Vendor ID : 44 Module ID : 255 SW Major Version : 9 SW Minor Version : 0 SW Patch Version : 0 MAC Port 1 Address: 70:ff:76:1d:92:c1 Waiting for Host.. No Response from Host, remaining retry = 100 Host App detected! Sending Read ACK CMD... ----------------------------------------------------------- test_0001: START test_0001: received 1000 of 1000 frames test_0001: END Test Result: Pass ----------------------------------------------------------- ----------------------------------------------------------- test_0002: START test_0002: END Test Result: Pass ----------------------------------------------------------- ----------------------------------------------------------- test_0003: START test_0003: END Test Result: Pass ----------------------------------------------------------- ----------------------------------------------------------- test_0004: START test_0004: received 500 of 500 frames test_0004: END Test Result: Pass ----------------------------------------------------------- ----------------------------------------------------------- test_0005: START test_0005: Null: Exp1: exp 500, got 500 test_0005: Null: Exp2: exp 0, got 0 test_0005: Ucast: Exp1: exp 500, got 500 test_0005: Ucast: Exp2: exp 500, got 500 test_0005: Mcast: Exp1: exp 500, got 500 test_0005: Mcast: Exp2: exp 500, got 500 test_0005: Mcast: Exp1: exp 500, got 500 test_0005: Mcast: Exp2: exp 0, got 0 test_0005: Bcast: Exp1: exp 500, got 500 test_0005: Bcast: Exp2: exp 500, got 500 test_0005: Null: Exp1: exp 500, got 500 test_0005: Null: Exp2: exp 0, got 0 test_0005: END Test Result: Pass ----------------------------------------------------------- ----------------------------------------------------------- test_0006: START test_0006: END Test Result: Pass ----------------------------------------------------------- ----------------------------------------------------------- test_0007: START test_0007: END Test Result: Pass ----------------------------------------------------------- ----------------------------------------------------------- test_0008: START test_0008: END Test Result: Pass ----------------------------------------------------------- ----------------------------------------------------------- test_0009: START test_0009: received 1000 of 1000 frames test_0009: END Test Result: Pass ----------------------------------------------------------- ----------------------------------------------------------- test_0010: START EthApp_CtrlModeIndication: DOWN EthApp_CtrlModeIndication: ACTIVE test_0002: START test_0002: END test_0001: START test_0001: received 1000 of 1000 frames test_0001: END EthApp_CtrlModeIndication: DOWN EthApp_CtrlModeIndication: ACTIVE test_0002: START test_0002: END test_0001: START test_0001: received 1000 of 1000 frames test_0001: END EthApp_CtrlModeIndication: DOWN EthApp_CtrlModeIndication: ACTIVE test_0002: START test_0002: END test_0001: START test_0001: received 1000 of 1000 frames test_0001: END EthApp_CtrlModeIndication: DOWN EthApp_CtrlModeIndication: ACTIVE test_0002: START test_0002: END test_0001: START test_0001: received 1000 of 1000 frames test_0001: END EthApp_CtrlModeIndication: DOWN EthApp_CtrlModeIndication: ACTIVE test_0002: START test_0002: END test_0001: START test_0001: received 1000 of 1000 frames test_0001: END EthApp_CtrlModeIndication: DOWN EthApp_CtrlModeIndication: ACTIVE test_0002: START test_0002: END test_0001: START test_0001: received 1000 of 1000 frames test_0001: END EthApp_CtrlModeIndication: DOWN EthApp_CtrlModeIndication: ACTIVE test_0002: START test_0002: END test_0001: START test_0001: received 1000 of 1000 frames test_0001: END EthApp_CtrlModeIndication: DOWN EthApp_CtrlModeIndication: ACTIVE test_0002: START test_0002: END test_0001: START test_0001: received 1000 of 1000 frames test_0001: END EthApp_CtrlModeIndication: DOWN EthApp_CtrlModeIndication: ACTIVE test_0002: START test_0002: END test_0001: START test_0001: received 1000 of 1000 frames test_0001: END EthApp_CtrlModeIndication: DOWN EthApp_CtrlModeIndication: ACTIVE test_0002: START test_0002: END test_0001: START test_0001: received 1000 of 1000 frames test_0001: END test_0010: completed 10 of 10 iterations test_0010: END Test Result: Pass ----------------------------------------------------------- ----------------------------------------------------------- test_0100: START test_0100: 150000 frames sent test_0100: END Test Result: Pass ----------------------------------------------------------- ETH Stack Usage: 1784 bytes Final Tests Results: PASS Eth Application Completed
| Sl No | Specification | Comment / Link |
|---|---|---|
| 1 | AUTOSAR 4.3.1 | AUTOSAR Specification for Eth Driver Intranet Link |
| 2 | - | Design Page (Eth Design Document) |
| 3 | - | Eth User Guide (Eth & EthTrcv User Guide) |
| Revision | Date | Author | Description | Status |
|---|---|---|---|---|
| 0.1 | 14 Feb 2020 | Badri S | First version | Pending Review |
| 0.2 | 29 May 2020 | Misael Lopez | Updated for AUTOSAR 4.3.1 | Approved |
| 0.3 | 04 Nov 2020 | Misael Lopez | Updated for SDK 7.1 | Approved |
1.8.15