[PATCH] doc - document how gcc relies on the length of an asm

[Richard Earnshaw]

> This is a documentation update in response to PR 11442 where the user had 
> put a .skip directive in an ASM statement and this broke GCC's asm size 
> estimation rules.  It tries to make it clear that this is a user error 
> that will only be detected by the assembler.
> 
> Comments?  If I don't hear any objections I'll commit this in a few days.
> 
> R.
> 
> <date>  Richard Earnshaw  <rearnsha@arm.com>
> 
> 	* extend.texi: Document how GCC estimates and relies on the size
> 	of an asm.
> 

I tweaked the wording slightly and installed the following:


-------------- next part --------------
Index: doc/extend.texi
===================================================================
RCS file: /cvs/gcc/gcc/gcc/doc/extend.texi,v
retrieving revision 1.161
diff -p -r1.161 extend.texi
*** doc/extend.texi	16 Sep 2003 07:58:25 -0000	1.161
--- doc/extend.texi	4 Oct 2003 10:15:52 -0000
*************** If you are writing a header file that sh
*** 4136,4141 ****
--- 4136,4161 ----
  programs, write @code{__asm__} instead of @code{asm}.  @xref{Alternate
  Keywords}.
  
+ @subsection Size of an @code{asm}
+ 
+ Some targets require that GCC track the size of each instruction used in
+ order to generate correct code.  Because the final length of an
+ @code{asm} is only known by the assembler, GCC must make an estimate as
+ to how big it will be.  The estimate is formed by counting the number of
+ statements in the pattern of the @code{asm} and multiplying that by the
+ length of the longest instruction on that processor.  Statements in the
+ @code{asm} are identified by newline characters and whatever statement
+ separator characters are supported by the assembler; on most processors
+ this is the `@code{;}' character.
+ 
+ Normally, GCC's estimate is perfectly adequate to ensure that correct
+ code is generated, but it is possible to confuse the compiler if you use
+ pseudo instructions or assembler macros that expand into multiple real
+ instructions or if you use assembler directives that expand to more
+ space in the object file than would be needed for a single instruction.
+ If this happens then the assembler will produce a diagnostic saying that
+ a label is unreachable.
+ 
  @subsection i386 floating point asm operands
  
  There are several rules on the usage of stack-like regs in