[Bug gas/10775] New: x86 64 documentation addenda

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.

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.

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]'.

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.

--
           Summary: x86 64 documentation addenda
           Product: binutils
           Version: 2.19
            Status: NEW
          Severity: normal
          Priority: P2
         Component: gas
        AssignedTo: unassigned at sources dot redhat dot com
        ReportedBy: konrad dot schwarz at siemens dot com
                CC: bug-binutils at gnu dot org


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.


_______________________________________________
bug-binutils mailing list
bug-binutils@...
http://lists.gnu.org/mailman/listinfo/bug-binutils

------- 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.
I don't think we want to go into such details here.

> 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.
>
> 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.

> 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: @samp{%db8}--@samp{%db15}.
 
 @item
+the 8 control registers: @samp{%cr8}--@samp{%cr15}.
+
+@item
 the 8 SSE registers: @samp{%xmm8}--@samp{%xmm15}.
 @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 @code{@value{AS}} back to writing
-normal 32-bit code with the @samp{.code32} directive.
+be run in 16-bit mode.  You can switch @code{@value{AS}} to writing
+32-bit code with the @samp{.code32} directive or 64-bit code with the
+@samp{.code64} directive.
 
 @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 are on the CC list for the bug, or are watching someone who is.


_______________________________________________
bug-binutils mailing list
bug-binutils@...
http://lists.gnu.org/mailman/listinfo/bug-binutils

------- Additional Comments From cvs-commit at gcc dot gnu dot org  2009-10-16 16:33 -------
Subject: Bug 10775

CVSROOT: /cvs/src
Module name: src
Changes by: hjl@... 2009-10-16 16:33:17

Modified files:
        gas            : ChangeLog
        gas/doc        : c-i386.texi

Log message:
        2009-10-16  H.J. Lu  <hongjiu.lu@...>
       
        PR gas/10775
        * doc/c-i386.texi: Mention the 8 extra control registers for
        x86-64.
        Mention .code64 directive.

Patches:
http://sources.redhat.com/cgi-bin/cvsweb.cgi/src/gas/ChangeLog.diff?cvsroot=src&r1=1.3987&r2=1.3988
http://sources.redhat.com/cgi-bin/cvsweb.cgi/src/gas/doc/c-i386.texi.diff?cvsroot=src&r1=1.38&r2=1.39



--


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.


_______________________________________________
bug-binutils mailing list
bug-binutils@...
http://lists.gnu.org/mailman/listinfo/bug-binutils

------- Additional Comments From hjl dot tools at gmail dot com  2009-10-16 16:55 -------
Fixed.

--
           What    |Removed                     |Added
----------------------------------------------------------------------------
             Status|NEW                         |RESOLVED
         Resolution|                            |FIXED


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.


_______________________________________________
bug-binutils mailing list
bug-binutils@...
http://lists.gnu.org/mailman/listinfo/bug-binutils

------- 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:sourceware-bugzilla@...]
> 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: @samp{%db8}--@samp{%db15}.
>  
>  @item
> +the 8 control registers: @samp{%cr8}--@samp{%cr15}.

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

> +
> +@item
>  the 8 SSE registers: @samp{%xmm8}--@samp{%xmm15}.
>  @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 @code{@value{AS}}
> back to writing
> -normal 32-bit code with the @samp{.code32} directive.
> +be run in 16-bit mode.  You can switch @code{@value{AS}} to writing
> +32-bit code with the @samp{.code32} directive or 64-bit code with the
> +@samp{.code64} 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.


_______________________________________________
bug-binutils mailing list
bug-binutils@...
http://lists.gnu.org/mailman/listinfo/bug-binutils

------- Additional Comments From konrad dot schwarz at siemens dot com  2009-10-19 08:52 -------
Please add the other parts of the patch too.  See Comment #4 for why.  (Sorry
for the long lines).

If you wish, I can submit the proposed changes in patch form.

--
           What    |Removed                     |Added
----------------------------------------------------------------------------
             Status|RESOLVED                    |REOPENED
         Resolution|FIXED                       |


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.


_______________________________________________
bug-binutils mailing list
bug-binutils@...
http://lists.gnu.org/mailman/listinfo/bug-binutils

------- Additional Comments From hjl dot tools at gmail dot com  2009-10-19 17:08 -------
(In reply to comment #4)

> >
> > movabs is not the only form to load a 64-bit literal into a register.
>
> If there are other forms, where are they documented?

The normal "mov" insn:

mov $0x1ffffffff,%rax

works fine for me.

> > 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.

movabs is only required only if you want a specific insn encoding
Otherwise, you can use "mov". Also movabs can also be used in

movabs 0x1ffffffff,%rax

which has a different meaning.

> >
> >
> > > 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.

Gas manual isn't a real x86 assembler reference. I always
point users to Sun's manual if they want to know the details.

> > >
> > > 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.

My Intel64/ia32 SDM doesn't have PUSH EFLAGS nor POP EFLAGS.
It only has pushf/popf.

> >
> > > 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: @samp{%db8}--@samp{%db15}.
> >  
> >  @item
> > +the 8 control registers: @samp{%cr8}--@samp{%cr15}.
>
> Does GAS really support cr9--cr15?  These registers are currently not

documented by the SDM.

Gas supports r0 to r15. But not all of them are valid, like
CR1, CR5, CR6, CR7, and CR9–CR15. I will revert it. People
should read SDM when accessing them.

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

Please feel free to submit a patch.  Thanks.


--


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.


_______________________________________________
bug-binutils mailing list
bug-binutils@...
http://lists.gnu.org/mailman/listinfo/bug-binutils

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

> > > movabs is not the only form to load a 64-bit literal into
> a register.
> >
> > If there are other forms, where are they documented?
>
> The normal "mov" insn:
>
> mov $0x1ffffffff,%rax
>
> works fine for me.
>
> > > 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.
>
> movabs is only required only if you want a specific insn encoding
> Otherwise, you can use "mov". Also movabs can also be used in
>
> movabs 0x1ffffffff,%rax
>
> which has a different meaning.

What is the point of not writing this in the manual?

> > > > 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.
>
> Gas manual isn't a real x86 assembler reference. I always
> point users to Sun's manual if they want to know the details.

So, do you want to continue to do this and have those users who don't think of asking you personally luck out, or should this information be put into the GAS manual?

[...]
> My Intel64/ia32 SDM doesn't have PUSH EFLAGS nor POP EFLAGS.
> It only has pushf/popf.

I'm sorry, my bad.

> > Does GAS really support cr9--cr15?  These registers are
> currently not
> documented by the SDM.
>
> Gas supports r0 to r15. But not all of them are valid, like
> CR1, CR5, CR6, CR7, and CR9-CR15. I will revert it. People
> should read SDM when accessing them.
>
> >
> > Documenting how to generate 64-bit code in a section
> entitled "Writing 16-bit
> Code" seems suboptimal.
> >
>
> Please feel free to submit a patch.  Thanks.

Thank you very much.

--


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.


_______________________________________________
bug-binutils mailing list
bug-binutils@...
http://lists.gnu.org/mailman/listinfo/bug-binutils

------- Additional Comments From cvs-commit at gcc dot gnu dot org  2009-10-20 22:18 -------
Subject: Bug 10775

CVSROOT: /cvs/src
Module name: src
Changes by: hjl@... 2009-10-20 22:18:19

Modified files:
        gas            : ChangeLog
        gas/doc        : c-i386.texi
        gas/testsuite  : ChangeLog
        gas/testsuite/gas/i386: immed64.d l1om.d x86-64-disp-intel.d
                                x86-64-disp.d x86_64.d
        opcodes        : ChangeLog i386-dis.c

Log message:
        gas/
       
        2009-10-20  H.J. Lu  <hongjiu.lu@...>
       
        PR gas/10775
        * doc/c-i386.texi: Mention movabs.
       
        gas/testsuite/
       
        2009-10-20  H.J. Lu  <hongjiu.lu@...>
       
        PR gas/10775
        * gas/i386/immed64.d: Updated.
        * gas/i386/l1om.d: Likewise.
        * gas/i386/x86-64-disp-intel.d: Likewise.
        * gas/i386/x86-64-disp.d: Likewise.
        * gas/i386/x86_64.d: Likewise.
       
        opcodes/
       
        2009-10-20  H.J. Lu  <hongjiu.lu@...>
       
        PR gas/10775
        * i386-dis.c: Document LB, LS and LV macros.
        (dis386): Use mov%LB, mov%LS and mov%LV on mov instruction
        with the 64-bit displacement or immediate operand.
        (putop): Handle LB, LS and LV macros.

Patches:
http://sources.redhat.com/cgi-bin/cvsweb.cgi/src/gas/ChangeLog.diff?cvsroot=src&r1=1.3993&r2=1.3994
http://sources.redhat.com/cgi-bin/cvsweb.cgi/src/gas/doc/c-i386.texi.diff?cvsroot=src&r1=1.40&r2=1.41
http://sources.redhat.com/cgi-bin/cvsweb.cgi/src/gas/testsuite/ChangeLog.diff?cvsroot=src&r1=1.1571&r2=1.1572
http://sources.redhat.com/cgi-bin/cvsweb.cgi/src/gas/testsuite/gas/i386/immed64.d.diff?cvsroot=src&r1=1.2&r2=1.3
http://sources.redhat.com/cgi-bin/cvsweb.cgi/src/gas/testsuite/gas/i386/l1om.d.diff?cvsroot=src&r1=1.2&r2=1.3
http://sources.redhat.com/cgi-bin/cvsweb.cgi/src/gas/testsuite/gas/i386/x86-64-disp-intel.d.diff?cvsroot=src&r1=1.2&r2=1.3
http://sources.redhat.com/cgi-bin/cvsweb.cgi/src/gas/testsuite/gas/i386/x86-64-disp.d.diff?cvsroot=src&r1=1.3&r2=1.4
http://sources.redhat.com/cgi-bin/cvsweb.cgi/src/gas/testsuite/gas/i386/x86_64.d.diff?cvsroot=src&r1=1.19&r2=1.20
http://sources.redhat.com/cgi-bin/cvsweb.cgi/src/opcodes/ChangeLog.diff?cvsroot=src&r1=1.1480&r2=1.1481
http://sources.redhat.com/cgi-bin/cvsweb.cgi/src/opcodes/i386-dis.c.diff?cvsroot=src&r1=1.204&r2=1.205



--


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.


_______________________________________________
bug-binutils mailing list
bug-binutils@...
http://lists.gnu.org/mailman/listinfo/bug-binutils