4.11. ETHTRCV¶
4.11.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.11.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.11.3. Table of contents¶
4.11.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.11.5. Functional Overview¶
4.11.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.11.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.11.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.11.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.11.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.11.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.11.5.1.6. Interrupt Service Routine¶
EthTrcv driver does not provide any ISR.
4.11.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.11.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.11.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.11.5.5. Design overview (Link to the Architecture document and Design Document)¶
Will be updated in future release.
4.11.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.11.6. Deviations to requirements (Requirement Traceability)¶
4.11.6.1. Module Requirements¶
Will be updated in future release.
4.11.6.2. Deviation of requirements against AUTOSAR specification requirements¶
Will be updated in future release.
4.11.7. Integration Details¶
4.11.7.1. Dependency on Other Software Modules¶
4.11.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.11.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.11.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.11.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.11.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.11.7.1.6. Error Handling: Runtime Errors¶
There are no runtime errors.
4.11.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.11.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.11.7.2. Hardware - Software - ISR API name mapping¶
EthTrcv driver does not provide any ISR, it is taken care in Ethernet.
4.11.7.3. Scheduling Strategy¶
4.11.7.3.1. SchM¶
Beside the OS the BSW Scheduler provides functions that module EthTrcv calls at begin and end of critical sections.
4.11.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.11.8. API Description¶
4.11.8.1. Description of the API’s¶
Please refer MCAL_AM263_ApiGuide.CHM document provided as part of CSP.
4.11.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.11.8.3. Description on Non Standard API’s¶
Not Applicable.
4.11.9. Configuration Description¶
4.11.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.11.9.2. Parameter Description¶
4.11.9.2.1. Standard Configuration¶
Will be updated in future release.
4.11.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.11.9.3. Symbolic Names deviations¶
None
4.11.9.4. Configuration rules and constraints to enable plausibility checks¶
Not Applicable.
4.11.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.11.11. Memory footprint¶
Please refer Memory Footprint for more details.
4.11.12. Performance¶
Not Applicable.
4.11.13. Example Usage¶
4.11.13.1. Steps to build and run example¶
For Eth and EthTrcv we have common example, So please refer Eth - Example Usage
4.11.13.2. Example Logs¶
please refer Example Usage for Example Logs.
4.11.14. FAQ’s¶
None
4.11.15. Test Report (Link to test report)¶
Will be updated in future release
4.11.16. References¶
4.11.17. TI Disclaimer¶
Texas Instruments and its subsidiaries (TI) reserve the right to make changes to their products or to discontinue any product or service without notice, and advise customers to obtain the latest version of relevant information to verify, before placing orders, that information being relied on is current and complete. All products are sold subject to the terms and conditions of sale supplied at the time of order acknowledgment, including those pertaining to warranty, patent infringement, and limitation of liability.
TI warrants performance of its products to the specifications applicable at the time of sale in accordance with TI’s standard warranty. Testing and other quality control techniques are utilized to the extent TI deems necessary to support this warranty. Specific testing of all parameters of each device is not necessarily performed, except those mandated by government requirements.
Customers are responsible for their applications using TI components. In order to minimize risks associated with the customer’s applications, adequate design and operating safeguards must be provided by the customer to minimize inherent or procedural hazards.
TI assumes no liability for applications assistance or customer product design. TI does not warrant or represent that any license, either express or implied, is granted under any patent right, copyright, mask work right, or other intellectual property right of TI covering or relating to any combination, machine, or process in which such products or services might be or are used. TI’s publication of information regarding any third party’s products or services does not constitute TI’s approval, license, warranty or endorsement thereof.
Reproduction of information in TI data books or data sheets is permissible only if reproduction is without alteration and is accompanied by all associated warranties, conditions, limitations and notices. Representation or reproduction o f this information with alteration voids all warranties provided for an associated TI product or service, is an unfair and deceptive business practice, and TI is not responsible nor liable for any such use.
Resale of TI’s products or services with statements different from or beyond the parameters stated by TI for that product or service voids all express and any implied warranties for the associated TI product or service, is an unfair and deceptive business practice, and TI is not responsible nor liable for any such use.
Also see: Standard Terms and Conditions of Sale for Semiconductor Products https://www.ti.com/sc/docs/stdterms.htm
Mailing Address: Texas Instruments, Post Office Box 655303, Dallas, Texas 75265