ROCm Code Object Tooling

ROCm（Radeon Open Compute）提供了一系列的工具，用于检查和提取编译器生成的代码对象，包括可执行文件、目标文件和共享对象库。

一、roc-obj

roc-obj 是 ROCm（Radeon Open Compute）提供的一个高层级工具，用于操作和提取 ROCm 编译器生成的代码对象。

以下是关于 roc-obj 工具的一些使用示例：

1. 提取所有 ROCm 代码对象： 使用以下命令从一系列可执行文件中提取所有的 ROCm 代码对象：

   roc-obj <executable>...

2.  提取并反汇编 ROCm 代码对象： 如果你想提取代码对象并同时进行反汇编，可以使用带有 --disassemble 或简写 -d 选项的命令：

   roc-obj --disassemble <executable>... 
   or 
   roc-obj -d <executable>... 

3. 将 ROCm 代码对象提取到指定目录： 使用 --outdir 或 -o 选项后跟目标目录的路径，可以将提取的代码对象保存到该目录中：

   roc-obj --outdir dir/ <executable>... 
   or 
   roc-obj -o dir/ <executable>... 

二、Low-Level Tooling

1. URI Syntax

ROCm 代码对象可以使用统一资源标识符（URI）语法进行列表显示和访问。以下是 URI 语法的组成部分及其示例：

1. code_object_uri：这是一个通用的代码对象URI，可以是文件URI（file_uri）或内存URI（memory_uri）。

2. file_uri：指向文件系统中的一个代码对象。

       <extract_file> 是经过URI编码的操作系统文件路径，表示代码对象所在的文件。

3. memory_uri：指向内存中的一个代码对象。

       <process_id> 是一个十进制数字，表示包含代码对象的进程ID。

4. range_specifier：定义了要访问的代码对象的一部分。

   • # 或 ? 是范围指定符，用于区分后续的参数。
   • offset= 后面跟随的数字表示从指定位置开始的偏移量。
   • size= 后面跟随的数字表示要访问的数据块的大小。

5. extract_file：表示需要提取的文件，它是经过URI编码的操作系统文件路径。

6. process_id：表示包含代码对象的内存所在进程的唯一标识符，是一个十进制数字。

7. number：可以是以下任意一种格式的数字：

   • HEX_NUMBER：十六进制数，以 "0x" 开头。
   • DECIMAL_NUMBER：十进制数。
   • OCTAL_NUMBER：八进制数，通常以数字开头，但不应以数字0开头，以避免与十六进制混淆。

8. Examples：

   • file://dir1/dir2/hello_world#offset=133&size=14472：表示文件系统中的 hello_world 文件中，从偏移量 133 开始，大小为 14472 字节的代码对象。

   • memory://1234#offset=0x20000&size=3000：表示进程 ID 为 1234 的内存中，从偏移量 0x20000（十六进制）开始，大小为 3000 字节的代码对象。

这种 URI 语法为 ROCm 代码对象提供了一种灵活的访问方式，允许开发者根据需要定位和操作代码对象的特定部分。

2. List available ROCm Code Objects: roc-obj-ls

roc-obj-ls 是 ROCm（Radeon Open Compute）提供的一个工具，用于列出指定宿主可执行文件中嵌入的 ROCm 代码对象。这些代码对象按捆绑编号（bundle number）、条目 ID（entry ID）和 URI 语法列出，提供了一种方法来查看和管理编译后的 GPU 代码。

以下是 roc-obj-ls 工具的使用方式和选项：

• Usage: roc-obj-ls [-v|h] executable...

  • 这个命令后面跟着一个或多个可执行文件名，这些文件包含了要列出的代码对象。

• Options:

  • -v 或 --verbose：详细输出模式。添加列标题，使得输出格式更易于阅读和理解。
  • -h 或 --help：显示帮助信息。提供关于如何使用 roc-obj-ls 工具的说明。

例如，如果你想列出一个名为 my_application 的可执行文件中的所有 ROCm 代码对象，并希望输出包含列标题以便更好地理解结果，你可以使用以下命令：

roc-obj-ls -v my_application

如果你只需要查看帮助信息，以了解如何使用这个工具，可以使用：

roc-obj-ls -h

使用 roc-obj-ls 可以帮助开发者审计和分析他们的应用程序中包含的 GPU 代码，确保它们正确嵌入，并且可以用于调试和性能分析。

3. Extract ROCm Code Objects: roc-obj-extract

roc-obj-extract 是 ROCm（Radeon Open Compute）提供的一个工具，用于从指定的 URI 中提取 ROCm 代码对象。以下是该工具的使用方法和选项：

• Usage: roc-obj-extract [-o|v|h] URI...

  • 这个命令接受一个或多个 URI，这些 URI 指定了要提取的代码对象的位置。

• Options:

  • -o <path>：输出路径。指定提取的代码对象文件的存放位置。如果指定为 -，则将代码对象打印到标准输出（STDOUT）。
  • -v：详细输出模式。在输出中包含额外的信息，如条目 ID。
  • -h：显示帮助信息。

• Input from STDIN：

  • URIs 可以从标准输入（STDIN）中读取，每行一个。

• Output File Naming：

  • 提取的代码对象将被保存在文件中，文件名的格式为：<executable_name>[pid<NUMBER>]-offset<NUMBER>-size<NUMBER>.co。

• Escaping Characters：

  • 如果你从 roc-obj-ls 的输出中复制 URI 作为 roc-obj-extract 的参数，需要转义 & 字符，否则你的 shell 可能会将其解释为后台运行命令的选项。

例如，如果 roc-obj-ls 生成了如下 URI：

file://my_exe#offset=24576&size=46816xxi

你需要使用以下参数来调用 roc-obj-extract：

file://my_exe#offset=24576\&size=46816

示例用法：

• 从 URI 提取代码对象并保存到指定路径：

• roc-obj-extract -o ./output/ file://my_exe#offset=24576&size=46816

• 从标准输入读取 URIs 并提取代码对象，将结果打印到 STDOUT：

• roc-obj-ls | roc-obj-extract -o -

• 提取代码对象并使用详细模式输出更多信息：

• roc-obj-extract -v file://my_exe#offset=24576&size=46816

使用 roc-obj-extract 工具可以帮助开发者提取和分析 GPU 程序的二进制代码对象，这对于性能调优和代码调试非常有用。

4. Examples