MCUSW
Eth Design Document

Introduction

Overview

The figure below depicts the AUTOSAR layered architecture as 3 distinct layers, Application, Runtime Environment (RTE) and Basic Software (BSW). The BSW is further divided into 4 layers, Services, Electronic Control Unit Abstraction, MicroController Abstraction (MCAL) and Complex Drivers.

autosar_acrhitecture_common.png
AUTOSAR Architecture

MCAL is the lowest abstraction layer of the Basic Software. It contains software modules that interact with the Microcontroller and its internal peripherals directly. The ETH driver is part of the Communication Drivers module which is also part of the Basic Software. The block diagram below shows the position of the Ethernet driver in the AUTOSAR Architecture.

autosar_acrhitecture_eth.png
AUTOSAR Architecture – Eth MCAL

Eth Overview

As described in the AUTOSAR Ethernet Driver specification, the Ethernet Driver (Eth) is in charge of providing a uniform, hardware independent interface to the upper layer, the Ethernet Interface (EthIf). Thus, the Ethernet Interface may access the underlying bus system in a uniform manner.

The driver provides bus specific functionality for controller initialization, configuration, data transmission, data reception, statistics gathering, etc. A single Ethernet Driver module supports only one type of controller hardware, but several controllers of the same type. Figure below shows the lower part of the Ethernet stack.

eth_stack.png
Lower-level of the Ethernet stack

This Ethernet Driver implementation shall support an Ethernet controller based on the two-port Gigabit Ethernet Switch (CPSW) peripheral present in the MCU domain of the TDA4x family of devices.

Refer to the Ethernet Driver and Ethernet Interface specification in References section for more details on Eth operation.

Two-Port Gigabit Ethernet Switch

The TDA4x family of devices have an integrated the two-port Gigabit Ethernet Switch (CPSW) into the device MCU domain named MCU_CPSW0. Please refer to figure below for a block diagram of the peripheral.

Port 0 is the internal Communications Port Programming Interface (CPPI) host port. Port 1 is the Ethernet port which supports RGMII and RMII interfaces.

The CPSW peripheral natively supports features like IEEE 1588 Clock Synchronization, Address Lookup Engine (ALE), and Ethernet Statistics. Further information on these and several other features supported by the CPSW subsystem can be found in the device TRM.

eth_cpsw0_block.png
MCU_CPSW0 Block Diagram

Back To Top

References

Sl No Specification Comment / Link
1 AUTOSAR 4.3.1 AUTOSAR Specification for Eth Driver Internet Link
2 AUTOSAR 4.3.1 Specification of the Ethernet Interface Internet Link
3 AUTOSAR 4.3.1 BSW General Specification of Basic Software Modules Internet Link
4 AUTOSAR 4.3.1 List of Basic Software Modules, AUTOSAR Release Internet Link
5 TDA4x TRM Technical Reference Manual, TDA4X Ethernet module is detailed
6 BSW General Requirements / Coding guidelines Intranet Link
7 Software Product Specification (SPS) Intranet Link Requirements are derived from [1]
8 AUTOSAR 4.3.1 Specification of the Ethernet State Manager Internet Link

Requirements

The Eth driver shall implement as per requirements detailed in the Software Product Specification (SPS) [7], Ethernet Driver specification [1] and Basic Software Modules specification [3]. It’s recommended to refer to the Ethernet Driver specification [1] for any clarification.

The Eth driver shall follow coding guidelines listed in the BSW General Requirements and Coding Guidelines document [6].

Back To Top

Features Supported

Below listed are some of the key features that are expected to be supported

  • Ethernet controller initialization
  • Transmission and reception of Ethernet frames
  • Interrupt-based hardware error reporting
  • MDIO
  • Statistics gathering
  • Packet time-stamping (PTP)
  • VLAN tag
  • Hardware-based error detection (collisions, under/over-sized frames, CRC, etc)
Design ID DES_ETH_001
Requirements Covered SWS_Eth_00003, SWS_Eth_00004, SWS_Eth_00006, SWS_Eth_00007, SWS_Eth_00011, SWS_Eth_00026, SWS_Eth_00119, SWS_Eth_00148, SWS_Eth_00218

Configuration Requirements

Design ID DES_ETH_039
Requirements Covered SWS_Eth_00005, SWS_Eth_00010, SWS_Eth_00012, SWS_Eth_00013, SWS_Eth_00124, SWS_Eth_00125, SWS_Eth_00126

Back To Top

caution.png

Features Not Supported / NON Compliance

  • SWS_Eth_00238 and ECUC_Eth_00036 give different configuration parameter name to enable or disable Eth_GetRxStats. EthGetRxStatsApi name is assumed in this implementation.
  • Ethernet Switch interface APIs are not called by the driver.

Back To Top

Assumptions

Below listed are assumed to valid for this design/implementation, exceptions and other deviations are listed for each explicitly. Care should be taken to ensure these assumptions are addressed.

  1. The CPSW module is expected to be properly clocked before calling any Ethernet Driver API. The driver shall not perform any power and/or clock related configuration.
  2. The Ethernet driver shall not perform any pinmux related settings which are assumed to be done by other entities.
  3. The Ethernet driver shall rely on the UDMA driver/utility for all DMA related transactions which includes configuration and operation of the UDMAP-P, PSI-L, Ring Accelerator.
  4. The Ethernet driver shall only be responsible of enabling and handling interrupt sources on the CPSW side. ISR registration as well as MCU interrupt configuration shall be performed by other entities.

Back To Top

Design Description

The Ethernet driver shall not have dependency on any external component. The Ethernet driver shall maintain its own version of CSL, UDMA and CPSW helper functions.

  • CSL - CPSW register overlay and basic helper functions.
  • UDMA helper function - To configure and manage DMA transfers, abstracting the the complexity of the programming of the UDMA, Ring Accelerator, PSI-L, etc, from the top-level MCAL Ethernet implementation.
  • CPSW helper functions - To abstract functionality provided by CPSW sub-modules such as MAC port, host port, MDIO, ALE, etc.
eth_driver_block.png
CPSW Ethernet Driver Block Diagram

The data flow model of the AUTOSAR Ethernet driver requires that buffers are passed one by one to/from the upper layers. Additionally, there are a number of memory copy operations that need to take place in the lifecycle of packet buffer across the upper layers (i.e. UDP, RTP, etc). This Ethernet driver design aims to being able to scale the driver implementation for higher data throughput

Back To Top

Dynamic Behavior

The driver maintains the following three states: UNINIT, INIT and ACTIVE. Please refer to the sequence diagrams shown in the Specification of Ethernet State Manager [8], for further details on the interactions and transitions between those states.

Back To Top

Sequence Diagrams

The following sequence diagrams the data flow interactions between the EthIf, Eth and the proposed design. These sequence diagrams extended from the diagrams of the Ethernet Interface specification document [2].

Data Transmission

The sequence diagrams below list control / data flow for transmission in polling and interrupt methods.

eth_driver_seq_tx_poll.png
Data Transmission in Polling Mode
eth_driver_seq_tx_int.png
Data Transmission in Interrupt Mode

Back To Top

Data Reception

The sequence diagrams below list control / data flow for transmission in polling and interrupt methods.

eth_driver_seq_rx_poll.png
Data Reception in Polling Mode
eth_driver_seq_rx_int.png
Data Reception in Interrupt Mode

Back To Top

Directory Structure

The directory structure is as depicted in figures below, the source files can be categorized under “Driver Implementation” and “Example Application”

eth_driver_dir_spec.png
Directory Structure : Sourced from AUTOSAR Specification

Driver Implemented by

  • Eth.h and Eth_Irq.h: Shall implement the interface provided by the driver
  • Eth.c, Eth_Irq.c, Eth_Packet.c, Eth_Priv.h, Eth_Priv.c, Eth_Packet.h, Eth_Rpc.c, Eth_Rpc.h, Eth_RpcPriv.h, Eth_VirtMac.h, Eth_VirtMac.c, Eth_IrqPacing.h, Eth_IrqPacing.c: Shallimplement the driver functionality
  • Eth/src/cpsw : Shall implement internal module specifics functionalities
  • Eth/src/udma : Shall implement internal module specifics functionalities
  • Eth/src/csl : Shall implement internal module specifics functionalities
  • Eth/src/cpsw/include: Shall provide the internal module interfaces that shall be limited to the driver implementation.
  • Please note : The implementation shall provide a separate .c & .h for each sub-module of the cpsw.
eth_driver_dir.png
Detailed Directory Structure

Example Application

  • Host
    • HostApp.c: Shall implement host / PC based application variant
  • Target
    • EthApp.c: Shall implement MCAL Eth demo application, which demonstrates use of Eth driver in conjunction with Host Application.
  • Pre Compile Configuration
    • Provided by Eth_Cfg.h and Eth_Cfg.c Eth_Lcfg.c Eth_PBcfg.c
Design ID DES_ETH_002
Requirements Covered MCAL-2132

Back To Top

Interrupt Service Routines

The Ethernet Driver supports two data transfer related interrupts, one for transmission and another for reception. These interrupts are generated when the underlying completion queue rings (CQ Rings) associated with TX and RX get a descriptor from CPSW. For TX, this event signalizes that a previous transmission has completed and its descriptor is free to be reused. For RX, this event signalizes the arrival of new packet.

The Eth_RxIrqHdlr_0() interrupt service routine shall clear the interrupt and read the frames of all received buffers. This driver design takes into consideration the ability to receive several frames from the DMA engine. The driver shall call the Ethernet Interface callback function EthIf_RxIndication() on each received frame.

The Eth_TxIrqHdlr_0() interrupt service routine shall clear the interrupt and check all filled transmit buffers for successful transmission. The driver shall call the Ethernet Interface callback function EthIf_TxConfirmation() for each transmit frame, if requested.

The statistics interrupt is generated when any statistics value is greater than or equal to 0x80000000. The service routine for this interrupt shall clear the interrupt and update the statistics counter(s) accordingly. The intention of this event is to avoid overflow in the 32-bit wide statistics counter values in hardware.

Back To Top

Configurator

The AUTOSAR Eth Driver Specification details mandatory parameters that shall be configurable via the configurator. Please refer section 10 of the Ethernet driver specification listed in References section.

Design ID DES_ETH_024
Requirements Covered ECUC_Eth_00001, ECUC_Eth_00002, ECUC_Eth_00003, ECUC_Eth_00004, ECUC_Eth_00006, ECUC_Eth_00007, ECUC_Eth_00010, ECUC_Eth_00011, ECUC_Eth_00012, ECUC_Eth_00015, ECUC_Eth_00016, ECUC_Eth_00017, ECUC_Eth_00018, ECUC_Eth_00019, ECUC_Eth_00020, ECUC_Eth_00021, ECUC_Eth_00022, ECUC_Eth_00023, ECUC_Eth_00024, ECUC_Eth_00025, ECUC_Eth_00026, ECUC_Eth_00027, ECUC_Eth_00028, ECUC_Eth_00029, ECUC_Eth_00030, ECUC_Eth_00031, ECUC_Eth_00032, ECUC_Eth_00033, ECUC_Eth_00034, ECUC_Eth_00035, ECUC_Eth_00036, ECUC_Eth_00037, ECUC_Eth_00038, ECUC_Eth_00039, ECUC_Eth_00040, ECUC_Eth_00041, ECUC_Eth_00042, ECUC_Eth_00043, ECUC_Eth_00044, ECUC_Eth_00045, ECUC_Eth_00046, ECUC_Eth_00047, ECUC_Eth_00048, ECUC_Eth_00049, ECUC_Eth_00050, ECUC_Eth_00051, ECUC_Eth_00052, ECUC_Eth_00053, ECUC_Eth_00054, ECUC_Eth_00055, ECUC_Eth_00056, ECUC_Eth_00057, ECUC_Eth_00058, ECUC_Eth_00059, ECUC_Eth_00060, ECUC_Eth_00061, ECUC_Eth_00062, ECUC_Eth_00063

NON Standard configurable parameters

Following lists this design’s specific configurable parameters

Parameter Usage comment
EthEnableCacheOps Allows integration to enable cache operations on buffer memory when placed in cacheable memory.
EthRingInCachedMem Allows integration to enable cache operations on ring memory when placed in cacheable memory.
EthDescInCachedMem Allows integration to enable cache operations on descriptor memory when placed in cacheable memory.
EthMdioClkFreq Allows integrators to specify the MDIO clock frequency. Device TRM details the frequency based on the PLL configurations.
EthMdioBusFreq Allows integrators to specify the MDIO BUS frequency (MDCLK). Device TRM details the frequency based on the PLL configurations.
EthConnType Allows integrators to specify the MII connection type.
EthEnableLoopBack Allows integrators to enable or disable loopback mode of operation. Expected to be used for debug.
EthUseDefaultMacAddr Allows integrators to use MAC address that is present in ROM.
EthDefaultOSCounterId This shall allow integrators to specify the OS counter instance to be used in OS API GetCounterValue () The driver shall implement timed-wait for all waits (e.g. waiting for reset to complete). This timed wait shall use OS API GetCounterValue ().
EthTimeoutDuration Allow integrators to configure the time duration for which Eth-Busy should wait. Mainly needed for PHY register accesses.
EthDmaTxChIntrNum Allows integrators to specify the UDMA transmit interrupt number.
EthDmaRxChIntrNum Allows integrators to specify the UDMA receive interrupt number.
EthDmaRxChStartNum Allows integrators to specify the UDMA Rx channel start number.
EthDmaTxChStartNum Allows integrators to specify the UDMA Tx channel start number.
EthDmaRingStartNum Allows integrators to specify the UDMA Ring start number.
EthDmaFlowStartNum Allows integrators to specify the UDMA Flow start number.
EthDmaGlobalStartNum Allows integrators to specify the UDMA global event number.
EthDmaVirtualIntrStartNum Allows integrators to specify the UDMA virtual interrupt number.
EthDmaProxyStartNum Allows integrators to specify the UDMA proxy number.
EthTxDmaThresholdNum Allows integrators to specify the maximum Tx packet number process in Tx IRQ or Eth_TxConfirmation API.
EthRxDmaThresholdNum Allows integrators to specify the maximum Rx packet number process in Rx IRQ or Eth_Receive API.
EthHwTimerClockFreq Allows integrators to specify hardware timer clock frequency.
EthRxHwTimerId Allows integrators to specify hardware timer ID for RX IRQ pacing function.
EthRxHwIrqPacingInterval Allows integrators to specify IRQ pacing interval (in milliseconds) for RX IRQ pacing function.
EthTxHwTimerId Allows integrators to specify hardware timer ID for TX IRQ pacing function.
EthTxHwIrqPacingInterval Allows integrators to specify IRQ pacing interval (in milliseconds) for TX IRQ pacing function.
EthCptsRftClkFreq Allows integrators to specify CPTS reference clock frequency index.
EthDmaRingCfgOps Allows integrators to enable UDMA ring configuration operation.

Back To Top

Debug Information

The ETH driver shall provide driver status for debugging. The states ETH_STATE_UNINIT and ETH_STATE_INIT can be probed.

Design ID DES_ETH_035
Requirements Covered SWS_Eth_00159

Back To Top

Error Classification

Errors are classified in two categories, development error and runtime / production error.

Design ID DES_ETH_034
Requirements Covered SWS_Eth_00008, SWS_Eth_00120

Development Errors

Development errors are reported to the DET using the service Det_ReportError() if development error detection and reporting are enabled. The reported ETH module ID is 088 4.

The following table presents the service IDs and the related services:

Service ID (HEX) Service Name
0x01 Eth_Init
0x03 Eth_SetControllerMode
0x04 Eth_GetControllerMode
0x05 Eth_WriteMii
0x06 Eth_ReadMii
0x08 Eth_GetPhysAddr
0x09 Eth_ProvideTxBuffer
0xA Eth_Transmit
0x0B Eth_Receive
0x0C Eth_TxConfirmation
0xD Eth_GetVersionInfo
0x12 Eth_UpdatePhysAddrFilter
0x13 Eth_SetPhysAddr
0x14 Eth_GetCounterValues
0x15 Eth_GetRxStats
0x16 Eth_GetCurrentTime
0x17 Eth_EnableEgressTimeStamp
0x18 Eth_GetEgressTimeStamp
0x19 Eth_GetIngressTimeStamp
0x1C Eth_GetTxStats
0x1D Eth_GetTxErrorCounterValue
0x20 Eth_MainFunction

Back To Top

Error Detection

The detection of development errors is configurable (ON / OFF) at pre-compile time. The switch EthDevErrorDetect will activate or deactivate the detection of all development errors.

Error notification (DET)

All detected development errors are reported to Det_ReportError service of the Development Error Tracer (DET).

Parameter Checking

Design ID DES_ETH_003
Requirements Covered SWS_Eth_00016, SWS_Eth_00043, SWS_Eth_00044, SWS_Eth_00048, SWS_Eth_00049, SWS_Eth_00050, SWS_Eth_00054, SWS_Eth_00055, SWS_Eth_00056, SWS_Eth_00140, SWS_Eth_00141, SWS_Eth_00142, SWS_Eth_00164, SWS_Eth_00165, SWS_Eth_00166, SWS_Eth_00060, SWS_Eth_00061, SWS_Eth_00066, SWS_Eth_00067, SWS_Eth_00068, SWS_Eth_00228, SWS_Eth_00229, SWS_Eth_00230, SWS_Eth_00235, SWS_Eth_00236, SWS_Eth_00237, SWS_Eth_00182, SWS_Eth_00183, SWS_Eth_00184, SWS_Eth_00187, SWS_Eth_00188, SWS_Eth_00191, SWS_Eth_00192, SWS_Eth_00193, SWS_Eth_00196, SWS_Eth_00197, SWS_Eth_00198, SWS_Eth_00081, SWS_Eth_00082, SWS_Eth_00083, SWS_Eth_00084, SWS_Eth_00085, SWS_Eth_00090, SWS_Eth_00091, SWS_Eth_00092, SWS_Eth_00093, SWS_Eth_00129, SWS_Eth_00097, SWS_Eth_00098, SWS_Eth_00132, SWS_Eth_00103, SWS_Eth_00104, SWS_Eth_00134, SWS_Eth_00136

Back To Top

Runtime Errors

The Eth driver shall be capable of reporting the following production errors using the Dem_ReportErrorStatus() interface from the Diagnostics Event Manager (DEM), as specified by the AUTOSAR Ethernet Driver specification.

Type of Error Related Error code Value (Hex)
Invalid controller index ETH_E_INV_CTRL_IDX 0x01
Eth module or controller was not initialized ETH_E_NOT_INITIALIZED 0x02
Invalid pointer in the 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

Extended Production error

The CPSW module is capable of recording and reporting statistics related to different types of traffic events. A subset of those statistics shall be mapped to the error types required in the AUTOSAR Ethernet driver specification as follows:

  • ETH_E_ACCESS. Mapped to CPSW’s port 0 enable state and UDMA error condition.
  • ETH_E_RX_FRAMES_LOST. Mapped to CPSW’s “RX Bottom of FIFO Drop” which reports the total number of frames received on a port that overran the port’s RX FIFO and were dropped.
  • ETH_E_CRC. Mapped to CPSW’s “RX CRC Errors” which reports the total number of frames received on a port that experienced a CRC error.
  • ETH_E_UNDERSIZEFRAME. Mapped to CPSW’s “Undersize (Short) RX Frames” which reports the total number of undersized frames received on a port.
  • ETH_E_OVERSIZEFRAME. Mapped to CPSW’s “Oversize RX Frames” which reports the total number of oversized frames received on a port.
  • ETH_E_ALIGNMENT. Mapped to CPSW’s “RX Align/Code Errors” which reports the total number of frames received on a port that experienced an alignment or code error.
  • ETH_E_SINGLECOLLISION. Mapped to CPSW’s “Single Collision TX Frames” which reports the total number of frames transmitted on a port that experienced exactly one collision.
  • ETH_E_MULTIPLECOLLISION. Mapped to CPSW’s “Multiple Collision TX Frames” which reports the total number of frames transmitted on a port that experienced multiple (2 to 15) collisions.
  • ETH_E_LATECOLLISION. Mapped to CPSW’s “Late Collisions” which reports the total number of frames on a port with an abandoned transfer due to a late collision (512-bit times into the transmission).
Design ID DES_ETH_032
Requirements Covered SWS_Eth_00173, SWS_Eth_00174, SWS_Eth_00219, SWS_Eth_00220, SWS_Eth_00221, SWS_Eth_00222, SWS_Eth_00223, SWS_Eth_00224, SWS_Eth_00225

Back To Top

Resource Behavior

  • The Ethernet driver shall support one controller corresponding to the single Ethernet port e.g. (port 1) in the MCU_CPSW0 instance.
  • The Ethernet driver shall support single buffer per packet.
  • Code Size : Implementation of this driver shall not exceed 30 kilo lines of code and 1 KB of data section.
Design ID DES_ETH_036
Requirements Covered MCAL-2129
  • Stack Size : Worst case stack utilization shall not exceed 4 kilo bytes.
Design ID DES_ETH_037
Requirements Covered MCAL-2128

Back To Top

API's

For the standard API's please refer 8.3 of 1. Sections below highlight other design considerations for the implementation.

Eth_Init

Refer section 8.3.1 of the Ethernet Driver specification [1].

Design ID DES_ETH_005
Requirements Covered SWS_Eth_00027, SWS_Eth_00028, SWS_Eth_00029, SWS_Eth_00031, SWS_Eth_00034, SWS_Eth_00039

Back To Top

Eth_SetControllerMode

Refer section 8.3.2 of the Ethernet Driver specification [1].

Design ID DES_ETH_007
Requirements Covered SWS_Eth_00041, SWS_Eth_00042, SWS_Eth_00043, SWS_Eth_00044, SWS_Eth_00045, SWS_Eth_00168

Back To Top

Eth_GetControllerMode

Refer section 8.3.3 of the Ethernet Driver specification [1].

Design ID DES_ETH_008
Requirements Covered SWS_Eth_00046, SWS_Eth_00047, SWS_Eth_00048, SWS_Eth_00049, SWS_Eth_00050, SWS_Eth_00051

Back To Top

Eth_GetPhysAddr

Refer section 8.3.4 of the Ethernet Driver specification [1].

Design ID DES_ETH_009
Requirements Covered SWS_Eth_00052, SWS_Eth_00053, SWS_Eth_00054, SWS_Eth_00055, SWS_Eth_00056, SWS_Eth_00057

Back To Top

Eth_SetPhysAddr

Refer section 8.3.5 of the Ethernet Driver specification [1].

Design ID DES_ETH_019
Requirements Covered SWS_Eth_00139, SWS_Eth_00140, SWS_Eth_00141, SWS_Eth_00142, SWS_Eth_00143, SWS_Eth_00151

Back To Top

Eth_UpdatePhysAddrFilter

Refer section 8.3.6 of the Ethernet Driver specification [1].

Design ID DES_ETH_020
Requirements Covered SWS_Eth_00144, SWS_Eth_00146, SWS_Eth_00147, SWS_Eth_00150, SWS_Eth_00152, SWS_Eth_00164, SWS_Eth_00165, SWS_Eth_00166, SWS_Eth_00167, SWS_Eth_00245, SWS_Eth_00246

Back To Top

Eth_WriteMii

Refer section 8.3.7 of the Ethernet Driver specification [1].

Design ID DES_ETH_010
Requirements Covered SWS_Eth_00058, SWS_Eth_00059, SWS_Eth_00060, SWS_Eth_00061, SWS_Eth_00062, SWS_Eth_00063, SWS_Eth_00241

Back To Top

Eth_ReadMii

Refer section 8.3.8 of the Ethernet Driver specification [1].

Design ID DES_ETH_011
Requirements Covered SWS_Eth_00064, SWS_Eth_00065, SWS_Eth_00066, SWS_Eth_00067, SWS_Eth_00068, SWS_Eth_00069, SWS_Eth_00070, SWS_Eth_00242

Back To Top

Eth_GetCounterValues

Refer section 8.3.9 of the Ethernet Driver specification [1].

Design ID DES_ETH_022
Requirements Covered SWS_Eth_00226, SWS_Eth_00227, SWS_Eth_00228, SWS_Eth_00229, SWS_Eth_00230, SWS_Eth_00231, SWS_Eth_00232

Back To Top

Eth_GetRxStats

Refer section 8.3.10 of the Ethernet Driver specification [1].

Design ID DES_ETH_023
Requirements Covered SWS_Eth_00233, SWS_Eth_00234, SWS_Eth_00235, SWS_Eth_00236, SWS_Eth_00237, SWS_Eth_00238

Back To Top

Eth_GetTxStats

Refer section 8.3.11 of the Ethernet Driver specification [1].

Design ID DES_ETH_040
Requirements Covered SWS_Eth_00248, SWS_Eth_00249, SWS_Eth_00250, SWS_Eth_00251

Back To Top

Eth_GetTxErrorCounterValues

Refer section 8.3.12 of the Ethernet Driver specification [1].

Design ID DES_ETH_041
Requirements Covered SWS_Eth_91006, SWS_Eth_00252, SWS_Eth_00253, SWS_Eth_00254, SWS_Eth_00255

Back To Top

Eth_GetCurrentTime

Refer section 8.3.13 of the Ethernet Driver specification [1].

Design ID DES_ETH_026
Requirements Covered SWS_Eth_00181, SWS_Eth_00182, SWS_Eth_00183, SWS_Eth_00184, SWS_Eth_00185, SWS_Eth_00210

Back To Top

Eth_EnableEgressTimeStamp

Refer section 8.3.14 of the Ethernet Driver specification [1].

Design ID DES_ETH_027
Requirements Covered SWS_Eth_00186, SWS_Eth_00187, SWS_Eth_00188, SWS_Eth_00189, SWS_Eth_00211

Back To Top

Eth_GetEgressTimeStamp

Refer section 8.3.15 of the Ethernet Driver specification [1].

Design ID DES_ETH_028
Requirements Covered SWS_Eth_00190, SWS_Eth_00191, SWS_Eth_00192, SWS_Eth_00193, SWS_Eth_00194, SWS_Eth_00212

Back To Top

Eth_GetIngressTimeStamp

Refer section 8.3.16 of the Ethernet Driver specification [1].

Design ID DES_ETH_029
Requirements Covered SWS_Eth_00195, SWS_Eth_00196, SWS_Eth_00197, SWS_Eth_00198, SWS_Eth_00199, SWS_Eth_00213

Back To Top

Eth_ProvideTxBuffer

Refer section 8.3.17 of the Ethernet Driver specification [1].

Design ID DES_ETH_012
Requirements Covered SWS_Eth_00077, SWS_Eth_00078, SWS_Eth_00079, SWS_Eth_00080, SWS_Eth_00081, SWS_Eth_00082, SWS_Eth_00083, SWS_Eth_00084, SWS_Eth_00085, SWS_Eth_00086, SWS_Eth_00137

Back To Top

Eth_Transmit

Refer section 8.3.18 of the Ethernet Driver specification [1].

Design ID DES_ETH_013
Requirements Covered SWS_Eth_00087, SWS_Eth_00088, SWS_Eth_00089, SWS_Eth_00090, SWS_Eth_00091, SWS_Eth_00092, SWS_Eth_00093, SWS_Eth_00094, SWS_Eth_00129, SWS_Eth_00138

Back To Top

Eth_Receive

Refer section 8.3.19 of the Ethernet Driver specification [1].

Design ID DES_ETH_014
Requirements Covered SWS_Eth_00095, SWS_Eth_00096, SWS_Eth_00097, SWS_Eth_00098, SWS_Eth_00099, SWS_Eth_00132, SWS_Eth_00153

Back To Top

Eth_TxConfirmation

Refer section 8.3.20 of the Ethernet Driver specification [1].

Design ID DES_ETH_015
Requirements Covered SWS_Eth_00100, SWS_Eth_00101, SWS_Eth_00102, SWS_Eth_00103, SWS_Eth_00104, SWS_Eth_00105, SWS_Eth_00134

Back To Top

Eth_GetVersionInfo

Refer section 8.3.21 of the Ethernet Driver specification [1].

Design ID DES_ETH_016
Requirements Covered SWS_Eth_00106, SWS_Eth_00136

Back To Top

Eth_MainFunction

Refer section 8.5.1 of the Ethernet Driver specification [1].

Design ID DES_ETH_031
Requirements Covered SWS_Eth_00169, SWS_Eth_00171, SWS_Eth_00172, SWS_Eth_00240

Back To Top

Ethernet Interface Callbacks

The following Ethernet Interface (EthIf) callbacks are called upon transmission or reception events.

  • EthIf_TxConfirmation is called by the driver when notification has been enabled in Eth_Transmit().
  • EthIf_RxIndication is called by the driver upon successful reception.
Design ID DES_ETH_042
Requirements Covered SWS_Eth_00243, SWS_Eth_00256, SWS_Eth_00244

Refer to section 7.1.2 of the Ethernet Driver specification [1] for further information.

Back To Top

Ethernet Switch Callbacks

The following Ethernet Switch (EthSwt) callbacks are to be called to inform the Ethernet Switch driver about special treatment required for switch management purposes.

  • EthSwt_EthRxProcessFrame()
  • EthSwt_EthRxFinishedIndication()
  • EthSwt_EthTxPrepareFrame()
  • EthSwt_EthTxAdaptBufferLength()
  • EthSwt_EthTxProcessFrame()
  • EthSwt_EthTxFinishedIndication()
Design ID DES_ETH_043
Requirements Covered SWS_Eth_00247

Refer to section 7.1.2 of the Ethernet Driver specification [1] for further information.

This feature is not supported in this release. Please refer to Features Not Supported / NON Compliance section for further information.

Back To Top

Types

The following types are required as per AUTOSAR Ethernet Driver specification, 8.2 of the Ethernet Driver specification [1].

  • Eth_ConfigType. Implementation specific structure of the post build configuration.
  • Eth_ReturnType. Ethernet Driver specific return type.
  • Eth_ModeType. Defines the controller modes.
  • Eth_StateType. Status supervision used for Development Error Detection.
  • Eth_FrameType. The Ethernet frame type used in the Ethernet frame header.
  • Eth_DataType. The Ethernet data type used for data transmission. Its definition depends on the used CPU.
  • Eth_RxStatusType. Used as out parameter in Eth_Receive(). It indicates whether a frame has been received and if so, whether more frames are available or frames got lost.
  • Eth_FilterActionType. An enumeration that describes the action to be taken for the MAC address given in the *PhysAddrPtr.
  • Eth_TimeStampQualType. Depending on the HW, quality information regarding the evaluated time stamp might be supported. If not supported, the value shall be always Valid. For Uncertain and Invalid values, the upper layer discards the time stamp.
  • Eth_TimeStampType. Used for expressing the time stamps including relative and absolute calendar time.
  • Eth_TimeIntDiffType. Used to express time differences in a usual way.
  • Eth_RateRatioType. Used to express frequency ratios.
  • Eth_MacVlanType. Interpretation of this value is not specified by driver specification.
  • Eth_TxStatsType. Statistic counter for diagnostics.
  • Eth_RxStatsType. Statistic counter for diagnostics.
  • Eth_TxErrorCounterValuesType. Statistic counters for diagnostics.
Design ID DES_ETH_033
Requirements Covered SWS_Eth_00156, SWS_Eth_00158, SWS_Eth_00159, SWS_Eth_00160, SWS_Eth_00161, SWS_Eth_00162, SWS_Eth_00163, SWS_Eth_00175, SWS_Eth_00177, SWS_Eth_00178, SWS_Eth_00179, SWS_Eth_00180, SWS_Eth_91001, SWS_Eth_91002, SWS_Eth_91003, SWS_Eth_91004

Global Variables

This design expects that implementation will require to use following global variables.

Variable Type Description Default Value
Eth_DrvStatus Eth_StateType ETH driver status ETH_STATE_UNINIT
Eth_CtrlMacAddress uint8 ETH driver mac address -
Eth_CtrlPromiciousMode boolean Eth driver promicious mode status FALSE
Eth_CtrlModeChanged boolean Eth driver mode change status FALSE
Eth_RingMem_Ctrl_0_Fq_Egress_0 uint64 TX free ring memory -
Eth_RingMem_Ctrl_0_Cq_Egress_0 uint64 TX completion ring memory -
Eth_RingMem_Ctrl_0_TdCq_Egress_0 uint64 TX teardown completion ring memory -
Eth_RingMem_Ctrl_0_Fq_Ingress_0 uint64 RX free ring memory -
Eth_RingMem_Ctrl_0_Cq_Ingress_0 uint64 RX completion ring memory -
Eth_RingMem_Ctrl_0_TdCq_Ingress_0 uint64 RX teardown completion ring memory -
Eth_Ctrl_0_Egress_BufferMem_0 uint8 TX packet buffer memory -
Eth_Ctrl_0_Ingress_BufferMem_0 uint8 RX packet buffer memory -
Eth_Ctrl_0_Egress_Descriptor_0 uint8 TX DMA descriptor memory -
Eth_Ctrl_0_Ingress_Descriptor_0 uint8 RX DMA descriptor memory -
Eth_Ctrl_0_Egress_BufferState_0 uint8 TX packet buffer state memory -
Eth_Ctrl_0_Ingress_BufferState_0 uint8 RX packet buffer state memory -
Eth_Udma_RingCfg_0 Eth_Udma_RingCfgType UDMA Ring configuration -
Eth_EventCfg_Ctrl_0 Eth_Udma_EventCfgType UDMA Event configuration -
Eth_RingEventCfg_Ctrl_0 Eth_Udma_RingEventCfgType UDMA ring event configuration -
Eth_RingDyn_Ctrl_0 Eth_Udma_RingDynType UDMA ring dynamic data memory -

Back To Top

Decision Analysis & Resolution (DAR)

Sections below list some of the important design decisions and rational behind those decision.

Packet Submission & Retrieval to CPSW: Single or Queue

Traffic throughput can be limited by the underlying mechanism used to pass packets to the Ethernet hardware (CPSW). Unfortunately, the transfer related APIs of the AUTOSAR Ethernet Driver impose a significant constraint on the maximum throughput by processing packets one by one. However, the driver implementation can be done in a way that facilitates future throughput related improvements and customizations.

DAR Criteria

The ability to achieve higher throughput without significant driver complexity increase.

Available Alternatives

  • Single Packet A single packet is passed to the transmission or reception helper functions of the driver.
    • Advantages:
      • Simpler driver implementation, no queue operations need to be implemented
      • Meets the AUTOSAR Ethernet driver requirements
    • Disadvantages:
      • The maximum throughput is limited by having to process one packet at a time
      • Not straightforward way to increase throughput without major driver changes
  • Queue of Packets A linked-list based queue of packets is passed to the transmission or reception helper functions of the driver. The helper functions take care of creating packet descriptors for each packet in the queue.
    • Advantages:
      • Prepares the driver for higher throughput use-cases
      • Prepares the driver for reduced CPU load in higher throughput use-cases, which is achieved by reducing the overhead per packet by processing them all in a single shot
    • Disadvantages:
      • Upper layers can’t take advantage of this approach unless the mechanism to pass packets to the driver is customized
      • Increases driver complexity

Decision

The capability of scaling the driver for higher Ethernet throughput is a strong argument in favor of the alternative 2 (Queue of Packets). No major overhead is foreseen by using a queue instead of an array of packets. While the driver complexity increases, it’s not significant enough to affect the decision.

Back To Top

Buffers Per Packet

The number of data buffers in one Ethernet packet is often a configurable parameter in driver implementations. At this point, the AUTOSAR specification doesn’t require that the driver implementation supports multiple buffers per packet.

DAR Criteria

Buffers per packet configurability without significant driver complexity increase.

Available Alternatives

  • One buffer per packet No configurability allowed. The driver would create only Host Packet Descriptors.
    • Advantages:
      • Simpler driver implementation, only one type of descriptor needs to be implemented
      • Meets the AUTOSAR Ethernet driver requirements
    • Disadvantages:
      • Less configurability of the packet buffers
  • Configurable number of buffers per packet The driver would create Host Packet Descriptors for the first buffer in the packet and Host Buffer Descriptor for the rest.
    • Advantages:
      • More configurability of the packet buffers
    • Disadvantages:
      • Upper layers can’t take advantage of this approach unless the mechanism to pass packets to the driver is customized
      • Increases driver complexity

Decision

Adding the support for flexible number of buffers per packet in the Ethernet driver is localized changes. Consequently it makes more sense to add this feature when the Ethernet specification mandates it. Recommended to implement option 1 (one buffer per packet).

Back To Top

Test Criteria

The sections below identify some of the aspects of design that would require emphasis during testing of this design implementation

  • Loopback Test
    • CPSW internal loopback test (transmit to receive). Generally speaking, the loopback tests are easier and faster to run because they don’t involve any additional test setup. It’s recommended that loopback tests are performed before any other type of testing as it can help identify problems more quickly (NON Standard configurable parameters)
  • Transmit: Basic and Stress Tests
    • Transmission of 100 packets from the DUT
      • Packets shall be received in a PC machine (i.e. running Wireshark or similar application)
      • Manual inspection shall be done to ensure packet content is correct (i.e. it matches an expected pattern)
    • Transmission of 500k packets from the DUT
      • Packets shall be received in a PC
      • Received packet count must match
    • Transmission of packets with injected errors
      • The test application shall print TX error messages from CPSW statistics
  • Reception: Basic and Stress Tests
    • Reception of N packets on the DUT
      • Packets shall be sent from a PC machine (i.e. running packeETH or similar application)
      • The test application shall inspect packet content to ensure content is correct (i.e. it matches an expected pattern)
    • Reception of 500k packets from the DUT
      • Packets shall be received in a PC
      • Received packet count must match
    • Reception of packets with injected errors
      • The test application shall print RX error messages from CPSW statistics
  • Polling and Interrupt Mode Test
    • Basic transmission and reception tests with the Eth driver in interrupt mode
    • Basic transmission and reception tests with the Eth driver in polling mode
  • Global Time Support Tests
    • Reception of PTP packets
      • PTP packets sent from PC
      • The test application shall inspected all incoming packets and identify the time sync events related
      • The test application shall print the time stamp of the identified packets

Back To Top

Document Revision History

Revision Date Author Description Status
0.1 28 Jun 2018 Misael Lopez First version Approved
0.2 04 Oct 2018 Sujith S Format change and re-order Approved
0.3 29 May 2020 Misael Lopez Updated for AUTOSAR 4.3.1 Approved
0.4 09 Dec 2022 Quan Tran Updated for lastest driver implemation Approved
0.5 30 May 2023 Quan Tran Updated for lastest driver implemation Approved