开源小满EasyXMen
EthTSyn¶
文档信息 Document Information¶
版本历史 Version History¶
日期(Date) |
作者(Author) |
版本(Version) |
状态(Status) |
说明(Description) |
|---|---|---|---|---|
2025/2/27 |
shuangyang.fu |
V0.1 |
发布(Release) |
首次发布(First release) |
2025/04/04 |
shuangyang.fu |
V1.0 |
发布(Release) |
正式发布(Official release) |
参考文档 References¶
编号(Number) |
分类(Classification) |
标题(Title) |
版本(Version) |
|---|---|---|---|
1 |
Autosar |
AUTOSAR_SWS_SynchronizedTimeBaseManager.pdf |
R23-11 |
2 |
Autosar |
AUTOSAR_SWS_SynchronizedTimeBaseManager.pdf |
R24-11 |
3 |
Autosar |
AUTOSAR_PRS_TimeSyncProtocol.pdf |
R23-11 |
4 |
Autosar |
AUTOSAR_PRS_TimeSyncProtocol.pdf |
R24-11 |
5 |
Autosar |
AUTOSAR_SWS_TimeSyncOverEthernet.pdf |
R23-11 |
6 |
Autosar |
AUTOSAR_SWS_TimeSyncOverEthernet.pdf |
R24-11 |
7 |
IEEE |
IEEE Std 802.1AS-2011.pdf |
2011 |
术语与简写 Terms and Abbreviations¶
术语 Terms¶
术语(Terms) |
解释(Explanation) |
|---|---|
PTP |
一种高精度时间同步协议,可以到达亚微秒级精度(A high-precision time synchronization protocol that can achieve sub-microsecond accuracy) |
简写 Abbreviations¶
简写(Abbreviation) |
全称(Full name) |
解释(Explanation) |
|---|---|---|
STBM |
SynchronizedTimeBaseManager |
同步时基管理 |
<Bus>TSyn |
A bus specific Time Synchronization Provider module |
总线特定的时间同步提供程序模块 |
Follow_Up |
Time transport message (Follow-Up) |
时间传输消息(后续) |
ETH |
Ethernet |
以太网 |
EthTSyn |
Time Synchronization Provider module for Ethernet |
Eth提供的时间同步程序模块 |
SYNC |
Time synchronization message |
时间同步消息 |
简介 Introduction¶
EthTSyn模块负责确保以太网同步时间信息的采集和分发。它与StbM交互,并为StbM提供所有特定于以太网的功能。EthTSyn主要功能包括测量以太网消息之间的延迟和不同时基之前的时间同步。
The EthTSyn module is responsible for ensuring the collection and distribution of Ethernet synchronized time information. It interacts with StbM and provides all Ethernet-specific functions for StbM. The main functions of EthTSyn include measuring the delay between Ethernet messages and time synchronization before different time bases.
如图所示，EthTSyn模块处于AUTOSAR架构中的系统服务层，其依赖Ethif和StbM两个模块。
As shown in the figure, the EthTSyn module is located in the system service layer of the AUTOSAR architecture and depends on two modules, Ethif and StbM.
功能描述 Functional Description¶
特性 Features¶
周期时间同步 Periodic Time Synchronization¶
EthTSyn默认采用的是周期时间同步，作为主时钟（TIME_MASTER）的端口将以可配置的周期循环发送SYNC和FOLLOWUP报文。其中的全局同步时间将在FOLLOWUP报文中携带。从时钟（TIME_SLAVE）收到SYNC报文后，将会记下当前时间。当收到FOLLOWUP报文后，解析出携带的全局同步时间，最后计算出本地需要更新的全局时间进行最终的同步。
EthTSyn adopts periodic time synchronization by default. The port acting as the master clock (TIME_MASTER) will send SYNC and FOLLOWUP messages cyclically at a configurable period. The global synchronization time is carried in the FOLLOWUP message. After receiving the SYNC message, the slave clock (TIME_SLAVE) will record the current time. After receiving the FOLLOWUP message, parse out the carried global synchronization time, and finally calculate the global time that needs to be updated locally for final synchronization.
立即时间同步 Immediate Time Synchronization¶
除了周期的时间同步，EthTSyn还支持立即时间同步。通过上层APP调用stbm的立即时间同步接口StbM_TriggerTimeTransmission，EthTSyn模块将立即出发SYNC和Follow-Up报文的发送。
In addition to periodic time synchronization, EthTSyn also supports immediate time synchronization. By calling the immediate time synchronization interface StbM_TriggerTimeTransmission of stbm from the upper-layer APP, the EthTSyn module will immediately trigger the sending of SYNC and Follow-Up messages.
延迟测量 Delay Measurement¶
EthTSyn模块支持对网路延迟进行测量，测量发起方将发送Pdelay_Req报文，接收方收到请求报文后，将会恢复Pdelay_Response和Pdelay_Response_Followup报文。请求方通过计算可得到网络延迟。注意：因为AUTOSAR的时间同步符合802.1AS，要求时间同步是p2p的模式，即时间同步和网络延迟是相互独立进行的。
The EthTSyn module supports measuring network delay. The measurement initiator will send a Pdelay_Req message. After receiving the request message, the receiver will restore the Pdelay_Response and Pdelay_Response_Followup messages. The requester can calculate the network delay. Note: Because the time synchronization of AUTOSAR conforms to 802.1AS, the time synchronization is required to be in p2p mode, that is, time synchronization and network delay are performed independently of each other.
偏差 Deviation¶
1.不支持Time Recording
1.Time Recording is not supported
功能还未开发，将在后续版本中进行开发。
The function has not been developed yet and will be developed in subsequent versions.
2.不支持Security Events 和 Secure Time Synchronization
2.Security Events and Secure Time Synchronization are not supported
功能还未开发，将在后续版本中进行开发。
The function has not been developed yet and will be developed in subsequent versions.
3.不支持Time measurement with Switches
3.Time measurement with Switches is not supported
功能还未开发，将在后续版本中进行开发。
The function has not been developed yet and will be developed in subsequent versions.
扩展 Extension¶
None
集成 Integration¶
文件列表 File List¶
静态文件 Static Files¶
文件(File) |
描述(Description) |
|---|---|
EthTSyn.h |
实现EthTSyn模块全部外部接口的声明，以及配置文件中全局变量的声明(Implements the declaration of all external interfaces of the EthTSyn module and the declaration of global variables in the configuration file) |
EthTSyn_Types.h |
实现EthTSyn模块全部数据类型的声明(Implements the declaration of all data types of the EthTSyn module) |
EthTSyn.c |
作为EthTSyn模块的核心文件，实现EthTSyn模块全部对外接口，以及实现EthTSyn模块功能所必须的local函数，local宏定义，local变量定义(As the core file of the EthTSyn module, it implements all external interfaces of the EthTSyn module, as well as the local functions, local macro definitions, and local variable definitions necessary for implementing the functions of the EthTSyn module) |
动态文件 Dynamic Files¶
文件(File) |
描述(Description) |
|---|---|
EthTSyn_Cfg.h |
定义Com模块PC配置的宏定义(Defines the macro definitions for PC configuration of the Com module) |
EthTSyn_Cfg.c |
定义Com模块PC配置的结构体参数(Defines the structure parameters for PC configuration of the Com module) |
EthTSyn_PBcfg.c |
定义Com模块PB配置的结构体参数(Defines the structure parameters for PB configuration of the Com module) |
错误处理 Error Handling¶
开发错误 Development Errors¶
Error code |
Value[hex] |
Description |
|---|---|---|
ETHTSYN_E_UNINIT |
0x20 |
EthTSyn module is not initialized |
ETHTSYN_E_INIT_FAILED |
0x21 |
EthTSyn module initialization failed |
ETHTSYN_E_CTRL_IDX |
0x22 |
Invalid controller index |
ETHTSYN_E_PARAM_POINTER |
0x23 |
Invalid parameter pointer |
ETHTSYN_E_PARAM |
0x24 |
Invalid parameter |
ETHTSYN_E_ALREADY_INITIALIZED |
0x25 |
EthTSyn module is already initialized |
ETHTSYN_E_INVALID_PARTITION_CONTEXT |
0x26 |
Invalid partition context |
运行时错误 Runtime Errors¶
Error code |
Value[hex] |
Description |
|---|---|---|
ETHTSYN_E_TMCONFLICT |
0x01 |
Time Master conflict |
ETHTSYN_E_TSCONFLICT |
0x02 |
Time Slave conflict |
接口描述 Interface Description¶
类型定义 Type Definitions¶
Type Name |
Type |
Description |
|---|---|---|
EthTSyn_CrcTimeFlagsTxSecuredCfgType |
struct EthTSyn_CrcTimeFlagsTxSecuredCfgTypeTag |
This type shall Determine whether the CRC verification is enabled for each specific field under the sub-TLV. |
EthTSyn_CrcFlagsRxValidatedCfgType |
EthTSyn_CrcTimeFlagsTxSecuredCfgType |
This type shall Determine whether the CRC verification is enabled for each specific field under the sub-TLV. |
EthTSyn_GlobalTimeSlaveCfgType |
struct EthTSyn_GlobalTimeSlaveCfgTypeTag |
This type shall define the configuration of the time slave. |
EthTSyn_PdelayConfigCfgType |
struct EthTSyn_PdelayConfigCfgTypeTag |
This type shall define the configuration of the propagation delay. |
EthTSyn_GlobalTimeMasterCfgType |
struct EthTSyn_GlobalTimeMasterCfgTypeTag |
This type shall define the configuration of the time master. |
EthTSyn_PortRoleCfgType |
struct EthTSyn_PortRoleCfgTypeTag |
This type shall define the configuration of role of a port during the synchronization process. |
EthTSyn_PortRoleType |
enum EthTSyn_PortRoleTypeTag |
This type shall define the role of a port during time synchronization process. |
EthTSyn_PortConfigCfgType |
struct EthTSyn_PortConfigCfgTypeTag |
This type shall define the configuration of the port under a time domain. |
EthTSyn_GlobalTimeFollowUpDataIDListElementCfgType |
struct EthTSyn_GlobalTimeFollowUpDataIDListElementCfgTypeTag |
This type shall define the data ID,which is used for CRC caculation or message authentication. |
EthTSyn_GlobalTimeFollowUpDataIDListCfgType |
struct EthTSyn_GlobalTimeFollowUpDataIDListCfgTypeTag |
This type shall define the list of data ID,which is used for CRC caculation or message authentication. |
EthTSyn_GlobalTimeDomainCfgType |
struct EthTSyn_GlobalTimeDomainCfgTypeTag |
This type shall define the configuration of a time domain. |
EthTSynMessageType |
uint8 |
This definition specifies the types of messages that the EthTSyn module sends and receives. |
EthTSyn_PdelayTXStatusType |
enum EthTSyn_PdelayTXStatusTypeTag |
This type shall define the status of Pdelay Delay Measurement Requester during pdelay measurement. |
EthTSyn_PdelayRXStatusType |
enum EthTSyn_PdelayRXStatusTypeTag |
This type shall define the status of Pdelay Delay Measurement Receiver during pdelay measurement. |
EthTSyn_SyncStatusType |
enum EthTSyn_SyncStatusTypeTag |
This type shall define the status of a port during synchronization process. |
EthTSyn_TransmissionModeType |
enum EthTSyn_TransmissionModeTypeTag |
This type shall define the mode of transmission. |
EthTSyn_TimeStampType |
struct EthTSyn_TimeStampTypeTag |
This type shall define the format of global timestamp. |
EthTSyn_PdelayResponderTimestampType |
struct EthTSyn_PdelayResponderTimestampTypeTag |
This type shall define the type of ingress timestamp and egress timestamp during pdelay measurement. |
EthTSyn_SyncEgressTupleType |
struct EthTSyn_SyncEgressTupleTypeTag |
This type shall define the type of egress time tuple,which includes the global and local time. |
EthTSyn_PortType |
struct EthTSyn_PortTypeTag |
This type shall define the runtime variable of a port. |
EthTSyn_ConfigType |
struct EthTSyn_ConfigTypeTag |
This type shall define the configuration of EthTSyn. |
EthTSyn_PortRoleTypeTag |
enum |
This type shall define the role of a port during time synchronization process. |
EthTSyn_PdelayTXStatusTypeTag |
enum |
This type shall define the status of Pdelay Delay Measurement Requester during pdelay measurement. |
EthTSyn_PdelayRXStatusTypeTag |
enum |
This type shall define the status of Pdelay Delay Measurement Receiver during pdelay measurement. |
EthTSyn_SyncStatusTypeTag |
enum |
This type shall define the status of a port during synchronization process. |
EthTSyn_TransmissionModeTypeTag |
enum |
This type shall define the mode of transmission. |
提供的服务 Services¶
EthTSyn_Init¶
void EthTSyn_Init(const EthTSyn_ConfigType *configPtr)
This function initializes the Time Synchronization over Ethernet.
- Sync/Async
Synchronous
- Reentrancy
Non Reentrant
Parameters
Dir |
Name |
Description |
|---|---|---|
[in] |
configPtr |
Pointer to the selected configuration set. |
- Return type
void
EthTSyn_GetVersionInfo¶
void EthTSyn_GetVersionInfo(Std_VersionInfoType *versioninfo)
Returns the version information of this module.
- Sync/Async
Synchronous
- Reentrancy
Reentrant
Parameters
Dir |
Name |
Description |
|---|---|---|
[in] |
versioninfo |
Pointer to the memory location holding the version information of the module. |
- Return type
void
EthTSyn_SetTransmissionMode¶
void EthTSyn_SetTransmissionMode(uint8 ctrlIdx, EthTSyn_TransmissionModeType mode)
This API is used to turn on and off the TX capabilities of the EthTSyn.
- Sync/Async
Synchronous
- Reentrancy
Non Reentrant
Parameters
Dir |
Name |
Description |
|---|---|---|
[in] |
ctrlIdx |
Index of the Ethernet controller. |
[in] |
mode |
the mode of Transmission. |
- Return type
void
EthTSyn_RxIndication¶
void EthTSyn_RxIndication(uint8 ctrlIdx, Eth_FrameType frameType, boolean isBroadcast, const uint8 *physAddrPtr, const uint8 *dataPtr, uint16 lenByte)
By this API service the EthTSyn gets an indication and the data of a received frame.
- Sync/Async
Synchronous
- Reentrancy
Non Reentrant
Parameters
Dir |
Name |
Description |
|---|---|---|
[in] |
ctrlIdx |
Index of the Ethernet controller. |
[in] |
frameType |
frame type of received Ethernet frame |
[in] |
isBroadcast |
parameter to indicate a broadcast frame |
[in] |
physAddrPtr |
pointer to Physical source address (MAC address in network byte |
[in] |
dataPtr |
Pointer to payload of the received Ethernet frame (i.e. Ethernet header is not provided). |
[in] |
lenByte |
Length of received data. |
- Return type
void
EthTSyn_TxConfirmation¶
void EthTSyn_TxConfirmation(uint8 ctrlIdx, Eth_BufIdxType bufIdx, Std_ReturnType result)
Confirms the transmission of an Ethernet frame.
- Sync/Async
Synchronous
- Reentrancy
Non Reentrant
Parameters
Dir |
Name |
Description |
|---|---|---|
[in] |
ctrlIdx |
Index of the Ethernet controller within the context of the Ethernet Interface. |
[in] |
bufIdx |
Index of the buffer resource. |
[in] |
result |
E_OK: The transmission was successful, E_NOT_OK: The transmission failed. |
- Return type
void
EthTSyn_TrcvLinkStateChg¶
void EthTSyn_TrcvLinkStateChg(uint8 ctrlIdx, EthTrcv_LinkStateType trcvLinkState)
Allows resetting state machine in case of unexpected Link loss to avoid inconsistent Sync and Follow_Up sequences.
- Sync/Async
Synchronous
- Reentrancy
Non Reentrant
Parameters
Dir |
Name |
Description |
|---|---|---|
[in] |
ctrlIdx |
Index of the Ethernet controller within the context of the Ethernet Interface. |
[in] |
trcvLinkState |
ETHTRCV_LINK_STATE_DOWN ETHTRCV_LINK_STATE_ACTIVE |
- Return type
void
EthTSyn_MainFunction¶
void EthTSyn_MainFunction(uint8 portIndex)
Main function for cyclic call/resp.Sync, Follow_Up and Pdelay_Req transmissions.
- Sync/Async
Synchronous
- Reentrancy
Non Reentrant
Parameters
Dir |
Name |
Description |
|---|---|---|
[in] |
portIndex |
Index of the configured Port. |
- Return type
void
配置函数 Configuration function¶
EthTSyn_MainFunction_{{EthIfControllor.ShortName}}¶
void Nm_MainFunction_<NmChannel.ShortName>(void)
This function implements the transmission of message,which is running in the EthIfController.
- Sync/Async
Synchronous
- Reentrancy
Non Reentrant
- Return type
void
依赖的服务 Applicable Services¶
强制接口 Compulsory interface¶
API Function |
Header File |
Description |
|---|---|---|
Det_ReportRuntimeError |
Det.h |
Service to report runtime errors. If a callout has been configured then this callout shall be called. |
TcpIp_Bind |
TcpIp.h |
By this API service the TCP/IP stack is requested to bind a UDP or TCP socket to a local resource. |
可选接口 Optional Interface¶
API Function |
Header File |
Description |
|---|---|---|
Crc_CalculateCRC8H2F |
Crc.h |
This service makes a CRC8 calculation with the Polynomial 0x2F on Crc_Length. |
Det_ReportError |
Det.h |
Service to report development errors. |
EthIf_EnableEgressTimeStamp |
EthIf.h |
Activates egress time stamping on a dedicated message object. Some HW does store once the egress time stamp marker and some HW needs it always before transmission. There will be no “disable” functionality, due to the fact, that the message type is always “time stamped” by network design. |
EthIf_GetEgressTimeStamp |
EthIf.h |
Reads back the egress time stamp on a dedicated message object. It must be called within the TxConfirmation() function. |
EthIf_GetIngressTimeStamp |
EthIf.h |
Reads back the ingress time stamp on a dedicated message object. It must be called within the RxIndication() function. |
EthIf_ProvideTxBuffer |
EthIf.h |
Provides access to a transmit buffer of the specified Ethernet controller. |
EthIf_Transmit |
EthIf.h |
Triggers transmission of a previously filled transmit buffer |
StbM_BusSetGlobalTime |
StbM.h |
Allows the Time Base Provider Modules to forward the Rx Time Tuple to the StbM. |
StbM_GetCurrentTime |
StbM.h |
Returns a time tuple (Local time, Global time and Timebase status) and user data details Note: This API shall be called with locked interrupts / within an Exclusive Area to prevent interruption (i.e., the risk that the time stamp is outdated on return of the function call). |
StbM_GetCurrentVirtualLocalTime |
StbM.h |
Returns the Virtual Local Time of the referenced Time Base. |
StbM_GetTimeBaseStatus |
StbM.h |
Returns detailed status information for a Synchronized (or Pure Local) Time Base and, if called for an Offset Time Base, for the Offset Time Base and the underlying Synchronized Time Base. |
StbM_GetTimeBaseUpdateCounter |
StbM.h |
Allows the Timesync Modules to detect, whether a Time Base should be transmitted immediately in the subsequent <Bus>TSyn_MainFunction() cycle. |
配置 Configuration¶
支持硬件时间戳的时间同步 Time Synchronization Supporting Hardware Timestamp¶
时间同步的实现方式有两种，一种是通过硬件时间戳来实现，另一种是通过软件时间戳来实现。硬件时间戳的实现方式是通过硬件来实现时间戳的采集。
There are two ways to implement time synchronization, one is implemented through hardware timestamp, and the other is implemented through software timestamp. The hardware timestamp implementation method is to collect timestamps through hardware.
硬件时间戳是指获取时间的接口采用以太网硬件的时间戳功能，即通过调用EthIf的接口获取时间戳。对于主时间节点来说，由于时间同步对于精度的要求较高，又因为调用发送接口到报文真正从网口发出去是有时间延迟的，而如果不采用硬件时间戳的方式，是无法拿到较准确的报文出口时间，进而无法计算出准确的preciseOriginalTime，导致slave接收FollowUp报文后同步的精度下降。
Hardware timestamp means that the interface for obtaining time uses the timestamp function of Ethernet hardware, that is, the timestamp is obtained by calling the interface of EthIf. For the master time node, because time synchronization has high requirements for accuracy, and because there is a time delay from calling the sending interface to the message actually being sent from the network port, if the hardware timestamp method is not adopted, it is impossible to obtain a more accurate message exit time, and thus it is impossible to calculate an accurate preciseOriginalTime, resulting in a decrease in the accuracy of synchronization after the slave receives the FollowUp message.
同理，对于slave来说，如果不是用硬件时间戳，无法拿到准确的报文入口时间。
Similarly, for the slave, if hardware timestamp is not used, an accurate message entry time cannot be obtained.
下面是配置支持硬件时间戳的基本步骤：
The following are the basic steps to configure support for hardware timestamp:
通用配置的图片 (Picture of General Configuration)¶
如上图所示，在EthTSynGeneral中，开启支持硬件时间戳，即勾选EthTSynHardWareTimestampSupport。其他公共配置项，比如周期。
As shown in the figure above, in EthTSynGeneral, enable support for hardware timestamp, that is, check EthTSynHardWareTimestampSupport. Other common configuration items, such as period.
domain配置的图片 (Picture of Domain Configuration)¶
StbM时钟源配置的图片 (Picture of StbM Clock Source Configuration)¶
在EthTSynGlobalTimeDomain中，配置时间域的相关参数，比如时间域的ID，关联的时间基。
In EthTSynGlobalTimeDomain, configure the relevant parameters of the time domain, such as the ID of the time domain and the associated time base.
Attention
一个时间域可以配置多个Port，EthTSynGlobalTimeHardware是指当前时间域关联的StbM时间基所配的时钟源来自哪个以太网Port。EthTSynGlobalTimeHardware当且仅当该时间域所配的时间基（EthTSynSchronizedTimeBaseRef）下的StbMLocalTimeClock关联的为以太网时钟时，才会生效。
A time domain can be configured with multiple Ports. EthTSynGlobalTimeHardware refers to which Ethernet Port the clock source configured for the StbM time base associated with the current time domain comes from. EthTSynGlobalTimeHardware takes effect if and only if the time base (EthTSynSchronizedTimeBaseRef) configured in the time domain is associated with the Ethernet clock in StbMLocalTimeClock.
port配置的图片 (Picture of Port Configuration)¶
配置时间域下端口Port，比如时间同步角色EthTSynGlobalTimePortRole，SYNC和Follow-Up报文发送间隔EthTSynGlobalTimeDebounceTime，Port关联的EthIfController。
Configure the Port under the time domain, such as the time synchronization role EthTSynGlobalTimePortRole, the sending interval of SYNC and Follow-Up messages EthTSynGlobalTimeDebounceTime, and the EthIfController associated with the Port.
Master的配置的图片 (Picture of Master Configuration)¶
配置时间域下主时间节点的相关参数，比如立即同步恢复到周期同步的恢复时间EthTSynCyclicMsgResumeTime，报文发送周EthTSynGlobalTimeTxPeriod等。
Configure the relevant parameters of the master time node under the time domain, such as the recovery time from immediate synchronization to periodic synchronization EthTSynCyclicMsgResumeTime, the message sending period EthTSynGlobalTimeTxPeriod, etc.
EthIf配置1 (EthIf Configuration 1)¶
除了以上配置，为了支持硬件时间戳，还需要将Mcal的硬件时间戳功能打开。同时将硬件时间戳相关的接口注册到EthIf层，如上图所示。并且要将EthTSyn的连接状态回调注册到EthIf层，如下图所示。
In addition to the above configuration, in order to support hardware timestamp, the hardware timestamp function of Mcal also needs to be enabled. At the same time, register the interfaces related to hardware timestamp to the EthIf layer, as shown in the figure above. And register the connection status callback of EthTSyn to the EthIf layer, as shown in the figure below.
EthIf配置2 (EthIf Configuration 2)¶
Attention
另外，如果需要激活时间同步Master，需要首先在应用层通过调用StbM设置时间的接口StbM_SetGlobalTime设置本时间域的时间基的全局时间，调用EthTSyn_SetTransmissionMode激活传输状态。
In addition, if you need to activate the time synchronization Master, you first need to call the interface StbM_SetGlobalTime of StbM in the application layer to set the global time of the time base in this time domain, and call EthTSyn_SetTransmissionMode to activate the transmission state.