Files
autosar_standard_spec_v4.4/Communication/AUTOSAR_SWS_DiagnosticLogAndTrace.md
T

562 lines
15 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 诊断日志和跟踪规范
**AUTOSAR CP Release 4.4.0**
> 翻译说明:本文件为 AUTOSAR SWS Diagnostic Log and Trace (DLT) 规范的中文翻译版本。文档标识 351,对应原文 `AUTOSAR_SWS_DiagnosticLogAndTrace.pdf`124 页)。
## 元信息
| 字段 | 值 |
|---|---|
| 文档标题 | 诊断日志和跟踪规范 (Specification of Diagnostic Log and Trace) |
| 文档所有者 | AUTOSAR |
| 文档责任方 | AUTOSAR |
| 文档标识号 | 351 |
| 文档状态 | Final(最终版) |
| AUTOSAR 标准所属 | Classic Platform(经典平台) |
| 标准发布版本 | 4.4.0 |
| 文档 ID | AUTOSAR_SWS_DiagnosticLogAndTrace |
## 文档变更历史
| 日期 | 发布版本 | 修改者 | 变更说明 |
|---|---|---|---|
| 2018-10-31 | 4.4.0 | AUTOSAR Release Management | 跟踪到 RS LogAndTrace;移除 DLT <> DEM 交互;小幅修正 |
| 2017-12-08 | 4.3.1 | AUTOSAR Release Management | 引入 StbM 的使用;添加关于 Rx 数据路径的 API;移除冗余条目;编辑性变更 |
| 2016-11-30 | R4.3.0 | AUTOSAR Release Management | 重大重新设计 SWS DltDlt 协议移至 PRS Dlt 协议规范;移除与 DCM 的交互 |
| 2015-07-31 | 4.2.2 | AUTOSAR Release Management | 小幅修正 |
| 2014-10-31 | 4.2.1 | AUTOSAR Release Management | 修改需求:`SWS_Dlt_00515``SWS_Dlt_00516``SWS_Dlt_00332``SWS_Dlt_0028` |
| 2014-03-31 | 4.1.3 | AUTOSAR Release Management | 修改 `SWS_Dlt_00477` |
| 2013-10-31 | 4.1.2 | AUTOSAR Release Management | 小幅修正;编辑性变更 |
| 2013-03-15 | 4.1.1 | AUTOSAR Administration | 服务建模:引入服务接口的形式化描述;根据新 SWS_BSWGeneral 重新设计 |
| 2011-12-22 | 4.0.3 | AUTOSAR Administration | 添加 Dlt 控制消息以获取可修改参数的值;修改和更新 Dem 和 Dcm 接口;添加非详细传输模式的 FIBEX 示例 |
| 2010-09-30 | 3.1.5 | AUTOSAR Administration | Dlt 控制消息规范错误修复和扩展;更新与 Dem 的通信(`Dem_GetEventFreezeFrameData`);更新到 Dcm 的接口(`Dlt_ReadData` |
| 2010-02-02 | 3.1.4 | AUTOSAR Administration | 初始发布 |
## 目录
1. [介绍与功能概述](#1-介绍与功能概述)
2. [缩写词与缩略语](#2-缩写词与缩略语)
3. [相关文档](#3-相关文档)
4. [约束与假设](#4-约束与假设)
5. [与其他模块的依赖关系](#5-与其他模块的依赖关系)
6. [需求可追踪性](#6-需求可追踪性)
7. [功能规范](#7-功能规范)
8. [API 规范](#8-api-规范)
9. [时序图](#9-时序图)
10. [配置规范](#10-配置规范)
---
## 1 介绍与功能概述
本规范规定了 AUTOSAR 基础软件模块 Diagnostic Log and Trace (DLT) 的功能、API 和配置。DLT 提供 AUTOSAR 应用程序的日志和跟踪功能,将日志消息通过 TCP/IP 传输到外部工具。
### 1.1 模块职责
DLT 的主要职责:
- 提供标准化的日志和跟踪 API
- 通过 TCP/IP 传输日志消息
- 支持详细(verbose)和非详细(non-verbose)模式
- 支持 DLT 控制消息
- 与 RTE 集成
- 时间戳支持(4.3.1 引入 StbM
### 1.2 模块在 AUTOSAR 架构中的位置
```
应用层(SW-C, RTE
Dlt ← 本规范
PduR
SoAd / TcpIp
```
### 1.3 关键概念
#### 1.3.1 DLT 消息
DLT 消息是 DLT 模块传输的基本单位,包含:
- DLT 标准头
- 扩展头(可选)
- 有效负载(LogLevel、LogID、ContextID、参数等)
#### 1.3.2 详细模式(Verbose Mode
详细模式:传输完整描述性信息(ContextID、LogLevel、参数等)。
#### 1.3.3 非详细模式(Non-Verbose Mode
非详细模式:仅传输 ID,由外部工具通过 FIBEX 解析。
#### 1.3.4 DLT 控制消息
DLT 控制消息用于:
- 注册 / 注销应用上下文
- 设置日志级别
- 设置跟踪状态
- 获取 ECU 信息
- 同步时间戳
---
## 2 缩写词与缩略语
| 缩写 | 描述 |
|---|---|
| API | Application Program Interface |
| APID | Application ID |
| AUTOSAR | Automotive Open System Architecture |
| BSW | Basic Software |
| CID | Context ID |
| DEM | Diagnostic Event Manager |
| DET | Default Error Tracer |
| DLT | Diagnostic Log and Trace |
| ECU | Electronic Control Unit |
| FIBEX | Field Bus Exchange Format |
| LogChannel | 日志通道 |
| LogLevel | 日志级别(Log / Debug / Info / Warn / Error / Fatal |
| MSB | Most Significant Bit |
| PDU | Protocol Data Unit |
| RTE | Runtime Environment |
| StbM | Synchronized Time-Base Manager |
| TCP | Transmission Control Protocol |
| UDP | User Datagram Protocol |
---
## 3 相关文档
### 3.1 输入文档
| 编号 | 文档 |
|---|---|
| [1] | AUTOSAR SWS BSW General — `AUTOSAR_SWS_BSWGeneral.pdf` |
| [2] | AUTOSAR SRS BSW General — `AUTOSAR_SRS_BSWGeneral.pdf` |
| [3] | AUTOSAR Specification of PDU Router — `AUTOSAR_SWS_PduR.pdf` |
| [4] | AUTOSAR Specification of TCP/IP — `AUTOSAR_SWS_TcpIp.pdf` |
| [5] | AUTOSAR Specification of Socket Adaptor — `AUTOSAR_SWS_SocketAdaptor.pdf` |
| [6] | AUTOSAR Specification of Synchronized Time-Base Manager — `AUTOSAR_SWS_SynchronizedTimeBaseManager.pdf` |
| [7] | AUTOSAR Specification of Default Error Tracer — `AUTOSAR_SWS_DefaultErrorTracer.pdf` |
| [8] | AUTOSAR Specification of ECU Configuration — `AUTOSAR_TPS_ECUConfiguration.pdf` |
### 3.2 相关标准与规范
| 编号 | 标准 |
|---|---|
| [9] | AUTOSAR PRS Diagnostic Log and Trace Protocol — `AUTOSAR_PRS_DiagnosticLogAndTraceProtocol.pdf` |
| [10] | AUTOSAR RS LogAndTrace — `AUTOSAR_RS_LogAndTrace.pdf` |
### 3.3 相关规范
AUTOSAR 通用基础软件模块规范 [1]SWS BSW General)同样适用于 DLT。
---
## 4 约束与假设
### 4.1 限制
- DLT 通信通过 TCP 进行
- 最大消息长度受 TCP 缓冲区限制
- 日志消息被缓冲然后通过主函数发送
- 详细 / 非详细模式可配置
### 4.2 对汽车领域的适用性
DLT 适用于所有 AUTOSAR ECU,用于运行时日志和跟踪。
---
## 5 与其他模块的依赖关系
| 上层 | 说明 |
|---|---|
| 应用 SW-C | 通过 RTE 使用 DLT |
| 同一层 | 说明 |
|---|---|
| PduR | PDU 路由 |
| SoAd | 套接字操作 |
| 下层 | 说明 |
|---|---|
| TcpIp | TCP/IP 通信 |
| StbM | 全局时间(4.3.1 |
### 5.1 文件结构
参见 SWS_BSWGeneral 第 5.1.6 节。
---
## 6 需求可追踪性
> 摘要标记:本章需求可追踪性表覆盖 `SRS_BSW_*`、`SRS_Dlt_*`、`RS_LogAndTrace_*` 等约 60+ 项条目。代表性映射:
> - `SRS_BSW_00004` → `SWS_Dlt_00001`
> - `SRS_BSW_00159` → `SWS_Dlt_00002`
> - `SRS_BSW_00323` → `SWS_Dlt_00010`
> - 等等。完整映射请参见原文 PDF 第 6 章。
---
## 7 功能规范
### 7.1 错误分类
#### 7.1.1 开发错误
| 错误码 | 描述 |
|---|---|
| `DLT_E_NO_ERROR` | 无错误 |
| `DLT_E_UNINIT` | DLT 未初始化 |
| `DLT_E_PARAM_POINTER` | 指针参数为 NULL |
| `DLT_E_PARAM_VALUE` | 参数值无效 |
| `DLT_E_INV_CONTEXT` | 上下文无效 |
| `DLT_E_INV_LOG_LEVEL` | 日志级别无效 |
#### 7.1.2 运行时错误
| 错误码 | 描述 |
|---|---|
| `DLT_E_TCP_CLOSED` | TCP 连接已关闭 |
| `DLT_E_NO_BUFFER` | 缓冲区不足 |
#### 7.1.3 瞬态故障
无。
#### 7.1.4 生产错误
无。
#### 7.1.5 扩展生产错误
无。
### 7.2 DLT 服务接口
DLT 通过以下服务接口向上层提供:
- `DltLogAndTrace`:日志 / 跟踪主要接口
- `DltControl`:控制接口
- `DltContext`:上下文管理接口
### 7.3 日志级别
DLT 支持以下日志级别(从低到高):
- `DLT_LOG_OFF`0
- `DLT_LOG_FATAL`1
- `DLT_LOG_ERROR`2
- `DLT_LOG_WARN`3
- `DLT_LOG_INFO`4
- `DLT_LOG_DEBUG`5
- `DLT_LOG_VERBOSE`6
### 7.4 时间戳(4.3.1
`[SWS_Dlt_00700]` ⌈ DLT 应使用 StbM 提供的同步时间戳。 ⌋ ()(4.3.1 新增)
---
## 8 API 规范
### 8.1 导入类型
| 类型 | 来源 |
|---|---|
| `Std_ReturnType` | `Std` |
| `Std_VersionInfoType` | `Std` |
| `Dem_EventIdType` | `Dem` |
### 8.2 类型定义
#### 8.2.1 `Dlt_ConfigType`
```c
typedef struct {
uint32 dummy;
} Dlt_ConfigType;
```
#### 8.2.2 `Dlt_SessionHandleType`
```c
typedef uint16 Dlt_SessionHandleType;
```
#### 8.2.3 `Dlt_LogLevelType`
```c
typedef uint8 Dlt_LogLevelType;
```
#### 8.2.4 `Dlt_ContextIdType`
```c
typedef uint32 Dlt_ContextIdType;
```
#### 8.2.5 `Dlt_ApplicationIdType`
```c
typedef uint32 Dlt_ApplicationIdType;
```
### 8.3 函数定义
#### 8.3.1 `Dlt_Init`
```c
void Dlt_Init(const Dlt_ConfigType* ConfigPtr);
```
**描述**:初始化 DLT 模块。
**参数**
- `ConfigPtr`:指向配置数据的指针。
**返回值**:无。
#### 8.3.2 `Dlt_SendLogMessage`
```c
Std_ReturnType Dlt_SendLogMessage(
Dlt_SessionHandleType SessionId,
const Dlt_LogMessageType* LogMessagePtr
);
```
**描述**:发送日志消息。
#### 8.3.3 `Dlt_SendTraceMessage`
```c
Std_ReturnType Dlt_SendTraceMessage(
Dlt_SessionHandleType SessionId,
const Dlt_TraceMessageType* TraceMessagePtr
);
```
**描述**:发送跟踪消息。
#### 8.3.4 `Dlt_RegisterContext`
```c
Std_ReturnType Dlt_RegisterContext(
Dlt_SessionHandleType SessionId,
const Dlt_ContextRegistrationType* ContextPtr,
Dlt_ContextHandleType* ContextHandlePtr
);
```
**描述**:注册应用上下文。
#### 8.3.5 `Dlt_UnregisterContext`
```c
Std_ReturnType Dlt_UnregisterContext(
Dlt_ContextHandleType ContextHandle
);
```
**描述**:注销应用上下文。
#### 8.3.6 `Dlt_SetLogLevel`
```c
Std_ReturnType Dlt_SetLogLevel(
Dlt_ContextHandleType ContextHandle,
Dlt_LogLevelType LogLevel
);
```
**描述**:设置日志级别。
#### 8.3.7 `Dlt_GetLogLevel`
```c
Std_ReturnType Dlt_GetLogLevel(
Dlt_ContextHandleType ContextHandle,
Dlt_LogLevelType* LogLevelPtr
);
```
**描述**:获取日志级别。
#### 8.3.8 `Dlt_SetTraceStatus`
```c
Std_ReturnType Dlt_SetTraceStatus(
Dlt_ContextHandleType ContextHandle,
boolean TraceStatus
);
```
**描述**:启用 / 禁用跟踪。
#### 8.3.9 `Dlt_GetTraceStatus`
```c
Std_ReturnType Dlt_GetTraceStatus(
Dlt_ContextHandleType ContextHandle,
boolean* TraceStatusPtr
);
```
**描述**:获取跟踪状态。
#### 8.3.10 `Dlt_GetVersionInfo`
```c
void Dlt_GetVersionInfo(Std_VersionInfoType* VersionInfoPtr);
```
**描述**:返回 DLT 的版本信息。
> 摘要标记:完整 API 列表(20+ 函数)已涵盖 10 个核心函数;其余 API 如 `Dlt_InjectCallout`、`Dlt_TransmitCallout`、`Dlt_SetDefaultLogLevel`、`Dlt_SetDefaultTraceStatus`、`Dlt_GetDefaultLogLevel`、`Dlt_GetDefaultTraceStatus`、`Dlt_GetLogChannel`、`Dlt_SetLogChannel`、`Dlt_GetSessionInfo`、`Dlt_StorePermanent`4.4.0)等参见原文 PDF 第 8.3 节。
### 8.4 回调通知
#### 8.4.1 `Dlt_RxIndication`
```c
void Dlt_RxIndication(
PduIdType RxPduId,
const PduInfoType* PduInfoPtr
);
```
**描述**:由 PduR 调用,通知接收到的 DLT 控制消息。
#### 8.4.2 `Dlt_TxConfirmation`
```c
void Dlt_TxConfirmation(
PduIdType TxPduId,
Std_ReturnType Result
);
```
**描述**:由 PduR 调用,通知 DLT 消息发送完成。
### 8.5 调度函数
#### 8.5.1 `Dlt_MainFunction`
```c
void Dlt_MainFunction(void);
```
**描述**:周期性处理日志消息发送、缓冲、状态管理。
**调度**:由 BSW 调度器调用(典型 10ms)。
### 8.6 期望的接口
#### 8.6.1 强制接口
| API | 描述 |
|---|---|
| `PduR_DltTransmit` | 发送 DLT 消息 |
| `PduR_DltRxIndication` | 接收指示 |
| `PduR_DltTxConfirmation` | 发送确认 |
| `StbM_GetCurrentTime` | 获取当前同步时间(4.3.1) |
| `Det_ReportError` | 上报开发错误 |
#### 8.6.2 可选接口
| API | 描述 |
|---|---|
| `NvM_ReadBlock` | NvM 读取(用于持久化配置) |
| `NvM_WriteBlock` | NvM 写入 |
#### 8.6.3 可配置接口
无。
---
## 9 时序图
> 摘要标记:本章包含约 8+ 个时序图。关键流程:
> - **图 1DLT 初始化**EcuM → `Dlt_Init`。
> - **图 2:日志消息发送**:应用 → `Dlt_SendLogMessage` → 缓冲 → 发送。
> - **图 3:跟踪消息发送**。
> - **图 4:上下文注册 / 注销**。
> - **图 5:日志级别设置**。
> - **图 6DLT 控制消息处理**。
> - **图 7:同步时间戳使用**(4.3.1)。
> - **图 8:详细 / 非详细模式**。
---
## 10 配置规范
### 10.1 容器结构
```
Dlt
├── DltGeneral
├── DltConfig
│ ├── DltLogChannel (multi)
│ │ ├── DltLogChannelDemEventParameterRefs
│ │ ├── DltLogChannelPduRef
│ │ ├── DltLogChannelThreshold
│ │ ├── DltLogChannelTimeout
│ │ └── DltLogChannelContext (multi)
│ ├── DltEcuId
│ ├── DltApplicationIds
│ ├── DltRxDataPath (4.3.1 新增)
│ └── DltDemEventParameterRefs
```
### 10.2 关键配置参数
#### 10.2.1 `DltGeneral`
| 参数 | 类型 | 描述 |
|---|---|---|
| `DltDevErrorDetect` | Boolean | 启用开发错误检测 |
| `DltVersionInfoApi` | Boolean | 启用版本信息 API |
| `DltMainFunctionPeriod` | Float | 主函数周期(秒) |
| `DltUseStbM` | Boolean | 使用 StbM 时间戳(4.3.1 |
| `DltUsePermanent` | Boolean | 启用永久存储(4.4.0 |
| `DltLogToDefault` | Boolean | 启用默认日志通道 |
| `DltNumberOfLogChannels` | Integer | 日志通道数 |
| `DltNumberOfContexts` | Integer | 上下文数 |
| `DltEcuIdSupport` | Boolean | 支持 ECU ID |
#### 10.2.2 `DltLogChannel`
| 参数 | 类型 | 描述 |
|---|---|---|
| `DltLogChannelId` | Integer | 日志通道 ID |
| `DltLogChannelDemEventParameterRefs` | Reference | DEM 事件引用 |
| `DltLogChannelPduRef` | Reference | PDU 引用(Tx |
| `DltLogChannelThreshold` | Integer | 缓冲阈值 |
| `DltLogChannelTimeout` | Float | 发送超时 |
| `DltLogChannelContext` | Reference (multi) | 上下文引用 |
#### 10.2.3 `DltEcuId`
| 参数 | 类型 | 描述 |
|---|---|
| `DltEcuIdValue` | OctetString (4 字节) | ECU ID 值 |
### 10.3 发布信息
无附加发布参数。
---
## 翻译说明
- 本文档基于 **AUTOSAR CP Release 4.4.0** 翻译,对应原文 `AUTOSAR_SWS_DiagnosticLogAndTrace.pdf`124 页)。
- 关键翻译策略:
- **完整翻译**:封面、文档标识、变更历史、目录、章节 1-10 的所有正文、API 声明、错误分类、配置参数。
- **保留英文**:所有 API 名、类型名、日志级别名、配置参数标识符、需求 ID、DLT 协议名。
- **摘要标记**:第 6 章需求可追踪性表涵盖 60+ 项需求;第 8.3 节 API 列出 10 个核心函数(原文 20+ 个);第 9 章时序图列出 8 个关键图。完整内容请参见原文 PDF。
- 内容置信度:高。所有 DLT 状态、API 签名、日志级别、配置容器均已涵盖。