Introduction¶

This document aims to provide a high-level overview of the design and APIof the JITLink library. It assumes some familiarity with linking andrelocatable object files, but should not require deep expertise. If you knowwhat a section, symbol, and relocation are then you should find this documentaccessible. If it is not, please submit a patch (Contributing to LLVM) or file abug (How to submit an LLVM bug report).

JITLink is a library forJIT Linking. It was built to support theORC JITAPIs and is most commonly accessed via ORC’s ObjectLinkingLayer API. JITLink wasdeveloped with the aim of supporting the full set of features provided by eachobject format; including static initializers, exception handling, thread localvariables, and language runtime registration. Supporting these features enablesORC to execute code generated from source languages which rely on these features(e.g. C++ requires object format support for static initializers to supportstatic constructors, eh-frame registration for exceptions, and TLV support forthread locals; Swift and Objective-C require language runtime registration formany features). For some object format features support is provided entirelywithin JITLink, and for others it is provided in cooperation with the(prototype) ORC runtime.

JITLink aims to support the following features, some of which are still underdevelopment:

1. Cross-process and cross-architecture linking of single relocatable objectsinto a targetexecutor process.

2. Support for all object format features.

3. Open linker data structures (LinkGraph) and pass system.

JITLink and ObjectLinkingLayer¶

ObjectLinkingLayer is ORCs wrapper for JITLink. It is an ORC layer thatallows objects to be added to aJITDylib, or emitted from some higher levelprogram representation. When an object is emitted,ObjectLinkingLayer usesJITLink to construct aLinkGraph (seeConstructing LinkGraphs) andcalls JITLink’slink function to link the graph into the executor process.

TheObjectLinkingLayer class provides a plugin API,ObjectLinkingLayer::Plugin, which users can subclass in order to inspect andmodifyLinkGraph instances at link time, and react to important JIT events(such as an object being emitted into target memory). This enables many featuresand optimizations that were not possible under MCJIT or RuntimeDyld.

// Plugin class to print the set of defined symbols in an object when that// object is linked.classMyPlugin:publicObjectLinkingLayer::Plugin{public:// Add passes to print the set of defined symbols after dead-stripping.voidmodifyPassConfig(MaterializationResponsibility&MR,jitlink::LinkGraph&G,jitlink::PassConfiguration&Config)override{Config.PostPrunePasses.push_back([this](jitlink::LinkGraph&G){returnprintAllSymbols(G);});}// Implement mandatory overrides:ErrornotifyFailed(MaterializationResponsibility&MR)override{returnError::success();}ErrornotifyRemovingResources(JITDylib&JD,ResourceKeyK)override{returnError::success();}voidnotifyTransferringResources(JITDylib&JD,ResourceKeyDstKey,ResourceKeySrcKey)override{}// JITLink pass to print all defined symbols in G.ErrorprintAllSymbols(LinkGraph&G){for(auto*Sym:G.defined_symbols())if(Sym->hasName())dbgs()<<Sym->getName()<<"\n";returnError::success();}};// Create our LLJIT instance using a custom object linking layer setup.// This gives us a chance to install our plugin.autoJ=ExitOnErr(LLJITBuilder().setObjectLinkingLayerCreator([](ExecutionSession&ES,constTriple&T){// Manually set up the ObjectLinkingLayer for our LLJIT// instance.autoOLL=std::make_unique<ObjectLinkingLayer>(ES,std::make_unique<jitlink::InProcessMemoryManager>());// Install our plugin:OLL->addPlugin(std::make_unique<MyPlugin>());returnOLL;}).create());// Add an object to the JIT. Nothing happens here: linking isn't triggered// until we look up some symbol in our object.ExitOnErr(J->addObject(loadFromDisk("main.o")));// Plugin triggers here when our lookup of main triggers linking of main.oautoMainSym=J->lookup("main");

LinkGraph¶

JITLink maps all relocatable object formats to a genericLinkGraph typethat is designed to make linking fast and easy (LinkGraph instances canalso be created manually. SeeConstructing LinkGraphs).

Relocatable object formats (e.g. COFF, ELF, MachO) differ in their details,but share a common goal: to represent machine level code and data withannotations that allow them to be relocated in a virtual address space. Tothis end they usually contain names (symbols) for content defined inside thefile or externally, chunks of content that must be moved as a unit (sectionsor subsections, depending on the format), and annotations describing how topatch content based on the final address of some target symbol/section(relocations).

At a high level, theLinkGraph type represents these concepts as a decoratedgraph. Nodes in the graph represent symbols and content, and edges representrelocations. Each of the elements of the graph is listed here:

• Addressable – A node in the link graph that can be assigned an addressin the executor process’s virtual address space.

  Absolute and external symbols are represented using plainAddressableinstances. Content defined inside the object file is represented using theBlock subclass.

• Block – AnAddressable node that hasContent (or is marked aszero-filled), a parentSection, aSize, anAlignment (and anAlignmentOffset), and a list ofEdge instances.

  Blocks provide a container for binary content which must remain contiguous inthe target address space (alayout unit). Many interesting low leveloperations onLinkGraph instances involve inspecting or mutating blockcontent or edges.

  • Content is represented as anllvm::StringRef, and accessible viathegetContent method. Content is only available for content blocks,and not for zero-fill blocks (useisZeroFill to check, and prefergetSize when only the block size is needed as it works for bothzero-fill and content blocks).

  • Section is represented as aSection& reference, and accessible viathegetSection method. TheSection class is described in more detailbelow.

  • Size is represented as asize_t, and is accessible via thegetSize method for both content and zero-filled blocks.

  • Alignment is represented as auint64_t, and available via thegetAlignment method. It represents the minimum alignment requirement (inbytes) of the start of the block.

  • AlignmentOffset is represented as auint64_t, and accessible via thegetAlignmentOffset method. It represents the offset from the alignmentrequired for the start of the block. This is required to support blockswhose minimum alignment requirement comes from data at some non-zero offsetinside the block. E.g. if a block consists of a single byte (with bytealignment) followed by a uint64_t (with 8-byte alignment), then the blockwill have 8-byte alignment with an alignment offset of 7.

  • list ofEdge instances. An iterator range for this list is returned bytheedges method. TheEdge class is described in more detail below.

• Symbol – An offset from anAddressable (often aBlock), with anoptionalName, aLinkage, aScope, aCallable flag, and aLive flag.

  Symbols make it possible to name content (blocks and addressables areanonymous), or target content with anEdge.

  • Name is represented as anllvm::StringRef (equal tollvm::StringRef() if the symbol has no name), and accessible via thegetName method.

  • Linkage is one ofStrong orWeak, and is accessible via thegetLinkage method. TheJITLinkContext can use this flag to determinewhether this symbol definition should be kept or dropped.

  • Scope is one ofDefault,Hidden, orLocal, and is accessible viathegetScope method. TheJITLinkContext can use this to determinewho should be able to see the symbol. A symbol with default scope should beglobally visible. A symbol with hidden scope should be visible to otherdefinitions within the same simulated dylib (e.g. ORCJITDylib) orexecutable, but not from elsewhere. A symbol with local scope should only bevisible within the currentLinkGraph.

  • Callable is a boolean which is set to true if this symbol can be called,and is accessible via theisCallable method. This can be used toautomate the introduction of call-stubs for lazy compilation.

  • Live is a boolean that can be set to mark this symbol as root fordead-stripping purposes (seeGeneric Link Algorithm). JITLink’sdead-stripping algorithm will propagate liveness flags through the graph toall reachable symbols before deleting any symbols (and blocks) that are notmarked live.

• Edge – A quad of anOffset (implicitly from the start of thecontainingBlock), aKind (describing the relocation type), aTarget, and anAddend.

  Edges represent relocations, and occasionally other relationships, betweenblocks and symbols.

  • Offset, accessible viagetOffset, is an offset from the start of theBlock containing theEdge.

  • Kind, accessible viagetKind is a relocation type – it describeswhat kinds of changes (if any) should be made to block content at the givenOffset based on the address of theTarget.

  • Target, accessible viagetTarget, is a pointer to aSymbol,representing whose address is relevant to the fixup calculation specified bythe edge’sKind.

  • Addend, accessible viagetAddend, is a constant whose interpretationis determined by the edge’sKind.

• Section – A set ofSymbol instances, plus a set ofBlockinstances, with aName, a set ofProtectionFlags, and anOrdinal.

  Sections make it easy to iterate over the symbols or blocks associated witha particular section in the source object file.

  • blocks() returns an iterator over the set of blocks defined in thesection (asBlock* pointers).

  • symbols() returns an iterator over the set of symbols defined in thesection (asSymbol* pointers).

  • Name is represented as anllvm::StringRef, and is accessible via thegetName method.

  • ProtectionFlags are represented as a sys::Memory::ProtectionFlags enum,and accessible via thegetProtectionFlags method. These flags describewhether the section is readable, writable, executable, or some combinationof these. The most common combinations areRW- for writable data,R-- for constant data, andR-X for code.

  • SectionOrdinal, accessible viagetOrdinal, is a number used to orderthe section relative to others. It is usually used to preserve sectionorder within a segment (a set of sections with the same memory protections)when laying out memory.

For the graph-theorists: TheLinkGraph is bipartite, with one set ofSymbol nodes and one set ofAddressable nodes. EachSymbol node hasone (implicit) edge to its targetAddressable. EachBlock has a set ofedges (possibly empty, represented asEdge instances) back to elements oftheSymbol set. For convenience and performance of common algorithms,symbols and blocks are further grouped intoSections.

TheLinkGraph itself provides operations for constructing, removing, anditerating over sections, symbols, and blocks. It also provides metadataand utilities relevant to the linking process:

• Graph element operations

  • sections returns an iterator over all sections in the graph.

  • findSectionByName returns a pointer to the section with the givenname (as aSection*) if it exists, otherwise returns a nullptr.

  • blocks returns an iterator over all blocks in the graph (across allsections).

  • defined_symbols returns an iterator over all defined symbols in thegraph (across all sections).

  • external_symbols returns an iterator over all external symbols in thegraph.

  • absolute_symbols returns an iterator over all absolute symbols in thegraph.

  • createSection creates a section with a given name and protection flags.

  • createContentBlock creates a block with the given initial content,parent section, address, alignment, and alignment offset.

  • createZeroFillBlock creates a zero-fill block with the given size,parent section, address, alignment, and alignment offset.

  • addExternalSymbol creates a new addressable and symbol with a givenname, size, and linkage.

  • addAbsoluteSymbol creates a new addressable and symbol with a givenname, address, size, linkage, scope, and liveness.

  • addCommonSymbol convenience function for creating a zero-filled blockand weak symbol with a given name, scope, section, initial address, size,alignment and liveness.

  • addAnonymousSymbol creates a new anonymous symbol for a given block,offset, size, callable-ness, and liveness.

  • addDefinedSymbol creates a new symbol for a given block with a name,offset, size, linkage, scope, callable-ness and liveness.

  • makeExternal transforms a formerly defined symbol into an external oneby creating a new addressable and pointing the symbol at it. The existingblock is not deleted, but can be manually removed (if unreferenced) bycallingremoveBlock. All edges to the symbol remain valid, but thesymbol must now be defined outside thisLinkGraph.

  • removeExternalSymbol removes an external symbol and its targetaddressable. The target addressable must not be referenced by any othersymbols.

  • removeAbsoluteSymbol removes an absolute symbol and its targetaddressable. The target addressable must not be referenced by any othersymbols.

  • removeDefinedSymbol removes a defined symbol, butdoes not removeits target block.

  • removeBlock removes the given block.

  • splitBlock split a given block in two at a given index (useful whereit is known that a block contains decomposable records, e.g. CFI recordsin an eh-frame section).

• Graph utility operations

  • getName returns the name of this graph, which is usually based on thename of the input object file.

  • getTargetTriple returns anllvm::Triple for the executor process.

  • getPointerSize returns the size of a pointer (in bytes) in the executorprocess.

  • getEndianness returns the endianness of the executor process.

  • allocateString copies data from a givenllvm::Twine into thelink graph’s internal allocator. This can be used to ensure that contentcreated inside a pass outlives that pass’s execution.

Generic Link Algorithm¶

JITLink provides a generic link algorithm which can be extended / modified atcertain points by the introduction of JITLinkPasses.

At the end of each phase the linker packages its state into acontinuationand calls theJITLinkContext object to perform a (potentially high-latency)asynchronous operation: allocating memory, resolving external symbols, andfinally transferring linked memory to the executing process.

1. Phase 1

   This phase is called immediately by thelink function as soon as theinitial configuration (including the pass pipeline setup) is complete.

   1. Run pre-prune passes.

      These passes are called on the graph before it is pruned. At this stageLinkGraph nodes still have their original vmaddrs. A mark-live pass(supplied by theJITLinkContext) will be run at the end of thissequence to mark the initial set of live symbols.

      Notable use cases: marking nodes live, accessing/copying graph data thatwill be pruned (e.g. metadata that’s important for the JIT, but not neededfor the link process).

   2. Prune (dead-strip) theLinkGraph.

      Removes all symbols and blocks not reachable from the initial set of livesymbols.

      This allows JITLink to remove unreachable symbols / content, includingoverridden weak and redundant ODR definitions.

   3. Run post-prune passes.

      These passes are run on the graph after dead-stripping, but before memoryis allocated or nodes assigned their final target vmaddrs.

      Passes run at this stage benefit from pruning, as dead functions and datahave been stripped from the graph. However new content can still be addedto the graph, as target and working memory have not been allocated yet.

      Notable use cases: Building Global Offset Table (GOT), Procedure LinkageTable (PLT), and Thread Local Variable (TLV) entries.

   4. Asynchronously allocate memory.

      Calls theJITLinkContext’sJITLinkMemoryManager to allocate bothworking and target memory for the graph. As part of this process theJITLinkMemoryManager will update the addresses of all nodesdefined in the graph to their assigned target address.

      Note: This step only updates the addresses of nodes defined in this graph.External symbols will still have null addresses.

2. Phase 2

   1. Run post-allocation passes.

      These passes are run on the graph after working and target memory havebeen allocated, but before theJITLinkContext is notified of thefinal addresses of the symbols in the graph. This gives these passes achance to set up data structures associated with target addresses beforeany JITLink clients (especially ORC queries for symbol resolution) canattempt to access them.

      Notable use cases: Setting up mappings between target addresses andJIT data structures, such as a mapping between__dso_handle andJITDylib*.

   2. Notify theJITLinkContext of the assigned symbol addresses.

      CallsJITLinkContext::notifyResolved on the link graph, allowingclients to react to the symbol address assignments made for this graph.In ORC this is used to notify any pending queries forresolved symbols,including pending queries from concurrently running JITLink instances thathave reached the next step and are waiting on the address of a symbol inthis graph to proceed with their link.

   3. Identify external symbols and resolve their addresses asynchronously.

      Calls theJITLinkContext to resolve the target address of any externalsymbols in the graph.

3. Phase 3

   1. Apply external symbol resolution results.

      This updates the addresses of all external symbols. At this point allnodes in the graph have their final target addresses, however nodecontent still points back to the original data in the object file.

   2. Run pre-fixup passes.

      These passes are called on the graph after all nodes have been assignedtheir final target addresses, but before node content is copied intoworking memory and fixed up. Passes run at this stage can make lateoptimizations to the graph and content based on address layout.

      Notable use cases: GOT and PLT relaxation, where GOT and PLT accesses arebypassed for fixup targets that are directly accessible under the assignedmemory layout.

   3. Copy block content to working memory and apply fixups.

      Copies all block content into allocated working memory (following thetarget layout) and applies fixups. Graph blocks are updated to point atthe fixed up content.

   4. Run post-fixup passes.

      These passes are called on the graph after fixups have been applied andblocks updated to point to the fixed up content.

      Post-fixup passes can inspect blocks contents to see the exact bytes thatwill be copied to the assigned target addresses.

   5. Finalize memory asynchronously.

      Calls theJITLinkMemoryManager to copy working memory to the executorprocess and apply the requested permissions.

4. Phase 3.

   1. Notify the context that the graph has been emitted.

      CallsJITLinkContext::notifyFinalized and hands off theJITLinkMemoryManager::FinalizedAlloc object for this graph’s memoryallocation. This allows the context to track/hold memory allocations andreact to the newly emitted definitions. In ORC this is used to update theExecutionSession instance’s dependence graph, which may result inthese symbols (and possibly others) becomingReady if all of theirdependencies have also been emitted.

ErrorrelaxGOTEdges(LinkGraph&G){for(auto*B:G.blocks())for(auto&E:B->edges())if(E.getKind()==x86_64::GOTLoad){auto&GOTTarget=getGOTEntryTarget(E.getTarget());if(isInRange(B.getFixupAddress(E),GOTTarget)){// Rewrite B.getContent() at fixup address from// MOVQ to LEAQ// Update edge target and kind.E.setTarget(GOTTarget);E.setKind(x86_64::PCRel32);}}returnError::success();}

ErrorregisterEHFrameSection(LinkGraph&G){if(auto*Sec=G.findSectionByName("__eh_frame")){SectionRangeSR(*Sec);registerEHFrameSection(SR.getStart(),SR.getEnd());}returnError::success();}

StringRefFunctionName="foo";std::vector<ExecutorAddr>CallSitesForFunction;autoRecordCallSites=[&](LinkGraph&G)->Error{for(auto*B:G.blocks())for(auto&E:B.edges())if(E.getKind()==CallEdgeKind&&E.getTarget().hasName()&&E.getTraget().getName()==FunctionName)CallSitesForFunction.push_back(B.getFixupAddress(E));returnError::success();};

/// Called when allocation has been completed.usingOnAllocatedFunction=unique_function<void(Expected<std::unique_ptr<InFlightAlloc>)>;/// Called when deallocation has completed.usingOnDeallocatedFunction=unique_function<void(Error)>;/// Call to allocate memory.virtualvoidallocate(constJITLinkDylib*JD,LinkGraph&G,OnAllocatedFunctionOnAllocated)=0;/// Call to deallocate memory.virtualvoiddeallocate(std::vector<FinalizedAlloc>Allocs,OnDeallocatedFunctionOnDeallocated)=0;

usingOnFinalizedFunction=unique_function<void(Expected<FinalizedAlloc>)>;usingOnAbandonedFunction=unique_function<void(Error)>;/// Called prior to finalization if the allocation should be abandoned.virtualvoidabandon(OnAbandonedFunctionOnAbandoned)=0;/// Called to transfer working memory to the target and apply finalization.virtualvoidfinalize(OnFinalizedFunctionOnFinalized)=0;

Connection to the ORC Runtime¶

The ORC Runtime (currently under development) aims to provide runtime supportfor advanced JIT features, including object format features that requirenon-trivial action in the executor (e.g. running initializers, managing threadlocal storage, registering with language runtimes, etc.).

ORC Runtime support for object format features typically requires cooperationbetween the runtime (which executes in the executor process) and JITLink (whichruns in the JIT process and can inspect LinkGraphs to determine what actionsmust be taken in the executor). For example: Execution of MachO staticinitializers in the ORC runtime is performed by thejit_dlopen function,which calls back to the JIT process to ask for the list of address ranges of__mod_init sections to walk. This list is collated by theMachOPlatformPlugin, which installs a pass to record this information foreach object as it is linked into the target.

Constructing LinkGraphs¶

Clients usually access and manipulateLinkGraph instances that were createdfor them by anObjectLinkingLayer instance, but they can be created manually:

1. By directly constructing and populating aLinkGraph instance.

2. By using thecreateLinkGraph family of functions to create aLinkGraph from an in-memory buffer containing an object file. This is howObjectLinkingLayer usually createsLinkGraphs.

1. createLinkGraph_<Object-Format>_<Architecture> can be used whenboth the object format and architecture are known ahead of time.

2. createLinkGraph_<Object-Format> can be used when the object format isknown ahead of time, but the architecture is not. In this case thearchitecture will be determined by inspection of the object header.

3. createLinkGraph can be used when neither the object format northe architecture are known ahead of time. In this case the object headerwill be inspected to determine both the format and architecture.

JIT Linking¶

The JIT linker concept was introduced in LLVM’s earlier generation of JIT APIs,MCJIT. In MCJIT theRuntimeDyld component enabled re-use of LLVM as anin-memory compiler by adding an in-memory link step to the end of the usualcompiler pipeline. Rather than dumping relocatable objects to disk as a compilerusually would, MCJIT passed them to RuntimeDyld to be linked into a targetprocess.

This approach to linking differs from standardstatic ordynamic linking:

Astatic linker takes one or more relocatable object files as input and linksthem into an executable or dynamic library on disk.

Adynamic linker applies relocations to executables and dynamic libraries thathave been loaded into memory.

AJIT linker takes a single relocatable object file at a time and links itinto a target process, usually using a context object to allow the linked codeto resolve symbols in the target.

The llvm-jitlink tool¶

Thellvm-jitlink tool is a command line wrapper for the JITLink library.It loads some set of relocatable object files and then links them usingJITLink. Depending on the options used it will then execute them, or validatethe linked memory.

Thellvm-jitlink tool was originally designed to aid JITLink development byproviding a simple environment for testing.

%cathello-world.c#include <stdio.h>intmain(intargc,char*argv[]){printf("hello, world!\n");return0;}%clang-c-ohello-world.ohello-world.c%llvm-jitlinkhello-world.oHello,World!

%catprint-args.c#include <stdio.h>voidprint_args(intargc,char*argv[]){for(inti=0;i!=argc;++i)printf("arg %i is \"%s\"\n",i,argv[i]);}%catprint-args-main.cvoidprint_args(intargc,char*argv[]);intmain(intargc,char*argv[]){print_args(argc,argv);return0;}%clang-c-oprint-args.oprint-args.c%clang-c-oprint-args-main.oprint-args-main.c%llvm-jitlinkprint-args.oprint-args-main.o-argsabcarg0is"a"arg1is"b"arg2is"c"

voidirrelevant_function(){irrelevant_external();}intfunction_to_mock(intX){return/* some function of X */;}staticvoidfunction_to_test(){...intY=function_to_mock();printf("Y is %i\n",Y);}

voidfunction_to_test();intfunction_to_mock(intX){printf("used mock utility function\n");return42;}intmain(intargc,char*argv[]){function_to_test():return0;}

%clang-c-otest_code_harness.otest_code_harness.c%llvm-jitlink-phony-externalstest_code.o-harnesstest_code_harness.ousedmockutilityfunctionYis42

Roadmap¶

JITLink is under active development. Work so far has focused on the MachOimplementation. In LLVM 12 there is limited support for ELF on x86-64.

Major outstanding projects include:

• Refactor architecture support to maximize sharing across formats.

  All formats should be able to share the bulk of the architecture specificcode (especially relocations) for each supported architecture.

• Refactor ELF link graph construction.

  ELF’s link graph construction is currently implemented in theELF_x86_64.cppfile, and tied to the x86-64 relocation parsing code. The bulk of the code isgeneric and should be split into an ELFLinkGraphBuilder base class along thesame lines as the existing generic MachOLinkGraphBuilder.

• Implement support for arm32.

• Implement support for other new architectures.