Documenting GCC-only ABI

Documenting GCC-only ABI

[Kazu Hirata]

Hi,

I have a question about where to place an ABI document.

AFAIK, H8 port of GCC uses a unique ABI that no other H8 compiler
vendor follows.  As such, it's natural to put an ABI document in some
place associated with GCC like gcc-x.x.x.tar.gz or http://gcc.gnu.org.
Any suggestions?

Thanks in advance,

Kazu Hirata

Re: Documenting GCC-only ABI

[Gerald Pfeifer]

On Sat, 17 Jan 2004, Kazu Hirata wrote:
> AFAIK, H8 port of GCC uses a unique ABI that no other H8 compiler
> vendor follows.  As such, it's natural to put an ABI document in some
> place associated with GCC like gcc-x.x.x.tar.gz or http://gcc.gnu.org.
> Any suggestions?

How large is this document?  One option would be adding it somewhere under
http://gcc.gnu.org/projects, another to add a new document under gcc/doc.

If someone has another/better suggestion, I'm certainly open!

Gerald
-- 
Gerald Pfeifer (Jerry)   gerald@pfeifer.com   http://www.pfeifer.com/gerald/

Re: Documenting GCC-only ABI

[Kazu Hirata]

Hi Gerald,

> > AFAIK, H8 port of GCC uses a unique ABI that no other H8 compiler
> > vendor follows.  As such, it's natural to put an ABI document in some
> > place associated with GCC like gcc-x.x.x.tar.gz or http://gcc.gnu.org.
> > Any suggestions?
> 
> How large is this document?  One option would be adding it somewhere under
> http://gcc.gnu.org/projects, another to add a new document under gcc/doc.

Less than 150 lines so far. :-) I'll post a patch to create a new web
page then.  Would a link from readings.html be OK?

Kazu Hirata

Re: Documenting GCC-only ABI

[Gerald Pfeifer]

On Sun, 18 Jan 2004, Kazu Hirata wrote:
> Less than 150 lines so far. :-) I'll post a patch to create a new web
> page then.  Would a link from readings.html be OK?

Sure! (Preapproved.)

Gerald

Re: Documenting GCC-only ABI

[Joseph S. Myers]

On Sun, 18 Jan 2004, Kazu Hirata wrote:

> Less than 150 lines so far. :-) I'll post a patch to create a new web
> page then.  Would a link from readings.html be OK?

I think interface.texi (or somewhere similar in the internals manual) is
the right place to accumulate links to external ABIs that GCC implements,
saying "GCC on target X follows ABI Y, with the following ABI for GNU
extensions beyond the scope of the externally specified ABI".  Whereas
compat.texi and some information in trouble.texi discusses the
user-visible ABI issues.  readings.html links to various ABI documents but
such links are "for information" rather than stating that this document
describes the intended ABI for a given version on a given target (with
given extensions, and given variations depending on command-line options).  
See the previous discussion
<http://gcc.gnu.org/ml/gcc/2002-08/msg01754.html> and following thread.

(A GCC-specific ABI would of course cover the ABI for extensions of
ABI-significance, such as complex integers and structures containing VLAs,
so there the manual would only link to it without needing to add further
details.  But if you later make a deliberate change to the ABI, each
branch's manual would point to the correct version for that branch, e.g.
though a version number being explicitly included in the URL for the ABI.)

-- 
Joseph S. Myers
jsm@polyomino.org.uk

Re: Documenting GCC-only ABI

[Kazu Hirata]

Hi Joseph,

> > Less than 150 lines so far. :-) I'll post a patch to create a new web
> > page then.  Would a link from readings.html be OK?
> 
> I think interface.texi (or somewhere similar in the internals manual) is
> the right place to accumulate links to external ABIs that GCC implements,
> saying "GCC on target X follows ABI Y, with the following ABI for GNU
> extensions beyond the scope of the externally specified ABI".  Whereas
> compat.texi and some information in trouble.texi discusses the
> user-visible ABI issues.  readings.html links to various ABI documents but
> such links are "for information" rather than stating that this document
> describes the intended ABI for a given version on a given target (with
> given extensions, and given variations depending on command-line options).  
> See the previous discussion
> <http://gcc.gnu.org/ml/gcc/2002-08/msg01754.html> and following thread.

What about putting a pointers in both <somewhere>.texi and
readings.html and put the ABI document proper in http://gcc.gnu.org?
I am not planning to change the ABI, so a fixed permanent location
would be nice.  Anyway, I'll post a patch soon, and we can discuss
further if there is some problem.  This discussion is probably longer
than the ABI that I have written down so far. :-)

> (A GCC-specific ABI would of course cover the ABI for extensions of
> ABI-significance, such as complex integers and structures containing VLAs,
> so there the manual would only link to it without needing to add further
> details.  But if you later make a deliberate change to the ABI, each
> branch's manual would point to the correct version for that branch, e.g.
> though a version number being explicitly included in the URL for the ABI.)

Well, H8's ABI for GCC is original AFAIK, not an extension of some
vendor's ABI.  But you are right, I forgot about complex numbers.

Currently, if I search for H8's ABI for GCC, I see several web pages
that seem to be the result of people digging up from the generated
assembly code, but that's not really healthy.  This is exactly the
point that I want to address.

Kazu Hirata

Re: Documenting GCC-only ABI

[Joseph S. Myers]

On Mon, 19 Jan 2004, Kazu Hirata wrote:

> What about putting a pointers in both <somewhere>.texi and
> readings.html and put the ABI document proper in http://gcc.gnu.org?
> I am not planning to change the ABI, so a fixed permanent location
> would be nice.  Anyway, I'll post a patch soon, and we can discuss

Seems reasonable.  But if you do change it incompatibly in future, then
allocate a new URL for the new version.

> Well, H8's ABI for GCC is original AFAIK, not an extension of some
> vendor's ABI.  But you are right, I forgot about complex numbers.

Of course complex numbers aren't themselves an extension (for ABIs that
are recent enough to cover C99, or that considered Fortran in the first
place), it's complex integers specifically that are a GCC extension.  
(There might be other extensions beyond complex integers and VLAs in
structures that have ABI significance; those were just the obvious ones.)

-- 
Joseph S. Myers
jsm@polyomino.org.uk