[PSA] Planned LLVM debug info API changes

We (Sony) are starting to open patches (starting here) that change the representation of source locations in LLVM to use “Function-Local Metadata”, significantly reducing the memory usage for source locations (currently represented by DILocation); more detail can be found here. This introduces some breaking changes to LLVM’s API for DebugLoc and DILocation, and deprecates several existing functions in LLVM’s C-API. A dev implementation, representative of the overall design (but with some missing components and interface changes), can be found here.

Initially, the functional changes will be hidden behind a CMake flag, LLVM_USE_FLMD_SOURCE_LOCS, which will be disabled by default while this feature is being landed in LLVM, but many of the interface changes described below will come into effect before the point where the flag is switched on by default. The following is a shortlist of the most widespread/impactful changes, and how consumers of the API should be updated:

  1. DILocation is replaced by DebugLoc - DILocation will no longer be the default way to store source location information, and will rarely be used; instead, DebugLoc should be used as a direct replacement, and implicit conversion between DebugLoc<->DILocation will be deprecated.
  2. DebugLoc requires context - The DebugLoc is becoming a wide-pointer-like class, containing a set of indexes (DebugLocStorage) and a wrapped pointer to a function-local context (DebugLocContext) where the indexes are used. In most classes (e.g. Instruction), only the indexes are stored as a member, and the context pointer is fetched on-demand from the parent function in a new function getFullDebugLoc(). Since the context pointer isn’t needed to check whether a source location is present or to copy from one instruction to another, it is recommended to use just getDebugLoc() when possible.
  3. Debug locations are no longer Metadata - Source location information is no longer stored as global metadata, so any tools/passes that try to access it as a kind of Metadata* (e.g. via getMetadata()) will now fail. For cases where a reference to a source location from metadata is needed, such as the start/end locations in a loop MDNode, DILocation is now an MDNode wrapper for a DebugLoc.
  4. The Textual IR is changed - For any tools that parse, print, or process textual IR, function-local metadata will require modifications. The new representation uses some minor new syntax, similar to existing metadata but using a double-bang !! prefix, and metadata attachments for instructions, machine instructions, and debug records now implicitly reference that function’s MDFunctionLocalContext, which is attached to the function as !flmd !<index>. Additional flags allow switching between printing in a “readable” format, or a closer-to-memory representation.
    • Test updates for textual IR tests are unfinished; these updates will be gradually phased in and performed via a variety of scripts, as there are far too many tests to update by hand, and the changes are complex enough that no single script is likely to be able to address all cases. All such scripts will be made publicly available to help transition downstream tests.

One additional change outside of the API itself is that scopes and inlined calls are now finite per-function: the use of integer-indexed fields to represent source location information means that there is a maximum indexable number of non-inlined scopes in a function, and a maximum number of inlined calls (including transitively inlined) in a function; the limit for each of these is 2^16. These numbers can be plausibly be increased by 4-8 bits (giving us up to 2^24 scopes/inlined calls), but space for storing the indexes is tight so we want to avoid making them larger than necessary: feedback from codebases where these limits are likely to be pushed, e.g. very large functions (generated/macro-heavy) in PGO builds, or containing a large number of calls with multiple levels of forced inlining, is highly requested. Currently, exceeding these limits triggers an assert (which has not been hit in my testing); for the final implementation, one suitable approach would be to simply drop debug information after reaching these limits, but if there are cases where we are both likely to hit limits and cannot accept dropped debug information then it may be possible to create a “slow” path.

Update Guide

The following is a short summary of how downstream code, including frontends and forks of LLVM itself, can be updated to be compatible with function-local metadata; a more detailed explanation of the new format and its semantics can be found here. For most projects, these changes should be simple enough to perform by hand, but we used scripts and custom clang-tidy transforms to handle the large volume of changes in LLVM; these automated updates will be made available in case they are useful.

The update steps for most typical code in LLVM are as follows:

  • Replace DILocation with DebugLoc in all cases where Metadata is not explicitly required, and do not use implicit DebugLoc->DILocation conversion.
  • Where Metadata is explicitly required, create a DILocation from an existing DebugLoc.
  • Use getFullDebugLoc() when examining the contents of a DebugLoc, and getDebugLoc() when performing opaque operations, e.g. copying or checking if present.
    • As a further optimization, getFullDebugLoc has an overload that accepts an existing DebugLocContext, allowing the context to be fetched upfront and reused, which is significantly faster if calling getFullDebugLoc with the same context many times.
  • Prefer to store DebugLocStorage instead of DebugLoc in function-scoped data structures where possible for performance reasons.

For frontends, the DIBuilder class now has a set of new methods that should be used for creating source locations:

  • DebugLocContext startFunctionContext(Function *F, DISubprogram *SP) - Call when starting to emit code for F, using the returned DebugLocContext when emitting source locations into F.
  • DebugLoc getLoc(DebugLocContext Context, ...) - Call to create new source locations, using the same arguments as DebugLoc::get (which itself uses almost identical arguments to DILocation::get), and a DebugLocContext returned by startFunctionContext (above).
  • DebugLoc addInlinedFunctionContext(DISubprogram *CalleeSP, DebugLoc CallLoc) - Call when creating an inlined function call within the frontend, where CallLoc is the location of the inlined call, and the returned DebugLoc is used as the InlinedAt for source locations in that call.
  • void finalizeFunctionContext(Function *F) - Call when you are finished emitting a function body, and will not be adding any more source locations. After this is called, DebugLoc::get must be used to create source locations within that function.
  • When using the C-API, all of the above also applies, and existing methods that accept or return a DILocation (wrapped as MetadataRef) have updated DebugLoc equivalents (e.g. someMethod(MetadataRef) has a replacement someMethod2(OpaqueDebugLocStorage)).

For non-frontend projects, e.g. downstream LLVM forks, updating code should be simple and straightforward, with some extra manual effort recommended if the code has any notable DebugLoc/DILocation handling. For the frontend-specific updates this will require some extra work to call the start/end context functions when necessary, replace calls to DebugLoc::get/DILocation::get, and access the current function’s DebugLocContext when creating source locations; for clang, this was a relatively small update totalling around ~70 lines changed.

Next Steps

As this work has not yet been reviewed, some API details (and particularly type/function names) may change, but the overall direction is likely to be as written here. Once enough of the patches have landed for the flag to be functional, we will put out a call for users with substantial downstream code to test enabling the flag, to catch any issues that are platform-specific or exist on code paths not exercised by lit or X86 builds of clang/llvm-test-suite.

The current performance includes a ~0.15% slowdown for non-debug builds, a ~0.2% speedup for -O0 -g builds, a ~0.5% speedup for ReleaseLTO-g builds, and some significant max-rss reductions for debug builds, high in variance but roughly ~4.7% for the link step in ReleaseLTO-g builds (and up to 12% for the extreme cases). There are still some outstanding performance improvements to be made, particularly regarding non-debug builds, but these numbers are likely to be roughly representative of the final result.

4 Likes

One thing to note here is that the (more important) stage2-O3 config only shows a +0.03% regression, which should be acceptable (and probably can be reduced, too). This difference could either be benefits from ThinLTO or bad GCC codegen; I wouldn’t care too much about stage1 regressions that don’t show up in stage2.

2 Likes