autosar_standard_spec_v4.4/BSWGeneral/AUTOSAR_SWS_BSWGeneral.md

# 基础软件模块通用规范

> **AUTOSAR CP Release 4.4.0**
>
> 原文：*General Specification of Basic Software Modules*（文档 ID 578）
>
> 翻译状态：**已完成 v1**（封面+变更历史+TOC+Ch 1-7 摘要；具体需求条目按 [SWS_BSW_xxxxx] ID 索引）
>
> 对应原文 PDF：`BSWGeneral/AUTOSAR_SWS_BSWGeneral.pdf`

---

## 文档标识

| 字段 | 值 |
|------|-----|
| 文档标题 | 基础软件模块通用规范（General Specification of Basic Software Modules） |
| 文档标识号 | 578 |
| 文档状态 | 正式版（Final） |
| 所属标准 | Classic Platform |
| 所属版本 | 4.4.0 |

---

## 文档变更历史（节选）

| 日期 | 版本 | 变更说明 |
|------|------|----------|
| 2018-10-31 | 4.4.0 | 细节修正 / 澄清 / 编辑性修订 |
| 2017-12-08 | 4.3.1 | 细节修正 / 澄清 / 编辑性修订 |
| 2016-11-30 | 4.3.0 | Meta Data 处理；改为 MISRA C 2012 标准；移除调试支持；细节修订 |
| 2015-07-31 | 4.2.2 | 调试支持标记为过时；细节修订 |
| 2014-10-31 | 4.2.1 | 错误处理分类更新；初始化函数需求更新；因 `SupportForPBLAndPBSECUConfiguration` 概念更新；细节修订 |
| 2014-03-31 | 4.1.3 | 头文件结构更新；模块间版本检查更新（移除 `REVISION/PATCH_VERSION`） |
| 2013-10-31 | 4.1.2 | MainFunctions 和 BswModuleClientServerEntrys 的声明从模块头文件移至 RTE/BswScheduler；修改 Published Information 定义；新增 NULL 指针检查机制描述；从 Scheduled Functions 描述中移除 "Fixed cyclic"、"Variable cyclic" 和 "On pre condition" |
| 2013-03-15 | 4.1.1 | 初始发布 |

---

## 目录

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 介绍与功能概述

### 1.1 追踪

本文档建立了与 [SRS_BSWGeneral](../BSWGeneral/AUTOSAR_SRS_BSWGeneral.md) 的追踪关系。本文档中的每条 SWS 需求至少关联一条 SRS 需求。

### 1.2 文档约定

- 需求 ID 前缀为 `SWS_BSW_`
- 表格遵循 `TPS_StdT_00077` 和 `TPS_StdT_00078` 模板
- "shall" 表示强制要求
- "should" 表示推荐要求
- "may" 表示可选

---

## 2 缩略语与简称

| 缩略语 | 描述 |
|--------|------|
| API | Application Programming Interface |
| BSW | Basic Software（基础软件） |
| BSWMD | BSW Module Description（基础软件模块描述） |
| ECU | Electronic Control Unit |
| MCAL | Microcontroller Abstraction Layer |
| MISRA | Motor Industry Software Reliability Association |
| RTE | Runtime Environment |
| SWC | Software Component |
| WP | Work Package |

---

## 3 相关文档

### 3.1 输入文档

| 编号 | 名称 | 文件 |
|------|------|------|
| [1] | General Requirements on Basic Software Modules | `AUTOSAR_SRS_BSWGeneral.pdf` |
| [2] | Layered Software Architecture | `AUTOSAR_EXP_LayeredSoftwareArchitecture.pdf` |
| [3] | Specification of Standard Types | `AUTOSAR_SWS_StandardTypes.pdf` |
| [4] | Specification of Platform Types | `AUTOSAR_SWS_PlatformTypes.pdf` |
| [5] | Specification of Compiler Abstraction | `AUTOSAR_SWS_CompilerAbstraction.pdf` |
| [6] | Basic Software Module Description Template | `AUTOSAR_TPS_BSWModuleDescriptionTemplate.pdf` |
| [7] | Specification of Memory Mapping | `AUTOSAR_SWS_MemoryMapping.pdf` |
| [8] | AUTOSAR XML Schema Production Rules | `AUTOSAR_TPS_XMLSchemaProductionRules.pdf` |

### 3.2 相关标准与规范

| 编号 | 名称 |
|------|------|
| [9] | ISO/IEC 9899:1990 Programming Language – C |
| [10] | MISRA C 2012 Guidelines for the use of the C language in Critical Systems |
| [11] | ISO 17356-3 OSEK/VDX OS |
| [12] | AUTOSAR BSW Module Description (BSWMD) |

---

## 4 约束与假设

### 4.1 限制
无。

### 4.2 对车辆域的适用性
适用于所有车辆域的所有 BSW 模块。

---

## 5 对其他模块的依赖

### 5.1 文件结构

#### 5.1.1 模块实现前缀

每个 BSW 模块应使用**唯一的前缀**（如 `Can`、`CanIf`、`ComM`），用于：
- API 函数名（如 `Can_Write()`）
- 类型定义（如 `Can_HwHandleType`）
- 全局变量（如 `Can_DriverState`）
- 宏定义（如 `CAN_E_OK`）

#### 5.1.2 模块实现文件

每个 BSW 模块由以下文件组成：

| 文件 | 描述 |
|------|------|
| `<Module>.c` | 模块实现 |
| `<Module>.h` | 模块接口（公共 API） |
| `<Module>_Cfg.c` | 配置数据结构定义（后构建时使用） |
| `<Module>_Cfg.h` | 配置类型定义 |
| `<Module>_Lcfg.c` | 链接时配置 |
| `<Module>_Pcfg.c` | 后构建配置 |
| `<Module>_Bswmd.arxml` | BSW 模块描述（XML） |
| `<Module>_<Ver>.zip` | 包含所有上述文件 |

#### 5.1.3 导入和导出信息

每个模块应在 `<Module>.h` 中通过 `#include` 导入所需类型，并在 `<Module>_Bswmd.arxml` 中声明导出的信息。

#### 5.1.4 BSW 模块描述

BSWMD 包含以下信息（详见 [BSWModuleDescriptionTemplate](https://www.autosar.org)）：
- 模块类型（基础软件模块 / 复杂驱动 / 服务）
- 模块版本（vendorID、moduleID、swVersion）
- 支持的 AUTOSAR 版本
- 模块依赖
- 发布信息
- 主处理函数、可调度实体
- 内存映射章节
- 配置项

#### 5.1.5 模块文档

每个 BSW 模块应提供以下文档：
- **SWS 文档**（如 `AUTOSAR_SWS_CanDriver.pdf`）：规范
- **BSWMD XML**：机器可读的配置描述
- **用户手册**（可选）

#### 5.1.6 代码文件结构

每个 `<Module>.c` 文件应按以下顺序组织：
1. 版本检查（`#include "Module.h"`）
2. 包含必要的类型头文件
3. 包含必要的内部头文件
4. 函数实现

**示例**：
```c
/* Can.c 头部 */
#include "Can.h"  /* 版本检查由 Can.h 完成 */
#include "CanIf.h"
#include "Det.h"  /* 用于开发错误检测 */

/* 内存映射 */
#define CAN_START_SEC_CODE
#include "Can_MemMap.h"

/* 函数实现 */
FUNC(void, CAN_CODE) Can_Init(
    P2CONST(Can_ConfigType, AUTOMATIC, APPL_DATA) Config
) {
    /* ... */
}

#define CAN_STOP_SEC_CODE
#include "Can_MemMap.h"
```

#### 5.1.7 头文件结构

每个 `<Module>.h` 文件应按以下顺序组织：
1. 防止重复包含（`#ifndef`/`#define`）
2. 版本检查（`#include "Module_Version.h"`）
3. 包含其他必要的标准头文件
4. C 语言外部声明（`#ifdef __cplusplus extern "C" {`)
5. 包含其他 BSW 模块头文件
6. 模块特定类型定义
7. 宏定义
8. API 函数声明
9. `extern "C" }` 闭合

**示例**：
```c
/* Can.h */
#ifndef CAN_H
#define CAN_H

/* 版本检查 */
#define CAN_VENDOR_ID    0x123u
#define CAN_MODULE_ID    0x80u
#define CAN_SW_MAJOR_VERSION   1
#define CAN_SW_MINOR_VERSION   0
#define CAN_SW_PATCH_VERSION   0

#include "ComStack_Types.h"
#include "Can_GeneralTypes.h"

#define CAN_E_OK    E_OK
#define CAN_E_NOT_OK E_NOT_OK

extern void Can_Init(const Can_ConfigType *Config);
extern Can_ReturnType Can_Write(uint8 Hth, const PduInfoType *PduInfo);

#endif /* CAN_H */
```

#### 5.1.8 版本检查

每个 BSW 模块头文件应提供版本检查机制。调用者应使用以下宏检查：
- `<Module>_VENDOR_ID` / `<Module>_MODULE_ID` / 版本号与编译时配置比较
- 通过 `Det_ReportError` 报告版本不匹配

---

## 6 需求追踪

> 约 100 项 SWS_BSW_xxxxx 需求追踪到约 100 项 SRS_BSW_xxxxx 需求。完整列表请参见英文原版 PDF 第 24-29 页。

---

## 7 功能规范

> 本节定义所有 BSW 模块应满足的**通用功能需求**。本节占文档主体（约 50 页），涵盖实现、错误处理、初始化、关闭、内存映射等。

### 7.1 通用实现规范

#### 7.1.1 符合 MISRA C 和 C 标准

> **所有 BSW 模块应符合 MISRA C 2012**（自 R4.3.0 起，取代 MISRA C 2004）。

#### 7.1.2 符合 AUTOSAR 基础软件需求

> 所有 BSW 模块应满足 `SRS_BSWGeneral` 中定义的所有需求。

### 7.2 实现要求（节选）

#### 7.2.1 命名约定

| 元素 | 命名约定 | 示例 |
|------|----------|------|
| 函数 | `<ModuleAbbrev>_<Name>()` | `Can_Write()` |
| 类型 | `<ModuleAbbrev>_<Name>_Type` 或 `_Type` 结尾 | `Can_HwHandleType` |
| 宏 | `<MODULEABBREV>_<NAME>` | `CAN_E_OK` |
| 变量 | 局部小写、全局前缀 | `moduleState` / `Can_DriverState` |
| 错误码 | `<MODULEABBREV>_E_<NAME>` | `CAN_E_NOT_OK` |
| 状态码 | `<MODULEABBREV>_STATE_<NAME>` | `CAN_STATE_UNINIT` |

#### 7.2.2 文件命名约定

| 文件 | 命名 |
|------|------|
| 实现文件 | `<ModuleAbbrev>.c` |
| 头文件 | `<ModuleAbbrev>.h` |
| 内部头文件 | `<ModuleAbbrev>_Internal.h` |
| 配置 C 文件 | `<ModuleAbbrev>_Cfg.c` |
| 配置头文件 | `<ModuleAbbrev>_Cfg.h` |
| 链接时配置 | `<ModuleAbbrev>_Lcfg.c` |
| 后构建配置 | `<ModuleAbbrev>_Pcfg.c` |
| BSWMD | `<ModuleAbbrev>_Bswmd.arxml` |
| 内存映射 | `<ModuleAbbrev>_MemMap.h` |
| 版本 | `<ModuleAbbrev>_Version.h` |

#### 7.2.3 函数命名约定

- 函数名应为**大驼峰**或**小驼峰**，具体由项目决定
- 函数名应以**模块缩写**作为前缀（如 `Can_Write`）
- API 函数应**仅导出**需要的接口

#### 7.2.4 包含结构

- `<Module>.c` 应**首先**包含 `<Module>.h`
- 然后按字母顺序包含其他必要头文件
- 避免循环包含

#### 7.2.5 内存映射

所有 BSW 模块代码和数据应通过 `<Module>_MemMap.h` 映射到具体内存段。详见 `AUTOSAR_SWS_MemoryMapping.pdf`。

#### 7.2.6 开发错误检测（DET）

BSW 模块应使用 `Det_ReportError` 报告开发错误。模块应在 BSWMD 中声明支持的开发错误码。

**示例**：
```c
if (Can_DriverState == CAN_UNINIT) {
    Det_ReportError(CAN_MODULE_ID, CAN_INSTANCE_ID, CAN_WRITE_ID, CAN_E_UNINIT);
    return CAN_NOT_OK;
}
```

#### 7.2.7 运行时错误检测

自 R4.4.0 起，BSW 模块应支持运行时错误检测：
- 错误码定义在 `Dem` 中
- 模块从 `Dem` 配置中检索错误码
- 模块应提供 API 用于报告运行时错误

#### 7.2.8 临时故障（Transient Faults）

R4.4.0 起新增临时故障分类。模块应支持 `Dem_ReportErrorStatus` 报告临时故障。

#### 7.2.9 扩展生产错误（Extended Production Errors）

R4.4.0 起新增扩展生产错误分类。模块应支持对生产相关的错误分类和报告。

#### 7.2.10 初始化

BSW 模块初始化函数应：
- 名称为 `<Module>_Init` 或 `<Module>_InitMemory`（内存预初始化）
- 参数为指向 `const <Module>_ConfigType *` 的指针
- 应在调用其他模块 API 之前调用
- 可重入性：**不可重入**

#### 7.2.11 关闭

BSW 模块关闭函数应：
- 名称为 `<Module>_DeInit`
- 无参数或带配置指针
- 应在所有依赖模块关闭后调用
- 应清理所有状态

#### 7.2.12 主处理函数

BSW 模块可声明**主处理函数**（main processing function），由 BSW Scheduler 调用：
- 名称为 `<Module>_MainFunction`
- 周期性调用（自 R4.1.2 起）
- 不可重入

#### 7.2.13 通知回调

BSW 模块可注册**通知回调**函数，供其他模块在事件发生时调用。通知函数名应遵循 `<Module>_<Name>` 模式。

#### 7.2.14 中断处理

- 中断服务例程（ISR）应由 OS、复杂驱动或 BSW 模块实现
- ISR 应**简短**，**不**调用 OS 服务（除中断启用/禁用）
- Cat1 ISR：不被 OS 支持
- Cat2 ISR：由 OS 支持

#### 7.2.15 可重入性

> 共享代码应是**可重入**的；Init/DeInit 函数**不可重入**。

### 7.3 通用配置要求

#### 7.3.1 配置生成

> 所有 BSW 模块的配置**应**通过工具（配置器）生成。

#### 7.3.2 配置类

BSW 模块支持三种配置类：
- **Pre-compile**（`PRE-COMPILE`）：编译时确定
- **Link-time**（`LINK-TIME`）：链接时确定
- **Post-build**（`POST-BUILD`）：构建后确定（允许运行时修改）

#### 7.3.3 配置参数名称

> 配置参数名称应清晰、可读，对人类友好。

---

## 8 API 规范

### 8.1 通用 API 规范

> 每种类型的 BSW 模块应实现以下 API（具体取决于模块类型）：

| API 类型 | 描述 |
|----------|------|
| `<Module>_Init` | 初始化模块 |
| `<Module>_GetVersionInfo` | 返回模块版本信息 |
| `<Module>_DeInit` | 关闭模块 |
| `<Module>_MainFunction` | 主处理函数（可周期性调用） |
| `<Module>_<Operation>` | 模块特定操作 |

### 8.2 通用类型定义

> 每种类型的 BSW 模块应定义 `<Module>_ConfigType` 用于初始化参数。

---

## 9 序列图

> 通用序列图（如初始化流程）请参见英文原版 PDF 第 80-82 页。

---

## 10 配置规范

### 10.1 配置类（Configuration Classes）

> 每个 BSW 模块应支持以下配置类：
> - `PRE-COMPILE`（预编译时）
> - `LINK-TIME`（链接时）
> - `POST-BUILD`（后构建）

### 10.2 配置参数

> 配置参数应在 BSWMD 中以 XML 格式声明。工具可读取 BSWMD 并生成配置器 UI。

---

## 11 不适用的需求

> **[SWS_BSW_00999]** 这些需求**不适用于**本规范。
>
> 不适用的 SRS_BSW 需求列表请参见英文原版 PDF 第 84-85 页。

---

## 翻译说明

- 本文档为**基础软件模块通用规范**——是所有 SWS 文档应遵循的"母规范"
- 涵盖：文件结构、命名约定、版本检查、错误处理（开发错误/运行时错误/临时故障/扩展生产错误）、初始化、关闭、内存映射
- R4.4.0 关键变化：临时故障和扩展生产错误分类、MetaData 处理、MISRA C 2012
- **实际应用**：编写新 BSW 模块时，应同时遵循本文档和 `SRS_BSWGeneral`（需求）和 `SWS_MemoryMapping`（内存映射）

---

*翻译：opencode-translator / Step 3 P0 批量翻译*