[Bug gas/10775] x86 64 documentation addenda

[konrad dot schwarz at siemens dot com]

------- Additional Comments From konrad dot schwarz at siemens dot com  
2009-10-19 07:05 -------
Subject: RE:  x86 64 documentation addenda

Hi,  

forgive me for being so blunt, but you are wrong in rejecting some parts of the 
patch.

Please see below for a detailed rebuttal.  The gist of the argument is that the 
additions describe things not documented in or deviations from the SDM.  Some 
things are documented in the AT&T documentation (which is actually the SUN 
documentation).  The GAS manual however, has not required reading the SUN 
documentation as a prerequisite up to now; it should stay independent of AT&T 
resp. SUN documentation.

The motivation for submitting this bug report is that, despite having read the 
SDM, it still took several ill-spent hours of experimentation to get my code to 
assemble.  Had the GAS manual held the information supplied by this patch, this 
would have been avoided.

Konrad Schwarz


> -----Original Message-----
> From: hjl dot tools at gmail dot com 
> [mailto:address@hidden 
> Sent: Friday, October 16, 2009 6:30 PM
> To: Schwarz, Konrad
> Subject: [Bug gas/10775] x86 64 documentation addenda
> 
> 
> ------- Additional Comments From hjl dot tools at gmail dot 
> com  2009-10-16 16:30 -------
> (In reply to comment #0)
> > The following information is lacking from the GAS manual:
> > 
> > In node (as.info)i386-Mnemonics, add at the end of 9.13.4,
> > 
> > In 64-bit mode, `movabs' is the form of the mov instruction 
> which loads
> > a 64-bit literal into a register.
> >
> 
> movabs is not the only form to load a 64-bit literal into a register.

If there are other forms, where are they documented?

> I don't think we want to go into such details here.

movabs is not an official Intel mnemonic.  Node (as.info)i386-Mnemonics 
documents the detailed differences between Intel and AT&T syntax, so I don't 
understand your reaction at all here.

As a practical matter, it took me maybe one or two hours to figure this out.  
Other users of GAS should have it easier.

> 
> 
> > The AT&T/Unixware assembler is documented at
> > 
> http://docs.sun.com/app/docs/doc/802-1948?l=en&q=assembler+manual and
> > http://docs.sun.com/app/docs/doc/817-5477?l=en.

What harm comes of adding this?  The AT&T/Unixware assembler manual is not 
available from SCO's site (makers of Unixware)---only from SUN; they also 
defined the extensions to 64-bit mode.  Again, establishing this probably took 
an hour or two.

> > 
> > In node (as.info)i386-Regs, before "* the 8 debug registers:" add
> > * The processor control register `%cr8'.
> > 
> > At the end of that node, add
> > 
> > The 80386 flags register is not supported as a distinct 
> register.  Instead, the
> > instructions `PUSH [ER]?FLAGS' and `POP [EA]?FLAGS' are 
> encoded as `pushf[wlq]'
> > and `popf[wlq]'.
> 
> I don't think this belongs here. People should consult SDM when
> writing assembly code.

The SDM uses the mnemonics PUSH EFLAGS and POP EFLAGS, but GAS in AT&T mode 
does not support this syntax.  Reference to a register %eflags results in a GAS 
assembler error.  Again, figuring this out took me maybe an hour.  What is 
being documented here are the differences between the SDM and GAS.

> 
> > After node (as.info)i386-16bit, add a new section:
> > 
> > 9.13.13 Writing 64-bit Code
> > ---------------------------
> > The `.code64' directive causes the assembler to emit AMD64 
> ``long mode''
> > (64-bit) code.  As mentioned above, the `.code32' directive 
> switches to 32-bit
> > code.  Which mode the assembler is in originally depends on 
> the --32 and --64
> > options.
> 
> I will check in this patch.
> 
> diff --git a/gas/doc/c-i386.texi b/gas/doc/c-i386.texi
> index cf0bfa8..50e6e98 100644
> --- a/gas/doc/c-i386.texi
> +++ b/gas/doc/c-i386.texi
> @@ -513,6 +513,9 @@ the 4 8-bit registers: @samp{%sil}, 
> @samp{%dil}, @samp{%bpl}
> , @samp{%spl}.
>  the 8 debug registers: @address@hidden
>  
>  @item
> +the 8 control registers: @address@hidden

Does GAS really support cr9--cr15?  These registers are currently not 
documented by the SDM.

> +
> address@hidden
>  the 8 SSE registers: @address@hidden
>  @end itemize
>  
> @@ -812,8 +815,9 @@ or 64-bit x86-64 code depending on the 
> default configuration
> ,
>  it also supports writing code to run in real mode or in 
> 16-bit protected
>  mode code segments.  To do this, put a @samp{.code16} or
>  @samp{.code16gcc} directive before the assembly language 
> instructions to
> -be run in 16-bit mode.  You can switch @address@hidden 
> back to writing
> -normal 32-bit code with the @samp{.code32} directive.
> +be run in 16-bit mode.  You can switch @address@hidden to writing
> +32-bit code with the @samp{.code32} directive or 64-bit code with the
> address@hidden directive.

Documenting how to generate 64-bit code in a section entitled "Writing 16-bit 
Code" seems suboptimal.

>  
>  @samp{.code16gcc} provides experimental support for generating 16-bit
>  code from gcc, and differs from @samp{.code16} in that @samp{call},
> 
> 
> -- 
> 
> 
> http://sourceware.org/bugzilla/show_bug.cgi?id=10775
> 
> ------- You are receiving this mail because: -------
> You reported the bug, or are watching the reporter.
> 

-- 


http://sourceware.org/bugzilla/show_bug.cgi?id=10775

------- You are receiving this mail because: -------
You are on the CC list for the bug, or are watching someone who is.