1. 引言/Preface¶

1.1. 目的/Purpose¶

文档主要介绍TopsCC基础工具集中clang / llc / lld / fatbinary / llvm-mc / llvm-objdump / llvm-dis的需求说明

1.2. 术语/Glossary¶

表 1.2.1 术语¶
Name	Description
`GCU`	燧原AI 加速卡
`TopsCC`	燧原编程平台
`clang`	C/C++ 编译器
`llc`	编译器
`lld`	链接器
`fatbinary`	生成包含设备端和主机端运行程序的二进制文件
`llvm-mc`	汇编器
`llvm-dis`	反汇编器
`llvm-objdump`	查看目标文件或可执行文件的组成信息

1.3. 版本/Revision History¶

表 1.3.1 版本¶
Version	Date	Author	Note
v0.1.0	Apil. 13, 2023	Baoqi Liu	创建文档结构
v0.1.1	Aug. 15, 2023	Zhongjun Zhang	补充clang/topscc选项

1.4. 参考/Reference¶

[CUDA Compiler Driver NVCC] (https://docs.nvidia.com/cuda/cuda-compiler-driver-nvcc/index.html)
[CUDA Binary Utilities] (https://docs.nvidia.com/cuda/cuda-binary-utilities/index.html)

2. 概述/Overview¶

2.1. 系统结构图/Architecture¶

2.2. 功能概述/Function Description¶

本文档的这一部分提供有关以下工具的命令行选项的常见详细信息：

clang / llc / lld / fatbinary / llvm-mc / llvm-objdump / llvm-dis

上面工具参考以下规则：

每个命令行选项都有一个长名称和一个短名称。

长名称之前必须有两个连字符。例如，--include-path
短名称之前必须有一个连字符。例如，-I

识别三种类型的命令选项：布尔选项、单值选项和列表选项。

布尔选项：没有参数
单值选项：参数只能指定一个
列表选项：参数可以指定多个

Boolean option : disasm --print-raw <file>
Single value   : disasm --arch GCU200 <file>
List options   : llvm-objdump  --function "foo,bar,foobar" <file>

单值选项和列表选项必须有参数，参数必须在选项名称后跟一个或多个空格或等号字符。

单字符短名称时，选项的值也可以紧跟在选项本身之后，而不用空格或等号字符分隔。
列表选项的各个值可以在选项的单个实例中用逗号分隔，或者选项可以重复，或者这两种情况的任意组合。

-o file
-o=file
-Idir1,dir2 -I=dir3 -I dir4,dir5

2.3. 安装方法/Installation¶

用户首先需要获取并下载TopsCC安装包，并在自定义路径下安装。

支持的系统：Ubuntu 16.04.z(z<=6)、Ubuntu 18.04.z(z<=6)、Ubuntu 20.04.z(z<=5)、Redhat linux 8.6

第一步：获取并下载 TopsCC 安装包

$ wget https://.../topscc.run

第二步：在自定义路径下安装 TopsCC

$ topscc.run /your/install/dir/

默认将安装至 /opt/topscc/ 目录下

第三步: 设置环境变量

安装完成后，为方便后续使用TopsCC，需要将

所指定安装目录 /your/install/dir/bin 加入到环境变量 PATH 中

$ export PATH=/your/install/dir/bin:$PATH

3. 详细设计/Detail Design¶

3.1. clang¶

命令行接口/Command Interface¶

表 3.1.1 命令行接口¶
选项（长）	选项（短）	功能要求	默认值	注释
`--help`	`-h`	帮助
`--preprocess`	`-E`	运行预编译阶段
	`-S`	运行预编译、编译阶段		生成程序集文件
	`-c`	运行预编译、编译、汇编阶段		生成目标.o文件如果没有选择任何阶段参数选项的默认参数
	`-O<value>`	优化等级-O0 不做优化，通常用于debug-O3 执行大部分优化
`--target=<value>`		根据target生成特定code	dtu
`--mcpu=<value>`		根据mcpu生成特定code，支持：gcu200/gcu210/gcu300	N/A
`--include=<paths>`	`-I=<path> <path>...`	指定include 文件路径
`--output=<path>`	`-o=<path>`	指定输出文件路径
`--emit-llvm`	`-emit-llvm`	使用llvm ir bitcode作为输出
	`-ffunction-sections`	将每个func放在自己的段 (ELF Only)
	`-mllvm <value>`	往llc中传递参数
	`-fno-inline`	禁止函数inline

使用范例/Use Case¶

USAGE: clang [options] file…

Example: clang --target=dtu -mcpu=gcu300 -O3 -S test.cpp -o test.s

3.2. topscc¶

命令行接口/Command Interface¶

表 3.2.1 命令行接口¶
选项（长）	选项（短）	功能要求	默认值	注释
`--version`	`-v`	显示topscc版本号
`-std=<value>`	`-std=<value>`	topscc支持的c++标准，目前支持c++11, c++14, c++17	c++11
`-arch=<value>`	`-arch=<value>`	topscc编译出指定架构的目标代码，支持：gcu200,gcu210, gcu300	gcu200	生成特定架构的代码
`-E`	`-E`	生成预处理后的代码，后缀以topsi结尾，内部包含host和device代码
`-S`	`-S`	生成汇编代码，其中混合了host和device代码
`-c`	`-c`	生成机器码，其中包含host和device机器码
`-rdc`	`-rdc`	topscc对设备端代码的处理，默认是整体程序模式，用户需要保证所有设备端代码位于单一源码文件中，但加rdc选项可以将设备代码存储于多个不同的源码文件中，更利于软件项目管理
`-shared -fPIC`	`-shared -fPIC`	将包含设备端的代码编译成动态库
`-save-temps`	`-save-temps`	将编译过程中产生的中间文件保存在当前目录中，方便定位问题
`-D name`	`-D name`	定义宏
`-U name`	`-U name`	消除宏定义
`-O3`	`-O3`	最高级别优化选项	`-O0`
`-L`	`-L`	指定库文件搜索路径
`-Wall`	`-Wall`	打印编程时出现的warning
`-g`	`-g`	增加调试信息
`-h`	`-h`	查看topscc支持的选项
`-arch=<value>`	`-arch=<value>`	根据target生成特定code，支持gcu200/gcu210/gcu300	gcu200
`--include=<paths>`	`-I=<path> <path>...`	指定include文件路径

使用范例/Use Case¶

USAGE: clang [options] file…

Example: topscc a.cpp -arch gcu210 -ltops -o a.out

3.3. llc¶

命令行接口/Command Interface¶

表 3.3.1 命令行接口¶
长选项	短选项	功能要求
`--march=<value>`		指定硬件架构
`--mcpu=<value>`		生成具体GCU型号的指令
`--help`	`-h`	显示可用选项
	`-I=<value>`	包含搜索路径
	`-O=<value>`	优化级别。[-O0, -O1, -O2, or -O3]
`--function-sections`		将每个func放在自己的段 (ELF Only)

使用范例/Use Case¶

USAGE: llc [options]

Example: llc --march=dtu -mcpu=gcu200 test.ll -o test.s

OPTIONS:

Color Options:

–color - Use colors in output (default=autodetect)

General options:

–function-sections           - Emit functions into separate sections
–march=<string>              - Architecture to generate code for (see –version)
–mcpu=<cpu-name>             - Target a specific cpu type (-mcpu=help for details)
-o=<filename>                - Output filename

Generic Options:

–help - Display available options (–help-hidden for more)
–help-list - Display list of available options (–help-list-hidden for more)
–version - Display the version of this program

3.4. lld¶

命令行接口/Command Interface¶

表 3.4.1 命令行接口¶
长选项	短选项	功能要求
/	`-ltopsrt`	链接tops runtime库
/	`-o=<path>`	输出路径
`--library-path=<path>`	`-L=<path>`	包含库文件搜索路径
`--shared`		编译成共享库
`--help`	`-h`	查看可用选项

使用范例/Use Case¶

USAGE: ./ld.lld [options] file…

3.5. fatbinary¶

命令行接口/Command Interface¶

使用范例/Use Case¶

Usage : fatbinary [options]

Option:

–help (-h)

Print this help information on this tool.

–version Print version information on this tool.

3.6. llvm-mc¶

llvm-mc 汇编器，将汇编代码转换成机器码。

命令行接口/Command Interface¶

表 3.6.1 命令行接口¶
长选项	短选项	可选值	功能要求
`--arch=<value>`	`-arch`	dtu	指定GCU架构
`--mattr=<value>`	`-mattr`	+gcu200, +gcu210, +gcu300	生成架构特定的GCU指令
`-filetype=<value>`		asm, obj	选择输出文件格式
	`-I`		指定包含文件路径
	`-o=<filename>`		指定输出文件
`--show-encoding`			显示指令编码

使用范例/Use Case¶

USAGE: llvm-mc [options]

Example: llvm-mc test.s --arch=dtu -mattr=+gcu300 -filetype=obj -o test.o

3.7. llvm-objdump¶

llvm-objdump从二进制文件（独立的和嵌入在主机二进制文件中的文件）中提取信息，并以可读的格式呈现它们。

命令行接口/Command Interface¶

// 下面是cuda cuobjdump的选项，参考并形成topscc的objdump选项

表 3.7.1 命令行接口¶
选项（长）	选项（短）	描述
`--all-fatbin`	`-all`	转储所有 fatbin 部分。默认情况下只会转储可执行 fatbin 的内容（如果存在），否则如果没有可执行 fatbin 则可重定位 fatbin。
`--mcpu=<value>`	`-mcpu=<value>`	反汇编特定GCU架构的文件，可选值：gcu200/gcu300
`--disassemble`	`-d`	反汇编机器指令
`--disassemble-zeroes`	`-z`	反汇编时不忽略0值
`--print-imm-hex`		使用十六进制格式显示立即数
`--help`	`-h`	打印有关此工具的此帮助信息。
`--version`	`-V`	打印有关此工具的版本信息。

使用范例/Use Case¶

llvm-objdump Options:

USAGE: llvm-objdump [options]

Example: llvm-objdump -mcpu=gcu300 -dz test.o -o test.dump

3.8. llvm-dis¶

llvm-dis从独立的bitcode文件中提取信息并以人类可读的格式呈现它们。disasm的输出包括每个内核的汇编代码、ELF 数据部分等。

命令行接口/Command Interface¶

表 3.8.1 命令行接口¶
选项（长）	选项（短）	描述
`--materialize-metadata`		加载模块而不具体化元数据，则仅具体化元数据
	`-o=<filename>`	指定输出文件名

使用范例/Use Case¶

USAGE: llvm-dis [options]

Example: llvm-dis test.bc -o test.ll