提供SymCache支持。

这包括二进制格式的读取器和写入器，以及在写入SymCache之前应用于调试符号的辅助特性和函数。

SymCache结构

一个版本为7的SymCache包含以下主要数据类型，按照以下顺序写入

1. 文件
2. 函数
3. 源位置
4. 地址范围
5. 字符串数据

该格式使用 u32 表示行号、地址、引用和字符串偏移量。行号使用 0 表示未知或无效值。地址、引用和字符串偏移量则使用 u32::MAX。

字符串保存在一个连续的段落中，每个单独的字符串前面都加上4个字节来表示其长度。函数和文件通过指向字符串段的偏移量来引用字符串，因此称为“字符串偏移量”。

文件

一个文件包含其文件名、父目录和编译目录的字符串偏移量。

函数

函数包含名称和编译目录的字符串偏移量，一个u32表示入口地址，一个u32表示源语言。名称是必需的，即名称索引应始终指向有效的字符串。

地址范围

范围保存为连续的u32列表，表示它们的起始地址。

源位置

symcache中的源位置表示源文件中行的可能内联副本。它包含行号、对文件（见上文）的引用、对函数的引用以及引用到将此源位置内联的源位置。除了函数之外的所有这些数据都是可选的。

从范围到源位置的映射

在SymCache中的每个范围都与至少一个源位置相关联。如上所述，每个源位置可能还会引用一个将其内联的源位置。从概念上讲，每个地址范围指向一系列源位置，表示内联函数调用的层次结构。

示例

映射

• 0x0001 - 0x002f
  • trigger_crash在文件b.c的第12行
  • 内联到文件a.c中的main的第10行
• 0x002f - 0x004a
  • trigger_crash在文件b.c的第13行
  • 内联到文件a.c中的main的第10行

在SymCache中的表示如下（为了简化，内联了函数/文件名字符串）

ranges: [
    0x0001 -> 1
    0x002f -> 2
]

source_locations: [{
    file: "a.c"
    line: 10
    function: "main"
    inlined_into: u32::MAX (not inlined)
}, {
    file: "b.c"
    line: 12
    function: "trigger_crash"
    inlined_into: 0 <- index reference to "main"
}, {
    file: "b.c"
    line: 13
    function: "trigger_crash"
    inlined_into: 0 <- index reference to "main"
}]

查找

在SymCache中查找地址addr

1. 通过二分查找找到覆盖addr的范围。
2. 找到属于此范围的源位置。
3. 返回一个从步骤2中找到的源位置开始的源位置序列的迭代器。迭代器通过内联层次结构向上爬升，直到根源位置。

返回的源位置包含其函数、文件和行号的访问器方法。