/JIT/llvm_fbuilder.h

  1// -*- C++ -*-
  2#ifndef PYTHON_LLVM_FBUILDER_H
  3#define PYTHON_LLVM_FBUILDER_H
  4
  5#ifndef __cplusplus
  6#error This header expects to be included only in C++ source
  7#endif
  8
  9#include "JIT/llvm_state.h"
 10
 11#include "JIT/PyTypeBuilder.h"
 12#include "JIT/RuntimeFeedback.h"
 13#include "Util/EventTimer.h"
 14#include "llvm/ADT/SmallPtrSet.h"
 15#include "llvm/ADT/SparseBitVector.h"
 16#include "llvm/ADT/Twine.h"
 17#include "llvm/Analysis/DebugInfo.h"
 18#include "llvm/Constants.h"
 19#include "llvm/ExecutionEngine/ExecutionEngine.h"
 20#include "llvm/GlobalVariable.h"
 21#include "llvm/Type.h"
 22#include "llvm/Support/IRBuilder.h"
 23#include "llvm/Support/TargetFolder.h"
 24
 25#include <bitset>
 26#include <string>
 27
 28struct PyCodeObject;
 29struct PyGlobalLlvmData;
 30
 31namespace py {
 32
 33/// Helps the compiler build LLVM functions corresponding to Python
 34/// functions.  This class maintains all Value*s which depend on a
 35/// single frame/code object. It also contains all functions that
 36/// depend on these Values.
 37class LlvmFunctionBuilder {
 38    LlvmFunctionBuilder(const LlvmFunctionBuilder &);  // Not implemented.
 39    void operator=(const LlvmFunctionBuilder &);  // Not implemented.
 40
 41public:
 42    LlvmFunctionBuilder(LlvmFunctionState *state, PyCodeObject *code);
 43
 44    llvm::Function *function() { return function_; }
 45    typedef llvm::IRBuilder<true, llvm::TargetFolder> BuilderT;
 46    BuilderT& builder() { return builder_; }
 47    LlvmFunctionState *state() const { return this->state_; }
 48    PyCodeObject *code_object() const { return this->code_object_; }
 49    PyGlobalLlvmData *llvm_data() const { return this->llvm_data_; }
 50    llvm::LLVMContext& context() { return this->context_; } 
 51    bool &uses_delete_fast() { return this->uses_delete_fast_; }
 52    std::vector<bool> &loads_optimized() { return this->loads_optimized_; }
 53
 54    llvm::BasicBlock *unreachable_block() const
 55    { 
 56        return this->unreachable_block_;
 57    }
 58    llvm::BasicBlock *unwind_block() const { return this->unwind_block_; }
 59    llvm::BasicBlock *do_return_block() const { return this->do_return_block_; }
 60
 61    llvm::Value *unwind_reason_addr() const
 62    {
 63        return this->unwind_reason_addr_;
 64    }
 65    llvm::Value *retval_addr() const
 66    {
 67        return this->retval_addr_;
 68    }
 69    llvm::Value *num_blocks_addr() const
 70    {
 71        return this->num_blocks_addr_;
 72    }
 73    llvm::Value *blockstack_addr() const
 74    {
 75        return this->blockstack_addr_;
 76    }
 77    llvm::Value *stack_pointer_addr() const
 78    {
 79        return this->stack_pointer_addr_;
 80    }
 81    llvm::Value *f_lasti_addr() const { return this->f_lasti_addr_; }
 82
 83    llvm::Value *stack_bottom() const { return this->stack_bottom_; }
 84    int stack_top() const { return this->stack_top_; }
 85    
 86    llvm::Value *freevars() const { return this->freevars_; }
 87    llvm::Value *frame() const { return this->frame_; }
 88    llvm::Value *globals() const { return this->globals_; }
 89    llvm::Value *builtins() const { return this->builtins_; }
 90    llvm::Value *fastlocals() const { return this->fastlocals_; }
 91    
 92    bool is_generator() const { return this->is_generator_; }
 93
 94    llvm::Value *GetLocal(int i) const { return this->locals_[i]; }
 95
 96    void UpdateStackInfo();
 97    bool Error() { return this->error_; }
 98
 99    /// Sets the current instruction index.  This is only put into the
100    /// frame object when tracing.
101    void SetLasti(int current_instruction_index);
102    int GetLasti() const { return this->f_lasti_; }
103
104    /// Sets the current line number being executed.  This is used to
105    /// make tracebacks correct and to get tracing to fire in the
106    /// right places.
107    void SetLineNumber(int line);
108
109    /// Inserts a call to llvm.dbg.stoppoint.
110    void SetDebugStopPoint(int line_number);
111
112    /// This function fills the block that handles a backedge.  Each
113    /// backedge needs to check if it needs to handle signals or
114    /// switch threads.  If the backedge doesn't land at the start of
115    /// a line, it also needs to update the line number and check
116    /// whether line tracing has been turned on.  This function leaves
117    /// the insert point in a block with a terminator already added,
118    /// so the caller should re-set the insert point.
119    void FillBackedgeLanding(llvm::BasicBlock *backedge_landing,
120                             llvm::BasicBlock *target,
121                             bool to_start_of_line,
122                             int line_number);
123
124    /// Sets the insert point to next_block, inserting an
125    /// unconditional branch to there if the current block doesn't yet
126    /// have a terminator instruction.
127    void FallThroughTo(llvm::BasicBlock *next_block);
128
129    /// Register callbacks that might invalidate native code based on the
130    /// optimizations performed in the generated code.
131    int FinishFunction();
132
133    /// These two push or pop a value onto or off of the stack. The
134    /// behavior is undefined if the Value's type isn't PyObject* or a
135    /// subclass.  These do no refcount operations, which means that
136    /// Push() consumes a reference and gives ownership of it to the
137    /// new value on the stack, and Pop() returns a pointer that owns
138    /// a reference (which it got from the stack).
139    /// Push/Pop are legacy methods to provide compatibility to existing
140    /// opcode implementations. They should not be used any more.
141    /// You must call Push only once per argument and Pop only once
142    /// per result.
143    void Push(llvm::Value *value);
144    llvm::Value *Pop();
145
146    /// Set the number of arguments the next opcode uses.
147    /// This serves as a baseline for reading/writing to the stack.
148    /// It also resets the stack pointer to it's base value.
149    void SetOpcodeArguments(int amount);
150    
151    /// Sets the number of arguments the next opcode uses.
152    /// Use this when the opcode needs to implement guards.
153    /// GetOpcodeArg can be used as usual. Call BeginOpcodeImpl
154    /// if the guard was successfully passed.
155    void SetOpcodeArgsWithGuard(int amount);
156    /// Changes the stack pointer after a successfully passed guard.
157    void BeginOpcodeImpl();
158    /// Retrieve an opcode argument. Must be called after SetOpcodeArguments.
159    /// Can be called unlimited.
160    /// Increasing the argument reads in the direction of stack growth.
161    llvm::Value *GetOpcodeArg(int i);
162    /// Sets the result of an opcode. Must be called after SetOpcodeArguments.
163    /// Must only be called once per result per IR-codepath.
164    void SetOpcodeResult(int i, llvm::Value *value);
165
166    /// Normally it is not needed to specify the number of result values an
167    /// opcode produces, as the stack top will be set to the correct value
168    /// at the beginning of each opcode
169    /// If you want to use SetOpcodeArguments/SetOpocodeArgsWithGuard twice
170    /// in one opcode (e.g. to split the opcode in to sub-implementations)
171    /// call FinishOpcodeImpl with the number of results from the previous
172    /// opcode.
173    void FinishOpcodeImpl(int amount);
174
175    /// Takes a target stack pointer and pops values off the stack
176    /// until it gets there, decref'ing as it goes.
177    void PopAndDecrefTo(llvm::Value *target_stack_pointer);
178
179    /// The PyFrameObject holds several values, like the block stack
180    /// and stack pointer, that we store in allocas inside this
181    /// function.  When we suspend or resume a generator, or bail out
182    /// to the interpreter, we need to transfer those values between
183    /// the frame and the allocas.
184    void CopyToFrameObject();
185    void CopyFromFrameObject();
186
187    /// We copy the function's locals into an LLVM alloca so that LLVM can
188    /// better reason about them.
189    void CopyLocalsFromFrameObject();
190
191    /// Returns the difference between the current stack pointer and
192    /// the base of the stack.
193    llvm::Value *GetStackLevel();
194
195    /// Get the runtime feedback for the current opcode (as set by SetLasti()).
196    /// Opcodes with multiple feedback units should use the arg_index version
197    /// to access individual units.
198    const PyRuntimeFeedback *GetFeedback() const {
199        return GetFeedback(0);
200    }
201    const PyRuntimeFeedback *GetFeedback(unsigned arg_index) const;
202    const PyTypeObject *GetTypeFeedback(unsigned arg_index) const;
203
204    // Look up a name in the function's names list, returning the
205    // PyStringObject for the name_index.
206    llvm::Value *LookupName(int name_index);
207
208    /// Inserts a call that will print opcode_name and abort the
209    /// program when it's reached.
210    void DieForUndefinedOpcode(const char *opcode_name);
211
212    /// How many parameters does the currently-compiling function have?
213    int GetParamCount() const;
214
215    // Emits code to decrement _Py_Ticker and handle signals and
216    // thread-switching when it expires.  Falls through to next_block (or a
217    // new block if it's NULL) and leaves the insertion point there.
218    void CheckPyTicker(llvm::BasicBlock *next_block = NULL);
219
220    /// Marks the end of the function and inserts a return instruction.
221    llvm::ReturnInst *CreateRet(llvm::Value *retval);
222
223    // Returns an i1, true if value is a PyObject considered true.
224    // Steals the reference to value.
225    llvm::Value *IsPythonTrue(llvm::Value *value);
226
227    /// During stack unwinding it may be necessary to jump back into
228    /// the function to handle a finally or except block.  Since LLVM
229    /// doesn't allow us to directly store labels as data, we instead
230    /// add the index->label mapping to a switch instruction and
231    /// return the i32 for the index.
232    llvm::ConstantInt *AddUnwindTarget(llvm::BasicBlock *target,
233                                       int target_opindex);
234
235    // Inserts a jump to the return block, returning retval.  You
236    // should _never_ call CreateRet directly from one of the opcode
237    // handlers, since doing so would fail to unwind the stack.
238    void Return(llvm::Value *retval);
239
240    // Propagates an exception by jumping to the unwind block with an
241    // appropriate unwind reason set.
242    void PropagateException();
243
244    // Set up a block preceding the bail-to-interpreter block.
245    void CreateBailPoint(unsigned bail_idx, char reason);
246    void CreateBailPoint(char reason) {
247        CreateBailPoint(this->f_lasti_, reason);
248    }
249
250    // Set up a block preceding the bail-to-interpreter block.
251    void CreateGuardBailPoint(unsigned bail_idx, char reason);
252    void CreateGuardBailPoint(char reason) {
253        CreateGuardBailPoint(this->f_lasti_, reason);
254    }
255
256    // Only for use in the constructor: Fills in the block that
257    // handles bailing out of JITted code back to the interpreter
258    // loop.  Code jumping to this block must first:
259    //  1) Set frame->f_lasti to the current opcode index.
260    //  2) Set frame->f_bailed_from_llvm to a reason.
261    void FillBailToInterpreterBlock();
262    // Only for use in the constructor: Fills in the block that starts
263    // propagating an exception.  Jump to this block when you want to
264    // add a traceback entry for the current line.  Don't jump to this
265    // block (and just set retval_addr_ and unwind_reason_addr_
266    // directly) when you're re-raising an exception and you want to
267    // use its traceback.
268    void FillPropagateExceptionBlock();
269    // Only for use in the constructor: Fills in the unwind block.
270    void FillUnwindBlock();
271    // Only for use in the constructor: Fills in the block that
272    // actually handles returning from the function.
273    void FillDoReturnBlock();
274
275    // If 'value' represents NULL, propagates the exception.
276    // Otherwise, falls through.
277    void PropagateExceptionOnNull(llvm::Value *value);
278    // If 'value' represents a negative integer, propagates the exception.
279    // Otherwise, falls through.
280    void PropagateExceptionOnNegative(llvm::Value *value);
281    // If 'value' represents a non-zero integer, propagates the exception.
282    // Otherwise, falls through.
283    void PropagateExceptionOnNonZero(llvm::Value *value);
284
285    /// Emits code to conditionally bail out to the interpreter loop
286    /// if a line tracing function is installed.  If the line tracing
287    /// function is not installed, execution will continue at
288    /// fallthrough_block.  direction should be _PYFRAME_LINE_TRACE or
289    /// _PYFRAME_BACKEDGE_TRACE.
290    void MaybeCallLineTrace(llvm::BasicBlock *fallthrough_block,
291                            char direction);
292
293    /// Emits code to conditionally bail out to the interpreter loop if a
294    /// profiling function is installed. If a profiling function is not
295    /// installed, execution will continue at fallthrough_block.
296    void BailIfProfiling(llvm::BasicBlock *fallthrough_block);
297
298    /// Return the BasicBlock we should jump to in order to bail to the
299    /// interpreter.
300    llvm::BasicBlock *GetBailBlock() const;
301
302    /// Return the BasicBlock we should jump to in order to handle a Python
303    /// exception.
304    llvm::BasicBlock *GetExceptionBlock() const;
305    void PushException();
306
307    // Add a Type to the watch list.
308    void WatchType(PyTypeObject *type);
309
310    void WatchDict(int reason);
311
312    // Return a i1 which is true when the use_jit field is set in the
313    // code object
314    llvm::Value *GetUseJitCond();
315
316    void AddYieldResumeBB(llvm::ConstantInt *number, llvm::BasicBlock *block);
317
318private:
319    // Stack pointer relative push and pop methods are for internal
320    // use only.
321    llvm::Value *PopRel();
322
323    LlvmFunctionState *state_;
324    PyGlobalLlvmData *const llvm_data_;
325    // The code object is used for looking up peripheral information
326    // about the function.  It's not used to examine the bytecode
327    // string.
328    PyCodeObject *const code_object_;
329    llvm::LLVMContext &context_;
330    llvm::Module *const module_;
331    llvm::Function *const function_;
332    BuilderT &builder_;
333    llvm::DIFactory &debug_info_;
334    const llvm::DICompileUnit debug_compile_unit_;
335    const llvm::DISubprogram debug_subprogram_;
336
337    // The most recent index we've started emitting an instruction for.
338    int f_lasti_;
339
340    // Flags to indicate whether the code object is watching any of the
341    // watchable dicts.
342    std::bitset<NUM_WATCHING_REASONS> uses_watched_dicts_;
343
344    // The following pointers hold values created in the function's
345    // entry block. They're constant after construction.
346    llvm::Value *frame_;
347
348    // Address of code_object_->co_use_jit, used for guards.
349    llvm::Value *use_jit_addr_;
350
351    llvm::Value *tstate_;
352    llvm::Value *stack_bottom_;
353    llvm::Value *stack_pointer_addr_;
354    // The tmp_stack_pointer is used when we need to have another
355    // function update the stack pointer.  Passing the stack pointer
356    // directly would prevent mem2reg from working on it, so we copy
357    // it to and from the tmp_stack_pointer around the call.
358    llvm::Value *tmp_stack_pointer_addr_;
359    llvm::Value *varnames_;
360    llvm::Value *names_;
361    llvm::Value *globals_;
362    llvm::Value *builtins_;
363    llvm::Value *fastlocals_;
364    llvm::Value *freevars_;
365    llvm::Value *f_lineno_addr_;
366    llvm::Value *f_lasti_addr_;
367    // These two fields correspond to the f_blockstack and f_iblock
368    // fields in the frame object.  They get explicitly copied back
369    // and forth when the frame escapes.
370    llvm::Value *blockstack_addr_;
371    llvm::Value *num_blocks_addr_;
372
373    // Expose the frame's locals to LLVM. We copy them in on function-entry,
374    // copy them out on write. We use a separate alloca for each local
375    // because LLVM's scalar replacement of aggregates pass doesn't handle
376    // array allocas.
377    std::vector<llvm::Value*> locals_;
378
379    llvm::BasicBlock *unreachable_block_;
380
381    // In generators, we use this switch to jump back to the most
382    // recently executed yield instruction.
383    llvm::SwitchInst *yield_resume_switch_;
384
385    llvm::BasicBlock *bail_to_interpreter_block_;
386
387    llvm::BasicBlock *propagate_exception_block_;
388    llvm::BasicBlock *unwind_block_;
389    llvm::Value *unwind_target_index_addr_;
390    llvm::SparseBitVector<> existing_unwind_targets_;
391    llvm::SwitchInst *unwind_target_switch_;
392    // Stores one of the UNWIND_XXX constants defined at the top of
393    // llvm_fbuilder.cc
394    llvm::Value *unwind_reason_addr_;
395    llvm::Value *exception_tb_;
396    llvm::Value *exception_val_;
397    llvm::Value *exception_exc_;
398    llvm::BasicBlock *do_return_block_;
399    llvm::Value *retval_addr_;
400
401    llvm::SmallPtrSet<PyTypeObject*, 5> types_used_;
402
403    // A stack that corresponds to LOAD_METHOD/CALL_METHOD pairs.  For every
404    // load, we push on a boolean for whether or not the load was optimized.
405    // The call uses this value to decide whether to expect an extra "self"
406    // argument.  The stack is necessary if the user wrote code with nested
407    // method calls, like this: f.foo(b.bar()).
408    std::vector<bool> loads_optimized_;
409
410    // Stores information about the stack top for every opcode
411    std::vector<int> stack_info_;
412    int stack_top_;
413
414    // True if something went wrong and we need to stop compilation without
415    // aborting the process. If this is true, a Python error has already
416    // been set.
417    bool error_;
418
419    const bool is_generator_;
420    bool uses_delete_fast_;
421};
422
423}  // namespace py
424
425#endif  // PYTHON_LLVM_FBUILDER_H