Sim Api User Guide(1)

1. Introduction

1.1 Overview

本文件描述了用于在系统仿真环境中对Hexagon核心进行建模的系统应用编程接口（API）。该 API 还用于开发用于仿真的协同仿真模型。
本文件旨在供从事系统仿真和协同仿真模型的开发人员和支持人员使用。

1.2 Type definitions

在本文件中，变量类型是用类型定义来指定的。这些定义在发行版中的头文件 HexagonTypes.h 中定义。
表1-1列出了API中使用的Hexagon特定类型定义。

2. Simulator System API

2.1 Overview

Hexagon仿真器被设计成一个库，可以被系统仿真器动态加载。它支持两种仿真模式:
■独立仿真（如hexagon-sim）。
■作为更大的系统仿真环境的一部分进行仿真。
仿真器库输出了一些可以被系统仿真环境调用的函数。这个应用编程接口（API）支持仿真配置和仿真控制。
仿真器库还支持加载协同仿真模型，并通过专门的API与它们进行通信。
本章包括以下内容:
■仿真器组件
■在独立模式下调用模拟器
■在系统仿真模式下调用模拟器
■文件处理
■状态结果
■仿真器构造器
■协同仿真
■仿真配置
■外部设备API
■运行时仿真器调用
■仿真器控制

2.2 Simulator components

图2-1显示了单机和系统仿真中使用的仿真器组件。

/**Figure 2-1 Simulator components## 2.3 **/
hexagon-sim是一个用于从命令行界面执行独立模拟的命令。命令参数指定仿真环境。
system-sim 代表一个主机程序，它调用 Hexagon 仿真作为更大的系统仿真环境的一部分。
Hexagon构造器（名为HexagonWrapper）在独立模拟和系统模拟中都被用来创建和配置Hexagon模拟器的实例。
Hexagon仿真引擎由构造器调用以执行仿真。
COSIM是一个协同仿真模块，对Hexagon处理器外部的一个或多个设备进行建模。协同仿真通过仿真器API与仿真引擎进行通信。
有关这些组件的更多信息，请参见本章的以下章节，以及Hexagon模拟器用户指南（80-VB419-12）。

2.3 Invoking the simulator in standalone mode

在独立模式下，模拟器使用命令行选项进行配置。

hexagon-sim [options] executable

该可执行文件类似于 "系统模拟 "环境，其中目标平台仅由 Hexagon 核心组成。hexagon-sim 可执行文件使用模拟器 API 来模拟 Hexagon 核心的操作。以下是API功能的概述。
hexagon-sim 首先解析命令行选项，以确定要求模拟的特定 Hexagon 架构。这取决于是否存在专门说明要使用的架构的选项（例如，-mv3c），或者，如果没有明确说明，则通过检查提供的可执行文件来确定架构。在后一种情况下，架构被设置为与可执行文件相匹配。
hexagon-sim首先用指定的处理器架构创建一个HexagonWrapper类（第2.7节）的实例，然后根据传递给它的命令行参数调用配置成员函数（第2.9节）。
配置后，模拟器要么运行到程序终止，要么将控制权交给调试器。在调试模式下，模拟器可以在交互式模式下运行，也可以用TRACE32或GDB这样的调试器运行。
下面的伪代码描述了hexagon-sim的功能。

#include "HexagonTypes.h"
                #include "HexagonWrapper.h"
                main(int argc, char** argv)
                {
                  HEXAPI_Cpu main_arch_type;
                  HexagonWrapper *hex;
                  main_arch_type = findArch(argc, argv); // bail if invalid
                  // Load architecture specific library based on command line
                  // option and/or binary image. Put files in current dir
                  hex = new HexagonWrapper(main_arch_type);
                  // Call configuration methods based on command-line
                  // options passed to the simulator
                  ConfigureOptions(argc, argv);
                  if (InteractiveModeRequested)
                  { start interactive mode }
                  else
                  {  load image and run }
}

2.4 Invoking the simulator in system simulation mode

本节介绍了在系统仿真模式下与 Hexagon 仿真器一起工作的 API 调用。
Hexagon核心的每个架构版本都有自己的模拟器库（其名称为

libhexagoniss$(HEXAGON_VERSION).so or libhexagoniss$(HEXAGON_VERSION).dll). This library is located at $(HEXAGON_TOOLS_INSTALL_DIR)/qc/lib/iss.

HexagonWrapper 类（libwrapper.a）被静态链接到希望实例化 Hexagon 核心的系统仿真应用程序。这个包装器类知道在哪里为所需的架构模拟器找到要加载的库，方法是通过加载器的LD_LIBRARY_PATH环境变量设置，通过链接应用程序向链接器提供特定的路径（ld的-rpath选项），或者在hexagon-sim的情况下，相对于hexagon-sim的可执行路径。提供给 HexagonWrapper 构造函数的架构类型决定了加载哪个库。
例如，如果环境变量LD_LIBRARY_PATH指向要加载的库，那么编译行将看起来类似于这样:

 g++ -o sys_sym sys_sym.c -
                I$(HEXAGON_TOOLS_INSTALL_DIR)/qc/include/iss -
                L$(HEXAGON_TOOLS_INSTALL_DIR)/qc/lib/iss -lwrapper

环境变量LD_LIBRARY_PATH被设置为:

$(HEXAGON_TOOLS_INSTALL_DIR)/qc/lib/iss

为了动态地绑定模拟器库，运行时的链接路径可以硬编码到二进制文件中，如下所示:

 g++ -o sys_sym sys_main.c
              -Wl,-rpath,$(HEXAGON_TOOLS_INSTALL_DIR)/qc/lib/iss -lwrapper

当hexagon-sim从命令行被调用时，库的路径被确定，相对于hexagon-sim的安装路径。

2.5 File handling

所有处理路径或文件名的模拟器API调用都有以下假设:
■用户有正确的文件权限
■由名称字符串指定的实体具有与规范所期望的相同的类型

因此，如果一个API调用需要一个字符串，其内容描述了一个路径（即一个目录），被引用的目录必须存在并且有正确的权限。如果字符串描述的是一个文件，API假定它的格式对平台来说是正确的（“C:… “或”/usr/…”），并且它以正确的权限存在，或者，在模拟器创建文件的情况下，要创建文件的目录存在并具有允许创建文件的权限。
一个枚举类型（HEXAPI_OpenMode）可与文件名一起传递，指示模拟器以调用者指定的方式打开特定文件。例如，这允许将来自模拟的不同部分的跟踪结果串联成一个文件。每个API都指定了模拟器默认使用的打开模式。
/注意/ 用HEX_MODE_WRITE或HEX_MODE_WRITEBINARY打开文件会覆盖文件中的任何现有数据。
配置API只检查指定文件的有效性，但不检查任何文件内容的有效性。一个配置命令可能会成功，但在以后的模拟中会返回一个错误。例如，ConfigureCosim()接受了一个配置文件的名称。cosim配置文件包含要加载的cosim库的名称。如果其中一个cosim库的名字无效，ConfigureCosim()函数就会成功，但随后会产生一个错误。
模拟器为指定的每个文件保持开放的文件句柄，在调用 HexagonWrapper 的析构器（通常是通过删除实例）之前不会关闭文件。在删除 HexagonWrapper 实例之前读取或写入这些文件会产生不可预知的结果。

2.6 Status results

大多数模拟器API函数返回一个函数结果值，表示操作的结果。
API为结果值定义了一套标准的符号（HEXAPI_Status类型）。表2-1列出了这些符号。

/注意/
API函数Run（第2.12.2节）返回一个HEXAPI_CoreState类型的特定函数结果值。