[llvm] r279007 - [Docs] Update MemorySSA doc to address more feedback.

Fri Aug 19 08:43:06 PDT 2016

Sorry for the noise.
It was another revision. My mistake.

Thanks

Galina

On Thu, Aug 18, 2016 at 3:28 PM, George Burgess IV <
george.burgess.iv at gmail.com> wrote:

> Hi!
>
> This commit is just a doc update in LLVM, so I don't think it would break
> an OpenMP test in clang. :)
>
> Looking at the builds since then (specifically #119 and #120), it seems
> that the OpenMP test failure has vanished, but other tests are now
> consistently failing; all of the failing tests say "llvm-dis: Could not
> open [...]: no such file or directory,"
>
> I'm not sure what commit could have caused this. :/
>
> Thanks,
> George
>
> On Thu, Aug 18, 2016 at 2:35 PM, Galina Kistanova <gkistanova at gmail.com>
> wrote:
>
>> 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/MemorySS
>>> A.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/20160819/db92fb6c/attachment-0001.html>