llvm.org GIT mirror llvm / ba9118a
[Kaleidoscope][BuildingAJIT] Add a description of the KaleidoscopeJIT addModule method to Chapter1 of the BuildingAJIT tutorial. git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@270778 91177308-0d34-0410-b5e6-96231b3b80d8 Lang Hames 3 years ago
2 changed file(s) with 115 addition(s) and 24 deletion(s). Raw diff Collapse all Expand all
185185
186186 .. code-block:: c++
187187
188 ModuleHandleT addModule(std::unique_ptr M) {
189 // We need a memory manager to allocate memory and resolve symbols for this
190 // new module. Create one that resolves symbols by looking back into the
191 // JIT.
192 auto Resolver = createLambdaResolver(
193 [&](const std::string &Name) {
194 if (auto Sym = CompileLayer.findSymbol(Name, false))
195 return RuntimeDyld::SymbolInfo(Sym.getAddress(), Sym.getFlags());
196 return RuntimeDyld::SymbolInfo(nullptr);
197 },
198 [](const std::string &S) { return nullptr; });
199 std::vector> Ms;
200 Ms.push_back(std::move(M));
201 return CompileLayer.addModuleSet(singletonSet(std::move(M)),
202 make_unique(),
203 std::move(Resolver));
204 }
205
206 *To be done: describe addModule -- createLambdaResolver, resolvers, memory
207 managers, why 'module set' rather than a single module...*
188 ModuleHandle addModule(std::unique_ptr M) {
189 // Build our symbol resolver:
190 // Lambda 1: Look back into the JIT itself to find symbols that are part of
191 // the same "logical dylib".
192 // Lambda 2: Search for external symbols in the host process.
193 auto Resolver = createLambdaResolver(
194 [&](const std::string &Name) {
195 if (auto Sym = CompileLayer.findSymbol(Name, false))
196 return RuntimeDyld::SymbolInfo(Sym.getAddress(), Sym.getFlags());
197 return RuntimeDyld::SymbolInfo(nullptr);
198 },
199 [](const std::string &S) {
200 if (auto SymAddr =
201 RTDyldMemoryManager::getSymbolAddressInProcess(Name))
202 return RuntimeDyld::SymbolInfo(SymAddr, JITSymbolFlags::Exported);
203 return RuntimeDyld::SymbolInfo(nullptr);
204 });
205
206 // Build a singlton module set to hold our module.
207 std::vector> Ms;
208 Ms.push_back(std::move(M));
209
210 // Add the set to the JIT with the resolver we created above and a newly
211 // created SectionMemoryManager.
212 return CompileLayer.addModuleSet(std::move(Ms),
213 make_unique(),
214 std::move(Resolver));
215 }
216
217 Now we come to the first of our central JIT API methods: addModule. This method
218 is responsible for adding IR to the JIT and making it available for execution.
219 In this initial implementation of our JIT we will make our modules "available
220 for execution" by compiling them immediately as they are added to the JIT. In
221 later chapters we will teach our JIT to be lazier and instead add the Modules
222 to a "pending" list to be compiled if and when they are first executed.
223
224 To add our module to the IRCompileLayer we need to supply two auxiliary
225 objects: a memory manager and a symbol resolver. The memory manager will be
226 responsible for managing the memory allocated to JIT'd machine code, applying
227 memory protection permissions, and registering JIT'd exception handling tables
228 (if the JIT'd code uses exceptions). In our simple use-case we can just supply
229 an off-the-shelf SectionMemoryManager instance. The memory, exception handling
230 tables, etc. will be released when we remove the module from the JIT again
231 (using removeModule) or, if removeModule is never called, when the JIT class
232 itself is destructed.
233
234 The second auxiliary class, the symbol resolver, is more interesting for us. It
235 exists to tell the JIT where to look when it encounters an *external symbol* in
236 the module we are adding. External symbols are any symbol not defined within the
237 module itself, including calls to functions outside the JIT and calls to
238 functions defined in other modules that have already been added to the JIT. It
239 may seem as though modules added to the JIT should "know about one another" by
240 default, but since we would still have to supply a symbol resolver for
241 references to code outside the JIT it turns out to re-use this one mechanism
242 for all symbol resolution. This has the added benefit that the user has full
243 control over the symbol resolution process. Should we search for definitions
244 within the JIT first, then fall back on external definitions? Or should we
245 prefer external definitions where available and only JIT code if we don't
246 already have an available implementation? By using a single symbol resolution
247 scheme we are free to choose whatever makes the most sense for any given use
248 case.
249
250 Building a symbol resolver is made especially easy by the
251 *createLambdaResolver* function. This function takes two lambdas (actually
252 they don't have to be lambdas, any object with a call operator will do) and
253 returns a RuntimeDyld::SymbolResolver instance. The first lambda is used as
254 the implementation of the resolver's findSymbolInLogicalDylib method. This
255 method searches for symbol definitions that should be thought of as being part
256 of the same "logical" dynamic library as this Module. If you are familiar with
257 static linking: this means that findSymbolInLogicalDylib should expose symbols
258 with common linkage and hidden visibility. If all this sounds foreign you can
259 ignore the details and just remember that this is the first method that the
260 linker will use to try to find a symbol definition. If the
261 findSymbolInLogicalDylib method returns a null result then the linker will
262 call the second symbol resolver method, called findSymbol. This searches for
263 symbols that should be thought of as external to (but visibile from) the module
264 and its logical dylib.
265
266 In this tutorial we will use the following simple breakdown: All modules added
267 to the JIT will behave as if they were linked into a single, ever-growing
268 logical dylib. To implement this our first lambda (the one defining
269 findSymbolInLogicalDylib) will just search for JIT'd code by calling the
270 CompileLayer's findSymbol method. If we don't find a symbol in the JIT itself
271 we'll fall back to our second lambda, which implements findSymbol. This will
272 use the RTDyldMemoyrManager::getSymbolAddressInProcess method to search for
273 the symbol within the program itself. If we can't find a symbol definition
274 via either of these paths the JIT will refuse to accept our moudle, returning
275 a "symbol not found" error.
276
277 Now that we've built our symbol resolver we're ready to add our module to the
278 JIT. We do this by calling the CompileLayer's addModuleSet method [3]_. Since
279 we only have a single Module and addModuleSet expects a collection, we will
280 create a vector of modules and add our module as the only member. Since we
281 have already typedef'd our ModuleHandle type to be the same as the
282 CompileLayer's handle type, we can return the handle from addModuleSet
283 directly from our addModule method.
208284
209285 .. code-block:: c++
210286
278354 | DynamicLibrary.h | Provides the DynamicLibrary class, which |
279355 | | makes symbols in the host process searchable. |
280356 +-----------------------+-----------------------------------------------+
357
358 .. [3] ORC layers accept sets of Modules, rather than individual ones, so that
359 all Modules in the set could be co-located by the memory manager, though
360 this feature is not yet implemented.
5454 TargetMachine &getTargetMachine() { return *TM; }
5555
5656 ModuleHandle addModule(std::unique_ptr M) {
57 // We need a memory manager to allocate memory and resolve symbols for this
58 // new module. Create one that resolves symbols by looking back into the
59 // JIT.
57 // Build our symbol resolver:
58 // Lambda 1: Look back into the JIT itself to find symbols that are part of
59 // the same "logical dylib".
60 // Lambda 2: Search for external symbols in the host process.
6061 auto Resolver = createLambdaResolver(
6162 [&](const std::string &Name) {
6263 if (auto Sym = CompileLayer.findSymbol(Name, false))
6364 return RuntimeDyld::SymbolInfo(Sym.getAddress(), Sym.getFlags());
6465 return RuntimeDyld::SymbolInfo(nullptr);
6566 },
66 [](const std::string &S) { return nullptr; });
67 [](const std::string &Name) {
68 if (auto SymAddr =
69 RTDyldMemoryManager::getSymbolAddressInProcess(Name))
70 return RuntimeDyld::SymbolInfo(SymAddr, JITSymbolFlags::Exported);
71 return RuntimeDyld::SymbolInfo(nullptr);
72 });
73
74 // Build a singlton module set to hold our module.
6775 std::vector> Ms;
6876 Ms.push_back(std::move(M));
77
78 // Add the set to the JIT with the resolver we created above and a newly
79 // created SectionMemoryManager.
6980 return CompileLayer.addModuleSet(std::move(Ms),
7081 make_unique(),
7182 std::move(Resolver));