编译器抽象规范（Specification of Compiler Abstraction）

1 介绍与功能概述（Introduction and functional overview）

本文档规范了用于抽象编译器特定关键字的宏，这些关键字用于声明和定义中的数据和代码寻址。

主要是针对 16 位平台（例如 Cosmic 和 Metrowerks for S12X、Tasking for ST10）的编译器使用特殊关键字来处理微控制器架构的特性，原因在于 16 位地址范围的限制。如果不将内存模型调整为 large 或 huge，编译器的分页（paging）和扩展寻址（用于访问 64K 边界以外的内存）等特性不会被自动启用。数据和代码的位置必须通过特殊关键字显式选择。如果直接在源代码中使用这些关键字，将导致每次移植到新的微控制器系列时都必须修改软件，违反了源代码的平台无关性要求。

如果默认将内存模型切换为 large 或 huge（以规避上述问题），则项目将承受增加的代码大小。

本文档规范了一个三步概念：

1. 文件 Compiler.h 提供用于封装定义和声明的宏。
2. 每个单独的模块必须至少区分以下不同的内存类和指针类。每个类由一个 #define 表示。
3. 文件 Compiler_Cfg.h 允许根据模块描述和构建场景的内存设置，使用适当的编译器特定关键字来配置这些 #define。

2 缩略语与术语（Acronyms and abbreviations）

仅在本文件局部使用、因而未收录到 AUTOSAR 术语表中的缩略语与术语，必须在本节"局部术语表"中列出。

3 相关文档（Related documentation）

3.1 输入文档

3.2 相关规范

AUTOSAR 提供了通用基础软件模块规范 [12]（SWS BSW General），该规范对编译器抽象同样适用。

因此，SWS BSW General 应被视为编译器抽象的附加且必需的规范。

4 约束与假设（Constraints and assumptions）

4.1 限制（Limitations）

在对抽象进行规范和概念验证时，已考虑了 3.1 节中列出的编译器。若任何其他编译器需要的关键字无法映射到本规范描述的机制，则该编译器将不被 AUTOSAR 支持。在这种情况下，编译器厂商必须调整其编译器。

如果物理存在的内存在代码空间或数据空间上大于逻辑可寻址内存，且使用了超过逻辑可寻址空间的部分，则逻辑地址必须被重用。C 语言（以及其他语言）无法处理这种情况。

4.2 对汽车领域的适用性（Applicability to car domains）

无限制。

4.3 对功能安全相关环境的适用性（Applicability to safety related environments）

无限制。编译器抽象文件不实现任何功能，仅包含符号和宏。

5 对其他模块的依赖（Dependencies to other modules）

5.1 文件结构（File structure）

图 1：Compiler.h 的包含结构

«header»                    «header»
Compiler.h                ←  Std_Types.h
        «includes»
                              «includes»
                          «header»
                       Compiler_Cfg.h
  

以下说明描述了与其他间接链接模块的连接：

• 注 1：编译器抽象用于配置元素（指针、变量、函数等）的可寻址性。
• 注 2：内存映射用于执行内存的分段。用户可以为优化源代码而定义段。
• 注 3：链接器设置负责将元素分类到相应的内存段。

6 需求追溯（Requirements traceability）

本规范中实际有效的 SRS 需求追溯如下：

7 功能规范（Functional specification）

7.1 一般行为（General behavior）

7.1.1 编译器符号清单（List of Compiler symbols）

下表根据 SWS_COMPILER_00010 定义了目标编译器符号。此表仅包含示例，并未列出 AUTOSAR 支持的所有可能编译器！

注意：为避免不兼容和/或不一致，编译器符号定义不得在符号后包含任何值。

7.1.2 对使用编译器抽象的实现的要求（Requirements on implementations using compiler abstraction）

<PREFIX> 的组成：

• 对于 BSW 模块：按 <snp>[_<vi>_<ai>] 构成，其中：
  • <snp> 是段名前缀（Section Name Prefix）：
    • 若 BSW 模块描述或软件组件描述中的 MemorySection 未定义 SectionNamePrefix，则 <snp> 应为 BswModuleDescription 的 shortName 转换为大写字母。
    • 若定义了 SectionNamePrefix，则 <snp> 应为与 MemorySection 关联的 SectionNamePrefix 的符号。
  • <vi> 是 BSW 模块的 vendorId。
  • <ai> 是 BSW 模块的 vendorApiInfix。

  方括号中的子部分 [_<vi>_<ai>] 在 BSW 模块未定义 vendorApiInfix（即不使用多实例化）时省略。

• 对于软件组件：<PREFIX> 是软件组件类型的 shortName（大小写敏感）。

<INIT_POLICY>（变量的初始化策略）的取值包括：

• NO_INIT：用于从不清除且从不初始化的变量；
• CLEARED：用于在每次复位后清零的变量；
• POWER_ON_CLEARED：用于仅在上电复位后清零的变量；
• INIT：用于在每次复位后用值初始化的变量；
• POWER_ON_INIT：用于仅在上电复位后用值初始化的变量。

对于形式为 <PREFIX>_<NAME> 的内存类，<NAME> 部分可在 BSW 模块描述或软件组件描述的 MemorySections 中指定。这对生成代码尤其重要：

• 若 MemorySection 未定义 memClassSymbol 属性，则 <NAME> 为所引用 SwAddrMethod 的 shortName（大小写敏感）。
• 仅对 BSW：若定义了 memClassSymbol 属性，则 <NAME> 为 MemorySection 的 memClassSymbol（大小写敏感）。

示例：

原生 C API：

Std_ReturnType Spi_SetupBuffers
(
    Spi_ChannelType       Channel,
    const Spi_DataType   *SrcDataBufferPtr,
    Spi_DataType         *DesDataBufferPtr,
    Spi_NumberOfDataType Length
);

封装后：

FUNC(Std_ReturnType, SPI_CODE) Spi_SetupBuffers
(
    Spi_ChannelType        Channel,
    P2CONST(Spi_DataType, AUTOMATIC, SPI_APPL_DATA) SrcDataBufferPtr,
    P2VAR(Spi_DataType, AUTOMATIC, SPI_APPL_DATA,) DesDataBufferPtr,
    Spi_NumberOfDataType   Length
);

7.1.3 Compiler.h 的内容（Contents of Compiler.h）

#define FUNC(type, memclass) type
/* DIABDATA 不需要 */

符号清单见 7.1.1 节。

其原理是：更改变量、指针或函数的存储类时，模块的实现不应受到影响。

#ifndef COMPILER_H
    #define COMPILER_H
      /* Compiler.h 的实现 */
      ...
    #endif /* COMPILER_H */

7.1.4 Compiler_Cfg.h 的内容（Contents of Compiler_Cfg.h）

7.1.5 综合示例（Comprehensive example）

本示例展示了一个 API 函数中宏的定义、使用和配置位置。

• 模块：Eep
• API 函数：Eep_Read
• 平台：S12X
• 编译器：Cosmic

文件 Eep.c：

#include "Std_Types.h"    /* 该文件已包含 Compiler.h */

FUNC(Std_ReturnType, EEP_CODE) Eep_Read
              (
                  Eep_AddressType EepromAddress,
                  P2VAR(uint8, AUTOMATIC, EEP_APPL_DATA) DataBufferPtr,
                  Eep_LengthType Length
              )

文件 Compiler.h：

#include "Compiler_Cfg.h"

#define AUTOMATIC
#define FUNC(rettype, memclass) rettype memclass
#define P2VAR(ptrtype, memclass, ptrclass) ptrclass ptrtype * memclass

文件 Compiler_Cfg.h：

#define EEP_CODE
#define EEP_APPL_DATA @far    /* NvM 的 RAM 块位于 banked RAM */

依赖关系是什么？

EEP_APPL_DATA 被定义为 far。这意味着指向由 NVRAM Manager 管理的 RAM 块的指针也必须定义为 far。应用程序可以将 RAM 镜像放在 banked RAM 或非 banked RAM 中。RAM 块到 banked RAM 的映射在 <Mip>_MemMap.h 中完成（关于 <Mip> 的更多信息见 [12]）。

由于这些指针也通过 Memory Interface 和 EEPROM Abstraction 传递，因此它们的指针类和内存类必须也匹配 EEP_APPL_DATA。

在 32 位平台上会有什么不同？

尽管只有 S12X 内部有 EEPROM，但从编译器抽象的角度看，唯一变化的是 Compiler_Cfg.h 中的定义。它们将变为空定义：

#define EEP_CODE
#define EEP_APPL_DATA

7.1.6 建议流程（Proposed process）

为支持多供应商环境下的开发和集成，特定的交付流程不可或缺。以下描述可视为建议：

图 2：建议的集成流程
步骤 1：基础文件交付
AUTOSAR 模块供应商：实现源文件和文档、分配版本号和厂商号、实现 Compiler_Cfg.h 和 <Mip>_MemMap.h 的模块特定部分、构建包；交付 Compiler.h、Std_Types.h、Platform_Types.h。
AUTOSAR 集成商：接收并检查包、集成模块、将各模块的 Compiler_Cfg.h 集成到主 Compiler_Cfg.h 中、配置 <Mip>_MemMap.h 和 Compiler_Cfg.h。
步骤 2：模块/组件交付
模块 A/B/C 的 Compiler_Cfg.h 与源代码一起打包交付，由集成环境统一集成。

8 API 规范（API specification）

本节是本模块唯一适用的 API。

8.2.1 通用定义（General definitions）

8.2.1.1 内存类 AUTOMATIC

8.2.1.2 内存类 TYPEDEF

8.2.1.3 NULL_PTR

8.2.1.4 INLINE

8.2.1.5 LOCAL_INLINE

8.2.2 函数定义（Function definitions）

8.2.2.1 FUNC 函数标识信息

示例（Cosmic, S12X）：

#define <PREFIX>_CODE         @near
#define FUNC(rettype, memclass) memclass rettype

/* 函数声明和定义所需用法： */
FUNC(void, <PREFIX>_CODE) ExampleFunction (void);

示例：

typedef P2VAR(uint8, AUTOMATIC, <PREFIX>_VAR) NearDataType;
FUNC(NearDataType, <PREFIX>_CODE)
FarFuncReturnsNearPtr(void);

8.2.2.2 FUNC_P2CONST

8.2.2.3 FUNC_P2VAR

8.2.3 指针定义（Pointer definitions）

8.2.3.1 P2VAR

示例（Metrowerks, S12X）：

#define P2VAR(ptrtype, memclass, ptrclass) \
                   ptrclass ptrtype * memclass

/* 指针声明和定义所需用法： */
#define SPI_APPL_DATA @far
#define SPI_VAR_FAST @near

P2VAR(uint8, SPI_VAR_FAST, SPI_APPL_DATA) Spi_FastPointerToApplData;

8.2.3.2 P2CONST

示例：

/* Metrowerks, S12X */
#define P2CONST(ptrtype, memclass, ptrclass) \
                   const ptrtype memclass * ptrclass

/* Cosmic, S12X */
#define P2CONST(ptrtype, memclass, ptrclass) \
                   const ptrtype ptrclass * memclass

/* Tasking, ST10 */
#define P2CONST(ptrtype, memclass, ptrclass) \
                   const ptrclass ptrtype * memclass

/* 指针声明和定义所需用法： */
#define EEP_APPL_CONST @far
#define EEP_VAR @near

P2CONST(Eep_ConfigType, EEP_VAR, EEP_APPL_CONST) Eep_ConfigurationPtr;

8.2.3.3 CONSTP2VAR

示例（Tasking, ST10）：

#define CONSTP2VAR (ptrtype, memclass, ptrclass) \
                   ptrclass ptrtype * const memclass

/* 所需用法： */
/* 指向应用数据的常量指针 */
CONSTP2VAR (uint8, NVM_VAR, NVM_APPL_DATA)
NvM_PointerToRamMirror = Appl_RamMirror;

8.2.3.4 CONSTP2CONST

8.2.3.5 P2FUNC

8.2.3.6 CONSTP2FUNC

8.2.4 常量定义（Constant definitions）

8.2.4.1 CONST

示例（Cosmic, S12X）：

#define CONST(type, memclass) memclass const type

/* 所需用法： */
#define NVM_CONST @gpage

CONST(uint8, NVM_CONST) NvM_ConfigurationData;

8.2.5 变量定义（Variable definitions）

8.2.5.1 VAR

示例（Tasking, ST10）：

#define VAR(type, memclass) memclass type

/* 所需用法： */
#define NVM_FAST_VAR _near

VAR(uint8, NVM_FAST_VAR) NvM_VeryFrequentlyUsedState;

8.3 类型定义

不适用。

8.4 函数定义

不适用。

8.5 回调通知

不适用。

8.6 调度函数

不适用。

8.7 期望接口

不适用（8.7.1/8.7.2/8.7.3 均不适用）。

8.8 服务接口

不适用（8.8.1–8.8.5 均不适用）。

9 时序图（Sequence diagrams）

不适用。

10 配置规范（Configuration specification）

编译器抽象没有独立的配置接口（即没有单独的参数定义）。取而代之的是，内存映射（见 [13]）的配置已扩展为本章中描述的参数。

10.1 如何阅读本章

强烈建议同时阅读以下文档：分层软件架构 [3]、ECU 配置规范 [4]。

10.2 容器与配置参数

10.2.1 模块特定内存类

也可以配置模块特定内存类。这通过容器 MemMapAddressingModeSet 及其包含的参数 MemMapCompilerMemClassSymbolImpl 完成。详见 [13]。

10.2.2 全局内存类

也可以配置对所有模块有效的全局内存类。这通过容器 MemMapGenericCompilerMemClass 及其包含的参数 MemMapGenericCompilerMemClassSymbolImpl 完成。详见 [13]。

10.3 发布信息（Published Information）

不适用。

11 不适用的需求（Not applicable requirements）