# 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 章附录