562 lines
15 KiB
Markdown
562 lines
15 KiB
Markdown
# 诊断日志和跟踪规范
|
||
|
||
**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 Dlt;Dlt 协议移至 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+ 个时序图。关键流程:
|
||
> - **图 1:DLT 初始化**:EcuM → `Dlt_Init`。
|
||
> - **图 2:日志消息发送**:应用 → `Dlt_SendLogMessage` → 缓冲 → 发送。
|
||
> - **图 3:跟踪消息发送**。
|
||
> - **图 4:上下文注册 / 注销**。
|
||
> - **图 5:日志级别设置**。
|
||
> - **图 6:DLT 控制消息处理**。
|
||
> - **图 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 签名、日志级别、配置容器均已涵盖。
|