Metal Library Archive（Metal 库归档）

• 文件以 0x424c544d (MTLB) 开头；文件大小记录在偏移量 0x10 处。

  int __ZN25MTLLibraryDataWithArchive16parseArchiveSyncEPP7NSErrorb(void * * arg0, bool arg1) {
    r12 = rdx;
    r14 = arg1;
    r13 = arg0;
    (*(*arg0 + 0xb8))(arg0, 0x0); //LibraryWithFile::setPosition(...)
    r15 = r13 + 0x78;
    rbx = (*(*r13 + 0xc0))(r13, r15, 0x58);  //LibraryWithFile::readBytes(...)
    rax = *r13;
    rax = (*(rax + 0xc8))(r13); //LibraryWithFile::getFileSize(...)
    
    // 0x424c544d - MTLB
    // File size field offset: 0x88 - 0x78 = 0x10
    if (((rbx != 0x58) || (*(int32_t *)(r13 + 0x78) != 0x424c544d)) || (*(r13 + 0x88) != rax)) goto loc_6a65b;
    
    ...
    
    loc_6a65b:
    if (r14 == 0x0) goto loc_6a6c5;
  
    loc_6a660:
    rdx = @"Invalid library file";
     
    ...
  }

• 偏移量 0x4 处的一个 Int16 值与目标平台相关。

  loc_6a610:
  // 0x7c - 0x78 = 0x4
  rax = *(int16_t *)(r13 + 0x7c) & 0xffff;
  
  if ((rax >= 0x0) || (r12 == 0x0)) goto loc_6a6ea;
  
  loc_6a627:
  if (r14 == 0x0) goto loc_6a6c5;
  
  loc_6a630:
  rdx = @"This library format is not supported on this platform (or was built with an old version of the tools)";
  goto loc_6a689;

• 存在一个“Header Extension Section”（头部扩展节），其中包含有关“Dynamic Header Section”（动态头部节）、“Imported Symbol List”（导入符号列表）和“Variable List”（变量列表）的信息。

  if (MTLLibraryDataWithArchive::parseHeaderExtension(r13, r13 + 0x100, r14) != 0x0) {
      if (MTLLibraryDataWithArchive::parseDynamicHeaderSection(r13) != 0x0) {
          if (MTLLibraryDataWithArchive::parseImportedSymbolListSection(r13) != 0x0) {
              rax = MTLLibraryDataWithArchive::parseVariableListSection(r13);
          } else {
              rax = 0x0;
          }
      } else {
          rax = 0x0;
      }
  } else {
      rax = 0x0;
  }

• Bitcode 使用 SHA256 进行验证。

  int ____ZN25MTLLibraryDataWithArchive15validateBitCodeEmmPK6NSDataRK12MTLUINT256_t_block_invoke(int arg0) {
      ...
      CC_SHA256_Init(&var_B0);
      CC_SHA256_Update(&var_B0, r14, *(int32_t *)(r15 + 0x38));
      CC_SHA256_Final(&var_48, &var_B0);
      ...
  }

• 许多 FourCC 代码。

  // 0x454e4454 - ENDT
  loc_6a8bc:
  if (rax == 0x454e4454) goto loc_6a871;
  ...
  // 0x54595045 - TYPE
  loc_6a984:
  if (rax == 0x54595045) goto loc_6a9dc;
  ...
  // 0x44594e4c - DYNL
  loc_6ae5b:
  if (rax != 0x44594e4c) goto loc_6b002;
  ...
  // 0x56455253 - VERS
  loc_6b731:
  if (rax == 0x56455253) goto loc_6b81c;

经过一番研究，我大致了解了 metallib 文件的结构。

• 该文件有一个 88 字节的头部，其中包含文件版本、目标平台、库类型、节索引等。

• 文件头中记录了 4 个节：

  • 函数列表

  • 公共元数据

  • 私有元数据

  • Bitcode 模块

  每个节都记录了偏移量和大小。 这意味着节可以是不连续的，这允许 Apple 在它们之间引入新的节而不会破坏兼容性。 Apple 确实为“header extension”节做了这一点 - 它位于函数列表和公共元数据节之间。

• 大多数节（bitcode 节除外）都类似于基于“标签”的结构。

  • FourCharCode 用作标签的名称/类型。

  • 一个 UInt16（在大多数情况下）大小的值紧随标签名称之后。

    源存档数据标签 SARC 不出所料地使用 UInt32 值表示其大小 - 源存档很容易超过 65KB。

  • 标签被分组。

    • 每个组代表一个项目的属性集。

    • 标签组以 ENDT 标签结束。

接下来，我需要弄清楚每个标签/字段保存什么信息。 这很难从 Metal.framework 的汇编中获取，因为

• 某些字段可能纯粹是为工具或调试而设计的，因此 MTLLibraryDataWithArchive 可能只是忽略它们。

• 汇编是平台相关的。 例如，iOS 版本的 MTLLibraryDataWithArchive 可能只会检查 metallib 是否是为 iOS 构建的，而无法判断该库是否是为 macOS 构建的。

• 某些字段很难分析和跟踪。 例子：

  • 函数的 OFFT 标签中有 3 个偏移量，它们指向哪里？ 它们最终如何使用？

  • 函数类型有哪些可能的值？ 每个值的含义是什么？

似乎获得此信息的最快方法是通过实验。

我首先手动编译具有不同着色器、选项和 SDK 的 metal 文件，然后检查我感兴趣的每个字段。 我的桌面很快就被 metallib 文件和 HexFiend 窗口淹没了，但我没有找到太多有用的信息。 我需要一些可以自动构建 metallib 并只向我展示我感兴趣的字段的东西。

我想出了“Test Driven Guessing”（测试驱动猜测法）

1. 基于手头的二进制结构概述编写一个 metallib 解析器。

2. 在解析器中，记录当前未知的字段/标签（或一些相关字段）的值。

3. 创建测试，使用不同类型的着色器和可能影响字段值的编译选项生成 metallib 文件，并使用解析器解析文件数据。

4. 运行测试并分析日志以做出假设。

5. 根据假设更新解析器。

6. 再次运行测试进行验证。

经过几轮，我能够得到函数类型表、目标操作系统表以及 OFFT 标签中 3 个偏移量的含义。

我也在这个过程中发现了一些有趣的事情：

• Metal 不支持 watchOS，但是，可以构建一个针对 watchOS 的 metallib。 Apple 确实在 watchOS SDK 中包含了一些 metallib。（例如：Xcode.app/Contents/Developer/Platforms/WatchOS.platform/Library/Developer/CoreSimulator/Profiles/Runtimes/watchOS.simruntime/Contents/Resources/RuntimeRoot/System/Library/Frameworks/CoreImage.framework/ci_filters.metallib）

• 针对旧版本 iOS 的空 metallib 被 错误地标记为针对 macOS。

• 我无法构建目标操作系统值为 0x85 的 metallib。 起初我认为它可能被保留给隐藏的 realityOS，但后来发现它 更可能是为 bridgeOS。

2022 年 4 月 10 日

像 LAYR、VATY、CNST 等标签包含 Metal 数据类型的 UInt8 值。 可以使用 Metal.framework 中的一个私有类检索每个数据类型值的对应描述 - MTLTypeInternal

id value = [[NSClassFromString(@"MTLTypeInternal") alloc] initWithDataType:0x06];
NSLog(@"%@", value.description); // MTLDataTypeFloat4

我创建了一个命令行工具来生成 Metal 数据类型表。

cd Utilities
swift run metal-data-type-tools gen-markdown --columns 2 # generate a markdown table
swift run metal-data-type-tools gen-swift # generate a Swift enum for Metal data types.

2022 年 3 月 31 日

air-lld (Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/metal/ios/bin/air-lld) 也提供了很多关于 metallib 文件是如何构建的信息。 一些节名称和描述已更新。

int __ZN4llvm3air20MetalLibObjectWriter5writeEv() {
    r14 = rdi;
    rax = llvm::air::MetalLibObjectWriter::writeHeader();
    if (rax != 0x0) goto loc_1000351b9;

loc_100035135:
    rax = llvm::air::MetalLibObjectWriter::writeFunctionList();
    if (rax != 0x0) goto loc_1000351b9;

loc_100035141:
    rax = llvm::air::MetalLibObjectWriter::writeHeaderExtension();
    if (rax != 0x0) goto loc_1000351b9;

loc_10003514d:
    rax = llvm::air::MetalLibObjectWriter::writePublicMetadata();
    if (rax != 0x0) goto loc_1000351b9;

loc_100035159:
    rax = llvm::air::MetalLibObjectWriter::writePrivateMetadata();
    if (rax != 0x0) goto loc_1000351b9;

loc_100035165:
    rax = llvm::air::MetalLibObjectWriter::writeModuleList();
    if (rax != 0x0) goto loc_1000351b9;

loc_100035171:
    rax = llvm::air::MetalLibObjectWriter::writeSources();
    if (rax != 0x0) goto loc_1000351b9;

loc_10003517d:
    rax = llvm::air::MetalLibObjectWriter::writeDynamicHeader();
    if (rax != 0x0) goto loc_1000351b9;

loc_100035189:
    rax = llvm::air::MetalLibObjectWriter::writeVariableList();
    if (rax != 0x0) goto loc_1000351b9;

loc_100035195:
    rax = llvm::air::MetalLibObjectWriter::writeImportedSymbolList();
    if (rax != 0x0) goto loc_1000351b9;

loc_1000351a1:
    rax = llvm::air::MetalLibObjectWriter::computeUUID();
    if (rax != 0x0) goto loc_1000351b9;

loc_1000351ad:
    rax = llvm::air::MetalLibObjectWriter::backpatchAllLocations();
    if (rax == 0x0) goto loc_1000351c2;

loc_1000351b9:
    rbx = rax;
    goto loc_1000351bb;

loc_1000351bb:
    rax = rbx;
    return rax;

loc_1000351c2:
    rbx = 0x0;
    std::__1::system_category();
    goto loc_1000351bb;
}