Re: document IA-64 options

[Jim Wilson <wilson at cygnus dot com>]

>> + Generate code for the GNU linker.  This is the default.  Also, this is the
>> + default if the configure option @samp{--with-gnu-ld} is used.

>It gets to be the default twice?
>I don't understand.

I'm just trying to be complete.  At the moment, it is the default for all
toolchains I am aware of, however, there probably exist toolchains I don't
know about yet, and I can't guarantee that they use GNU linker by default.

I still think the mention of --with-gnu-ld is useful, because there may exist
someone somewhere that may need it.  If something is the default twice, then
it is still the default.

I can see how it might be confusing though.  I will go ahead and add the
@c for now.

>I think it would help a little to use the words "position independent code"
>somewhere here.

OK.  That is easy enough, though it seems a little picky.  Several other
targets mention pic and/or PIC without defining the term, so I'm not sure
why IA-64 has to define it.  While I am at it, I may as well extend this
to point out that the code is not ABI compliant to try to discourage people
from using this option.

>(Why is this `-mno-pic' rather than `-fno-pic'?)

Because it is an IA-64 specific option, and machine dependent options start
with -m.

Explaining more than that requires IA-64 specific knowledge.  IA-64 code is
always PIC, just like alpha.  The -fpic option still has a meaning though,
just like most other targets including alpha.  It means generate code for a
shared library.  This code needs to be different than static code, even though
both are pic.  -fno-pic thus makes no sense, as this option isn't the
opposite of generating code for shared libraries.

>What's a stop bit?

I see no point in describing this to anyone who doesn't understand the IA-64
architecture.  You can't write asms if you don't understand the architecture,
so anyone who needs the option will understand what it does.

A stop bit marks the end of an instruction group.  An instruction group is
a set of instructions that can (but might not be) executed in parallel.
The architecture has no interlocks, so it is up to the compiler to ensure
that all of the instructions in an instruction group can safely be executed
in parallel.  Since the compiler does not know the contents of extended asms,
it can't know whether a stop bit is necessary before or after the asm.  The
convention is that the author of an asm adds the bits if necessary.  The
-mvolatile-asm-stop option makes the compiler emit extra stop bits if the
author did not put them in the asms.  If stop bits are missing, the assembler
will warn about the problem.

> + @item -mregister-names
>It would be nice to explain why that might be useful,

Ok.

>	This is needed if your source code uses those names in asm statements.

No.

>	It may also make the generated assembler code easier to read.

Yes.  I can add this.

2001-01-16  Jim Wilson  <wilson@redhat.com>

	* invoke.texi (IA-64 options): Clarify -mgnu-as, -mgnu-ld, -mno-pic,
	and -mregister-names documentation.

Index: invoke.texi
===================================================================
RCS file: /cvs/gcc/gcc/gcc/invoke.texi,v
retrieving revision 1.266
diff -p -r1.266 invoke.texi
*** invoke.texi	2001/01/16 21:45:34	1.266
--- invoke.texi	2001/01/17 00:59:18
*************** and Linux.
*** 7721,7736 ****
  
  @item -mgnu-as
  @itemx -mno-gnu-as
! Generate code for the GNU assembler.  This is the default.  Also, this is
! the default if the configure option @samp{--with-gnu-as} is used.
  
  @item -mgnu-ld
  @itemx -mno-gnu-ld
! Generate code for the GNU linker.  This is the default.  Also, this is the
! default if the configure option @samp{--with-gnu-ld} is used.
  
  @item -mno-pic
! Generate code that does not use a global pointer register.
  
  @item -mvolatile-asm-stop
  @itemx -mno-volatile-asm-stop
--- 7721,7739 ----
  
  @item -mgnu-as
  @itemx -mno-gnu-as
! Generate code for the GNU assembler.  This is the default.
! @c Also, this is the default if the configure option @samp{--with-gnu-as}
! @c is used.
  
  @item -mgnu-ld
  @itemx -mno-gnu-ld
! Generate code for the GNU linker.  This is the default.
! @c Also, this is the default if the configure option @samp{--with-gnu-ld}
! @c is used.
  
  @item -mno-pic
! Generate code that does not use a global pointer register.  The result
! is not position independent code, and violates the IA-64 ABI.
  
  @item -mvolatile-asm-stop
  @itemx -mno-volatile-asm-stop
*************** Generate code that works around Itanium 
*** 7742,7748 ****
  @item -mregister-names
  @itemx -mno-register-names
  Generate @samp{in}, @samp{loc}, and @samp{out} register names for the
! stacked registers.
  
  @item -mno-sdata
  @itemx -msdata
--- 7745,7751 ----
  @item -mregister-names
  @itemx -mno-register-names
  Generate @samp{in}, @samp{loc}, and @samp{out} register names for the
! stacked registers.  This may make assembler output more readable.
  
  @item -mno-sdata
  @itemx -msdata