llvm dev - Jun 2014 - [LLVMdev] Clarification on the backward compatibility promises

A bit of history first:

Back when we transitioned from bytecode to bitcode (2.0) we had a tool
called llvm-upgrade which would read .ll files from 1.9 and output 2.0
format which could then be passed to llvm-as to produce bitcode.

The release notes for 2.3 note that llvm-upgrade was not supported any more.

During the 2.X development we tried to keep reading older bitcodes.
Once we got to 3.1, we dropped support for reading 2.X:

http://llvm.org/viewvc/llvm-project?view=revision&revision=145165

Since then we make sure that when IR format is changed we upgrade as
we read the bitcode and mark those code paths with something like "//
TODO: Remove with llvm 4.0".

There is some support for parsing .ll files, but we have not been
nearly as systematic about it.

So, what IR do we promise to be compatible with?
>From the above history, it looks like the working assumptions are
* The is no strong guarantee about .ll compatibility. We don't make
gratuitous changes and when desirable/requested we do keep support for
old syntax around for some time and in some cases issue warnings about
it. In summary: it is fuzzy, don't assume much about it.

* All of llvm's 3.X and 4.0 releases will be able to read and upgrade
bitcode produced by all preceding 3.X releases (except for bugs).

* Once 4.0 is released, trunk may drop support for reading bitcode
produced by 3.X. We may then decide to keep some support, but we don't
offer any promises.

Do others agree that this is the case or at least that this would be a
reasonable balance?

In any case, we should probably document whatever we decide. Where
should that go? Sean suggested docs/DeveloperPolicy.html. Is everyone
OK with that?

Cheers,
Rafael

Hi Rafael,
> Do others agree that this is the case or at least that this would be a
> reasonable balance?
IMO it's easier to be compatible on .ll level, no? In case of binary
IR it's really easy to make incompatible changes. After all there are
no tests on IR binary compatibility, however the whole regression
testsuite can be viewed as a big test for .ll compatibility.

There are two more points here:

1. Actually we had much stronger policies wrt the bitcode
compatibility in minor releases. Something like x.y should be able to
read stuff from x.y-1, but x.y+2 is allowed not to read stuff there,
so the proper path is transition x.y-1 => x.y => x.y+2. Am I right?
2. Metadata compatibility. We already had precedence of introducing
incompatible changes into metadata format in the past within release.
Should we use relaxes rules for metadata compatibility?
> In any case, we should probably document whatever we decide. Where
> should that go? Sean suggested docs/DeveloperPolicy.html. Is everyone
> OK with that?
+1

-- 
With best regards, Anton Korobeynikov
Faculty of Mathematics and Mechanics, Saint Petersburg State University

On 17 June 2014 16:07, Anton Korobeynikov <anton at korobeynikov.info>
wrote:
> Hi Rafael,
>
>> Do others agree that this is the case or at least that this would be a
>> reasonable balance?
> IMO it's easier to be compatible on .ll level, no?
That is not my experience with the bitcode format. The way the API is
structured makes it really easy to support backwards compatibility.

It also seems a lot more valuable from an user perspective to support
reading old .bc files. It means they can keep a library with IR for an
entire major LLVM release for example.
>In case of binary
> IR it's really easy to make incompatible changes. After all there are
> no tests on IR binary compatibility, however the whole regression
> testsuite can be viewed as a big test for .ll compatibility.
We do have tests that are done by checking in old versions of bitcode
files. We didn't use to be good about it, but I think we are now
fairly systematic about it any time we change the format.
> There are two more points here:
>
> 1. Actually we had much stronger policies wrt the bitcode
> compatibility in minor releases. Something like x.y should be able to
> read stuff from x.y-1, but x.y+2 is allowed not to read stuff there,
> so the proper path is transition x.y-1 => x.y => x.y+2. Am I right?
That doesn't match what we have in trunk right now.  For example, we
changed how inline asm is stored in r163185 (Sep 5 2012), but we still
support reading the old one. This is one of the cases where we have a
FIXME about 4.0.
> 2. Metadata compatibility. We already had precedence of introducing
> incompatible changes into metadata format in the past within release.
> Should we use relaxes rules for metadata compatibility?
I think we have a special case for debug metadata (and should document
that), but otherwise I think we should hold metadata to the same
standard as the rest of the IR.
>> In any case, we should probably document whatever we decide. Where
>> should that go? Sean suggested docs/DeveloperPolicy.html. Is everyone
>> OK with that?
> +1
Cheers,
Rafael

On Tue, Jun 17, 2014 at 2:07 PM, Anton Korobeynikov <anton at
korobeynikov.info
> wrote:
> Hi Rafael,
>
> > Do others agree that this is the case or at least that this would be a
> > reasonable balance?
> IMO it's easier to be compatible on .ll level, no? In case of binary
> IR it's really easy to make incompatible changes. After all there are
> no tests on IR binary compatibility, however the whole regression
> testsuite can be viewed as a big test for .ll compatibility.
>
This is a really good point. Theoretically (and to a good approximation in
practice), every feature of the IR is tested in the test suite in .ll form,
which means that a compatibility break at the .ll level will cause visible
churn. The same cannot be said for the bitcode.

-- Sean Silva

>
> There are two more points here:
>
> 1. Actually we had much stronger policies wrt the bitcode
> compatibility in minor releases. Something like x.y should be able to
> read stuff from x.y-1, but x.y+2 is allowed not to read stuff there,
> so the proper path is transition x.y-1 => x.y => x.y+2. Am I right?
> 2. Metadata compatibility. We already had precedence of introducing
> incompatible changes into metadata format in the past within release.
> Should we use relaxes rules for metadata compatibility?
>
> > In any case, we should probably document whatever we decide. Where
> > should that go? Sean suggested docs/DeveloperPolicy.html. Is everyone
> > OK with that?
> +1
>
> --
> With best regards, Anton Korobeynikov
> Faculty of Mathematics and Mechanics, Saint Petersburg State University
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL:
<http://lists.llvm.org/pipermail/llvm-dev/attachments/20140618/2291546b/attachment.html>