4.10. ETHTRCV¶
4.10.1. About This Document¶
Document Title |
User Guide of MCAL ETHTRCV Driver |
Document Version |
Version 1.3 |
Company |
Texas Instruments |
Document Name |
ETHTRCV User Guide |
4.10.2. Revision History¶
Version |
Date |
Revision History |
Status |
|---|---|---|---|
Version 1.0 |
05 Aug 2022 |
Initial Version |
Approved |
Version 1.1 |
08 May 2023 |
Example app Test procedure added |
Approved |
Version 1.2 |
12 Jun 2023 |
Updated as per HTML format. |
Approved |
Version 1.3 |
25 Aug 2023 |
Document release version column removed |
Approved |
4.10.3. Table of contents¶
4.10.4. Acronyms and Definitions¶
Acronyms and Definitions Used are presented in below table.
Acronyms |
Descriptions |
|---|---|
EC |
Ethernet controller |
ET |
Ethernet transceiver |
Eth |
Ethernet Controller Driver (AUTOSAR BSW module) |
EthIf |
Ethernet Interface (AUTOSAR BSW module) |
EthTrcv |
Ethernet Transceiver Driver (AUTOSAR BSW module) |
MCG |
Module Configuration Generator |
MII |
Media Independent Interface (standardized Interface provided by Ethernet controllers to access Ethernet transceivers) |
4.10.5. Functional Overview¶
4.10.5.1. Brief Overview¶
This document describes the functionality, API, and configuration of the AUTOSAR BSW module Ethernet Transceiver. The Ethernet transceiver driver is a hardware abstraction layer with a standardized interface to the Eth Interface layer.
Supported AUTOSAR Release |
4.3.1 |
Supported Configuration Variants |
Pre-Compile time, Link-time, post-build time |
Vendor ID |
ETHTRCV_VENDOR_ID (44) |
Module ID |
ETHTRCV_MODULE_ID (73) |
Supported Platform |
AM263x |
The EthTrcv module initializes and controls the Ethernet transceivers (commonly called as Ethernet PHYs). It provides services to configure all PHYs present on board to enable transfer of Ethernet frames. It uses MII APIs of Eth driver.
4.10.5.1.1. ETHTRCV Driver Architecture¶
The following figure shows where the EthTrcv is located in the AUTOSAR architecture.
Simplified View of the EthTrcv driver Architecture
Below figure shows EthTrcv driver in Ethernet stack module
Ethernet stack module overview
4.10.5.1.2. Initialization¶
EthTrcv_Init called to initialize the EthTrcv driver at power on, and on this the driver state will change to ETHTRCV_STATE_INIT.
The initialization covers the following steps #. Reset transceiver. #. Check link status and if link is up, configuring all transceiver configuration parameters (e.g., baud rate, duplex mode, automatic negotiation). #. Set loopback mode, if enabled in configuration.
4.10.5.1.3. States¶
The states and modes of the EthTrcv driver define whether the EthTrcv driver is operational or not. There are two states in which the Ethernet hardware/driver can be in.
ETHTRCV_STATE_UNINT: This is the state when the Driver is not yet configured.
ETHTRCV_STATE_INIT: This is the state when the Driver is configured and initialization was successful.
4.10.5.1.4. ETHTRCV modes¶
There are 2 modes in which the EthTrcv driver can be in.
ETHTRCV_MODE_DOWN: This mode can be set by the EthTrcv_SetTransceiverMode to disable the EthTrcv.
ETHTRCV_MODE_ACTIVE: This is the state in which the hardware is initialized and is running.
The states and modes coexist. The modes of the driver can be changed by the API EthTrcv_SetTransceiverMode.
4.10.5.1.5. Auto-negotiation¶
In Auto negotiation Ethernet controller and Transceiver (PHY) choose common transmission parameters, such as speed, duplex mode, and flow control. They first share their capabilities regarding these parameters and then choose the highest performance transmission mode they both support.
EthTrcv driver initiates auto-negotiation process. Also, separate API EthTrcv_StartAutoNegotiation can be used. The parameters used for auto-negotiation are passed during initialization through structure EthTrcv Config.
4.10.5.1.6. Interrupt Service Routine¶
EthTrcv driver does not provide any ISR.
4.10.5.2. Supported and Not Supported Features¶
Features Supported |
AUTOSAR Supported Features |
Features Not Supported |
|---|---|---|
10, 100 Mbps Full and Half Duplex |
Initialization of ETHTRCV. |
1000 Mbps half-duplex mode (As it is not supporting in AM263x Ethernet) |
1000 Mbps Full Duplex |
Enable Auto-negotiation. |
SGMII MAC Interface not supported by software as it is not supported in am263x Ethernet. |
Auto-Negotiation for all Speeds |
Configuration of Speed, Duplex mode, and Baud rate. |
MII MAC Interface supported by hardware but not implemented |
Link monitoring |
Link monitoring. |
Wakeup mode features supported by PHY but not implemented because DP83869HM is industrial PHY not an automotive PHY |
Loop Back Mode |
||
RGMII MAC Interface |
||
Supported PHY : DP83869HM |
4.10.5.3. Assumptions¶
The Ethernet BSW stack is intended to be used wherever high data rates are required but no hard real-time is required. Of course, it can also be used for less-demanding use cases, i.e. for low data rates.
4.10.5.4. Limitations¶
The Ethernet Transceiver Driver module is only able to handle a single thread of execution. The execution must not be pre-empted by itself.
4.10.5.5. Design overview (Link to the Architecture document and Design Document)¶
Will be updated in future release.
4.10.5.6. File Structure¶
Static source C File is defined below in the table.
File Name |
Description |
|---|---|
EthTrcv.h |
Contains the APIs of the EthTrcv driver to be used |
EthTrcv.c |
Contains the implementation of the APIs for EthTrcv |
EthTrcv_Priv.c |
Contains module private functions used by main APIs. |
EthTrcv_Priv.h |
Internal header file. |
Plugin File is defined below in the table.
EthTrcv_Cfg.h |
Contains the pre-complier switches. |
EthTrcv_Cfg.c |
Contains the Pre compile configuration parameters. |
EthTrcv_Lcfg.c |
Contains the Link time configuration parameters. |
EthTrcv_PBcfg.c |
Contains the Post build configuration parameters. |
The below diagram shows the files structure for the ETHTRCV driver.
Fig. 4.6 Figure 1: File Structure¶
4.10.6. Deviations to requirements (Requirement Traceability)¶
4.10.6.1. Module Requirements¶
Will be updated in future release.
4.10.6.2. Deviation of requirements against AUTOSAR specification requirements¶
Will be updated in future release.
4.10.7. Integration Details¶
4.10.7.1. Dependency on Other Software Modules¶
4.10.7.1.1. Eth Driver¶
EthTrcv driver depends on Ethernet Controller Driver (Eth) for transceiver access via Media Independent Interface (MII). Eth APIs Eth_ReadMII and Eth_WriteMII are used by EthTrcv for accessing transceiver registers.
4.10.7.1.2. MCU¶
The module MCU powers up the microcontroller peripherals at startup time and initializes the PLL and the internal clock domains which go to the Ethernet controller. No specific initialization needed for transceiver.
4.10.7.1.3. PORT¶
No specific port configuration is needed for EthTrcv driver, though to access transceiver registers we need port configuration which is done as a part of Eth driver port configuration.
4.10.7.1.4. AUTOSAR OS (Optional)¶
An operating system can be used for task scheduling, interrupt handling, global suspend and restore of interrupts and creating of the Interrupt Vector Table. The EthTrcv module may use OSEK/AUTOSAR OS to suspend and restore global interrupts.
4.10.7.1.5. Error Handling: DET¶
The module EthTrcv depends on the DET (by default) to report development errors. Detection and reporting of development errors can be enabled or disabled by the switch “Enable Development Error Detection” on the tab “General Settings” within the module EthTrcv.
The DET can be replaced optionally by an equivalent component which is responsible to recognize development errors, if no DET component is available.
Type of Error |
Relevance |
Related Error code |
Value (Hex) |
|---|---|---|---|
API service called with wrong transceiver index. |
Development |
ETHTRCV_E_INV_TRCV_IDX |
[0x1] |
API service called when transceiver is not initialized. |
Development |
ETHTRCV_E_UNINIT |
[0x2] |
API is called with wrong pointer value (e.g., NULL pointer) |
Development |
ETHTRCV_E_PARAM_POINTER |
[0x3] |
API is called with not supported mode |
Development |
ETHTRCV_E_NOT_SUPPORTED |
[0x4] |
The following table shows which parameter checks are performed on which services:
Services |
ETHTRCV_E_INV_TRCV_IDX |
ETHTRCV_E_UNINIT |
ETHTRCV_E_PARAM_POINTER |
ETHTRCV_E_NOT_SUPPORTED |
|---|---|---|---|---|
EthTrcv_Init |
x |
x |
||
EthTrcv_SetTransceiverMode |
x |
x |
||
EthTrcv_GetTransceiverMode |
x |
x |
x |
|
EthTrcv_StartAutoNegotiation |
x |
x |
||
EthTrcv_GetLinkState |
x |
x |
x |
|
EthTrcv_GetBaudRate |
x |
x |
x |
|
EthTrcv_GetDuplexMode |
x |
x |
x |
|
EthTrcv_WriteMiiIndication |
||||
EthTrcv_ReadMiiIndication |
||||
EthTrcv_GetVersionInfo |
x |
|||
EthTrcv_MainFunction |
x |
|||
EthTrcv_SetPhyTestMode |
x |
x |
x |
|
EthTrcv_SetPhyLoopbackMode |
x |
x |
x |
|
EthTrcv_GetPhySignalQuality |
x |
x |
x |
|
EthTrcv_SetPhyTxMode |
x |
x |
x |
|
EthTrcv_GetCableDiagnosticsResult |
x |
x |
x |
|
EthTrcv_GetPhyIdentifier |
x |
x |
x |
4.10.7.1.6. Error Handling: Runtime Errors¶
There are no runtime errors.
4.10.7.1.7. Error Handling: DEM¶
By default, production code related errors are reported to the DEM using the service Dem_SetEventStatus().
The errors reported to DEM are described in the following table:
Error Code |
Description |
|
|---|---|---|
Assigned by DEM |
ETHTRCV_E_ACCESS |
This error is raised when monitoring the access to the Ethernet Transceiver fails. |
Assigned by DEM |
ETHTRCV_E_HARDWARE_ERROR |
This error is reference to the DemEventParameter which shall be issued when the error " Timeout on blocking API call occurs " has occurred |
4.10.7.1.8. Callback Notification¶
EthTrcv have two Callback Notifications:
EthTrcv_ReadMiiIndication : Called when information has been read out via MII interface. Triggered by previous Eth_ReadMii call. EthTrcv_ReadMiiIndication can directly be called within Eth_ReadMii.
EthTrcv_WriteMiiIndication : Called when information has been written via MII interface. Triggered by previous Eth_WriteMii call. EthTrcv_WriteMiiIndication can directly be called within Eth_WriteMii.
4.10.7.2. Hardware - Software - ISR API name mapping¶
EthTrcv driver does not provide any ISR, it is taken care in Ethernet.
4.10.7.3. Scheduling Strategy¶
4.10.7.3.1. SchM¶
Beside the OS the BSW Scheduler provides functions that module EthTrcv calls at begin and end of critical sections.
4.10.7.3.2. Critical Sections¶
There is only one kind of critical sections in this driver. Within these sections all read /modify/write accesses to internal EthTrcv status variables must be protected. Therefore, switching to tasks that also access EthTrcv must be avoided and all EthTrcv interrupts have to be suspended.
4.10.8. API Description¶
4.10.8.1. Description of the API’s (Can be referred to Api Guide spec)¶
Will be updated in future release.
4.10.8.2. API’s with Service ID¶
The following table presents the service IDs and the related services:
Autosar API’s Supported:
Service ID |
Autosar API’s Supported |
Autosar API’s not Supported |
|---|---|---|
0x01 |
EthTrcv_Init |
|
0x03 |
EthTrcv_SetTransceiverMode |
|
0x04 |
EthTrcv_GetTransceiverMode |
|
0x05 |
EthTrcv_StartAutoNegotiation |
|
0x06 |
EthTrcv_GetLinkState |
|
0x07 |
EthTrcv_GetBaudRate |
|
0x08 |
EthTrcv_GetDuplexMode |
|
0x09 |
EthTrcv_ReadMiiIndication |
|
0x0A |
EthTrcv_WriteMiiIndication |
|
0x0B |
EthTrcv_GetVersionInfo |
|
0x0C |
EthTrcv_MainFunction |
|
0x10 |
EthTrcv_GetPhySignalQuality |
|
0x11 |
EthTrcv_SetPhyTestMode |
|
0x12 |
EthTrcv_SetPhyLoopbackMode |
|
0x13 |
EthTrcv_SetPhyTxMode |
|
0x14 |
EthTrcv_GetCableDiagnosticsResult |
|
0x15 |
EthTrcv_GetPhyIdentifier |
|
0x0D |
EthTrcv_SetTransceiverWakeupMode |
|
0x0E |
EthTrcv_GetTransceiverWakeupMode |
|
0x0F |
EthTrcv_CheckWakeup |
Refer Autosar SWS for API description mentioned in above table.
4.10.8.3. Description on Non Standard API’s¶
Not Applicable.
4.10.9. Configuration Description¶
4.10.9.1. Configuration Variants¶
The ETHTRCV is configured through GUI in Post-Build, Pre-Compile and Link-Time Variants.
Variants
|
Configured Files
|
|---|---|
PostBuild |
EthTrcv_PBcfg.c , EthTrcv_Cfg.h |
Pre-Compile |
EthTrcv_Cfg.c , EthTrcv_Cfg.h |
Link-Compile |
EthTrcv_Lcfg.c , EthTrcv_Cfg.h |
4.10.9.2. Parameter Description¶
4.10.9.2.1. Standard Configuration¶
Will be updated in future release.
4.10.9.2.2. IP Specific Configuration¶
IP Name |
Description |
|---|---|
EthTrcvEnableLoopback |
To enable Phy loopback for Test purpose |
EthTrcvGigabitCapabilityEnabled |
To enable GigabitCapability for Test purpose |
ETHTRCV_E_HARDWARE_ERROR |
Reference to the DemEventParameter which shall be issued when the error " Timeout on blocking API call occurs " has occurred |
EthTrcvCapabTypeEnum |
Enumerates Advertisement configurations |
EthTrcvPhyAdvertiseCapability |
This parameter defines the transceiver advertise capability |
EthTrcvLinkPartnerCapability |
This parameter defines the transceiver Link partner capability |
EthTrcvAutoNegotiationWaitCountTicks |
Ethernet Tranceiver delay after autonetotiation started to autonegotiation completed. Transceiver (PHY) sets auto-negotiation status bit in status register once it is complete. Depending on Transceiver type, MDIO frequence it will take different time. change count value if transceiver detection fails in auto-negotiation. For auto-negotiation configuring wait count to 100ms. |
EthTrcvLinkStatusWaitCountTicks |
Wait for link status to become up after configuration |
EthTrcvMaxControllersSupported |
This is for Maximum Controller Supported |
EthTrcvMaxTrcvConfigSupported |
Maximum number of configurations supported. The config Index passed to EthTrcv APIs should be less than this value |
EthTrcvDefaultOSCounterId |
Default Os Counter Id if node reference to OsCounter ref EthTrcvOsCounterRef is not set |
EthTrcvTimeoutDuration |
ETHTRCV timeout - used in ETHTRCV busy wait |
EthTrcvInternalLoopbackMode |
Configures Internal Loopback mode to Analog or Digital |
EthTrcvOsCounterRef |
This parameter contains a reference to the OsCounter, which is used by the ETHTRCV driver |
EthTrcvDeviceVariant |
To Select SOC AM263x Variant |
4.10.9.3. Symbolic Names deviations¶
None
4.10.9.4. Configuration rules and constraints to enable plausibility checks¶
Not Applicable.
4.10.10. Memory Mapping¶
The objects (e.g., variables, functions, constants) are declared by compiler independent definitions – the compiler abstraction definitions. Each compiler abstraction definition is assigned to a memory section. The following table contains the memory section names and the compiler abstraction definitions defined for the EthTrcv and illustrate their assignment among each other.
Memory Mapping Sections |
ETHTRCV_CODE |
ETHTRCV_VAR |
ETHTRCV_VAR_NOINIT |
ETHTRCV_CONST |
|---|---|---|---|---|
ETHTRCV_START_SEC_VAR_INIT_UNSPECIFIED (.data) |
x |
|||
ETHTRCV_STOP_SEC_VAR_INIT_UNSPECIFIED |
x |
|||
ETHTRCV_START_SEC_CODE (.text) |
x |
|||
ETHTRCV_STOP_SEC_CODE |
x |
|||
ETHTRCV_START_SEC_VAR_NO_INIT_UNSPECIFIED (.bss) |
x |
|||
ETHTRCV_STOP_SEC_VAR_NO_INIT_UNSPECIFIED |
x |
|||
ETHTRCV_START_SEC_CONST_UNSPECIFIED (. const)] |
x |
|||
ETHTRCV_STOP_SEC_CONST_UNSPECIFIED |
x |
|||
ETHTRCV_START_SEC_CODE_ISR (.text) |
x |
|||
ETHTRCV_STOP_SEC_CODE_ISR |
x |
4.10.11. Memory footprint¶
Please refer Memory Footprint for more details.
4.10.12. Performance¶
Not Applicable.
4.10.13. Example Usage¶
4.10.13.1. Steps to build and run example¶
For Eth and EthTrcv we have common example, So please refer Eth - Example Usage
4.10.13.2. Example Logs¶
please refer Example Usage for Example Logs.
4.10.14. FAQ’s¶
None
4.10.15. Test Report (Link to test report)¶
Will be updated in future release
4.10.16. References¶
Autosar SWS 4.3.1 will be updated in future release.
4.10.17. Disclaimer¶
Will be updated in future release.