Implement and expose line information

[jan-auer]

This PR implements proper handling for C13 line and file information. Disclaimer: This will need some more testing with PDBs from different sources.

To give due credit, this PR is loosely based on initial work by @jrmuizel.

Backgrounds

Alright, so we've known for a while that module info streams ("modi") can store either C11 or C13 line information. LLVM claims they have only ever encountered C13 -- although that doesn't mean much since they are also not handling OMAPs so far. I did some digging and found that:

• C13 is the format used by VC 7.x and up. I believe this was introduced somewhere around 2002, so no wonder that there's not much out there using older versions. There is also CV_SIGNATURE_C13 = 4, which is the signature used for instance in the module information header.
• C11 is the format used by VC 5.x. A header in the Microsoft PDB repository mentions "uses 32-bit types", which refers to the use of pascal-style length prefixed strings, I believe. Not sure, but since it's quite old I don't care at the moment :)
• There is even C7, which even most of the Microsoft PDB source code ignores to support. Great.

The implementation in this PR tries to cover C13 only, but prepares for the introduction of C11 code, if necessary -- or even a potential successor if that is ever the case.

C13 data in the module info stream consists of a variable number of sub streams of various kinds. Some of those only occur once, while others exist multiple times. To expose line information, only two of those needed to be read, but here's a slightly more complete picture:

• DEBUG_S_FILECHKSMS: Contains a list of files referenced by this module along with content checksums. Each entry also contains a reference to the file name in the string table.
• DEBUG_S_LINES: Contains mappings of code offsets to line numbers, grouped by file (referring to the entries in the file checksums substream).
• DEBUG_S_SYMBOLS: This would contain symbols. I have never seen this substream, however, as symbols were always declared separately before the line substreams. Also, the u32 that the symbol iterator skips at the beginning turns out to have the C13 signature value of 4.
• DEBUG_S_INLINEELINES: Contains inlining information. I want to implement this soon in a follow-up PR, but that also requires to implement the IPI stream.
  • DEBUG_S_STRINGTABLE: A module-local version of the string table. This seems to be unused, since all recent PDBs only use the global string table stored in the /names stream (often referred to as "Name Table" in the original code).
  • ... various other streams that are completely irrelevant to reading line information.

Implementation

• The StringRef type wraps offsets into the string table, and StringTable allows to resolve it into a string value. This follows the exact same pattern as the AddressMap in #17. There are also "convenience" methods StringRef::to_string_lossy and StringRef::to_raw_string, which are not much more convenient but far more obvious than the getter on StringTable.
• All logic regarding lines and file lookups is encapsulated in the LineProgram type returned by ModuleInfo::line_program. This should immediately be familiar to anyone who has worked with Dwarf. It exposes an iterator over line records, and has another function to resolve file names from file indices. It's up to the caller whether and when to look up names.
  • The line program performs an internal static dispatch to the line info implementation. This is boring at the moment, since only C13 is implemented.
  • Everything else is hidden in the c13 submodule. It contains all low-level types from the PDB and slightly higher level structs and iterators to interface with the debug lines and file checksums subsections. Eventually, it might make sense to use these types in other places or even make them public interface, but for the moment it's probably better to leave them private.
• There is a test and example showing basic usage of the new API.

Caveats

Line and column numbers seem to sometimes contain special values. I yet have to find out what they mean. Specifically, I have observed:

• start_line sometimes contains the marker values 0xfeefee (read: "do not step onto") or 0xf00f00 (read: "do not step into"). I am not sure what to do with these lines: Either throw them away or mark them as special in the LineInfo struct. Edit: They are special cased now, and intentionally hidden.
• end_line is actually not a real value in the PDB. Instead, the PDB should contain a delta offset value to the start line. However, I've observed that this is not the case at all, instead it just contains the end line value truncated to 7 bits. This is now reflected in the computation of that value, but there needs to be some more testing around this.
• The column values are often Some(0), which I believe can be treated as None. Again, this needs some more verification.
• Strangely, sometimes the column values -- especially the end column value -- contain complete garbage values. I can only assume these are markers or flags, but I'm lacking most context on this part.

Fixes #19

[jan-auer]

This PR now includes a breaking change: PDB::module_info returns an Option, which is None if the module stream points to 0xffffffff. This is generally treated as a marker for missing streams in PDBs.

I was thinking about introducing a wrapper type StreamNumber that encapsulates this, but this would require more refactoring which exceeds the scope of this PR.

[willglynn]

Thanks!

[jan-auer]

@willglynn Just don't release this right away please :) I'm planning of adding more features quite soon and they might have more breaking changes. Might make sense to batch them up for the next release.

[willglynn]

I figured about as much :-)