开源小满EasyXMen
Tm¶
文档信息(Document Information)¶
版本历史(Version History)¶
日期(Date) |
作者(Author) |
版本(Version) |
状态(Status) |
说明(Description) |
|---|---|---|---|---|
2025/01/24 |
xudong.guan |
V0.1 |
发布(Release) |
首次发布(First release) |
2025/04/04 |
xudong.guan |
V1.0 |
发布(Release) |
正式发布(Official release) |
参考文档(References)¶
编号(Number) |
分类(Classification) |
标题(Title) |
版本(Version) |
|---|---|---|---|
1 |
Autosar |
AUTOSAR_CP_SRS_TimeService.pdf |
R23-11 |
2 |
Autosar |
AUTOSAR_CP_SWS_TimeService.pdf |
R23-11 |
术语与简写(Terms and Abbreviations)¶
术语(Terms)¶
术语(Term) |
解释(Explanation) |
|---|---|
GPT Predef Timer |
GPT Predef Timer是由GPT driver提供的自由运行的向上计数器。哪些GPT Predef Timer可用取决于硬件(时钟、硬件定时器、预分频器、定时器寄存器宽度等)和配置。GPT Predef Timer具有预定义的物理时间单位和范围(A GPT Predef Timer is a free-running up counter provided by the GPT driver. Available GPT Predef Timers depend on hardware (clock, hardware timers, prescaler, timer register width, etc.) and configuration. GPT Predef Timers have predefined physical time units and ranges.) |
Time Service Predef Timer |
Time Service Predef Timer是具有预定义物理时间单位和范围的自由运行向上计数器。其硬件定时器功能基于对应的GPT Predef Timer实现。Time Service模块会为每个Predef Timer提供一组API services。用户可实例化任意数量的定时器(仅受可用内存限制)，且各定时器实例的使用完全相互独立。(A Time Service Predef Timer is a free-running up counter with predefined physical time units and ranges. Its hardware timer functionality is based on corresponding GPT Predef Timers. The Time Service module provides a set of API services for each Predef Timer. Users can instantiate any number of timers (limited only by available memory), and timer instances operate completely independently.) |
Timer instance |
timer instance是API数据类型Tm_PredefTimer…bitType的数据对象，这意味着它是Time Service Predef Timer在用户软件层面的实例化产物。用户可实例化任意数量的定时器(仅受可用内存限制)。通过API services提供的方法，各timer instance的使用可完全相互独立。(A timer instance is a data object of API data type Tm_PredefTimer…bitType, meaning it instantiates a Time Service Predef Timer at the user software level. Users can instantiate any number of timers (limited only by available memory). Through methods provided by API services, timer instances operate completely independently.) |
Reference time |
reference time是为每个timer instance存储的时间值。它是API数据类型Tm_PredefTimer…bitType中一个与实现相关的元素。(Reference time is the time value stored for each timer instance. It is an implementation-specific element of the API data types Tm_PredefTimer…bitType.) |
简写(Abbreviations)¶
简写(Abbreviation) |
全称(Full name) |
解释(Explanation) |
|---|---|---|
GPT |
General Purpose Timer |
通用定时器模块，提供高精度定时功能，提供接口作为Tm模块获取时间来源基础。(General Purpose Timer module providing high-precision timing functions and interfaces as time source for Tm module.) |
nop |
No operation |
无操作。 |
简介(Introduction)¶
如图所示Tm模块位于系统服务，所有层都可以使用系统服务。Tm模块可以越过一个软件层来访问GPT，而GPT不能与其他MCAL模块直接产生交互。
As shown in the figure, the Tm module is located in system services accessible to all layers. The Tm module can access GPT across a software layer, while GPT cannot directly interact with other MCAL modules.
复杂驱动和ECU抽象层与GPT存在交互，但不受Tm模块影响。
Complex drivers and the ECU Abstraction Layer interact with GPT but remain unaffected by the Tm module.
Tm架构层次图 (Tm Architecture Hierarchy Diagram)¶
Tm Architecture Hierarchy Diagram
功能描述(Functional Description)¶
特性(Features)¶
Tm功能介绍(Introduction to Tm Functions)¶
Tm模块通过直接访问GPT硬件，经过一定转换后给其他BSW模块提供接口从而可以初始化一个时钟，随时获取其经过时间，或者可以主动忙碌等待一段时间，并可以对时钟进行偏移等操作。
The Tm module directly accesses GPT hardware and, after conversions, provides interfaces for other BSW modules to initialize timers, retrieve elapsed time, perform busy waits, and apply clock offsets.
不同种类的时钟，也称为”Tm预定义时钟”，在硬件的和配置支持下存在。每一个预定义时钟都有一个预定义的tick duration(最小单位记录时长)和一个预定义的字节数(物理范围)。这些预定义时钟是基于GPT预定义时钟的，这是GPT驱动提供的自由运行的硬件时钟。
Various timer types, termed “Tm predefined timers”, are available with hardware and configuration support. Each predefined timer has a predefined tick duration (minimum time unit) and bit width (physical range). These predefined timers are based on GPT predefined timers - free-running hardware counters provided by the GPT driver.
共有以下四种预定义时钟：Tm_PredefTimer1us16bitType，Tm_PredefTimer1us24bitType，Tm_PredefTimer1us32bitType，Tm_PredefTimer100us32bitType。(前一项为tick duration，后一项为字节大小)。
Four predefined timers are available: Tm_PredefTimer1us16bitType, Tm_PredefTimer1us24bitType, Tm_PredefTimer1us32bitType, and Tm_PredefTimer100us32bitType. (First value indicates tick duration, second indicates bit width).
那么，Tm提供的服务也都支持这四种时钟。相关服务有：Tm_ResetTimer…, Tm_GetTimeSpan…, Tm_ShiftTimer…, Tm_SyncTimer…, Tm_BusyWait…。注意100us不支持BusyWait。
Tm services support all four timer types. Related services include: Tm_ResetTimer…, Tm_GetTimeSpan…, Tm_ShiftTimer…, Tm_SyncTimer…, Tm_BusyWait… Note: 100us timers do not support BusyWait.
集成(Integration)¶
文件列表(File List)¶
静态文件(Static Files)¶
文件(File) |
描述(Description) |
|---|---|
Tm.c |
Tm模块源码文件，包含需要使用的宏定义，内部变量，内部函数，全局函数。(Source code files of the Tm module, containing required macro definitions, internal variables, internal functions, and global functions.) |
Tm.h |
Tm模块头文件，包含需要使用的宏定义，类型定义，配置结构体声明，外部函数声明。(Header file of the Tm module, containing required macro definitions, type definitions, configuration structure declarations, and external function declarations.) |
Tm_MemMep.h |
Tm的内存映射定义文件。(Memory mapping definition file of the Tm module.) |
动态文件(Dynamic Files)¶
文件(File) |
描述(Description) |
|---|---|
Tm_Cfg.h |
Tm模块配置头文件，包含配置宏定义。(Configuration header file of the Tm module, containing configuration macro definitions.) |
错误处理(Error Handling)¶
开发错误(Development Errors)¶
Error code |
Value[hex] |
Description |
|---|---|---|
TM_E_PARAM_POINTER |
0x01 |
调用API服务的时候传入了非法(例如空指针)的指针。(Invalid pointer (e.g., null pointer) passed during API service call.) |
TM_E_PARAM_VALUE |
0x02 |
调用API服务的时候传入了非法的参数。(Invalid parameter passed during API service call.) |
产品错误(Product Errors)¶
None
运行时错误(Runtime Errors)¶
TM_E_HARDWARE_TIMER
0x03
访问底层硬件计时器(GPT Predef Timer)失败。(Failed to access the underlying hardware timer (GPT Predef Timer).)
接口描述(Interface Description)¶
类型定义(Type Definitions)¶
Type Name |
Type |
Description |
|---|---|---|
Tm_PredefTimer1us16bitType |
struct Tm_PredefTimer1us16bitTypeTag |
Data type of Time Service Predef Timer 1us16bit. The structure contains the reference time. |
Tm_PredefTimer1us24bitType |
struct Tm_PredefTimer1us24bitTypeTag |
Data type of Time Service Predef Timer 1us24bit. The structure contains the reference time. |
Tm_PredefTimer1us32bitType |
struct Tm_PredefTimer1us32bitTypeTag |
Data type of Time Service Predef Timer 1us32bit. The structure contains the reference time. |
Tm_PredefTimer100us32bitType |
struct Tm_PredefTimer100us32bitTypeTag |
Data type of Time Service Predef Timer 100µs32bit. The structure contains the reference time. |
提供的服务(Services)¶
Tm_GetVersionInfo¶
void Tm_GetVersionInfo(Std_VersionInfoType *versioninfo)
Returns the version information of this module..
- Sync/Async
TRUE
- Reentrancy
Reentrant
Parameters
Dir |
Name |
Description |
|---|---|---|
[out] |
versioninfo |
to where to store the version information of this module. |
- Return type
void
Tm_ResetTimer1us16bit¶
Std_ReturnType Tm_ResetTimer1us16bit(Tm_PredefTimer1us16bitType *TimerPtr)
Resets a timer instance (user point of view).
- Sync/Async
TRUE
- Reentrancy
Reentrant but not for the same timer instance
Parameters
Dir |
Name |
Description |
|---|---|---|
[out] |
TimerPtr |
to a timer instance defined by the user. |
- Return type
Std_ReturnType
Return values
Name |
Description |
|---|---|
E_OK |
The underlying GPT driver service has returned E_OK and no development error has been detected |
E_NOT_OK |
The underlying GPT driver service has returned E_NOT_OK, or a development error has been detected |
Tm_GetTimeSpan1us16bit¶
Std_ReturnType Tm_GetTimeSpan1us16bit(const Tm_PredefTimer1us16bitType *TimerPtr, uint16 *TimeSpanPtr)
Delivers the time difference (current time - reference time).
- Sync/Async
TRUE
- Reentrancy
Reentrant but not for the same timer instance
Parameters
Dir |
Name |
Description |
|---|---|---|
[in] |
TimerPtr |
to a timer instance defined by the user. |
[out] |
TimeSpanPtr |
to time span destination data in RAM. |
- Return type
Std_ReturnType
Return values
Name |
Description |
|---|---|
E_OK |
The underlying GPT driver service has returned E_OK and no development error has been detected |
E_NOT_OK |
The underlying GPT driver service has returned E_NOT_OK, or a development error has been detected |
Tm_ShiftTimer1us16bit¶
void Tm_ShiftTimer1us16bit(Tm_PredefTimer1us16bitType *TimerPtr, uint16 TimeValue)
Shifts the reference time of the timer instance.
- Sync/Async
TRUE
- Reentrancy
Reentrant but not for the same timer instance
Parameters
Dir |
Name |
Description |
|---|---|---|
[in] |
TimerPtr |
to a timer instance defined by the user. |
[out] |
TimeValue |
value in us, the reference time has to be shifted. |
- Return type
void
Tm_SyncTimer1us16bit¶
void Tm_SyncTimer1us16bit(Tm_PredefTimer1us16bitType *TimerDstPtr, const Tm_PredefTimer1us16bitType *TimerSrcPtr)
Synchronizes two timer instances.
- Sync/Async
TRUE
- Reentrancy
Reentrant but not for the same timer instance
Parameters
Dir |
Name |
Description |
|---|---|---|
[out] |
TimerDstPtr |
to the destination timer instance defined by the user. |
[in] |
TimerSrcPtr |
to the source timer instance defined by the user. |
- Return type
void
Tm_BusyWait1us16bit¶
Std_ReturnType Tm_BusyWait1us16bit(uint8 WaitingTimeMin)
Performs busy waiting by polling with a guaranteed minimum waiting time.
- Sync/Async
TRUE
- Reentrancy
Reentrant
Parameters
Dir |
Name |
Description |
|---|---|---|
[in] |
WaitingTimeMin |
waiting time in microseconds. |
- Return type
Std_ReturnType
Return values
Name |
Description |
|---|---|
E_OK |
The underlying GPT driver service has returned E_OK and no development error has been detected |
E_NOT_OK |
The underlying GPT driver service has returned E_NOT_OK, or a development error has been detected |
Tm_ResetTimer1us24bit¶
Std_ReturnType Tm_ResetTimer1us24bit(Tm_PredefTimer1us24bitType *TimerPtr)
Resets a timer instance (user point of view).
- Sync/Async
TRUE
- Reentrancy
Reentrant but not for the same timer instance
Parameters
Dir |
Name |
Description |
|---|---|---|
[out] |
TimerPtr |
to a timer instance defined by the user. |
- Return type
Std_ReturnType
Return values
Name |
Description |
|---|---|
E_OK |
The underlying GPT driver service has returned E_OK and no development error has been detected |
E_NOT_OK |
The underlying GPT driver service has returned E_NOT_OK, or a development error has been detected |
Tm_GetTimeSpan1us24bit¶
Std_ReturnType Tm_GetTimeSpan1us24bit(const Tm_PredefTimer1us24bitType *TimerPtr, uint32 *TimeSpanPtr)
Delivers the time difference (current time - reference time).
- Sync/Async
TRUE
- Reentrancy
Reentrant but not for the same timer instance
Parameters
Dir |
Name |
Description |
|---|---|---|
[in] |
TimerPtr |
to a timer instance defined by the user. |
[out] |
TimeSpanPtr |
to time span destination data in RAM. |
- Return type
Std_ReturnType
Return values
Name |
Description |
|---|---|
E_OK |
The underlying GPT driver service has returned E_OK and no development error has been detected |
E_NOT_OK |
The underlying GPT driver service has returned E_NOT_OK, or a development error has been detected |
Tm_ShiftTimer1us24bit¶
void Tm_ShiftTimer1us24bit(Tm_PredefTimer1us24bitType *TimerPtr, uint32 TimeValue)
Shifts the reference time of the timer instance.
- Sync/Async
TRUE
- Reentrancy
Reentrant but not for the same timer instance
Parameters
Dir |
Name |
Description |
|---|---|---|
[in] |
TimerPtr |
to a timer instance defined by the user. |
[out] |
TimeValue |
value in us, the reference time has to be shifted. |
- Return type
void
Tm_SyncTimer1us24bit¶
void Tm_SyncTimer1us24bit(Tm_PredefTimer1us24bitType *TimerDstPtr, const Tm_PredefTimer1us24bitType *TimerSrcPtr)
Synchronizes two timer instances.
- Sync/Async
TRUE
- Reentrancy
Reentrant but not for the same timer instance
Parameters
Dir |
Name |
Description |
|---|---|---|
[out] |
TimerDstPtr |
to the destination timer instance defined by the user. |
[in] |
TimerSrcPtr |
to the source timer instance defined by the user. |
- Return type
void
Tm_BusyWait1us24bit¶
Std_ReturnType Tm_BusyWait1us24bit(uint8 WaitingTimeMin)
Performs busy waiting by polling with a guaranteed minimum waiting time.
- Sync/Async
TRUE
- Reentrancy
Reentrant
Parameters
Dir |
Name |
Description |
|---|---|---|
[in] |
WaitingTimeMin |
waiting time in microseconds. |
- Return type
Std_ReturnType
Return values
Name |
Description |
|---|---|
E_OK |
The underlying GPT driver service has returned E_OK and no development error has been detected |
E_NOT_OK |
The underlying GPT driver service has returned E_NOT_OK, or a development error has been detected |
Tm_ResetTimer1us32bit¶
Std_ReturnType Tm_ResetTimer1us32bit(Tm_PredefTimer1us32bitType *TimerPtr)
Resets a timer instance (user point of view).
- Sync/Async
TRUE
- Reentrancy
Reentrant but not for the same timer instance
Parameters
Dir |
Name |
Description |
|---|---|---|
[out] |
TimerPtr |
to a timer instance defined by the user. |
- Return type
Std_ReturnType
Return values
Name |
Description |
|---|---|
E_OK |
The underlying GPT driver service has returned E_OK and no development error has been detected |
E_NOT_OK |
The underlying GPT driver service has returned E_NOT_OK, or a development error has been detected |
Tm_GetTimeSpan1us32bit¶
Std_ReturnType Tm_GetTimeSpan1us32bit(const Tm_PredefTimer1us32bitType *TimerPtr, uint32 *TimeSpanPtr)
Delivers the time difference (current time - reference time).
- Sync/Async
TRUE
- Reentrancy
Reentrant but not for the same timer instance
Parameters
Dir |
Name |
Description |
|---|---|---|
[in] |
TimerPtr |
to a timer instance defined by the user. |
[out] |
TimeSpanPtr |
to time span destination data in RAM. |
- Return type
Std_ReturnType
Return values
Name |
Description |
|---|---|
E_OK |
The underlying GPT driver service has returned E_OK and no development error has been detected |
E_NOT_OK |
The underlying GPT driver service has returned E_NOT_OK, or a development error has been detected |
Tm_ShiftTimer1us32bit¶
void Tm_ShiftTimer1us32bit(Tm_PredefTimer1us32bitType *TimerPtr, uint32 TimeValue)
Shifts the reference time of the timer instance.
- Sync/Async
TRUE
- Reentrancy
Reentrant but not for the same timer instance
Parameters
Dir |
Name |
Description |
|---|---|---|
[in] |
TimerPtr |
to a timer instance defined by the user. |
[out] |
TimeValue |
value in us, the reference time has to be shifted. |
- Return type
void
Tm_SyncTimer1us32bit¶
void Tm_SyncTimer1us32bit(Tm_PredefTimer1us32bitType *TimerDstPtr, const Tm_PredefTimer1us32bitType *TimerSrcPtr)
Synchronizes two timer instances.
- Sync/Async
TRUE
- Reentrancy
Reentrant but not for the same timer instance
Parameters
Dir |
Name |
Description |
|---|---|---|
[out] |
TimerDstPtr |
to the destination timer instance defined by the user. |
[in] |
TimerSrcPtr |
to the source timer instance defined by the user. |
- Return type
void
Tm_BusyWait1us32bit¶
Std_ReturnType Tm_BusyWait1us32bit(uint8 WaitingTimeMin)
Performs busy waiting by polling with a guaranteed minimum waiting time.
- Sync/Async
TRUE
- Reentrancy
Reentrant
Parameters
Dir |
Name |
Description |
|---|---|---|
[in] |
WaitingTimeMin |
waiting time in microseconds. |
- Return type
Std_ReturnType
Return values
Name |
Description |
|---|---|
E_OK |
The underlying GPT driver service has returned E_OK and no development error has been detected |
E_NOT_OK |
The underlying GPT driver service has returned E_NOT_OK, or a development error has been detected |
Tm_ResetTimer100us32bit¶
Std_ReturnType Tm_ResetTimer100us32bit(Tm_PredefTimer100us32bitType *TimerPtr)
Resets a timer instance (user point of view).
- Sync/Async
TRUE
- Reentrancy
Reentrant but not for the same timer instance
Parameters
Dir |
Name |
Description |
|---|---|---|
[out] |
TimerPtr |
to a timer instance defined by the user. |
- Return type
Std_ReturnType
Return values
Name |
Description |
|---|---|
E_OK |
The underlying GPT driver service has returned E_OK and no development error has been detected |
E_NOT_OK |
The underlying GPT driver service has returned E_NOT_OK, or a development error has been detected |
Tm_GetTimeSpan100us32bit¶
Std_ReturnType Tm_GetTimeSpan100us32bit(const Tm_PredefTimer100us32bitType *TimerPtr, uint32 *TimeSpanPtr)
Delivers the time difference (current time - reference time).
- Sync/Async
TRUE
- Reentrancy
Reentrant but not for the same timer instance
Parameters
Dir |
Name |
Description |
|---|---|---|
[in] |
TimerPtr |
to a timer instance defined by the user. |
[out] |
TimeSpanPtr |
to time span destination data in RAM. |
- Return type
Std_ReturnType
Return values
Name |
Description |
|---|---|
E_OK |
The underlying GPT driver service has returned E_OK and no development error has been detected |
E_NOT_OK |
The underlying GPT driver service has returned E_NOT_OK, or a development error has been detected |
Tm_ShiftTimer100us32bit¶
void Tm_ShiftTimer100us32bit(Tm_PredefTimer100us32bitType *TimerPtr, uint32 TimeValue)
Shifts the reference time of the timer instance.
- Sync/Async
TRUE
- Reentrancy
Reentrant but not for the same timer instance
Parameters
Dir |
Name |
Description |
|---|---|---|
[in] |
TimerPtr |
to a timer instance defined by the user. |
[out] |
TimeValue |
value in us, the reference time has to be shifted. |
- Return type
void
Tm_SyncTimer100us32bit¶
void Tm_SyncTimer100us32bit(Tm_PredefTimer100us32bitType *TimerDstPtr, const Tm_PredefTimer100us32bitType *TimerSrcPtr)
Synchronizes two timer instances.
- Sync/Async
TRUE
- Reentrancy
Reentrant but not for the same timer instance
Parameters
Dir |
Name |
Description |
|---|---|---|
[out] |
TimerDstPtr |
to the destination timer instance defined by the user. |
[in] |
TimerSrcPtr |
to the source timer instance defined by the user. |
- Return type
void
Tm_GetTimeSpan1ms32bit¶
Std_ReturnType Tm_GetTimeSpan1ms32bit(const Tm_PredefTimer1ms32bitType *TimerPtr, uint32 *TimeSpanPtr)
Delivers the time difference (current time - reference time).
- Sync/Async
TRUE
- Reentrancy
Reentrant but not for the same timer instance
Parameters
Dir |
Name |
Description |
|---|---|---|
[in] |
TimerPtr |
to a timer instance defined by the user. |
[out] |
TimeSpanPtr |
to time span destination data in RAM. |
- Return type
Std_ReturnType
Return values
Name |
Description |
|---|---|
E_OK |
The underlying GPT driver service has returned E_OK and no development error has been detected |
E_NOT_OK |
The underlying GPT driver service has returned E_NOT_OK, or a development error has been detected |
依赖的服务(Dependent Services)¶
强制接口(Mandatory Interfaces)¶
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. |
Gpt_GetPredefTimerValue |
Gpt.h |
Delivers the current value of the desired GPT Predef Timer. |
可选接口(Optional Interfaces)¶
API Function |
Header File |
Description |
|---|---|---|
Det_ReportError |
Det.h |
Service to report development errors |
服务封装(Service Encapsulation)¶
Tm无服务封装接口。
Tm module has no service encapsulation interfaces.
配置(Configuration)¶
基础配置说明(Basic Configuration Description)¶
开发错误检测开关(Development Error Detection Switch)¶
Tm模块提供TmDevErrorDetection开关，用于控制是否开启Tm模块的开发错误检测功能。
The Tm module provides the TmDevErrorDetection switch, which is used to control whether to enable the development error detection function of the Tm module.
Tm配置图-开发错误检测(Tm Configuration Diagram - Development Error Detection)¶
预定时器接口使能开关(Predefined Timer Interface Enable Switches)¶
Tm模块支持4种预定时器，分别是1us16bit，1us24bit,1us32bit和100us32bit，并提供相应的开关来控制是否使能相应的定时器接口。
The Tm module supports 4 types of predefined timers, namely 1us16bit, 1us24bit, 1us32bit, and 100us32bit, and provides corresponding switches to control whether to enable the corresponding timer interfaces.
Tm配置图-预定时器接口使能开关 (Tm Configuration Diagram - Predefined Timer Interface Enable Switches)¶
版本获取开关(Version Acquisition Switch)¶
Tm模块提供版本获取开关，用于控制是否获取版本号。
The Tm module provides a version acquisition switch to control version number retrieval.
Tm配置图-版本获取开关 (Tm Configuration Diagram - Version Acquisition Switch)¶