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:
DILocationis replaced byDebugLoc-DILocationwill no longer be the default way to store source location information, and will rarely be used; instead,DebugLocshould be used as a direct replacement, and implicit conversion betweenDebugLoc<->DILocationwill be deprecated.DebugLocrequires context - TheDebugLocis 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 functiongetFullDebugLoc(). 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 justgetDebugLoc()when possible.- 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 ofMetadata*(e.g. viagetMetadata()) will now fail. For cases where a reference to a source location from metadata is needed, such as the start/end locations in a loopMDNode,DILocationis now anMDNodewrapper for aDebugLoc. - 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’sMDFunctionLocalContext, 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
DILocationwithDebugLocin all cases whereMetadatais not explicitly required, and do not use implicitDebugLoc->DILocationconversion. - Where
Metadatais explicitly required, create aDILocationfrom an existingDebugLoc. - Use
getFullDebugLoc()when examining the contents of aDebugLoc, andgetDebugLoc()when performing opaque operations, e.g. copying or checking if present.- As a further optimization,
getFullDebugLochas an overload that accepts an existingDebugLocContext, allowing the context to be fetched upfront and reused, which is significantly faster if callinggetFullDebugLocwith the same context many times.
- As a further optimization,
- Prefer to store
DebugLocStorageinstead ofDebugLocin 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 forF, using the returnedDebugLocContextwhen emitting source locations intoF.DebugLoc getLoc(DebugLocContext Context, ...)- Call to create new source locations, using the same arguments asDebugLoc::get(which itself uses almost identical arguments toDILocation::get), and aDebugLocContextreturned bystartFunctionContext(above).DebugLoc addInlinedFunctionContext(DISubprogram *CalleeSP, DebugLoc CallLoc)- Call when creating an inlined function call within the frontend, whereCallLocis the location of the inlined call, and the returnedDebugLocis used as theInlinedAtfor 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::getmust 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 asMetadataRef) have updatedDebugLocequivalents (e.g.someMethod(MetadataRef)has a replacementsomeMethod2(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.