llvm dev - Oct 2016 - Status of docs/BitCodeFormat.rst?

I think it just changed formats which prompted a change in ID -- the code now
uses TYPE_BLOCK_ID_NEW (= 17). I haven’t looked deeply to see how different it
is.

Ismail
> On Oct 13, 2016, at 2:02 PM, Mehdi Amini <mehdi.amini at apple.com>
wrote:
> 
> 
>> On Oct 13, 2016, at 10:24 AM, Ismail Badawi (ibadawi) via llvm-dev
<llvm-dev at lists.llvm.org> wrote:
>> 
>> Hi folks,
>> 
>> A while back I noticed some outdated information in
docs/BitCodeFormat.rst about how parameter attributes were encoded — it
describes an old encoding that was changed in 3.3 with the introduction of
attribute groups. I opened a bug about this
(https://llvm.org/bugs/show_bug.cgi?id=28941) and started trying to write a
patch, but along the way ran into more and more issues (e.g. new things not
documented, things that were removed or changed formats).
>> 
>> So I’m wondering whether there is an interest in keeping this document
up to date. I see that there are some commits to this file in 2016 so it’s not
totally abandoned, but at the same time there is information that has been
outdated for 5+ years.
>> 
>> Assuming there is an interest, I’m also wondering whether (or how) to
approach fixing this incrementally. For example, in trying to document the new
paramattr format, I noticed that the type format is also outdated, and there is
a conflict in block ids (i.e. the old TYPE_BLOCK format which is documented used
blockid=10, but blockid=10 is now used for PARAMATTR_GROUP_BLOCK),
> 
> For this particular example, it should just be removed I think. If I read
correctly the history the TYPE_BLOCK was a 2.9 thing.
> 
> — 
> Mehdi
> 
> 
>> so that fixing the paramattr docs on their own might introduce
inconsistencies. Would it be better to try & bring the whole document up to
date at once, or would it be fine to do it incrementally & possibly
introduce some strangeness in the intermediate steps?
>> 
>> Thanks,
>> Ismail
>> _______________________________________________
>> LLVM Developers mailing list
>> llvm-dev at lists.llvm.org
>> http://lists.llvm.org/cgi-bin/mailman/listinfo/llvm-dev
>

It is more than that: the ID was *freed* and that’s why it has been reused for
something else.
We only support bitcode from version 3.0 and above.
There is really no point keeping in the documentation construct from 2.9 and
before that we can’t read anymore today.

Hope this makes sense.

— 
Mehdi
> On Oct 13, 2016, at 11:09 AM, Ismail Badawi (ibadawi) <ibadawi at
cisco.com> wrote:
> 
> I think it just changed formats which prompted a change in ID -- the code
now uses TYPE_BLOCK_ID_NEW (= 17). I haven’t looked deeply to see how different
it is.
> 
> Ismail
> 
>> On Oct 13, 2016, at 2:02 PM, Mehdi Amini <mehdi.amini at
apple.com> wrote:
>> 
>> 
>>> On Oct 13, 2016, at 10:24 AM, Ismail Badawi (ibadawi) via llvm-dev
<llvm-dev at lists.llvm.org> wrote:
>>> 
>>> Hi folks,
>>> 
>>> A while back I noticed some outdated information in
docs/BitCodeFormat.rst about how parameter attributes were encoded — it
describes an old encoding that was changed in 3.3 with the introduction of
attribute groups. I opened a bug about this
(https://llvm.org/bugs/show_bug.cgi?id=28941) and started trying to write a
patch, but along the way ran into more and more issues (e.g. new things not
documented, things that were removed or changed formats).
>>> 
>>> So I’m wondering whether there is an interest in keeping this
document up to date. I see that there are some commits to this file in 2016 so
it’s not totally abandoned, but at the same time there is information that has
been outdated for 5+ years.
>>> 
>>> Assuming there is an interest, I’m also wondering whether (or how)
to approach fixing this incrementally. For example, in trying to document the
new paramattr format, I noticed that the type format is also outdated, and there
is a conflict in block ids (i.e. the old TYPE_BLOCK format which is documented
used blockid=10, but blockid=10 is now used for PARAMATTR_GROUP_BLOCK),
>> 
>> For this particular example, it should just be removed I think. If I
read correctly the history the TYPE_BLOCK was a 2.9 thing.
>> 
>> — 
>> Mehdi
>> 
>> 
>>> so that fixing the paramattr docs on their own might introduce
inconsistencies. Would it be better to try & bring the whole document up to
date at once, or would it be fine to do it incrementally & possibly
introduce some strangeness in the intermediate steps?
>>> 
>>> Thanks,
>>> Ismail
>>> _______________________________________________
>>> LLVM Developers mailing list
>>> llvm-dev at lists.llvm.org
>>> http://lists.llvm.org/cgi-bin/mailman/listinfo/llvm-dev
>> 
>

I’ve opened https://reviews.llvm.org/D25623 to start bringing this up to date.
Would appreciate someone taking the time to review.

Thanks,
Ismail
> On Oct 13, 2016, at 2:10 PM, Mehdi Amini <mehdi.amini at apple.com>
wrote:
> 
> It is more than that: the ID was *freed* and that’s why it has been reused
for something else.
> We only support bitcode from version 3.0 and above.
> There is really no point keeping in the documentation construct from 2.9
and before that we can’t read anymore today.
> 
> Hope this makes sense.
> 
> — 
> Mehdi
> 
>> On Oct 13, 2016, at 11:09 AM, Ismail Badawi (ibadawi) <ibadawi at
cisco.com> wrote:
>> 
>> I think it just changed formats which prompted a change in ID -- the
code now uses TYPE_BLOCK_ID_NEW (= 17). I haven’t looked deeply to see how
different it is.
>> 
>> Ismail
>> 
>>> On Oct 13, 2016, at 2:02 PM, Mehdi Amini <mehdi.amini at
apple.com> wrote:
>>> 
>>> 
>>>> On Oct 13, 2016, at 10:24 AM, Ismail Badawi (ibadawi) via
llvm-dev <llvm-dev at lists.llvm.org> wrote:
>>>> 
>>>> Hi folks,
>>>> 
>>>> A while back I noticed some outdated information in
docs/BitCodeFormat.rst about how parameter attributes were encoded — it
describes an old encoding that was changed in 3.3 with the introduction of
attribute groups. I opened a bug about this
(https://llvm.org/bugs/show_bug.cgi?id=28941) and started trying to write a
patch, but along the way ran into more and more issues (e.g. new things not
documented, things that were removed or changed formats).
>>>> 
>>>> So I’m wondering whether there is an interest in keeping this
document up to date. I see that there are some commits to this file in 2016 so
it’s not totally abandoned, but at the same time there is information that has
been outdated for 5+ years.
>>>> 
>>>> Assuming there is an interest, I’m also wondering whether (or
how) to approach fixing this incrementally. For example, in trying to document
the new paramattr format, I noticed that the type format is also outdated, and
there is a conflict in block ids (i.e. the old TYPE_BLOCK format which is
documented used blockid=10, but blockid=10 is now used for
PARAMATTR_GROUP_BLOCK),
>>> 
>>> For this particular example, it should just be removed I think. If
I read correctly the history the TYPE_BLOCK was a 2.9 thing.
>>> 
>>> — 
>>> Mehdi
>>> 
>>> 
>>>> so that fixing the paramattr docs on their own might introduce
inconsistencies. Would it be better to try & bring the whole document up to
date at once, or would it be fine to do it incrementally & possibly
introduce some strangeness in the intermediate steps?
>>>> 
>>>> Thanks,
>>>> Ismail
>>>> _______________________________________________
>>>> LLVM Developers mailing list
>>>> llvm-dev at lists.llvm.org
>>>> http://lists.llvm.org/cgi-bin/mailman/listinfo/llvm-dev
>>> 
>> 
>