diff options
author | Stephen Hines <srhines@google.com> | 2014-07-21 00:45:20 -0700 |
---|---|---|
committer | Stephen Hines <srhines@google.com> | 2014-07-21 00:45:20 -0700 |
commit | c6a4f5e819217e1e12c458aed8e7b122e23a3a58 (patch) | |
tree | 81b7dd2bb4370a392f31d332a566c903b5744764 /docs/ProgrammersManual.rst | |
parent | 19c6fbb3e8aaf74093afa08013134b61fa08f245 (diff) | |
download | external_llvm-c6a4f5e819217e1e12c458aed8e7b122e23a3a58.zip external_llvm-c6a4f5e819217e1e12c458aed8e7b122e23a3a58.tar.gz external_llvm-c6a4f5e819217e1e12c458aed8e7b122e23a3a58.tar.bz2 |
Update LLVM for rebase to r212749.
Includes a cherry-pick of:
r212948 - fixes a small issue with atomic calls
Change-Id: Ib97bd980b59f18142a69506400911a6009d9df18
Diffstat (limited to 'docs/ProgrammersManual.rst')
-rw-r--r-- | docs/ProgrammersManual.rst | 97 |
1 files changed, 46 insertions, 51 deletions
diff --git a/docs/ProgrammersManual.rst b/docs/ProgrammersManual.rst index 7e46ac4..a7b28b3 100644 --- a/docs/ProgrammersManual.rst +++ b/docs/ProgrammersManual.rst @@ -387,7 +387,8 @@ Fine grained debug info with ``DEBUG_TYPE`` and the ``-debug-only`` option Sometimes you may find yourself in a situation where enabling ``-debug`` just turns on **too much** information (such as when working on the code generator). If you want to enable debug information with more fine-grained control, you -define the ``DEBUG_TYPE`` macro and the ``-debug`` only option as follows: +can define the ``DEBUG_TYPE`` macro and use the ``-debug-only`` option as +follows: .. code-block:: c++ @@ -545,14 +546,15 @@ methods. Within GDB, for example, you can usually use something like ``call DAG.viewGraph()`` to pop up a window. Alternatively, you can sprinkle calls to these functions in your code in places you want to debug. -Getting this to work requires a small amount of configuration. On Unix systems +Getting this to work requires a small amount of setup. On Unix systems with X11, install the `graphviz <http://www.graphviz.org>`_ toolkit, and make sure 'dot' and 'gv' are in your path. If you are running on Mac OS X, download and install the Mac OS X `Graphviz program <http://www.pixelglow.com/graphviz/>`_ and add ``/Applications/Graphviz.app/Contents/MacOS/`` (or wherever you install it) to -your path. Once in your system and path are set up, rerun the LLVM configure -script and rebuild LLVM to enable this functionality. +your path. The programs need not be present when configuring, building or +running LLVM and can simply be installed when needed during an active debug +session. ``SelectionDAG`` has been extended to make it easier to locate *interesting* nodes in large complex graphs. From gdb, if you ``call DAG.setGraphColor(node, @@ -1916,7 +1918,7 @@ which is a pointer to an integer on the run time stack. *Inserting instructions* -There are essentially two ways to insert an ``Instruction`` into an existing +There are essentially three ways to insert an ``Instruction`` into an existing sequence of instructions that form a ``BasicBlock``: * Insertion into an explicit instruction list @@ -1986,6 +1988,41 @@ sequence of instructions that form a ``BasicBlock``: which is much cleaner, especially if you're creating a lot of instructions and adding them to ``BasicBlock``\ s. +* Insertion using an instance of ``IRBuilder`` + + Inserting several ``Instruction``\ s can be quite laborious using the previous + methods. The ``IRBuilder`` is a convenience class that can be used to add + several instructions to the end of a ``BasicBlock`` or before a particular + ``Instruction``. It also supports constant folding and renaming named + registers (see ``IRBuilder``'s template arguments). + + The example below demonstrates a very simple use of the ``IRBuilder`` where + three instructions are inserted before the instruction ``pi``. The first two + instructions are Call instructions and third instruction multiplies the return + value of the two calls. + + .. code-block:: c++ + + Instruction *pi = ...; + IRBuilder<> Builder(pi); + CallInst* callOne = Builder.CreateCall(...); + CallInst* callTwo = Builder.CreateCall(...); + Value* result = Builder.CreateMul(callOne, callTwo); + + The example below is similar to the above example except that the created + ``IRBuilder`` inserts instructions at the end of the ``BasicBlock`` ``pb``. + + .. code-block:: c++ + + BasicBlock *pb = ...; + IRBuilder<> Builder(pb); + CallInst* callOne = Builder.CreateCall(...); + CallInst* callTwo = Builder.CreateCall(...); + Value* result = Builder.CreateMul(callOne, callTwo); + + See :doc:`tutorial/LangImpl3` for a practical use of the ``IRBuilder``. + + .. _schanges_deleting: Deleting Instructions @@ -2133,46 +2170,13 @@ compiler, consider compiling LLVM and LLVM-GCC in single-threaded mode, and using the resultant compiler to build a copy of LLVM with multithreading support. -.. _startmultithreaded: - -Entering and Exiting Multithreaded Mode ---------------------------------------- - -In order to properly protect its internal data structures while avoiding -excessive locking overhead in the single-threaded case, the LLVM must intialize -certain data structures necessary to provide guards around its internals. To do -so, the client program must invoke ``llvm_start_multithreaded()`` before making -any concurrent LLVM API calls. To subsequently tear down these structures, use -the ``llvm_stop_multithreaded()`` call. You can also use the -``llvm_is_multithreaded()`` call to check the status of multithreaded mode. - -Note that both of these calls must be made *in isolation*. That is to say that -no other LLVM API calls may be executing at any time during the execution of -``llvm_start_multithreaded()`` or ``llvm_stop_multithreaded``. It is the -client's responsibility to enforce this isolation. - -The return value of ``llvm_start_multithreaded()`` indicates the success or -failure of the initialization. Failure typically indicates that your copy of -LLVM was built without multithreading support, typically because GCC atomic -intrinsics were not found in your system compiler. In this case, the LLVM API -will not be safe for concurrent calls. However, it *will* be safe for hosting -threaded applications in the JIT, though :ref:`care must be taken -<jitthreading>` to ensure that side exits and the like do not accidentally -result in concurrent LLVM API calls. - .. _shutdown: Ending Execution with ``llvm_shutdown()`` ----------------------------------------- When you are done using the LLVM APIs, you should call ``llvm_shutdown()`` to -deallocate memory used for internal structures. This will also invoke -``llvm_stop_multithreaded()`` if LLVM is operating in multithreaded mode. As -such, ``llvm_shutdown()`` requires the same isolation guarantees as -``llvm_stop_multithreaded()``. - -Note that, if you use scope-based shutdown, you can use the -``llvm_shutdown_obj`` class, which calls ``llvm_shutdown()`` in its destructor. +deallocate memory used for internal structures. .. _managedstatic: @@ -2180,20 +2184,11 @@ Lazy Initialization with ``ManagedStatic`` ------------------------------------------ ``ManagedStatic`` is a utility class in LLVM used to implement static -initialization of static resources, such as the global type tables. Before the -invocation of ``llvm_shutdown()``, it implements a simple lazy initialization -scheme. Once ``llvm_start_multithreaded()`` returns, however, it uses +initialization of static resources, such as the global type tables. In a +single-threaded environment, it implements a simple lazy initialization scheme. +When LLVM is compiled with support for multi-threading, however, it uses double-checked locking to implement thread-safe lazy initialization. -Note that, because no other threads are allowed to issue LLVM API calls before -``llvm_start_multithreaded()`` returns, it is possible to have -``ManagedStatic``\ s of ``llvm::sys::Mutex``\ s. - -The ``llvm_acquire_global_lock()`` and ``llvm_release_global_lock`` APIs provide -access to the global lock used to implement the double-checked locking for lazy -initialization. These should only be used internally to LLVM, and only if you -know what you're doing! - .. _llvmcontext: Achieving Isolation with ``LLVMContext`` |