gcc.texi: Move several chapters out to ...

	* doc/gcc.texi: Move several chapters out to ...
	* doc/configterms.texi, doc/fragments.texi, doc/hostconfig.texi,
	doc/include/linux-and-gnu.texi, doc/interface.texi,
	doc/makefile.texi, doc/passes.texi, doc/portability.texi:
	... here.  New files.
	* doc/gcc.texi, doc/contrib.texi: Move section headings into
	contrib.texi.
	* Makefile.in ($(docdir)/gcc.info, gcc.dvi): Update dependencies.

From-SVN: r46951

1 files changed, 102 insertions, 0 deletions

diff --git a/gcc/doc/interface.texi b/gcc/doc/interface.texi
new file mode 100644
index 0000000..846de56b
--- /dev/null
+++ b/gcc/doc/interface.texi
@@ -0,0 +1,102 @@
+@c Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998,
+@c 1999, 2000, 2001 Free Software Foundation, Inc.
+@c This is part of the GCC manual.
+@c For copying conditions, see the file gcc.texi.
+
+@node Interface
+@chapter Interfacing to GCC Output
+@cindex interfacing to GCC output
+@cindex run-time conventions
+@cindex function call conventions
+@cindex conventions, run-time
+
+GCC is normally configured to use the same function calling convention
+normally in use on the target system.  This is done with the
+machine-description macros described (@pxref{Target Macros}).
+
+@cindex unions, returning
+@cindex structures, returning
+@cindex returning structures and unions
+However, returning of structure and union values is done differently on
+some target machines.  As a result, functions compiled with PCC
+returning such types cannot be called from code compiled with GCC,
+and vice versa.  This does not cause trouble often because few Unix
+library routines return structures or unions.
+
+GCC code returns structures and unions that are 1, 2, 4 or 8 bytes
+long in the same registers used for @code{int} or @code{double} return
+values.  (GCC typically allocates variables of such types in
+registers also.)  Structures and unions of other sizes are returned by
+storing them into an address passed by the caller (usually in a
+register).  The machine-description macros @code{STRUCT_VALUE} and
+@code{STRUCT_INCOMING_VALUE} tell GCC where to pass this address.
+
+By contrast, PCC on most target machines returns structures and unions
+of any size by copying the data into an area of static storage, and then
+returning the address of that storage as if it were a pointer value.
+The caller must copy the data from that memory area to the place where
+the value is wanted.  This is slower than the method used by GCC, and
+fails to be reentrant.
+
+On some target machines, such as RISC machines and the 80386, the
+standard system convention is to pass to the subroutine the address of
+where to return the value.  On these machines, GCC has been
+configured to be compatible with the standard compiler, when this method
+is used.  It may not be compatible for structures of 1, 2, 4 or 8 bytes.
+
+@cindex argument passing
+@cindex passing arguments
+GCC uses the system's standard convention for passing arguments.  On
+some machines, the first few arguments are passed in registers; in
+others, all are passed on the stack.  It would be possible to use
+registers for argument passing on any machine, and this would probably
+result in a significant speedup.  But the result would be complete
+incompatibility with code that follows the standard convention.  So this
+change is practical only if you are switching to GCC as the sole C
+compiler for the system.  We may implement register argument passing on
+certain machines once we have a complete GNU system so that we can
+compile the libraries with GCC@.
+
+On some machines (particularly the Sparc), certain types of arguments
+are passed ``by invisible reference''.  This means that the value is
+stored in memory, and the address of the memory location is passed to
+the subroutine.
+
+@cindex @code{longjmp} and automatic variables
+If you use @code{longjmp}, beware of automatic variables.  ISO C says that
+automatic variables that are not declared @code{volatile} have undefined
+values after a @code{longjmp}.  And this is all GCC promises to do,
+because it is very difficult to restore register variables correctly, and
+one of GCC's features is that it can put variables in registers without
+your asking it to.
+
+If you want a variable to be unaltered by @code{longjmp}, and you don't
+want to write @code{volatile} because old C compilers don't accept it,
+just take the address of the variable.  If a variable's address is ever
+taken, even if just to compute it and ignore it, then the variable cannot
+go in a register:
+
+@example
+@{
+  int careful;
+  &careful;
+  @dots{}
+@}
+@end example
+
+@cindex arithmetic libraries
+@cindex math libraries
+@opindex msoft-float
+Code compiled with GCC may call certain library routines.  Most of
+them handle arithmetic for which there are no instructions.  This
+includes multiply and divide on some machines, and floating point
+operations on any machine for which floating point support is disabled
+with @option{-msoft-float}.  Some standard parts of the C library, such as
+@code{bcopy} or @code{memcpy}, are also called automatically.  The usual
+function call interface is used for calling the library routines.
+
+Some of these routines can be defined in mostly machine-independent C;
+they appear in @file{libgcc2.c}.  Others must be hand-written in
+assembly language for each processor.  Wherever they are defined, they
+are compiled into the support library, @file{libgcc.a}, which is
+automatically searched when you link programs with GCC@.