[llvm] r279007 - [Docs] Update MemorySSA doc to address more feedback.
Galina Kistanova via llvm-commits
llvm-commits at lists.llvm.org
Thu Aug 18 14:35:16 PDT 2016
Hello George,
It looks like this commit broke one of our new builders on staging master:
http://lab.llvm.org:8014/builders/clang-with-lto-ubuntu/builds/117
The previous revision r279002 id green
http://lab.llvm.org:8014/builders/clang-with-lto-ubuntu/builds/116
Please have a look at this?
I am going to move the builder from staging to main master today.
Thanks
Galina
On Wed, Aug 17, 2016 at 4:21 PM, George Burgess IV via llvm-commits <
llvm-commits at lists.llvm.org> wrote:
> Author: gbiv
> Date: Wed Aug 17 18:21:56 2016
> New Revision: 279007
>
> URL: http://llvm.org/viewvc/llvm-project?rev=279007&view=rev
> Log:
> [Docs] Update MemorySSA doc to address more feedback.
>
> Primarily, this clarifies wording in a few places, and adds "\ "s to
> make the formatting of things like "``Foo`` s" better.
>
> Thanks to Michael Kuperstein for the comments.
>
> Modified:
> llvm/trunk/docs/MemorySSA.rst
>
> Modified: llvm/trunk/docs/MemorySSA.rst
> URL: http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/
> MemorySSA.rst?rev=279007&r1=279006&r2=279007&view=diff
> ============================================================
> ==================
> --- llvm/trunk/docs/MemorySSA.rst (original)
> +++ llvm/trunk/docs/MemorySSA.rst Wed Aug 17 18:21:56 2016
> @@ -36,8 +36,8 @@ MemorySSA Structure
> ===================
>
> MemorySSA is a virtual IR. After it's built, ``MemorySSA`` will contain a
> -structure that maps ``Instruction`` s to ``MemoryAccess`` es, which are
> -``MemorySSA``'s parallel to LLVM ``Instruction`` s.
> +structure that maps ``Instruction``\ s to ``MemoryAccess``\ es, which are
> +``MemorySSA``'s parallel to LLVM ``Instruction``\ s.
>
> Each ``MemoryAccess`` can be one of three types:
>
> @@ -45,25 +45,25 @@ Each ``MemoryAccess`` can be one of thre
> - ``MemoryUse``
> - ``MemoryDef``
>
> -``MemoryPhi`` s are ``PhiNode`` , but for memory operations. If at any
> -point we have two (or more) ``MemoryDef`` s that could flow into a
> +``MemoryPhi``\ s are ``PhiNode``\ s, but for memory operations. If at any
> +point we have two (or more) ``MemoryDef``\ s that could flow into a
> ``BasicBlock``, the block's top ``MemoryAccess`` will be a
> -``MemoryPhi``. As in LLVM IR, ``MemoryPhi`` s don't correspond to any
> -concrete operation. As such, you can't look up a ``MemoryPhi`` with an
> -``Instruction`` (though we do allow you to do so with a
> -``BasicBlock``).
> +``MemoryPhi``. As in LLVM IR, ``MemoryPhi``\ s don't correspond to any
> +concrete operation. As such, ``BasicBlock``\ s are mapped to
> ``MemoryPhi``\ s
> +inside ``MemorySSA``, whereas ``Instruction``\ s are mapped to
> ``MemoryUse``\ s
> +and ``MemoryDef``\ s.
>
> Note also that in SSA, Phi nodes merge must-reach definitions (that
> is, definite new versions of variables). In MemorySSA, PHI nodes merge
> may-reach definitions (that is, until disambiguated, the versions that
> reach a phi node may or may not clobber a given variable)
>
> -``MemoryUse`` s are operations which use but don't modify memory. An
> example of
> +``MemoryUse``\ s are operations which use but don't modify memory. An
> example of
> a ``MemoryUse`` is a ``load``, or a ``readonly`` function call.
>
> -``MemoryDef`` s are operations which may either modify memory, or which
> -otherwise clobber memory in unquantifiable ways. Examples of
> ``MemoryDef`` s
> -include ``store`` s, function calls, ``load`` s with ``acquire`` (or
> higher)
> +``MemoryDef``\ s are operations which may either modify memory, or which
> +otherwise clobber memory in unquantifiable ways. Examples of
> ``MemoryDef``\ s
> +include ``store``\ s, function calls, ``load``\ s with ``acquire`` (or
> higher)
> ordering, volatile operations, memory fences, etc.
>
> Every function that exists has a special ``MemoryDef`` called
> ``liveOnEntry``.
> @@ -73,12 +73,12 @@ run on, and implies that we've hit the t
> ``liveOnEntry`` implies that the memory being used is either undefined or
> defined before the function begins.
>
> -An example of all of this overlayed on LLVM IR (obtained by running ``opt
> +An example of all of this overlaid on LLVM IR (obtained by running ``opt
> -passes='print<memoryssa>' -disable-output`` on an ``.ll`` file) is
> below. When
> viewing this example, it may be helpful to view it in terms of clobbers.
> The
> operands of a given ``MemoryAccess`` are all (potential) clobbers of said
> MemoryAccess, and the value produced by a ``MemoryAccess`` can act as a
> clobber
> -for other ``MemoryAccess`` es. Another useful way of looking at it is in
> +for other ``MemoryAccess``\ es. Another useful way of looking at it is in
> terms of heap versions. In that view, operands of of a given
> ``MemoryAccess`` are the version of the heap before the operation, and
> if the access produces a value, the value is the new version of the heap
> @@ -125,7 +125,7 @@ to (if such an instruction exists). For
> is a ``MemoryAccess`` (specifically, a ``MemoryDef``), and it describes
> the LLVM
> instruction ``store i8 0, i8* %p3``. Other places in ``MemorySSA`` refer
> to this
> particular ``MemoryDef`` as ``1`` (much like how one can refer to ``load
> i8, i8*
> -%p1`` in LLVM with ``%1``). Again, ``MemoryPhi`` s don't correspond to
> any LLVM
> +%p1`` in LLVM with ``%1``). Again, ``MemoryPhi``\ s don't correspond to
> any LLVM
> Instruction, so the line directly below a ``MemoryPhi`` isn't special.
>
> Going from the top down:
> @@ -135,7 +135,9 @@ Going from the top down:
> ``MemoryPhi`` is referred to in the textual IR by the number ``6``.
> - ``2 = MemoryDef(6)`` notes that ``store i8 0, i8* %p1`` is a definition,
> and its reaching definition before it is ``6``, or the ``MemoryPhi``
> after
> - ``while.cond``.
> + ``while.cond``. (See the `Build-time use optimization`_ and `Precision`_
> + sections below for why this ``MemoryDef`` isn't linked to a seperate,
> + disambiguated ``MemoryPhi``.)
> - ``3 = MemoryDef(6)`` notes that ``store i8 0, i8* %p2`` is a
> definition; its
> reaching definition is also ``6``.
> - ``5 = MemoryPhi({if.then,2},{if.else,3})`` notes that the clobber
> before
> @@ -146,9 +148,9 @@ Going from the top down:
> reaching definition is ``5``.
> - ``MemoryUse(1)`` notes that ``load i8, i8* %p3`` is just a user of
> memory,
> and the last thing that could clobber this use is above ``while.cond``
> (e.g.
> - the store to ``%p3``). In heap versioning parlance, it really
> - only depends on the heap version 1, and is unaffected by the new
> - heap versions generated since then.
> + the store to ``%p3``). In heap versioning parlance, it really only
> depends on
> + the heap version 1, and is unaffected by the new heap versions
> generated since
> + then.
>
> As an aside, ``MemoryAccess`` is a ``Value`` mostly for convenience; it's
> not
> meant to interact with LLVM IR.
> @@ -158,9 +160,9 @@ Design of MemorySSA
>
> ``MemorySSA`` is an analysis that can be built for any arbitrary
> function. When
> it's built, it does a pass over the function's IR in order to build up its
> -mapping of ``MemoryAccess`` es. You can then query ``MemorySSA`` for
> things like
> -the dominance relation between ``MemoryAccess`` es, and get the
> ``MemoryAccess``
> -for any given ``Instruction`` .
> +mapping of ``MemoryAccess``\ es. You can then query ``MemorySSA`` for
> things
> +like the dominance relation between ``MemoryAccess``\ es, and get the
> +``MemoryAccess`` for any given ``Instruction`` .
>
> When ``MemorySSA`` is done building, it also hands you a
> ``MemorySSAWalker``
> that you can use (see below).
> @@ -171,7 +173,7 @@ The walker
>
> A structure that helps ``MemorySSA`` do its job is the
> ``MemorySSAWalker``, or
> the walker, for short. The goal of the walker is to provide answers to
> clobber
> -queries beyond what's represented directly by ``MemoryAccess`` es. For
> example,
> +queries beyond what's represented directly by ``MemoryAccess``\ es. For
> example,
> given:
>
> .. code-block:: llvm
> @@ -190,10 +192,11 @@ The store to ``%a`` is clearly not a clo
> be the walker's goal to figure this out, and return ``liveOnEntry`` when
> queried
> for the clobber of ``MemoryAccess`` ``2``.
>
> -By default, ``MemorySSA`` provides a walker that can optimize
> ``MemoryDef`` s
> -and ``MemoryUse`` s by consulting alias analysis. Walkers were built to be
> -flexible, though, so it's entirely reasonable (and expected) to create
> more
> -specialized walkers (e.g. one that queries ``GlobalsAA``).
> +By default, ``MemorySSA`` provides a walker that can optimize
> ``MemoryDef``\ s
> +and ``MemoryUse``\ s by consulting whatever alias analysis stack you
> happen to
> +be using. Walkers were built to be flexible, though, so it's entirely
> reasonable
> +(and expected) to create more specialized walkers (e.g. one that
> specifically
> +queries ``GlobalsAA``, one that always stops at ``MemoryPhi`` nodes, etc).
>
>
> Locating clobbers yourself
> @@ -201,22 +204,23 @@ Locating clobbers yourself
>
> If you choose to make your own walker, you can find the clobber for a
> ``MemoryAccess`` by walking every ``MemoryDef`` that dominates said
> -``MemoryAccess``. The structure of ``MemoryDef`` s makes this relatively
> simple;
> +``MemoryAccess``. The structure of ``MemoryDef``\ s makes this relatively
> simple;
> they ultimately form a linked list of every clobber that dominates the
> ``MemoryAccess`` that you're trying to optimize. In other words, the
> ``definingAccess`` of a ``MemoryDef`` is always the nearest dominating
> ``MemoryDef`` or ``MemoryPhi`` of said ``MemoryDef``.
>
>
> -Use optimization
> -----------------
> +Build-time use optimization
> +---------------------------
>
> -``MemorySSA`` will optimize some ``MemoryAccess`` es at build-time.
> +``MemorySSA`` will optimize some ``MemoryAccess``\ es at build-time.
> Specifically, we optimize the operand of every ``MemoryUse`` to point to
> the
> actual clobber of said ``MemoryUse``. This can be seen in the above
> example; the
> second ``MemoryUse`` in ``if.end`` has an operand of ``1``, which is a
> ``MemoryDef`` from the entry block. This is done to make walking,
> value numbering, etc, faster and easier.
> +
> It is not possible to optimize ``MemoryDef`` in the same way, as we
> restrict ``MemorySSA`` to one heap variable and, thus, one Phi node
> per block.
> @@ -228,13 +232,13 @@ Invalidation and updating
> Because ``MemorySSA`` keeps track of LLVM IR, it needs to be updated
> whenever
> the IR is updated. "Update", in this case, includes the addition,
> deletion, and
> motion of ``Instructions``. The update API is being made on an as-needed
> basis.
> -If you'd like examples, ``GVNHoist`` is a user of ``MemorySSA`` s update
> API.
> +If you'd like examples, ``GVNHoist`` is a user of ``MemorySSA``\ s update
> API.
>
>
> Phi placement
> ^^^^^^^^^^^^^
>
> -``MemorySSA`` only places ``MemoryPhi`` s where they're actually
> +``MemorySSA`` only places ``MemoryPhi``\ s where they're actually
> needed. That is, it is a pruned SSA form, like LLVM's SSA form. For
> example, consider:
>
> @@ -274,7 +278,7 @@ for ``if.end`` would be pointless, so we
> place a ``MemoryDef`` in ``if.then`` or ``if.else``, you'll need to also
> create
> a ``MemoryPhi`` for ``if.end``.
>
> -If it turns out that this is a large burden, we can just place
> ``MemoryPhi`` s
> +If it turns out that this is a large burden, we can just place
> ``MemoryPhi``\ s
> everywhere. Because we have Walkers that are capable of optimizing above
> said
> phis, doing so shouldn't prohibit optimizations.
>
>
>
> _______________________________________________
> llvm-commits mailing list
> llvm-commits at lists.llvm.org
> http://lists.llvm.org/cgi-bin/mailman/listinfo/llvm-commits
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.llvm.org/pipermail/llvm-commits/attachments/20160818/41c16935/attachment-0001.html>
More information about the llvm-commits
mailing list