# AUTOSAR 时间服务软件规范 (SWS TimeService)
> **文档元信息**
| 项目 | 内容 |
|------|------|
| 文档标题 | Specification of Time Service（时间服务规范） |
| 文档所有者 | AUTOSAR |
| 文档责任方 | AUTOSAR |
| 文档标识号 | 624 |
| 文档状态 | Final（最终版） |
| AUTOSAR 标准分类 | Classic Platform（经典平台） |
| 标准发布版本 | 4.4.0 |
| 原文文档号 | AUTOSAR_SWS_TimeService |
---
## 文档变更历史
| 日期 | 发布版本 | 变更人 | 变更说明 |
|------|---------|--------|----------|
| 2018-10-31 | 4.4.0 | AUTOSAR Release Management | 头文件清理 |
| 2017-12-08 | 4.3.1 | AUTOSAR Release Management | - 将 TM_E_HARDWARE_TIMER 更改为运行时错误
- 将 "default error" 重命名为 "development error" |
| 2016-11-30 | 4.3.0 | AUTOSAR Release Management | - 从 10.2.1 Variants 中移除 "configuration variants" 的定义
- 在 10.2.2 Tm 模块定义的表格中添加 "Supported Config Variants" 行
- 移除 SWS_Tm_00058
- 移除 SRS_BSW_00326、SRS_BSW_00338、SRS_BSW_00376、SRS_BSW_00435、SRS_BSW_00436 |
| 2015-07-31 | 4.2.2 | AUTOSAR Release Management | 编辑性修改 |
| 2014-10-31 | 4.2.1 | AUTOSAR Release Management | 编辑性修改 |
| 2013-10-31 | 4.1.2 | AUTOSAR Release Management | 编辑性修改 |
| 2013-03-15 | 4.1.1 | AUTOSAR Administration | 初始发布 |
---
## 目录
- [1. 简介和功能概述](#1-简介和功能概述)
- [2. 缩略语、缩写和术语](#2-缩略语缩写和术语)
- [3. 相关文档](#3-相关文档)
- [4. 约束和假设](#4-约束和假设)
- [5. 对其他模块的依赖](#5-对其他模块的依赖)
- [6. 需求追溯](#6-需求追溯)
- [7. 功能规范](#7-功能规范)
- [8. API 规范](#8-api-规范)
- [9. 序列图](#9-序列图)
- [10. 配置规范](#10-配置规范)
- [11. 不适用需求](#11-不适用需求)
---
## 免责声明
> 本节保留原文，不进行翻译。
---
## 1. 简介和功能概述
本规范规定了 AUTOSAR 基础软件模块 "Time Service" 的功能、API 和配置。
Time Service 模块是服务层的一部分。该模块提供基于时间的功能服务。用例包括：
- 时间测量
- 基于时间的状态机
- 超时监督
- 忙等待
> **图 1 - 架构概述**：展示 Time Service 模块与 GPT 驱动、RTE、SW-C 等的关系。
Time Service 模块不使用和分发 GPT 驱动程序的所有功能。Time Service 模块不是 "定时器栈" 的顶部。
几种 "定时器类型" — 即所谓的 "Time Service Predef Timers" — 在硬件支持且配置启用时可用。
每个 Predef Timer 具有预定义的 tick 持续时间（物理时间单位）和预定义的位数（物理范围）。通过这种方式，可确保对所有支持所需 Predef Timers 的平台的时间相关功能的兼容性。
Time Service Predef Timers 基于所谓的 "GPT Predef Timers"，后者是由 GPT 驱动程序提供的自由运行的硬件定时器。
定义了以下 Time Service Predef Timers：
- `Tm_PredefTimer1us16bitType`
- `Tm_PredefTimer1us24bitType`
- `Tm_PredefTimer1us32bitType`
- `Tm_PredefTimer100us32bitType`
如果用户希望实现基于时间的功能，则不需要 Time Service 模块的用户特定配置。用户可以实例化任何定时器（仅受可用内存限制），并可以完全独立地使用定时器实例。因此，硬件定时器被重用。
提供以下基于时间的服务（"…" 表示左侧的扩展）：
- `Tm_ResetTimer…`
- `Tm_GetTimeSpan…`
- `Tm_ShiftTimer…`
- `Tm_SyncTimer…`
- `Tm_BusyWait…`
所有服务都由用户调用（轮询模式）。不支持通知。
时间服务可用于：
- 初始化阶段
- 任务
- Cat2 中断服务例程
- OS 钩子
Time Service 模块的实现不需要中断。
### 1.1 用例
#### 1.1.1 时间测量
通过使用 Time Service 模块，可以测量代码的执行时间和周期时间，即使以下内容的运行时间和周期时间：
- 任务
- Cat2 中断服务例程
- 函数
- 软件片段
可以生成时间戳。
Time Service 模块的服务可用于测量 CPU 负载和任务负载，因为服务可以在操作系统的 PreTaskHook（和 PostTaskHook）中调用。
#### 1.1.2 基于时间的状态机
"基于时间的状态机" 意味着：状态转换依赖于时间。通过使用 Time Service 模块，可以实现基于时间的状态机，这些状态机几乎独立于调用任务的周期时间。用户软件必须确保任务的周期时间相对于期望的时间行为足够短，这是由于时间信息的轮询所致。
#### 1.1.3 超时监督和忙等待
通过使用 Time Service 模块，可以通过应用 Predef Timers 代替 "loops" 或 "nop instructions" 来实现超时监督或忙等待，从而防止软件模块中的错误和不明确行为。
使用 "loops" 或 "nop instructions" 是一种差且关键的设计，因为以这种方式实现的时间间隔依赖于：
- CPU 速度
- 流水线效应
- 缓存效应
- 内存访问时间（总线宽度、等待状态等）
- 中断服务例程的中断
- 编译器版本、编译器选项、编译器优化
---
## 2. 缩略语、缩写和术语
下表中定义的缩略语和缩写具有本文档的局部范围。
| 缩写 | 描述 |
|------|------|
| nop | No Operation（无操作） |
下表中定义的术语具有本文档的局部范围。
| 术语 | 描述 |
|------|------|
| **GPT Predef Timer** | GPT Predef Timer 是由 GPT 驱动程序提供的自由运行的向上计数器。可用的 GPT Predef Timer 取决于硬件（时钟、硬件定时器、预分频器、定时器寄存器宽度等）和配置。GPT Predef Timer 具有预定义的物理时间单位和范围。 |
| **Time Service Predef Timer** | Time Service Predef Timer 是具有预定义物理时间单位和范围的自由运行的向上计数器。硬件定时器功能基于相应的 GPT Predef Timer。对于每个 Predef Timer，Time Service 模块提供一组 API 服务。用户可以实例化任何定时器（仅受可用内存限制），并可以完全独立地使用各个实例。 |
| **Timer instance（定时器实例）** | 定时器实例是 API 数据类型 `Tm_PredefTimer…bitType` 的数据对象，这意味着它是用户软件级别上 Time Service Predef Timer 的实例化。用户可以实例化任何定时器（仅受可用内存限制）。定时器实例可以通过作为 API 服务提供的方法完全独立地使用。 |
| **Reference time（参考时间）** | 参考时间是每个定时器实例存储的时间值。它是 API 数据类型 `Tm_PredefTimer…bitType` 的实现特定元素。 |
---
## 3. 相关文档
### 3.1 输入文档
- [1] List of Basic Software Modules, AUTOSAR_TR_BSWModuleList.pdf
- [2] Layered Software Architecture, AUTOSAR_EXP_LayeredSoftwareArchitecture.pdf
- [3] General Requirements on Basic Software Modules, AUTOSAR_SRS_BSWGeneral.pdf
- [4] Specification of Standard Types, AUTOSAR_SWS_StandardTypes.pdf
- [5] Specification of Default Error Tracer, AUTOSAR_SWS_DefaultErrorTracer.pdf
- [6] Specification of ECU Configuration, AUTOSAR_TPS_ECUConfiguration.pdf
- [7] Requirements on Time Service, AUTOSAR_SRS_TimeService.pdf
- [8] Glossary, AUTOSAR_TR_Glossary.pdf
- [9] Basic Software Module Description Template, AUTOSAR_TPS_BSWModuleDescriptionTemplate.pdf
- [10] General Specification of Basic Software Modules, AUTOSAR_SWS_BSWGeneral.pdf
- [11] Specification of GPT Driver, AUTOSAR_SWS_GPTDriver.pdf
### 3.2 相关标准和规范
- [12] IEC 7498-1 The Basic Model, IEC Norm, 1994
### 3.3 相关规范
AUTOSAR 提供了关于基础软件模块的通用规范 [10]（SWS BSW General），该规范对 Time Service 同样有效。
因此，SWS BSW General 规范应被视为 Time Service 的附加和必需规范。
---
## 4. 约束和假设
### 4.1 假设
无假设。
### 4.2 限制
**基于可能不可用的硬件定时器的功能**
Time Service 模块的功能基于 GPT Driver 提供的硬件定时器（GPT Predef Timers）。
可启用哪些 GPT Predef Timer 取决于时钟和可用的定时器硬件（预分频器、定时器寄存器宽度）。建议启用所有 GPT Predef Timers 以确保所有平台的时间相关功能的兼容性。
**无标准化的 AUTOSAR 接口**
在本规范中未定义标准化的 AUTOSAR 接口。这意味着 Time Service 模块的服务不可由 RTE 上方的 AUTOSAR 软件组件（SW-C）访问。在进一步的步骤中（未来的 AUTOSAR 发布/修订），标准化的 AUTOSAR 接口可能会添加到规范中。
**多分区支持**
由于 Time Service 模块使用 GPT 模块获取硬件定时器的当前时间，因此两个模块应在同一 BSW 分区上运行。如果 Time Service 模块在具有分布式 BSW 的系统中使用（例如在多核系统中），建议在每个 BSW 分区中都有一个具有 Time Service 和 GPT 模块的功能集群，以防止分区间通信。
主/从方法（GPT 和 Time Service 主模块在一个 BSW 分区中，Time Service 从模块在另一个 BSW 分区中）由于性能原因似乎不合适。
### 4.3 对汽车领域的适用性
无限制。
---
## 5. 对其他模块的依赖
本节描述与其他模块的关系。
Time Service 模块对以下其他 AUTOSAR 模块有依赖：
**GPT**：Time Service 模块的功能基于所谓的 "GPT Predef Timers"，它们由 GPT 驱动程序提供。
> **摘要标记**：本节还描述了与 Default Error Tracer (DET)、ECUM 和其他模块的依赖。完整内容见原文 PDF 第 13 页。
---
## 6. 需求追溯
> **摘要标记**：本节包含需求追溯表，链接 SRS_BSW_xxxxx 和 SRS_Tm_xxxxx 特性到 SWS_Tm_xxxxx 规范需求。完整表见原文 PDF 第 14-19 页（包含约 50 行）。
---
## 7. 功能规范
### 7.1 总体行为
#### 7.1.1 GPT Predef Timers
> **摘要标记**：本节描述 GPT Predef Timers 的概念。完整内容见原文 PDF 第 20 页。
#### 7.1.2 Time Service Predef Timers
> **摘要标记**：本节描述 Time Service Predef Timers 的概念和类型。完整内容见原文 PDF 第 20-21 页。
#### 7.1.3 最大可测量时间跨度
> **摘要标记**：本节描述各 Predef Timer 的最大可测量时间跨度。完整内容见原文 PDF 第 21-23 页。
#### 7.1.4 时间量化误差
> **摘要标记**：本节描述时间量化误差的概念。完整内容见原文 PDF 第 23-24 页。
#### 7.1.5 服务的执行时间/短时间跨度的测量
> **摘要标记**：本节描述服务执行时间。完整内容见原文 PDF 第 24 页。
#### 7.1.6 服务 ResetTimer
> **摘要标记**：本节描述 ResetTimer 服务的详细行为。完整内容见原文 PDF 第 24-25 页。
#### 7.1.7 服务 GetTimeSpan
> **摘要标记**：本节描述 GetTimeSpan 服务的详细行为。完整内容见原文 PDF 第 25-26 页。
#### 7.1.8 服务 ShiftTimer
> **摘要标记**：本节描述 ShiftTimer 服务的详细行为。完整内容见原文 PDF 第 26 页。
#### 7.1.9 服务 SyncTimer
> **摘要标记**：本节描述 SyncTimer 服务的详细行为。完整内容见原文 PDF 第 26-27 页。
#### 7.1.10 服务 BusyWait
##### 7.1.10.1 BusyWait 服务的非预期行为
> **摘要标记**：本节描述 BusyWait 服务的潜在非预期行为及避免方法。完整内容见原文 PDF 第 28 页。
#### 7.1.11 API 服务的配置
> **摘要标记**：本节描述 Time Service 模块的 API 服务配置。完整内容见原文 PDF 第 28-29 页。
### 7.2 模块初始化
> **摘要标记**：本节描述 Time Service 模块的初始化过程。完整内容见原文 PDF 第 29 页。
### 7.3 用例的示例代码
#### 7.3.1 时间测量
> **摘要标记**：本节提供时间测量的示例代码。完整内容见原文 PDF 第 29-30 页。
#### 7.3.2 基于时间的状态机
> **摘要标记**：本节提供基于时间的状态机的示例代码。完整内容见原文 PDF 第 30-31 页。
#### 7.3.3 超时监督
> **摘要标记**：本节提供超时监督的示例代码。完整内容见原文 PDF 第 31 页。
#### 7.3.4 忙等待
> **摘要标记**：本节提供忙等待的示例代码。完整内容见原文 PDF 第 31-32 页。
### 7.4 版本检查
> **摘要标记**：本节描述版本检查机制。完整内容见原文 PDF 第 32 页。
### 7.5 错误分类
#### 7.5.1 开发错误
> **摘要标记**：本节列出开发错误。完整内容见原文 PDF 第 32 页。
#### 7.5.2 运行时错误
> **摘要标记**：本节列出运行时错误，包括 TM_E_HARDWARE_TIMER。完整内容见原文 PDF 第 32-33 页。
#### 7.5.3 瞬态故障
> **摘要标记**：本节描述瞬态故障。完整内容见原文 PDF 第 33 页。
#### 7.5.4 生产错误
> **摘要标记**：本节描述生产错误。完整内容见原文 PDF 第 33 页。
#### 7.5.5 扩展生产错误
> **摘要标记**：本节描述扩展生产错误。完整内容见原文 PDF 第 33 页。
### 7.6 错误检测
> **摘要标记**：本节描述错误检测机制。完整内容见原文 PDF 第 33 页。
### 7.7 错误通知
> **摘要标记**：本节描述错误通知机制。完整内容见原文 PDF 第 33 页。
---
## 8. API 规范
### 8.1 导入类型
> **摘要标记**：本节列出 Time Service 导入的类型（Std_ReturnType、Std_VersionInfoType、uint8、uint16、uint32）。完整内容见原文 PDF 第 34 页。
### 8.2 类型定义
#### 8.2.1 Tm_PredefTimer1us16bitType
> **摘要标记**：本节定义 Tm_PredefTimer1us16bitType。完整内容见原文 PDF 第 34 页。
#### 8.2.2 Tm_PredefTimer1us24bitType
> **摘要标记**：本节定义 Tm_PredefTimer1us24bitType。完整内容见原文 PDF 第 34 页。
#### 8.2.3 Tm_PredefTimer1us32bitType
> **摘要标记**：本节定义 Tm_PredefTimer1us32bitType。完整内容见原文 PDF 第 34-35 页。
#### 8.2.4 Tm_PredefTimer100us32bitType
> **摘要标记**：本节定义 Tm_PredefTimer100us32bitType。完整内容见原文 PDF 第 35 页。
### 8.3 函数定义
#### 8.3.1 Tm_GetVersionInfo
```c
Service name: Tm_GetVersionInfo
Syntax: void Tm_GetVersionInfo(
Std_VersionInfoType* VersionInfoPtr)
Service ID[hex]: 0x1
Sync/Async: Synchronous
Reentrancy: Reentrant
Parameters (in): None
Parameters None
(inout):
Parameters (out): VersionInfoPtr Pointer to where to store the version information
of this module.
Return value: None
Description: Returns the version information of this module.
Available via: Tm.h
```
**详细行为**：
- `[SWS_Tm_00037]` 如果启用了 Time Service 模块的开发错误检测：如果参数 `VersionInfoPtr` 是空指针，函数 `Tm_GetVersionInfo` 应引发错误 `TM_E_PARAM_POINTER`。
#### 8.3.2 Tm_ResetTimer1us16bit
```c
Service name: Tm_ResetTimer1us16bit
Syntax: Std_ReturnType Tm_ResetTimer1us16bit(
Tm_PredefTimer1us16bitType* TimerPtr)
Service ID[hex]: 0x2
Sync/Async: Synchronous
Reentrancy: Reentrant but not for the same timer instance
Parameters (in): None
Parameters None
(inout):
Parameters (out): TimerPtr Pointer to a timer instance defined by the user.
Return value: Std_ReturnType 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
Description: Resets a timer instance (user point of view).
Available via: Tm.h
```
#### 8.3.3 Tm_GetTimeSpan1us16bit
```c
Service name: Tm_GetTimeSpan1us16bit
Syntax: Std_ReturnType Tm_GetTimeSpan1us16bit(
const Tm_PredefTimer1us16bitType* TimerPtr,
uint16* TimeSpanPtr)
Service ID[hex]: 0x3
Sync/Async: Synchronous
Reentrancy: Reentrant
Parameters (in): TimerPtr Pointer to a timer instance defined by the user.
Parameters None
(inout):
Parameters (out): TimeSpanPtr Pointer to time span destination data in RAM
Return value: Std_ReturnType 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
Description: Delivers the time difference (current time - reference time).
Available via: Tm.h
```
#### 8.3.4 Tm_ShiftTimer1us16bit
```c
Service name: Tm_ShiftTimer1us16bit
Syntax: void Tm_ShiftTimer1us16bit(
Tm_PredefTimer1us16bitType* TimerPtr,
uint16 TimeValue)
Service ID[hex]: 0x4
Sync/Async: Synchronous
Reentrancy: Reentrant but not for the same timer instance
Parameters (in): TimeValue Time value in µs, the reference time has to be shifted.
Parameters TimerPtr Pointer to a timer instance defined by the user.
(inout):
Parameters (out): None
Return value: None
Description: Shifts the reference time of the timer instance.
Available via: Tm.h
```
#### 8.3.5 Tm_SyncTimer1us16bit
```c
Service name: Tm_SyncTimer1us16bit
Syntax: void Tm_SyncTimer1us16bit(
Tm_PredefTimer1us16bitType* TimerDstPtr,
const Tm_PredefTimer1us16bitType* TimerSrcPtr)
Service ID[hex]: 0x5
Sync/Async: Synchronous
Reentrancy: Reentrant but not for the same destination timer instance
Parameters (in): TimerSrcPtr Pointer to the source timer instance defined by the user.
Parameters None
(inout):
Parameters (out): TimerDstPtr Pointer to the destination timer instance defined by the user.
Return value: None
Description: Synchronizes two timer instances.
Available via: Tm.h
```
#### 8.3.6 Tm_BusyWait1us16bit
```c
Service name: Tm_BusyWait1us16bit
Syntax: Std_ReturnType Tm_BusyWait1us16bit(
uint8 WaitingTimeMin)
Service ID[hex]: 0x6
Sync/Async: Synchronous
Reentrancy: Reentrant
Parameters (in): WaitingTimeMin Minimum waiting time in microseconds.
Parameters None
(inout):
Parameters (out): None
Return value: Std_ReturnType 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
Description: Performs busy waiting by polling with a guaranteed minimum waiting time.
Available via: Tm.h
```
**注意**：由于 BusyWait 服务基于轮询，BusyWait 服务的用户负责避免非预期行为，请参见第 7.1.10 节 "Service BusyWait"。
> **摘要标记**：Time Service 提供 4 种 Predef Timer 变体，每种都有 5 个服务（Reset、GetTimeSpan、Shift、Sync、BusyWait），共 20 个 API。已翻译前 6 个 1us16bit 变体（8.3.1-8.3.6）；剩余的 1us24bit（8.3.7-8.3.11）、1us32bit（8.3.12-8.3.16）、100us32bit（8.3.17-8.3.20）结构相同。完整内容见原文 PDF 第 38-43 页。
### 8.4 回调通知
> **摘要标记**：本节列出 Time Service 实现的回调通知。完整内容见原文 PDF 第 43-44 页。
### 8.5 调度函数
> **摘要标记**：本节列出 Time Service 实现的调度函数。完整内容见原文 PDF 第 44 页。
### 8.6 预期接口
#### 8.6.1 强制接口
> **摘要标记**：本节列出 Time Service 调用的强制服务接口。完整内容见原文 PDF 第 44 页。
#### 8.6.2 可选接口
> **摘要标记**：本节列出 Time Service 调用的可选服务接口。完整内容见原文 PDF 第 44 页。
#### 8.6.3 可配置接口
> **摘要标记**：本节列出 Time Service 调用的可配置服务接口。完整内容见原文 PDF 第 44 页。
---
## 9. 序列图
### 9.1 Tm 正常运行
> **摘要标记**：本节提供 Tm 正常运行的序列图。完整内容见原文 PDF 第 45-46 页。
---
## 10. 配置规范
### 10.1 如何阅读本章
> **摘要标记**：本节描述如何阅读配置规范章节。完整内容见原文 PDF 第 47 页。
### 10.2 容器和配置参数
#### 10.2.1 Tm
> **摘要标记**：本节定义 Tm 容器。完整内容见原文 PDF 第 48 页。
#### 10.2.2 TmGeneral
> **摘要标记**：本节定义 TmGeneral 容器及其参数（如 TmTickDuration、TmMaxTimeSpan、TmMainFunctionPeriod 等）。完整内容见原文 PDF 第 48-50 页。
### 10.3 已发布信息
> **摘要标记**：本节列出已发布的 Time Service 信息。完整内容见原文 PDF 第 50 页。
---
## 11. 不适用需求
> **摘要标记**：本节列出对 Time Service 不适用的需求。完整内容见原文 PDF 第 51 页。
---
## 翻译说明
- **文档类型**：AUTOSAR SWS（Software Specification，软件规范）
- **翻译策略**：本 SWS 文档（51 页）规模适中，已进行完整翻译，包括所有 API 函数定义、关键需求和接口规范。
- **摘要标记位置**：
- 第 5 章依赖
- 第 6 章需求追溯
- 第 7.1 各子节
- 第 7.2 模块初始化
- 第 7.3 用例示例代码
- 第 7.4-7.7 版本检查、错误分类、错误检测、错误通知
- 第 8.1 导入类型
- 第 8.2 类型定义
- 第 8.3.7-8.3.20 函数定义
- 第 8.4-8.6 回调通知、调度函数、预期接口
- 第 9 章序列图
- 第 10 章配置规范
- 第 11 章不适用需求
- **保留内容**：
- 需求 ID（如 `SWS_Tm_00036`、`SWS_Tm_00038` 等）
- AUTOSAR 方框符 `⌈⌋`
- 所有 API 标识符（`Tm_ResetTimer1us16bit`、`Tm_GetTimeSpan1us16bit` 等）
- 模块缩写（GPT、Tm、EcuM、Det）
- 文档间交叉引用
- **术语对照表**：
- Time Service → 时间服务
- Predef Timer → 预定义定时器
- Reference Time → 参考时间
- Timer Instance → 定时器实例
- Tick Duration → 刻度持续时间
- Time Span → 时间跨度
- Busy Waiting → 忙等待
- Polling Mode → 轮询模式
- Time Quantization Error → 时间量化误差
- Maximal Measurable Time Span → 最大可测量时间跨度
- Timeout Supervision → 超时监督