Re: Documenting GCC-only ABI

[Kazu Hirata <kazu at cs dot umass dot edu>]

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