diff options
Diffstat (limited to 'docs')
27 files changed, 197 insertions, 66 deletions
diff --git a/docs/CommandGuide/index.rst b/docs/CommandGuide/index.rst index 9bfa964..ac8a944 100644 --- a/docs/CommandGuide/index.rst +++ b/docs/CommandGuide/index.rst @@ -28,6 +28,7 @@ Basic Commands llvm-diff llvm-cov llvm-stress + llvm-symbolizer Debugging Tools ~~~~~~~~~~~~~~~ diff --git a/docs/CommandGuide/llvm-symbolizer.rst b/docs/CommandGuide/llvm-symbolizer.rst new file mode 100644 index 0000000..73babb1 --- /dev/null +++ b/docs/CommandGuide/llvm-symbolizer.rst @@ -0,0 +1,65 @@ +llvm-symbolizer - convert addresses into source code locations +============================================================== + +SYNOPSIS +-------- + +:program:`llvm-symbolizer` [options] + +DESCRIPTION +----------- + +:program:`llvm-symbolizer` reads object file names and addresses from standard +input and prints corresponding source code locations to standard output. This +program uses debug info sections and symbol table in the object files. + +EXAMPLE +-------- + +.. code-block:: console + + $ cat addr.txt + a.out 0x4004f4 + /tmp/b.out 0x400528 + /tmp/c.so 0x710 + $ llvm-symbolizer < addr.txt + main + /tmp/a.cc:4 + + f(int, int) + /tmp/b.cc:11 + + h_inlined_into_g + /tmp/header.h:2 + g_inlined_into_f + /tmp/header.h:7 + f_inlined_into_main + /tmp/source.cc:3 + main + /tmp/source.cc:8 + +OPTIONS +------- + +.. option:: -functions + + Print function names as well as source file/line locations. Defaults to true. + +.. option:: -use-symbol-table + + Prefer function names stored in symbol table to function names + in debug info sections. Defaults to true. + +.. option:: -demangle + + Print demangled function names. Defaults to true. + +.. option:: -inlining + + If a source code location is in an inlined function, prints all the + inlnied frames. Defaults to true. + +EXIT STATUS +----------- + +:program:`llvm-symbolizer` returns 0. Other exit codes imply internal program error. diff --git a/docs/CompilerWriterInfo.rst b/docs/CompilerWriterInfo.rst index bc0b996..87add67 100644 --- a/docs/CompilerWriterInfo.rst +++ b/docs/CompilerWriterInfo.rst @@ -10,8 +10,6 @@ Architecture & Platform Information for Compiler Writers This document is a work-in-progress. Additions and clarifications are welcome. - Compiled by `Misha Brukman <http://misha.brukman.net>`_. - Hardware ======== diff --git a/docs/HowToSetUpLLVMStyleRTTI.rst b/docs/HowToSetUpLLVMStyleRTTI.rst index b906b25..e0f865a 100644 --- a/docs/HowToSetUpLLVMStyleRTTI.rst +++ b/docs/HowToSetUpLLVMStyleRTTI.rst @@ -295,6 +295,78 @@ ordering right:: | OtherSpecialSquare | Circle +A Bug to be Aware Of +-------------------- + +The example just given opens the door to bugs where the ``classof``\s are +not updated to match the ``Kind`` enum when adding (or removing) classes to +(from) the hierarchy. + +Continuing the example above, suppose we add a ``SomewhatSpecialSquare`` as +a subclass of ``Square``, and update the ``ShapeKind`` enum like so: + +.. code-block:: c++ + + enum ShapeKind { + SK_Square, + SK_SpecialSquare, + SK_OtherSpecialSquare, + + SK_SomewhatSpecialSquare, + SK_Circle + } + +Now, suppose that we forget to update ``Square::classof()``, so it still +looks like: + +.. code-block:: c++ + + static bool classof(const Shape *S) { + // BUG: Returns false when S->getKind() == SK_SomewhatSpecialSquare, + // even though SomewhatSpecialSquare "is a" Square. + return S->getKind() >= SK_Square && + S->getKind() <= SK_OtherSpecialSquare; + } + +As the comment indicates, this code contains a bug. A straightforward and +non-clever way to avoid this is to introduce an explicit ``SK_LastSquare`` +entry in the enum when adding the first subclass(es). For example, we could +rewrite the example at the beginning of `Concrete Bases and Deeper +Hierarchies`_ as: + +.. code-block:: c++ + + enum ShapeKind { + SK_Square, + + SK_SpecialSquare, + + SK_OtherSpecialSquare, + + SK_LastSquare, + SK_Circle + } + ... + // Square::classof() + - static bool classof(const Shape *S) { + - return S->getKind() == SK_Square; + - } + + static bool classof(const Shape *S) { + + return S->getKind() >= SK_Square && + + S->getKind() <= SK_LastSquare; + + } + +Then, adding new subclasses is easy: + +.. code-block:: c++ + + enum ShapeKind { + SK_Square, + SK_SpecialSquare, + SK_OtherSpecialSquare, + + SK_SomewhatSpecialSquare, + SK_LastSquare, + SK_Circle + } + +Notice that ``Square::classof`` does not need to be changed. + .. _classof-contract: The Contract of ``classof`` diff --git a/docs/LangRef.rst b/docs/LangRef.rst index c08cee1..03004f6 100644 --- a/docs/LangRef.rst +++ b/docs/LangRef.rst @@ -148,20 +148,20 @@ symbol table entries. Here is an example of the "hello world" module: .. code-block:: llvm - ; Declare the string constant as a global constant. - @.str = private unnamed_addr constant [13 x i8] c"hello world\0A\00" + ; Declare the string constant as a global constant. + @.str = private unnamed_addr constant [13 x i8] c"hello world\0A\00" - ; External declaration of the puts function - declare i32 @puts(i8* nocapture) nounwind + ; External declaration of the puts function + declare i32 @puts(i8* nocapture) nounwind ; Definition of main function - define i32 @main() { ; i32()* - ; Convert [13 x i8]* to i8 *... + define i32 @main() { ; i32()* + ; Convert [13 x i8]* to i8 *... %cast210 = getelementptr [13 x i8]* @.str, i64 0, i64 0 - ; Call puts function to write out the string to stdout. + ; Call puts function to write out the string to stdout. call i32 @puts(i8* %cast210) - ret i32 0 + ret i32 0 } ; Named metadata @@ -2224,7 +2224,7 @@ The following is the syntax for constant expressions: won't fit in the floating point type, the results are undefined. ``ptrtoint (CST to TYPE)`` Convert a pointer typed constant to the corresponding integer - constant ``TYPE`` must be an integer type. ``CST`` must be of + constant. ``TYPE`` must be an integer type. ``CST`` must be of pointer type. The ``CST`` value is zero extended, truncated, or unchanged to make it fit in ``TYPE``. ``inttoptr (CST to TYPE)`` @@ -2537,10 +2537,10 @@ guaranteed to be separate for each loop. The loop-level metadata is prefixed with ``llvm.loop``. The loop identifier metadata is implemented using a metadata that refers to -itself to avoid merging it with any other identifier metadata, e.g., -during module linkage or function inlining. That is, each loop should refer -to their own identification metadata even if they reside in separate functions. -The following example contains loop identifier metadata for two separate loop +itself to avoid merging it with any other identifier metadata, e.g., +during module linkage or function inlining. That is, each loop should refer +to their own identification metadata even if they reside in separate functions. +The following example contains loop identifier metadata for two separate loop constructs: .. code-block:: llvm @@ -2829,7 +2829,7 @@ For example, the following metadata section specifies two separate sets of linker options, presumably to link against ``libz`` and the ``Cocoa`` framework:: - !0 = metadata !{ i32 6, metadata !"Linker Options", + !0 = metadata !{ i32 6, metadata !"Linker Options", metadata !{ metadata !{ metadata !"-lz" }, metadata !{ metadata !"-framework", metadata !"Cocoa" } } } @@ -3997,7 +3997,7 @@ Example: <result> = lshr i32 4, 1 ; yields {i32}:result = 2 <result> = lshr i32 4, 2 ; yields {i32}:result = 1 <result> = lshr i8 4, 3 ; yields {i8}:result = 0 - <result> = lshr i8 -2, 1 ; yields {i8}:result = 0x7FFFFFFF + <result> = lshr i8 -2, 1 ; yields {i8}:result = 0x7FFFFFFF <result> = lshr i32 1, 32 ; undefined <result> = lshr <2 x i32> < i32 -2, i32 4>, < i32 1, i32 2> ; yields: result=<2 x i32> < i32 0x7FFFFFFF, i32 1> diff --git a/docs/Passes.rst b/docs/Passes.rst index ed72166..9cb8ba0 100644 --- a/docs/Passes.rst +++ b/docs/Passes.rst @@ -34,9 +34,6 @@ LLVM's Analysis and Transform Passes .. contents:: :local: -Written by `Reid Spencer <mailto:rspencer@x10sys.com>`_ - and Gordon Henriksen - Introduction ============ diff --git a/docs/README.txt b/docs/README.txt index fcc1bad..22cf930 100644 --- a/docs/README.txt +++ b/docs/README.txt @@ -4,9 +4,9 @@ LLVM Documentation LLVM's documentation is written in reStructuredText, a lightweight plaintext markup language (file extension `.rst`). While the reStructuredText documentation should be quite readable in source form, it -is meant to be processed by the Sphinx documentation generation system to -create HTML pages which are hosted on <http://llvm.org/docs/> and updated -after every commit. +is mostly meant to be processed by the Sphinx documentation generation +system to create HTML pages which are hosted on <http://llvm.org/docs/> and +updated after every commit. Manpage output is also supported, see below. If you instead would like to generate and view the HTML locally, install Sphinx <http://sphinx-doc.org/> and then do: @@ -22,3 +22,21 @@ If you are interested in writing new documentation, you will want to read `SphinxQuickstartTemplate.rst` which will get you writing documentation very fast and includes examples of the most important reStructuredText markup syntax. + +Manpage Output +=============== + +Building the manpages is similar to building the HTML documentation. The +primary difference is to use the `man` makefile target, instead of the +default (which is `html`). Sphinx then produces the man pages in the +directory `_build/man/`. + + cd docs/ + make -f Makefile.sphinx man + man -l _build/man/FileCheck.1 + +The correspondence between .rst files and man pages is +`docs/CommandGuide/Foo.rst` <-> `_build/man/Foo.1`. +These .rst files are also included during HTML generation so they are also +viewable online (as noted above) at e.g. +`http://llvm.org/docs/CommandGuide/Foo.html`. diff --git a/docs/ReleaseNotes.rst b/docs/ReleaseNotes.rst index 9383c5b..822b55f 100644 --- a/docs/ReleaseNotes.rst +++ b/docs/ReleaseNotes.rst @@ -90,6 +90,13 @@ in fairly early stages, but we expect successful compilation when: Some additional functionality is also implemented, notably DWARF debugging, GNU-style thread local storage and inline assembly. +Hexagon Target +-------------- + +- Removed support for legacy hexagonv2 and hexagonv3 processor + architectures which are no longer in use. Currently supported + architectures are hexagonv4 and hexagonv5. + Loop Vectorizer --------------- diff --git a/docs/SourceLevelDebugging.rst b/docs/SourceLevelDebugging.rst index 78ce4e0..16fa7f0 100644 --- a/docs/SourceLevelDebugging.rst +++ b/docs/SourceLevelDebugging.rst @@ -1811,11 +1811,11 @@ values, we can clarify the contents of the ``BUCKETS``, ``HASHES`` and | HEADER.header_data_len | uint32_t | HEADER_DATA | HeaderData |-------------------------| - | BUCKETS | uint32_t[bucket_count] // 32 bit hash indexes + | BUCKETS | uint32_t[n_buckets] // 32 bit hash indexes |-------------------------| - | HASHES | uint32_t[hashes_count] // 32 bit hash values + | HASHES | uint32_t[n_hashes] // 32 bit hash values |-------------------------| - | OFFSETS | uint32_t[hashes_count] // 32 bit offsets to hash value data + | OFFSETS | uint32_t[n_hashes] // 32 bit offsets to hash value data |-------------------------| | ALL HASH DATA | `-------------------------' diff --git a/docs/SphinxQuickstartTemplate.rst b/docs/SphinxQuickstartTemplate.rst index 8f6d71e..fe6e44a 100644 --- a/docs/SphinxQuickstartTemplate.rst +++ b/docs/SphinxQuickstartTemplate.rst @@ -22,7 +22,8 @@ reStructuredText syntax is useful when writing the document, so the last ~half of this document (starting with `Example Section`_) gives examples which should cover 99% of use cases. -Let me say that again: focus on *content*. +Let me say that again: focus on *content*. But if you really need to verify +Sphinx's output, see ``docs/README.txt`` for information. Once you have finished with the content, please send the ``.rst`` file to llvm-commits for review. diff --git a/docs/Vectorizers.rst b/docs/Vectorizers.rst index 0894b1e..e2d3667 100644 --- a/docs/Vectorizers.rst +++ b/docs/Vectorizers.rst @@ -245,6 +245,17 @@ See the table below for a list of these functions. | | | fmuladd | +-----+-----+---------+ +The loop vectorizer knows about special instructions on the target and will +vectorize a loop containing a function call that maps to the instructions. For +example, the loop below will be vectorized on Intel x86 if the SSE4.1 roundps +instruction is available. + +.. code-block:: c++ + + void foo(float *f) { + for (int i = 0; i != 1024; ++i) + f[i] = floorf(f[i]); + } Partial unrolling during vectorization ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/docs/tutorial/LangImpl1.rst b/docs/tutorial/LangImpl1.rst index eb84e4c..aa619cf 100644 --- a/docs/tutorial/LangImpl1.rst +++ b/docs/tutorial/LangImpl1.rst @@ -5,8 +5,6 @@ Kaleidoscope: Tutorial Introduction and the Lexer .. contents:: :local: -Written by `Chris Lattner <mailto:sabre@nondot.org>`_ - Tutorial Introduction ===================== diff --git a/docs/tutorial/LangImpl2.rst b/docs/tutorial/LangImpl2.rst index 0d62894..7262afa 100644 --- a/docs/tutorial/LangImpl2.rst +++ b/docs/tutorial/LangImpl2.rst @@ -5,8 +5,6 @@ Kaleidoscope: Implementing a Parser and AST .. contents:: :local: -Written by `Chris Lattner <mailto:sabre@nondot.org>`_ - Chapter 2 Introduction ====================== diff --git a/docs/tutorial/LangImpl3.rst b/docs/tutorial/LangImpl3.rst index 01935a4..9d5f908 100644 --- a/docs/tutorial/LangImpl3.rst +++ b/docs/tutorial/LangImpl3.rst @@ -5,8 +5,6 @@ Kaleidoscope: Code generation to LLVM IR .. contents:: :local: -Written by `Chris Lattner <mailto:sabre@nondot.org>`_ - Chapter 3 Introduction ====================== diff --git a/docs/tutorial/LangImpl4.rst b/docs/tutorial/LangImpl4.rst index 8484c57..96c06d1 100644 --- a/docs/tutorial/LangImpl4.rst +++ b/docs/tutorial/LangImpl4.rst @@ -5,8 +5,6 @@ Kaleidoscope: Adding JIT and Optimizer Support .. contents:: :local: -Written by `Chris Lattner <mailto:sabre@nondot.org>`_ - Chapter 4 Introduction ====================== diff --git a/docs/tutorial/LangImpl5.rst b/docs/tutorial/LangImpl5.rst index 8405e1a..80d5f37 100644 --- a/docs/tutorial/LangImpl5.rst +++ b/docs/tutorial/LangImpl5.rst @@ -5,8 +5,6 @@ Kaleidoscope: Extending the Language: Control Flow .. contents:: :local: -Written by `Chris Lattner <mailto:sabre@nondot.org>`_ - Chapter 5 Introduction ====================== diff --git a/docs/tutorial/LangImpl6.rst b/docs/tutorial/LangImpl6.rst index 30f4e90..a5a60bf 100644 --- a/docs/tutorial/LangImpl6.rst +++ b/docs/tutorial/LangImpl6.rst @@ -5,8 +5,6 @@ Kaleidoscope: Extending the Language: User-defined Operators .. contents:: :local: -Written by `Chris Lattner <mailto:sabre@nondot.org>`_ - Chapter 6 Introduction ====================== diff --git a/docs/tutorial/LangImpl7.rst b/docs/tutorial/LangImpl7.rst index 602dcb5..6dde2fe 100644 --- a/docs/tutorial/LangImpl7.rst +++ b/docs/tutorial/LangImpl7.rst @@ -5,8 +5,6 @@ Kaleidoscope: Extending the Language: Mutable Variables .. contents:: :local: -Written by `Chris Lattner <mailto:sabre@nondot.org>`_ - Chapter 7 Introduction ====================== diff --git a/docs/tutorial/LangImpl8.rst b/docs/tutorial/LangImpl8.rst index 4058991..3534b2e 100644 --- a/docs/tutorial/LangImpl8.rst +++ b/docs/tutorial/LangImpl8.rst @@ -5,8 +5,6 @@ Kaleidoscope: Conclusion and other useful LLVM tidbits .. contents:: :local: -Written by `Chris Lattner <mailto:sabre@nondot.org>`_ - Tutorial Conclusion =================== diff --git a/docs/tutorial/OCamlLangImpl1.rst b/docs/tutorial/OCamlLangImpl1.rst index daa4825..94ca3a5 100644 --- a/docs/tutorial/OCamlLangImpl1.rst +++ b/docs/tutorial/OCamlLangImpl1.rst @@ -5,9 +5,6 @@ Kaleidoscope: Tutorial Introduction and the Lexer .. contents:: :local: -Written by `Chris Lattner <mailto:sabre@nondot.org>`_ and `Erick -Tryzelaar <mailto:idadesub@users.sourceforge.net>`_ - Tutorial Introduction ===================== diff --git a/docs/tutorial/OCamlLangImpl2.rst b/docs/tutorial/OCamlLangImpl2.rst index 07490e1..83a22ab 100644 --- a/docs/tutorial/OCamlLangImpl2.rst +++ b/docs/tutorial/OCamlLangImpl2.rst @@ -5,9 +5,6 @@ Kaleidoscope: Implementing a Parser and AST .. contents:: :local: -Written by `Chris Lattner <mailto:sabre@nondot.org>`_ and `Erick -Tryzelaar <mailto:idadesub@users.sourceforge.net>`_ - Chapter 2 Introduction ====================== diff --git a/docs/tutorial/OCamlLangImpl3.rst b/docs/tutorial/OCamlLangImpl3.rst index d2a47b4..fd9f0e5 100644 --- a/docs/tutorial/OCamlLangImpl3.rst +++ b/docs/tutorial/OCamlLangImpl3.rst @@ -5,9 +5,6 @@ Kaleidoscope: Code generation to LLVM IR .. contents:: :local: -Written by `Chris Lattner <mailto:sabre@nondot.org>`_ and `Erick -Tryzelaar <mailto:idadesub@users.sourceforge.net>`_ - Chapter 3 Introduction ====================== diff --git a/docs/tutorial/OCamlLangImpl4.rst b/docs/tutorial/OCamlLangImpl4.rst index 865a03d..b13b2af 100644 --- a/docs/tutorial/OCamlLangImpl4.rst +++ b/docs/tutorial/OCamlLangImpl4.rst @@ -5,9 +5,6 @@ Kaleidoscope: Adding JIT and Optimizer Support .. contents:: :local: -Written by `Chris Lattner <mailto:sabre@nondot.org>`_ and `Erick -Tryzelaar <mailto:idadesub@users.sourceforge.net>`_ - Chapter 4 Introduction ====================== diff --git a/docs/tutorial/OCamlLangImpl5.rst b/docs/tutorial/OCamlLangImpl5.rst index 203fb6f..b8ae3c5 100644 --- a/docs/tutorial/OCamlLangImpl5.rst +++ b/docs/tutorial/OCamlLangImpl5.rst @@ -5,9 +5,6 @@ Kaleidoscope: Extending the Language: Control Flow .. contents:: :local: -Written by `Chris Lattner <mailto:sabre@nondot.org>`_ and `Erick -Tryzelaar <mailto:idadesub@users.sourceforge.net>`_ - Chapter 5 Introduction ====================== diff --git a/docs/tutorial/OCamlLangImpl6.rst b/docs/tutorial/OCamlLangImpl6.rst index 7665647..36bffa8 100644 --- a/docs/tutorial/OCamlLangImpl6.rst +++ b/docs/tutorial/OCamlLangImpl6.rst @@ -5,9 +5,6 @@ Kaleidoscope: Extending the Language: User-defined Operators .. contents:: :local: -Written by `Chris Lattner <mailto:sabre@nondot.org>`_ and `Erick -Tryzelaar <mailto:idadesub@users.sourceforge.net>`_ - Chapter 6 Introduction ====================== diff --git a/docs/tutorial/OCamlLangImpl7.rst b/docs/tutorial/OCamlLangImpl7.rst index 07da3a8..cfb4931 100644 --- a/docs/tutorial/OCamlLangImpl7.rst +++ b/docs/tutorial/OCamlLangImpl7.rst @@ -5,9 +5,6 @@ Kaleidoscope: Extending the Language: Mutable Variables .. contents:: :local: -Written by `Chris Lattner <mailto:sabre@nondot.org>`_ and `Erick -Tryzelaar <mailto:idadesub@users.sourceforge.net>`_ - Chapter 7 Introduction ====================== diff --git a/docs/tutorial/OCamlLangImpl8.rst b/docs/tutorial/OCamlLangImpl8.rst index 4058991..3534b2e 100644 --- a/docs/tutorial/OCamlLangImpl8.rst +++ b/docs/tutorial/OCamlLangImpl8.rst @@ -5,8 +5,6 @@ Kaleidoscope: Conclusion and other useful LLVM tidbits .. contents:: :local: -Written by `Chris Lattner <mailto:sabre@nondot.org>`_ - Tutorial Conclusion =================== |