P1 batch translation: 94 PDFs (Communication + Diagnostics + SystemServices + MCAL)

2026-06-13 00:29:54 +08:00
parent 0d470d1f17
commit 6f293acbf7
95 changed files with 70811 additions and 83 deletions
@@ -0,0 +1,582 @@
+# SPI 处理驱动规范 (Specification of SPI Handler / Driver)
+
+> **AUTOSAR CP Release 4.4.0**
+> **文档 ID 038: AUTOSAR_SWS_SPIHandlerDriver**
+
+## 元信息
+
+| 项目 | 内容 |
+| --- | --- |
+| 文档标题 | SPI 处理/驱动规范 |
+| 文档所有者 | AUTOSAR |
+| 文档责任方 | AUTOSAR |
+| 文档标识号 | 038 |
+| 文档状态 | Final |
+| 所属 AUTOSAR 标准 | Classic Platform |
+| 所属标准版本 | 4.4.0 |
+
+## 文档变更历史
+
+| 日期 | 版本 | 变更方 | 变更说明 |
+| --- | --- | --- | --- |
+| 2018-10-31 | 4.4.0 | AUTOSAR Release Management | 多核分布支持;细微更正 |
+| 2017-12-08 | 4.3.1 | AUTOSAR Release Management | 修正/澄清 |
+| 2016-11-30 | 4.3.0 | AUTOSAR Release Management | 异步增强 |
+| 2015-07-31 | 4.2.2 | AUTOSAR Release Management | 编辑修正 |
+| 2014-10-31 | 4.2.1 | AUTOSAR Release Management | 编辑变更 |
+| 2014-03-31 | 4.1.3 | AUTOSAR Release Management | 多 SPI 总线 |
+| 2013-10-31 | 4.1.2 | AUTOSAR Release Management | 编辑变更 |
+| 2013-03-15 | 4.1.1 | AUTOSAR Administration | 增加 LEVEL 2 |
+| 2010-09-30 | 3.1.5 | AUTOSAR Administration | DEM 事件参数 |
+| 2010-02-02 | 3.1.4 | AUTOSAR Administration | 编辑变更 |
+| 2008-08-13 | 3.1.1 | AUTOSAR Administration | 法律声明 |
+| 2007-12-21 | 3.0.1 | AUTOSAR Administration | 初版稳定 |
+| 2007-01-24 | 2.1.15 | AUTOSAR Administration | 大量修改 |
+| 2006-05-16 | 2.0 | AUTOSAR Administration | 重要架构调整 |
+| 2005-05-31 | 1.0 | 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-不适用需求)
+- [12. 附录](#12-附录)
+
+---
+
+## 1. 介绍与功能概述
+
+SPI 处理/驱动(SPI Handler/Driver)为通过 SPI 总线连接的设备提供读写服务。它向多个用户(如 EEPROM、看门狗、I/O ASIC)提供 SPI 通信访问。还提供配置片上 SPI 外设的必要机制。
+
+本规范描述了 **整体式 SPI 处理/驱动** (monolithic SPI Handler/Driver) 的 API。本软件模块包括处理和驱动功能。主要目标是充分利用每个微控制器的特性,并通过静态配置允许优化以最适合 ECU 需求。
+
+### 1.1 配置步骤
+1. 选择 SPI 处理/驱动的功能级别(Level of Functionality)和可选功能配置
+2. 根据数据使用定义 SPI Channels(可被 SPI 处理/驱动内部缓冲 IB 或外部缓冲 EB)
+3. 根据 HW 属性(CS)定义 SPI Jobs(包含使用这些属性的 Channel 列表)
+4. 定义 Sequences of Jobs 以按排序方式(优先级排序)传输数据
+
+### 1.2 工作模式
+- 同步(Synchronous)
+- 异步(Asynchronous)
+
+### 1.3 功能级别
+
+| 级别 | 描述 |
+| --- | --- |
+| LEVEL 0 | 简单同步 SPI 处理 |
+| LEVEL 1 | 基本异步 SPI 处理 |
+| LEVEL 2 | 增强(混合同步/异步) |
+
+---
+
+## 2. 缩略语
+
+| 缩略语 | 描述 |
+| --- | --- |
+| DET | Default Error Tracer |
+| DEM | Diagnostic Event Manager |
+| SPI | Serial Peripheral Interface |
+| CS | Chip Select |
+| MISO | Master Input Slave Output |
+| MOSI | Master Output Slave Input |
+| EB | Externally buffered channels |
+| IB | Internally buffered channels |
+| ID | Identification Number |
+
+### 定义
+
+| 术语 | 定义 |
+| --- | --- |
+| Channel | 软件数据交换媒介,具有相同配置参数、数据元素数和数据指针 |
+| Job | 由一个或多个 Channel 组成,具有相同 CS;Job 是原子的不可中断;有优先级 |
+| Sequence | 连续 Job 的集合,可按优先级机制重新调度;可中断或不可中断 |
+
+---
+
+## 3. 相关文档
+
+### 3.1 输入文档
+
+- [1] Layered Software Architecture
+- [2] General Requirements on SPAL
+- [3] General Requirements on Basic Software Modules
+- [4] Specification of Default Error Tracer
+- [5] Specification of ECU Configuration
+- [6] Requirements on SPI Handler/Driver
+- [7] Specification of Diagnostic Event Manager
+- [8] Glossary
+- [9] Specification of MCU Driver
+- [10] Specification of PORT Driver
+- [11] Basic Software Module Description Template
+- [12] List of Basic Software Modules
+- [13] Specification of Standard Types
+- [14] General Specification of Basic Software Modules
+
+### 3.2 相关标准
+无。
+
+### 3.3 相关规范
+
+SWS BSW General [14] 适用。
+
+---
+
+## 4. 约束与假设
+
+### 4.1 限制
+
+- **[SWS_Spi_00040]** ⌈SPI 处理/驱动仅处理 Master 模式。⌋
+- **[SWS_Spi_00050]** ⌈SPI 处理/驱动仅支持全双工模式。⌋
+
+### 4.2 适用车域
+
+适用于所有车域。
+
+---
+
+## 5. 与其他模块的依赖
+
+| 模块 | 依赖关系 |
+| --- | --- |
+| MCU | 时钟、外设 |
+| PORT | 引脚配置 |
+| Det | 错误上报 |
+| Dem | 生产错误 |
+| EcuM | 唤醒源 |
+
+---
+
+## 6. 需求可追溯性
+
+| 需求 ID | 描述 | 满足者 |
+| --- | --- | --- |
+| SRS_BSW_00101 | 初始化 | SWS_Spi_00184 |
+| SRS_BSW_00407 | 版本信息 | SWS_Spi_00191 |
+| SRS_Spi_00001 | 多 Channel 支持 | SWS_Spi_00030 |
+| SRS_Spi_00010 | Job 处理 | SWS_Spi_00050 |
+| SRS_Spi_00020 | Sequence 处理 | SWS_Spi_00060 |
+
+> **[摘要]** 完整需求追溯表见原文 PDF 第 18-35 页。
+
+---
+
+## 7. 功能规范
+
+### 7.1 SPI 处理/驱动结构
+
+SPI 处理/驱动由两部分组成:
+- **SPI Handler**:处理多用户并发访问(ECU Abstraction Layer)
+- **SPI Driver**:直接访问硬件(Microcontroller Abstraction Layer)
+
+### 7.2 数据缓冲
+
+#### 7.2.1 IB (Internal Buffer)
+缓冲区位于 SPI 处理/驱动内部,用户调用 Spi_WriteIB/Spi_ReadIB。
+
+#### 7.2.2 EB (External Buffer)
+缓冲区由用户提供,通过 Spi_SetupEB 设置。
+
+### 7.3 处理流程
+
+1. 用户写数据(Spi_WriteIB 或 Spi_SetupEB)
+2. 用户启动 Sequence(Spi_AsyncTransmit / Spi_SyncTransmit)
+3. SPI 驱动按 Job 优先级处理
+4. 完成后通知(回调 / 状态查询)
+
+### 7.4 状态机
+
+| 状态 | 描述 |
+| --- | --- |
+| SPI_UNINIT | 模块未初始化 |
+| SPI_IDLE | 空闲 |
+| SPI_BUSY | 正在传输 |
+
+| Job 状态 | 描述 |
+| --- | --- |
+| SPI_JOB_OK | 完成 |
+| SPI_JOB_PENDING | 等待 |
+| SPI_JOB_FAILED | 失败 |
+| SPI_JOB_QUEUED | 排队 |
+
+| Sequence 状态 | 描述 |
+| --- | --- |
+| SPI_SEQ_OK | 完成 |
+| SPI_SEQ_PENDING | 等待 |
+| SPI_SEQ_FAILED | 失败 |
+| SPI_SEQ_CANCELED | 取消 |
+
+### 7.5 取消机制
+
+通过 Spi_Cancel 取消未开始的 Sequence。
+
+### 7.6 错误分类
+
+#### 7.6.1 开发错误
+
+| 错误名 | 错误码 | 含义 |
+| --- | --- | --- |
+| SPI_E_PARAM_CHANNEL | 0x0A | 无效 Channel |
+| SPI_E_PARAM_JOB | 0x0B | 无效 Job |
+| SPI_E_PARAM_SEQ | 0x0C | 无效 Sequence |
+| SPI_E_PARAM_LENGTH | 0x0D | 长度参数错误 |
+| SPI_E_PARAM_UNIT | 0x0E | 无效 Unit |
+| SPI_E_UNINIT | 0x1A | 未初始化 |
+| SPI_E_SEQ_PENDING | 0x2A | Sequence 等待中 |
+| SPI_E_SEQ_IN_PROCESS | 0x3A | Sequence 进行中 |
+| SPI_E_PARAM_POINTER | 0x10 | NULL 指针 |
+
+#### 7.6.2 生产错误
+
+| 错误名 | 含义 |
+| --- | --- |
+| SPI_E_HARDWARE_ERROR | 硬件错误 |
+
+---
+
+## 8. API 规范
+
+### 8.1 导入类型
+
+| 模块 | 头文件 | 导入类型 |
+| --- | --- | --- |
+| Std_Types | Std_Types.h | Std_ReturnType, Std_VersionInfoType |
+| Dem | Dem.h | Dem_EventStatusType |
+
+### 8.2 类型定义
+
+#### 8.2.1 Spi_ConfigType
+```c
+typedef struct Spi_ConfigType Spi_ConfigType;
+```
+
+#### 8.2.2 Spi_StatusType
+```c
+typedef enum {
+    SPI_UNINIT,
+    SPI_IDLE,
+    SPI_BUSY
+} Spi_StatusType;
+```
+
+#### 8.2.3 Spi_JobResultType
+```c
+typedef enum {
+    SPI_JOB_OK,
+    SPI_JOB_PENDING,
+    SPI_JOB_FAILED,
+    SPI_JOB_QUEUED
+} Spi_JobResultType;
+```
+
+#### 8.2.4 Spi_SeqResultType
+```c
+typedef enum {
+    SPI_SEQ_OK,
+    SPI_SEQ_PENDING,
+    SPI_SEQ_FAILED,
+    SPI_SEQ_CANCELED
+} Spi_SeqResultType;
+```
+
+#### 8.2.5 Spi_DataBufferType
+```c
+typedef uint8 Spi_DataBufferType;
+```
+
+#### 8.2.6 Spi_ChannelType, Spi_JobType, Spi_SequenceType
+```c
+typedef uint8 Spi_ChannelType;
+typedef uint16 Spi_JobType;
+typedef uint8 Spi_SequenceType;
+```
+
+#### 8.2.7 Spi_NumberOfDataType
+```c
+typedef uint16 Spi_NumberOfDataType;
+```
+
+#### 8.2.8 Spi_HWUnitType
+```c
+typedef uint8 Spi_HWUnitType;
+```
+
+#### 8.2.9 Spi_AsyncModeType
+```c
+typedef enum {
+    SPI_POLLING_MODE,
+    SPI_INTERRUPT_MODE
+} Spi_AsyncModeType;
+```
+
+### 8.3 函数定义
+
+#### 8.3.1 Spi_Init
+```c
+void Spi_Init(const Spi_ConfigType* ConfigPtr)
+```
+| Service ID | 0x00 |
+| --- | --- |
+
+#### 8.3.2 Spi_DeInit
+```c
+Std_ReturnType Spi_DeInit(void)
+```
+| Service ID | 0x01 |
+| --- | --- |
+
+#### 8.3.3 Spi_WriteIB (LEVEL 0, 2 / IB)
+```c
+Std_ReturnType Spi_WriteIB(
+    Spi_ChannelType Channel,
+    const Spi_DataBufferType* DataBufferPtr
+)
+```
+| Service ID | 0x02 |
+| --- | --- |
+
+#### 8.3.4 Spi_AsyncTransmit (LEVEL 1, 2)
+```c
+Std_ReturnType Spi_AsyncTransmit(Spi_SequenceType Sequence)
+```
+| Service ID | 0x03 |
+| --- | --- |
+
+#### 8.3.5 Spi_ReadIB
+```c
+Std_ReturnType Spi_ReadIB(
+    Spi_ChannelType Channel,
+    Spi_DataBufferType* DataBufferPointer
+)
+```
+| Service ID | 0x04 |
+| --- | --- |
+
+#### 8.3.6 Spi_SetupEB (EB)
+```c
+Std_ReturnType Spi_SetupEB(
+    Spi_ChannelType Channel,
+    const Spi_DataBufferType* SrcDataBufferPtr,
+    Spi_DataBufferType* DesDataBufferPtr,
+    Spi_NumberOfDataType Length
+)
+```
+| Service ID | 0x05 |
+| --- | --- |
+
+#### 8.3.7 Spi_GetStatus
+```c
+Spi_StatusType Spi_GetStatus(void)
+```
+| Service ID | 0x06 |
+| --- | --- |
+
+#### 8.3.8 Spi_GetJobResult
+```c
+Spi_JobResultType Spi_GetJobResult(Spi_JobType Job)
+```
+| Service ID | 0x07 |
+| --- | --- |
+
+#### 8.3.9 Spi_GetSequenceResult
+```c
+Spi_SeqResultType Spi_GetSequenceResult(Spi_SequenceType Sequence)
+```
+| Service ID | 0x08 |
+| --- | --- |
+
+#### 8.3.10 Spi_GetVersionInfo
+```c
+void Spi_GetVersionInfo(Std_VersionInfoType* versioninfo)
+```
+| Service ID | 0x09 |
+| --- | --- |
+
+#### 8.3.11 Spi_SyncTransmit (LEVEL 0, 2)
+```c
+Std_ReturnType Spi_SyncTransmit(Spi_SequenceType Sequence)
+```
+| Service ID | 0x0A |
+| --- | --- |
+
+#### 8.3.12 Spi_GetHWUnitStatus
+```c
+Spi_StatusType Spi_GetHWUnitStatus(Spi_HWUnitType HWUnit)
+```
+| Service ID | 0x0B |
+| --- | --- |
+
+#### 8.3.13 Spi_Cancel
+```c
+void Spi_Cancel(Spi_SequenceType Sequence)
+```
+| Service ID | 0x0C |
+| --- | --- |
+
+#### 8.3.14 Spi_SetAsyncMode (LEVEL 2)
+```c
+Std_ReturnType Spi_SetAsyncMode(Spi_AsyncModeType Mode)
+```
+| Service ID | 0x0D |
+| --- | --- |
+
+### 8.4 调度函数
+
+#### 8.4.1 Spi_MainFunction_Handling
+```c
+void Spi_MainFunction_Handling(void)
+```
+处理异步 SPI 传输。
+
+#### 8.4.2 Spi_MainFunction_Driving (LEVEL 1, 2)
+```c
+void Spi_MainFunction_Driving(void)
+```
+驱动 SPI 硬件(polling 模式)。
+
+### 8.5 回调通知
+
+#### 8.5.1 <Job Notification>
+Job 完成时调用的可配置回调。
+
+#### 8.5.2 <Sequence Notification>
+Sequence 完成时调用的可配置回调。
+
+### 8.6 期望接口
+
+#### 8.6.1 强制接口
+- Det_ReportError
+
+#### 8.6.2 可选接口
+- Dem_SetEventStatus
+
+---
+
+## 9. 时序图
+
+> **[摘要]** 详细时序图见原文 PDF 第 60-77 页(包含多种 Channel/Job/Sequence 组合的同步、异步传输场景)。
+
+主要场景:
+- 9.1 LEVEL 0:同步传输
+- 9.2 LEVEL 1:异步传输 (Write/AsyncTransmit/Read with IB)
+- 9.3 LEVEL 2:混合
+- 9.4 EB:Setup/AsyncTransmit
+- 9.5 混合 Job 传输
+- 9.6 LEVEL 0 同步传输
+
+---
+
+## 10. 配置规范
+
+### 10.1 如何阅读本章
+
+### 10.2 容器与配置参数
+
+#### 10.2.1 Spi
+根容器。
+
+#### 10.2.2 SpiDemEventParameterRefs
+DEM 事件参数引用。
+
+#### 10.2.3 SpiGeneral
+| 参数 | 类型 | 说明 |
+| --- | --- | --- |
+| SpiDevErrorDetect | bool | DET 启用 |
+| SpiVersionInfoApi | bool | 版本信息 API |
+| SpiLevelDelivered | int | 0/1/2 |
+| SpiSupportConcurrentSyncTransmit | bool | 并发同步传输 |
+| SpiInterruptibleSeqAllowed | bool | Sequence 可中断 |
+| SpiChannelBuffersAllowed | int | 缓冲区类型支持(0/1/2) |
+| SpiMainFunctionPeriod | float | main 周期 |
+| SpiCancelApi | bool | 启用 Cancel API |
+| SpiHwStatusApi | bool | 启用 GetHWUnitStatus API |
+
+#### 10.2.4 SpiSequence
+| 参数 | 类型 | 说明 |
+| --- | --- | --- |
+| SpiSeqId | int | Sequence ID |
+| SpiInterruptibleSequence | bool | 可中断 |
+| SpiSequenceEndNotification | string | Sequence 完成回调名 |
+
+#### 10.2.5 SpiChannel
+| 参数 | 类型 | 说明 |
+| --- | --- | --- |
+| SpiChannelId | int | Channel ID |
+| SpiChannelType | enum | IB / EB |
+| SpiDataWidth | int | 数据宽度(位) |
+| SpiDefaultData | int | 默认数据 |
+| SpiEbMaxLength | int | EB 最大长度 |
+| SpiIbNBuffers | int | IB 缓冲区数 |
+| SpiTransferStart | enum | LSB / MSB |
+
+#### 10.2.6 SpiChannelList
+Channel 列表(从属于 Job)。
+
+#### 10.2.7 SpiJob
+| 参数 | 类型 | 说明 |
+| --- | --- | --- |
+| SpiJobId | int | Job ID |
+| SpiJobPriority | int | 优先级 0-3 |
+| SpiJobEndNotification | string | Job 完成回调名 |
+| SpiDeviceAssignment | ref | 外部设备引用 |
+
+#### 10.2.8 SpiExternalDevice
+| 参数 | 类型 | 说明 |
+| --- | --- | --- |
+| SpiBaudrate | float | 波特率 |
+| SpiCsIdentifier | int | CS ID |
+| SpiCsPolarity | enum | HIGH / LOW |
+| SpiCsPin | int | CS 引脚 |
+| SpiCsFunctionUsed | bool | CS 是否启用 |
+| SpiDataShiftEdge | enum | LEADING / TRAILING |
+| SpiShiftClockIdleLevel | enum | LOW / HIGH |
+| SpiTimeBetweenClkAndCs | float | CLK 到 CS 时间 |
+
+#### 10.2.9 SpiDriver
+驱动参数容器。
+
+#### 10.2.10 SpiPublishedInformation
+已发布信息。
+
+> **[摘要]** 完整配置参数详见原文 PDF 第 79-93 页。
+
+### 10.3 已发布信息
+按 BSW General。
+
+### 10.4 配置概念
+
+SPI 处理/驱动通过 ARXML 配置生成 C 代码。
+
+---
+
+## 11. 不适用需求
+
+详见原文 PDF 第 97 页。
+
+---
+
+## 12. 附录
+
+附录详见原文 PDF 第 98-99 页。
+
+---
+
+## 翻译说明
+
+- 本译本基于 AUTOSAR CP 4.4.0 的 SPI 处理驱动规范 (Document ID 038,共 100 页)
+- 摘要标记位置:
+  - 第 6 章需求追溯
+  - 第 9 章时序图
+  - 第 10 章配置参数
+  - 第 11 章不适用需求
+  - 第 12 章附录