Ethernet Driver (Eth)

The function Eth_Init serves to initialize the Ethernet driver [SWS_Eth_00027]. It is declared via the header file Eth.h, has the service ID 0x01, and has no return value (void) [SWS_Eth_00027]. As an input parameter, it expects CfgPtr, which points to an implementation-specific configuration structure of type Eth_ConfigType [SWS_Eth_00027]. The call is synchronous and defined as non-reentrant (Non Reentrant) [SWS_Eth_00027].

In the operational sequence, Eth_Init constitutes the fundamental precondition for working with the module. All other functions strictly require a prior controller initialization by Eth_Init [SWS_Eth_00070], [SWS_Eth_00167], [SWS_Eth_00185]. This dependency is mandatorily prescribed for various controller services of the driver [SWS_Eth_00189], [SWS_Eth_00194], [SWS_Eth_00199], [SWS_Eth_00232].

Dedicated error handling is provided in case of uninitialized access: When development error detection (DET) is activated, the driver functions check whether service Eth_Init was properly called beforehand [SWS_Eth_00066]. If this check is not successful, they raise the development error ETH_E_UNINIT [SWS_Eth_00164], [SWS_Eth_00182], [SWS_Eth_00187], [SWS_Eth_00196]. If DET is disabled, however, affected functions refuse execution and signal the impermissible state by returning status E_NOT_OK [SWS_Eth_00228], [SWS_Eth_00235], [SWS_Eth_00248], [SWS_Eth_00252].

The function Eth_SetControllerMode serves to enable (ETH_MODE_ACTIVE) or disable (ETH_MODE_DOWN) the Ethernet controller addressed via parameter CtrlIdx [SWS_Eth_00041]. In AUTOSAR Classic R20-11, this service is classified as obsolete (obsolete) [SWS_Eth_00041].

Execution of the service is asynchronous and non-reentrant (Non Reentrant) [SWS_Eth_00041]. As return value, the function returns E_OK upon successful initiation or E_NOT_OK if the operating mode could not be changed [SWS_Eth_00041]. Interpretation: Since the call is specified as asynchronous, but no callback is defined in the payload, the actual state change is likely completed near the hardware in the driver background after return from the function. Question Q-d7ec04578e921eb9 (open)

If the controller or its transmit and receive communication is disabled via Eth_SetControllerMode, mandatory buffer cleanup actions apply:

• All locked transmit buffers must be released [SWS_Eth_00137] [SWS_Eth_00280].
• All pending transmit buffers must also be released [SWS_Eth_00138] [SWS_Eth_00281].

Due to the property Non Reentrant, the function must not be executed concurrently for the same or additional controller instances [SWS_Eth_00041]. Specific DET or DEM error notifications are not listed; error conditions are communicated to the caller via the return value E_NOT_OK [SWS_Eth_00041].

The function Eth_SetControllerMode (Service ID 0x03, provided via Eth.h) serves to enable and disable receive and transmit communication (Rx/Tx) of a specific Ethernet controller [SWS_Eth_91009].

Usage and Call Conditions

Execution of the function is asynchronous and specified as non-reentrant (Non Reentrant) [SWS_Eth_91009]. Upon invocation, two parameters are passed:

• CtrlIdx: Index of the respective controller in the context of the Ethernet driver [SWS_Eth_91009].
• CtrlMode: Target mode for the controller, either ETH_MODE_ACTIVE to enable Rx/Tx communication or ETH_MODE_DOWN to disable it [SWS_Eth_91009].

As return value, the function returns status Std_ReturnType: E_OK signals successful execution, whereas E_NOT_OK indicates that the mode of the controller could not be changed [SWS_Eth_91009].

Interaction and Buffer Management

If the Rx/Tx communication of the indexed controller is disabled via Eth_SetControllerMode (mode ETH_MODE_DOWN), cleanup actions for the transmit buffers must mandatorily be performed:

• All locked transmit buffers must be released [SWS_Eth_00280].
• All pending transmit buffers must also be released [SWS_Eth_00281].

The current provisions for releasing locked and pending buffers as well as the function definition itself have the status "draft" [SWS_Eth_91009], [SWS_Eth_00280], [SWS_Eth_00281]. They replace the historically preceding requirements [SWS_Eth_00137] and [SWS_Eth_00138], which are classified as obsolete.

The synchronous interface Eth_UpdatePhysAddrFilter is provided via the header file Eth.h and has the service ID 0x12 [SWS_Eth_00152]. The function serves to add a physical address to or remove it from the filter of an indexed Ethernet controller [SWS_Eth_00152].

The parameters of the function comprise three input values [SWS_Eth_00152]:

• CtrlIdx: Determines the index of the respective Ethernet controller within the driver context [SWS_Eth_00152].
• PhysAddrPtr: Pointer to the memory area containing the physical destination address (MAC address) in network byte order; this is the multicast destination address of the layer 2 Ethernet packet [SWS_Eth_00152].
• Action: Specifies via the enumeration type Eth_FilterActionType whether the specified address is added to or deleted from the controller filter [SWS_Eth_00152].

The function returns a status of type Std_ReturnType: E_OK confirms the successful modification of the filter, while E_NOT_OK reports that the filter could not be modified [SWS_Eth_00152]. If the Ethernet controller is incapable on the hardware side of performing the filtering autonomously, the filtering task must be implemented by software [SWS_Eth_00152].

A strict reentrancy restriction applies to the execution: The function is non-reentrant for the same controller index (CtrlIdx), but may be called concurrently and reentrantly for differing controller indices [SWS_Eth_00152].

The function Eth_WriteMii serves to configure a register of an Ethernet transceiver via the MII interface or to trigger a function provided by the transceiver [SWS_Eth_00058]. The declaration is available via the header Eth.h [SWS_Eth_00058].

Usage and Parameters

The call is made with the service ID 0x05 and processes four input parameters [SWS_Eth_00058]:

• CtrlIdx: Index of the Ethernet controller in the context of the Ethernet driver [SWS_Eth_00058].
• TrcvIdx: Index of the transceiver on the MII interface [SWS_Eth_00058].
• RegIdx: Index of the transceiver register to be written on the MII [SWS_Eth_00058].
• RegVal: The 16-bit value to be written into the addressed register [SWS_Eth_00058].

The execution of the service is specified as asynchronous [SWS_Eth_00058]. This means that the actual write operation via the hardware interface is typically handled in the background, while the function returns immediately after accepting the request. Question Q-0f9a9e682985d796 (open)

Return Values and Restrictions

As return value, the function provides type Std_ReturnType [SWS_Eth_00058]:

• E_OK: The write request was accepted successfully [SWS_Eth_00058].
• E_NOT_OK: The service was rejected [SWS_Eth_00058].

Regarding concurrency, Eth_WriteMii is specified as non-reentrant (Non Reentrant) [SWS_Eth_00058]. Calls must therefore not be executed concurrently without appropriate synchronization by the caller.

Usage and Parameters

The function Eth_ReadMii (Service ID 0x06) serves to read a transceiver register via the MII interface and is provided via header file Eth.h [SWS_Eth_00064]. Upon invocation, CtrlIdx identifies the respective Ethernet controller in the driver context, TrcvIdx identifies the addressed transceiver on the MII, and RegIdx identifies the concrete transceiver register [SWS_Eth_00064]. The determined register value is written to the memory location pointed to by pointer RegValPtr [SWS_Eth_00064].

Execution and Concurrency

Execution is asynchronous (Asynchronous) [SWS_Eth_00064]. A return value of E_OK merely confirms that the service or the read request was successfully accepted (Service accepted), whereas E_NOT_OK signals a rejection of the request (Service denied) [SWS_Eth_00064]. Because of the asynchronous nature, the memory area passed for RegValPtr likely must remain valid until final completion of the read operation. Question Q-04a94624b96bf51f (open) Since the function is also classified as non-reentrant (Non Reentrant) [SWS_Eth_00064], callers must not perform concurrent accesses across different tasks or interrupt contexts without external synchronization.

Error handling

If the driver cannot accept the read request, the call is acknowledged directly with E_NOT_OK [SWS_Eth_00064]. Specific error codes, DET runtime checks, or DEM diagnostic events are not listed for this function in the element-related specification data.

The synchronous function Eth_EnableEgressTimeStamp activates the recording of egress timestamps (egress time stamping) for a dedicated message object of the Ethernet driver [SWS_Eth_00186]. The call is made via the header Eth.h with the service ID 0x17 and returns no value [SWS_Eth_00186].

When calling, the following input parameters must be passed [SWS_Eth_00186]:

• CtrlIdx: Index of the addressed Ethernet controller [SWS_Eth_00186].
• BufIdx: Index of the message buffer for which the upper-layer application expects the generation of an egress timestamp [SWS_Eth_00186].

Regarding concurrency, the function is specified as non-reentrant (Non Reentrant) [SWS_Eth_00186]. A parallel call for the same or additional buffers must therefore be synchronized or avoided on the caller side.

The behavior of the hardware varies depending on the controller implementation: Some hardware stores the mark for the egress timestamp persistently, whereas other controllers mandatorily require activation prior to each transmission [SWS_Eth_00186]. Interpretation: For hardware-independent control, it would therefore likely be advisable to call the function prior to each transmission of the desired buffer. Question Q-c2b8d2db03e9d13b (open) A deactivation interface does not exist because the message type is always transmitted timestamped according to the network design [SWS_Eth_00186].

use

The synchronous function Eth_ProvideTxBuffer grants access to an Ethernet transmit buffer of the FIFO that is assigned to the passed priority [SWS_Eth_00077]. It is provided via the header Eth.h and specified as reentrant [SWS_Eth_00077]. Via the input parameters, the controller index CtrlIdx as well as the frame priority Priority for FIFO selection are passed [SWS_Eth_00077]. The in/out parameter LenBytePtr passes the desired buffer size and returns the actually granted byte size after the call [SWS_Eth_00077]. The output parameters BufIdxPtr (resource index for subsequent queries) and BufPtr (pointer to the buffer) provide the references to the memory area [SWS_Eth_00077].

Error Handling and Return Values

The function signals the result via return values of type BufReq_ReturnType [SWS_Eth_00077]:

• BUFREQ_OK: The transmit buffer was successfully provided [SWS_Eth_00077].
• BUFREQ_E_BUSY: All buffer resources are currently occupied [SWS_Eth_00077].
• BUFREQ_E_OVFL: The requested buffer is too large [SWS_Eth_00077].
• BUFREQ_E_NOT_OK: A development error was detected [SWS_Eth_00077].

Interaction

If EthCtrlConfigSwBufferHandling is configured to TRUE, a tuple consisting of the buffer index of the software buffer pool passed to BufIdxPtr and the specified priority Priority is stored internally [SWS_Eth_00267].

If Eth_Transmit() is subsequently called, the given buffer index is assigned to the software FIFO whose configuration EthCtrlConfigEgressFifoPriorityAssignment matches the priority previously passed in Eth_ProvideTxBuffer() [SWS_Eth_00268].

Usage and Call Context

The synchronous interface Eth_Transmit initiates the transmission process for a previously provided and filled Ethernet transmit buffer [SWS_Eth_00087]. It accepts the following parameters:

• CtrlIdx: Index of the Ethernet controller within the context of the driver [SWS_Eth_00087].
• BufIdx: Index of the buffer resource to be transmitted [SWS_Eth_00087].
• FrameType: Specific Ethernet frame type [SWS_Eth_00087].
• TxConfirmation: Switch for activating transmit confirmation [SWS_Eth_00087].
• LenByte: Data length of the payload in bytes [SWS_Eth_00087].
• PhysAddrPtr: Pointer to the physical destination address (MAC address) in network byte order [SWS_Eth_00087].

The return value of type Std_ReturnType signals the successful initiation of the transmission with E_OK and a failure with E_NOT_OK [SWS_Eth_00087].

Interaction and buffer processing

As part of the transmission sequence, Eth_Transmit assigns the buffer pointer BufIdx to the software FIFO whose configuration element EthCtrlConfigEgressFifoPriorityAssignment matches the priority previously defined in Eth_ProvideTxBuffer() [SWS_Eth_00268]. With the call, the corresponding messages are transferred from the software FIFOs into the hardware FIFO [SWS_Eth_00269].

Concurrency

The function is reentrant for calls with different buffer indices (BufIdx) as well as different controller indices (CtrlIdx) [SWS_Eth_00087].

The synchronous function Eth_Receive serves to receive an Ethernet frame from a specific FIFO buffer of an Ethernet controller [SWS_Eth_00095]. It has no return value, but returns the result of the query to the caller via the pointer RxStatusPtr of type Eth_RxStatusType [SWS_Eth_00095]. This output parameter indicates whether a frame was successfully received and whether further frames are available for retrieval in the respective FIFO buffer [SWS_Eth_00095].

Parameters and call context

As input parameters, the function requires the controller index CtrlIdx within the Ethernet driver as well as the index FifoIdx of the FIFO to be read [SWS_Eth_00095]. The function is declared in the header file Eth.h [SWS_Eth_00095]. The call is typically expected to occur periodically within a polling mechanism by higher driver or interface layers. Question Q-f5ec0693a5887bcf (open)

Concurrency and Limitations

Regarding concurrency, Eth_Receive is implemented as reentrant for different FIFOs, but non-reentrant for the same FIFO [SWS_Eth_00095]. Concurrent calls querying the same FIFO of the same controller are impermissible and must be prevented by the calling software.

Interaction with the Ethernet interface

In polling mode, the Ethernet driver is obliged, upon a successful reception, to call the function EthIf_RxIndication directly from the routine Eth_Receive in order to report the received frame to the upper layer for further processing [SWS_Eth_00244].

Usage and Call Context

The function Eth_TxConfirmation available via header Eth.h serves to specifically trigger transmission confirmation for transmitted Ethernet frames [SWS_Eth_00100]. It has the Service ID 0x0C and is executed synchronously [SWS_Eth_00100]. As its only input parameter, the function expects CtrlIdx, which determines the logical index of the controller to be addressed within the instance of the Ethernet driver [SWS_Eth_00100]. A return value does not exist (void), and no output parameters are passed [SWS_Eth_00100].

Interaction in the Transmission Sequence

In the interaction of the layers, Eth_TxConfirmation handles the forwarding of the transmission status to the upper Ethernet Interface. If the corresponding notification was enabled, the Ethernet driver is obliged to call EthIf_TxConfirmation with the result value E_OK in order to signal a successful transmission [SWS_Eth_00243]. In polling mode, this call occurs explicitly from the context of routine Eth_TxConfirmation, whereas in interrupt-driven mode, it is alternatively issued directly from the interrupt routine [SWS_Eth_00243].

Concurrency and Execution Conditions

For execution, the restriction applies that Eth_TxConfirmation is defined as non-reentrant (Non Reentrant) [SWS_Eth_00100]. Concurrent calls for the same controller must therefore be prevented by the caller. In polling mode, the call is likely to occur typically cyclically through a higher-level schedule control. Question Q-c19295838459b689 (open) Specific error codes as well as requirements for DET or DEM notifications are not specified in the functional specification, which is why a separate error handling is omitted.

Usage and Call Context

The function Eth_MainFunction has the signature void Eth_MainFunction(void) and is provided via header file SchM_Eth.h [SWS_Eth_00171]. From this, it can be interpreted: The call is likely to occur cyclically through the Schedule Manager (SchM) in a task-based context, since no input parameters or return values are defined. Question Q-690a2dc372d49c6a (open)

Functional Scope and Polling

The main task of the function consists in polling state changes as well as checking for controller errors and lost Ethernet frames [SWS_Eth_00171]. If the function detects that the mode of the Ethernet controller has changed, it calls function EthIf_CtrlModeIndication to inform the upper layer about the state transition [SWS_Eth_00171].

Processing Order in the Transmit Path

In the context of Eth_MainFunction(), a fixed sequence is prescribed for processing software FIFOs [SWS_Eth_00270]:

• First, all SW FIFOs are iterated and their credit accounts (Credits Account) are updated [SWS_Eth_00270].
• Subsequently, all SW FIFOs are iterated again and checked for messages ready to send [SWS_Eth_00270].
• Transmission is then attempted for each iterated SW FIFO [SWS_Eth_00270].

In the layers of the Ethernet communication stack (such as EthIf, Eth, EthSwt, and EthTrcv), the generic enumeration type Eth_ModeType serves to enable or disable the Ethernet communication channel and to switch the associated hardware (such as Ethernet controller, Ethernet switch port, or Ethernet transceiver) into a low-power sleep state or active mode [SWS_Eth_00158].

The type is available via the header file Eth_GeneralTypes.h and defines the following value ranges [SWS_Eth_00158]:

• ETH_MODE_DOWN (0x00): Disables the Ethernet communication channel and switches the associated hardware into a low-power sleep mode [SWS_Eth_00158].
• ETH_MODE_ACTIVE (0x01): Enables the Ethernet communication channel and switches the hardware into operational mode (Power-On Mode) [SWS_Eth_00158].

Regarding the lifecycle and usage, it should be noted that Eth_ModeType is marked with the status obsolete in Release R20-11 [SWS_Eth_00158]. In new developments, using this type should therefore be avoided, as obsolete interface types in future standards are typically replaced by more modern control structures.

The enumeration type Eth_ModeType is declared via Eth_GeneralTypes.h and serves as a cross-layer mode type in the AUTOSAR Ethernet communication stack ([SWS_Eth_91008]). It is used in modules such as EthIf, Eth, EthSwt, and EthTrcv to specifically activate or deactivate communication channels and to switch the associated hardware component (Ethernet controller, switch ports, or transceiver) between a power-saving sleep mode and the active operating mode ([SWS_Eth_91008]).

The type comprises three states for mode control ([SWS_Eth_91008]):

• ETH_MODE_DOWN (0x00): Deactivates Rx and Tx communication and switches the associated hardware into a low-power sleep mode. If supported by the hardware, a sleep sequence is initiated at the same time (for example, requesting sleep on the data line according to OPEN Alliance TC10).
• ETH_MODE_ACTIVE (0x01): Activates Rx and Tx communication and switches the associated hardware into the regular operating mode (power-on).
• ETH_MODE_ACTIVE_WITH_WAKEUP_REQUEST (0x02): Activates Rx and Tx communication, sets the hardware to the operating mode, and additionally triggers a wake-up request on the network if the hardware has wake-up capabilities (such as wake-up on the data line according to OPEN Alliance TC10).

In the stack interaction, Eth_ModeType specifically supports forwarding wake-up requests from the service layer (ComM) via the intermediate layers down to the communication drivers (EthTrcv), whereby hardware with wake-up and sleep functionality on the data line is controlled as needed ([SWS_Eth_91008]).

The enumeration type Eth_StateType is provided via header Eth_GeneralTypes.h and serves according to [SWS_Eth_00159] for state monitoring of the Ethernet driver. Its purpose is to support development error detection, whereby the current state according to the specification must be available for debugging purposes ([SWS_Eth_00159]).

For state management, Eth_StateType defines two discrete enumeration values ([SWS_Eth_00159]):

• ETH_STATE_UNINIT (value 0x00): Indicates that the Ethernet driver is not yet configured ([SWS_Eth_00159]).
• ETH_STATE_INIT (value 0x01): Indicates that the Ethernet driver is successfully configured ([SWS_Eth_00159]).

Regarding error handling and interaction, this state type forms the basis for internal error detection. It is likely to be assumed that driver APIs query this state and reject calls as long as the driver is in the uninitialized state ETH_STATE_UNINIT ([SWS_Eth_00159]). Question Q-35a17e3267274d70 (open) Only when the driver has transitioned to state ETH_STATE_INIT is it considered configured and ready for operation ([SWS_Eth_00159]). Since the type definition resides in Eth_GeneralTypes.h, it is available across drivers ([SWS_Eth_00159]).

Usage and Value Range

The enumeration type Eth_RxStatusType is defined according to [SWS_Eth_00162] in the header file Eth_GeneralTypes.h. It serves as an output parameter (out parameter) in the function Eth_Receive(), via which the Ethernet driver indicates whether an Ethernet frame was received and whether further frames are subsequently present in the buffer or data has been lost [SWS_Eth_00162].

The specification defines three discrete enumeration values for this type [SWS_Eth_00162]:

• ETH_RECEIVED (0x00): An Ethernet frame was received; no further frames are available in the controller.
• ETH_NOT_RECEIVED (0x01): No Ethernet frame was received; no further frames are present.
• ETH_RECEIVED_MORE_DATA_AVAILABLE (0x02): An Ethernet frame was received, and additional frames are available for retrieval.

Interaction during frame processing

When calling Eth_Receive(), the calling layer passes a pointer to a variable of type Eth_RxStatusType. The evaluation of this output parameter controls the further sequence of the reception cycle: The return value ETH_RECEIVED_MORE_DATA_AVAILABLE likely serves as a criterion for the caller to immediately call Eth_Receive() again in order to quickly process remaining frames from the receive buffer [SWS_Eth_00162]. Question Q-4ed309522aa004f8 (open) In contrast, the states ETH_RECEIVED and ETH_NOT_RECEIVED signal that the buffer is exhausted and no further data is pending for processing. Provision via Eth_GeneralTypes.h ensures uniform type usage across modules [SWS_Eth_00162].

Usage and purpose

According to [SWS_Eth_91004], the data type Eth_TxErrorCounterValuesType is specified as a structure for statistical counters for diagnostic purposes in the Ethernet driver. The definition is available via the header file Eth_GeneralTypes.h. The structure bundles several 32-bit counters (uint32) that represent specific transmission states and transmission impediments at the interface level.

Structure Components and Semantics

According to [SWS_Eth_91004], the individual counters are based on standardized network MIB definitions:

• Tx Dropped No Error Pkts: Number of outbound packets that were discarded despite an error-free state, for example to free buffer space (RFC1213 ifOutDiscards).
• Tx Dropped Error Pkts: Number of packets that could not be transmitted due to errors encountered (RFC1213 ifOutErrors).
• Tx Deferred Trans: Number of frames whose first transmission attempt was delayed because the transmission medium was busy (RFC1643 dot3StatsDeferredTransmissions).
• Tx Single Collision and Tx Multiple Collision: Successfully transmitted frames whose transmission was delayed by exactly one or by multiple collisions, respectively (RFC1643).
• Tx Late Collision: Collisions detected later than 512 bit times after the start of packet transmission (RFC1643 dot3StatsLateCollisions).
• Tx Excessive Collison: Number of transmissions that failed definitively as a result of excessive collisions (RFC1643 dot3StatsExcessiveCollisions).

Call Context and Restrictions

Interpretation: Since the specification extract does not list an associated API function, this diagnostic type is presumably passed as an output parameter via pointer to corresponding driver functions for counter retrieval. Question Q-2bfbe59d1fb81938 (open) Specific requirements for error handling, DET reports, or concurrency are not defined in the sources for this pure data structure.