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

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), 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

> 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.
We’re not very good at upgrading the documentation I guess. 
> Assuming there is an interest
I think it is very valuable to document it though. Patches will be welcome!
> 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), 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?
Bitcode is supposed to be compatible since version 3.0.
I’m not sure if we should just document the current state or keep track of the
history.

— 
Mehdi

> -----Original Message-----
> From: llvm-dev [mailto:llvm-dev-bounces at lists.llvm.org] On Behalf Of
Mehdi
> Amini via llvm-dev
> Sent: Thursday, October 13, 2016 10:51 AM
> To: Ismail Badawi (ibadawi)
> Cc: llvm-dev at lists.llvm.org
> Subject: Re: [llvm-dev] Status of docs/BitCodeFormat.rst?
> 
> 
> > 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.
> 
> We’re not very good at upgrading the documentation I guess.
> 
> > Assuming there is an interest
> 
> I think it is very valuable to document it though. Patches will be
> welcome!
> 
> > 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), 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?
> 
> Bitcode is supposed to be compatible since version 3.0.
> I’m not sure if we should just document the current state or keep track of
> the history.
In principle the docs captured by previous release branches would document
the history.  But if the docs have been wrong for a long time, then prior
releases don't document the format correctly.  Therefore I think we would
be better off describing the history in the "living" document.
--paulr
> 
> —
> Mehdi
> 
> 
> _______________________________________________
> LLVM Developers mailing list
> llvm-dev at lists.llvm.org
> http://lists.llvm.org/cgi-bin/mailman/listinfo/llvm-dev

> 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 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
>