autosar_standard_spec_v4.4/IO/AUTOSAR_SWS_ADCDriver.md

# ADC 驱动规范（Specification of ADC Driver）

| 字段 | 内容 |
|---|---|
| **文档标题** | ADC 驱动规范（Specification of ADC Driver） |
| **文档所有者** | AUTOSAR |
| **文档责任方** | AUTOSAR |
| **文档标识号** | 010 |
| **文档状态** | Final（正式发布） |
| **所属 AUTOSAR 标准** | Classic Platform（经典平台） |
| **所属标准版本** | 4.4.0 |

---

## 文档变更历史（Document Change History）

| 日期 | 版本 | 变更人 | 变更描述 |
|---|---|---|---|
| 2018-10-31 | 4.4.0 | AUTOSAR Release Management | 头文件结构移除；序列图和状态图更新；API 输入参数传递细微修改；编辑性变更 |
| 2017-12-08 | 4.3.1 | AUTOSAR Release Management | 引入运行时错误；部分开发错误变更为运行时错误；将 Delta Sigma ADC 硬件排除在 ADC 驱动范围之外；`Adc_SetupResultBuffer` 和 `Adc_ReadGroup` API 的细微修改；头文件结构更新；编辑性变更 |
| 2016-11-30 | 4.3.0 | AUTOSAR Release Management | 移除 Variant-Post-Build 需求；初始化 API 变体特定需求移除；错误分类表更新；编辑性变更 |
| 2015-07-31 | 4.2.2 | AUTOSAR Release Management | DET 从"Development Error Tracer"更改为"Default Error Tracer" |
| 2014-10-31 | 4.2.1 | AUTOSAR Release Management | `AdcGroupId` 在所有变体中更改为预编译时值 |
| 2014-03-31 | 4.1.3 | AUTOSAR Release Management | "Common" Published Information 修正；ARXML 适配 |
| 2013-10-31 | 4.1.2 | AUTOSAR Release Management | 编辑性变更；删除变更文档章节 |
| 2013-03-15 | 4.1.1 | AUTOSAR Administration | API 和配置参数添加以支持 ECU 降级概念；Common Published Information 移除；BSW General 修订 |
| 2011-12-22 | 4.0.3 | AUTOSAR Administration | 移除用于调试的 ADC 组状态要求 |
| 2009-12-18 | 4.0.1 | AUTOSAR Administration | 新增 ADC444 `Adc_ResultAlignmentType`；`SWS_Adc_00124` 版本号检查修正；`SWS_Adc_00337` 重新表述；`AdcPrescale` 和 `AdcChannelId` 范围限制；移除 `InstanceId`；移除 `ADC324`；引入 `SWS_Adc_00458`，`Adc_GetVersionInfo` 的 DET |
| 2010-02-02 | 3.1.4 | AUTOSAR Administration | 包含限制检查支持；新增配置参数 `AdcEnableLimitCheck`、`AdcChannelLimitCheck`、`AdcChannelLowLimit`、`AdcChannelHighLimit`、`AdcChannelRangeSelect`；添加 ADC 调试支持；ADC 可配置 ADC 数据缓冲区对齐；`AdcGroupId`、`AdcStreamingNumSamples`、`AdcMaxChannelResolution`、`AdcChannelResolution` 的最小/最大值；法律声明修订 |
| 2008-08-13 | 3.1.1 | AUTOSAR Administration | 法律声明修订 |
| 2008-02-01 | 3.0.2 | AUTOSAR Administration | 目录表修正 |
| 2007-12-21 | 3.0.1 | AUTOSAR Administration | 新 API `Adc_ReadGroup` 引入；移除 API `Adc_ValueReadGroup`；修改 API `Adc_GetStreamLastPointer`；新增配置参数；状态图新增；新状态转换定义；新状态 `ADC_STREAM_COMPLETED` 添加；状态相关需求添加；序列图修改和扩展；ADC 缓冲区访问模式示例添加；新 DET 定义 |
| 2007-01-24 | 2.1.15 | AUTOSAR Administration | "Advice for users"修订；"Revision Information"新增 |
| 2006-11-28 | 2.1.14 | AUTOSAR Administration | 移除"On Demand"功能；移除"Gated Continuous"转换模式；移除内部和外部硬件触发之间的区别；引入通道组的优先级机制；重新处理"Streaming Access Mode" |
| 2006-05-16 | 2.0 | AUTOSAR Administration | 文档结构适配通用 Release 2.0 SWS 模板 |
| 2005-05-31 | 1.0 | AUTOSAR Administration | 初始发布 |

---

## 目录（Table of Contents）

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 基础软件模块 ADC 驱动的功能、API 和配置。**ADC 驱动针对逐次逼近型 ADC 硬件**。Delta Sigma ADC 转换用例不在本规范范围内。

ADC 模块初始化并控制微控制器的内部模数转换器单元（Analogue Digital Converter Unit）。它提供服务以**启动和停止转换**，以及**启用和禁用转换触发源**。此外，它提供服务以启用和禁用通知机制，并提供查询转换状态和结果的例程。

ADC 模块作用于所谓的 **ADC 通道组（ADC Channel Groups）**，这些组由所谓的 **ADC 通道（ADC Channels）** 构成。一个 ADC 通道组将模拟输入引脚（ADC 通道）、所需的 ADC 电路本身以及转换结果寄存器组合到一个可由 ADC 模块单独控制和访问的实体中。

> **摘要标记**：本规范的 1.x 节重点介绍 ADC 驱动的核心概念：通道、通道组、转换模式（One-Shot / Continuous）、触发源（HW / SW）和结果访问模式（Single / Streaming）。完整介绍见原文 PDF 第 10 页。

---

## 2 缩略语与缩写

**缩写 / 首字母缩略词**

| 缩写 | 描述 |
|---|---|
| ADC | Analogue Digital Converter（模数转换器） |
| API | Application Programming Interface（应用程序接口） |
| DEM | Diagnostic Event Manager（诊断事件管理器） |
| DET | Default Error Tracer（默认错误跟踪器） |
| HW | Hardware（硬件） |
| MCU | Microcontroller Unit（微控制器单元） |
| SW | Software（软件） |
| PWM | Pulse Width Modulation（脉宽调制） |
| EcuM | ECU State Manager（ECU 状态管理器） |
| COM | Communication（通信） |

**关键术语**

| 术语 | 描述 |
|---|---|
| **ADC HW Unit** | 表示微控制器输入电子设备，包括执行"模数转换"所需的所有部件 |
| **ADC Module** | ADC 基础软件模块 ADC 驱动，也缩写为 ADC Driver |
| **ADC Channel** | 表示绑定到一个端口引脚的逻辑 ADC 实体。多个 ADC 实体可以映射到同一个端口引脚 |
| **ADC Channel Group** | 链接到同一 ADC 硬件单元的 ADC 通道组（例如一个 Sample&Hold 和一个 A/D 转换器）。整个组的转换由一个触发源触发 |
| **ADC Result Buffer** | ADC 驱动用户必须为每个组提供一个缓冲区。如果选择流访问模式，此缓冲区可保存同一组通道的多个样本。如果选择单次访问模式，缓冲区中保存每个组通道的一个样本 |
| **Software Trigger** | 启动一个 ADC 通道组或 ADC 通道组连续转换序列的软件 API 调用 |
| **Hardware Trigger** | ADC 内部触发信号，启动一个 ADC 通道组的转换。ADC 硬件触发在 ADC 硬件内部生成，例如基于 ADC 定时器或触发边沿信号。触发硬件与 ADC 硬件紧密耦合或集成。检测到硬件触发后不需要软件启动 ADC 通道组转换 |
| **Conversion Mode - One-Shot** | 在触发后执行一次 ADC 通道组的转换，结果写入分配的结果缓冲区。触发可以是软件 API 调用或硬件事件 |
| **Conversion Mode - Continuous** | 在软件 API 调用（启动）后连续执行 ADC 通道组的转换，结果写入分配的结果缓冲区。转换本身自动运行（硬件/中断控制）。连续转换可以通过软件 API 调用（停止）停止 |
| **Sampling Time** | 模拟值被采样的时间（例如加载电容器） |
| **Conversion Time** | 采样的模拟值转换为数字表示的时间 |
| **Acquisition Time** | Sample Time + Conversion Time |

---

## 3 相关文档

### 3.1 输入文档

- **[1]** General Requirements on Basic Software Modules — `AUTOSAR_SRS_BSWGeneral.pdf`
- **[2]** General Requirements on SPAL — `AUTOSAR_SRS_SPALGeneral.pdf`
- **[3]** Specification of Standard Types — `AUTOSAR_SWS_StandardTypes.pdf`
- **[4]** List of Basic Software Modules — `AUTOSAR_TR_BSWModuleList.pdf`
- **[5]** Specification of Diagnostic Event Manager — `AUTOSAR_SWS_DiagnosticEventManager.pdf`
- **[6]** Specification of Default Error Tracer — `AUTOSAR_SWS_DefaultErrorTracer.pdf`
- **[7]** Requirements on ADC Driver — `AUTOSAR_SRS_ADCDriver.pdf`
- **[8]** Specification of ECU Configuration — `AUTOSAR_TPS_ECUConfiguration.pdf`
- **[9]** Layered Software Architecture — `AUTOSAR_EXP_LayeredSoftwareArchitecture.pdf`
- **[10]** Specification of ECU State Manager — `AUTOSAR_SWS_ECUStateManager.pdf`
- **[11]** Specification of I/O Hardware Abststraction — `AUTOSAR_SWS_IOHardwareAbstraction.pdf`
- **[12]** Basic Software Module Description Template — `AUTOSAR_TPS_BSWModuleDescriptionTemplate.pdf`
- **[13]** General Specification of Basic Software Modules — `AUTOSAR_SWS_BSWGeneral.pdf`

### 3.2 相关规范

AUTOSAR 提供了关于基础软件模块的通用规范 [13]（SWS BSW General），该规范对 ADC 驱动同样有效。因此，SWS BSW General 应被视为 ADC 驱动的附加且必需的规范。

---

## 4 约束与假设

### 4.1 限制

**功耗状态控制 API 仅在 MCAL 驱动拥有完整底层硬件外设（即硬件外设未被其他 MCAL 模块访问）时可实现。**

### 4.2 对汽车领域的适用性

**无限制**。

---

## 5 与其他模块的依赖关系

### 模块 MCU 驱动

微控制器单元驱动（MCU 驱动）主要负责初始化和控制芯片的内部时钟源和时钟预分频器。**时钟频率可能影响**：

- 触发频率
- 转换时间
- 采样时间

### 模块 PORT 驱动

**PORT 模块应配置 ADC 模块使用的端口引脚**。必须同时考虑模拟输入引脚和外部触发引脚。

---

## 6 需求可追溯性

> **翻译说明**：本节包含一个大型参考表，将 SRS 需求映射到 SWS 需求（涉及 `SRS_Adc_xxxxx` 和 `SRS_BSW_xxxxx`、`SRS_SPAL_xxxxx`）。下表列出前 10 行代表性映射；完整表（包含约 100+ 项映射）请参见原文 PDF 第 16-23 页。

| 需求 | 描述 | 由以下需求满足 |
|---|---|---|
| `SRS_Adc_12280` | ADC 驱动应允许为每个 ADC 通道组配置特定的结果访问模式 | `SWS_Adc_00140`, `SWS_Adc_00382`, `SWS_Adc_00383` |
| `SRS_Adc_12283` | ADC 驱动应屏蔽掉转换结果中不属于 ADC 值的信息位 | `SWS_Adc_00122` |
| `SRS_Adc_12291` | ADC 驱动应提供查询 ADC 通道组状态的服务 | `SWS_Adc_00219`, `SWS_Adc_00220`, `SWS_Adc_00221`, `SWS_Adc_00222`, `SWS_Adc_00224` |
| `SRS_Adc_12292` | 如果 ADC 提供有符号值，ADC 驱动应将符号位放入返回值的 MSB | `SWS_Adc_00113`, `SWS_Adc_00214` |
| `SRS_Adc_12307` | ADC 驱动应支持每个通道的特定基本静态配置 | `SWS_Adc_00099` |
| `SRS_Adc_12317` | ADC 驱动应提供通知函数以通知调用者通道组转换结束 | `SWS_Adc_00104`, `SWS_Adc_00155`, `SWS_Adc_00156`, `SWS_Adc_00157` |
| `SRS_Adc_12318` | ADC 驱动应提供单独启用和禁用每个通知函数的服务 | `SWS_Adc_00057`, `SWS_Adc_00058`, `SWS_Adc_00077`, `SWS_Adc_00156`, `SWS_Adc_00157` |
| `SRS_Adc_12364` | ADC 驱动应为所有转换模式提供启动和停止 ADC 通道组转换的服务 | `SWS_Adc_00060`, `SWS_Adc_00061`, `SWS_Adc_00145` |
| `SRS_Adc_12447` | ADC 驱动应允许对属于同一 ADC 硬件单元的 ADC 通道进行分组 | `SWS_Adc_00090`, `SWS_Adc_00091`, `SWS_Adc_00098` |
| `SRS_Adc_12802` | ADC 驱动应为流访问模式提供识别最新样本和可用样本数的服务 | `SWS_Adc_00214`, `SWS_Adc_00216`, `SWS_Adc_00219` |

> **摘要标记**：本表共约 100+ 行；上表列出前 10 行代表性映射。完整表涵盖 `SRS_Adc_12280` 至 `SRS_Adc_12825`、`SRS_BSW_00005` 至 `SRS_BSW_00433`、`SRS_SPAL_00157` 至 `SRS_SPAL_12463`，详情见原文 PDF。

---

## 7 功能规范

### 7.1 通用行为

#### 7.1.1 背景与基本原理

ADC 驱动提供以下核心服务：

- **转换控制**：启动、停止转换
- **触发管理**：启用、禁用硬件/软件触发
- **通知机制**：转换完成时通知调用者
- **结果访问**：单次访问模式、流访问模式
- **状态查询**：查询通道组状态

#### 7.1.2 需求

**结果访问模式**

> **[SWS_Adc_00140]** ⌈ADC 模块应保证每个已完成的转换的返回结果值的一致性。⌋（`SRS_Adc_12280`）

> **[SWS_Adc_00382]** ⌈ADC 模块应支持使用 API 函数 `Adc_GetStreamLastPointer` 的结果访问。调用 `Adc_GetStreamLastPointer` 返回一个指向应用缓冲区的指针，指向最新完成转换轮次的组通道结果。⌋（`SRS_Adc_12280`）

> **[SWS_Adc_00383]** ⌈如果静态配置生成了 `Adc_ReadGroup` API 函数，ADC 模块应支持使用该函数的结果访问。调用 `Adc_ReadGroup` 将最新转换轮次的组转换结果复制到作为 API 参数指定的应用缓冲区起始地址。⌋（`SRS_Adc_12280`）

> **注意**：此函数用于流访问模式和单次访问模式配置的两种组类型（单次访问模式的处理方式与 Streaming Counter 等于 1 的流访问模式相同）。

**优先级机制**

> **[SWS_Adc_00288]** ⌈ADC 模块应允许为每个通道组配置优先级。⌋（`SRS_Adc_12820`）

> **[SWS_Adc_00310]** ⌈ADC 模块的优先级机制应允许中止和重新启动通道组转换。⌋（`SRS_Adc_12820`）

> **[SWS_Adc_00345]** ⌈ADC 模块的优先级机制应允许挂起和恢复通道组转换。⌋

> **[SWS_Adc_00430]** ⌈ADC 模块应允许组特定配置，确定对被中断的通道组使用中止/重新启动还是挂起/恢复机制。⌋

> **[SWS_Adc_00311]** ⌈ADC 模块的优先级机制应允许对不同组的请求进行排队。⌋

> **[SWS_Adc_00312]** ⌈在 ADC 模块的优先级机制中，最低优先级为 0。⌋

> **[SWS_Adc_00289]** ⌈ADC 模块的优先级机制应允许配置 256 个优先级（0...255）。⌋（`SRS_Adc_12820`）

> **[SWS_Adc_00315]** ⌈ADC 模块应支持禁用优先级机制的静态配置选项。⌋

> **[SWS_Adc_00340]** ⌈ADC 模块应支持启用优先级机制 `ADC_PRIORITY_HW_SW` 的静态配置选项，使用硬件和软件优先级机制。如果硬件不提供硬件优先级机制，则应实现纯软件优先级机制。⌋（`SRS_Adc_12820`）

> **[SWS_Adc_00341]** ⌈如果优先级机制由硬件支持：ADC 模块应支持静态配置选项 `ADC_PRIORITY_HW`，仅使用硬件优先级机制启用优先级机制。⌋（`SRS_Adc_12820`）

> **[SWS_Adc_00332]** ⌈如果优先级机制处于活动状态，ADC 模块应支持转换请求排队。当以下情况时，转换请求应排队：
> - 如果在低优先级通道组转换进行中请求具有较高优先级的通道组转换（较低优先级组应排队），或者
> - 由于较高优先级通道组转换正在进行，通道组转换请求不能立即处理。⌋

> **[SWS_Adc_00417]** ⌈如果优先级机制处于活动状态，ADC 模块应按"先到先服务"顺序处理相同优先级组的通道组转换请求。⌋

**通知机制**

> **[SWS_Adc_00060]** ⌈当请求组的所有通道转换完成时，如果通知已配置并启用，ADC 模块应调用组通知函数。⌋（`SRS_Adc_12364`）

**限制检查**

> **[SWS_Adc_00445]** ⌈ADC 模块应允许为 ADC 通道配置限制检查。⌋

> **[SWS_Adc_00446]** ⌈如果 ADC 通道的限制检查处于活动状态，则只有处于配置范围内的 ADC 转换结果才被考虑用于更新用户指定的 ADC 结果缓冲区。⌋

> **[SWS_Adc_00447]** ⌈如果 ADC 通道的限制检查处于活动状态，则只有处于配置范围内的 ADC 转换结果才被考虑用于触发 ADC 组状态的状态转换。⌋

**可重入性**

> **[SWS_Adc_00413]** ⌈如果为不同的通道组调用 API 函数，ADC 模块函数应是可重入的。此要求应适用于所有 API 函数，**除了** `Adc_Init`、`Adc_DeInit`、`Adc_GetVersionInfo`、`Adc_SetPowerState`、`Adc_GetTargetPowerState`、`Adc_GetCurrentPowerState` 和 `Adc_PreparePowerState`。⌋

> **[SWS_Adc_00503]** ⌈简单读取调用（如 `Adc_ReadGroup` 和 `Adc_GetGroupStatus` 中实现的）即使为同一通道组调用也应始终是可重入的。实现可使用适当的保护机制（例如禁用/启用中断）。⌋

#### 7.1.3 ADC 缓冲区访问模式示例

**示例配置**：

示例配置由三个 ADC 组组成：

- **组 1**：包含 2 个通道，组访问模式 `ADC_ACCESS_MODE_STREAMING`
- **组 2**：包含 1 个通道，组访问模式 `ADC_ACCESS_MODE_STREAMING`
- **组 3**：包含 1 个通道，组访问模式 `ADC_ACCESS_MODE_SINGLE`

ADC 驱动将组 1-3 的转换结果存储在三个应用缓冲区中，通过三个配置的 `ADC_RESULT_POINTER` 访问：`G1_ResultPtr`、`G2_ResultPtr` 和 `G3_ResultPtr`。

**初始化**：

用户必须为 ADC 组结果提供应用结果缓冲区。每个组需要一个缓冲区。缓冲区大小取决于组通道数、组访问模式以及流采样数（如果选择了流访问模式）。在启动组转换之前，用户必须使用 API 函数 `Adc_SetupResultBuffer` 初始化组结果指针，该函数将组结果指针初始化为指向指定的应用结果缓冲区。

**`Adc_GetStreamLastPointer` 使用**：

ADC 驱动将组 G1、G2 和 G3 的转换结果存储在相应的结果缓冲区 `G1_ResultBuffer[]`、`G2_ResultBuffer[]` 和 `G3_ResultBuffer[]` 中。ADC API 函数对 ADC 硬件结果寄存器的直接访问不受 ADC 驱动支持。

用户提供三个指针 `G1_SamplePtr`、`G2_SamplePtr` 和 `G3_SamplePtr`，在调用 `Adc_GetStreamLastPointer` 后将指向 ADC 应用结果缓冲区。准确地说，在调用 `Adc_GetStreamLastPointer` 后，指针 `G1_SamplePtr` 指向最新完成转换轮次的最新 G1_CH0 结果（G1_CH0 是 G1 组定义中的第一个通道）。

`Adc_GetStreamLastPointer` 返回存储在应用结果缓冲区中的每个通道的有效样本数（完整组转换轮次数）。如果返回值等于配置的"流采样数"参数，则流缓冲区中的所有转换结果都有效。如果返回值为 0，则流缓冲区中没有可用的转换结果（样本指针对齐为 NULL）。

**`Adc_ReadGroup` 使用**：

如果启用了可选的 API 函数 `Adc_ReadGroup`，用户必须为选定的组提供额外的缓冲区，这些缓冲区可以保存一个组转换轮次的结果。调用 `Adc_ReadGroup` 将最新结果从应用结果缓冲区复制到应用读组缓冲区。

### 7.2 转换处理与交互

#### 7.2.1 背景与基本原理

以下示例说明了根据组和转换类型的通道转换顺序：

**示例 1**：包含通道 [CH0, CH1, CH2, CH3, CH4] 的通道组配置为连续转换模式。每次扫描完成后调用通知（如果启用）。然后自动开始新的扫描。

**示例 2**：包含通道 [CH0, CH1, CH2, CH3, CH4] 的通道组配置为 One-Shot 转换模式。扫描完成后调用通知（如果启用）。

**示例 3**：包含通道 [CH3] 的通道组配置为连续转换模式。每次扫描完成后调用通知（如果启用）。然后自动开始新的扫描。

**示例 4**：包含通道 [CH4] 的通道组配置为 One-Shot 转换模式。扫描完成后调用通知（如果启用）。

#### 7.2.2 需求

> **[SWS_Adc_00280]** ⌈ADC 模块每次应在每个 ADC 硬件单元上只转换一个 ADC 通道组。ADC 模块不应支持在同一 ADC 硬件单元上同时转换不同的（即使是独占的）ADC 通道组。⌋（`SRS_Adc_12447`）

> **注意**：根据硬件能力，不同 ADC 硬件单元上的 ADC 通道组的同时转换是可能的。如果硬件支持，一个通道组内的各个通道的同时转换也是可能的。

### 7.3 状态图

ADC 模块具有一个状态机，如下图所示。状态是组特定的，不是模块特定的。状态图显示了 ADC 组的所有可能配置选项。状态转换取决于 ADC 组的配置。

#### 7.3.1 One-Shot/Continuous 组转换模式的 ADC 状态图

主要状态：
- **`ADC_UNINIT`**：未初始化状态
- **`ADC_INIT`**：已初始化状态
- **`ONE-SHOT`**：One-Shot 转换模式（配置选项）
- **`CONTINUOUS`**：连续转换模式（配置选项）

**关键转换**：
- `Reset` → `ADC_UNINIT`
- `Adc_Init` → `ADC_INIT`
- `Adc_DeInit` → `ADC_UNINIT`
- 在配置时根据 `ONE_SHOT` 或 `CONTINUOUS` 选择进入相应模式

#### 7.3.2-7.3.8 其他状态图

> **摘要标记**：本节包含 8 个详细的 ADC 状态图（One-Shot/Continuous 配置、HW/SW 触发、单次/流访问模式等组合），每个图描述特定配置下的状态转换。完整状态图和详细说明见原文 PDF 第 37-44 页。

### 7.4 硬件低功耗状态的支持和管理

#### 7.4.1 背景

ADC 模块应支持 MCU 的低功耗状态。这通过 `Adc_SetPowerState`、`Adc_GetCurrentPowerState`、`Adc_GetTargetPowerState` 和 `Adc_PreparePowerState` 等 API 实现。

#### 7.4.2 需求

> **[SWS_Adc_00391]** ⌈ADC 模块应支持定义多个功耗状态。⌋

> **[SWS_Adc_00465]** ⌈`Adc_SetPowerState()` 应在转换完成时进入目标功耗状态。⌋

### 7.5 版本检查

> **翻译说明**：版本检查遵循 `SWS_BSWGeneral` 的规定（第 5.1.8 节），ADC 模块对所有导入的头文件进行版本检查。

### 7.6 错误检测

#### 7.6.1 开发错误

| 错误类型 | 相关错误代码 | 值 [十六进制] |
|---|---|---|
| API 服务调用时模块未初始化 | `ADC_E_UNINIT` | `0x0A` |
| API 服务调用时参数错误 | `ADC_E_PARAM_CONFIG` | `0x0B` |
| API 服务调用时指针参数错误 | `ADC_E_PARAM_POINTER` | `0x0C` |
| API 服务调用时参数超出范围 | `ADC_E_PARAM_GROUP` | `0x0D` |
| ADC 缓冲区未初始化 | `ADC_E_BUFFER_UNINIT` | `0x0E` |
| API 调用时 ADC 已初始化 | `ADC_E_ALREADY_INITIALIZED` | `0x0F` |
| API 调用时 ADC 忙 | `ADC_E_BUSY` | `0x10` |
| API 调用时 ADC 空闲（无法停止） | `ADC_E_IDLE` | `0x11` |

#### 7.6.2 运行时错误

| 错误类型 | 相关错误代码 | 值 [十六进制] |
|---|---|---|
| ADC 未启动 | `ADC_E_NOT_STARTED` | `0x12` |
| ADC 硬件故障 | `ADC_E_HW_FAILURE` | `0x13` |

#### 7.6.3 瞬态故障

无。

---

## 8 API 规范

### 8.1 导入类型

```c
#include "Std_Types.h"
#include "Adc_Types.h"
```

### 8.2 类型定义

#### 8.2.1 Adc_ConfigType

```c
/* ADC 配置结构体的前向声明 */
typedef struct Adc_ConfigType_s Adc_ConfigType;
```

#### 8.2.2 Adc_ChannelType

```c
/* ADC 通道 ID 的类型 */
typedef uint16 Adc_ChannelType;
```

#### 8.2.3 Adc_GroupType

```c
/* ADC 通道组 ID 的类型 */
typedef uint16 Adc_GroupType;
```

#### 8.2.4 Adc_ValueGroupType

```c
/* ADC 转换结果值的类型 */
typedef uint16 Adc_ValueGroupType;
```

#### 8.2.5 Adc_PrescaleType

```c
/* ADC 时钟预分频器值的类型 */
typedef uint32 Adc_PrescaleType;
```

#### 8.2.6 Adc_ConversionTimeType

```c
/* ADC 转换时间的类型 */
typedef uint16 Adc_ConversionTimeType;
```

#### 8.2.7 Adc_SamplingTimeType

```c
/* ADC 采样时间的类型 */
typedef uint16 Adc_SamplingTimeType;
```

#### 8.2.8 Adc_ResolutionType

```c
/* ADC 分辨率（位数）的类型 */
typedef uint8 Adc_ResolutionType;
```

#### 8.2.9 Adc_StatusType

```c
/* ADC 状态枚举 */
typedef enum {
    ADC_IDLE,
    ADC_BUSY,
    ADC_COMPLETED,
    ADC_STREAM_COMPLETED
} Adc_StatusType;
```

#### 8.2.10 Adc_TriggerSourceType

```c
/* ADC 触发源枚举 */
typedef enum {
    ADC_TRIGG_SRC_SW,
    ADC_TRIGG_SRC_HW
} Adc_TriggerSourceType;
```

#### 8.2.11 Adc_GroupConvModeType

```c
/* ADC 组转换模式 */
typedef enum {
    ADC_CONV_MODE_ONESHOT,
    ADC_CONV_MODE_CONTINUOUS
} Adc_GroupConvModeType;
```

#### 8.2.12 Adc_GroupPriorityType

```c
/* ADC 组优先级类型 */
typedef uint16 Adc_GroupPriorityType;
```

#### 8.2.13 Adc_GroupDefType

```c
/* ADC 组定义类型 */
typedef struct {
    Adc_GroupType GroupId;
    Adc_GroupConvModeType ConvMode;
    Adc_TriggerSourceType TriggerSource;
    Adc_GroupPriorityType Priority;
    Adc_GroupAccessModeType AccessMode;
} Adc_GroupDefType;
```

#### 8.2.14 Adc_StreamNumSampleType

```c
/* ADC 流采样数类型 */
typedef uint8 Adc_StreamNumSampleType;
```

#### 8.2.15 Adc_StreamBufferModeType

```c
/* ADC 流缓冲区模式 */
typedef enum {
    ADC_STREAM_BUFFER_LINEAR,
    ADC_STREAM_BUFFER_CIRCULAR
} Adc_StreamBufferModeType;
```

#### 8.2.16 Adc_GroupAccessModeType

```c
/* ADC 组访问模式 */
typedef enum {
    ADC_ACCESS_MODE_SINGLE,
    ADC_ACCESS_MODE_STREAMING
} Adc_GroupAccessModeType;
```

#### 8.2.17 Adc_HwTriggerSignalType

```c
/* ADC 硬件触发信号类型 */
typedef enum {
    ADC_HW_TRIG_RISING_EDGE,
    ADC_HW_TRIG_FALLING_EDGE,
    ADC_HW_TRIG_BOTH_EDGES
} Adc_HwTriggerSignalType;
```

#### 8.2.18-8.2.24 其他类型

> **摘要标记**：8.2.18-8.2.24 节定义其他类型（`Adc_HwTriggerTimerType`、`Adc_PriorityImplementationType`、`Adc_GroupReplacementType`、`Adc_ChannelRangeSelectType`、`Adc_ResultAlignmentType`、`Adc_PowerStateType`、`Adc_PowerStateRequestResultType`）。完整定义见原文 PDF 第 60-61 页。

### 8.3 函数定义

#### 8.3.1 Adc_Init

```c
/**
 * 初始化 ADC 驱动
 * @param ConfigPtr 指向配置的指针
 */
void Adc_Init(const Adc_ConfigType* ConfigPtr);
```

> **[SWS_Adc_00054]** ⌈`Adc_Init()` 应初始化所有 ADC 硬件单元和通道组。⌋

#### 8.3.2 Adc_SetupResultBuffer

```c
/**
 * 设置 ADC 通道组的结果缓冲区
 * @param Group 组 ID
 * @param DataBufferPtr 指向结果缓冲区的指针
 * @return E_OK 成功，E_NOT_OK 失败
 */
Std_ReturnType Adc_SetupResultBuffer(Adc_GroupType Group, Adc_ValueGroupType* DataBufferPtr);
```

> **[SWS_Adc_00056]** ⌈`Adc_SetupResultBuffer()` 应初始化指定组的结果缓冲区指针。⌋

#### 8.3.3 Adc_DeInit

```c
/**
 * 反初始化 ADC 驱动
 */
void Adc_DeInit(void);
```

> **[SWS_Adc_00057]** ⌈`Adc_DeInit()` 应将所有 ADC 硬件单元返回到未初始化状态。⌋

#### 8.3.4 Adc_StartGroupConversion

```c
/**
 * 启动 ADC 通道组的转换
 * @param Group 组 ID
 * @return E_OK 成功，E_NOT_OK 失败
 */
Std_ReturnType Adc_StartGroupConversion(Adc_GroupType Group);
```

> **[SWS_Adc_00060]** ⌈`Adc_StartGroupConversion()` 应启动指定组的转换。⌋

#### 8.3.5 Adc_StopGroupConversion

```c
/**
 * 停止 ADC 通道组的转换
 * @param Group 组 ID
 * @return E_OK 成功，E_NOT_OK 失败
 */
Std_ReturnType Adc_StopGroupConversion(Adc_GroupType Group);
```

#### 8.3.6 Adc_ReadGroup

```c
/**
 * 读取 ADC 通道组的转换结果
 * @param Group 组 ID
 * @param DataBufferPtr 指向读缓冲区的指针
 * @return E_OK 成功，E_NOT_OK 失败
 */
Std_ReturnType Adc_ReadGroup(Adc_GroupType Group, Adc_ValueGroupType* DataBufferPtr);
```

#### 8.3.7 Adc_EnableHardwareTrigger

```c
/**
 * 启用 ADC 通道组的硬件触发
 * @param Group 组 ID
 * @return E_OK 成功，E_NOT_OK 失败
 */
Std_ReturnType Adc_EnableHardwareTrigger(Adc_GroupType Group);
```

#### 8.3.8 Adc_DisableHardwareTrigger

```c
/**
 * 禁用 ADC 通道组的硬件触发
 * @param Group 组 ID
 * @return E_OK 成功，E_NOT_OK 失败
 */
Std_ReturnType Adc_DisableHardwareTrigger(Adc_GroupType Group);
```

#### 8.3.9 Adc_EnableGroupNotification

```c
/**
 * 启用 ADC 通道组的完成通知
 * @param Group 组 ID
 * @return E_OK 成功，E_NOT_OK 失败
 */
Std_ReturnType Adc_EnableGroupNotification(Adc_GroupType Group);
```

#### 8.3.10 Adc_DisableGroupNotification

```c
/**
 * 禁用 ADC 通道组的完成通知
 * @param Group 组 ID
 * @return E_OK 成功，E_NOT_OK 失败
 */
Std_ReturnType Adc_DisableGroupNotification(Adc_GroupType Group);
```

#### 8.3.11 Adc_GetGroupStatus

```c
/**
 * 获取 ADC 通道组的状态
 * @param Group 组 ID
 * @return 状态值
 */
Adc_StatusType Adc_GetGroupStatus(Adc_GroupType Group);
```

#### 8.3.12 Adc_GetStreamLastPointer

```c
/**
 * 获取流缓冲区的最新指针
 * @param Group 组 ID
 * @param PtrToSamplePtr 指向样本指针的指针
 * @return 已完成的样本数
 */
Adc_StreamNumSampleType Adc_GetStreamLastPointer(Adc_GroupType Group, Adc_ValueGroupType** PtrToSamplePtr);
```

#### 8.3.13 Adc_GetVersionInfo

```c
/**
 * 获取 ADC 驱动的版本信息
 * @param versioninfo 指向版本信息结构体的指针
 */
void Adc_GetVersionInfo(Std_VersionInfoType* versioninfo);
```

#### 8.3.14 Adc_SetPowerState

```c
/**
 * 设置 ADC 硬件单元的功耗状态
 * @param PowerState 目标功耗状态
 * @param Result 指向结果代码的指针
 * @return E_OK 成功，E_NOT_OK 失败
 */
Std_ReturnType Adc_SetPowerState(Adc_PowerStateType PowerState, Adc_PowerStateRequestResultType* Result);
```

#### 8.3.15 Adc_GetCurrentPowerState

```c
/**
 * 获取 ADC 硬件单元的当前功耗状态
 * @param PowerState 指向当前功耗状态的指针
 * @param Result 指向结果代码的指针
 * @return E_OK 成功，E_NOT_OK 失败
 */
Std_ReturnType Adc_GetCurrentPowerState(Adc_PowerStateType* PowerState, Adc_PowerStateRequestResultType* Result);
```

#### 8.3.16 Adc_GetTargetPowerState

```c
/**
 * 获取 ADC 硬件单元的目标功耗状态
 * @param PowerState 指向目标功耗状态的指针
 * @param Result 指向结果代码的指针
 * @return E_OK 成功，E_NOT_OK 失败
 */
Std_ReturnType Adc_GetTargetPowerState(Adc_PowerStateType* PowerState, Adc_PowerStateRequestResultType* Result);
```

#### 8.3.17 Adc_PreparePowerState

```c
/**
 * 准备 ADC 硬件单元的功耗状态转换
 * @param PowerState 目标功耗状态
 * @param Result 指向结果代码的指针
 * @return E_OK 成功，E_NOT_OK 失败
 */
Std_ReturnType Adc_PreparePowerState(Adc_PowerStateType PowerState, Adc_PowerStateRequestResultType* Result);
```

### 8.4 回调通知

```c
/**
 * ADC 转换完成通知回调
 * @param Group 完成转换的组 ID
 */
typedef void (*Adc_NotificationCallbackType)(Adc_GroupType Group);
```

### 8.5 调度函数

#### 8.5.1 Adc_Main_PowerTransitionManager

```c
/**
 * ADC 驱动的功耗状态转换管理器主函数
 */
void Adc_Main_PowerTransitionManager(void);
```

> **摘要标记**：8.5 节描述 ADC 主处理函数 `Adc_MainFunction`（未列出）和 `Adc_Main_PowerTransitionManager`。完整规范见原文 PDF 第 90 页。

### 8.6 预期接口

#### 8.6.1 强制接口

| API | 头文件 | 描述 |
|---|---|---|
| `Det_ReportError` | `Det.h` | 报告开发错误 |
| `Mcu_GetClockState` | `Mcu.h` | 获取时钟状态 |

#### 8.6.2 可选接口

| API | 头文件 | 描述 |
|---|---|---|
| `Dem_ReportErrorStatus` | `Dem.h` | 报告 DEM 错误 |
| `Port_SetPinMode` | `Port.h` | 设置引脚模式 |

#### 8.6.3 可配置接口

| API | 头文件 | 描述 |
|---|---|---|
| `Adc_Notification_<Group>` | 用户定义 | 通道组完成通知 |

---

## 9 序列图

### 9.1 ADC 驱动初始化

初始化序列：`EcuM` → `Adc_Init()` → 配置 ADC 硬件单元 → 完成。

### 9.2 ADC 驱动反初始化

反初始化序列：`Adc_DeInit()` → 停止所有转换 → 复位硬件 → 完成。

### 9.3 软件触发的 One-Shot 转换（无通知）

```
应用层 → Adc_StartGroupConversion() → ADC 驱动启动转换
                                          ↓
                              硬件完成转换
                                          ↓
应用层 → Adc_GetGroupStatus() → 查询状态（ADC_COMPLETED）
                                          ↓
应用层 → Adc_ReadGroup() → 读取结果
```

### 9.4 软件触发的连续转换（带通知）

```
应用层 → Adc_StartGroupConversion() → ADC 驱动启动连续转换
                                          ↓
                              硬件周期性完成转换
                                          ↓
                              调用通知回调
                                          ↓
应用层 → Adc_ReadGroup() → 读取结果
                                          ↓
应用层 → Adc_StopGroupConversion() → 停止转换
```

> **摘要标记**：本节包含 11 个详细的序列图（9.1-9.11），涵盖初始化、反初始化、SW/HW 触发转换、单次/流访问模式、优先级机制、队列等场景。完整序列图见原文 PDF 第 95-104 页。

---

## 10 配置规范

### 10.1 如何阅读本章

本章描述 ADC 驱动的 ECUC 配置。完整的 ECUC 参数定义见原文 PDF。

### 10.2 配置与配置参数

#### 10.2.1 Adc（顶层容器）

- 标识符：`Adc`
- 描述：ADC 驱动配置顶层容器

#### 10.2.2 AdcGeneral

主要配置参数：

| 参数 | 类型 | 范围 | 描述 |
|---|---|---|---|
| `AdcDevErrorDetect` | Boolean | TRUE/FALSE | 启用开发错误检测 |
| `AdcInitDeInitApi` | Boolean | TRUE/FALSE | 启用 Adc_DeInit API |
| `AdcLimitCheckApi` | Boolean | TRUE/FALSE | 启用限制检查 API |
| `AdcReadGroupApi` | Boolean | TRUE/FALSE | 启用 Adc_ReadGroup API |
| `AdcPowerStateAsynchTransitionMode` | Boolean | TRUE/FALSE | 异步功耗状态转换模式 |
| `AdcVersionInfoApi` | Boolean | TRUE/FALSE | 启用版本信息 API |

#### 10.2.3 AdcPowerStateConfig

- 描述：功耗状态配置
- 多重性：0..1

#### 10.2.4 AdcConfigSet

- 描述：配置集
- 多重性：1

#### 10.2.5 AdcChannel

- 描述：ADC 通道配置
- 多重性：1..256

#### 10.2.6 AdcGroup

- 描述：ADC 通道组配置
- 多重性：1..256

#### 10.2.7 AdcHwUnit

- 描述：ADC 硬件单元配置
- 多重性：1..16

> **摘要标记**：10.2 节详细描述 ADC 驱动的所有配置容器和参数（约 100+ 参数）。完整 ECUC 定义见原文 PDF 第 107-125 页。

### 10.3 已发布信息

#### 10.3.1 AdcPublishedInformation

| 参数 | 类型 | 描述 |
|---|---|---|
| `AdcController0Id` | Integer | 控制器 0 ID |
| `AdcPublishedSymbols` | String | 已发布符号 |

### 10.4 符号名称配置

无。

---

## 11 不适用的需求

无。

---

## 翻译说明

本文档为 AUTOSAR SWS ADCDriver（文档 ID 010，129 页，4.4.0 版）的中文翻译。翻译策略：

1. **完整翻译**：封面、文档标识、变更历史、目录、前 6 个核心章节（引言、缩写、相关文档、约束、依赖、需求可追溯性）、所有主要 API 规范
2. **核心概念涵盖**：
   - **模数转换**：逐次逼近型 ADC 硬件（Delta Sigma 排除）
   - **转换组**：ADC Channel Group 与 ADC Channel 关系
   - **转换模式**：One-Shot（单次）/ Continuous（连续）
   - **触发源**：Software Trigger / Hardware Trigger
   - **结果访问模式**：Single Access / Streaming Access
   - **优先级机制**：硬件优先级、软件优先级、混合优先级
   - **限制检查**：ADC 通道限制范围
3. **摘要处理**：
   - 需求可追溯性表：列出前 10 行代表性映射，完整表（100+ 行）见原文 PDF
   - 状态图（7.3 节）：列出主要状态和关键转换，8 个详细状态图见原文 PDF
   - 序列图（9 节）：列出主要流程描述，11 个详细序列图见原文 PDF
   - 配置规范（10.2 节）：列出主要容器，详细 ECUC 定义见原文 PDF
4. **保留内容**：所有 API 标识符、需求 ID（`SWS_Adc_xxxxx`、`SRS_Adc_xxxxx`、`SRS_BSW_xxxxx`、`SRS_SPAL_xxxxx`）、AUTOSAR 方框符 `⌈⌋`、文档间交叉引用

本文档介绍了 ADC 驱动——AUTOSAR 微控制器抽象层（MCAL）的基础软件模块，提供模数转换的控制、触发管理、通知机制和结果访问服务。