Eth (Ethernet Driver)

Introduction

The Ethernet Driver provides hardware independent access to configure and control Ethernet Controllers integrated in the microcontroller (MCU) or connected to it via an external interface like for example SPI.

Architecture Overview

Figure 2-1 shows where the Ethernet Driver is located in the AUTOSAR architecture.

Figure 2-2 shows the interfaces to adjacent modules of the Ethernet Driver. These interfaces are described in chapter 0.

Functional Description

Features

The features listed in the following tables cover the complete functionality specified for the whole range of Vector Ethernet Drivers.

For extensions beyond or limitation of the described functionalities please see [6] of the specific driver.

The AUTOSAR standard functionality is specified in [1], the corresponding features are listed in the tables

• Table 3-1 Supported AUTOSAR standard conform features
• Table 3-2 Not supported AUTOSAR standard conform features

Vector Informatik provides further Ethernet Driver functionality beyond the AUTOSAR standard. The corresponding features are listed in the tables

• Table 3-3 Features provided beyond the AUTOSAR standard
• Table 3-4 Platform dependent Ethernet features

The following features specified in [1] are supported:

Deviations

The following features specified in [1] are not supported:

Additions / Extensions

The following features are provided beyond the AUTOSAR standard:

Platform Dependent Features

Table 3-4 lists all driver/hardware dependent features provided by Vector drivers.

Please refer to [6] for details if the noted features are available by the specific driver used.

Initialization

High-Level Initialization

The Ethernet Driver is initialized by calling the Eth_30_<Driver>_Init() service with NULL_PTR as configuration pointer due to Pre-Compile-Configuration-Variant only support.

The Ethernet controller itself is initialized by calling the Eth_30_<Driver>_ControllerInit() service for the respective controller to be initialized.

Low-Level Initialization

The Ethernet Driver relies on the proper configuration of the MCU, which must be done by the MCAL modules. Table 3-5 contains information about the modules involved and what preconditions must be provided by them for proper functionality of the Ethernet Controller.

States

The Ethernet Driver adopts the states described in the following table:

The Ethernet Controller adopts the states described in the following table:

Most APIs of the driver are only allowed to be called in specific states either of the driver or the Ethernet Controller. For details see the service descriptions in 5.

Main Functions

The Ethernet Driver has one main function described in the following table:

Error Handling

Development Error Reporting

By default, development errors are reported to the DET using the service Det_ReportError() as specified in [3], if development error reporting is enabled (i.e. pre-compile parameter ETH_30_<DRIVER>_DEV_ERROR_DETECT==STD_ON).

If another module is used for development error reporting, the function prototype for reporting the error can be configured by the integrator, but must have the same signature as the service Det_ReportError().

The reported Ethernet Driver ID is 88.

The reported service IDs identify the services which are described in [3]. Table 3-9 presents the service IDs and the related services:

The errors reported to DET are described in Table 3-10:

Production Code Error Reporting

By default, production code related errors are reported to the DEM using the service Dem_ReportErrorStatus() as specified in [4].

The errors reported to DEM are described in Table 3-11:

MAC Address

The MAC address of a controller may be configured to a default value via the MAC address configuration parameter within the configuration tool. Additionally, the user may call the API Eth_30_<Driver>_SetPhysAddr to change the MAC address at runtime.

The default behavior of Eth_30_<Driver>_SetPhysAddr is non-persistent. The user must provide the MAC address each time after an ECU restart (in case no default is configured within the configuration tool). An extended, persistent behavior can be enabled via the feature “Enable MAC address write access” discussed in the next section.

NV-RAM

The feature “Enable MAC address write access” enables NvM support for the API Eth_30_<Driver>_SetPhysAddr. In this case the MAC address gets written into a NV-RAM block and is loaded at controller initialization. This ensures that the MAC address is persistent even after a system restart.

The NV-RAM block for a MAC must have a length of 6 bytes. The initial value is configured via the MAC address configuration parameter within the configuration tool. The NV-RAM block must be managed by the AUTOSAR NV-Manager (NvM) and is addressed by a NvM block descriptor (refer to [7]).

The NV-RAM blocks must be processed during the NvM_ReadAll() and NvM_WriteAll() function calls.

The symbols for the ROM and RAM mirrors are listed below

• ROM default block: Eth_30_<Driver>_VPhysSrcAddrRomDefault_<CtrlIdx>
• RAM mirror: Eth_30_<Driver>_VPhysSrcAddr_<CtrlIdx>

where <CtrlIdx> is the index of the controller.

Hardware Cancellation

The hardware cancellation feature can be applied for different hardware operations by setting the corresponding cycle number. While performing these operations a counter is incremented in a loop in every cycle until either the operation is finished or the configured maximum value of the cycle number has been reached. In this case the operation has failed. The configurable maximum cycle counter values are:

• Controller Reset Loop Cycles: Specifies the number of loop cycles after which the controller reset timeout occurs.
• Controller MII Loop Cycles: Specifies the number of loop cycles after which the timeout for MII accesses occurs.
• Controller Loop Cycles: Specifies the number of loop cycles after which other hardware dependent loop timeouts occur.

Runtime Measurement

Runtime measurement allows to measure the processing time of specific functions of the driver. Therefore so called measurement points are used. These points are automatically created in the Rtm module, if the module is contained in the configuration.

This description only shows the Ethernet drivers specific aspect of the runtime measurement. For a more detailed description of the runtime measurement feature and the Rtm module providing the service see [8].

Dependent on the Ethernet controller core integrated on the derivative used and the features enabled, more or less measurement points are provided.

Ethernet Switch Frame Management

Some Ethernet Switches provide a functionality called frame management. This feature makes it possible to transfer Meta data related to an Ethernet frame over the MII interface. This Meta data is either embedded into the Ethernet Frame itself or transferred as a consecutive Ethernet frame. To allow the Ethernet Driver to process the Ethernet frames without the knowledge which kind of mechanism is used, an interaction between Ethernet Driver and Ethernet Switch Driver is needed.

For a more detailed description of the interface please refer to the Ethernet Switch Drivers technical reference.

Pre-/Post-ControllerInit User-Functions

The driver allows to inject integration code in the processing of the Eth_30_<Driver>_ControllerInit() API.

This integration code is either executed before the actual code of the Eth_30_<Driver>_ControllerInit() (Pre-ControllerInit User-Function), after the actual code (Post-ControllerInit User-Function) or both.

The functions can be used to integrate derivative specific code that must be executed for a proper operation of the Ethernet Controller. Such code could be setting registers in port or clock modules, which are needed to configure the xMII interface between the Ethernet Controller and the Ethernet PHY properly.

The User-Functions will be generated into the Eth_30_<Driver>_Lcfg.c file and contain a so-called User-Block-Comment where integration code can be provided, which is persisted and not overridden if the Eth_30_<Driver>_Lcfg.c file is generated again.

The function names are Eth_30_<Driver>_PreControllerInitCallout() and Eth_30_<Driver>_PostControllerInitCallout().

Rx and Tx Statistics

With the functions Eth_30_<Driver>_GetRxStats and Eth_30_<Driver>_GetTxStats the lists of counter values that can be seen in Table 3-13 and Table 3-14 can be obtained from the hardware. Please note, that if a realistic counter value cannot be obtained from the underlying hardware platform, the API returns a special value. See sections 5.2.1 and 5.2.2 for details on the used data type.

Driver/Hardware Dependent Features

The following sections introduce features which are contained in the software provided by Vector but are not supported on each driver or hardware derivative.

Please refer to [6] section 3.1. where following table can be found that summarizing the availability of the features by the respective driver or on the specific hardware derivative used.

Time Synchronization

The time synchronization allows synchronizing the Ethernet Controllers timer to a respective time base by retrieving timestamps of Ethernet frames on transmission and reception and manipulating the timer.

Timer

For the support of PTP the Ethernet Controller core implements a timer which maintains the local time. This time base is used to timestamp the frames. Additionally to the time stamping feature the timer can be manipulated by multiple APIs, which will be described in the following sections.

Timer Manipulation

The local time can be manipulated to be approximated to a global time negotiated between the nodes in the Ethernet network by a time synchronization protocol like PTP.

The API Eth_30_<Driver>_SetCorrectionTime() allows this manipulation. It enables the upper layer to correct the time by an offset or to slow down / accelerate the clock.

Global Time Retrieving/Setting

An upper layer is able to retrieve and set the global time. Therefor the APIs Eth_30_<Driver>_GetGlobalTime() and Eth_30_<Driver>_SetGlobalTime() are provided.

Ingress Time Stamping

If an incoming Ethernet frame is time stamped by the Ethernet Controller, an upper layer is able to retrieve this timestamp by calling the API Eth_30_<Driver>_GetIngressTimestamp().

Figure 3-1 illustrates the sequence with an EthTSyn (GPtp) upper layer:

Egress Time Stamping

The time stamping of outgoing Ethernet frames must be triggered by the upper layer itself.

To achieve the time stamping the upper layer must obtain a transmit buffer by calling Eth_30_<Driver>_ProvideTxBuffer(). Afterwards the buffer provided is locked and time stamping for this buffer can be enabled by calling Eth_30_<Driver>_EnableEgressTimestamp(). The transmission now can be trigger with the API Eth_30_<Driver>_Transmit().

The time stamp itself is retrieved on transmission indication by calling Eth_30_<Driver>_GetEgressTimestamp().

Figure 3-2 illustrates the sequence with an EthTSyn (GPtp) upper layer:

Quality of Service

Quality of Service (QoS) allows prioritizing the Ethernet traffic dependent on the priority of a VLAN tagged frame.

The following example provides three traffic classes: The best effort class-, class-1- and class-2-traffic, where best effort has the lowest priority and class 2 has the highest priority.

The different classes can be identified in the configuration tool by the parameter Priority (see Figure 3-3) and Table 3-16.

Like mentioned before, the traffic classification is done with the help of the priority encoded by the VLAN tag. To achieve this, the VLAN priority is used during configuration time to assign traffic to a specific traffic class. This can be done for the Transmission- and for the Reception-Path as well. In the screenshot, illustrated by Figure 3-3, for example, traffic class 2 on Transmission-Path has assigned all frames sent with the VLAN priority 6 and 7.

FQTSS (Traffic Shaping)

The FQTSS (Forwarding and Queuing Enhancements for Time-Sensitive Streams) support allows applying traffic shaping for Ethernet traffic on the Transmission-Path. The mechanism is based on the QoS traffic classes described in the section 3.12.2.

The traffic classes are assigned to a traffic shaper, which defines an idle slope to shape the Ethernet traffic. The driver allows configuring the shapers in a static way during configuration time by providing the desired bandwidth in [bit/s].

Additionally the current bandwidth limit can be manipulated or retrieved during runtime by using the APIs Eth_30_<Driver>_SetBandwidthLimit() and Eth_30_<Driver>_GetBandwidthLimit().

Checksum Offloading

Checksum Offloading allows calculating and checking checksums of protocols of the TcpIp stack. In principle following checksum calculation can be offloaded to hardware. However not each hardware is capable to calculate all checksums. For details regarding the used driver/hardware please see [6].

Safe Context

CPUs on certain platforms can support different operation modes (e.g. User and Privileged/Supervisor mode). Depending on the used derivative the R/W access to Ethernet hardware registers can be restricted to Privileged mode only. Additionally, depending on the system design, the Ethernet Driver may not be allowed to switch into a Privileged mode by itself. Therefore the protected registers must be accessed from outside of the Ethernet Driver by another software layer (e.g. the Operating System) which is able to switch into the required Privileged mode.

Privileged Access with OS Callbacks

The software layer (e.g. the Operating System) which is responsible to handle the privileged access to protected registers must add an area define according to the configured ‘Peripheral Region Os Identifier’ parameter value in the Ethernet controller configuration in DaVinci Configurator Pro.

For each used ‘Peripheral Region Os Identifier’ the following register address space has to be located inside the privileged region that can be configured within the Operating System module in DaVinci Configurator Pro:

The OS callbacks that are called by the Ethernet Driver are provided by the Operating System component. Please refer to the Technical Reference [9] of the OS component for further information.

Non-Privileged Access by Configuration of a Peripheral Protection Unit

A Peripheral Protection Unit (PPU) which is existing on certain platforms can be configured to permit access to registers which normally require Privileged access mode also for a non-privileged access in User mode. These access rights can be configured on certain platforms individually per peripheral unit, e.g. for a whole Ethernet MAC unit. For further details see e.g. section ‘Peripheral Protection Unit’ of the related hardware manual of the used derivative.

Receive Buffer Segmentation

Some Ethernet MACs provide the ability to receive one frame using multiple descriptors connected to small buffer. When this feature is available and enabled the configuration allows configuring segment sizes different to the maximum frame size, which can be received. The MAC uses as much descriptors per frame as necessary to receive the whole frame.

The implementation of this mechanism is transparent for the upper layers.

Enabling Receive Buffer Segmentation can be activated for a more efficient usage of RAM, which is needed in systems which need to receive large frames only in rare cases, but mainly receive small frames. Instead of having a pool of large buffers available which cause a lot of wasted memory for small frames, the usage of memory scales with the amount of used segments per frame.

Considering an example of three frames with a size of 128 Bytes and one frame with a size of 1500 Bytes, without Receive Buffer Segmentation 4 x 1500 = 6000 Bytes of receive buffers are needed. Using Receive Buffer Segmentation only 15 x 128 = 1920 Bytes of receive buffers are needed.

---

References

MICROSAR Ethernet Driver Technical Reference (Version 2.1.1)