mirror of
https://github.com/RPCS3/llvm-mirror.git
synced 2025-01-31 12:41:49 +01:00
b74bacff63
In the past, it was stated in D87994 that it is allowed to dereference a pointer that is partially undefined if all of its possible representations fit into a dereferenceable range. The motivation of the direction was to make a range analysis helpful for assuring dereferenceability. Even if a range analysis concludes that its offset is within bounds, the offset could still be partially undefined; to utilize the range analysis, this relaxation was necessary. https://groups.google.com/g/llvm-dev/c/2Qk4fOHUoAE/m/KcvYMEgOAgAJ has more context about this. However, this is currently blocking another optimization, which is annotating the noundef attribute for library functions' arguments. D95122 is the patch. Currently, there are quite a few library functions which cannot have noundef attached to its pointer argument because it can be transformed from load/store. For example, MemCpyOpt can convert stores into memset: ``` store p, i32 0 store (p+1), i32 0 // Since currently it is allowed for store to have partially undefined pointer.. -> memset(p, 0, 8) // memset cannot guarantee that its ptr argument is noundef. ``` A bigger problem is that this makes unclear which library functions are allowed to have 'noundef' and which functions aren't (e.g., strlen). This makes annotating noundef almost impossible for this kind of functions. This patch proposes that all memory operations should have well-defined pointers. For memset/memcpy, it is semantically equivalent to running a loop until the size is met (and branching on undef is UB), so the size is also updated to be well-defined. Strictly speaking, this again violates the implication of dereferenceability from range analysis result. However, I think this is okay for the following reasons: 1. It seems the existing analyses in the LLVM main repo does not have conflicting implementation with the new proposal. `isDereferenceableAndAlignedPointer` works only when the GEP offset is constant, and `isDereferenceableAndAlignedInLoop` is also fine. 2. A possible miscompilation happens only when the source has a pointer with a *partially* undefined offset (it's okay with poison because there is no 'partially poison' value). But, at least I'm not aware of a language using LLVM as backend that has a well-defined program while allowing partially undefined pointers. There might be such a language that I'm not aware of, but improving the performance of the mainstream languages like C and Rust is more important IMHO. Reviewed By: jdoerfert Differential Revision: https://reviews.llvm.org/D95238
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 mostly meant to be processed by the Sphinx documentation generation
system to create HTML pages which are hosted on <https://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:
cd <build-dir>
cmake -DLLVM_ENABLE_SPHINX=true -DSPHINX_OUTPUT_HTML=true <src-dir>
make -j3 docs-llvm-html
$BROWSER <build-dir>/docs//html/index.html
The mapping between reStructuredText files and generated documentation is
`docs/Foo.rst` <-> `<build-dir>/docs//html/Foo.html` <-> `https://llvm.org/docs/Foo.html`.
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-dir>/docs/man/`.
cd <build-dir>
cmake -DLLVM_ENABLE_SPHINX=true -DSPHINX_OUTPUT_MAN=true <src-dir>
make -j3 docs-llvm-man
man -l >build-dir>/docs/man/FileCheck.1
The correspondence between .rst files and man pages is
`docs/CommandGuide/Foo.rst` <-> `<build-dir>/docs//man/Foo.1`.
These .rst files are also included during HTML generation so they are also
viewable online (as noted above) at e.g.
`https://llvm.org/docs/CommandGuide/Foo.html`.
Checking links
==============
The reachability of external links in the documentation can be checked by
running:
cd docs/
make -f Makefile.sphinx linkcheck
Doxygen page Output
==============
Install doxygen <http://www.stack.nl/~dimitri/doxygen/download.html> and dot2tex <https://dot2tex.readthedocs.io/en/latest>.
cd <build-dir>
cmake -DLLVM_ENABLE_DOXYGEN=On <llvm-top-src-dir>
make doxygen-llvm # for LLVM docs
make doxygen-clang # for clang docs
It will generate html in
<build-dir>/docs/doxygen/html # for LLVM docs
<build-dir>/tools/clang/docs/doxygen/html # for clang docs