llvm dev - Sep 2019 - Google’s TensorFlow team would like to contribute MLIR to the LLVM Foundation

On Wed, Sep 11, 2019 at 1:54 PM David Greene <greened at obbligato.org>
wrote:
> Mehdi AMINI <joker.eph at gmail.com> writes:
>
> > Of course by its nature, MLIR doesn't lend itself to concrete
semantic
> >> descriptions, though I would expect the affine dialect (and
others) to
> >> have documentation on par with the LLVM IR.
> >
> >
> > Just last week I had to scout through the affine dialect "LangRef
> >
<https://github.com/tensorflow/mlir/blob/master/g3doc/Dialects/Affine.md
> >"
> > for something, and I also felt that it is due for a refresh! It seemed
a
> > bit more than just BNF though, do you have example of what you would
like
> > to see expanded there?
>
> I was referring to the base MLIR documentation with the BNF comment:
>
> https://github.com/tensorflow/mlir/blob/master/g3doc/LangRef.md
>
> Obviously there's more to it than that but I found this document pretty
> dense.
>
Oh I see, indeed this is a bit difficult to grasp: since MLIR is designed
for extensibility, a lot of the core "LangRef" things are very
structural
by nature at this level. If I draw a parallel with LLVM IR, it is like if
you would split LangRef into:
- the definition of what is SSA, Module, Function, Block, terminator, phi
nodes. In particular that would be most of: Abstract
<https://llvm.org/docs/LangRef.html#abstract>, Introduction
<https://llvm.org/docs/LangRef.html#introduction>, Well-Formedness
<https://llvm.org/docs/LangRef.html#well-formedness>, Identifiers
<https://llvm.org/docs/LangRef.html#identifiers>, High Level Structure
<https://llvm.org/docs/LangRef.html#high-level-structure>, Module
Structure
<https://llvm.org/docs/LangRef.html#module-structure>, and partially
Functions <https://llvm.org/docs/LangRef.html#functions> (which defines
CFG).
- the types and instructions semantics (all the rest of LangRef basically).

The MLIR LangRef corresponds to the former part only, because this is what
is common to all dialects. On the other hand, each dialect will need to
provide its own LangRef equivalent (for example I linked to the Affine
dialect doc before).

Does it make sense?

-- 
Mehdi


> > The current proposal includes all the content of
> > https://github.com/tensorflow/mlir/ as-is.
> > It does *not* include the TensorFlow specific dialects and other
pieces
> > here:
> >
>
https://github.com/tensorflow/tensorflow/tree/master/tensorflow/compiler/mlir/
>
> Looks great, thanks for making it more clear!
>
>                     -David
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL:
<http://lists.llvm.org/pipermail/llvm-dev/attachments/20190911/33740800/attachment.html>

On Wed, 11 Sep 2019 at 23:04, Mehdi Amini <aminim at google.com>
wrote:
> The MLIR LangRef corresponds to the former part only, because this is what
is common to all dialects. On the other hand, each dialect will need to provide
its own LangRef equivalent (for example I linked to the Affine dialect doc
before).
For LLVM, I think the document is:
https://github.com/tensorflow/mlir/blob/master/g3doc/ConversionToLLVMDialect.md

It has some examples and some tips, but it needs more love. In the
end, we'd need three things: reasonable documents, at least one
implementation in-tree and good testing coverage.

As with any new technology that we introduce to LLVM, these things can
build up with time. Unlike them, however, MLIR is an existing project
with its own responsibilities. There will be a period of instability
for both projects as they are merged.

So, as long as we understand the costs and are willing to pay them,
each of the three things can come at "reasonable" time, after the
merge.

I'm assuming that the general approach is to, in case of conflict,
value LLVM's stability more than MLIR's during the transition. I'm
also assuming the transition will not take longer than one release
period (1/2 year).

I'm uncertain how the other projects that use MLIR will interact with
the LLVM community, but I'm also assuming that's a given, by wanting
to merge the two communities.

IE, I hope we don't get to the point where other users of MLIR want to
take a radically different direction as LLVM does, which would start a
conflict.

I don't think anyone here wants that, but it's good to be aware that
it could happen, and prepare for it.

cheers,
--renato

On Thu, Sep 12, 2019 at 12:03 PM Renato Golin via llvm-dev <
llvm-dev at lists.llvm.org> wrote:
> On Wed, 11 Sep 2019 at 23:04, Mehdi Amini <aminim at google.com>
wrote:
> > The MLIR LangRef corresponds to the former part only, because this is
> what is common to all dialects. On the other hand, each dialect will need
> to provide its own LangRef equivalent (for example I linked to the Affine
> dialect doc before).
>
> For LLVM, I think the document is:
>
>
https://github.com/tensorflow/mlir/blob/master/g3doc/ConversionToLLVMDialect.md

For the LLVM dialect, the document is
https://github.com/tensorflow/mlir/blob/master/g3doc/Dialects/LLVM.md
It is a good question for such "interface" dialects whether we should
describe the semantics of the operations (essentially copy it from the
source), or just refer to the authoritative document (LLVM's LangRef in
this case).  So far, we decided to say that operations in the LLVM dialect
have the same semantics as LLVM IR instructions, but we had to describe
their syntax since it differs.  On the other hand, the operations that
model IR concepts absent from MLIR IR (first-class constant values,
globals) are defined with more detail.  Suggestions on how to structure
that document without much duplications are very welcome.  Also note that
the dialect currently covers ~60% of LLVM instructions and ~1% of
intrinsics.

The document you referenced above is about the conversion between the
Standard and the LLVM dialects.  Similarly to dialect documents, the
conversion document only describes the details of a specific A to B
conversion. In particular, type conversion and CFG requirements.
Admittedly, it does not describe how individual arithmetic operations are
converted when it is a direct one-to-one mapping after type conversion. The
conversion infrastructure itself is described in
https://github.com/tensorflow/mlir/blob/master/g3doc/DialectConversion.md.

>
>
> It has some examples and some tips, but it needs more love. In the
> end, we'd need three things: reasonable documents, at least one
> implementation in-tree and good testing coverage.
>
> As with any new technology that we introduce to LLVM, these things can
> build up with time. Unlike them, however, MLIR is an existing project
> with its own responsibilities. There will be a period of instability
> for both projects as they are merged.
>
> So, as long as we understand the costs and are willing to pay them,
> each of the three things can come at "reasonable" time, after the
> merge.
>
> I'm assuming that the general approach is to, in case of conflict,
> value LLVM's stability more than MLIR's during the transition.
I'm
> also assuming the transition will not take longer than one release
> period (1/2 year).
>
> I'm uncertain how the other projects that use MLIR will interact with
> the LLVM community, but I'm also assuming that's a given, by
wanting
> to merge the two communities.
>
> IE, I hope we don't get to the point where other users of MLIR want to
> take a radically different direction as LLVM does, which would start a
> conflict.
>
> I don't think anyone here wants that, but it's good to be aware
that
> it could happen, and prepare for it.
>
> cheers,
> --renato
> _______________________________________________
> LLVM Developers mailing list
> llvm-dev at lists.llvm.org
> https://lists.llvm.org/cgi-bin/mailman/listinfo/llvm-dev
>

-- 
-- Alex
-------------- next part --------------
An HTML attachment was scrubbed...
URL:
<http://lists.llvm.org/pipermail/llvm-dev/attachments/20190912/44d45cdd/attachment.html>

> On Sep 12, 2019, at 3:03 AM, Renato Golin <rengolin at gmail.com>
wrote:
> 
> As with any new technology that we introduce to LLVM, these things can
> build up with time. Unlike them, however, MLIR is an existing project
> with its own responsibilities. There will be a period of instability
> for both projects as they are merged.
Yep, you’re right that MLIR is still early and we can build these things up over
time.

One point of clarification though: MLIR was and has always been built with the
idea that it would go to LLVM.  This is why it has always followed the coding
style, development practices, etc.  The ‘instability’ that I expect is more
about the GitHub infra changing (monorepo etc) than the code itself.

To put it another way, MLIR was built the way Clang was (both Clang and MLIR
were a started as private projects that was eventually contributed to LLVM, with
full revision control history).  In contrast, MLIR isn’t being built the way
LLDB was, which was a project that built up over time and then was later decided
to move to LLVM.

-Chris

Mehdi Amini <aminim at google.com> writes:
> The MLIR LangRef corresponds to the former part only, because this is what
> is common to all dialects. On the other hand, each dialect will need to
> provide its own LangRef equivalent (for example I linked to the Affine
> dialect doc before).
>
> Does it make sense?
Yeah, it makes perfect sense.  I think maybe reading the document I got
caught up in the BNF grammar -- it's a bit distracting.  I've not seen a
similar BNF specification for LLVM IR.  It may exist somewhere, but BNF
isn't part of any LLVM document I've read.  :) Maybe the grammar bits
could be factored out into a formal specification and LangRef could be a
little more informal.

Just suggestions, obviously.

                         -David

On Thu, Sep 12, 2019 at 9:50 AM David Greene <greened at obbligato.org>
wrote:
> Mehdi Amini <aminim at google.com> writes:
>
> > The MLIR LangRef corresponds to the former part only, because this is
> what
> > is common to all dialects. On the other hand, each dialect will need
to
> > provide its own LangRef equivalent (for example I linked to the Affine
> > dialect doc before).
> >
> > Does it make sense?
>
> Yeah, it makes perfect sense.  I think maybe reading the document I got
> caught up in the BNF grammar -- it's a bit distracting.  I've not
seen a
> similar BNF specification for LLVM IR.  It may exist somewhere, but BNF
> isn't part of any LLVM document I've read.  :) Maybe the grammar
bits
> could be factored out into a formal specification and LangRef could be a
> little more informal.
>
> Just suggestions, obviously.

That's a good one, we should look into outlining the grammar to make this
more friendly to read.

Another things that I just remember now about documentation is that we
don't expect dialects to write a "LangRef" that describe each
operation.
Instead we use a table-driven approach for defining operation
<https://github.com/tensorflow/mlir/blob/master/g3doc/OpDefinitions.md#table-driven-operation-definition-specification-ods>
and
we generate both the C++ classes and the documentation from there (this
helps keeping documentation up-to-date as well!).
>From a local build directory of MLIR, you can try:
  {BUILD}/bin/mlir-tblgen -gen-op-doc {SRC}/Dialect/StandardOps/Ops.td -I
{SRC}/include/ > std.md

(try --gen-op-defs and --gen-op-decls for the C++ code)

I pushed these here for your convenience:
https://github.com/joker-eph/mlir-docs/

See for example the definition for alloc:
https://github.com/tensorflow/mlir/blob/master/include/mlir/Dialect/StandardOps/Ops.td#L124
>From there here is:
- the generated documentation:
https://github.com/joker-eph/mlir-docs/blob/master/std.md#stdalloc-allocop
- the C++ class declaration for this operation:
https://github.com/joker-eph/mlir-docs/blob/master/std.h#L130
- and the implementation:
https://github.com/joker-eph/mlir-docs/blob/master/std.cpp#L285

Of course we need to improve the content in general, but I expect the
incentive to do so to grow assuming we can get a space like
http://llvm.org/mlir ; at which point we could organize the MLIR overall
online doc structure to include these generated file continuously.

Best,

-- 
Mehdi
-------------- next part --------------
An HTML attachment was scrubbed...
URL:
<http://lists.llvm.org/pipermail/llvm-dev/attachments/20190914/b75ba3bb/attachment.html>