diff options
Diffstat (limited to 'gnu/usr.bin/gas/doc')
| -rw-r--r-- | gnu/usr.bin/gas/doc/Makefile | 187 | ||||
| -rw-r--r-- | gnu/usr.bin/gas/doc/Makefile.in | 172 | ||||
| -rw-r--r-- | gnu/usr.bin/gas/doc/a29k-coff.m4 | 14 | ||||
| -rw-r--r-- | gnu/usr.bin/gas/doc/a29k.m4 | 9 | ||||
| -rw-r--r-- | gnu/usr.bin/gas/doc/all.m4 | 20 | ||||
| -rw-r--r-- | gnu/usr.bin/gas/doc/as.texinfo | 6730 | ||||
| -rw-r--r-- | gnu/usr.bin/gas/doc/config.status | 5 | ||||
| -rw-r--r-- | gnu/usr.bin/gas/doc/configure.in | 34 | ||||
| -rw-r--r-- | gnu/usr.bin/gas/doc/gen.m4 | 14 | ||||
| -rw-r--r-- | gnu/usr.bin/gas/doc/h8.m4 | 15 | ||||
| -rw-r--r-- | gnu/usr.bin/gas/doc/i80386.m4 | 12 | ||||
| -rw-r--r-- | gnu/usr.bin/gas/doc/i960.m4 | 16 | ||||
| -rw-r--r-- | gnu/usr.bin/gas/doc/m680x0.m4 | 8 | ||||
| -rw-r--r-- | gnu/usr.bin/gas/doc/none.m4 | 57 | ||||
| -rw-r--r-- | gnu/usr.bin/gas/doc/pretex.m4 | 268 | ||||
| -rw-r--r-- | gnu/usr.bin/gas/doc/sparc.m4 | 8 | ||||
| -rw-r--r-- | gnu/usr.bin/gas/doc/vax.m4 | 7 | ||||
| -rw-r--r-- | gnu/usr.bin/gas/doc/vintage.m4 | 11 |
18 files changed, 7587 insertions, 0 deletions
diff --git a/gnu/usr.bin/gas/doc/Makefile b/gnu/usr.bin/gas/doc/Makefile new file mode 100644 index 00000000000..f2c319f382a --- /dev/null +++ b/gnu/usr.bin/gas/doc/Makefile @@ -0,0 +1,187 @@ +# This file was generated automatically by configure. Do not edit. +host_alias = i386 +host_cpu = i386 +host_vendor = unknown +host_os = scosysv322 +target_alias = i386 +target_cpu = i386 +target_vendor = unknown +target_os = scosysv322 +target_makefile_frag = +host_makefile_frag = +site_makefile_frag = +links = +VPATH = . +ALL=all.internal +# Makefile for GNU Assembler documentation +# - see pretex.m4 for discussion of preprocessor definitions +# Copyright (C) 1987-1992 Free Software Foundation, Inc. + +#This file is part of GNU GAS. + +#GNU GAS is free software; you can redistribute it and/or modify +#it under the terms of the GNU General Public License as published by +#the Free Software Foundation; either version 2, or (at your option) +#any later version. + +#GNU GAS is distributed in the hope that it will be useful, +#but WITHOUT ANY WARRANTY; without even the implied warranty of +#MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +#GNU General Public License for more details. + +#You should have received a copy of the GNU General Public License +#along with GNU GAS; see the file COPYING. If not, write to +#the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA. + +# The targets for external use include: +# all, doc, proto, install, uninstall, includes, TAGS, +# clean, cleanconfig, realclean, stage1, stage2, stage3, stage4. + +# Variables that exist for you to override. +# See below for how to change them for certain systems. + +srcdir = . + +prefix = /usr/local + +bindir = $(prefix)/bin +datadir = $(prefix)/lib +libdir = $(prefix)/lib +mandir = $(datadir)/man +man1dir = $(mandir)/man1 +man2dir = $(mandir)/man2 +man3dir = $(mandir)/man3 +man4dir = $(mandir)/man4 +man5dir = $(mandir)/man5 +man6dir = $(mandir)/man6 +man7dir = $(mandir)/man7 +man8dir = $(mandir)/man8 +man9dir = $(mandir)/man9 +infodir = $(datadir)/info +includedir = $(prefix)/include +docdir = $(datadir)/doc + +SHELL = /bin/sh + +INSTALL = install -c +INSTALL_PROGRAM = $(INSTALL) +INSTALL_DATA = $(INSTALL) + +AR = ar +AR_FLAGS = qv +BISON = bison +MAKEINFO = makeinfo +RANLIB = ranlib + +# What version of the manual you want (see *.m4); "all" includes everything +CONFIG=all + +# Sun/Berkeley m4 doesn't have all the things we need; use GNU or sV +M4=gm4 +#M4=/usr/5bin/m4 + +# Directory for gas source +srcdir = . + +# Where to find texinfo.tex to format docn with TeX +TEXIDIR = $(srcdir)/../texinfo/fsf + +#### host, target, and site specific Makefile frags come in here. +## + +all: +clean: +install: + $(INSTALL_DATA) $(srcdir)/as.1 $(man1dir)/as.1 + +info: as.info + +as.info: as-${CONFIG}.texinfo + makeinfo -o as.info as-${CONFIG}.texinfo + +install-info: as.info + [ -d $(infodir) ] || mkdir $(infodir) + for i in as.info* ; do \ + $(INSTALL_DATA) $$i $(infodir)/$$i ; \ + done + +as.dvi: as-${CONFIG}.texinfo + TEXINPUTS=${TEXIDIR}:.:$$TEXINPUTS tex as-${CONFIG}.texinfo + texindex as-${CONFIG}.?? + TEXINPUTS=${TEXIDIR}:.:$$TEXINPUTS tex as-${CONFIG}.texinfo + mv as-${CONFIG}.dvi as.dvi + rm as-${CONFIG}.?? as-${CONFIG}.??? + +# ROFF doc targets as.ms, as.mm, as.me +# (we don't use a variable because we don't trust all makes to handle +# a var in the target name right). +# roff output (-ms) +as.ms: as-${CONFIG}.texinfo + sed -e '/\\input texinfo/d' \ + -e '/@c TEXI2ROFF-KILL/,/@c END TEXI2ROFF-KILL/d' \ + -e 's/{.*,,/{/' \ + as-${CONFIG}.texinfo | \ + texi2roff -ms >as.ms + +# roff output (-mm) +as.mm: as-${CONFIG}.texinfo + sed -e '/\\input texinfo/d' \ + -e '/@c TEXI2ROFF-KILL/,/@c END TEXI2ROFF-KILL/d' \ + -e 's/{.*,,/{/' \ + -e '/@noindent/d' \ + as-${CONFIG}.texinfo | \ + texi2roff -mm | \ + sed -e 's/---/\\(em/g' \ + >as.mm + +# roff output (-me) +as.me: as-${CONFIG}.texinfo + sed -e '/\\input texinfo/d' \ + -e '/@c TEXI2ROFF-KILL/,/@c END TEXI2ROFF-KILL/d' \ + -e 's/{.*,,/{/' \ + as-${CONFIG}.texinfo | \ + texi2roff -me >as.me + + + +as-all.texinfo: as.texinfo pretex.m4 none.m4 all.m4 + ${M4} $(srcdir)/pretex.m4 $(srcdir)/none.m4 $(srcdir)/all.m4 $(srcdir)/as.texinfo >as-all.texinfo + +as-a29k.texinfo: as.texinfo pretex.m4 none.m4 a29k.m4 + ${M4} pretex.m4 none.m4 a29k.m4 as.texinfo >as-a29k.texinfo + +as-a29k-coff.texinfo: as.texinfo pretex.m4 none.m4 a29k-coff.m4 + ${M4} pretex.m4 none.m4 a29k-coff.m4 as.texinfo >as-a29k-coff.texinfo + +as-gen.texinfo: as.texinfo pretex.m4 none.m4 gen.m4 + ${M4} pretex.m4 none.m4 gen.m4 as.texinfo >as-gen.texinfo + +as-h8.texinfo: as.texinfo pretex.m4 none.m4 h8.m4 + ${M4} pretex.m4 none.m4 h8.m4 as.texinfo >as-h8.texinfo + +as-i80386.texinfo: as.texinfo pretex.m4 none.m4 i80386.m4 + ${M4} pretex.m4 none.m4 i80386.m4 as.texinfo >as-i80386.texinfo + +as-i960.texinfo: as.texinfo pretex.m4 none.m4 i960.m4 + ${M4} pretex.m4 none.m4 i960.m4 as.texinfo >as-i960.texinfo + +as-m680x0.texinfo: as.texinfo pretex.m4 none.m4 m680x0.m4 + ${M4} pretex.m4 none.m4 m680x0.m4 as.texinfo >as-m680x0.texinfo + +as-sparc.texinfo: as.texinfo pretex.m4 none.m4 sparc.m4 + ${M4} pretex.m4 none.m4 sparc.m4 as.texinfo >as-sparc.texinfo + +as-vax.texinfo: as.texinfo pretex.m4 none.m4 vax.m4 + ${M4} pretex.m4 none.m4 vax.m4 as.texinfo >as-vax.texinfo + +as-vintage.texinfo: as.texinfo pretex.m4 none.m4 vintage.m4 + ${M4} pretex.m4 none.m4 vintage.m4 as.texinfo >as-vintage.texinfo + +clean-info: + rm -f as-${CONFIG}.* as.dvi as.info* + +force: + +Makefile: $(srcdir)/Makefile.in $(host_makefile_frag) $(target_makefile_frag) + $(SHELL) ./config.status + diff --git a/gnu/usr.bin/gas/doc/Makefile.in b/gnu/usr.bin/gas/doc/Makefile.in new file mode 100644 index 00000000000..fdae0b28f40 --- /dev/null +++ b/gnu/usr.bin/gas/doc/Makefile.in @@ -0,0 +1,172 @@ +# Makefile for GNU Assembler documentation +# - see pretex.m4 for discussion of preprocessor definitions +# Copyright (C) 1987-1992 Free Software Foundation, Inc. + +#This file is part of GNU GAS. + +#GNU GAS is free software; you can redistribute it and/or modify +#it under the terms of the GNU General Public License as published by +#the Free Software Foundation; either version 2, or (at your option) +#any later version. + +#GNU GAS is distributed in the hope that it will be useful, +#but WITHOUT ANY WARRANTY; without even the implied warranty of +#MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +#GNU General Public License for more details. + +#You should have received a copy of the GNU General Public License +#along with GNU GAS; see the file COPYING. If not, write to +#the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA. + +# The targets for external use include: +# all, doc, proto, install, uninstall, includes, TAGS, +# clean, cleanconfig, realclean, stage1, stage2, stage3, stage4. + +# Variables that exist for you to override. +# See below for how to change them for certain systems. + +srcdir = . + +prefix = /usr/local + +bindir = $(prefix)/bin +datadir = $(prefix)/lib +libdir = $(prefix)/lib +mandir = $(datadir)/man +man1dir = $(mandir)/man1 +man2dir = $(mandir)/man2 +man3dir = $(mandir)/man3 +man4dir = $(mandir)/man4 +man5dir = $(mandir)/man5 +man6dir = $(mandir)/man6 +man7dir = $(mandir)/man7 +man8dir = $(mandir)/man8 +man9dir = $(mandir)/man9 +infodir = $(datadir)/info +includedir = $(prefix)/include +docdir = $(datadir)/doc + +SHELL = /bin/sh + +INSTALL = install -c +INSTALL_PROGRAM = $(INSTALL) +INSTALL_DATA = $(INSTALL) + +AR = ar +AR_FLAGS = qv +BISON = bison +MAKEINFO = makeinfo +RANLIB = ranlib + +# What version of the manual you want (see *.m4); "all" includes everything +CONFIG=all + +# Sun/Berkeley m4 doesn't have all the things we need; use GNU or sV +M4=gm4 +#M4=/usr/5bin/m4 + +# Directory for gas source +srcdir=.. + +# Where to find texinfo.tex to format docn with TeX +TEXIDIR = $(srcdir)/../texinfo/fsf + +#### host, target, and site specific Makefile frags come in here. +## + +all: +clean: +install: + $(INSTALL_DATA) $(srcdir)/as.1 $(man1dir)/as.1 + +info: as.info + +as.info: as-${CONFIG}.texinfo + makeinfo -o as.info as-${CONFIG}.texinfo + +install-info: as.info + [ -d $(infodir) ] || mkdir $(infodir) + for i in as.info* ; do \ + $(INSTALL_DATA) $$i $(infodir)/$$i ; \ + done + +as.dvi: as-${CONFIG}.texinfo + TEXINPUTS=${TEXIDIR}:.:$$TEXINPUTS tex as-${CONFIG}.texinfo + texindex as-${CONFIG}.?? + TEXINPUTS=${TEXIDIR}:.:$$TEXINPUTS tex as-${CONFIG}.texinfo + mv as-${CONFIG}.dvi as.dvi + rm as-${CONFIG}.?? as-${CONFIG}.??? + +# ROFF doc targets as.ms, as.mm, as.me +# (we don't use a variable because we don't trust all makes to handle +# a var in the target name right). +# roff output (-ms) +as.ms: as-${CONFIG}.texinfo + sed -e '/\\input texinfo/d' \ + -e '/@c TEXI2ROFF-KILL/,/@c END TEXI2ROFF-KILL/d' \ + -e 's/{.*,,/{/' \ + as-${CONFIG}.texinfo | \ + texi2roff -ms >as.ms + +# roff output (-mm) +as.mm: as-${CONFIG}.texinfo + sed -e '/\\input texinfo/d' \ + -e '/@c TEXI2ROFF-KILL/,/@c END TEXI2ROFF-KILL/d' \ + -e 's/{.*,,/{/' \ + -e '/@noindent/d' \ + as-${CONFIG}.texinfo | \ + texi2roff -mm | \ + sed -e 's/---/\\(em/g' \ + >as.mm + +# roff output (-me) +as.me: as-${CONFIG}.texinfo + sed -e '/\\input texinfo/d' \ + -e '/@c TEXI2ROFF-KILL/,/@c END TEXI2ROFF-KILL/d' \ + -e 's/{.*,,/{/' \ + as-${CONFIG}.texinfo | \ + texi2roff -me >as.me + + + +as-all.texinfo: as.texinfo pretex.m4 none.m4 all.m4 + ${M4} $(srcdir)/pretex.m4 $(srcdir)/none.m4 $(srcdir)/all.m4 $(srcdir)/as.texinfo >as-all.texinfo + +as-a29k.texinfo: as.texinfo pretex.m4 none.m4 a29k.m4 + ${M4} pretex.m4 none.m4 a29k.m4 as.texinfo >as-a29k.texinfo + +as-a29k-coff.texinfo: as.texinfo pretex.m4 none.m4 a29k-coff.m4 + ${M4} pretex.m4 none.m4 a29k-coff.m4 as.texinfo >as-a29k-coff.texinfo + +as-gen.texinfo: as.texinfo pretex.m4 none.m4 gen.m4 + ${M4} pretex.m4 none.m4 gen.m4 as.texinfo >as-gen.texinfo + +as-h8.texinfo: as.texinfo pretex.m4 none.m4 h8.m4 + ${M4} pretex.m4 none.m4 h8.m4 as.texinfo >as-h8.texinfo + +as-i80386.texinfo: as.texinfo pretex.m4 none.m4 i80386.m4 + ${M4} pretex.m4 none.m4 i80386.m4 as.texinfo >as-i80386.texinfo + +as-i960.texinfo: as.texinfo pretex.m4 none.m4 i960.m4 + ${M4} pretex.m4 none.m4 i960.m4 as.texinfo >as-i960.texinfo + +as-m680x0.texinfo: as.texinfo pretex.m4 none.m4 m680x0.m4 + ${M4} pretex.m4 none.m4 m680x0.m4 as.texinfo >as-m680x0.texinfo + +as-sparc.texinfo: as.texinfo pretex.m4 none.m4 sparc.m4 + ${M4} pretex.m4 none.m4 sparc.m4 as.texinfo >as-sparc.texinfo + +as-vax.texinfo: as.texinfo pretex.m4 none.m4 vax.m4 + ${M4} pretex.m4 none.m4 vax.m4 as.texinfo >as-vax.texinfo + +as-vintage.texinfo: as.texinfo pretex.m4 none.m4 vintage.m4 + ${M4} pretex.m4 none.m4 vintage.m4 as.texinfo >as-vintage.texinfo + +clean-info: + rm -f as-${CONFIG}.* as.dvi as.info* + +force: + +Makefile: $(srcdir)/Makefile.in $(host_makefile_frag) $(target_makefile_frag) + $(SHELL) ./config.status + diff --git a/gnu/usr.bin/gas/doc/a29k-coff.m4 b/gnu/usr.bin/gas/doc/a29k-coff.m4 new file mode 100644 index 00000000000..c3b04e1e134 --- /dev/null +++ b/gnu/usr.bin/gas/doc/a29k-coff.m4 @@ -0,0 +1,14 @@ +_divert__(-1) +_define__(<_A29K__>,<1>) +_define__(<_GENERIC__>,<0>) +_define__(<_HOST__>,<AMD 29K>) +_define__(<_MACH_DEP__>,<AMD29K-Dependent>) +_define__(<_AOUT__>,<0>) +_define__(<_BOUT__>,<0>) +_define__(<_COFF__>,<1>) +_define__(<_ELF__>,<0>) +_define__(<_DIFFTABKLUG__>,0) NO difference-table kluge +_define__(<_IEEEFLOAT__>,1) IEEE floating point +_define__(<_W32__>,1) 32-bit words +_define__(<_W16__>,0) +_divert__<> diff --git a/gnu/usr.bin/gas/doc/a29k.m4 b/gnu/usr.bin/gas/doc/a29k.m4 new file mode 100644 index 00000000000..95643875774 --- /dev/null +++ b/gnu/usr.bin/gas/doc/a29k.m4 @@ -0,0 +1,9 @@ +_divert__(-1) +_define__(<_A29K__>,<1>) +_define__(<_HOST__>,<AMD 29K>) +_define__(<_MACH_DEP__>,<AMD29K-Dependent>) +_define__(<_DIFFTABKLUG__>,0) NO difference-table kluge +_define__(<_IEEEFLOAT__>,1) IEEE floating point +_define__(<_W32__>,1) 32-bit words +_define__(<_W16__>,0) +_divert__<> diff --git a/gnu/usr.bin/gas/doc/all.m4 b/gnu/usr.bin/gas/doc/all.m4 new file mode 100644 index 00000000000..9205895c185 --- /dev/null +++ b/gnu/usr.bin/gas/doc/all.m4 @@ -0,0 +1,20 @@ +_divert__(-1) +<$Id: all.m4,v 1.1 1995/10/18 08:39:08 deraadt Exp $> +_define__(<_ALL_ARCH__>,<1>) +_define__(<_GENERIC__>,<1>) In case none.m4 changes its mind abt default + +_define__(<_AOUT__>,<1>) +_define__(<_BOUT__>,<1>) +_define__(<_COFF__>,<1>) +_define__(<_ELF__>,<1>) + +_define__(<_A29K__>,<1>) +_define__(<_H8__>,<1>) +_define__(<_I80386__>,<1>) +_define__(<_I960__>,<1>) +_define__(<_M680X0__>,<1>) +_define__(<_SPARC__>,<1>) +_define__(<_VAX__>,<1>) +_define__(<_VXWORKS__>,<1>) + +_divert__<> diff --git a/gnu/usr.bin/gas/doc/as.texinfo b/gnu/usr.bin/gas/doc/as.texinfo new file mode 100644 index 00000000000..ce666058cfb --- /dev/null +++ b/gnu/usr.bin/gas/doc/as.texinfo @@ -0,0 +1,6730 @@ +_dnl__ -*-Texinfo-*- +_dnl__ Copyright (c) 1991 1992 Free Software Foundation, Inc. +_dnl__ $Id: as.texinfo,v 1.1 1995/10/18 08:39:08 deraadt Exp $ +\input texinfo @c -*-Texinfo-*- +@c Copyright (c) 1991 1992 Free Software Foundation, Inc. +@c %**start of header +@setfilename _AS__.info +_if__(_GENERIC__) +@settitle Using _AS__ +_fi__(_GENERIC__) +_if__(!_GENERIC__) +@settitle Using _AS__ (_HOST__) +_fi__(!_GENERIC__) +@setchapternewpage odd +@c @smallbook +@c @cropmarks +@c %**end of header + +@finalout +@syncodeindex ky cp + +_if__(0) + +NOTE: this manual is marked up for preprocessing with a collection +of m4 macros called "pretex.m4". + +THIS IS THE FULL SOURCE. The full source needs to be run through m4 +before either tex- or info- formatting: for example, + m4 pretex.m4 none.m4 m680x0.m4 as.texinfo >as-680x0.texinfo +will produce (assuming your path finds either GNU or SysV m4; Berkeley +won't do) a file, configured for the M680x0 version of GAS, suitable for +formatting. See the text in "pretex.m4" for a fuller explanation (and +the macro definitions). + +_fi__(0) +@c +@ifinfo +This file documents the GNU Assembler "_AS__". + +Copyright (C) 1991 Free Software Foundation, Inc. + +Permission is granted to make and distribute verbatim copies of +this manual provided the copyright notice and this permission notice +are preserved on all copies. + +@ignore +Permission is granted to process this file through Tex and print the +results, provided the printed document carries copying permission +notice identical to this one except for the removal of this paragraph +(this paragraph not being relevant to the printed manual). + +@end ignore +Permission is granted to copy and distribute modified versions of this +manual under the conditions for verbatim copying, provided also that the +section entitled ``GNU General Public License'' is included exactly as +in the original, and provided that the entire resulting derived work is +distributed under the terms of a permission notice identical to this +one. + +Permission is granted to copy and distribute translations of this manual +into another language, under the above conditions for modified versions, +except that the section entitled ``GNU General Public License'' may be +included in a translation approved by the Free Software Foundation +instead of in the original English. +@end ifinfo + +@titlepage +@title Using _AS__ +@subtitle The GNU Assembler +_if__(!_GENERIC__) +@subtitle for the _HOST__ family +_fi__(!_GENERIC__) +@sp 1 +@subtitle January 1992 +@sp 1 +@sp 13 +The Free Software Foundation Inc. thanks The Nice Computer +Company of Australia for loaning Dean Elsner to write the +first (Vax) version of @code{as} for Project GNU. +The proprietors, management and staff of TNCCA thank FSF for +distracting the boss while they got some work +done. +@sp 3 +@author Dean Elsner, Jay Fenlason & friends +@c edited by: pesch@cygnus.com +@page +@tex +\def\$#1${{#1}} % Kluge: collect RCS revision info without $...$ +\xdef\manvers{\$Revision: 1.1 $} % For use in headers, footers too +{\parskip=0pt +\hfill \manvers\par +\hfill \TeX{}info \texinfoversion\par +} +%"boxit" macro for figures: +%Modified from Knuth's ``boxit'' macro from TeXbook (answer to exercise 21.3) +\gdef\boxit#1#2{\vbox{\hrule\hbox{\vrule\kern3pt + \vbox{\parindent=0pt\parskip=0pt\hsize=#1\kern3pt\strut\hfil +#2\hfil\strut\kern3pt}\kern3pt\vrule}\hrule}}%box with visible outline +\gdef\ibox#1#2{\hbox to #1{#2\hfil}\kern8pt}% invisible box +@end tex + +Edited by Roland Pesch for Cygnus Support. + +@vskip 0pt plus 1filll +Copyright @copyright{} 1991 Free Software Foundation, Inc. + +Permission is granted to make and distribute verbatim copies of +this manual provided the copyright notice and this permission notice +are preserved on all copies. + +Permission is granted to copy and distribute modified versions of this +manual under the conditions for verbatim copying, provided also that the +section entitled ``GNU General Public License'' is included exactly as +in the original, and provided that the entire resulting derived work is +distributed under the terms of a permission notice identical to this +one. + +Permission is granted to copy and distribute translations of this manual +into another language, under the above conditions for modified versions, +except that the section entitled ``GNU General Public License'' may be +included in a translation approved by the Free Software Foundation +instead of in the original English. +@end titlepage +@page +@node Top, Overview, (dir), (dir) +@ifinfo +This file is a user guide to the GNU assembler @code{_AS__}. +_if__(!_GENERIC__) +This version of the file describes @code{_AS__} configured to generate +code for _HOST__ architectures. +_fi__(!_GENERIC__) +@end ifinfo +@menu +* Overview:: Overview +* Invoking:: Command-Line Options +* Syntax:: Syntax +* Sections:: Sections and Relocation +* Symbols:: Symbols +* Expressions:: Expressions +* Pseudo Ops:: Assembler Directives +* _MACH_DEP__:: Machine Dependent Features +* Copying:: GNU GENERAL PUBLIC LICENSE +* Index:: Index +@end menu + +@node Overview, Invoking, Top, Top +@chapter Overview +@iftex +This manual is a user guide to the GNU assembler @code{_AS__}. +_if__(!_GENERIC__) +This version of the manual describes @code{_AS__} configured to generate +code for _HOST__ architectures. +_fi__(!_GENERIC__) +@end iftex + +@cindex invocation summary +@cindex option summary +@cindex summary of options +Here is a brief summary of how to invoke @code{_AS__}. For details, +@pxref{Invoking,,Comand-Line Options}. + +@c We don't use deffn and friends for the following because they seem +@c to be limited to one line for the header. +@smallexample + _AS__ [ -a | -al | -as ] [ -D ] [ -f ] + [ -I @var{path} ] [ -k ] [ -L ] + [ -o @var{objfile} ] [ -R ] [ -v ] [ -w ] +_if__(_A29K__) +@c am29k has no machine-dependent assembler options +_fi__(_A29K__) +_if__(_H8__) +@c h8/300 has no machine-dependent assembler options +_fi__(_H8__) +_if__(_I960__) +@c see md_parse_option in i960.c + [ -ACA | -ACA_A | -ACB | -ACC | -AKA | -AKB | -AKC | -AMC ] + [ -b ] [ -norelax ] +_fi__(_I960__) +_if__(_M680X0__) + [ -l ] [ -mc68000 | -mc68010 | -mc68020 ] +_fi__(_M680X0__) + [ -- | @var{files} @dots{} ] +@end smallexample + +@table @code +@item -a | -al | -as +Turn on assembly listings; @samp{-al}, listing only, @samp{-as}, symbols +only, @samp{-a}, everything. + +@item -D +This option is accepted only for script compatibility with calls to +other assemblers; it has no effect on @code{_AS__}. + +@item -f +``fast''---skip preprocessing (assume source is compiler output) + +@item -I @var{path} +Add @var{path} to the search list for @code{.include} directives + +@item -k +_if__((!_GENERIC__) && !_DIFFTABKLUG__) +This option is accepted but has no effect on the _HOST__ family. +_fi__((!_GENERIC__) && !_DIFFTABKLUG__) +_if__(_GENERIC__ || _DIFFTABKLUG__) +Issue warnings when difference tables altered for long displacements. +_fi__(_GENERIC__ || _DIFFTABKLUG__) + +@item -L +Keep (in symbol table) local symbols, starting with @samp{L} + +@item -o @var{objfile} +Name the object-file output from @code{_AS__} + +@item -R +Fold data section into text section + +@item -v +Announce @code{as} version + +@item -W +Suppress warning messages + +_if__(_I960__) +@item -ACA | -ACA_A | -ACB | -ACC | -AKA | -AKB | -AKC | -AMC +_if__(_GENERIC__) +(When configured for Intel 960). +_fi__(_GENERIC__) +Specify which variant of the 960 architecture is the target. + +@item -b +_if__(_GENERIC__) +(When configured for Intel 960). +_fi__(_GENERIC__) +Add code to collect statistics about branches taken. + +@item -norelax +_if__(_GENERIC__) +(When configured for Intel 960). +_fi__(_GENERIC__) +Do not alter compare-and-branch instructions for long displacements; +error if necessary. +_fi__(_I960__) + +_if__(_M680X0__) +@item -l +_if__(_GENERIC__) +(When configured for Motorola 68000). +_fi__(_GENERIC__) +Shorten references to undefined symbols, to one word instead of two + +@item -mc68000 | -mc68010 | -mc68020 +_if__(_GENERIC__) +(When configured for Motorola 68000). +_fi__(_GENERIC__) +Specify what processor in the 68000 family is the target (default 68020) +_fi__(_M680X0__) + +@item -- | @var{files} @dots{} +Standard input, or source files to assemble +@end table + +@menu +* Manual:: Structure of this Manual +* GNU Assembler:: _AS__, the GNU Assembler +* Object Formats:: Object File Formats +* Command Line:: Command Line +* Input Files:: Input Files +* Object:: Output (Object) File +* Errors:: Error and Warning Messages +@end menu + +@node Manual, GNU Assembler, Overview, Overview +@section Structure of this Manual + +@cindex manual, structure and purpose +This manual is intended to describe what you need to know to use +@sc{gnu} @code{_AS__}. We cover the syntax expected in source files, including +notation for symbols, constants, and expressions; the directives that +@code{_AS__} understands; and of course how to invoke @code{_AS__}. + +_if__(!_GENERIC__) +We also cover special features in the _HOST__ +configuration of @code{_AS__}, including assembler directives. +_fi__(!_GENERIC__) +_if__(_GENERIC__) +This manual also describes some of the machine-dependent features of +various flavors of the assembler. +_fi__(_GENERIC__) +_if__(_INTERNALS__) +This manual also describes how the assembler works internally, and +provides some information that may be useful to people attempting to +port the assembler to another machine. +_fi__(_INTERNALS__) +@refill + +@cindex machine instructions (not covered) +On the other hand, this manual is @emph{not} intended as an introduction +to programming in assembly language---let alone programming in general! +In a similar vein, we make no attempt to introduce the machine +architecture; we do @emph{not} describe the instruction set, standard +mnemonics, registers or addressing modes that are standard to a +particular architecture. +_if__(_GENERIC__) +You may want to consult the manufacturer's +machine architecture manual for this information. +_fi__(_GENERIC__) +_if__(_H8__&&!_GENERIC__) +For information on the H8/300 machine instruction set, see @cite{H8/300 +Series Programming Manual} (Hitachi ADE--602--025). +_fi__(_H8__&&!_GENERIC__) + + +@c I think this is premature---pesch@cygnus.com, 17jan1991 +@ignore +Throughout this manual, we assume that you are running @dfn{GNU}, +the portable operating system from the @dfn{Free Software +Foundation, Inc.}. This restricts our attention to certain kinds of +computer (in particular, the kinds of computers that GNU can run on); +once this assumption is granted examples and definitions need less +qualification. + +@code{_AS__} is part of a team of programs that turn a high-level +human-readable series of instructions into a low-level +computer-readable series of instructions. Different versions of +@code{_AS__} are used for different kinds of computer. +@end ignore + +@c There used to be a section "Terminology" here, which defined +@c "contents", "byte", "word", and "long". Defining "word" to any +@c particular size is confusing when the .word directive may generate 16 +@c bits on one machine and 32 bits on another; in general, for the user +@c version of this manual, none of these terms seem essential to define. +@c They were used very little even in the former draft of the manual; +@c this draft makes an effort to avoid them (except in names of +@c directives). + +@node GNU Assembler, Object Formats, Manual, Overview +@section _AS__, the GNU Assembler + +GNU @code{as} is really a family of assemblers. +_if__(!_GENERIC__) +This manual describes @code{_AS__}, a member of that family which is +configured for the _HOST__ architectures. +_fi__(!_GENERIC__) +If you use (or have used) the GNU assembler on one architecture, you +should find a fairly similar environment when you use it on another +architecture. Each version has much in common with the others, +including object file formats, most assembler directives (often called +@dfn{pseudo-ops)} and assembler syntax.@refill + +_if__(_GENERIC__||!_H8__) +@cindex purpose of @sc{gnu} @code{_AS__} +@code{_AS__} is primarily intended to assemble the output of the GNU C +compiler @code{_GCC__} for use by the linker @code{_LD__}. Nevertheless, +we've tried to make @code{_AS__} assemble correctly everything that the native +assembler would. +_fi__(_GENERIC__||!_H8__) +_if__(_VAX__) +Any exceptions are documented explicitly (@pxref{_MACH_DEP__}). +_fi__(_VAX__) +_if__(_GENERIC__||_M680X0__) +This doesn't mean @code{_AS__} always uses the same syntax as another +assembler for the same architecture; for example, we know of several +incompatible versions of 680x0 assembly language syntax. +_fi__(_GENERIC__||_M680X0__) + +Unlike older assemblers, @code{_AS__} is designed to assemble a source +program in one pass of the source file. This has a subtle impact on the +@kbd{.org} directive (@pxref{Org,,@code{.org}}). + +@node Object Formats, Command Line, GNU Assembler, Overview +@section Object File Formats + +@cindex object file format +The GNU assembler can be configured to produce several alternative +object file formats. For the most part, this does not affect how you +write assembly language programs; but directives for debugging symbols +are typically different in different file formats. @xref{Symbol +Attributes,,Symbol Attributes}. +_if__(!_GENERIC__) +_if__(!(_I960__||_A29K__)) +_if__(_AOUT__ && (!_COFF__) && (!_ELF__)) +On the _HOST__, @code{_AS__} is configured to produce @code{a.out} format object +files.@refill +_fi__(_AOUT__ && (!_COFF__) && (!_ELF__)) +_if__((!_AOUT__) && _COFF__ && (!_ELF__)) +On the _HOST__, @code{_AS__} is configured to produce COFF format object +files.@refill +_fi__((!_AOUT__) && _COFF__ && (!_ELF__)) +_fi__(!(_I960__||_A29K__)) +_if__(_A29K__) +On the _HOST__, @code{_AS__} can be configured to produce either +@code{a.out} or COFF format object files. +_fi__(_A29K__) +_if__(_I960__) +On the _HOST__, @code{_AS__} can be configured to produce either @code{b.out} or COFF +format object files. +_fi__(_I960__) +_fi__(!_GENERIC__) + +@node Command Line, Input Files, Object Formats, Overview +@section Command Line + +@cindex command line conventions +After the program name @code{_AS__}, the command line may contain +options and file names. Options may appear in any order, and may be +before, after, or between file names. The order of file names is +significant. + +@cindex standard input, as input file +@kindex -- +@file{--} (two hyphens) by itself names the standard input file +explicitly, as one of the files for @code{_AS__} to assemble. + +@cindex options, command line +Except for @samp{--} any command line argument that begins with a +hyphen (@samp{-}) is an option. Each option changes the behavior of +@code{_AS__}. No option changes the way another option works. An +option is a @samp{-} followed by one or more letters; the case of +the letter is important. All options are optional. + +Some options expect exactly one file name to follow them. The file +name may either immediately follow the option's letter (compatible +with older assemblers) or it may be the next command argument (GNU +standard). These two command lines are equivalent: + +@smallexample +_AS__ -o my-object-file.o mumble.s +_AS__ -omy-object-file.o mumble.s +@end smallexample + +@node Input Files, Object, Command Line, Overview +@section Input Files + +@cindex input +@cindex source program +@cindex files, input +We use the phrase @dfn{source program}, abbreviated @dfn{source}, to +describe the program input to one run of @code{_AS__}. The program may +be in one or more files; how the source is partitioned into files +doesn't change the meaning of the source. + +@c I added "con" prefix to "catenation" just to prove I can overcome my +@c APL training... pesch@cygnus.com +The source program is a concatenation of the text in all the files, in the +order specified. + +Each time you run @code{_AS__} it assembles exactly one source +program. The source program is made up of one or more files. +(The standard input is also a file.) + +You give @code{_AS__} a command line that has zero or more input file +names. The input files are read (from left file name to right). A +command line argument (in any position) that has no special meaning +is taken to be an input file name. + +If you give @code{_AS__} no file names it attempts to read one input file +from the @code{_AS__} standard input, which is normally your terminal. You +may have to type @key{ctl-D} to tell @code{_AS__} there is no more program +to assemble. + +Use @samp{--} if you need to explicitly name the standard input file +in your command line. + +If the source is empty, @code{_AS__} will produce a small, empty object +file. + +@subheading Filenames and Line-numbers + +@cindex input file linenumbers +@cindex line numbers, in input files +There are two ways of locating a line in the input file (or files) and +either may be used in reporting error messages. One way refers to a line +number in a physical file; the other refers to a line number in a +``logical'' file. @xref{Errors, ,Error and Warning Messages}. + +@dfn{Physical files} are those files named in the command line given +to @code{_AS__}. + +@dfn{Logical files} are simply names declared explicitly by assembler +directives; they bear no relation to physical files. Logical file names +help error messages reflect the original source file, when @code{_AS__} +source is itself synthesized from other files. +@xref{App-File,,@code{.app-file}}. + +@node Object, Errors, Input Files, Overview +@section Output (Object) File + +@cindex object file +@cindex output file +@kindex a.out +@kindex .o +Every time you run @code{_AS__} it produces an output file, which is +your assembly language program translated into numbers. This file +is the object file, named @code{a.out} unless you tell @code{_AS__} to +give it another name by using the @code{-o} option. Conventionally, +object file names end with @file{.o}. The default name of +@file{a.out} is used for historical reasons: older assemblers were +capable of assembling self-contained programs directly into a +runnable program. +@c This may still work, but hasn't been tested. + +@cindex linker +@kindex ld +The object file is meant for input to the linker @code{_LD__}. It contains +assembled program code, information to help @code{_LD__} integrate +the assembled program into a runnable file, and (optionally) symbolic +information for the debugger. + +@c link above to some info file(s) like the description of a.out. +@c don't forget to describe GNU info as well as Unix lossage. + +@node Errors, , Object, Overview +@section Error and Warning Messages + +@cindex error messsages +@cindex warning messages +@cindex messages from @code{_AS__} +@code{_AS__} may write warnings and error messages to the standard error +file (usually your terminal). This should not happen when a compiler +runs @code{_AS__} automatically. Warnings report an assumption made so +that @code{_AS__} could keep assembling a flawed program; errors report a +grave problem that stops the assembly. + +@cindex format of warning messages +Warning messages have the format + +@smallexample +file_name:@b{NNN}:Warning Message Text +@end smallexample + +@noindent +@cindex line numbers, in warnings/errors +(where @b{NNN} is a line number). If a logical file name has +been given (@pxref{App-File,,@code{.app-file}}) it is used for the filename, otherwise the +name of the current input file is used. If a logical line number was +given +_if__(!_A29K__) +(@pxref{Line,,@code{.line}}) +_fi__(!_A29K__) +_if__(_A29K__) +(@pxref{Ln,,@code{.ln}}) +_fi__(_A29K__) +then it is used to calculate the number printed, +otherwise the actual line in the current source file is printed. The +message text is intended to be self explanatory (in the grand Unix +tradition). @refill + +@cindex format of error messages +Error messages have the format +@smallexample +file_name:@b{NNN}:FATAL:Error Message Text +@end smallexample +The file name and line number are derived as for warning +messages. The actual message text may be rather less explanatory +because many of them aren't supposed to happen. + +@node Invoking, Syntax, Overview, Top +@chapter Command-Line Options + +@cindex options, all versions of @code{_AS__} +This chapter describes command-line options available in @emph{all} +versions of the GNU assembler; @pxref{_MACH_DEP__}, for options specific +_if__(!_GENERIC__) +to the _HOST__. +_fi__(!_GENERIC__) +_if__(_GENERIC__) +to particular machine architectures. +_fi__(_GENERIC__) + +@section Enable Listings: @code{-a}, @code{-al}, @code{-as} + +@kindex -a +@kindex -al +@kindex -as +@cindex listings, enabling +@cindex assembly listings, enabling +These options enable listing output from the assembler. @samp{-a} by +itself requests all listing output; @samp{-al} requests only the +output-program listing, and @samp{-as} requests only a symbol table +listing. + +Once you have specified one of these options, you can further control +listing output and its appearance using the directives @code{.list}, +@code{.nolist}, @code{.psize}, @code{.eject}, @code{.title}, and +@code{.sbttl}. + +If you do not request listing output with one of the @samp{-a} options, the +listing-control directives have no effect. + +@section @code{-D} + +@kindex -D +This option has no effect whatsoever, but it is accepted to make it more +likely that scripts written for other assemblers will also work with +@code{_AS__}. + +@section Work Faster: @code{-f} + +@kindex -f +@cindex trusted compiler +@cindex faster processing (@code{-f}) +@samp{-f} should only be used when assembling programs written by a +(trusted) compiler. @samp{-f} stops the assembler from pre-processing +the input file(s) before assembling them. @xref{Pre-processing, +,Pre-processing}. + +@quotation +@emph{Warning:} if the files actually need to be pre-processed (if they +contain comments, for example), @code{_AS__} will not work correctly if +@samp{-f} is used. +@end quotation + +@section @code{.include} search path: @code{-I} @var{path} + +@kindex -I @var{path} +@cindex paths for @code{.include} +@cindex search path for @code{.include} +@cindex @code{include} directive search path +Use this option to add a @var{path} to the list of directories +@code{_AS__} will search for files specified in @code{.include} +directives (@pxref{Include,,@code{.include}}). You may use @code{-I} as +many times as necessary to include a variety of paths. The current +working directory is always searched first; after that, @code{_AS__} +searches any @samp{-I} directories in the same order as they were +specified (left to right) on the command line. + +@section Difference Tables: @code{-k} + +@kindex -k +_if__((!_GENERIC__) && (!_DIFFTABKLUG__)) +On the _HOST__ family, this option is allowed, but has no effect. It is +permitted for compatibility with the GNU assembler on other platforms, +where it can be used to warn when the assembler alters the machine code +generated for @samp{.word} directives in difference tables. The _HOST__ +family does not have the addressing limitations that sometimes lead to this +alteration on other platforms. +_fi__((!_GENERIC__) && (!_DIFFTABKLUG__)) + +_if__(_GENERIC__ || _DIFFTABKLUG__ ) +@cindex difference tables, warning +@cindex warning for altered difference tables +@code{_AS__} sometimes alters the code emitted for directives of the form +@samp{.word @var{sym1}-@var{sym2}}; @pxref{Word,,@code{.word}}. +You can use the @samp{-k} option if you want a warning issued when this +is done. +_fi__(_GENERIC__ || _DIFFTABKLUG__ ) + +@section Include Local Labels: @code{-L} + +@kindex -L +@cindex local labels, retaining in output +Labels beginning with @samp{L} (upper case only) are called @dfn{local +labels}. @xref{Symbol Names}. Normally you don't see such labels when +debugging, because they are intended for the use of programs (like +compilers) that compose assembler programs, not for your notice. +Normally both @code{_AS__} and @code{_LD__} discard such labels, so you don't +normally debug with them. + +This option tells @code{_AS__} to retain those @samp{L@dots{}} symbols +in the object file. Usually if you do this you also tell the linker +@code{_LD__} to preserve symbols whose names begin with @samp{L}. + +@section Name the Object File: @code{-o} + +@kindex -o +@cindex naming object file +@cindex object file name +There is always one object file output when you run @code{_AS__}. By +default it has the name @file{a.out}. You use this option (which +takes exactly one filename) to give the object file a different name. + +Whatever the object file is called, @code{_AS__} will overwrite any +existing file of the same name. + +@section Join Data and Text Sections: @code{-R} + +@kindex -R +@cindex data and text sections, joining +@cindex text and data sections, joining +@cindex joining text and data sections +@cindex merging text and data sections +@code{-R} tells @code{_AS__} to write the object file as if all +data-section data lives in the text section. This is only done at +the very last moment: your binary data are the same, but data +section parts are relocated differently. The data section part of +your object file is zero bytes long because all it bytes are +appended to the text section. (@xref{Sections,,Sections and Relocation}.) + +When you specify @code{-R} it would be possible to generate shorter +address displacements (because we don't have to cross between text and +data section). We refrain from doing this simply for compatibility with +older versions of @code{_AS__}. In future, @code{-R} may work this way. + +_if__(_COFF__) +When @code{_AS__} is configured for COFF output, +this option is only useful if you use sections named @samp{.text} and +@samp{.data}. +_fi__(_COFF__) + +@section Announce Version: @code{-v} + +@kindex -v +@kindex -version +@cindex @code{_AS__} version +@cindex version of @code{_AS__} +You can find out what version of as is running by including the +option @samp{-v} (which you can also spell as @samp{-version}) on the +command line. + +@section Suppress Warnings: @code{-W} + +@kindex -W +@cindex suppressing warnings +@cindex warnings, suppressing +@code{_AS__} should never give a warning or error message when +assembling compiler output. But programs written by people often +cause @code{_AS__} to give a warning that a particular assumption was +made. All such warnings are directed to the standard error file. +If you use this option, no warnings are issued. This option only +affects the warning messages: it does not change any particular of how +@code{_AS__} assembles your file. Errors, which stop the assembly, are +still reported. + +@node Syntax, Sections, Invoking, Top +@chapter Syntax + +@cindex machine-independent syntax +@cindex syntax, machine-independent +This chapter describes the machine-independent syntax allowed in a +source file. @code{_AS__} syntax is similar to what many other assemblers +use; it is inspired in BSD 4.2 +_if__(!_VAX__) +assembler. @refill +_fi__(!_VAX__) +_if__(_VAX__) +assembler, except that @code{_AS__} does not assemble Vax bit-fields. +_fi__(_VAX__) + +@menu +* Pre-processing:: Pre-processing +* Whitespace:: Whitespace +* Comments:: Comments +* Symbol Intro:: Symbols +* Statements:: Statements +* Constants:: Constants +@end menu + +@node Pre-processing, Whitespace, Syntax, Syntax +@section Pre-Processing + +@cindex preprocessing +The pre-processor: +@itemize @bullet +@cindex whitespace, removed by preprocessor +@item +adjusts and removes extra whitespace. It leaves one space or tab before +the keywords on a line, and turns any other whitespace on the line into +a single space. + +@cindex comments, removed by preprocessor +@item +removes all comments, replacing them with a single space, or an +appropriate number of newlines. + +@cindex constants, converted by preprocessor +@item +converts character constants into the appropriate numeric values. +@end itemize + +Excess whitespace, comments, and character constants +cannot be used in the portions of the input text that are not +pre-processed. + +@cindex turning preprocessing on and off +@cindex preprocessing, turning on and off +@kindex #NO_APP +@kindex #APP +If the first line of an input file is @code{#NO_APP} or the @samp{-f} +option is given, the input file will not be pre-processed. Within such +an input file, parts of the file can be pre-processed by putting a line +that says @code{#APP} before the text that should be pre-processed, and +putting a line that says @code{#NO_APP} after them. This feature is +mainly intend to support @code{asm} statements in compilers whose output +normally does not need to be pre-processed. + +@node Whitespace, Comments, Pre-processing, Syntax +@section Whitespace + +@cindex whitespace +@dfn{Whitespace} is one or more blanks or tabs, in any order. +Whitespace is used to separate symbols, and to make programs neater for +people to read. Unless within character constants +(@pxref{Characters,,Character Constants}), any whitespace means the same +as exactly one space. + +@node Comments, Symbol Intro, Whitespace, Syntax +@section Comments + +@cindex comments +There are two ways of rendering comments to @code{_AS__}. In both +cases the comment is equivalent to one space. + +Anything from @samp{/*} through the next @samp{*/} is a comment. +This means you may not nest these comments. + +@smallexample +/* + The only way to include a newline ('\n') in a comment + is to use this sort of comment. +*/ + +/* This sort of comment does not nest. */ +@end smallexample + +@cindex line comment character +Anything from the @dfn{line comment} character to the next newline +is considered a comment and is ignored. The line comment character is +_if__(_VAX__) +@samp{#} on the Vax; +_fi__(_VAX__) +_if__(_I960__) +@samp{#} on the i960; +_fi__(_I960__) +_if__(_M680X0__) +@samp{|} on the 680x0; +_fi__(_M680X0__) +_if__(_A29K__) +@samp{;} for the AMD 29K family; +_fi__(_A29K__) +_if__(_H8__) +@samp{;} for the _HOST__ family; +_fi__(_H8__) +@pxref{_MACH_DEP__}. @refill +@c FIXME: fill in SPARC line comment char + +_if__(_GENERIC__) +On some machines there are two different line comment characters. One +will only begin a comment if it is the first non-whitespace character on +a line, while the other will always begin a comment. +_fi__(_GENERIC__) + +@kindex # +@cindex lines starting with @code{#} +@cindex logical line numbers +To be compatible with past assemblers, a special interpretation is +given to lines that begin with @samp{#}. Following the @samp{#} an +absolute expression (@pxref{Expressions}) is expected: this will be +the logical line number of the @b{next} line. Then a string +(@xref{Strings}.) is allowed: if present it is a new logical file +name. The rest of the line, if any, should be whitespace. + +If the first non-whitespace characters on the line are not numeric, +the line is ignored. (Just like a comment.) +@smallexample + # This is an ordinary comment. +# 42-6 "new_file_name" # New logical file name + # This is logical line # 36. +@end smallexample +This feature is deprecated, and may disappear from future versions +of @code{_AS__}. + +@node Symbol Intro, Statements, Comments, Syntax +@section Symbols + +@cindex symbols +@cindex characters used in symbols +A @dfn{symbol} is one or more characters chosen from the set of all +letters (both upper and lower case), digits and +_if__(!_H8__) +the three characters @samp{_.$} +_fi__(!_H8__) +_if__(_H8__) +the two characters @samp{_.} +_if__(_GENERIC__) +On most machines, you can also use @code{$} in symbol names; exceptions +are noted in @ref{_MACH_DEP__}. +_fi__(_GENERIC__) +_fi__(_H8__) +No symbol may begin with a digit. Case is significant. +There is no length limit: all characters are significant. Symbols are +delimited by characters not in that set, or by the beginning of a file +(since the source program must end with a newline, the end of a file is +not a possible symbol delimiter). @xref{Symbols}. +@cindex length of symbols + +@node Statements, Constants, Symbol Intro, Syntax +@section Statements + +@cindex statements, structure of +@cindex line separator character +@cindex statement separator character +_if__(!_GENERIC__) +_if__(!(_A29K__||_H8__)) +A @dfn{statement} ends at a newline character (@samp{\n}) or at a +semicolon (@samp{;}). The newline or semicolon is considered part of +the preceding statement. Newlines and semicolons within character +constants are an exception: they don't end statements. +_fi__(!(_A29K__||_H8__)) +_if__(_A29K__) +A @dfn{statement} ends at a newline character (@samp{\n}) or an ``at'' +sign (@samp{@@}). The newline or at sign is considered part of the +preceding statement. Newlines and at signs within character constants +are an exception: they don't end statements. +_fi__(_A29K__) +_if__(_H8__) +A @dfn{statement} ends at a newline character (@samp{\n}) or a dollar +sign (@samp{$}). The newline or dollar sign is considered part of the +preceding statement. Newlines and dollar signs within character constants +are an exception: they don't end statements. +_fi__(_H8__) +_fi__(!_GENERIC__) +_if__(_GENERIC__) +A @dfn{statement} ends at a newline character (@samp{\n}) or line +separator character. (The line separator is usually @samp{;}, unless +this conflicts with the comment character; @pxref{_MACH_DEP__}.) The +newline or separator character is considered part of the preceding +statement. Newlines and separators within character constants are an +exception: they don't end statements. +_fi__(_GENERIC__) + +@cindex newline, required at file end +@cindex EOF, newline must precede +It is an error to end any statement with end-of-file: the last +character of any input file should be a newline.@refill + +@cindex continuing statements +@cindex multi-line statements +@cindex statement on multiple lines +You may write a statement on more than one line if you put a +backslash (@kbd{\}) immediately in front of any newlines within the +statement. When @code{_AS__} reads a backslashed newline both +characters are ignored. You can even put backslashed newlines in +the middle of symbol names without changing the meaning of your +source program. + +An empty statement is allowed, and may include whitespace. It is ignored. + +@cindex instructions and directives +@cindex directives and instructions +@c "key symbol" is not used elsewhere in the document; seems pedantic to +@c @defn{} it in that case, as was done previously... pesch@cygnus.com, +@c 13feb91. +A statement begins with zero or more labels, optionally followed by a +key symbol which determines what kind of statement it is. The key +symbol determines the syntax of the rest of the statement. If the +symbol begins with a dot @samp{.} then the statement is an assembler +directive: typically valid for any computer. If the symbol begins with +a letter the statement is an assembly language @dfn{instruction}: it +will assemble into a machine language instruction. +_if__(_GENERIC__) +Different versions of @code{_AS__} for different computers will +recognize different instructions. In fact, the same symbol may +represent a different instruction in a different computer's assembly +language.@refill +_fi__(_GENERIC__) + +@cindex @code{:} (label) +@cindex label (@code{:}) +A label is a symbol immediately followed by a colon (@code{:}). +Whitespace before a label or after a colon is permitted, but you may not +have whitespace between a label's symbol and its colon. @xref{Labels}. + +@smallexample +label: .directive followed by something +another_label: # This is an empty statement. + instruction operand_1, operand_2, @dots{} +@end smallexample + +@node Constants, , Statements, Syntax +@section Constants + +@cindex constants +A constant is a number, written so that its value is known by +inspection, without knowing any context. Like this: +@smallexample +.byte 74, 0112, 092, 0x4A, 0X4a, 'J, '\J # All the same value. +.ascii "Ring the bell\7" # A string constant. +.octa 0x123456789abcdef0123456789ABCDEF0 # A bignum. +.float 0f-314159265358979323846264338327\ +95028841971.693993751E-40 # - pi, a flonum. +@end smallexample + +@menu +* Characters:: Character Constants +* Numbers:: Number Constants +@end menu + +@node Characters, Numbers, Constants, Constants +@subsection Character Constants + +@cindex character constants +@cindex constants, character +There are two kinds of character constants. A @dfn{character} stands +for one character in one byte and its value may be used in +numeric expressions. String constants (properly called string +@emph{literals}) are potentially many bytes and their values may not be +used in arithmetic expressions. + +@menu +* Strings:: Strings +* Chars:: Characters +@end menu + +@node Strings, Chars, Characters, Characters +@subsubsection Strings + +@cindex string constants +@cindex constants, string +A @dfn{string} is written between double-quotes. It may contain +double-quotes or null characters. The way to get special characters +into a string is to @dfn{escape} these characters: precede them with +a backslash @samp{\} character. For example @samp{\\} represents +one backslash: the first @code{\} is an escape which tells +@code{_AS__} to interpret the second character literally as a backslash +(which prevents @code{_AS__} from recognizing the second @code{\} as an +escape character). The complete list of escapes follows. + +@cindex escape codes, character +@cindex character escape codes +@table @kbd +@c @item \a +@c Mnemonic for ACKnowledge; for ASCII this is octal code 007. +@c +@item \b +@cindex @code{\b} (backspace character) +@cindex backspace (@code{\b}) +Mnemonic for backspace; for ASCII this is octal code 010. + +@c @item \e +@c Mnemonic for EOText; for ASCII this is octal code 004. +@c +@item \f +@cindex @code{\f} (formfeed character) +@cindex formfeed (@code{\f}) +Mnemonic for FormFeed; for ASCII this is octal code 014. + +@item \n +@cindex @code{\n} (newline character) +@cindex newline (@code{\n}) +Mnemonic for newline; for ASCII this is octal code 012. + +@c @item \p +@c Mnemonic for prefix; for ASCII this is octal code 033, usually known as @code{escape}. +@c +@item \r +@cindex @code{\r} (carriage return character) +@cindex carriage return (@code{\r}) +Mnemonic for carriage-Return; for ASCII this is octal code 015. + +@c @item \s +@c Mnemonic for space; for ASCII this is octal code 040. Included for compliance with +@c other assemblers. +@c +@item \t +@cindex @code{\t} (tab) +@cindex tab (@code{\t}) +Mnemonic for horizontal Tab; for ASCII this is octal code 011. + +@c @item \v +@c Mnemonic for Vertical tab; for ASCII this is octal code 013. +@c @item \x @var{digit} @var{digit} @var{digit} +@c A hexadecimal character code. The numeric code is 3 hexadecimal digits. +@c +@item \ @var{digit} @var{digit} @var{digit} +@cindex @code{\@var{ddd}} (octal character code) +@cindex octal character code (@code{\@var{ddd}}) +An octal character code. The numeric code is 3 octal digits. +For compatibility with other Unix systems, 8 and 9 are accepted as digits: +for example, @code{\008} has the value 010, and @code{\009} the value 011. + +@item \\ +@cindex @code{\\} (@samp{\} character) +@cindex backslash (@code{\\}) +Represents one @samp{\} character. + +@c @item \' +@c Represents one @samp{'} (accent acute) character. +@c This is needed in single character literals +@c (@xref{Characters,,Character Constants}.) to represent +@c a @samp{'}. +@c +@item \" +@cindex @code{\"} (doublequote character) +@cindex doublequote (@code{\"}) +Represents one @samp{"} character. Needed in strings to represent +this character, because an unescaped @samp{"} would end the string. + +@item \ @var{anything-else} +Any other character when escaped by @kbd{\} will give a warning, but +assemble as if the @samp{\} was not present. The idea is that if +you used an escape sequence you clearly didn't want the literal +interpretation of the following character. However @code{_AS__} has no +other interpretation, so @code{_AS__} knows it is giving you the wrong +code and warns you of the fact. +@end table + +Which characters are escapable, and what those escapes represent, +varies widely among assemblers. The current set is what we think +the BSD 4.2 assembler recognizes, and is a subset of what most C +compilers recognize. If you are in doubt, don't use an escape +sequence. + +@node Chars, , Strings, Characters +@subsubsection Characters + +@cindex single character constant +@cindex character, single +@cindex constant, single character +A single character may be written as a single quote immediately +followed by that character. The same escapes apply to characters as +to strings. So if you want to write the character backslash, you +must write @kbd{'\\} where the first @code{\} escapes the second +@code{\}. As you can see, the quote is an acute accent, not a +grave accent. A newline +_if__(!_GENERIC__) +_if__(!(_A29K__||_H8__)) +(or semicolon @samp{;}) +_fi__(!(_A29K__||_H8__)) +_if__(_A29K__) +(or at sign @samp{@@}) +_fi__(_A29K__) +_if__(_H8__) +(or dollar sign @samp{$}) +_fi__(_H8__) +_fi__(!_GENERIC__) +immediately following an acute accent is taken as a literal character +and does not count as the end of a statement. The value of a character +constant in a numeric expression is the machine's byte-wide code for +that character. @code{_AS__} assumes your character code is ASCII: +@kbd{'A} means 65, @kbd{'B} means 66, and so on. @refill + +@node Numbers, , Characters, Constants +@subsection Number Constants + +@cindex constants, number +@cindex number constants +@code{_AS__} distinguishes three kinds of numbers according to how they +are stored in the target machine. @emph{Integers} are numbers that +would fit into an @code{int} in the C language. @emph{Bignums} are +integers, but they are stored in more than 32 bits. @emph{Flonums} +are floating point numbers, described below. + +@menu +* Integers:: Integers +* Bignums:: Bignums +* Flonums:: Flonums +_if__(_I960__&&!_GENERIC__) +* Bit Fields:: Bit Fields +_fi__(_I960__&&!_GENERIC__) +@end menu + +@node Integers, Bignums, Numbers, Numbers +@subsubsection Integers +@cindex integers +@cindex constants, integer + +@cindex binary integers +@cindex integers, binary +A binary integer is @samp{0b} or @samp{0B} followed by zero or more of +the binary digits @samp{01}. + +@cindex octal integers +@cindex integers, octal +An octal integer is @samp{0} followed by zero or more of the octal +digits (@samp{01234567}). + +@cindex decimal integers +@cindex integers, decimal +A decimal integer starts with a non-zero digit followed by zero or +more digits (@samp{0123456789}). + +@cindex hexadecimal integers +@cindex integers, hexadecimal +A hexadecimal integer is @samp{0x} or @samp{0X} followed by one or +more hexadecimal digits chosen from @samp{0123456789abcdefABCDEF}. + +Integers have the usual values. To denote a negative integer, use +the prefix operator @samp{-} discussed under expressions +(@pxref{Prefix Ops,,Prefix Operators}). + +@node Bignums, Flonums, Integers, Numbers +@subsubsection Bignums + +@cindex bignums +@cindex constants, bignum +A @dfn{bignum} has the same syntax and semantics as an integer +except that the number (or its negative) takes more than 32 bits to +represent in binary. The distinction is made because in some places +integers are permitted while bignums are not. + +_if__(_I960__&&!_GENERIC__) +@node Flonums, Bit Fields, Bignums, Numbers +_fi__(_I960__&&!_GENERIC__) +_if__(_GENERIC__||!_I960__) +@node Flonums, , Bignums, Numbers +_fi__(_GENERIC__||!_I960__) +@subsubsection Flonums +@cindex flonums +@cindex floating point numbers +@cindex constants, floating point + +@cindex precision, floating point +A @dfn{flonum} represents a floating point number. The translation is +indirect: a decimal floating point number from the text is converted by +@code{_AS__} to a generic binary floating point number of more than +sufficient precision. This generic floating point number is converted +to a particular computer's floating point format (or formats) by a +portion of @code{_AS__} specialized to that computer. + +A flonum is written by writing (in order) +@itemize @bullet +@item +The digit @samp{0}. +@item +A letter, to tell @code{_AS__} the rest of the number is a flonum. +_if__(_GENERIC__) +@kbd{e} is recommended. Case is not important. +@ignore +@c FIXME: verify if flonum syntax really this vague for most cases + (Any otherwise illegal letter +will work here, but that might be changed. Vax BSD 4.2 assembler seems +to allow any of @samp{defghDEFGH}.) +@end ignore +_fi__(_GENERIC__) +_if__(_A29K__||_H8__) +_if__(_GENERIC__) +On the AMD 29K and H8/300 architectures, the letter must be: +_fi__(_GENERIC__) +One of the letters @samp{DFPRSX} (in upper or lower case). +_fi__(_A29K__||_H8__) +_if__(_I960__) +_if__(_GENERIC__) +On the Intel 960 architecture, the letter must be: +_fi__(_GENERIC__) +One of the letters @samp{DFT} (in upper or lower case). +_fi__(_I960__) +@item +An optional sign: either @samp{+} or @samp{-}. +@item +An optional @dfn{integer part}: zero or more decimal digits. +@item +An optional @dfn{fractional part}: @samp{.} followed by zero +or more decimal digits. +@item +An optional exponent, consisting of: +@itemize @bullet +@item +An @samp{E} or @samp{e}. +@c I can't find a config where "EXP_CHARS" is other than 'eE', but in +@c principle this can perfectly well be different on different targets. +@item +Optional sign: either @samp{+} or @samp{-}. +@item +One or more decimal digits. +@end itemize +@end itemize + +At least one of the integer part or the fractional part must be +present. The floating point number has the usual base-10 value. + +@code{_AS__} does all processing using integers. Flonums are computed +independently of any floating point hardware in the computer running +@code{_AS__}. + +_if__(_I960__&&!_GENERIC__) +@c Bit fields are written as a general facility but are also controlled +@c by a conditional-compilation flag---which is as of now (21mar91) +@c turned on only by the i960 config of GAS. +@node Bit Fields, , Flonums, Numbers +@subsubsection Bit Fields + +@cindex bit fields +@cindex constants, bit field +You can also define numeric constants as @dfn{bit fields}. +specify two numbers separated by a colon--- +@example +@var{mask}:@var{value} +@end example +@noindent +the first will act as a mask; @code{_AS__} will bitwise-and it with the +second value. + +The resulting number is then packed +_if__(_GENERIC__) +@c this conditional paren in case bit fields turned on elsewhere than 960 +(in host-dependent byte order) +_fi__(_GENERIC__) +into a field whose width depends on which assembler directive has the +bit-field as its argument. Overflow (a result from the bitwise and +requiring more binary digits to represent) is not an error; instead, +more constants are generated, of the specified width, beginning with the +least significant digits.@refill + +The directives @code{.byte}, @code{.hword}, @code{.int}, @code{.long}, +@code{.short}, and @code{.word} accept bit-field arguments. +_fi__(_I960__&&!_GENERIC__) + +@node Sections, Symbols, Syntax, Top +@chapter Sections and Relocation +@cindex sections +@cindex relocation + +@menu +* Secs Background:: Background +* _LD__ Sections:: _LD__ Sections +* _AS__ Sections:: _AS__ Internal Sections +* Sub-Sections:: Sub-Sections +* bss:: bss Section +@end menu + +@node Secs Background, _LD__ Sections, Sections, Sections +@section Background + +Roughly, a section is a range of addresses, with no gaps; all data +``in'' those addresses is treated the same for some particular purpose. +For example there may be a ``read only'' section. + +@cindex linker, and assembler +@cindex assembler, and linker +The linker @code{_LD__} reads many object files (partial programs) and +combines their contents to form a runnable program. When @code{_AS__} +emits an object file, the partial program is assumed to start at address +0. @code{_LD__} will assign the final addresses the partial program +occupies, so that different partial programs don't overlap. This is +actually an over-simplification, but it will suffice to explain how +@code{_AS__} uses sections. + +@code{_LD__} moves blocks of bytes of your program to their run-time +addresses. These blocks slide to their run-time addresses as rigid +units; their length does not change and neither does the order of bytes +within them. Such a rigid unit is called a @emph{section}. Assigning +run-time addresses to sections is called @dfn{relocation}. It includes +the task of adjusting mentions of object-file addresses so they refer to +the proper run-time addresses. +_if__(_H8__) +For the H8/300, @code{_AS__} pads sections if needed to ensure they end +on a word (sixteen bit) boundary. +_fi__(_H8__) + +@cindex standard @code{_AS__} sections +An object file written by @code{_AS__} has at least three sections, any +of which may be empty. These are named @dfn{text}, @dfn{data} and +@dfn{bss} sections. + +_if__(_COFF__) +_if__(_GENERIC__) +When it generates COFF output, +_fi__(_GENERIC__) +@code{_AS__} can also generate whatever other named sections you specify +using the @samp{.section} directive (@pxref{Section,,@code{.section}}). +If you don't use any directives that place output in the @samp{.text} +or @samp{.data} sections, these sections will still exist, but will be empty. +_fi__(_COFF__) + +Within the object file, the text section starts at address @code{0}, the +data section follows, and the bss section follows the data section. + +To let @code{_LD__} know which data will change when the sections are +relocated, and how to change that data, @code{_AS__} also writes to the +object file details of the relocation needed. To perform relocation +@code{_LD__} must know, each time an address in the object +file is mentioned: +@itemize @bullet +@item +Where in the object file is the beginning of this reference to +an address? +@item +How long (in bytes) is this reference? +@item +Which section does the address refer to? What is the numeric value of +@display +(@var{address}) @minus{} (@var{start-address of section})? +@end display +@item +Is the reference to an address ``Program-Counter relative''? +@end itemize + +@cindex addresses, format of +@cindex section-relative addressing +In fact, every address @code{_AS__} ever uses is expressed as +@display +(@var{section}) + (@var{offset into section}) +@end display +@noindent +Further, every expression @code{_AS__} computes is of this section-relative +nature. @dfn{Absolute expression} means an expression with section +``absolute'' (@pxref{_LD__ Sections}). A @dfn{pass1 expression} means +an expression with section ``pass1'' (@pxref{_AS__ Sections,,_AS__ +Internal Sections}). In this manual we use the notation @{@var{secname} +@var{N}@} to mean ``offset @var{N} into section @var{secname}''. + +Apart from text, data and bss sections you need to know about the +@dfn{absolute} section. When @code{_LD__} mixes partial programs, +addresses in the absolute section remain unchanged. For example, address +@code{@{absolute 0@}} is ``relocated'' to run-time address 0 by @code{_LD__}. +Although two partial programs' data sections will not overlap addresses +after linking, @emph{by definition} their absolute sections will overlap. +Address @code{@{absolute@ 239@}} in one partial program will always be the same +address when the program is running as address @code{@{absolute@ 239@}} in any +other partial program. + +The idea of sections is extended to the @dfn{undefined} section. Any +address whose section is unknown at assembly time is by definition +rendered @{undefined @var{U}@}---where @var{U} will be filled in later. +Since numbers are always defined, the only way to generate an undefined +address is to mention an undefined symbol. A reference to a named +common block would be such a symbol: its value is unknown at assembly +time so it has section @emph{undefined}. + +By analogy the word @emph{section} is used to describe groups of sections in +the linked program. @code{_LD__} puts all partial programs' text +sections in contiguous addresses in the linked program. It is +customary to refer to the @emph{text section} of a program, meaning all +the addresses of all partial program's text sections. Likewise for +data and bss sections. + +Some sections are manipulated by @code{_LD__}; others are invented for +use of @code{_AS__} and have no meaning except during assembly. + +@node _LD__ Sections, _AS__ Sections, Secs Background, Sections +@section _LD__ Sections +@code{_LD__} deals with just four kinds of sections, summarized below. + +@table @strong + +_if__(_GENERIC__||_COFF__) +@cindex named sections +@cindex sections, named +@item named sections +_fi__(_GENERIC__||_COFF__) +_if__(_AOUT__||_BOUT__) +@cindex text section +@cindex data section +@item text section +@itemx data section +_fi__(_AOUT__||_BOUT__) +These sections hold your program. @code{_AS__} and @code{_LD__} treat them as +separate but equal sections. Anything you can say of one section is +true another. +_if__(_AOUT__||_BOUT__) +When the program is running, however, it is +customary for the text section to be unalterable. The +text section is often shared among processes: it will contain +instructions, constants and the like. The data section of a running +program is usually alterable: for example, C variables would be stored +in the data section. +_fi__(_AOUT__||_BOUT__) + +@cindex bss section +@item bss section +This section contains zeroed bytes when your program begins running. It +is used to hold unitialized variables or common storage. The length of +each partial program's bss section is important, but because it starts +out containing zeroed bytes there is no need to store explicit zero +bytes in the object file. The bss section was invented to eliminate +those explicit zeros from object files. + +@cindex absolute section +@item absolute section +Address 0 of this section is always ``relocated'' to runtime address 0. +This is useful if you want to refer to an address that @code{_LD__} must +not change when relocating. In this sense we speak of absolute +addresses being ``unrelocatable'': they don't change during relocation. + +@cindex undefined section +@item undefined section +This ``section'' is a catch-all for address references to objects not in +the preceding sections. +@c FIXME: ref to some other doc on obj-file formats could go here. +@end table + +@cindex relocation example +An idealized example of three relocatable sections follows. +_if__(_COFF__) +The example uses the traditional section names @samp{.text} and @samp{.data}. +_fi__(_COFF__) +Memory addresses are on the horizontal axis. + +@c TEXI2ROFF-KILL +@ifinfo +@c END TEXI2ROFF-KILL +@smallexample + +-----+----+--+ +partial program # 1: |ttttt|dddd|00| + +-----+----+--+ + + text data bss + seg. seg. seg. + + +---+---+---+ +partial program # 2: |TTT|DDD|000| + +---+---+---+ + + +--+---+-----+--+----+---+-----+~~ +linked program: | |TTT|ttttt| |dddd|DDD|00000| + +--+---+-----+--+----+---+-----+~~ + + addresses: 0 @dots{} +@end smallexample +@c TEXI2ROFF-KILL +@end ifinfo +@c FIXME make sure no page breaks inside figure!! +@tex + +\line{\it Partial program \#1: \hfil} +\line{\ibox{2.5cm}{\tt text}\ibox{2cm}{\tt data}\ibox{1cm}{\tt bss}\hfil} +\line{\boxit{2.5cm}{\tt ttttt}\boxit{2cm}{\tt dddd}\boxit{1cm}{\tt 00}\hfil} + +\line{\it Partial program \#2: \hfil} +\line{\ibox{1cm}{\tt text}\ibox{1.5cm}{\tt data}\ibox{1cm}{\tt bss}\hfil} +\line{\boxit{1cm}{\tt TTT}\boxit{1.5cm}{\tt DDDD}\boxit{1cm}{\tt 000}\hfil} + +\line{\it linked program: \hfil} +\line{\ibox{.5cm}{}\ibox{1cm}{\tt text}\ibox{2.5cm}{}\ibox{.75cm}{}\ibox{2cm}{\tt data}\ibox{1.5cm}{}\ibox{2cm}{\tt bss}\hfil} +\line{\boxit{.5cm}{}\boxit{1cm}{\tt TTT}\boxit{2.5cm}{\tt +ttttt}\boxit{.75cm}{}\boxit{2cm}{\tt dddd}\boxit{1.5cm}{\tt +DDDD}\boxit{2cm}{\tt 00000}\ \dots\hfil} + +\line{\it addresses: \hfil} +\line{0\dots\hfil} + +@end tex +@c END TEXI2ROFF-KILL + +@node _AS__ Sections, Sub-Sections, _LD__ Sections, Sections +@section _AS__ Internal Sections + +@cindex internal @code{_AS__} sections +@cindex sections in messages, internal +These sections are meant only for the internal use of @code{_AS__}. They +have no meaning at run-time. You don't really need to know about these +sections for most purposes; but they can be mentioned in @code{_AS__} +warning messages, so it might be helpful to have an idea of their +meanings to @code{_AS__}. These sections are used to permit the +value of every expression in your assembly language program to be a +section-relative address. + +@table @b +@item absent +@cindex absent (internal section) +An expression was expected and none was found. + +@item ASSEMBLER-INTERNAL-LOGIC-ERROR! +@cindex assembler internal logic error +An internal assembler logic error has been found. This means there is a +bug in the assembler. + +@item bignum/flonum +@cindex bignum/flonum (internal section) +If a number can't be written as a C @code{int} constant (a bignum or a +flonum, but not an integer), it is recorded as belonging to this +``section''. @code{_AS__} has to remember that a flonum or a bignum +does not fit into 32 bits, and cannot be an argument (@pxref{Arguments}) +in an expression: this is done by making a flonum or bignum be in a +separate internal section. This is purely for internal @code{_AS__} +convenience; bignum/flonum section behaves similarly to absolute +section. + +@item pass1 section +@cindex pass1 (internal section) +The expression was impossible to evaluate in the first pass. The +assembler will attempt a second pass (second reading of the source) to +evaluate the expression. Your expression mentioned an undefined symbol +in a way that defies the one-pass (section + offset in section) assembly +process. No compiler need emit such an expression. + +@quotation +@emph{Warning:} the second pass is currently not implemented. @code{_AS__} +will abort with an error message if one is required. +@end quotation + +@item difference section +@cindex difference (internal section) +As an assist to the C compiler, expressions of the forms +@display + (@var{undefined symbol}) @minus{} (@var{expression}) + @var{something} @minus{} (@var{undefined symbol}) + (@var{undefined symbol}) @minus{} (@var{undefined symbol}) +@end display + +are permitted, and belong to the difference section. @code{_AS__} +re-evaluates such expressions after the source file has been read and +the symbol table built. If by that time there are no undefined symbols +in the expression then the expression assumes a new section. The +intention is to permit statements like +@samp{.word label - base_of_table} +to be assembled in one pass where both @code{label} and +@code{base_of_table} are undefined. This is useful for compiling C and +Algol switch statements, Pascal case statements, FORTRAN computed goto +statements and the like. +@c FIXME item debug +@c FIXME item transfer[t] vector preload +@c FIXME item transfer[t] vector postload +@c FIXME item register +@end table + +@node Sub-Sections, bss, _AS__ Sections, Sections +@section Sub-Sections + +@cindex numbered subsections +@cindex grouping data +_if__(_AOUT__||_BOUT__) +Assembled bytes +_if__(_COFF__) +conventionally +_fi__(_COFF__) +fall into two sections: text and data. +_fi__(_AOUT__||_BOUT__) +You may have separate groups of +_if__(_COFF__||_GENERIC__) +data in named sections +_fi__(_COFF__||_GENERIC__) +_if__((_AOUT__||_BOUT__)&&!_GENERIC__) +text or data +_fi__((_AOUT__||_BOUT__)&&!_GENERIC__) +that you want to end up near to each other in the object +file, even though they are not contiguous in the assembler source. +@code{_AS__} allows you to use @dfn{subsections} for this purpose. +Within each section, there can be numbered subsections with +values from 0 to 8192. Objects assembled into the same subsection will +be grouped with other objects in the same subsection when they are all +put into the object file. For example, a compiler might want to store +constants in the text section, but might not want to have them +interspersed with the program being assembled. In this case, the +compiler could issue a @samp{.text 0} before each section of code being +output, and a @samp{.text 1} before each group of constants being output. + +Subsections are optional. If you don't use subsections, everything +will be stored in subsection number zero. + +_if__(_GENERIC__) +Each subsection is zero-padded up to a multiple of four bytes. +(Subsections may be padded a different amount on different flavors +of @code{_AS__}.) +_fi__(_GENERIC__) +_if__(!_GENERIC__) +_if__(_H8__) +On the H8/300 platform, each subsection is zero-padded to a word +boundary (two bytes). +_fi__(_H8__) +_if__(_I960__) +@c FIXME section padding (alignment)? +@c Rich Pixley says padding here depends on target obj code format; that +@c doesn't seem particularly useful to say without further elaboration, +@c so for now I say nothing about it. If this is a generic BFD issue, +@c these paragraphs might need to vanish from this manual, and be +@c discussed in BFD chapter of binutils (or some such). +_fi__(_I960__) +_if__(_A29K__) +On the AMD 29K family, no particular padding is added to section or +subsection sizes; _AS__ forces no alignment on this platform. +_fi__(_A29K__) +_fi__(!_GENERIC__) + +Subsections appear in your object file in numeric order, lowest numbered +to highest. (All this to be compatible with other people's assemblers.) +The object file contains no representation of subsections; @code{_LD__} and +other programs that manipulate object files will see no trace of them. +They just see all your text subsections as a text section, and all your +data subsections as a data section. + +To specify which subsection you want subsequent statements assembled +into, use a numeric argument to specify it, in a @samp{.text +@var{expression}} or a @samp{.data @var{expression}} statement. +_if__(_COFF__) +_if__(_GENERIC__) +When generating COFF output, you +_fi__(_GENERIC__) +_if__(!_GENERIC__) +You +_fi__(!_GENERIC__) +can also use an extra subsection +argument with arbitrary named sections: @samp{.section @var{name}, +@var{expression}}. +_fi__(_COFF__) +@var{Expression} should be an absolute expression. +(@xref{Expressions}.) If you just say @samp{.text} then @samp{.text 0} +is assumed. Likewise @samp{.data} means @samp{.data 0}. Assembly +begins in @code{text 0}. For instance: +@smallexample +.text 0 # The default subsection is text 0 anyway. +.ascii "This lives in the first text subsection. *" +.text 1 +.ascii "But this lives in the second text subsection." +.data 0 +.ascii "This lives in the data section," +.ascii "in the first data subsection." +.text 0 +.ascii "This lives in the first text section," +.ascii "immediately following the asterisk (*)." +@end smallexample + +Each section has a @dfn{location counter} incremented by one for every +byte assembled into that section. Because subsections are merely a +convenience restricted to @code{_AS__} there is no concept of a subsection +location counter. There is no way to directly manipulate a location +counter---but the @code{.align} directive will change it, and any label +definition will capture its current value. The location counter of the +section that statements are being assembled into is said to be the +@dfn{active} location counter. + +@node bss, , Sub-Sections, Sections +@section bss Section + +@cindex bss section +@cindex common variable storage +The bss section is used for local common variable storage. +You may allocate address space in the bss section, but you may +not dictate data to load into it before your program executes. When +your program starts running, all the contents of the bss +section are zeroed bytes. + +Addresses in the bss section are allocated with special directives; you +may not assemble anything directly into the bss section. Hence there +are no bss subsections. @xref{Comm,,@code{.comm}}, +@pxref{Lcomm,,@code{.lcomm}}. + +@node Symbols, Expressions, Sections, Top +@chapter Symbols + +@cindex symbols +Symbols are a central concept: the programmer uses symbols to name +things, the linker uses symbols to link, and the debugger uses symbols +to debug. + +@quotation +@cindex debuggers, and symbol order +@emph{Warning:} @code{_AS__} does not place symbols in the object file in +the same order they were declared. This may break some debuggers. +@end quotation + +@menu +* Labels:: Labels +* Setting Symbols:: Giving Symbols Other Values +* Symbol Names:: Symbol Names +* Dot:: The Special Dot Symbol +* Symbol Attributes:: Symbol Attributes +@end menu + +@node Labels, Setting Symbols, Symbols, Symbols +@section Labels + +@cindex labels +A @dfn{label} is written as a symbol immediately followed by a colon +@samp{:}. The symbol then represents the current value of the +active location counter, and is, for example, a suitable instruction +operand. You are warned if you use the same symbol to represent two +different locations: the first definition overrides any other +definitions. + +@node Setting Symbols, Symbol Names, Labels, Symbols +@section Giving Symbols Other Values + +@cindex assigning values to symbols +@cindex symbol values, assigning +A symbol can be given an arbitrary value by writing a symbol, followed +by an equals sign @samp{=}, followed by an expression +(@pxref{Expressions}). This is equivalent to using the @code{.set} +directive. @xref{Set,,@code{.set}}. + +@node Symbol Names, Dot, Setting Symbols, Symbols +@section Symbol Names + +@cindex symbol names +@cindex names, symbol +Symbol names begin with a letter or with one of +_if__(!_H8__) +@samp{_.$} +_fi__(!_H8__) +_if__(_H8__) +@samp{_.} +_if__(_GENERIC__) +(On most machines, you can also use @code{$} in symbol names; exceptions +are noted in @ref{_MACH_DEP__}.) +_fi__(_GENERIC__) +_fi__(_H8__) +That character may be followed by any string of digits, letters, +_if__(!_H8__) +underscores and dollar signs. +_fi__(!_H8__) +_if__(_H8__) +_if__(_GENERIC__) +dollar signs (unless otherwise noted in @ref{_MACH_DEP__}), +_fi__(_GENERIC__) +and underscores. +_fi__(_H8__) +Case of letters is significant: +@code{foo} is a different symbol name than @code{Foo}. + +_if__(_A29K__) +For the AMD 29K family, @samp{?} is also allowed in the +body of a symbol name, though not at its beginning. +_fi__(_A29K__) + +Each symbol has exactly one name. Each name in an assembly language +program refers to exactly one symbol. You may use that symbol name any +number of times in a program. + +@subheading Local Symbol Names + +@cindex local symbol names +@cindex symbol names, local +@cindex temporary symbol names +@cindex symbol names, temporary +Local symbols help compilers and programmers use names temporarily. +There are ten local symbol names, which are re-used throughout the +program. You may refer to them using the names @samp{0} @samp{1} +@dots{} @samp{9}. To define a local symbol, write a label of the form +@samp{@b{N}:} (where @b{N} represents any digit). To refer to the most +recent previous definition of that symbol write @samp{@b{N}b}, using the +same digit as when you defined the label. To refer to the next +definition of a local label, write @samp{@b{N}f}---where @b{N} gives you +a choice of 10 forward references. The @samp{b} stands for +``backwards'' and the @samp{f} stands for ``forwards''. + +Local symbols are not emitted by the current GNU C compiler. + +There is no restriction on how you can use these labels, but +remember that at any point in the assembly you can refer to at most +10 prior local labels and to at most 10 forward local labels. + +Local symbol names are only a notation device. They are immediately +transformed into more conventional symbol names before the assembler +uses them. The symbol names stored in the symbol table, appearing in +error messages and optionally emitted to the object file have these +parts: + +@table @code +@item L +All local labels begin with @samp{L}. Normally both @code{_AS__} and +@code{_LD__} forget symbols that start with @samp{L}. These labels are +used for symbols you are never intended to see. If you give the +@samp{-L} option then @code{_AS__} will retain these symbols in the +object file. If you also instruct @code{_LD__} to retain these symbols, +you may use them in debugging. + +@item @var{digit} +If the label is written @samp{0:} then the digit is @samp{0}. +If the label is written @samp{1:} then the digit is @samp{1}. +And so on up through @samp{9:}. + +@item @ctrl{A} +This unusual character is included so you don't accidentally invent +a symbol of the same name. The character has ASCII value +@samp{\001}. + +@item @emph{ordinal number} +This is a serial number to keep the labels distinct. The first +@samp{0:} gets the number @samp{1}; The 15th @samp{0:} gets the +number @samp{15}; @emph{etc.}. Likewise for the other labels @samp{1:} +through @samp{9:}. +@end table + +For instance, the first @code{1:} is named @code{L1@ctrl{A}1}, the 44th +@code{3:} is named @code{L3@ctrl{A}44}. + +@node Dot, Symbol Attributes, Symbol Names, Symbols +@section The Special Dot Symbol + +@cindex dot (symbol) +@cindex @code{.} (symbol) +@cindex current address +@cindex location counter +The special symbol @samp{.} refers to the current address that +@code{_AS__} is assembling into. Thus, the expression @samp{melvin: +.long .} will cause @code{melvin} to contain its own address. +Assigning a value to @code{.} is treated the same as a @code{.org} +directive. Thus, the expression @samp{.=.+4} is the same as saying +_if__(!_A29K__) +@samp{.space 4}. +_fi__(!_A29K__) +_if__(_A29K__) +@samp{.block 4}. +_fi__(_A29K__) + +@node Symbol Attributes, , Dot, Symbols +@section Symbol Attributes + +@cindex symbol attributes +@cindex attributes, symbol +Every symbol has, as well as its name, the attributes ``Value'' and +``Type''. Depending on output format, symbols can also have auxiliary +attributes. +_if__(_INTERNALS__) +The detailed definitions are in _0__<a.out.h>_1__. +_fi__(_INTERNALS__) + +If you use a symbol without defining it, @code{_AS__} assumes zero for +all these attributes, and probably won't warn you. This makes the +symbol an externally defined symbol, which is generally what you +would want. + +@menu +* Symbol Value:: Value +* Symbol Type:: Type +_if__(_AOUT__||_BOUT__) +_if__(_GENERIC__||!_BOUT__) +* a.out Symbols:: Symbol Attributes: @code{a.out} +_fi__(_GENERIC__||!_BOUT__) +_if__(_BOUT__&&!_GENERIC__) +* a.out Symbols:: Symbol Attributes: @code{a.out}, @code{b.out} +_fi__(_BOUT__&&!_GENERIC__) +_fi__(_AOUT__||_BOUT__) +_if__(_COFF__) +* COFF Symbols:: Symbol Attributes for COFF +_fi__(_COFF__) +@end menu + +@node Symbol Value, Symbol Type, Symbol Attributes, Symbol Attributes +@subsection Value + +@cindex value of a symbol +@cindex symbol value +The value of a symbol is (usually) 32 bits. For a symbol which labels a +location in the text, data, bss or absolute sections the value is the +number of addresses from the start of that section to the label. +Naturally for text, data and bss sections the value of a symbol changes +as @code{_LD__} changes section base addresses during linking. Absolute +symbols' values do not change during linking: that is why they are +called absolute. + +The value of an undefined symbol is treated in a special way. If it is +0 then the symbol is not defined in this assembler source program, and +@code{_LD__} will try to determine its value from other programs it is +linked with. You make this kind of symbol simply by mentioning a symbol +name without defining it. A non-zero value represents a @code{.comm} +common declaration. The value is how much common storage to reserve, in +bytes (addresses). The symbol refers to the first address of the +allocated storage. + +_if__(!(_AOUT__||_BOUT__)) +@node Symbol Type, COFF Symbols, Symbol Value, Symbol Attributes +_fi__(!(_AOUT__||_BOUT__)) +_if__((_AOUT__||_BOUT__)) +@node Symbol Type, a.out Symbols, Symbol Value, Symbol Attributes +_fi__((_AOUT__||_BOUT__)) +@subsection Type + +@cindex type of a symbol +@cindex symbol type +The type attribute of a symbol contains relocation (section) +information, any flag settings indicating that a symbol is external, and +(optionally), other information for linkers and debuggers. The exact +format depends on the object-code output format in use. + +_if__(_AOUT__||_BOUT__) +_if__(_COFF__) +@node a.out Symbols, COFF Symbols, Symbol Type, Symbol Attributes +_fi__(_COFF__) +_if__(!_COFF__) +@node a.out Symbols, , Symbol Type, Symbol Attributes +_fi__(!_COFF__) +_if__(_BOUT__&&!_GENERIC__) +@subsection Symbol Attributes: @code{a.out}, @code{b.out} + +@cindex @code{b.out} symbol attributes +@cindex symbol attributes, @code{b.out} +These symbol attributes appear only when @code{_AS__} is configured for +one of the Berkeley-descended object output formats. +_fi__(_BOUT__&&!_GENERIC__) +_if__(_GENERIC__||!_BOUT__) +@subsection Symbol Attributes: @code{a.out} +_fi__(_GENERIC__||!_BOUT__) + +@cindex @code{a.out} symbol attributes +@cindex symbol attributes, @code{a.out} + +@menu +* Symbol Desc:: Descriptor +* Symbol Other:: Other +@end menu + +@node Symbol Desc, Symbol Other, a.out Symbols, a.out Symbols +@subsubsection Descriptor + +@cindex descriptor, of @code{a.out} symbol +This is an arbitrary 16-bit value. You may establish a symbol's +descriptor value by using a @code{.desc} statement +(@pxref{Desc,,@code{.desc}}). A descriptor value means nothing to +@code{_AS__}. + +@node Symbol Other, , Symbol Desc, a.out Symbols +@subsubsection Other + +@cindex other attribute, of @code{a.out} symbol +This is an arbitrary 8-bit value. It means nothing to @code{_AS__}. +_fi__(_AOUT__||_BOUT__) + +_if__(_COFF__) +_if__(!(_AOUT__||_BOUT__)) +@node COFF Symbols, , Symbol Type, Symbol Attributes +_fi__(!(_AOUT__||_BOUT__)) +_if__(_AOUT__||_BOUT__) +@node COFF Symbols, , a.out Symbols, Symbol Attributes +_fi__(_AOUT__||_BOUT__) +@subsection Symbol Attributes for COFF + +@cindex COFF symbol attributes +@cindex symbol attributes, COFF + +The COFF format supports a multitude of auxiliary symbol attributes; +like the primary symbol attributes, they are set between @code{.def} and +@code{.endef} directives. + +@subsubsection Primary Attributes + +@cindex primary attributes, COFF symbols +The symbol name is set with @code{.def}; the value and type, +respectively, with @code{.val} and @code{.type}. + +@subsubsection Auxiliary Attributes + +@cindex auxiliary attributes, COFF symbols +The @code{_AS__} directives @code{.dim}, @code{.line}, @code{.scl}, +@code{.size}, and @code{.tag} can generate auxiliary symbol table +information for COFF. +_fi__(_COFF__) + +@node Expressions, Pseudo Ops, Symbols, Top +@chapter Expressions + +@cindex expressions +@cindex addresses +@cindex numeric values +An @dfn{expression} specifies an address or numeric value. +Whitespace may precede and/or follow an expression. + +@menu +* Empty Exprs:: Empty Expressions +* Integer Exprs:: Integer Expressions +@end menu + +@node Empty Exprs, Integer Exprs, Expressions, Expressions +@section Empty Expressions + +@cindex empty expressions +@cindex expressions, empty +An empty expression has no value: it is just whitespace or null. +Wherever an absolute expression is required, you may omit the +expression and @code{_AS__} will assume a value of (absolute) 0. This +is compatible with other assemblers. + +@node Integer Exprs, , Empty Exprs, Expressions +@section Integer Expressions + +@cindex integer expressions +@cindex expressions, integer +An @dfn{integer expression} is one or more @emph{arguments} delimited +by @emph{operators}. + +@menu +* Arguments:: Arguments +* Operators:: Operators +* Prefix Ops:: Prefix Operators +* Infix Ops:: Infix Operators +@end menu + +@node Arguments, Operators, Integer Exprs, Integer Exprs +@subsection Arguments + +@cindex expression arguments +@cindex arguments in expressions +@cindex operands in expressions +@cindex arithmetic operands +@dfn{Arguments} are symbols, numbers or subexpressions. In other +contexts arguments are sometimes called ``arithmetic operands''. In +this manual, to avoid confusing them with the ``instruction operands'' of +the machine language, we use the term ``argument'' to refer to parts of +expressions only, reserving the word ``operand'' to refer only to machine +instruction operands. + +Symbols are evaluated to yield @{@var{section} @var{NNN}@} where +@var{section} is one of text, data, bss, absolute, +or undefined. @var{NNN} is a signed, 2's complement 32 bit +integer. + +Numbers are usually integers. + +A number can be a flonum or bignum. In this case, you are warned +that only the low order 32 bits are used, and @code{_AS__} pretends +these 32 bits are an integer. You may write integer-manipulating +instructions that act on exotic constants, compatible with other +assemblers. + +@cindex subexpressions +Subexpressions are a left parenthesis @samp{(} followed by an integer +expression, followed by a right parenthesis @samp{)}; or a prefix +operator followed by an argument. + +@node Operators, Prefix Ops, Arguments, Integer Exprs +@subsection Operators + +@cindex operators, in expressions +@cindex arithmetic functions +@cindex functions, in expressions +@dfn{Operators} are arithmetic functions, like @code{+} or @code{%}. Prefix +operators are followed by an argument. Infix operators appear +between their arguments. Operators may be preceded and/or followed by +whitespace. + +@node Prefix Ops, Infix Ops, Operators, Integer Exprs +@subsection Prefix Operator + +@cindex prefix operators +@code{_AS__} has the following @dfn{prefix operators}. They each take +one argument, which must be absolute. + +@c the tex/end tex stuff surrounding this small table is meant to make +@c it align, on the printed page, with the similar table in the next +@c section (which is inside an enumerate). +@tex +\global\advance\leftskip by \itemindent +@end tex + +@table @code +@item - +@dfn{Negation}. Two's complement negation. +@item ~ +@dfn{Complementation}. Bitwise not. +@end table + +@tex +\global\advance\leftskip by -\itemindent +@end tex + +@node Infix Ops, , Prefix Ops, Integer Exprs +@subsection Infix Operators + +@cindex infix operators +@cindex operators, permitted arguments +@dfn{Infix operators} take two arguments, one on either side. Operators +have precedence, but operations with equal precedence are performed left +to right. Apart from @code{+} or @code{-}, both arguments must be +absolute, and the result is absolute. + +@enumerate +@cindex operator precedence +@cindex precedence of operators + +@item +Highest Precedence + +@table @code +@item * +@dfn{Multiplication}. + +@item / +@dfn{Division}. Truncation is the same as the C operator @samp{/} + +@item % +@dfn{Remainder}. + +@item _0__<_1__ +@itemx _0__<<_1__ +@dfn{Shift Left}. Same as the C operator @samp{_0__<<_1__} + +@item _0__>_1__ +@itemx _0__>>_1__ +@dfn{Shift Right}. Same as the C operator @samp{_0__>>_1__} +@end table + +@item +Intermediate precedence + +@table @code +@item | + +@dfn{Bitwise Inclusive Or}. + +@item & +@dfn{Bitwise And}. + +@item ^ +@dfn{Bitwise Exclusive Or}. + +@item ! +@dfn{Bitwise Or Not}. +@end table + +@item +Lowest Precedence + +@table @code +@item + +@cindex addition, permitted arguments +@cindex plus, permitted arguments +@cindex arguments for addition +@dfn{Addition}. If either argument is absolute, the result +has the section of the other argument. +If either argument is pass1 or undefined, the result is pass1. +Otherwise @code{+} is illegal. + +@item - +@cindex subtraction, permitted arguments +@cindex minus, permitted arguments +@cindex arguments for subtraction +@dfn{Subtraction}. If the right argument is absolute, the +result has the section of the left argument. +If either argument is pass1 the result is pass1. +If either argument is undefined the result is difference section. +If both arguments are in the same section, the result is absolute---provided +that section is one of text, data or bss. +Otherwise subtraction is illegal. +@end table +@end enumerate + +The sense of the rule for addition is that it's only meaningful to add +the @emph{offsets} in an address; you can only have a defined section in +one of the two arguments. + +Similarly, you can't subtract quantities from two different sections. + +@node Pseudo Ops, _MACH_DEP__, Expressions, Top +@chapter Assembler Directives + +@cindex directives, machine independent +@cindex pseudo-ops, machine independent +@cindex machine independent directives +All assembler directives have names that begin with a period (@samp{.}). +The rest of the name is letters, usually in lower case. + +This chapter discusses directives present regardless of the target +machine configuration for the GNU assembler. +_if__(!_H8__) +@xref{_MACH_DEP__} for additional directives. +_fi__(!_H8__) + +@menu +* Abort:: @code{.abort} +_if__(_COFF__) +* coff-ABORT:: @code{.ABORT} +_fi__(_COFF__) +_if__(_BOUT__&&!_COFF__) +* bout-ABORT:: @code{.ABORT} +_fi__(_BOUT__&&!_COFF__) +* Align:: @code{.align @var{abs-expr} , @var{abs-expr}} +* App-File:: @code{.app-file @var{string}} +* Ascii:: @code{.ascii "@var{string}"}@dots{} +* Asciz:: @code{.asciz "@var{string}"}@dots{} +* Byte:: @code{.byte @var{expressions}} +* Comm:: @code{.comm @var{symbol} , @var{length} } +* Data:: @code{.data @var{subsection}} +_if__(_COFF__||_BOUT__) +* Def:: @code{.def @var{name}} +_fi__(_COFF__||_BOUT__) +_if__(_AOUT__||_BOUT__) +* Desc:: @code{.desc @var{symbol}, @var{abs-expression}} +_fi__(_AOUT__||_BOUT__) +_if__(_COFF__||_BOUT__) +* Dim:: @code{.dim} +_fi__(_COFF__||_BOUT__) +* Double:: @code{.double @var{flonums}} +* Eject:: @code{.eject} +* Else:: @code{.else} +_if__(_COFF__||_BOUT__) +* Endef:: @code{.endef} +_fi__(_COFF__||_BOUT__) +* Endif:: @code{.endif} +* Equ:: @code{.equ @var{symbol}, @var{expression}} +* Extern:: @code{.extern} +_if__(_GENERIC__||!_A29K__) +* File:: @code{.file @var{string}} +_fi__(_GENERIC__||!_A29K__) +* Fill:: @code{.fill @var{repeat} , @var{size} , @var{value}} +* Float:: @code{.float @var{flonums}} +* Global:: @code{.global @var{symbol}}, @code{.globl @var{symbol}} +* hword:: @code{.hword @var{expressions}} +* Ident:: @code{.ident} +* If:: @code{.if @var{absolute expression}} +* Include:: @code{.include "@var{file}"} +* Int:: @code{.int @var{expressions}} +* Lcomm:: @code{.lcomm @var{symbol} , @var{length}} +* Lflags:: @code{.lflags} +_if__(_GENERIC__||!_A29K__) +* Line:: @code{.line @var{line-number}} +_fi__(_GENERIC__||!_A29K__) +* Ln:: @code{.ln @var{line-number}} +* List:: @code{.list} +* Long:: @code{.long @var{expressions}} +* Lsym:: @code{.lsym @var{symbol}, @var{expression}} +* Nolist:: @code{.nolist} +* Octa:: @code{.octa @var{bignums}} +* Org:: @code{.org @var{new-lc} , @var{fill}} +* Psize:: @code{.psize @var{lines}, @var{columns}} +* Quad:: @code{.quad @var{bignums}} +* Sbttl:: @code{.sbttl "@var{subheading}"} +_if__(_COFF__||_BOUT__) +* Scl:: @code{.scl @var{class}} +_fi__(_COFF__||_BOUT__) +_if__(_COFF__) +* Section:: @code{.section @var{name}, @var{subsection}} +_fi__(_COFF__) +* Set:: @code{.set @var{symbol}, @var{expression}} +* Short:: @code{.short @var{expressions}} +* Single:: @code{.single @var{flonums}} +_if__(_COFF__||_BOUT__) +* Size:: @code{.size} +_fi__(_COFF__||_BOUT__) +* Space:: @code{.space @var{size} , @var{fill}} +_if__(_GENERIC__||!_H8__) +* Stab:: @code{.stabd, .stabn, .stabs} +_fi__(_GENERIC__||!_H8__) +_if__(_COFF__||_BOUT__) +* Tag:: @code{.tag @var{structname}} +_fi__(_COFF__||_BOUT__) +* Text:: @code{.text @var{subsection}} +* Title:: @code{.title "@var{heading}"} +_if__(_COFF__||_BOUT__) +* Type:: @code{.type @var{int}} +* Val:: @code{.val @var{addr}} +_fi__(_COFF__||_BOUT__) +* Word:: @code{.word @var{expressions}} +* Deprecated:: Deprecated Directives +@end menu + +_if__(_COFF__) +@node Abort, coff-ABORT, Pseudo Ops, Pseudo Ops +_fi__(_COFF__) +_if__((!_COFF__) && _BOUT__) +@node Abort, bout-ABORT, Pseudo Ops, Pseudo Ops +_fi__((!_COFF__) && _BOUT__) +_if__(! (_BOUT__ || _COFF__) ) +@node Abort, Align, Pseudo Ops, Pseudo Ops +_fi__(! (_BOUT__ || _COFF__) ) +@section @code{.abort} + +@cindex @code{abort} directive +@cindex stopping the assembly +This directive stops the assembly immediately. It is for +compatibility with other assemblers. The original idea was that the +assembly language source would be piped into the assembler. If the sender +of the source quit, it could use this directive tells @code{_AS__} to +quit also. One day @code{.abort} will not be supported. + +_if__(_COFF__) +@node coff-ABORT, Align, Abort, Pseudo Ops +@section @code{.ABORT} + +@cindex @code{ABORT} directive +When producing COFF output, @code{_AS__} accepts this directive as a +synonym for @samp{.abort}. +_fi__(_COFF__) + +_if__(_BOUT__) +_if__(!_COFF__) +@node bout-ABORT, Align, Abort, Pseudo Ops +@section @code{.ABORT} + +@cindex @code{ABORT} directive +_fi__(!_COFF__) + +When producing @code{b.out} output, @code{_AS__} accepts this directive, +but ignores it. +_fi__(_BOUT__) + +_if__( ! (_COFF__ || _BOUT__) ) +@node Align, App-File, Abort, Pseudo Ops +_fi__( ! (_COFF__ || _BOUT__) ) +_if__( _COFF__) +@node Align, App-File, coff-ABORT, Pseudo Ops +_fi__( _COFF__) +_if__( _BOUT__ && (! _COFF__)) +@node Align, App-File, bout-ABORT, Pseudo Ops +_fi__( _BOUT__ && (! _COFF__)) +@section @code{.align @var{abs-expr} , @var{abs-expr}} + +@cindex padding the location counter +@cindex advancing location counter +@cindex location counter, advancing +@cindex @code{align} directive +Pad the location counter (in the current subsection) to a particular +storage boundary. The first expression (which must be absolute) is the +number of low-order zero bits the location counter will have after +advancement. For example @samp{.align 3} will advance the location +counter until it a multiple of 8. If the location counter is already a +multiple of 8, no change is needed. + +The second expression (also absolute) gives the value to be stored in +the padding bytes. It (and the comma) may be omitted. If it is +omitted, the padding bytes are zero. + +@node App-File, Ascii, Align, Pseudo Ops +@section @code{.app-file @var{string}} + +@cindex logical file name +@cindex file name, logical +@cindex @code{app-file} directive +@code{.app-file} +_if__(!_A29K__) +(which may also be spelled @samp{.file}) +_fi__(!_A29K__) +tells @code{_AS__} that we are about to start a new +logical file. @var{string} is the new file name. In general, the +filename is recognized whether or not it is surrounded by quotes @samp{"}; +but if you wish to specify an empty file name is permitted, +you must give the quotes--@code{""}. This statement may go away in +future: it is only recognized to be compatible with old @code{_AS__} +programs.@refill + +@node Ascii, Asciz, App-File, Pseudo Ops +@section @code{.ascii "@var{string}"}@dots{} + +@cindex @code{ascii} directive +@cindex string literals +@code{.ascii} expects zero or more string literals (@pxref{Strings}) +separated by commas. It assembles each string (with no automatic +trailing zero byte) into consecutive addresses. + +@node Asciz, Byte, Ascii, Pseudo Ops +@section @code{.asciz "@var{string}"}@dots{} + +@cindex @code{asciz} directive +@cindex zero-terminated strings +@cindex null-terminated strings +@code{.asciz} is just like @code{.ascii}, but each string is followed by +a zero byte. The ``z'' in @samp{.asciz} stands for ``zero''. + +@node Byte, Comm, Asciz, Pseudo Ops +@section @code{.byte @var{expressions}} + +@cindex @code{byte} directive +@cindex integers, one byte +@code{.byte} expects zero or more expressions, separated by commas. +Each expression is assembled into the next byte. + +@node Comm, Data, Byte, Pseudo Ops +@section @code{.comm @var{symbol} , @var{length} } + +@cindex @code{comm} directive +@cindex symbol, common +@code{.comm} declares a named common area in the bss section. Normally +@code{_LD__} reserves memory addresses for it during linking, so no partial +program defines the location of the symbol. Use @code{.comm} to tell +@code{_LD__} that it must be at least @var{length} bytes long. @code{_LD__} +will allocate space for each @code{.comm} symbol that is at least as +long as the longest @code{.comm} request in any of the partial programs +linked. @var{length} is an absolute expression. + +_if__(_COFF__ || _BOUT__) +@node Data, Def, Comm, Pseudo Ops +_fi__(_COFF__ || _BOUT__) +_if__(!(_COFF__ || _BOUT__) && _AOUT__) +@node Data, Desc, Comm, Pseudo Ops +_fi__(!(_COFF__ || _BOUT__) && _AOUT__) +_if__(! (_COFF__ || _BOUT__ || _AOUT__) ) +@c Well, this *might* happen... +@node Data, Double, Comm, Pseudo Ops +_fi__(! (_COFF__ || _BOUT__ || _AOUT__) ) +@section @code{.data @var{subsection}} + +@cindex @code{data} directive +@code{.data} tells @code{_AS__} to assemble the following statements onto the +end of the data subsection numbered @var{subsection} (which is an +absolute expression). If @var{subsection} is omitted, it defaults +to zero. + +_if__(_COFF__ || _BOUT__) +_if__(_AOUT__ || _BOUT__) +@node Def, Desc, Data, Pseudo Ops +_fi__(_AOUT__ || _BOUT__) +_if__(!(_AOUT__ || _BOUT__)) +@node Def, Dim, Data, Pseudo Ops +_fi__(!(_AOUT__ || _BOUT__)) +@section @code{.def @var{name}} + +@cindex @code{def} directive +@cindex COFF symbols, debugging +@cindex debugging COFF symbols +Begin defining debugging information for a symbol @var{name}; the +definition extends until the @code{.endef} directive is encountered. +_if__(_BOUT__) + +This directive is only observed when @code{_AS__} is configured for COFF +format output; when producing @code{b.out}, @samp{.def} is recognized, +but ignored. +_fi__(_BOUT__) +_fi__(_COFF__ || _BOUT__) + +_if__(_AOUT__||_BOUT__) +_if__(_COFF__||_BOUT__) +@node Desc, Dim, Def, Pseudo Ops +_fi__(_COFF__||_BOUT__) +_if__(!(_COFF__||_BOUT__)) +@node Desc, Double, Data, Pseudo Ops +_fi__(!(_COFF__||_BOUT__)) +@section @code{.desc @var{symbol}, @var{abs-expression}} + +@cindex @code{desc} directive +@cindex COFF symbol descriptor +@cindex symbol descriptor, COFF +This directive sets the descriptor of the symbol (@pxref{Symbol Attributes}) +to the low 16 bits of an absolute expression. + +_if__(_COFF__) +The @samp{.desc} directive is not available when @code{_AS__} is +configured for COFF output; it is only for @code{a.out} or @code{b.out} +object format. For the sake of compatibility, @code{_AS__} will accept +it, but produce no output, when configured for COFF. +_fi__(_COFF__) +_fi__(_AOUT__||_BOUT__) + +_if__(_COFF__ || _BOUT__) +_if__(_AOUT__ || _BOUT__) +@node Dim, Double, Desc, Pseudo Ops +_fi__(_AOUT__ || _BOUT__) +_if__(!(_AOUT__ || _BOUT__)) +@node Dim, Double, Def, Pseudo Ops +_fi__(!(_AOUT__ || _BOUT__)) +@section @code{.dim} + +@cindex @code{dim} directive +@cindex COFF auxiliary symbol information +@cindex auxiliary symbol information, COFF +This directive is generated by compilers to include auxiliary debugging +information in the symbol table. It is only permitted inside +@code{.def}/@code{.endef} pairs. +_if__(_BOUT__) + +@samp{.dim} is only meaningful when generating COFF format output; when +@code{_AS__} is generating @code{b.out}, it accepts this directive but +ignores it. +_fi__(_BOUT__) +_fi__(_COFF__ || _BOUT__) + +_if__(_COFF__||_BOUT__) +@node Double, Eject, Dim, Pseudo Ops +_fi__(_COFF__||_BOUT__) +_if__(!(_COFF__||_BOUT__)) +@node Double, Eject, Desc, Pseudo Ops +_fi__(!(_COFF__||_BOUT__)) +@section @code{.double @var{flonums}} + +@cindex @code{double} directive +@cindex floating point numbers (double) +@code{.double} expects zero or more flonums, separated by commas. It +assembles floating point numbers. +_if__(_GENERIC__) +The exact kind of floating point numbers emitted depends on how +@code{_AS__} is configured. @xref{_MACH_DEP__}. +_fi__(_GENERIC__) +_if__((!_GENERIC__) && _IEEEFLOAT__) +On the _HOST__ family @samp{.double} emits 64-bit floating-point numbers +in @sc{ieee} format. +_fi__((!_GENERIC__) && _IEEEFLOAT__) + +@node Eject, Else, Double, Pseudo Ops +@section @code{.eject} + +@cindex @code{eject} directive +@cindex new page, in listings +@cindex page, in listings +@cindex listing control: new page +Force a page break at this point, when generating assembly listings. + +_if__(_COFF__||_BOUT__) +@node Else, Endef, Eject, Pseudo Ops +_fi__(_COFF__||_BOUT__) +_if__(!(_COFF__||_BOUT__)) +@node Else, Endif, Eject, Pseudo Ops +_fi__(!(_COFF__||_BOUT__)) +@section @code{.else} + +@cindex @code{else} directive +@code{.else} is part of the @code{_AS__} support for conditional +assembly; @pxref{If,,@code{.if}}. It marks the beginning of a section +of code to be assembled if the condition for the preceding @code{.if} +was false. + +_if__(0) +@node End, Endef, Else, Pseudo Ops +@section @code{.end} + +@cindex @code{end} directive +This doesn't do anything---but isn't an s_ignore, so I suspect it's +meant to do something eventually (which is why it isn't documented here +as "for compatibility with blah"). +_fi__(0) + +_if__(_COFF__||_BOUT__) +@node Endef, Endif, Else, Pseudo Ops +@section @code{.endef} + +@cindex @code{endef} directive +This directive flags the end of a symbol definition begun with +@code{.def}. +_if__(_BOUT__) + +@samp{.endef} is only meaningful when generating COFF format output; if +@code{_AS__} is configured to generate @code{b.out}, it accepts this +directive but ignores it. +_fi__(_BOUT__) +_fi__(_COFF__||_BOUT__) + +_if__(_COFF__||_BOUT__) +@node Endif, Equ, Endef, Pseudo Ops +_fi__(_COFF__||_BOUT__) +_if__(!(_COFF__||_BOUT__)) +@node Endif, Equ, Else, Pseudo Ops +_fi__(!(_COFF__||_BOUT__)) +@section @code{.endif} + +@cindex @code{endif} directive +@code{.endif} is part of the @code{_AS__} support for conditional assembly; +it marks the end of a block of code that is only assembled +conditionally. @xref{If,,@code{.if}}. + +@node Equ, Extern, Endif, Pseudo Ops +@section @code{.equ @var{symbol}, @var{expression}} + +@cindex @code{equ} directive +@cindex assigning values to symbols +@cindex symbols, assigning values to +This directive sets the value of @var{symbol} to @var{expression}. +It is synonymous with @samp{.set}; @pxref{Set,,@code{.set}}. + +_if__(_GENERIC__||!_A29K__) +@node Extern, File, Equ, Pseudo Ops +_fi__(_GENERIC__||!_A29K__) +_if__(_A29K__&&!_GENERIC__) +@node Extern, Fill, Equ, Pseudo Ops +_fi__(_A29K__&&!_GENERIC__) +@section @code{.extern} + +@cindex @code{extern} directive +@code{.extern} is accepted in the source program---for compatibility +with other assemblers---but it is ignored. @code{_AS__} treats +all undefined symbols as external. + +_if__(_GENERIC__||!_A29K__) +@node File, Fill, Extern, Pseudo Ops +@section @code{.file @var{string}} + +@cindex @code{file} directive +@cindex logical file name +@cindex file name, logical +@code{.file} (which may also be spelled @samp{.app-file}) tells +@code{_AS__} that we are about to start a new logical file. +@var{string} is the new file name. In general, the filename is +recognized whether or not it is surrounded by quotes @samp{"}; but if +you wish to specify an empty file name, you must give the +quotes--@code{""}. This statement may go away in future: it is only +recognized to be compatible with old @code{_AS__} programs. +_if__(_A29K__) +In some configurations of @code{_AS__}, @code{.file} has already been +removed to avoid conflicts with other assemblers. @xref{_MACH_DEP__}. +_fi__(_A29K__) +_fi__(_GENERIC__||!_A29K__) + +_if__(_GENERIC__||!_A29K__) +@node Fill, Float, File, Pseudo Ops +_fi__(_GENERIC__||!_A29K__) +_if__(_A29K__&&!_GENERIC__) +@node Fill, Float, Extern, Pseudo Ops +_fi__(_A29K__&&!_GENERIC__) +@section @code{.fill @var{repeat} , @var{size} , @var{value}} + +@cindex @code{fill} directive +@cindex writing patterns in memory +@cindex patterns, writing in memory +@var{result}, @var{size} and @var{value} are absolute expressions. +This emits @var{repeat} copies of @var{size} bytes. @var{Repeat} +may be zero or more. @var{Size} may be zero or more, but if it is +more than 8, then it is deemed to have the value 8, compatible with +other people's assemblers. The contents of each @var{repeat} bytes +is taken from an 8-byte number. The highest order 4 bytes are +zero. The lowest order 4 bytes are @var{value} rendered in the +byte-order of an integer on the computer @code{_AS__} is assembling for. +Each @var{size} bytes in a repetition is taken from the lowest order +@var{size} bytes of this number. Again, this bizarre behavior is +compatible with other people's assemblers. + +@var{size} and @var{value} are optional. +If the second comma and @var{value} are absent, @var{value} is +assumed zero. If the first comma and following tokens are absent, +@var{size} is assumed to be 1. + +@node Float, Global, Fill, Pseudo Ops +@section @code{.float @var{flonums}} + +@cindex floating point numbers (single) +@cindex @code{float} directive +This directive assembles zero or more flonums, separated by commas. It +has the same effect as @code{.single}. +_if__(_GENERIC__) +The exact kind of floating point numbers emitted depends on how +@code{_AS__} is configured. +@xref{_MACH_DEP__}. +_fi__(_GENERIC__) +_if__((!_GENERIC__) && _IEEEFLOAT__) +On the _HOST__ family, @code{.float} emits 32-bit floating point numbers +in @sc{ieee} format. +_fi__((!_GENERIC__) && _IEEEFLOAT__) + +@node Global, hword, Float, Pseudo Ops +@section @code{.global @var{symbol}}, @code{.globl @var{symbol}} + +@cindex @code{global} directive +@cindex symbol, making visible to linker +@code{.global} makes the symbol visible to @code{_LD__}. If you define +@var{symbol} in your partial program, its value is made available to +other partial programs that are linked with it. Otherwise, +@var{symbol} will take its attributes from a symbol of the same name +from another partial program it is linked with. + +Both spellings (@samp{.globl} and @samp{.global}) are accepted, for +compatibility with other assemblers. + +_if__(_AOUT__||_BOUT__||_COFF__) +@node hword, Ident, Global, Pseudo Ops +_fi__(_AOUT__||_BOUT__||_COFF__) +_if__(!(_AOUT__||_BOUT__||_COFF__)) +@node hword, If, Global, Pseudo Ops +_fi__(!(_AOUT__||_BOUT__||_COFF__)) +@section @code{.hword @var{expressions}} + +@cindex @code{hword} directive +@cindex integers, 16-bit +@cindex numbers, 16-bit +@cindex sixteen bit integers +This expects zero or more @var{expressions}, and emits +a 16 bit number for each. + +_if__(_GENERIC__) +This directive is a synonym for @samp{.short}; depending on the target +architecture, it may also be a synonym for @samp{.word}. +_fi__(_GENERIC__) +_if__( _W32__ && !_GENERIC__ ) +This directive is a synonym for @samp{.short}. +_fi__( _W32__ && !_GENERIC__ ) +_if__(_W16__ && !_GENERIC__ ) +This directive is a synonym for both @samp{.short} and @samp{.word}. +_fi__(_W16__ && !_GENERIC__ ) + +_if__(_AOUT__||_BOUT__||_COFF__) +@node Ident, If, hword, Pseudo Ops +@section @code{.ident} + +@cindex @code{ident} directive +This directive is used by some assemblers to place tags in object files. +@code{_AS__} simply accepts the directive for source-file +compatibility with such assemblers, but does not actually emit anything +for it. +_fi__(_AOUT__||_BOUT__||_COFF__) + +_if__(_AOUT__||_BOUT__||_COFF__) +@node If, Include, Ident, Pseudo Ops +_fi__(_AOUT__||_BOUT__||_COFF__) +_if__(!(_AOUT__||_BOUT__||_COFF__)) +@node If, Include, hword, Pseudo Ops +_fi__(!(_AOUT__||_BOUT__||_COFF__)) +@section @code{.if @var{absolute expression}} + +@cindex conditional assembly +@cindex @code{if} directive +@code{.if} marks the beginning of a section of code which is only +considered part of the source program being assembled if the argument +(which must be an @var{absolute expression}) is non-zero. The end of +the conditional section of code must be marked by @code{.endif} +(@pxref{Endif,,@code{.endif}}); optionally, you may include code for the +alternative condition, flagged by @code{.else} (@pxref{Else,,@code{.else}}. + +The following variants of @code{.if} are also supported: +@table @code +@item .ifdef @var{symbol} +@cindex @code{ifdef} directive +Assembles the following section of code if the specified @var{symbol} +has been defined. + +_if__(0) +@item .ifeqs +@cindex @code{ifeqs} directive +Not yet implemented. +_fi__(0) + +@item .ifndef @var{symbol} +@itemx ifnotdef @var{symbol} +@cindex @code{ifndef} directive +@cindex @code{ifnotdef} directive +Assembles the following section of code if the specified @var{symbol} +has not been defined. Both spelling variants are equivalent. + +_if__(0) +@item ifnes +Not yet implemented. +_fi__(0) +@end table + +@node Include, Int, If, Pseudo Ops +@section @code{.include "@var{file}"} + +@cindex @code{include} directive +@cindex supporting files, including +@cindex files, including +This directive provides a way to include supporting files at specified +points in your source program. The code from @var{file} is assembled as +if it followed the point of the @code{.include}; when the end of the +included file is reached, assembly of the original file continues. You +can control the search paths used with the @samp{-I} command-line option +(@pxref{Invoking,,Command-Line Options}). Quotation marks are required +around @var{file}. + +@node Int, Lcomm, Include, Pseudo Ops +@section @code{.int @var{expressions}} + +@cindex @code{int} directive +_if__(_GENERIC__||!_H8__) +@cindex integers, 32-bit +_fi__(_GENERIC__||!_H8__) +Expect zero or more @var{expressions}, of any section, separated by +commas. For each expression, emit a +_if__(_GENERIC__||!_H8__) +32-bit +_fi__(_GENERIC__||!_H8__) +_if__(_H8__&&!_GENERIC__) +16-bit +_fi__(_H8__&&!_GENERIC__) +number that will, at run +time, be the value of that expression. The byte order of the +expression depends on what kind of computer will run the program. + +@node Lcomm, Lflags, Int, Pseudo Ops +@section @code{.lcomm @var{symbol} , @var{length}} + +@cindex @code{lcomm} directive +@cindex local common symbols +@cindex symbols, local common +Reserve @var{length} (an absolute expression) bytes for a local common +denoted by @var{symbol}. The section and value of @var{symbol} are +those of the new local common. The addresses are allocated in the bss +section, so at run-time the bytes will start off zeroed. @var{Symbol} +is not declared global (@pxref{Global,,@code{.global}}), so is normally +not visible to @code{_LD__}. + +_if__(_GENERIC__||(!_A29K__)) +@node Lflags, Line, Lcomm, Pseudo Ops +_fi__(_GENERIC__||(!_A29K__)) +_if__((!_GENERIC__)&& _A29K__) +@node Lflags, Ln, Lcomm, Pseudo Ops +_fi__((!_GENERIC__)&& _A29K__) +@section @code{.lflags} + +@cindex @code{lflags} directive (ignored) +@code{_AS__} accepts this directive, for compatibility with other +assemblers, but ignores it. + +_if__(_GENERIC__ || !_A29K__) +@node Line, Ln, Lflags, Pseudo Ops +@section @code{.line @var{line-number}} + +@cindex @code{line} directive +_fi__(_GENERIC__ || (!_A29K__)) +_if__(_A29K__ && (!_GENERIC__)) +@node Ln, List, Lflags, Pseudo Ops +@section @code{.ln @var{line-number}} + +@cindex @code{ln} directive +_fi__(_A29K__ && (!_GENERIC__)) +@cindex logical line number +_if__(_AOUT__||_BOUT__) +Tell @code{_AS__} to change the logical line number. @var{line-number} must be +an absolute expression. The next line will have that logical line +number. So any other statements on the current line (after a statement +separator +_if__(_GENERIC__) +character) +_fi__(_GENERIC__) +_if__(!_GENERIC__) +_if__(! (_A29K__||_H8__) ) +character @code{;}) +_fi__(! (_A29K__||_H8__) ) +_if__(_A29K__) +character @samp{@@}) +_fi__(_A29K__) +_if__(_H8__) +character @samp{$}) +_fi__(_H8__) +_fi__(!_GENERIC__) +will be reported as on logical line number +@var{line-number} @minus{} 1. +One day this directive will be unsupported: it is used only +for compatibility with existing assembler programs. @refill + +_if__(_GENERIC__ && _A29K__) +@emph{Warning:} In the AMD29K configuration of _AS__, this command is +only available with the name @code{.ln}, rather than as either +@code{.line} or @code{.ln}. +_fi__(_GENERIC__ && _A29K__) +_fi__(_AOUT__||_BOUT__) +_if__(_COFF__) + +Even though this is a directive associated with the @code{a.out} or +@code{b.out} object-code formats, @code{_AS__} will still recognize it +when producing COFF output, and will treat @samp{.line} as though it +were the COFF @samp{.ln} @emph{if} it is found outside a +@code{.def}/@code{.endef} pair. + +Inside a @code{.def}, @samp{.line} is, instead, one of the directives +used by compilers to generate auxiliary symbol information for +debugging. +_fi__(_COFF__) + +_if__(_AOUT__&&(_GENERIC__||!_A29K__)) +@node Ln, List, Line, Pseudo Ops +@section @code{.ln @var{line-number}} + +@cindex @code{ln} directive +@samp{.ln} is a synonym for @samp{.line}. +_fi__(_AOUT__&&(_GENERIC__||!_A29K__)) +_if__(_COFF__&&!_AOUT__) +@node Ln, List, Line, Pseudo Ops +@section @code{.ln @var{line-number}} + +@cindex @code{ln} directive +Tell @code{_AS__} to change the logical line number. @var{line-number} +must be an absolute expression. The next line will have that logical +line number, so any other statements on the current line (after a +statement separator character @code{;}) will be reported as on logical +line number @var{line-number} @minus{} 1. +_if__(_BOUT__) + +This directive is accepted, but ignored, when @code{_AS__} is configured for +@code{b.out}; its effect is only associated with COFF output format. +_fi__(_BOUT__) +_fi__(_COFF__&&!_AOUT__) + +@node List, Long, Ln, Pseudo Ops +@section @code{.list} + +@cindex @code{list} directive +@cindex listing control, turning on +Control (in conjunction with the @code{.nolist} directive) whether or +not assembly listings are generated. These two directives maintain an +internal counter (which is zero initially). @code{.list} increments the +counter, and @code{.nolist} decrements it. Assembly listings are +generated whenever the counter is greater than zero. + +By default, listings are disabled. When you enable them (with the +@samp{-a} command line option; @pxref{Invoking,,Command-Line Options}), +the initial value of the listing counter is one. + +@node Long, Lsym, List, Pseudo Ops +@section @code{.long @var{expressions}} + +@cindex @code{long} directive +@code{.long} is the same as @samp{.int}, @pxref{Int,,@code{.int}}. + +@node Lsym, Nolist, Long, Pseudo Ops +@section @code{.lsym @var{symbol}, @var{expression}} + +@cindex @code{lsym} directive +@cindex symbol, not referenced in assembly +@code{.lsym} creates a new symbol named @var{symbol}, but does not put it in +the hash table, ensuring it cannot be referenced by name during the +rest of the assembly. This sets the attributes of the symbol to be +the same as the expression value: +@smallexample +@var{other} = @var{descriptor} = 0 +@var{type} = @r{(section of @var{expression})} +@var{value} = @var{expression} +@end smallexample +@noindent +The new symbol is not flagged as external. + +@node Nolist, Octa, Lsym, Pseudo Ops +@section @code{.nolist} + +@cindex @code{nolist} directive +@cindex listing control, turning off +Control (in conjunction with the @code{.list} directive) whether or +not assembly listings are generated. These two directives maintain an +internal counter (which is zero initially). @code{.list} increments the +counter, and @code{.nolist} decrements it. Assembly listings are +generated whenever the counter is greater than zero. + +@node Octa, Org, Nolist, Pseudo Ops +@section @code{.octa @var{bignums}} + +@c FIXME: double size emitted for "octa" on i960, others? Or warn? +@cindex @code{octa} directive +@cindex integer, 16-byte +@cindex sixteen byte integer +This directive expects zero or more bignums, separated by commas. For each +bignum, it emits a 16-byte integer. + +The term ``octa'' comes from contexts in which a ``word'' is two bytes; +hence @emph{octa}-word for 16 bytes. + +@node Org, Psize, Octa, Pseudo Ops +@section @code{.org @var{new-lc} , @var{fill}} + +@cindex @code{org} directive +@cindex location counter, advancing +@cindex advancing location counter +@cindex current address, advancing +@code{.org} will advance the location counter of the current section to +@var{new-lc}. @var{new-lc} is either an absolute expression or an +expression with the same section as the current subsection. That is, +you can't use @code{.org} to cross sections: if @var{new-lc} has the +wrong section, the @code{.org} directive is ignored. To be compatible +with former assemblers, if the section of @var{new-lc} is absolute, +@code{_AS__} will issue a warning, then pretend the section of @var{new-lc} +is the same as the current subsection. + +@code{.org} may only increase the location counter, or leave it +unchanged; you cannot use @code{.org} to move the location counter +backwards. + +@c double negative used below "not undefined" because this is a specific +@c reference to "undefined" (as SEG_UNKNOWN is called in this manual) +@c section. pesch@cygnus.com 18feb91 +Because @code{_AS__} tries to assemble programs in one pass @var{new-lc} +may not be undefined. If you really detest this restriction we eagerly await +a chance to share your improved assembler. + +Beware that the origin is relative to the start of the section, not +to the start of the subsection. This is compatible with other +people's assemblers. + +When the location counter (of the current subsection) is advanced, the +intervening bytes are filled with @var{fill} which should be an +absolute expression. If the comma and @var{fill} are omitted, +@var{fill} defaults to zero. + +@node Psize, Quad, Org, Pseudo Ops +@section @code{.psize @var{lines} , @var{columns}} + +@cindex @code{psize} directive +@cindex listing control: paper size +@cindex paper size, for listings +Use this directive to declare the number of lines---and, optionally, the +number of columns---to use for each page, when generating listings. + +If you don't use @code{.psize}, listings will use a default line-count +of 60. You may omit the comma and @var{columns} specification; the +default width is 200 columns. + +@code{_AS__} will generate formfeeds whenever the specified number of +lines is exceeded (or whenever you explicitly request one, using +@code{.eject}). + +If you specify @var{lines} as @code{0}, no formfeeds are generated save +those explicitly specified with @code{.eject}. + +@node Quad, Sbttl, Psize, Pseudo Ops +@section @code{.quad @var{bignums}} + +@cindex @code{quad} directive +@code{.quad} expects zero or more bignums, separated by commas. For +each bignum, it emits +_if__(_GENERIC__||(!_I960__)) +an 8-byte integer. If the bignum won't fit in 8 +bytes, it prints a warning message; and just takes the lowest order 8 +bytes of the bignum.@refill +@cindex eight-byte integer +@cindex integer, 8-byte + +The term ``quad'' comes from contexts in which a ``word'' is two bytes; +hence @emph{quad}-word for 8 bytes. +_fi__(_GENERIC__||(!_I960__)) +_if__(_I960__&&(!_GENERIC__)) +a 16-byte integer. If the bignum won't fit in 16 bytes, it prints a +warning message; and just takes the lowest order 16 bytes of the +bignum.@refill +@cindex sixteen-byte integer +@cindex integer, 16-byte +_fi__(_I960__&&(!_GENERIC__)) + +_if__(_COFF__||_BOUT__) +@node Sbttl, Scl, Quad, Pseudo Ops +_fi__(_COFF__||_BOUT__) +_if__(!(_COFF__||_BOUT__)) +@node Sbttl, Set, Quad, Pseudo Ops +_fi__(!(_COFF__||_BOUT__)) +@section @code{.sbttl "@var{subheading}"} + +@cindex @code{sbttl} directive +@cindex subtitles for listings +@cindex listing control: subtitle +Use @var{subheading} as the title (third line, immediately after the +title line) when generating assembly listings. + +This directive affects subsequent pages, as well as the current page if +it appears within ten lines of the top of a page. + +_if__(_COFF__||_BOUT__) +_if__(!_COFF__) +@node Scl, Set, Sbttl, Pseudo Ops +_fi__(!_COFF__) +_if__(_COFF__) +@node Scl, Section, Sbttl, Pseudo Ops +_fi__(_COFF__) +@section @code{.scl @var{class}} + +@cindex @code{scl} directive +@cindex symbol storage class (COFF) +@cindex COFF symbol storage class +Set the storage-class value for a symbol. This directive may only be +used inside a @code{.def}/@code{.endef} pair. Storage class may flag +whether a symbol is static or external, or it may record further +symbolic debugging information. +_if__(_BOUT__) + +The @samp{.scl} directive is primarily associated with COFF output; when +configured to generate @code{b.out} output format, @code{_AS__} will +accept this directive but ignore it. +_fi__(_BOUT__) +_fi__(_COFF__||_BOUT__) + +_if__(_COFF__) +@node Section, Set, Scl, Pseudo Ops +@section @code{.section @var{name}, @var{subsection}} + +@cindex @code{section} directive +@cindex named section (COFF) +@cindex COFF named section +Assemble the following code into end of subsection numbered +@var{subsection} in the COFF named section @var{name}. If you omit +@var{subsection}, @code{_AS__} uses subsection number zero. +@samp{.section .text} is equivalent to the @code{.text} directive; +@samp{.section .data} is equivalent to the @code{.data} directive. + +@node Set, Short, Section, Pseudo Ops +_fi__(_COFF__) +_if__(_BOUT__&&!_COFF__) +@node Set, Short, Scl, Pseudo Ops +_fi__(_BOUT__&&!_COFF__) +_if__(!(_COFF__||_BOUT__)) +@node Set, Short, Quad, Pseudo Ops +_fi__(!(_COFF__||_BOUT__)) +@section @code{.set @var{symbol}, @var{expression}} + +@cindex @code{set} directive +@cindex symbol value, setting +This directive sets the value of @var{symbol} to @var{expression}. This +will change @var{symbol}'s value and type to conform to +@var{expression}. If @var{symbol} was flagged as external, it remains +flagged. (@xref{Symbol Attributes}.) + +You may @code{.set} a symbol many times in the same assembly. +If the expression's section is unknowable during pass 1, a second +pass over the source program will be forced. The second pass is +currently not implemented. @code{_AS__} will abort with an error +message if one is required. + +If you @code{.set} a global symbol, the value stored in the object +file is the last value stored into it. + +@node Short, Single, Set, Pseudo Ops +@section @code{.short @var{expressions}} + +@cindex @code{short} directive +_if__(_GENERIC__ || _W16__) +@code{.short} is the same as @samp{.word}. @xref{Word,,@code{.word}}. +_if__(_W32__) +In some configurations, however, @code{.short} and @code{.word} generate +numbers of different lengths; @pxref{_MACH_DEP__}. +_fi__(_W32__) +_fi__(_GENERIC__|| _W16__) +_if__((!_GENERIC__) && _W32__) +This expects zero or more @var{expressions}, and emits +a 16 bit number for each. +_fi__((!_GENERIC__) && _W32__) +_if__(_COFF__||_BOUT__) +@node Single, Size, Short, Pseudo Ops +_fi__(_COFF__||_BOUT__) +_if__(!(_COFF__||_BOUT__)) +@node Single, Space, Short, Pseudo Ops +_fi__(!(_COFF__||_BOUT__)) +@section @code{.single @var{flonums}} + +@cindex @code{single} directive +@cindex floating point numbers (single) +This directive assembles zero or more flonums, separated by commas. It +has the same effect as @code{.float}. +_if__(_GENERIC__) +The exact kind of floating point numbers emitted depends on how +@code{_AS__} is configured. @xref{_MACH_DEP__}. +_fi__(_GENERIC__) +_if__((!_GENERIC__) && _IEEEFLOAT__) +On the _HOST__ family, @code{.single} emits 32-bit floating point +numbers in @sc{ieee} format. +_fi__((!_GENERIC__) && _IEEEFLOAT__) + +_if__(_COFF__||_BOUT__) +@node Size, Space, Single, Pseudo Ops +@section @code{.size} + +@cindex @code{size} directive +This directive is generated by compilers to include auxiliary debugging +information in the symbol table. It is only permitted inside +@code{.def}/@code{.endef} pairs. +_if__(_BOUT__) + +@samp{.size} is only meaningful when generating COFF format output; when +@code{_AS__} is generating @code{b.out}, it accepts this directive but +ignores it. +_fi__(_BOUT__) +_fi__(_COFF__||_BOUT__) + +_if__(_H8__&&!_GENERIC__) +@node Space, Tag, Size, Pseudo Ops +_fi__(_H8__&&!_GENERIC__) +_if__(_GENERIC__||!_H8__) +_if__(_COFF__||_BOUT__) +@node Space, Stab, Size, Pseudo Ops +_fi__(_COFF__||_BOUT__) +_if__(!(_COFF__||_BOUT__)) +@node Space, Stab, Single, Pseudo Ops +_fi__(!(_COFF__||_BOUT__)) +_fi__(_GENERIC__||!_H8__) +_if__(_GENERIC__ || !_A29K__) +@section @code{.space @var{size} , @var{fill}} + +@cindex @code{space} directive +@cindex filling memory +This directive emits @var{size} bytes, each of value @var{fill}. Both +@var{size} and @var{fill} are absolute expressions. If the comma +and @var{fill} are omitted, @var{fill} is assumed to be zero. +_fi__(_GENERIC__ || !_A29K__) + +_if__(_A29K__) +@section @code{.space} + +@cindex @code{space} directive +On the AMD 29K, this directive is ignored; it is accepted for +compatibility with other AMD 29K assemblers. + +@quotation +@emph{Warning:} In other versions of the GNU assembler, the directive +@code{.space} has the effect of @code{.block} @xref{_MACH_DEP__}. +@end quotation +_fi__(_A29K__) + +_if__(_GENERIC__||!_H8__) +_if__(_AOUT__||_BOUT__||_COFF__) +_if__(_COFF__||_BOUT__) +@node Stab, Tag, Space, Pseudo Ops +_fi__(_COFF__||_BOUT__) +_if__(!(_COFF__||_BOUT__)) +@node Stab, Text, Space, Pseudo Ops +_fi__(!(_COFF__||_BOUT__)) +@section @code{.stabd, .stabn, .stabs} + +@cindex symbolic debuggers, information for +@cindex @code{stab@var{x}} directives +There are three directives that begin @samp{.stab}. +All emit symbols (@pxref{Symbols}), for use by symbolic debuggers. +The symbols are not entered in the @code{_AS__} hash table: they +cannot be referenced elsewhere in the source file. +Up to five fields are required: +@table @var +@item string +This is the symbol's name. It may contain any character except @samp{\000}, +so is more general than ordinary symbol names. Some debuggers used to +code arbitrarily complex structures into symbol names using this field. +@item type +An absolute expression. The symbol's type is set to the low 8 +bits of this expression. +Any bit pattern is permitted, but @code{_LD__} and debuggers will choke on +silly bit patterns. +@item other +An absolute expression. +The symbol's ``other'' attribute is set to the low 8 bits of this expression. +@item desc +An absolute expression. +The symbol's descriptor is set to the low 16 bits of this expression. +@item value +An absolute expression which becomes the symbol's value. +@end table + +If a warning is detected while reading a @code{.stabd}, @code{.stabn}, +or @code{.stabs} statement, the symbol has probably already been created +and you will get a half-formed symbol in your object file. This is +compatible with earlier assemblers! + +@table @code +@cindex @code{stabd} directive +@item .stabd @var{type} , @var{other} , @var{desc} + +The ``name'' of the symbol generated is not even an empty string. +It is a null pointer, for compatibility. Older assemblers used a +null pointer so they didn't waste space in object files with empty +strings. + +The symbol's value is set to the location counter, +relocatably. When your program is linked, the value of this symbol +will be where the location counter was when the @code{.stabd} was +assembled. + +@item .stabn @var{type} , @var{other} , @var{desc} , @var{value} +@cindex @code{stabn} directive +The name of the symbol is set to the empty string @code{""}. + +@item .stabs @var{string} , @var{type} , @var{other} , @var{desc} , @var{value} +@cindex @code{stabs} directive +All five fields are specified. +@end table +_fi__(_AOUT__||_BOUT__||_COFF__) +_fi__(_GENERIC__||!_H8__) + +_if__(_COFF__||_BOUT__) +_if__(_GENERIC__||!_H8__) +@node Tag, Text, Stab, Pseudo Ops +_fi__(_GENERIC__||!_H8__) +_if__(_H8__&&!_GENERIC__) +@node Tag, Text, Space, Pseudo Ops +_fi__(_H8__&&!_GENERIC__) +@section @code{.tag @var{structname}} + +@cindex COFF structure debugging +@cindex structure debugging, COFF +@cindex @code{tag} directive +This directive is generated by compilers to include auxiliary debugging +information in the symbol table. It is only permitted inside +@code{.def}/@code{.endef} pairs. Tags are used to link structure +definitions in the symbol table with instances of those structures. +_if__(_BOUT__) + +@samp{.tag} is only used when generating COFF format output; when +@code{_AS__} is generating @code{b.out}, it accepts this directive but +ignores it. +_fi__(_BOUT__) +_fi__(_COFF__||_BOUT__) + +_if__(_COFF__||_BOUT__) +@node Text, Title, Tag, Pseudo Ops +_fi__(_COFF__||_BOUT__) +_if__(!(_COFF__||_BOUT__)) +@node Text, Title, Stab, Pseudo Ops +_fi__(!(_COFF__||_BOUT__)) +@section @code{.text @var{subsection}} + +@cindex @code{text} directive +Tells @code{_AS__} to assemble the following statements onto the end of +the text subsection numbered @var{subsection}, which is an absolute +expression. If @var{subsection} is omitted, subsection number zero +is used. + +_if__(_COFF__||_BOUT__) +@node Title, Type, Text, Pseudo Ops +_fi__(_COFF__||_BOUT__) +_if__(!(_COFF__||_BOUT__)) +@node Title, Word, Text, Pseudo Ops +_fi__(!(_COFF__||_BOUT__)) +@section @code{.title "@var{heading}"} + +@cindex @code{title} directive +@cindex listing control: title line +Use @var{heading} as the title (second line, immediately after the +source file name and pagenumber) when generating assembly listings. + +This directive affects subsequent pages, as well as the current page if +it appears within ten lines of the top of a page. + +_if__(_COFF__||_BOUT__) +@node Type, Val, Title, Pseudo Ops +@section @code{.type @var{int}} + +@cindex COFF symbol type +@cindex symbol type, COFF +@cindex @code{type} directive +This directive, permitted only within @code{.def}/@code{.endef} pairs, +records the integer @var{int} as the type attribute of a symbol table entry. +_if__(_BOUT__) + +@samp{.type} is associated only with COFF format output; when +@code{_AS__} is configured for @code{b.out} output, it accepts this +directive but ignores it. +_fi__(_BOUT__) +_fi__(_COFF__||_BOUT__) + +_if__(_COFF__||_BOUT__) +@node Val, Word, Type, Pseudo Ops +@section @code{.val @var{addr}} + +@cindex @code{val} directive +@cindex COFF value attribute +@cindex value attribute, COFF +This directive, permitted only within @code{.def}/@code{.endef} pairs, +records the address @var{addr} as the value attribute of a symbol table +entry. +_if__(_BOUT__) + +@samp{.val} is used only for COFF output; when @code{_AS__} is +configured for @code{b.out}, it accepts this directive but ignores it. +_fi__(_BOUT__) +_fi__(_COFF__||_BOUT__) + +_if__(_COFF__||_BOUT__) +@node Word, Deprecated, Val, Pseudo Ops +_fi__(_COFF__||_BOUT__) +_if__(!(_COFF__||_BOUT__)) +@node Word, Deprecated, Text, Pseudo Ops +_fi__(!(_COFF__||_BOUT__)) +@section @code{.word @var{expressions}} + +@cindex @code{word} directive +This directive expects zero or more @var{expressions}, of any section, +separated by commas. +_if__((!_GENERIC__) && _W32__) +For each expression, @code{_AS__} emits a 32-bit number. +_fi__((!_GENERIC__) && _W32__) +_if__((!_GENERIC__) && _W16__) +For each expression, @code{_AS__} emits a 16-bit number. +_fi__((!_GENERIC__) && _W16__) + +_if__(_GENERIC__) +The size of the number emitted, and its byte order, +depends on what kind of computer will run the program. +_fi__(_GENERIC__) + +@c on amd29k, i960, sparc the "special treatment to support compilers" doesn't +@c happen---32-bit addressability, period; no long/short jumps. +_if__(_GENERIC__ || _DIFFTABKLUG__) +@cindex difference tables altered +@cindex altered difference tables +@quotation +@emph{Warning: Special Treatment to support Compilers} +@end quotation + +_if__(_GENERIC__) +Machines with a 32-bit address space, but that do less than 32-bit +addressing, require the following special treatment. If the machine of +interest to you does 32-bit addressing (or doesn't require it; +@pxref{_MACH_DEP__}), you can ignore this issue. + +_fi__(_GENERIC__) +In order to assemble compiler output into something that will work, +@code{_AS__} will occasionlly do strange things to @samp{.word} directives. +Directives of the form @samp{.word sym1-sym2} are often emitted by +compilers as part of jump tables. Therefore, when @code{_AS__} assembles a +directive of the form @samp{.word sym1-sym2}, and the difference between +@code{sym1} and @code{sym2} does not fit in 16 bits, @code{_AS__} will +create a @dfn{secondary jump table}, immediately before the next label. +This secondary jump table will be preceded by a short-jump to the +first byte after the secondary table. This short-jump prevents the flow +of control from accidentally falling into the new table. Inside the +table will be a long-jump to @code{sym2}. The original @samp{.word} +will contain @code{sym1} minus the address of the long-jump to +@code{sym2}. + +If there were several occurrences of @samp{.word sym1-sym2} before the +secondary jump table, all of them will be adjusted. If there was a +@samp{.word sym3-sym4}, that also did not fit in sixteen bits, a +long-jump to @code{sym4} will be included in the secondary jump table, +and the @code{.word} directives will be adjusted to contain @code{sym3} +minus the address of the long-jump to @code{sym4}; and so on, for as many +entries in the original jump table as necessary. + +_if__(_INTERNALS__) +@emph{This feature may be disabled by compiling @code{_AS__} with the +@samp{-DWORKING_DOT_WORD} option.} This feature is likely to confuse +assembly language programmers. +_fi__(_INTERNALS__) +_fi__(_GENERIC__ || _DIFFTABKLUG__) + +@node Deprecated, , Word, Pseudo Ops +@section Deprecated Directives + +@cindex deprecated directives +@cindex obsolescent directives +One day these directives won't work. +They are included for compatibility with older assemblers. +@table @t +@item .abort +@item .app-file +@item .line +@end table + +@node _MACH_DEP__, Copying, Pseudo Ops, Top +_if__(_GENERIC__) +@chapter Machine Dependent Features + +@cindex machine dependencies +The machine instruction sets are (almost by definition) different on +each machine where @code{_AS__} runs. Floating point representations +vary as well, and @code{_AS__} often supports a few additional +directives or command-line options for compatibility with other +assemblers on a particular platform. Finally, some versions of +@code{_AS__} support special pseudo-instructions for branch +optimization. + +This chapter discusses most of these differences, though it does not +include details on any machine's instruction set. For details on that +subject, see the hardware manufacturer's manual. + +@menu +_if__(_VAX__) +* Vax-Dependent:: VAX Dependent Features +_fi__(_VAX__) +_if__(_A29K__) +* AMD29K-Dependent:: AMD 29K Dependent Features +_fi__(_A29K__) +_if__(_H8__) +* H8/300-Dependent:: AMD 29K Dependent Features +_fi__(_H8__) +_if__(_I960__) +* i960-Dependent:: Intel 80960 Dependent Features +_fi__(_I960__) +_if__(_M680X0__) +* M68K-Dependent:: M680x0 Dependent Features +_fi__(_M680X0__) +_if__(_SPARC__) +* Sparc-Dependent:: SPARC Dependent Features +_fi__(_SPARC__) +_if__(_I80386__) +* i386-Dependent:: 80386 Dependent Features +_fi__(_I80386__) +@end menu + +_fi__(_GENERIC__) +_if__(_VAX__) +_if__(_GENERIC__) +@node Vax-Dependent, AMD29K-Dependent, Machine Dependent, Machine Dependent +_fi__(_GENERIC__) +_CHAPSEC__(0+_GENERIC__) VAX Dependent Features + +@cindex VAX support +@menu +* Vax-Opts:: VAX Command-Line Options +* VAX-float:: VAX Floating Point +* VAX-directives:: Vax Machine Directives +* VAX-opcodes:: VAX Opcodes +* VAX-branch:: VAX Branch Improvement +* VAX-operands:: VAX Operands +* VAX-no:: Not Supported on VAX +@end menu + +@node Vax-Opts, VAX-float, Vax-Dependent, Vax-Dependent +_CHAPSEC__(1+_GENERIC__) VAX Command-Line Options + +@cindex command-line options ignored, VAX +@cindex VAX command-line options ignored +The Vax version of @code{_AS__} accepts any of the following options, +gives a warning message that the option was ignored and proceeds. +These options are for compatibility with scripts designed for other +people's assemblers. + +@table @asis +@item @kbd{-D} (Debug) +@itemx @kbd{-S} (Symbol Table) +@itemx @kbd{-T} (Token Trace) +@cindex @code{-D}, ignored on VAX +@cindex @code{-S}, ignored on VAX +@cindex @code{-T}, ignored on VAX +These are obsolete options used to debug old assemblers. + +@item @kbd{-d} (Displacement size for JUMPs) +@cindex @code{-d}, VAX option +This option expects a number following the @kbd{-d}. Like options +that expect filenames, the number may immediately follow the +@kbd{-d} (old standard) or constitute the whole of the command line +argument that follows @kbd{-d} (GNU standard). + +@item @kbd{-V} (Virtualize Interpass Temporary File) +@cindex @code{-V}, redundant on VAX +Some other assemblers use a temporary file. This option +commanded them to keep the information in active memory rather +than in a disk file. @code{_AS__} always does this, so this +option is redundant. + +@item @kbd{-J} (JUMPify Longer Branches) +@cindex @code{-J}, ignored on VAX +Many 32-bit computers permit a variety of branch instructions +to do the same job. Some of these instructions are short (and +fast) but have a limited range; others are long (and slow) but +can branch anywhere in virtual memory. Often there are 3 +flavors of branch: short, medium and long. Some other +assemblers would emit short and medium branches, unless told by +this option to emit short and long branches. + +@item @kbd{-t} (Temporary File Directory) +@cindex @code{-t}, ignored on VAX +Some other assemblers may use a temporary file, and this option +takes a filename being the directory to site the temporary +file. @code{_AS__} does not use a temporary disk file, so this +option makes no difference. @kbd{-t} needs exactly one +filename. +@end table + +@cindex VMS (VAX) options +@cindex options for VAX/VMS +@cindex VAX/VMS options +@cindex @code{-h} option, VAX/VMS +@cindex @code{-+} option, VAX/VMS +@cindex Vax-11 C compatibility +@cindex symbols with lowercase, VAX/VMS +@c FIXME! look into "I think" below, correct if needed, delete. +The Vax version of the assembler accepts two options when +compiled for VMS. They are @kbd{-h}, and @kbd{-+}. The +@kbd{-h} option prevents @code{_AS__} from modifying the +symbol-table entries for symbols that contain lowercase +characters (I think). The @kbd{-+} option causes @code{_AS__} to +print warning messages if the FILENAME part of the object file, +or any symbol name is larger than 31 characters. The @kbd{-+} +option also insertes some code following the @samp{_main} +symbol so that the object file will be compatible with Vax-11 +"C". + +@node VAX-float, VAX-directives, Vax-Opts, Vax-Dependent +_CHAPSEC__(1+_GENERIC__) VAX Floating Point + +@cindex VAX floating point +@cindex floating point, VAX +Conversion of flonums to floating point is correct, and +compatible with previous assemblers. Rounding is +towards zero if the remainder is exactly half the least significant bit. + +@code{D}, @code{F}, @code{G} and @code{H} floating point formats +are understood. + +Immediate floating literals (@emph{e.g.} @samp{S`$6.9}) +are rendered correctly. Again, rounding is towards zero in the +boundary case. + +@cindex @code{float} directive, VAX +@cindex @code{double} directive, VAX +The @code{.float} directive produces @code{f} format numbers. +The @code{.double} directive produces @code{d} format numbers. + +@node VAX-directives, VAX-opcodes, VAX-float, Vax-Dependent +_CHAPSEC__(1+_GENERIC__) Vax Machine Directives + +@cindex machine directives, VAX +@cindex VAX machine directives +The Vax version of the assembler supports four directives for +generating Vax floating point constants. They are described in the +table below. + +@cindex wide floating point directives, VAX +@table @code +@item .dfloat +@cindex @code{dfloat} directive, VAX +This expects zero or more flonums, separated by commas, and +assembles Vax @code{d} format 64-bit floating point constants. + +@item .ffloat +@cindex @code{ffloat} directive, VAX +This expects zero or more flonums, separated by commas, and +assembles Vax @code{f} format 32-bit floating point constants. + +@item .gfloat +@cindex @code{gfloat} directive, VAX +This expects zero or more flonums, separated by commas, and +assembles Vax @code{g} format 64-bit floating point constants. + +@item .hfloat +@cindex @code{hfloat} directive, VAX +This expects zero or more flonums, separated by commas, and +assembles Vax @code{h} format 128-bit floating point constants. + +@end table + +@node VAX-opcodes, VAX-branch, VAX-directives, Vax-Dependent +_CHAPSEC__(1+_GENERIC__) VAX Opcodes + +@cindex VAX opcode mnemonics +@cindex opcode mnemonics, VAX +@cindex mnemonics for opcodes, VAX +All DEC mnemonics are supported. Beware that @code{case@dots{}} +instructions have exactly 3 operands. The dispatch table that +follows the @code{case@dots{}} instruction should be made with +@code{.word} statements. This is compatible with all unix +assemblers we know of. + +@node VAX-branch, VAX-operands, VAX-opcodes, Vax-Dependent +_CHAPSEC__(1+_GENERIC__) VAX Branch Improvement + +@cindex VAX branch improvement +@cindex branch improvement, VAX +@cindex pseudo-ops for branch, VAX +Certain pseudo opcodes are permitted. They are for branch +instructions. They expand to the shortest branch instruction that +will reach the target. Generally these mnemonics are made by +substituting @samp{j} for @samp{b} at the start of a DEC mnemonic. +This feature is included both for compatibility and to help +compilers. If you don't need this feature, don't use these +opcodes. Here are the mnemonics, and the code they can expand into. + +@table @code +@item jbsb +@samp{Jsb} is already an instruction mnemonic, so we chose @samp{jbsb}. +@table @asis +@item (byte displacement) +@kbd{bsbb @dots{}} +@item (word displacement) +@kbd{bsbw @dots{}} +@item (long displacement) +@kbd{jsb @dots{}} +@end table +@item jbr +@itemx jr +Unconditional branch. +@table @asis +@item (byte displacement) +@kbd{brb @dots{}} +@item (word displacement) +@kbd{brw @dots{}} +@item (long displacement) +@kbd{jmp @dots{}} +@end table +@item j@var{COND} +@var{COND} may be any one of the conditional branches +@code{neq nequ eql eqlu gtr geq lss gtru lequ vc vs gequ cc lssu cs}. +@var{COND} may also be one of the bit tests +@code{bs bc bss bcs bsc bcc bssi bcci lbs lbc}. +@var{NOTCOND} is the opposite condition to @var{COND}. +@table @asis +@item (byte displacement) +@kbd{b@var{COND} @dots{}} +@item (word displacement) +@kbd{b@var{NOTCOND} foo ; brw @dots{} ; foo:} +@item (long displacement) +@kbd{b@var{NOTCOND} foo ; jmp @dots{} ; foo:} +@end table +@item jacb@var{X} +@var{X} may be one of @code{b d f g h l w}. +@table @asis +@item (word displacement) +@kbd{@var{OPCODE} @dots{}} +@item (long displacement) +@example +@var{OPCODE} @dots{}, foo ; +brb bar ; +foo: jmp @dots{} ; +bar: +@end example +@end table +@item jaob@var{YYY} +@var{YYY} may be one of @code{lss leq}. +@item jsob@var{ZZZ} +@var{ZZZ} may be one of @code{geq gtr}. +@table @asis +@item (byte displacement) +@kbd{@var{OPCODE} @dots{}} +@item (word displacement) +@example +@var{OPCODE} @dots{}, foo ; +brb bar ; +foo: brw @var{destination} ; +bar: +@end example +@item (long displacement) +@example +@var{OPCODE} @dots{}, foo ; +brb bar ; +foo: jmp @var{destination} ; +bar: +@end example +@end table +@item aobleq +@itemx aoblss +@itemx sobgeq +@itemx sobgtr +@table @asis +@item (byte displacement) +@kbd{@var{OPCODE} @dots{}} +@item (word displacement) +@example +@var{OPCODE} @dots{}, foo ; +brb bar ; +foo: brw @var{destination} ; +bar: +@end example +@item (long displacement) +@example +@var{OPCODE} @dots{}, foo ; +brb bar ; +foo: jmp @var{destination} ; +bar: +@end example +@end table +@end table + +@node VAX-operands, VAX-no, VAX-branch, Vax-Dependent +_CHAPSEC__(1+_GENERIC__) VAX Operands + +@cindex VAX operand notation +@cindex operand notation, VAX +@cindex immediate character, VAX +@cindex VAX immediate character +The immediate character is @samp{$} for Unix compatibility, not +@samp{#} as DEC writes it. + +@cindex indirect character, VAX +@cindex VAX indirect character +The indirect character is @samp{*} for Unix compatibility, not +@samp{@@} as DEC writes it. + +@cindex displacement sizing character, VAX +@cindex VAX displacement sizing character +The displacement sizing character is @samp{`} (an accent grave) for +Unix compatibility, not @samp{^} as DEC writes it. The letter +preceding @samp{`} may have either case. @samp{G} is not +understood, but all other letters (@code{b i l s w}) are understood. + +@cindex register names, VAX +@cindex VAX register names +Register names understood are @code{r0 r1 r2 @dots{} r15 ap fp sp +pc}. Any case of letters will do. + +For instance +@smallexample +tstb *w`$4(r5) +@end smallexample + +Any expression is permitted in an operand. Operands are comma +separated. + +@c There is some bug to do with recognizing expressions +@c in operands, but I forget what it is. It is +@c a syntax clash because () is used as an address mode +@c and to encapsulate sub-expressions. + +@node VAX-no, , VAX-operands, Vax-Dependent +_CHAPSEC__(1+_GENERIC__) Not Supported on VAX + +@cindex VAX bitfields not supported +@cindex bitfields, not supported on VAX +Vax bit fields can not be assembled with @code{_AS__}. Someone +can add the required code if they really need it. + +_fi__(_VAX__) +_if__(_A29K__) +_if__(_GENERIC__) +@node AMD29K-Dependent, H8/300-Dependent, Vax-Dependent, Machine Dependent +_fi__(_GENERIC__) +_CHAPSEC__(0+_GENERIC__) AMD 29K Dependent Features + +@cindex AMD 29K support +@cindex 29K support +@menu +* AMD29K Options:: Options +* AMD29K Syntax:: Syntax +* AMD29K Floating Point:: Floating Point +* AMD29K Directives:: AMD 29K Machine Directives +* AMD29K Opcodes:: Opcodes +@end menu + +@node AMD29K Options, AMD29K Syntax, AMD29K-Dependent, AMD29K-Dependent +_CHAPSEC__(1+_GENERIC__) Options +@cindex AMD 29K options (none) +@cindex options for AMD29K (none) +@code{_AS__} has no additional command-line options for the AMD +29K family. + +@node AMD29K Syntax, AMD29K Floating Point, AMD29K Options, AMD29K-Dependent +_CHAPSEC__(1+_GENERIC__) Syntax +@menu +* AMD29K-Chars:: Special Characters +* AMD29K-Regs:: Register Names +@end menu + +@node AMD29K-Chars, AMD29K-Regs, AMD29K Syntax, AMD29K Syntax +_CHAPSEC__(2+_GENERIC__) Special Characters + +@cindex line comment character, AMD 29K +@cindex AMD 29K line comment character +@samp{;} is the line comment character. + +@cindex line separator, AMD 29K +@cindex AMD 29K line separator +@cindex statement separator, AMD 29K +@cindex AMD 29K statement separator +@samp{@@} can be used instead of a newline to separate statements. + +@cindex identifiers, AMD 29K +@cindex AMD 29K identifiers +The character @samp{?} is permitted in identifiers (but may not begin +an identifier). + +@node AMD29K-Regs, , AMD29K-Chars, AMD29K Syntax +_CHAPSEC__(2+_GENERIC__) Register Names + +@cindex AMD 29K register names +@cindex register names, AMD 29K +General-purpose registers are represented by predefined symbols of the +form @samp{GR@var{nnn}} (for global registers) or @samp{LR@var{nnn}} +(for local registers), where @var{nnn} represents a number between +@code{0} and @code{127}, written with no leading zeros. The leading +letters may be in either upper or lower case; for example, @samp{gr13} +and @samp{LR7} are both valid register names. + +You may also refer to general-purpose registers by specifying the +register number as the result of an expression (prefixed with @samp{%%} +to flag the expression as a register number): +@smallexample +%%@var{expression} +@end smallexample +@noindent +---where @var{expression} must be an absolute expression evaluating to a +number between @code{0} and @code{255}. The range [0, 127] refers to +global registers, and the range [128, 255] to local registers. + +@cindex special purpose registers, AMD 29K +@cindex AMD 29K special purpose registers +@cindex protected registers, AMD 29K +@cindex AMD 29K protected registers +In addition, @code{_AS__} understands the following protected +special-purpose register names for the AMD 29K family: + +@smallexample + vab chd pc0 + ops chc pc1 + cps rbp pc2 + cfg tmc mmu + cha tmr lru +@end smallexample + +These unprotected special-purpose register names are also recognized: +@smallexample + ipc alu fpe + ipa bp inte + ipb fc fps + q cr exop +@end smallexample + +@node AMD29K Floating Point, AMD29K Directives, AMD29K Syntax, AMD29K-Dependent +_CHAPSEC__(1+_GENERIC__) Floating Point + +@cindex floating point, AMD 29K (@sc{ieee}) +@cindex AMD 29K floating point (@sc{ieee}) +The AMD 29K family uses @sc{ieee} floating-point numbers. + +@node AMD29K Directives, AMD29K Opcodes, AMD29K Floating Point, AMD29K-Dependent +_CHAPSEC__(1+_GENERIC__) AMD 29K Machine Directives + +@cindex machine directives, AMD 29K +@cindex AMD 29K machine directives +@table @code +@item .block @var{size} , @var{fill} +@cindex @code{block} directive, AMD 29K +This directive emits @var{size} bytes, each of value @var{fill}. Both +@var{size} and @var{fill} are absolute expressions. If the comma +and @var{fill} are omitted, @var{fill} is assumed to be zero. + +In other versions of the GNU assembler, this directive is called +@samp{.space}. +@end table + +@table @code +@item .cputype +@cindex @code{cputype} directive, AMD 29K +This directive is ignored; it is accepted for compatibility with other +AMD 29K assemblers. + +@item .file +@cindex @code{file} directive, AMD 29K +This directive is ignored; it is accepted for compatibility with other +AMD 29K assemblers. + +@quotation +@emph{Warning:} in other versions of the GNU assembler, @code{.file} is +used for the directive called @code{.app-file} in the AMD 29K support. +@end quotation + +@item .line +@cindex @code{line} directive, AMD 29K +This directive is ignored; it is accepted for compatibility with other +AMD 29K assemblers. + +@item .reg @var{symbol}, @var{expression} +@cindex @code{reg} directive, AMD 29K +@code{.reg} has the same effect as @code{.lsym}; @pxref{Lsym,,@code{.lsym}}. + +@item .sect +@cindex @code{sect} directive, AMD 29K +This directive is ignored; it is accepted for compatibility with other +AMD 29K assemblers. + +@item .use @var{section name} +@cindex @code{use} directive, AMD 29K +Establishes the section and subsection for the following code; +@var{section name} may be one of @code{.text}, @code{.data}, +@code{.data1}, or @code{.lit}. With one of the first three @var{section +name} options, @samp{.use} is equivalent to the machine directive +@var{section name}; the remaining case, @samp{.use .lit}, is the same as +@samp{.data 200}. +@end table + +@node AMD29K Opcodes, , AMD29K Directives, AMD29K-Dependent +_CHAPSEC__(1+_GENERIC__) Opcodes + +@cindex AMD 29K opcodes +@cindex opcodes for AMD 29K +@code{_AS__} implements all the standard AMD 29K opcodes. No +additional pseudo-instructions are needed on this family. + +For information on the 29K machine instruction set, see @cite{Am29000 +User's Manual}, Advanced Micro Devices, Inc. + +_fi__(_A29K__) +_if__(_H8__) +_if__(_GENERIC__) +@node H8/300-Dependent, i960-Dependent, AMD29K-Dependent, Machine Dependent +_fi__(_GENERIC__) +_CHAPSEC__(0+_GENERIC__) H8/300 Dependent Features + +@cindex H8/300 support +@menu +* H8/300 Options:: Options +* H8/300 Syntax:: Syntax +* H8/300 Floating Point:: Floating Point +* H8/300 Directives:: H8/300 Machine Directives +* H8/300 Opcodes:: Opcodes +@end menu + +@node H8/300 Options, H8/300 Syntax, H8/300-Dependent, H8/300-Dependent +_CHAPSEC__(1+_GENERIC__) Options + +@cindex H8/300 options (none) +@cindex options, H8/300 (none) +@code{_AS__} has no additional command-line options for the Hitachi +H8/300 family. + +@node H8/300 Syntax, H8/300 Floating Point, H8/300 Options, H8/300-Dependent +_CHAPSEC__(1+_GENERIC__) Syntax +@menu +* H8/300-Chars:: Special Characters +* H8/300-Regs:: Register Names +* H8/300-Addressing:: Addressing Modes +@end menu + +@node H8/300-Chars, H8/300-Regs, H8/300 Syntax, H8/300 Syntax +_CHAPSEC__(2+_GENERIC__) Special Characters + +@cindex line comment character, H8/300 +@cindex H8/300 line comment character +@samp{;} is the line comment character. + +@cindex line separator, H8/300 +@cindex statement separator, H8/300 +@cindex H8/300 line separator +@samp{$} can be used instead of a newline to separate statements. +Therefore @emph{you may not use @samp{$} in symbol names} on the H8/300. + +@node H8/300-Regs, H8/300-Addressing, H8/300-Chars, H8/300 Syntax +_CHAPSEC__(2+_GENERIC__) Register Names + +@cindex H8/300 registers +@cindex registers, H8/300 +You can use predefined symbols of the form @samp{r@var{n}h} and +@samp{r@var{n}l} to refer to the H8/300 registers as sixteen 8-bit +general-purpose registers. @var{n} is a digit from @samp{0} to +@samp{7}); for instance, both @samp{r0h} and @samp{r7l} are valid +register names. + +You can also use the eight predefined symbols @samp{r@var{n}} to refer +to the H8/300 registers as 16-bit registers (you must use this form for +addressing). + +The two control registers are called @code{pc} (program counter; a +16-bit register) and @code{ccr} (condition code register; an 8-bit +register). @code{r7} is used as the stack pointer, and can also be +called @code{sp}. + +@node H8/300-Addressing, , H8/300-Regs, H8/300 Syntax +_CHAPSEC__(2+_GENERIC__) Addressing Modes + +@cindex addressing modes, H8/300 +@cindex H8/300 addressing modes +_AS__ understands the following addressing modes for the H8/300: +@table @code +@item r@var{n} +Register direct + +@item @@r@var{n} +Register indirect + +@item @@(@var{d}, r@var{n}) +@itemx @@(@var{d}:16, r@var{n}) +Register indirect: 16-bit displacement @var{d} from register @var{n}. +(You may specify the @samp{:16} for clarity if you wish, but it is not +required and has no effect.) + +@item @@r@var{n}+ +Register indirect with post-increment + +@item @@-r@var{n} +Register indirect with pre-decrement + +@item @code{@@}@var{aa} +@itemx @code{@@}@var{aa}:8 +@itemx @code{@@}@var{aa}:16 +Absolute address @code{aa}. You may specify the @samp{:8} or @samp{:16} +for clarity, if you wish; but @code{_AS__} neither requires this nor +uses it---the address size required is taken from context. + +@item #@var{xx} +@itemx #@var{xx}:8 +@itemx #@var{xx}:16 +Immediate data @var{xx}. You may specify the @samp{:8} or @samp{:16} +for clarity, if you wish; but @code{_AS__} neither requires this nor +uses it---the data size required is taken from context. + +@item @code{@@}@code{@@}@var{aa} +@itemx @code{@@}@code{@@}@var{aa}:8 +Memory indirect. You may specify the @samp{:8} for clarity, if you +wish; but @code{_AS__} neither requires this nor uses it. +@end table + +@node H8/300 Floating Point, H8/300 Directives, H8/300 Syntax, H8/300-Dependent +_CHAPSEC__(1+_GENERIC__) Floating Point + +@cindex floating point, H8/300 (@sc{ieee}) +@cindex H8/300 floating point (@sc{ieee}) +The H8/300 family uses @sc{ieee} floating-point numbers. + +@node H8/300 Directives, H8/300 Opcodes, H8/300 Floating Point, H8/300-Dependent +_CHAPSEC__(1+_GENERIC__) H8/300 Machine Directives + +@cindex H8/300 machine directives (none) +@cindex machine directives, H8/300 (none) +@cindex @code{word} directive, H8/300 +@cindex @code{int} directive, H8/300 +@code{_AS__} has no machine-dependent directives for the H8/300. +However, on this platform the @samp{.int} and @samp{.word} directives +generate 16-bit numbers. + +@node H8/300 Opcodes, , H8/300 Directives, H8/300-Dependent +_CHAPSEC__(1+_GENERIC__) Opcodes + +@cindex H8/300 opcode summary +@cindex opcode summary, H8/300 +@cindex mnemonics, H8/300 +@cindex instruction summary, H8/300 +For detailed information on the H8/300 machine instruction set, see +@cite{H8/300 Series Programming Manual} (Hitachi ADE--602--025). + +@code{_AS__} implements all the standard H8/300 opcodes. No additional +pseudo-instructions are needed on this family. + +The following table summarizes the opcodes and their arguments: +@c kluge due to lack of group outside example +@page +@smallexample +@group + Rs @r{source register} + Rd @r{destination register} + imm @r{immediate data} + x:3 @r{a bit (as a number between 0 and 7)} + d:8 @r{eight bit displacement from @code{pc}} + d:16 @r{sixteen bit displacement from @code{Rs}} + +add.b Rs,Rd biand #x:3,Rd +add.b #imm:8,Rd biand #x:3,@@Rd +add.w Rs,Rd biand #x:3,@@aa:8 +adds #1,Rd bild #x:3,Rd +adds #2,Rd bild #x:3,@@Rd +addx #imm:8,Rd bild #x:3,@@aa:8 +addx Rs,Rd bior #x:3,Rd +and #imm:8,Rd bior #x:3,@@Rd +and Rs,Rd bior #x:3,@@aa:8 +andc #imm:8,ccr bist #x:3,Rd +band #x:3,Rd bist #x:3,@@Rd +band #x:3,@@Rd bist #x:3,@@aa:8 +bra d:8 bixor #x:3,Rd +bt d:8 bixor #x:3,@@Rd +brn d:8 bixor #x:3,@@aa:8 +bf d:8 bld #x:3,Rd +bhi d:8 bld #x:3,@@Rd +bls d:8 bld #x:3,@@aa:8 +bcc d:8 bnot #x:3,Rd +bhs d:8 bnot #x:3,@@Rd +bcs d:8 bnot #x:3,@@aa:8 +blo d:8 bnot Rs,Rd +bne d:8 bnot Rs,@@Rd +beq d:8 bnot Rs,@@aa:8 +bvc d:8 bor #x:3,Rd +bvs d:8 bor #x:3,@@Rd +bpl d:8 bor #x:3,@@aa:8 +bmi d:8 bset #x:3,@@Rd +bge d:8 bset #x:3,@@aa:8 +blt d:8 bset Rs,Rd +bgt d:8 bset Rs,@@Rd +ble d:8 bset Rs,@@aa:8 +bclr #x:3,Rd bsr d:8 +bclr #x:3,@@Rd bst #x:3,Rd +bclr #x:3,@@aa:8 bst #x:3,@@Rd +bclr Rs,Rd bst #x:3,@@aa:8 +bclr Rs,@@Rd btst #x:3,Rd +@end group +@group +btst #x:3,@@Rd mov.w @@(d:16, Rs),Rd +btst #x:3,@@aa:8 mov.w @@Rs+,Rd +btst Rs,Rd mov.w @@aa:16,Rd +btst Rs,@@Rd mov.w Rs,@@Rd +btst Rs,@@aa:8 mov.w Rs,@@(d:16, Rd) +bxor #x:3,Rd mov.w Rs,@@-Rd +bxor #x:3,@@Rd mov.w Rs,@@aa:16 +bxor #x:3,@@aa:8 movfpe @@aa:16,Rd +cmp.b #imm:8,Rd movtpe Rs,@@aa:16 +cmp.b Rs,Rd mulxu Rs,Rd +cmp.w Rs,Rd neg Rs +daa Rs nop +das Rs not Rs +dec Rs or #imm:8,Rd +divxu Rs,Rd or Rs,Rd +eepmov orc #imm:8,ccr +inc Rs pop Rs +jmp @@Rs push Rs +jmp @@aa:16 rotl Rs +jmp @@@@aa rotr Rs +jsr @@Rs rotxl Rs +jsr @@aa:16 rotxr Rs +jsr @@@@aa:8 rte +ldc #imm:8,ccr rts +ldc Rs,ccr shal Rs +mov.b Rs,Rd shar Rs +mov.b #imm:8,Rd shll Rs +mov.b @@Rs,Rd shlr Rs +mov.b @@(d:16, Rs),Rd sleep +mov.b @@Rs+,Rd stc ccr,Rd +mov.b @@aa:16,Rd sub.b Rs,Rd +mov.b @@aa:8,Rd sub.w Rs,Rd +mov.b Rs,@@Rd subs #1,Rd +mov.b Rs,@@(d:16, Rd) subs #2,Rd +mov.b Rs,@@-Rd subx #imm:8,Rd +mov.b Rs,@@aa:16 subx Rs,Rd +mov.b Rs,@@aa:8 xor #imm:8,Rd +mov.w Rs,Rd xor Rs,Rd +mov.w #imm:16,Rd xorc #imm:8,ccr +mov.w @@Rs,Rd +@end group +@end smallexample + +@cindex size suffixes, H8/300 +@cindex H8/300 size suffixes +Four H8/300 instructions (@code{add}, @code{cmp}, @code{mov}, +@code{sub}) are defined with variants using the suffixes @samp{.b} and +@samp{.w} to specify the size of a memory operand. @code{_AS__} +supports these suffixes, but does not require them; since one of the +operands is always a register, @code{_AS__} can deduce the correct size. + +For example, since @code{r0} refers to a 16-bit register, +@example +mov r0,@@foo +@exdent is equivalent to +mov.w r0,@@foo +@end example + +If you use the size suffixes, @code{_AS__} will issue a warning if +there's a mismatch between the suffix and the register size. + +_fi__(_H8__) +_if__(_I960__) +_if__(_GENERIC__) +@node i960-Dependent, M68K-Dependent, H8/300-Dependent, Machine Dependent +_fi__(_GENERIC__) +_CHAPSEC__(0+_GENERIC__) Intel 80960 Dependent Features + +@cindex i960 support +@menu +* Options-i960:: i960 Command-line Options +* Floating Point-i960:: Floating Point +* Directives-i960:: i960 Machine Directives +* Opcodes for i960:: i960 Opcodes +@end menu + +@c FIXME! Add Syntax sec with discussion of bitfields here, at least so +@c long as they're not turned on for other machines than 960. +@node Options-i960, Floating Point-i960, i960-Dependent, i960-Dependent + +_CHAPSEC__(1+_GENERIC__) i960 Command-line Options + +@cindex i960 options +@cindex options, i960 +@table @code + +@item -ACA | -ACA_A | -ACB | -ACC | -AKA | -AKB | -AKC | -AMC +@cindex i960 architecture options +@cindex architecture options, i960 +@cindex @code{-A} options, i960 +Select the 80960 architecture. Instructions or features not supported +by the selected architecture cause fatal errors. + +@samp{-ACA} is equivalent to @samp{-ACA_A}; @samp{-AKC} is equivalent to +@samp{-AMC}. Synonyms are provided for compatibility with other tools. + +If none of these options is specified, @code{_AS__} will generate code for any +instruction or feature that is supported by @emph{some} version of the +960 (even if this means mixing architectures!). In principle, +@code{_AS__} will attempt to deduce the minimal sufficient processor +type if none is specified; depending on the object code format, the +processor type may be recorded in the object file. If it is critical +that the @code{_AS__} output match a specific architecture, specify that +architecture explicitly. + +@item -b +@cindex @code{-b} option, i960 +@cindex branch recording, i960 +@cindex i960 branch recording +Add code to collect information about conditional branches taken, for +later optimization using branch prediction bits. (The conditional branch +instructions have branch prediction bits in the CA, CB, and CC +architectures.) If @var{BR} represents a conditional branch instruction, +the following represents the code generated by the assembler when +@samp{-b} is specified: + +@smallexample + call @var{increment routine} + .word 0 # pre-counter +Label: @var{BR} + call @var{increment routine} + .word 0 # post-counter +@end smallexample + +The counter following a branch records the number of times that branch +was @emph{not} taken; the differenc between the two counters is the +number of times the branch @emph{was} taken. + +@cindex @code{gbr960}, i960 postprocessor +@cindex branch statistics table, i960 +A table of every such @code{Label} is also generated, so that the +external postprocessor @code{gbr960} (supplied by Intel) can locate all +the counters. This table is always labelled @samp{__BRANCH_TABLE__}; +this is a local symbol to permit collecting statistics for many separate +object files. The table is word aligned, and begins with a two-word +header. The first word, initialized to 0, is used in maintaining linked +lists of branch tables. The second word is a count of the number of +entries in the table, which follow immediately: each is a word, pointing +to one of the labels illustrated above. + +@c TEXI2ROFF-KILL +@ifinfo +@c END TEXI2ROFF-KILL +@example + +------------+------------+------------+ ... +------------+ + | | | | | | + | *NEXT | COUNT: N | *BRLAB 1 | | *BRLAB N | + | | | | | | + +------------+------------+------------+ ... +------------+ + + __BRANCH_TABLE__ layout +@end example +@c TEXI2ROFF-KILL +@end ifinfo +@tex +\vskip 1pc +\line{\leftskip=0pt\hskip\tableindent +\boxit{2cm}{\tt *NEXT}\boxit{2cm}{\tt COUNT: \it N}\boxit{2cm}{\tt +*BRLAB 1}\ibox{1cm}{\quad\dots}\boxit{2cm}{\tt *BRLAB \it N}\hfil} +\centerline{\it {\tt \_\_BRANCH\_TABLE\_\_} layout} +@end tex +@c END TEXI2ROFF-KILL + +The first word of the header is used to locate multiple branch tables, +since each object file may contain one. Normally the links are +maintained with a call to an initialization routine, placed at the +beginning of each function in the file. The GNU C compiler will +generate these calls automatically when you give it a @samp{-b} option. +For further details, see the documentation of @samp{gbr960}. + +@item -norelax +@cindex @code{-norelax} option, i960 +Normally, Compare-and-Branch instructions with targets that require +displacements greater than 13 bits (or that have external targets) are +replaced with the corresponding compare (or @samp{chkbit}) and branch +instructions. You can use the @samp{-norelax} option to specify that +@code{_AS__} should generate errors instead, if the target displacement +is larger than 13 bits. + +This option does not affect the Compare-and-Jump instructions; the code +emitted for them is @emph{always} adjusted when necessary (depending on +displacement size), regardless of whether you use @samp{-norelax}. +@end table + +@node Floating Point-i960, Directives-i960, Options-i960, i960-Dependent +_CHAPSEC__(1+_GENERIC__) Floating Point + +@cindex floating point, i960 (@sc{ieee}) +@cindex i960 floating point (@sc{ieee}) +@code{_AS__} generates @sc{ieee} floating-point numbers for the directives +@samp{.float}, @samp{.double}, @samp{.extended}, and @samp{.single}. + +@node Directives-i960, Opcodes for i960, Floating Point-i960, i960-Dependent +_CHAPSEC__(1+_GENERIC__) i960 Machine Directives + +@cindex machine directives, i960 +@cindex i960 machine directives + +@table @code +@cindex @code{bss} directive, i960 +@item .bss @var{symbol}, @var{length}, @var{align} +Reserve @var{length} bytes in the bss section for a local @var{symbol}, +aligned to the power of two specified by @var{align}. @var{length} and +@var{align} must be positive absolute expressions. This directive +differs from @samp{.lcomm} only in that it permits you to specify +an alignment. @xref{Lcomm,,@code{.lcomm}}. +@end table + +@table @code +@item .extended @var{flonums} +@cindex @code{extended} directive, i960 +@code{.extended} expects zero or more flonums, separated by commas; for +each flonum, @samp{.extended} emits an @sc{ieee} extended-format (80-bit) +floating-point number. + +@item .leafproc @var{call-lab}, @var{bal-lab} +@cindex @code{leafproc} directive, i960 +You can use the @samp{.leafproc} directive in conjunction with the +optimized @code{callj} instruction to enable faster calls of leaf +procedures. If a procedure is known to call no other procedures, you +may define an entry point that skips procedure prolog code (and that does +not depend on system-supplied saved context), and declare it as the +@var{bal-lab} using @samp{.leafproc}. If the procedure also has an +entry point that goes through the normal prolog, you can specify that +entry point as @var{call-lab}. + +A @samp{.leafproc} declaration is meant for use in conjunction with the +optimized call instruction @samp{callj}; the directive records the data +needed later to choose between converting the @samp{callj} into a +@code{bal} or a @code{call}. + +@var{call-lab} is optional; if only one argument is present, or if the +two arguments are identical, the single argument is assumed to be the +@code{bal} entry point. + +@item .sysproc @var{name}, @var{index} +@cindex @code{sysproc} directive, i960 +The @samp{.sysproc} directive defines a name for a system procedure. +After you define it using @samp{.sysproc}, you can use @var{name} to +refer to the system procedure identified by @var{index} when calling +procedures with the optimized call instruction @samp{callj}. + +Both arguments are required; @var{index} must be between 0 and 31 +(inclusive). +@end table + +@node Opcodes for i960, , Directives-i960, i960-Dependent +_CHAPSEC__(1+_GENERIC__) i960 Opcodes + +@cindex opcodes, i960 +@cindex i960 opcodes +All Intel 960 machine instructions are supported; +@pxref{Options-i960,,i960 Command-line Options} for a discussion of +selecting the instruction subset for a particular 960 +architecture.@refill + +Some opcodes are processed beyond simply emitting a single corresponding +instruction: @samp{callj}, and Compare-and-Branch or Compare-and-Jump +instructions with target displacements larger than 13 bits. + +@menu +* callj-i960:: @code{callj} +* Compare-and-branch-i960:: Compare-and-Branch +@end menu + +@node callj-i960, Compare-and-branch-i960, Opcodes for i960, Opcodes for i960 +_CHAPSEC__(2+_GENERIC__) @code{callj} + +@cindex @code{callj}, i960 pseudo-opcode +@cindex i960 @code{callj} pseudo-opcode +You can write @code{callj} to have the assembler or the linker determine +the most appropriate form of subroutine call: @samp{call}, +@samp{bal}, or @samp{calls}. If the assembly source contains +enough information---a @samp{.leafproc} or @samp{.sysproc} directive +defining the operand---then @code{_AS__} will translate the +@code{callj}; if not, it will simply emit the @code{callj}, leaving it +for the linker to resolve. + +@node Compare-and-branch-i960, , callj-i960, Opcodes for i960 +_CHAPSEC__(2+_GENERIC__) Compare-and-Branch + +@cindex i960 compare and branch instructions +@cindex compare and branch instructions, i960 +The 960 architectures provide combined Compare-and-Branch instructions +that permit you to store the branch target in the lower 13 bits of the +instruction word itself. However, if you specify a branch target far +enough away that its address won't fit in 13 bits, the assembler can +either issue an error, or convert your Compare-and-Branch instruction +into separate instructions to do the compare and the branch. + +@cindex compare and jump expansions, i960 +@cindex i960 compare and jump expansions +Whether @code{_AS__} gives an error or expands the instruction depends +on two choices you can make: whether you use the @samp{-norelax} option, +and whether you use a ``Compare and Branch'' instruction or a ``Compare +and Jump'' instruction. The ``Jump'' instructions are @emph{always} +expanded if necessary; the ``Branch'' instructions are expanded when +necessary @emph{unless} you specify @code{-norelax}---in which case +@code{_AS__} gives an error instead. + +These are the Compare-and-Branch instructions, their ``Jump'' variants, +and the instruction pairs they may expand into: + +@c TEXI2ROFF-KILL +@ifinfo +@c END TEXI2ROFF-KILL +@example + Compare and + Branch Jump Expanded to + ------ ------ ------------ + bbc chkbit; bno + bbs chkbit; bo + cmpibe cmpije cmpi; be + cmpibg cmpijg cmpi; bg + cmpibge cmpijge cmpi; bge + cmpibl cmpijl cmpi; bl + cmpible cmpijle cmpi; ble + cmpibno cmpijno cmpi; bno + cmpibne cmpijne cmpi; bne + cmpibo cmpijo cmpi; bo + cmpobe cmpoje cmpo; be + cmpobg cmpojg cmpo; bg + cmpobge cmpojge cmpo; bge + cmpobl cmpojl cmpo; bl + cmpoble cmpojle cmpo; ble + cmpobne cmpojne cmpo; bne +@end example +@c TEXI2ROFF-KILL +@end ifinfo +@tex +\hskip\tableindent +\halign{\hfil {\tt #}\quad&\hfil {\tt #}\qquad&{\tt #}\hfil\cr +\omit{\hfil\it Compare and\hfil}\span\omit&\cr +{\it Branch}&{\it Jump}&{\it Expanded to}\cr + bbc& & chkbit; bno\cr + bbs& & chkbit; bo\cr + cmpibe& cmpije& cmpi; be\cr + cmpibg& cmpijg& cmpi; bg\cr + cmpibge& cmpijge& cmpi; bge\cr + cmpibl& cmpijl& cmpi; bl\cr + cmpible& cmpijle& cmpi; ble\cr + cmpibno& cmpijno& cmpi; bno\cr + cmpibne& cmpijne& cmpi; bne\cr + cmpibo& cmpijo& cmpi; bo\cr + cmpobe& cmpoje& cmpo; be\cr + cmpobg& cmpojg& cmpo; bg\cr + cmpobge& cmpojge& cmpo; bge\cr + cmpobl& cmpojl& cmpo; bl\cr + cmpoble& cmpojle& cmpo; ble\cr + cmpobne& cmpojne& cmpo; bne\cr} +@end tex +@c END TEXI2ROFF-KILL +_fi__(_I960__) + +_if__(_M680X0__) +_if__(_GENERIC__) +@c FIXME! node conds are only sufficient for m68k alone, all, and vintage +_if__(_I960__) +@node M68K-Dependent, Sparc-Dependent, i960-Dependent, Machine Dependent +_fi__(_I960__) +_if__(!_I960__) +@node M68K-Dependent, Sparc-Dependent, Machine Dependent, Machine Dependent +_fi__(!_I960__) +_fi__(_GENERIC__) +_CHAPSEC__(0+_GENERIC__) M680x0 Dependent Features + +@cindex M680x0 support +@menu +* M68K-Opts:: M680x0 Options +* M68K-Syntax:: Syntax +* M68K-Float:: Floating Point +* M68K-Directives:: 680x0 Machine Directives +* M68K-opcodes:: Opcodes +@end menu + +@node M68K-Opts, M68K-Syntax, M68K-Dependent, M68K-Dependent +_CHAPSEC__(1+_GENERIC__) M680x0 Options + +@cindex options, M680x0 +@cindex M680x0 options +The Motorola 680x0 version of @code{_AS__} has two machine dependent options. +One shortens undefined references from 32 to 16 bits, while the +other is used to tell @code{_AS__} what kind of machine it is +assembling for. + +@cindex @code{-l} option, M680x0 +You can use the @kbd{-l} option to shorten the size of references to +undefined symbols. If the @kbd{-l} option is not given, references to +undefined symbols will be a full long (32 bits) wide. (Since @code{_AS__} +cannot know where these symbols will end up, @code{_AS__} can only allocate +space for the linker to fill in later. Since @code{_AS__} doesn't know how +far away these symbols will be, it allocates as much space as it can.) +If this option is given, the references will only be one word wide (16 +bits). This may be useful if you want the object file to be as small as +possible, and you know that the relevant symbols will be less than 17 +bits away. + +@cindex @code{-m68000} and related options, M680x0 +@cindex architecture options, M680x0 +@cindex M680x0 architecture options +The 680x0 version of @code{_AS__} is most frequently used to assemble +programs for the Motorola MC68020 microprocessor. Occasionally it is +used to assemble programs for the mostly similar, but slightly different +MC68000 or MC68010 microprocessors. You can give @code{_AS__} the options +@samp{-m68000}, @samp{-mc68000}, @samp{-m68010}, @samp{-mc68010}, +@samp{-m68020}, and @samp{-mc68020} to tell it what processor is the +target. + +@node M68K-Syntax, M68K-Float, M68K-Opts, M68K-Dependent +_CHAPSEC__(1+_GENERIC__) Syntax + +@cindex M680x0 syntax +@cindex syntax, M680x0 +@cindex M680x0 size modifiers +@cindex size modifiers, M680x0 +The 680x0 version of @code{_AS__} uses syntax similar to the Sun assembler. +Size modifiers are appended directly to the end of the opcode without an +intervening period. For example, write @samp{movl} rather than +@samp{move.l}. + +_if__(_INTERNALS__) +If @code{_AS__} is compiled with SUN_ASM_SYNTAX defined, it will also allow +Sun-style local labels of the form @samp{1$} through @samp{$9}. +_fi__(_INTERNALS__) + +In the following table @dfn{apc} stands for any of the address +registers (@samp{a0} through @samp{a7}), nothing, (@samp{}), the +Program Counter (@samp{pc}), or the zero-address relative to the +program counter (@samp{zpc}). + +@cindex M680x0 addressing modes +@cindex addressing modes, M680x0 +The following addressing modes are understood: +@table @dfn +@item Immediate +@samp{#@var{digits}} + +@item Data Register +@samp{d0} through @samp{d7} + +@item Address Register +@samp{a0} through @samp{a7} + +@item Address Register Indirect +@samp{a0@@} through @samp{a7@@} + +@item Address Register Postincrement +@samp{a0@@+} through @samp{a7@@+} + +@item Address Register Predecrement +@samp{a0@@-} through @samp{a7@@-} + +@item Indirect Plus Offset +@samp{@var{apc}@@(@var{digits})} + +@item Index +@samp{@var{apc}@@(@var{digits},@var{register}:@var{size}:@var{scale})} + +or @samp{@var{apc}@@(@var{register}:@var{size}:@var{scale})} + +@item Postindex +@samp{@var{apc}@@(@var{digits})@@(@var{digits},@var{register}:@var{size}:@var{scale})} + +or @samp{@var{apc}@@(@var{digits})@@(@var{register}:@var{size}:@var{scale})} + +@item Preindex +@samp{@var{apc}@@(@var{digits},@var{register}:@var{size}:@var{scale})@@(@var{digits})} + +or @samp{@var{apc}@@(@var{register}:@var{size}:@var{scale})@@(@var{digits})} + +@item Memory Indirect +@samp{@var{apc}@@(@var{digits})@@(@var{digits})} + +@item Absolute +@samp{@var{symbol}}, or @samp{@var{digits}} +@ignore +@c pesch@cygnus.com: gnu, rich concur the following needs careful +@c research before documenting. + , or either of the above followed +by @samp{:b}, @samp{:w}, or @samp{:l}. +@end ignore +@end table + +@node M68K-Float, M68K-Directives, M68K-Syntax, M68K-Dependent +_CHAPSEC__(1+_GENERIC__) Floating Point + +@cindex floating point, M680x0 +@cindex M680x0 floating point +@c FIXME is this "not too well tested" crud STILL true? +The floating point code is not too well tested, and may have +subtle bugs in it. + +Packed decimal (P) format floating literals are not supported. +Feel free to add the code! + +The floating point formats generated by directives are these. + +@table @code +@item .float +@cindex @code{float} directive, M680x0 +@code{Single} precision floating point constants. + +@item .double +@cindex @code{double} directive, M680x0 +@code{Double} precision floating point constants. +@end table + +There is no directive to produce regions of memory holding +extended precision numbers, however they can be used as +immediate operands to floating-point instructions. Adding a +directive to create extended precision numbers would not be +hard, but it has not yet seemed necessary. + +@node M68K-Directives, M68K-opcodes, M68K-Float, M68K-Dependent +_CHAPSEC__(1+_GENERIC__) 680x0 Machine Directives + +@cindex M680x0 directives +@cindex directives, M680x0 +In order to be compatible with the Sun assembler the 680x0 assembler +understands the following directives. + +@table @code +@item .data1 +@cindex @code{data1} directive, M680x0 +This directive is identical to a @code{.data 1} directive. + +@item .data2 +@cindex @code{data2} directive, M680x0 +This directive is identical to a @code{.data 2} directive. + +@item .even +@cindex @code{even} directive, M680x0 +This directive is identical to a @code{.align 1} directive. +@c Is this true? does it work??? + +@item .skip +@cindex @code{skip} directive, M680x0 +This directive is identical to a @code{.space} directive. +@end table + +@node M68K-opcodes, , M68K-Directives, M68K-Dependent +_CHAPSEC__(1+_GENERIC__) Opcodes + +@cindex M680x0 opcodes +@cindex opcodes, M680x0 +@cindex instruction set, M680x0 +@c pesch@cygnus.com: I don't see any point in the following +@c paragraph. Bugs are bugs; how does saying this +@c help anyone? +@ignore +Danger: Several bugs have been found in the opcode table (and +fixed). More bugs may exist. Be careful when using obscure +instructions. +@end ignore + +@menu +* M68K-Branch:: Branch Improvement +* M68K-Chars:: Special Characters +@end menu + +@node M68K-Branch, M68K-Chars, M68K-opcodes, M68K-opcodes +_CHAPSEC__(2+_GENERIC__) Branch Improvement + +@cindex pseudo-opcodes, M680x0 +@cindex M680x0 pseudo-opcodes +@cindex branch improvement, M680x0 +@cindex M680x0 branch improvement +Certain pseudo opcodes are permitted for branch instructions. +They expand to the shortest branch instruction that will reach the +target. Generally these mnemonics are made by substituting @samp{j} for +@samp{b} at the start of a Motorola mnemonic. + +The following table summarizes the pseudo-operations. A @code{*} flags +cases that are more fully described after the table: + +@smallexample + Displacement + +--------------------------------------------------------- + | 68020 68000/10 +Pseudo-Op |BYTE WORD LONG LONG non-PC relative + +--------------------------------------------------------- + jbsr |bsrs bsr bsrl jsr jsr + jra |bras bra bral jmp jmp +* jXX |bXXs bXX bXXl bNXs;jmpl bNXs;jmp +* dbXX |dbXX dbXX dbXX; bra; jmpl +* fjXX |fbXXw fbXXw fbXXl fbNXw;jmp + +XX: condition +NX: negative of condition XX + +@end smallexample +@center @code{*}---see full description below + +@table @code +@item jbsr +@itemx jra +These are the simplest jump pseudo-operations; they always map to one +particular machine instruction, depending on the displacement to the +branch target. + +@item j@var{XX} +Here, @samp{j@var{XX}} stands for an entire family of pseudo-operations, +where @var{XX} is a conditional branch or condition-code test. The full +list of pseudo-ops in this family is: +@smallexample + jhi jls jcc jcs jne jeq jvc + jvs jpl jmi jge jlt jgt jle +@end smallexample + +For the cases of non-PC relative displacements and long displacements on +the 68000 or 68010, @code{_AS__} will issue a longer code fragment in terms of +@var{NX}, the opposite condition to @var{XX}: +@smallexample + j@var{XX} foo +@end smallexample +gives +@smallexample + b@var{NX}s oof + jmp foo + oof: +@end smallexample + +@item db@var{XX} +The full family of pseudo-operations covered here is +@smallexample + dbhi dbls dbcc dbcs dbne dbeq dbvc + dbvs dbpl dbmi dbge dblt dbgt dble + dbf dbra dbt +@end smallexample + +Other than for word and byte displacements, when the source reads +@samp{db@var{XX} foo}, @code{_AS__} will emit +@smallexample + db@var{XX} oo1 + bra oo2 + oo1:jmpl foo + oo2: +@end smallexample + +@item fj@var{XX} +This family includes +@smallexample + fjne fjeq fjge fjlt fjgt fjle fjf + fjt fjgl fjgle fjnge fjngl fjngle fjngt + fjnle fjnlt fjoge fjogl fjogt fjole fjolt + fjor fjseq fjsf fjsne fjst fjueq fjuge + fjugt fjule fjult fjun +@end smallexample + +For branch targets that are not PC relative, @code{_AS__} emits +@smallexample + fb@var{NX} oof + jmp foo + oof: +@end smallexample +when it encounters @samp{fj@var{XX} foo}. + +@end table + +@node M68K-Chars, , M68K-Branch, M68K-opcodes +_CHAPSEC__(2+_GENERIC__) Special Characters + +@cindex special characters, M680x0 +@cindex M680x0 immediate character +@cindex immediate character, M680x0 +@cindex M680x0 line comment character +@cindex line comment character, M680x0 +@cindex comments, M680x0 +The immediate character is @samp{#} for Sun compatibility. The +line-comment character is @samp{|}. If a @samp{#} appears at the +beginning of a line, it is treated as a comment unless it looks like +@samp{# line file}, in which case it is treated normally. + +_fi__(_M680X0__) +_if__(0) +@c pesch@cygnus.com: conditionalize on something other than 0 when filled in. +@section 32x32 +@section Options +The 32x32 version of @code{_AS__} accepts a @kbd{-m32032} option to +specify thiat it is compiling for a 32032 processor, or a +@kbd{-m32532} to specify that it is compiling for a 32532 option. +The default (if neither is specified) is chosen when the assembler +is compiled. + +@subsection Syntax +I don't know anything about the 32x32 syntax assembled by +@code{_AS__}. Someone who undersands the processor (I've never seen +one) and the possible syntaxes should write this section. + +@subsection Floating Point +The 32x32 uses @sc{ieee} floating point numbers, but @code{_AS__} will only +create single or double precision values. I don't know if the 32x32 +understands extended precision numbers. + +@subsection 32x32 Machine Directives +The 32x32 has no machine dependent directives. + +_fi__(0) +_if__(_SPARC__) +_if__(_GENERIC__) +_if__(_I80386__&&_M680X0__) +@node Sparc-Dependent, i386-Dependent, M68K-Dependent, Machine Dependent +_fi__(_I80386__&&_M680X0__) +_if__(_I80386__&&_I960__&&!_M680X0__) +@node Sparc-Dependent, i386-Dependent, i960-Dependent, Machine Dependent +_fi__(_I80386__&&_I960__&&!_M680X0__) +_if__(_I80386__&&_A29K__&&(!_I960__)&&!_M680X0__) +@node Sparc-Dependent, i386-Dependent, AMD29K-Dependent, Machine Dependent +_fi__(_I80386__&&_A29K__&&(!_I960__)&&!_M680X0__) +_if__(_I80386__&&_VAX__&&(!_A29K__)&&(!_I960__)&&!_M680X0__) +@node Sparc-Dependent, i386-Dependent, Vax-Dependent, Machine Dependent +_fi__(_I80386__&&_VAX__&&(!_A29K__)&&(!_I960__)&&!_M680X0__) +_if__(_I80386__&&(!_VAX__)&&(!_A29K__)&&(!_I960__)&&!_M680X0__) +@node Sparc-Dependent, i386-Dependent, Machine Dependent, Machine Dependent +_fi__(_I80386__&&(!_VAX__)&&(!_A29K__)&&(!_I960__)&&!_M680X0__) +_if__((!_I80386__)&&_M680X0__) +@node Sparc-Dependent, , M68K-Dependent, Machine Dependent +_fi__((!_I80386__)&&_M680X0__) +_if__((!_I80386__)&&_I960__&&!_M680X0__) +@node Sparc-Dependent, , i960-Dependent, Machine Dependent +_fi__((!_I80386__)&&_I960__&&!_M680X0__) +_if__((!_I80386__)&&_A29K__&&(!_I960__)&&!_M680X0__) +@node Sparc-Dependent, , AMD29K-Dependent, Machine Dependent +_fi__((!_I80386__)&&_A29K__&&(!_I960__)&&!_M680X0__) +_if__((!_I80386__)&&_VAX__&&(!_A29K__)&&(!_I960__)&&!_M680X0__) +@node Sparc-Dependent, , Vax-Dependent, Machine Dependent +_fi__((!_I80386__)&&_VAX__&&(!_A29K__)&&(!_I960__)&&!_M680X0__) +_if__((!_I80386__)&&(!_VAX__)&&(!_A29K__)&&(!_I960__)&&!_M680X0__) +@node Sparc-Dependent, , Machine Dependent, Machine Dependent +_fi__((!_I80386__)&&(!_VAX__)&&(!_A29K__)&&(!_I960__)&&!_M680X0__) +_fi__(_GENERIC__) +_CHAPSEC__(0+_GENERIC__) SPARC Dependent Features + +@cindex SPARC support +@menu +* Sparc-Opts:: Options +* Sparc-Float:: Floating Point +* Sparc-Directives:: Sparc Machine Directives +@end menu + +@node Sparc-Opts, Sparc-Float, Sparc-Dependent, Sparc-Dependent +_CHAPSEC__(1+_GENERIC__) Options + +@cindex options for SPARC (none) +@cindex SPARC options (none) +The Sparc has no machine dependent options. + +@ignore +@c FIXME: (sparc) Fill in "syntax" section! +@c subsection syntax +I don't know anything about Sparc syntax. Someone who does +will have to write this section. +@end ignore + +@node Sparc-Float, Sparc-Directives, Sparc-Opts, Sparc-Dependent +_CHAPSEC__(1+_GENERIC__) Floating Point + +@cindex floating point, SPARC (@sc{ieee}) +@cindex SPARC floating point (@sc{ieee}) +The Sparc uses @sc{ieee} floating-point numbers. + +@node Sparc-Directives, , Sparc-Float, Sparc-Dependent +_CHAPSEC__(1+_GENERIC__) Sparc Machine Directives + +@cindex SPARC machine directives +@cindex machine directives, SPARC +The Sparc version of @code{_AS__} supports the following additional +machine directives: + +@table @code +@item .common +@cindex @code{common} directive, SPARC +This must be followed by a symbol name, a positive number, and +@code{"bss"}. This behaves somewhat like @code{.comm}, but the +syntax is different. + +@item .half +@cindex @code{half} directive, SPARC +This is functionally identical to @code{.short}. + +@item .proc +@cindex @code{proc} directive, SPARC +This directive is ignored. Any text following it on the same +line is also ignored. + +@item .reserve +@cindex @code{reserve} directive, SPARC +This must be followed by a symbol name, a positive number, and +@code{"bss"}. This behaves somewhat like @code{.lcomm}, but the +syntax is different. + +@item .seg +@cindex @code{seg} directive, SPARC +This must be followed by @code{"text"}, @code{"data"}, or +@code{"data1"}. It behaves like @code{.text}, @code{.data}, or +@code{.data 1}. + +@item .skip +@cindex @code{skip} directive, SPARC +This is functionally identical to the @code{.space} directive. + +@item .word +@cindex @code{word} directive, SPARC +On the Sparc, the .word directive produces 32 bit values, +instead of the 16 bit values it produces on many other machines. +@end table + +_fi__(_SPARC__) +_if__(_I80386__) +_if__(_GENERIC__) +@c FIXME! Conditionalize for all combinations in this section +@node i386-Dependent, , Sparc-Dependent, Machine Dependent +_fi__(_GENERIC__) +_CHAPSEC__(0+_GENERIC__) 80386 Dependent Features + +@cindex i386 support +@cindex i80306 support +@menu +* i386-Options:: Options +* i386-Syntax:: AT&T Syntax versus Intel Syntax +* i386-Opcodes:: Opcode Naming +* i386-Regs:: Register Naming +* i386-prefixes:: Opcode Prefixes +* i386-Memory:: Memory References +* i386-jumps:: Handling of Jump Instructions +* i386-Float:: Floating Point +* i386-Notes:: Notes +@end menu + +@node i386-Options, i386-Syntax, i386-Dependent, i386-Dependent +_CHAPSEC__(1+_GENERIC__) Options + +@cindex options for i386 (none) +@cindex i386 options (none) +The 80386 has no machine dependent options. + +@node i386-Syntax, i386-Opcodes, i386-Options, i386-Dependent +_CHAPSEC__(1+_GENERIC__) AT&T Syntax versus Intel Syntax + +@cindex i386 syntax compatibility +@cindex syntax compatibility, i386 +In order to maintain compatibility with the output of @code{_GCC__}, +@code{_AS__} supports AT&T System V/386 assembler syntax. This is quite +different from Intel syntax. We mention these differences because +almost all 80386 documents used only Intel syntax. Notable differences +between the two syntaxes are: + +@itemize @bullet +@item +@cindex immediate operands, i386 +@cindex i386 immediate operands +@cindex register operands, i386 +@cindex i386 register operands +@cindex jump/call operands, i386 +@cindex i386 jump/call operands +@cindex operand delimiters, i386 +AT&T immediate operands are preceded by @samp{$}; Intel immediate +operands are undelimited (Intel @samp{push 4} is AT&T @samp{pushl $4}). +AT&T register operands are preceded by @samp{%}; Intel register operands +are undelimited. AT&T absolute (as opposed to PC relative) jump/call +operands are prefixed by @samp{*}; they are undelimited in Intel syntax. + +@item +@cindex i386 source, destination operands +@cindex source, destination operands; i386 +AT&T and Intel syntax use the opposite order for source and destination +operands. Intel @samp{add eax, 4} is @samp{addl $4, %eax}. The +@samp{source, dest} convention is maintained for compatibility with +previous Unix assemblers. + +@item +@cindex opcode suffixes, i386 +@cindex sizes operands, i386 +@cindex i386 size suffixes +In AT&T syntax the size of memory operands is determined from the last +character of the opcode name. Opcode suffixes of @samp{b}, @samp{w}, +and @samp{l} specify byte (8-bit), word (16-bit), and long (32-bit) +memory references. Intel syntax accomplishes this by prefixes memory +operands (@emph{not} the opcodes themselves) with @samp{byte ptr}, +@samp{word ptr}, and @samp{dword ptr}. Thus, Intel @samp{mov al, byte +ptr @var{foo}} is @samp{movb @var{foo}, %al} in AT&T syntax. + +@item +@cindex return instructions, i386 +@cindex i386 jump, call, return +Immediate form long jumps and calls are +@samp{lcall/ljmp $@var{section}, $@var{offset}} in AT&T syntax; the +Intel syntax is +@samp{call/jmp far @var{section}:@var{offset}}. Also, the far return +instruction +is @samp{lret $@var{stack-adjust}} in AT&T syntax; Intel syntax is +@samp{ret far @var{stack-adjust}}. + +@item +@cindex sections, i386 +@cindex i386 sections +The AT&T assembler does not provide support for multiple section +programs. Unix style systems expect all programs to be single sections. +@end itemize + +@node i386-Opcodes, i386-Regs, i386-Syntax, i386-Dependent +_CHAPSEC__(1+_GENERIC__) Opcode Naming + +@cindex i386 opcode naming +@cindex opcode naming, i386 +Opcode names are suffixed with one character modifiers which specify the +size of operands. The letters @samp{b}, @samp{w}, and @samp{l} specify +byte, word, and long operands. If no suffix is specified by an +instruction and it contains no memory operands then @code{_AS__} tries to +fill in the missing suffix based on the destination register operand +(the last one by convention). Thus, @samp{mov %ax, %bx} is equivalent +to @samp{movw %ax, %bx}; also, @samp{mov $1, %bx} is equivalent to +@samp{movw $1, %bx}. Note that this is incompatible with the AT&T Unix +assembler which assumes that a missing opcode suffix implies long +operand size. (This incompatibility does not affect compiler output +since compilers always explicitly specify the opcode suffix.) + +Almost all opcodes have the same names in AT&T and Intel format. There +are a few exceptions. The sign extend and zero extend instructions need +two sizes to specify them. They need a size to sign/zero extend +@emph{from} and a size to zero extend @emph{to}. This is accomplished +by using two opcode suffixes in AT&T syntax. Base names for sign extend +and zero extend are @samp{movs@dots{}} and @samp{movz@dots{}} in AT&T +syntax (@samp{movsx} and @samp{movzx} in Intel syntax). The opcode +suffixes are tacked on to this base name, the @emph{from} suffix before +the @emph{to} suffix. Thus, @samp{movsbl %al, %edx} is AT&T syntax for +``move sign extend @emph{from} %al @emph{to} %edx.'' Possible suffixes, +thus, are @samp{bl} (from byte to long), @samp{bw} (from byte to word), +and @samp{wl} (from word to long). + +@cindex conversion instructions, i386 +@cindex i386 conversion instructions +The Intel-syntax conversion instructions + +@itemize @bullet +@item +@samp{cbw} --- sign-extend byte in @samp{%al} to word in @samp{%ax}, + +@item +@samp{cwde} --- sign-extend word in @samp{%ax} to long in @samp{%eax}, + +@item +@samp{cwd} --- sign-extend word in @samp{%ax} to long in @samp{%dx:%ax}, + +@item +@samp{cdq} --- sign-extend dword in @samp{%eax} to quad in @samp{%edx:%eax}, +@end itemize + +@noindent +are called @samp{cbtw}, @samp{cwtl}, @samp{cwtd}, and @samp{cltd} in +AT&T naming. @code{_AS__} accepts either naming for these instructions. + +@cindex jump instructions, i386 +@cindex call instructions, i386 +Far call/jump instructions are @samp{lcall} and @samp{ljmp} in +AT&T syntax, but are @samp{call far} and @samp{jump far} in Intel +convention. + +@node i386-Regs, i386-prefixes, i386-Opcodes, i386-Dependent +_CHAPSEC__(1+_GENERIC__) Register Naming + +@cindex i386 registers +@cindex registers, i386 +Register operands are always prefixes with @samp{%}. The 80386 registers +consist of + +@itemize @bullet +@item +the 8 32-bit registers @samp{%eax} (the accumulator), @samp{%ebx}, +@samp{%ecx}, @samp{%edx}, @samp{%edi}, @samp{%esi}, @samp{%ebp} (the +frame pointer), and @samp{%esp} (the stack pointer). + +@item +the 8 16-bit low-ends of these: @samp{%ax}, @samp{%bx}, @samp{%cx}, +@samp{%dx}, @samp{%di}, @samp{%si}, @samp{%bp}, and @samp{%sp}. + +@item +the 8 8-bit registers: @samp{%ah}, @samp{%al}, @samp{%bh}, +@samp{%bl}, @samp{%ch}, @samp{%cl}, @samp{%dh}, and @samp{%dl} (These +are the high-bytes and low-bytes of @samp{%ax}, @samp{%bx}, +@samp{%cx}, and @samp{%dx}) + +@item +the 6 section registers @samp{%cs} (code section), @samp{%ds} +(data section), @samp{%ss} (stack section), @samp{%es}, @samp{%fs}, +and @samp{%gs}. + +@item +the 3 processor control registers @samp{%cr0}, @samp{%cr2}, and +@samp{%cr3}. + +@item +the 6 debug registers @samp{%db0}, @samp{%db1}, @samp{%db2}, +@samp{%db3}, @samp{%db6}, and @samp{%db7}. + +@item +the 2 test registers @samp{%tr6} and @samp{%tr7}. + +@item +the 8 floating point register stack @samp{%st} or equivalently +@samp{%st(0)}, @samp{%st(1)}, @samp{%st(2)}, @samp{%st(3)}, +@samp{%st(4)}, @samp{%st(5)}, @samp{%st(6)}, and @samp{%st(7)}. +@end itemize + +@node i386-prefixes, i386-Memory, i386-Regs, i386-Dependent +_CHAPSEC__(1+_GENERIC__) Opcode Prefixes + +@cindex i386 opcode prefixes +@cindex opcode prefixes, i386 +@cindex prefixes, i386 +Opcode prefixes are used to modify the following opcode. They are used +to repeat string instructions, to provide section overrides, to perform +bus lock operations, and to give operand and address size (16-bit +operands are specified in an instruction by prefixing what would +normally be 32-bit operands with a ``operand size'' opcode prefix). +Opcode prefixes are usually given as single-line instructions with no +operands, and must directly precede the instruction they act upon. For +example, the @samp{scas} (scan string) instruction is repeated with: +@smallexample + repne + scas +@end smallexample + +Here is a list of opcode prefixes: + +@itemize @bullet +@item +@cindex section override prefixes, i386 +Section override prefixes @samp{cs}, @samp{ds}, @samp{ss}, @samp{es}, +@samp{fs}, @samp{gs}. These are automatically added by specifying +using the @var{section}:@var{memory-operand} form for memory references. + +@item +@cindex size prefixes, i386 +Operand/Address size prefixes @samp{data16} and @samp{addr16} +change 32-bit operands/addresses into 16-bit operands/addresses. Note +that 16-bit addressing modes (i.e. 8086 and 80286 addressing modes) +are not supported (yet). + +@item +@cindex bus lock prefixes, i386 +@cindex inhibiting interrupts, i386 +The bus lock prefix @samp{lock} inhibits interrupts during +execution of the instruction it precedes. (This is only valid with +certain instructions; see a 80386 manual for details). + +@item +@cindex coprocessor wait, i386 +The wait for coprocessor prefix @samp{wait} waits for the +coprocessor to complete the current instruction. This should never be +needed for the 80386/80387 combination. + +@item +@cindex repeat prefixes, i386 +The @samp{rep}, @samp{repe}, and @samp{repne} prefixes are added +to string instructions to make them repeat @samp{%ecx} times. +@end itemize + +@node i386-Memory, i386-jumps, i386-prefixes, i386-Dependent +_CHAPSEC__(1+_GENERIC__) Memory References + +@cindex i386 memory references +@cindex memory references, i386 +An Intel syntax indirect memory reference of the form + +@smallexample +@var{section}:[@var{base} + @var{index}*@var{scale} + @var{disp}] +@end smallexample + +@noindent +is translated into the AT&T syntax + +@smallexample +@var{section}:@var{disp}(@var{base}, @var{index}, @var{scale}) +@end smallexample + +@noindent +where @var{base} and @var{index} are the optional 32-bit base and +index registers, @var{disp} is the optional displacement, and +@var{scale}, taking the values 1, 2, 4, and 8, multiplies @var{index} +to calculate the address of the operand. If no @var{scale} is +specified, @var{scale} is taken to be 1. @var{section} specifies the +optional section register for the memory operand, and may override the +default section register (see a 80386 manual for section register +defaults). Note that section overrides in AT&T syntax @emph{must} have +be preceded by a @samp{%}. If you specify a section override which +coincides with the default section register, @code{_AS__} will @emph{not} +output any section register override prefixes to assemble the given +instruction. Thus, section overrides can be specified to emphasize which +section register is used for a given memory operand. + +Here are some examples of Intel and AT&T style memory references: + +@table @asis +@item AT&T: @samp{-4(%ebp)}, Intel: @samp{[ebp - 4]} +@var{base} is @samp{%ebp}; @var{disp} is @samp{-4}. @var{section} is +missing, and the default section is used (@samp{%ss} for addressing with +@samp{%ebp} as the base register). @var{index}, @var{scale} are both missing. + +@item AT&T: @samp{foo(,%eax,4)}, Intel: @samp{[foo + eax*4]} +@var{index} is @samp{%eax} (scaled by a @var{scale} 4); @var{disp} is +@samp{foo}. All other fields are missing. The section register here +defaults to @samp{%ds}. + +@item AT&T: @samp{foo(,1)}; Intel @samp{[foo]} +This uses the value pointed to by @samp{foo} as a memory operand. +Note that @var{base} and @var{index} are both missing, but there is only +@emph{one} @samp{,}. This is a syntactic exception. + +@item AT&T: @samp{%gs:foo}; Intel @samp{gs:foo} +This selects the contents of the variable @samp{foo} with section +register @var{section} being @samp{%gs}. +@end table + +Absolute (as opposed to PC relative) call and jump operands must be +prefixed with @samp{*}. If no @samp{*} is specified, @code{_AS__} will +always choose PC relative addressing for jump/call labels. + +Any instruction that has a memory operand @emph{must} specify its size (byte, +word, or long) with an opcode suffix (@samp{b}, @samp{w}, or @samp{l}, +respectively). + +@node i386-jumps, i386-Float, i386-Memory, i386-Dependent +_CHAPSEC__(1+_GENERIC__) Handling of Jump Instructions + +@cindex jump optimization, i386 +@cindex i386 jump optimization +Jump instructions are always optimized to use the smallest possible +displacements. This is accomplished by using byte (8-bit) displacement +jumps whenever the target is sufficiently close. If a byte displacement +is insufficient a long (32-bit) displacement is used. We do not support +word (16-bit) displacement jumps (i.e. prefixing the jump instruction +with the @samp{addr16} opcode prefix), since the 80386 insists upon masking +@samp{%eip} to 16 bits after the word displacement is added. + +Note that the @samp{jcxz}, @samp{jecxz}, @samp{loop}, @samp{loopz}, +@samp{loope}, @samp{loopnz} and @samp{loopne} instructions only come in +byte displacements, so that it is possible that use of these +instructions (@code{_GCC__} does not use them) will cause the assembler to +print an error message (and generate incorrect code). The AT&T 80386 +assembler tries to get around this problem by expanding @samp{jcxz foo} to +@smallexample + jcxz cx_zero + jmp cx_nonzero +cx_zero: jmp foo +cx_nonzero: +@end smallexample + +@node i386-Float, i386-Notes, i386-jumps, i386-Dependent +_CHAPSEC__(1+_GENERIC__) Floating Point + +@cindex i386 floating point +@cindex floating point, i386 +All 80387 floating point types except packed BCD are supported. +(BCD support may be added without much difficulty). These data +types are 16-, 32-, and 64- bit integers, and single (32-bit), +double (64-bit), and extended (80-bit) precision floating point. +Each supported type has an opcode suffix and a constructor +associated with it. Opcode suffixes specify operand's data +types. Constructors build these data types into memory. + +@itemize @bullet +@item +@cindex @code{float} directive, i386 +@cindex @code{single} directive, i386 +@cindex @code{double} directive, i386 +@cindex @code{tfloat} directive, i386 +Floating point constructors are @samp{.float} or @samp{.single}, +@samp{.double}, and @samp{.tfloat} for 32-, 64-, and 80-bit formats. +These correspond to opcode suffixes @samp{s}, @samp{l}, and @samp{t}. +@samp{t} stands for temporary real, and that the 80387 only supports +this format via the @samp{fldt} (load temporary real to stack top) and +@samp{fstpt} (store temporary real and pop stack) instructions. + +@item +@cindex @code{word} directive, i386 +@cindex @code{long} directive, i386 +@cindex @code{int} directive, i386 +@cindex @code{quad} directive, i386 +Integer constructors are @samp{.word}, @samp{.long} or @samp{.int}, and +@samp{.quad} for the 16-, 32-, and 64-bit integer formats. The corresponding +opcode suffixes are @samp{s} (single), @samp{l} (long), and @samp{q} +(quad). As with the temporary real format the 64-bit @samp{q} format is +only present in the @samp{fildq} (load quad integer to stack top) and +@samp{fistpq} (store quad integer and pop stack) instructions. +@end itemize + +Register to register operations do not require opcode suffixes, +so that @samp{fst %st, %st(1)} is equivalent to @samp{fstl %st, %st(1)}. + +@cindex i386 @code{fwait} instruction +@cindex @code{fwait instruction}, i386 +Since the 80387 automatically synchronizes with the 80386 @samp{fwait} +instructions are almost never needed (this is not the case for the +80286/80287 and 8086/8087 combinations). Therefore, @code{_AS__} suppresses +the @samp{fwait} instruction whenever it is implicitly selected by one +of the @samp{fn@dots{}} instructions. For example, @samp{fsave} and +@samp{fnsave} are treated identically. In general, all the @samp{fn@dots{}} +instructions are made equivalent to @samp{f@dots{}} instructions. If +@samp{fwait} is desired it must be explicitly coded. + +@node i386-Notes, , i386-Float, i386-Dependent +_CHAPSEC__(1+_GENERIC__) Notes + +@cindex i386 @code{mul}, @code{imul} instructions +@cindex @code{mul} instruction, i386 +@cindex @code{imul} instruction, i386 +There is some trickery concerning the @samp{mul} and @samp{imul} +instructions that deserves mention. The 16-, 32-, and 64-bit expanding +multiplies (base opcode @samp{0xf6}; extension 4 for @samp{mul} and 5 +for @samp{imul}) can be output only in the one operand form. Thus, +@samp{imul %ebx, %eax} does @emph{not} select the expanding multiply; +the expanding multiply would clobber the @samp{%edx} register, and this +would confuse @code{_GCC__} output. Use @samp{imul %ebx} to get the +64-bit product in @samp{%edx:%eax}. + +We have added a two operand form of @samp{imul} when the first operand +is an immediate mode expression and the second operand is a register. +This is just a shorthand, so that, multiplying @samp{%eax} by 69, for +example, can be done with @samp{imul $69, %eax} rather than @samp{imul +$69, %eax, %eax}. + +_fi__(_I80386__) +_if__(0) +@c pesch@cygnus.com: we ignore the following chapters, since internals are +@c changing rapidly. These may need to be moved to another +@c book anyhow, if we adopt the model of user/modifier +@c books. +@node Maintenance, Retargeting, _MACH_DEP__, Top +@chapter Maintaining the Assembler +[[this chapter is still being built]] + +@section Design +We had these goals, in descending priority: +@table @b +@item Accuracy. +For every program composed by a compiler, @code{_AS__} should emit +``correct'' code. This leaves some latitude in choosing addressing +modes, order of @code{relocation_info} structures in the object +file, @emph{etc}. + +@item Speed, for usual case. +By far the most common use of @code{_AS__} will be assembling compiler +emissions. + +@item Upward compatibility for existing assembler code. +Well @dots{} we don't support Vax bit fields but everything else +seems to be upward compatible. + +@item Readability. +The code should be maintainable with few surprises. (JF: ha!) + +@end table + +We assumed that disk I/O was slow and expensive while memory was +fast and access to memory was cheap. We expect the in-memory data +structures to be less than 10 times the size of the emitted object +file. (Contrast this with the C compiler where in-memory structures +might be 100 times object file size!) +This suggests: +@itemize @bullet +@item +Try to read the source file from disk only one time. For other +reasons, we keep large chunks of the source file in memory during +assembly so this is not a problem. Also the assembly algorithm +should only scan the source text once if the compiler composed the +text according to a few simple rules. +@item +Emit the object code bytes only once. Don't store values and then +backpatch later. +@item +Build the object file in memory and do direct writes to disk of +large buffers. +@end itemize + +RMS suggested a one-pass algorithm which seems to work well. By not +parsing text during a second pass considerable time is saved on +large programs (@emph{e.g.} the sort of C program @code{yacc} would +emit). + +It happened that the data structures needed to emit relocation +information to the object file were neatly subsumed into the data +structures that do backpatching of addresses after pass 1. + +Many of the functions began life as re-usable modules, loosely +connected. RMS changed this to gain speed. For example, input +parsing routines which used to work on pre-sanitized strings now +must parse raw data. Hence they have to import knowledge of the +assemblers' comment conventions @emph{etc}. + +@section Deprecated Feature(?)s +We have stopped supporting some features: +@itemize @bullet +@item +@code{.org} statements must have @b{defined} expressions. +@item +Vax Bit fields (@kbd{:} operator) are entirely unsupported. +@end itemize + +It might be a good idea to not support these features in a future release: +@itemize @bullet +@item +@kbd{#} should begin a comment, even in column 1. +@item +Why support the logical line & file concept any more? +@item +Subsections are a good candidate for flushing. +Depends on which compilers need them I guess. +@end itemize + +@section Bugs, Ideas, Further Work +Clearly the major improvement is DON'T USE A TEXT-READING +ASSEMBLER for the back end of a compiler. It is much faster to +interpret binary gobbledygook from a compiler's tables than to +ask the compiler to write out human-readable code just so the +assembler can parse it back to binary. + +Assuming you use @code{_AS__} for human written programs: here are +some ideas: +@itemize @bullet +@item +Document (here) @code{APP}. +@item +Take advantage of knowing no spaces except after opcode +to speed up @code{_AS__}. (Modify @code{app.c} to flush useless spaces: +only keep space/tabs at begin of line or between 2 +symbols.) +@item +Put pointers in this documentation to @file{a.out} documentation. +@item +Split the assembler into parts so it can gobble direct binary +from @emph{e.g.} @code{cc}. It is silly for@code{cc} to compose text +just so @code{_AS__} can parse it back to binary. +@item +Rewrite hash functions: I want a more modular, faster library. +@item +Clean up LOTS of code. +@item +Include all the non-@file{.c} files in the maintenance chapter. +@item +Document flonums. +@item +Implement flonum short literals. +@item +Change all talk of expression operands to expression quantities, +or perhaps to expression arguments. +@item +Implement pass 2. +@item +Whenever a @code{.text} or @code{.data} statement is seen, we close +of the current frag with an imaginary @code{.fill 0}. This is +because we only have one obstack for frags, and we can't grow new +frags for a new subsection, then go back to the old subsection and +append bytes to the old frag. All this nonsense goes away if we +give each subsection its own obstack. It makes code simpler in +about 10 places, but nobody has bothered to do it because C compiler +output rarely changes subsections (compared to ending frags with +relaxable addresses, which is common). +@end itemize + +@section Sources +@c The following files in the @file{_AS__} directory +@c are symbolic links to other files, of +@c the same name, in a different directory. +@c @itemize @bullet +@c @item +@c @file{atof_generic.c} +@c @item +@c @file{atof_vax.c} +@c @item +@c @file{flonum_const.c} +@c @item +@c @file{flonum_copy.c} +@c @item +@c @file{flonum_get.c} +@c @item +@c @file{flonum_multip.c} +@c @item +@c @file{flonum_normal.c} +@c @item +@c @file{flonum_print.c} +@c @end itemize + +Here is a list of the source files in the @file{_AS__} directory. + +@table @file +@item app.c +This contains the pre-processing phase, which deletes comments, +handles whitespace, etc. This was recently re-written, since app +used to be a separate program, but RMS wanted it to be inline. + +@item append.c +This is a subroutine to append a string to another string returning a +pointer just after the last @code{char} appended. (JF: All these +little routines should probably all be put in one file.) + +@item as.c +Here you will find the main program of the assembler @code{_AS__}. + +@item expr.c +This is a branch office of @file{read.c}. This understands +expressions, arguments. Inside @code{_AS__}, arguments are called +(expression) @emph{operands}. This is confusing, because we also talk +(elsewhere) about instruction @emph{operands}. Also, expression +operands are called @emph{quantities} explicitly to avoid confusion +with instruction operands. What a mess. + +@item frags.c +This implements the @b{frag} concept. Without frags, finding the +right size for branch instructions would be a lot harder. + +@item hash.c +This contains the symbol table, opcode table @emph{etc.} hashing +functions. + +@item hex_value.c +This is a table of values of digits, for use in atoi() type +functions. Could probably be flushed by using calls to strtol(), or +something similar. + +@item input-file.c +This contains Operating system dependent source file reading +routines. Since error messages often say where we are in reading +the source file, they live here too. Since @code{_AS__} is intended to +run under GNU and Unix only, this might be worth flushing. Anyway, +almost all C compilers support stdio. + +@item input-scrub.c +This deals with calling the pre-processor (if needed) and feeding the +chunks back to the rest of the assembler the right way. + +@item messages.c +This contains operating system independent parts of fatal and +warning message reporting. See @file{append.c} above. + +@item output-file.c +This contains operating system dependent functions that write an +object file for @code{_AS__}. See @file{input-file.c} above. + +@item read.c +This implements all the directives of @code{_AS__}. This also deals +with passing input lines to the machine dependent part of the +assembler. + +@item strstr.c +This is a C library function that isn't in most C libraries yet. +See @file{append.c} above. + +@item subsegs.c +This implements subsections. + +@item symbols.c +This implements symbols. + +@item write.c +This contains the code to perform relaxation, and to write out +the object file. It is mostly operating system independent, but +different OSes have different object file formats in any case. + +@item xmalloc.c +This implements @code{malloc()} or bust. See @file{append.c} above. + +@item xrealloc.c +This implements @code{realloc()} or bust. See @file{append.c} above. + +@item atof-generic.c +The following files were taken from a machine-independent subroutine +library for manipulating floating point numbers and very large +integers. + +@file{atof-generic.c} turns a string into a flonum internal format +floating-point number. + +@item flonum-const.c +This contains some potentially useful floating point numbers in +flonum format. + +@item flonum-copy.c +This copies a flonum. + +@item flonum-multip.c +This multiplies two flonums together. + +@item bignum-copy.c +This copies a bignum. + +@end table + +Here is a table of all the machine-specific files (this includes +both source and header files). Typically, there is a +@var{machine}.c file, a @var{machine}-opcode.h file, and an +atof-@var{machine}.c file. The @var{machine}-opcode.h file should +be identical to the one used by GDB (which uses it for disassembly.) + +@table @file + +@item atof-ieee.c +This contains code to turn a flonum into a ieee literal constant. +This is used by tye 680x0, 32x32, sparc, and i386 versions of @code{_AS__}. + +@item i386-opcode.h +This is the opcode-table for the i386 version of the assembler. + +@item i386.c +This contains all the code for the i386 version of the assembler. + +@item i386.h +This defines constants and macros used by the i386 version of the assembler. + +@item m-generic.h +generic 68020 header file. To be linked to m68k.h on a +non-sun3, non-hpux system. + +@item m-sun2.h +68010 header file for Sun2 workstations. Not well tested. To be linked +to m68k.h on a sun2. (See also @samp{-DSUN_ASM_SYNTAX} in the +@file{Makefile}.) + +@item m-sun3.h +68020 header file for Sun3 workstations. To be linked to m68k.h before +compiling on a Sun3 system. (See also @samp{-DSUN_ASM_SYNTAX} in the +@file{Makefile}.) + +@item m-hpux.h +68020 header file for a HPUX (system 5?) box. Which box, which +version of HPUX, etc? I don't know. + +@item m68k.h +A hard- or symbolic- link to one of @file{m-generic.h}, +@file{m-hpux.h} or @file{m-sun3.h} depending on which kind of +680x0 you are assembling for. (See also @samp{-DSUN_ASM_SYNTAX} in the +@file{Makefile}.) + +@item m68k-opcode.h +Opcode table for 68020. This is now a link to the opcode table +in the @code{GDB} source directory. + +@item m68k.c +All the mc680x0 code, in one huge, slow-to-compile file. + +@item ns32k.c +This contains the code for the ns32032/ns32532 version of the +assembler. + +@item ns32k-opcode.h +This contains the opcode table for the ns32032/ns32532 version +of the assembler. + +@item vax-inst.h +Vax specific file for describing Vax operands and other Vax-ish things. + +@item vax-opcode.h +Vax opcode table. + +@item vax.c +Vax specific parts of @code{_AS__}. Also includes the former files +@file{vax-ins-parse.c}, @file{vax-reg-parse.c} and @file{vip-op.c}. + +@item atof-vax.c +Turns a flonum into a Vax constant. + +@item vms.c +This file contains the special code needed to put out a VMS +style object file for the Vax. + +@end table + +Here is a list of the header files in the source directory. +(Warning: This section may not be very accurate. I didn't +write the header files; I just report them.) Also note that I +think many of these header files could be cleaned up or +eliminated. + +@table @file + +@item a.out.h +This describes the structures used to create the binary header data +inside the object file. Perhaps we should use the one in +@file{/usr/include}? + +@item as.h +This defines all the globally useful things, and pulls in _0__<stdio.h>_1__ +and _0__<assert.h>_1__. + +@item bignum.h +This defines macros useful for dealing with bignums. + +@item expr.h +Structure and macros for dealing with expression() + +@item flonum.h +This defines the structure for dealing with floating point +numbers. It #includes @file{bignum.h}. + +@item frags.h +This contains macro for appending a byte to the current frag. + +@item hash.h +Structures and function definitions for the hashing functions. + +@item input-file.h +Function headers for the input-file.c functions. + +@item md.h +structures and function headers for things defined in the +machine dependent part of the assembler. + +@item obstack.h +This is the GNU systemwide include file for manipulating obstacks. +Since nobody is running under real GNU yet, we include this file. + +@item read.h +Macros and function headers for reading in source files. + +@item struct-symbol.h +Structure definition and macros for dealing with the _AS__ +internal form of a symbol. + +@item subsegs.h +structure definition for dealing with the numbered subsections +of the text and data sections. + +@item symbols.h +Macros and function headers for dealing with symbols. + +@item write.h +Structure for doing section fixups. +@end table + +@comment ~subsection Test Directory +@comment (Note: The test directory seems to have disappeared somewhere +@comment along the line. If you want it, you'll probably have to find a +@comment REALLY OLD dump tape~dots{}) +@comment +@comment The ~file{test/} directory is used for regression testing. +@comment After you modify ~@code{_AS__}, you can get a quick go/nogo +@comment confidence test by running the new ~@code{_AS__} over the source +@comment files in this directory. You use a shell script ~file{test/do}. +@comment +@comment The tests in this suite are evolving. They are not comprehensive. +@comment They have, however, caught hundreds of bugs early in the debugging +@comment cycle of ~@code{_AS__}. Most test statements in this suite were naturally +@comment selected: they were used to demonstrate actual ~@code{_AS__} bugs rather +@comment than being written ~i{a prioi}. +@comment +@comment Another testing suggestion: over 30 bugs have been found simply by +@comment running examples from this manual through ~@code{_AS__}. +@comment Some examples in this manual are selected +@comment to distinguish boundary conditions; they are good for testing ~@code{_AS__}. +@comment +@comment ~subsubsection Regression Testing +@comment Each regression test involves assembling a file and comparing the +@comment actual output of ~@code{_AS__} to ``known good'' output files. Both +@comment the object file and the error/warning message file (stderr) are +@comment inspected. Optionally the ~@code{_AS__} exit status may be checked. +@comment Discrepencies are reported. Each discrepency means either that +@comment you broke some part of ~@code{_AS__} or that the ``known good'' files +@comment are now out of date and should be changed to reflect the new +@comment definition of ``good''. +@comment +@comment Each regression test lives in its own directory, in a tree +@comment rooted in the directory ~file{test/}. Each such directory +@comment has a name ending in ~file{.ret}, where `ret' stands for +@comment REgression Test. The ~file{.ret} ending allows ~code{find +@comment (1)} to find all regression tests in the tree, without +@comment needing to list them explicitly. +@comment +@comment Any ~file{.ret} directory must contain a file called +@comment ~file{input} which is the source file to assemble. During +@comment testing an object file ~file{output} is created, as well as +@comment a file ~file{stdouterr} which contains the output to both +@comment stderr and stderr. If there is a file ~file{output.good} in +@comment the directory, and if ~file{output} contains exactly the +@comment same data as ~file{output.good}, the file ~file{output} is +@comment deleted. Likewise ~file{stdouterr} is removed if it exactly +@comment matches a file ~file{stdouterr.good}. If file +@comment ~file{status.good} is present, containing a decimal number +@comment before a newline, the exit status of ~@code{_AS__} is compared +@comment to this number. If the status numbers are not equal, a file +@comment ~file{status} is written to the directory, containing the +@comment actual status as a decimal number followed by newline. +@comment +@comment Should any of the ~file{*.good} files fail to match their corresponding +@comment actual files, this is noted by a 1-line message on the screen during +@comment the regression test, and you can use ~@code{find (1)} to find any +@comment files named ~file{status}, ~file {output} or ~file{stdouterr}. +@comment +@node Retargeting, Copying, Maintenance, Top +@chapter Teaching the Assembler about a New Machine + +This chapter describes the steps required in order to make the +assembler work with another machine's assembly language. This +chapter is not complete, and only describes the steps in the +broadest terms. You should look at the source for the +currently supported machine in order to discover some of the +details that aren't mentioned here. + +You should create a new file called @file{@var{machine}.c}, and +add the appropriate lines to the file @file{Makefile} so that +you can compile your new version of the assembler. This should +be straighforward; simply add lines similar to the ones there +for the four current versions of the assembler. + +If you want to be compatible with GDB, (and the current +machine-dependent versions of the assembler), you should create +a file called @file{@var{machine}-opcode.h} which should +contain all the information about the names of the machine +instructions, their opcodes, and what addressing modes they +support. If you do this right, the assembler and GDB can share +this file, and you'll only have to write it once. Note that +while you're writing @code{_AS__}, you may want to use an +independent program (if you have access to one), to make sure +that @code{_AS__} is emitting the correct bytes. Since @code{_AS__} +and @code{GDB} share the opcode table, an incorrect opcode +table entry may make invalid bytes look OK when you disassemble +them with @code{GDB}. + +@section Functions You will Have to Write + +Your file @file{@var{machine}.c} should contain definitions for +the following functions and variables. It will need to include +some header files in order to use some of the structures +defined in the machine-independent part of the assembler. The +needed header files are mentioned in the descriptions of the +functions that will need them. + +@table @code + +@item long omagic; +This long integer holds the value to place at the beginning of +the @file{a.out} file. It is usually @samp{OMAGIC}, except on +machines that store additional information in the magic-number. + +@item char comment_chars[]; +This character array holds the values of the characters that +start a comment anywhere in a line. Comments are stripped off +automatically by the machine independent part of the +assembler. Note that the @samp{/*} will always start a +comment, and that only @samp{*/} will end a comment started by +@samp{*/}. + +@item char line_comment_chars[]; +This character array holds the values of the chars that start a +comment only if they are the first (non-whitespace) character +on a line. If the character @samp{#} does not appear in this +list, you may get unexpected results. (Various +machine-independent parts of the assembler treat the comments +@samp{#APP} and @samp{#NO_APP} specially, and assume that lines +that start with @samp{#} are comments.) + +@item char EXP_CHARS[]; +This character array holds the letters that can separate the +mantissa and the exponent of a floating point number. Typical +values are @samp{e} and @samp{E}. + +@item char FLT_CHARS[]; +This character array holds the letters that--when they appear +immediately after a leading zero--indicate that a number is a +floating-point number. (Sort of how 0x indicates that a +hexadecimal number follows.) + +@item pseudo_typeS md_pseudo_table[]; +(@var{pseudo_typeS} is defined in @file{md.h}) +This array contains a list of the machine_dependent directives +the assembler must support. It contains the name of each +pseudo op (Without the leading @samp{.}), a pointer to a +function to be called when that directive is encountered, and +an integer argument to be passed to that function. + +@item void md_begin(void) +This function is called as part of the assembler's +initialization. It should do any initialization required by +any of your other routines. + +@item int md_parse_option(char **optionPTR, int *argcPTR, char ***argvPTR) +This routine is called once for each option on the command line +that the machine-independent part of @code{_AS__} does not +understand. This function should return non-zero if the option +pointed to by @var{optionPTR} is a valid option. If it is not +a valid option, this routine should return zero. The variables +@var{argcPTR} and @var{argvPTR} are provided in case the option +requires a filename or something similar as an argument. If +the option is multi-character, @var{optionPTR} should be +advanced past the end of the option, otherwise every letter in +the option will be treated as a separate single-character +option. + +@item void md_assemble(char *string) +This routine is called for every machine-dependent +non-directive line in the source file. It does all the real +work involved in reading the opcode, parsing the operands, +etc. @var{string} is a pointer to a null-terminated string, +that comprises the input line, with all excess whitespace and +comments removed. + +@item void md_number_to_chars(char *outputPTR,long value,int nbytes) +This routine is called to turn a C long int, short int, or char +into the series of bytes that represents that number on the +target machine. @var{outputPTR} points to an array where the +result should be stored; @var{value} is the value to store; and +@var{nbytes} is the number of bytes in 'value' that should be +stored. + +@item void md_number_to_imm(char *outputPTR,long value,int nbytes) +This routine is called to turn a C long int, short int, or char +into the series of bytes that represent an immediate value on +the target machine. It is identical to the function @code{md_number_to_chars}, +except on NS32K machines.@refill + +@item void md_number_to_disp(char *outputPTR,long value,int nbytes) +This routine is called to turn a C long int, short int, or char +into the series of bytes that represent an displacement value on +the target machine. It is identical to the function @code{md_number_to_chars}, +except on NS32K machines.@refill + +@item void md_number_to_field(char *outputPTR,long value,int nbytes) +This routine is identical to @code{md_number_to_chars}, +except on NS32K machines. + +@item void md_ri_to_chars(struct relocation_info *riPTR,ri) +(@code{struct relocation_info} is defined in @file{a.out.h}) +This routine emits the relocation info in @var{ri} +in the appropriate bit-pattern for the target machine. +The result should be stored in the location pointed +to by @var{riPTR}. This routine may be a no-op unless you are +attempting to do cross-assembly. + +@item char *md_atof(char type,char *outputPTR,int *sizePTR) +This routine turns a series of digits into the appropriate +internal representation for a floating-point number. +@var{type} is a character from @var{FLT_CHARS[]} that describes +what kind of floating point number is wanted; @var{outputPTR} +is a pointer to an array that the result should be stored in; +and @var{sizePTR} is a pointer to an integer where the size (in +bytes) of the result should be stored. This routine should +return an error message, or an empty string (not (char *)0) for +success. + +@item int md_short_jump_size; +This variable holds the (maximum) size in bytes of a short (16 +bit or so) jump created by @code{md_create_short_jump()}. This +variable is used as part of the broken-word feature, and isn't +needed if the assembler is compiled with +@samp{-DWORKING_DOT_WORD}. + +@item int md_long_jump_size; +This variable holds the (maximum) size in bytes of a long (32 +bit or so) jump created by @code{md_create_long_jump()}. This +variable is used as part of the broken-word feature, and isn't +needed if the assembler is compiled with +@samp{-DWORKING_DOT_WORD}. + +@item void md_create_short_jump(char *resultPTR,long from_addr, +@code{long to_addr,fragS *frag,symbolS *to_symbol)} +This function emits a jump from @var{from_addr} to @var{to_addr} in +the array of bytes pointed to by @var{resultPTR}. If this creates a +type of jump that must be relocated, this function should call +@code{fix_new()} with @var{frag} and @var{to_symbol}. The jump +emitted by this function may be smaller than @var{md_short_jump_size}, +but it must never create a larger one. +(If it creates a smaller jump, the extra bytes of memory will not be +used.) This function is used as part of the broken-word feature, +and isn't needed if the assembler is compiled with +@samp{-DWORKING_DOT_WORD}.@refill + +@item void md_create_long_jump(char *ptr,long from_addr, +@code{long to_addr,fragS *frag,symbolS *to_symbol)} +This function is similar to the previous function, +@code{md_create_short_jump()}, except that it creates a long +jump instead of a short one. This function is used as part of +the broken-word feature, and isn't needed if the assembler is +compiled with @samp{-DWORKING_DOT_WORD}. + +@item int md_estimate_size_before_relax(fragS *fragPTR,int segment_type) +This function does the initial setting up for relaxation. This +includes forcing references to still-undefined symbols to the +appropriate addressing modes. + +@item relax_typeS md_relax_table[]; +(relax_typeS is defined in md.h) +This array describes the various machine dependent states a +frag may be in before relaxation. You will need one group of +entries for each type of addressing mode you intend to relax. + +@item void md_convert_frag(fragS *fragPTR) +(@var{fragS} is defined in @file{as.h}) +This routine does the required cleanup after relaxation. +Relaxation has changed the type of the frag to a type that can +reach its destination. This function should adjust the opcode +of the frag to use the appropriate addressing mode. +@var{fragPTR} points to the frag to clean up. + +@item void md_end(void) +This function is called just before the assembler exits. It +need not free up memory unless the operating system doesn't do +it automatically on exit. (In which case you'll also have to +track down all the other places where the assembler allocates +space but never frees it.) + +@end table + +@section External Variables You will Need to Use + +You will need to refer to or change the following external variables +from within the machine-dependent part of the assembler. + +@table @code +@item extern char flagseen[]; +This array holds non-zero values in locations corresponding to +the options that were on the command line. Thus, if the +assembler was called with @samp{-W}, @var{flagseen['W']} would +be non-zero. + +@item extern fragS *frag_now; +This pointer points to the current frag--the frag that bytes +are currently being added to. If nothing else, you will need +to pass it as an argument to various machine-independent +functions. It is maintained automatically by the +frag-manipulating functions; you should never have to change it +yourself. + +@item extern LITTLENUM_TYPE generic_bignum[]; +(@var{LITTLENUM_TYPE} is defined in @file{bignum.h}. +This is where @dfn{bignums}--numbers larger than 32 bits--are +returned when they are encountered in an expression. You will +need to use this if you need to implement directives (or +anything else) that must deal with these large numbers. +@code{Bignums} are of @code{segT} @code{SEG_BIG} (defined in +@file{as.h}, and have a positive @code{X_add_number}. The +@code{X_add_number} of a @code{bignum} is the number of +@code{LITTLENUMS} in @var{generic_bignum} that the number takes +up. + +@item extern FLONUM_TYPE generic_floating_point_number; +(@var{FLONUM_TYPE} is defined in @file{flonum.h}. +The is where @dfn{flonums}--floating-point numbers within +expressions--are returned. @code{Flonums} are of @code{segT} +@code{SEG_BIG}, and have a negative @code{X_add_number}. +@code{Flonums} are returned in a generic format. You will have +to write a routine to turn this generic format into the +appropriate floating-point format for your machine. + +@item extern int need_pass_2; +If this variable is non-zero, the assembler has encountered an +expression that cannot be assembled in a single pass. Since +the second pass isn't implemented, this flag means that the +assembler is punting, and is only looking for additional syntax +errors. (Or something like that.) + +@item extern segT now_seg; +This variable holds the value of the section the assembler is +currently assembling into. + +@end table + +@section External functions will you need + +You will find the following external functions useful (or +indispensable) when you're writing the machine-dependent part +of the assembler. + +@table @code + +@item char *frag_more(int bytes) +This function allocates @var{bytes} more bytes in the current +frag (or starts a new frag, if it can't expand the current frag +any more.) for you to store some object-file bytes in. It +returns a pointer to the bytes, ready for you to store data in. + +@item void fix_new(fragS *frag, int where, short size, symbolS *add_symbol, symbolS *sub_symbol, long offset, int pcrel) +This function stores a relocation fixup to be acted on later. +@var{frag} points to the frag the relocation belongs in; +@var{where} is the location within the frag where the relocation begins; +@var{size} is the size of the relocation, and is usually 1 (a single byte), + 2 (sixteen bits), or 4 (a longword). +The value @var{add_symbol} @minus{} @var{sub_symbol} + @var{offset}, is added to the byte(s) +at _0__@var{frag->literal[where]}_1__. If @var{pcrel} is non-zero, the address of the +location is subtracted from the result. A relocation entry is also added +to the @file{a.out} file. @var{add_symbol}, @var{sub_symbol}, and/or +@var{offset} may be NULL.@refill + +@item char *frag_var(relax_stateT type, int max_chars, int var, +@code{relax_substateT subtype, symbolS *symbol, char *opcode)} +This function creates a machine-dependent frag of type @var{type} +(usually @code{rs_machine_dependent}). +@var{max_chars} is the maximum size in bytes that the frag may grow by; +@var{var} is the current size of the variable end of the frag; +@var{subtype} is the sub-type of the frag. The sub-type is used to index into +@var{md_relax_table[]} during @code{relaxation}. +@var{symbol} is the symbol whose value should be used to when relax-ing this frag. +@var{opcode} points into a byte whose value may have to be modified if the +addressing mode used by this frag changes. It typically points into the +@var{fr_literal[]} of the previous frag, and is used to point to a location +that @code{md_convert_frag()}, may have to change.@refill + +@item void frag_wane(fragS *fragPTR) +This function is useful from within @code{md_convert_frag}. It +changes a frag to type rs_fill, and sets the variable-sized +piece of the frag to zero. The frag will never change in size +again. + +@item segT expression(expressionS *retval) +(@var{segT} is defined in @file{as.h}; @var{expressionS} is defined in @file{expr.h}) +This function parses the string pointed to by the external char +pointer @var{input_line_pointer}, and returns the section-type +of the expression. It also stores the results in the +@var{expressionS} pointed to by @var{retval}. +@var{input_line_pointer} is advanced to point past the end of +the expression. (@var{input_line_pointer} is used by other +parts of the assembler. If you modify it, be sure to restore +it to its original value.) + +@item as_warn(char *message,@dots{}) +If warning messages are disabled, this function does nothing. +Otherwise, it prints out the current file name, and the current +line number, then uses @code{fprintf} to print the +@var{message} and any arguments it was passed. + +@item as_bad(char *message,@dots{}) +This function should be called when @code{_AS__} encounters +conditions that are bad enough that @code{_AS__} should not +produce an object file, but should continue reading input and +printing warning and bad error messages. + +@item as_fatal(char *message,@dots{}) +This function prints out the current file name and line number, +prints the word @samp{FATAL:}, then uses @code{fprintf} to +print the @var{message} and any arguments it was passed. Then +the assembler exits. This function should only be used for +serious, unrecoverable errors. + +@item void float_const(int float_type) +This function reads floating-point constants from the current +input line, and calls @code{md_atof} to assemble them. It is +useful as the function to call for the directives +@samp{.single}, @samp{.double}, @samp{.float}, etc. +@var{float_type} must be a character from @var{FLT_CHARS}. + +@item void demand_empty_rest_of_line(void); +This function can be used by machine-dependent directives to +make sure the rest of the input line is empty. It prints a +warning message if there are additional characters on the line. + +@item long int get_absolute_expression(void) +This function can be used by machine-dependent directives to +read an absolute number from the current input line. It +returns the result. If it isn't given an absolute expression, +it prints a warning message and returns zero. + +@end table + + +@section The concept of Frags + +This assembler works to optimize the size of certain addressing +modes. (e.g. branch instructions) This means the size of many +pieces of object code cannot be determined until after assembly +is finished. (This means that the addresses of symbols cannot be +determined until assembly is finished.) In order to do this, +@code{_AS__} stores the output bytes as @dfn{frags}. + +Here is the definition of a frag (from @file{as.h}) +@smallexample +struct frag +@{ + long int fr_fix; + long int fr_var; + relax_stateT fr_type; + relax_substateT fr_substate; + unsigned long fr_address; + long int fr_offset; + struct symbol *fr_symbol; + char *fr_opcode; + struct frag *fr_next; + char fr_literal[]; +@} +@end smallexample + +@table @var +@item fr_fix +is the size of the fixed-size piece of the frag. + +@item fr_var +is the maximum (?) size of the variable-sized piece of the frag. + +@item fr_type +is the type of the frag. +Current types are: +rs_fill +rs_align +rs_org +rs_machine_dependent + +@item fr_substate +This stores the type of machine-dependent frag this is. (what +kind of addressing mode is being used, and what size is being +tried/will fit/etc. + +@item fr_address +@var{fr_address} is only valid after relaxation is finished. +Before relaxation, the only way to store an address is (pointer +to frag containing the address) plus (offset into the frag). + +@item fr_offset +This contains a number, whose meaning depends on the type of +the frag. +for machine_dependent frags, this contains the offset from +fr_symbol that the frag wants to go to. Thus, for branch +instructions it is usually zero. (unless the instruction was +@samp{jba foo+12} or something like that.) + +@item fr_symbol +for machine_dependent frags, this points to the symbol the frag +needs to reach. + +@item fr_opcode +This points to the location in the frag (or in a previous frag) +of the opcode for the instruction that caused this to be a frag. +@var{fr_opcode} is needed if the actual opcode must be changed +in order to use a different form of the addressing mode. +(For example, if a conditional branch only comes in size tiny, +a large-size branch could be implemented by reversing the sense +of the test, and turning it into a tiny branch over a large jump. +This would require changing the opcode.) + +@var{fr_literal} is a variable-size array that contains the +actual object bytes. A frag consists of a fixed size piece of +object data, (which may be zero bytes long), followed by a +piece of object data whose size may not have been determined +yet. Other information includes the type of the frag (which +controls how it is relaxed), + +@item fr_next +This is the next frag in the singly-linked list. This is +usually only needed by the machine-independent part of +@code{_AS__}. + +@end table +_fi__(0) + +@node Copying, Index, _MACH_DEP__, Top +@unnumbered GNU GENERAL PUBLIC LICENSE + +@cindex license +@cindex GPL +@cindex copying @code{_AS__} +@center Version 2, June 1991 + +@display +Copyright @copyright{} 1989, 1991 Free Software Foundation, Inc. +675 Mass Ave, Cambridge, MA 02139, USA + +Everyone is permitted to copy and distribute verbatim copies +of this license document, but changing it is not allowed. +@end display + +@unnumberedsec Preamble + + The licenses for most software are designed to take away your +freedom to share and change it. By contrast, the GNU General Public +License is intended to guarantee your freedom to share and change free +software---to make sure the software is free for all its users. This +General Public License applies to most of the Free Software +Foundation's software and to any other program whose authors commit to +using it. (Some other Free Software Foundation software is covered by +the GNU Library General Public License instead.) You can apply it to +your programs, too. + + When we speak of free software, we are referring to freedom, not +price. Our General Public Licenses are designed to make sure that you +have the freedom to distribute copies of free software (and charge for +this service if you wish), that you receive source code or can get it +if you want it, that you can change the software or use pieces of it +in new free programs; and that you know you can do these things. + + To protect your rights, we need to make restrictions that forbid +anyone to deny you these rights or to ask you to surrender the rights. +These restrictions translate to certain responsibilities for you if you +distribute copies of the software, or if you modify it. + + For example, if you distribute copies of such a program, whether +gratis or for a fee, you must give the recipients all the rights that +you have. You must make sure that they, too, receive or can get the +source code. And you must show them these terms so they know their +rights. + + We protect your rights with two steps: (1) copyright the software, and +(2) offer you this license which gives you legal permission to copy, +distribute and/or modify the software. + + Also, for each author's protection and ours, we want to make certain +that everyone understands that there is no warranty for this free +software. If the software is modified by someone else and passed on, we +want its recipients to know that what they have is not the original, so +that any problems introduced by others will not reflect on the original +authors' reputations. + + Finally, any free program is threatened constantly by software +patents. We wish to avoid the danger that redistributors of a free +program will individually obtain patent licenses, in effect making the +program proprietary. To prevent this, we have made it clear that any +patent must be licensed for everyone's free use or not licensed at all. + + The precise terms and conditions for copying, distribution and +modification follow. + +@iftex +@unnumberedsec TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION +@end iftex +@ifinfo +@center TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION +@end ifinfo + +@enumerate +@item +This License applies to any program or other work which contains +a notice placed by the copyright holder saying it may be distributed +under the terms of this General Public License. The ``Program'', below, +refers to any such program or work, and a ``work based on the Program'' +means either the Program or any derivative work under copyright law: +that is to say, a work containing the Program or a portion of it, +either verbatim or with modifications and/or translated into another +language. (Hereinafter, translation is included without limitation in +the term ``modification''.) Each licensee is addressed as ``you''. + +Activities other than copying, distribution and modification are not +covered by this License; they are outside its scope. The act of +running the Program is not restricted, and the output from the Program +is covered only if its contents constitute a work based on the +Program (independent of having been made by running the Program). +Whether that is true depends on what the Program does. + +@item +You may copy and distribute verbatim copies of the Program's +source code as you receive it, in any medium, provided that you +conspicuously and appropriately publish on each copy an appropriate +copyright notice and disclaimer of warranty; keep intact all the +notices that refer to this License and to the absence of any warranty; +and give any other recipients of the Program a copy of this License +along with the Program. + +You may charge a fee for the physical act of transferring a copy, and +you may at your option offer warranty protection in exchange for a fee. + +@item +You may modify your copy or copies of the Program or any portion +of it, thus forming a work based on the Program, and copy and +distribute such modifications or work under the terms of Section 1 +above, provided that you also meet all of these conditions: + +@enumerate a +@item +You must cause the modified files to carry prominent notices +stating that you changed the files and the date of any change. + +@item +You must cause any work that you distribute or publish, that in +whole or in part contains or is derived from the Program or any +part thereof, to be licensed as a whole at no charge to all third +parties under the terms of this License. + +@item +If the modified program normally reads commands interactively +when run, you must cause it, when started running for such +interactive use in the most ordinary way, to print or display an +announcement including an appropriate copyright notice and a +notice that there is no warranty (or else, saying that you provide +a warranty) and that users may redistribute the program under +these conditions, and telling the user how to view a copy of this +License. (Exception: if the Program itself is interactive but +does not normally print such an announcement, your work based on +the Program is not required to print an announcement.) +@end enumerate + +These requirements apply to the modified work as a whole. If +identifiable sections of that work are not derived from the Program, +and can be reasonably considered independent and separate works in +themselves, then this License, and its terms, do not apply to those +sections when you distribute them as separate works. But when you +distribute the same sections as part of a whole which is a work based +on the Program, the distribution of the whole must be on the terms of +this License, whose permissions for other licensees extend to the +entire whole, and thus to each and every part regardless of who wrote it. + +Thus, it is not the intent of this section to claim rights or contest +your rights to work written entirely by you; rather, the intent is to +exercise the right to control the distribution of derivative or +collective works based on the Program. + +In addition, mere aggregation of another work not based on the Program +with the Program (or with a work based on the Program) on a volume of +a storage or distribution medium does not bring the other work under +the scope of this License. + +@item +You may copy and distribute the Program (or a work based on it, +under Section 2) in object code or executable form under the terms of +Sections 1 and 2 above provided that you also do one of the following: + +@enumerate a +@item +Accompany it with the complete corresponding machine-readable +source code, which must be distributed under the terms of Sections +1 and 2 above on a medium customarily used for software interchange; or, + +@item +Accompany it with a written offer, valid for at least three +years, to give any third party, for a charge no more than your +cost of physically performing source distribution, a complete +machine-readable copy of the corresponding source code, to be +distributed under the terms of Sections 1 and 2 above on a medium +customarily used for software interchange; or, + +@item +Accompany it with the information you received as to the offer +to distribute corresponding source code. (This alternative is +allowed only for noncommercial distribution and only if you +received the program in object code or executable form with such +an offer, in accord with Subsection b above.) +@end enumerate + +The source code for a work means the preferred form of the work for +making modifications to it. For an executable work, complete source +code means all the source code for all modules it contains, plus any +associated interface definition files, plus the scripts used to +control compilation and installation of the executable. However, as a +special exception, the source code distributed need not include +anything that is normally distributed (in either source or binary +form) with the major components (compiler, kernel, and so on) of the +operating system on which the executable runs, unless that component +itself accompanies the executable. + +If distribution of executable or object code is made by offering +access to copy from a designated place, then offering equivalent +access to copy the source code from the same place counts as +distribution of the source code, even though third parties are not +compelled to copy the source along with the object code. + +@item +You may not copy, modify, sublicense, or distribute the Program +except as expressly provided under this License. Any attempt +otherwise to copy, modify, sublicense or distribute the Program is +void, and will automatically terminate your rights under this License. +However, parties who have received copies, or rights, from you under +this License will not have their licenses terminated so long as such +parties remain in full compliance. + +@item +You are not required to accept this License, since you have not +signed it. However, nothing else grants you permission to modify or +distribute the Program or its derivative works. These actions are +prohibited by law if you do not accept this License. Therefore, by +modifying or distributing the Program (or any work based on the +Program), you indicate your acceptance of this License to do so, and +all its terms and conditions for copying, distributing or modifying +the Program or works based on it. + +@item +Each time you redistribute the Program (or any work based on the +Program), the recipient automatically receives a license from the +original licensor to copy, distribute or modify the Program subject to +these terms and conditions. You may not impose any further +restrictions on the recipients' exercise of the rights granted herein. +You are not responsible for enforcing compliance by third parties to +this License. + +@item +If, as a consequence of a court judgment or allegation of patent +infringement or for any other reason (not limited to patent issues), +conditions are imposed on you (whether by court order, agreement or +otherwise) that contradict the conditions of this License, they do not +excuse you from the conditions of this License. If you cannot +distribute so as to satisfy simultaneously your obligations under this +License and any other pertinent obligations, then as a consequence you +may not distribute the Program at all. For example, if a patent +license would not permit royalty-free redistribution of the Program by +all those who receive copies directly or indirectly through you, then +the only way you could satisfy both it and this License would be to +refrain entirely from distribution of the Program. + +If any portion of this section is held invalid or unenforceable under +any particular circumstance, the balance of the section is intended to +apply and the section as a whole is intended to apply in other +circumstances. + +It is not the purpose of this section to induce you to infringe any +patents or other property right claims or to contest validity of any +such claims; this section has the sole purpose of protecting the +integrity of the free software distribution system, which is +implemented by public license practices. Many people have made +generous contributions to the wide range of software distributed +through that system in reliance on consistent application of that +system; it is up to the author/donor to decide if he or she is willing +to distribute software through any other system and a licensee cannot +impose that choice. + +This section is intended to make thoroughly clear what is believed to +be a consequence of the rest of this License. + +@item +If the distribution and/or use of the Program is restricted in +certain countries either by patents or by copyrighted interfaces, the +original copyright holder who places the Program under this License +may add an explicit geographical distribution limitation excluding +those countries, so that distribution is permitted only in or among +countries not thus excluded. In such case, this License incorporates +the limitation as if written in the body of this License. + +@item +The Free Software Foundation may publish revised and/or new versions +of the General Public License from time to time. Such new versions will +be similar in spirit to the present version, but may differ in detail to +address new problems or concerns. + +Each version is given a distinguishing version number. If the Program +specifies a version number of this License which applies to it and ``any +later version'', you have the option of following the terms and conditions +either of that version or of any later version published by the Free +Software Foundation. If the Program does not specify a version number of +this License, you may choose any version ever published by the Free Software +Foundation. + +@item +If you wish to incorporate parts of the Program into other free +programs whose distribution conditions are different, write to the author +to ask for permission. For software which is copyrighted by the Free +Software Foundation, write to the Free Software Foundation; we sometimes +make exceptions for this. Our decision will be guided by the two goals +of preserving the free status of all derivatives of our free software and +of promoting the sharing and reuse of software generally. + +@iftex +@heading NO WARRANTY +@end iftex +@ifinfo +@center NO WARRANTY +@end ifinfo + +@item +BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY +FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN +OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES +PROVIDE THE PROGRAM ``AS IS'' WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED +OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF +MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS +TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE +PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, +REPAIR OR CORRECTION. + +@item +IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING +WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR +REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, +INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING +OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED +TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY +YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER +PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE +POSSIBILITY OF SUCH DAMAGES. +@end enumerate + +@iftex +@heading END OF TERMS AND CONDITIONS +@end iftex +@ifinfo +@center END OF TERMS AND CONDITIONS +@end ifinfo + +@page +@unnumberedsec Applying These Terms to Your New Programs + + If you develop a new program, and you want it to be of the greatest +possible use to the public, the best way to achieve this is to make it +free software which everyone can redistribute and change under these terms. + + To do so, attach the following notices to the program. It is safest +to attach them to the start of each source file to most effectively +convey the exclusion of warranty; and each file should have at least +the ``copyright'' line and a pointer to where the full notice is found. + +@smallexample +@var{one line to give the program's name and an idea of what it does.} +Copyright (C) 19@var{yy} @var{name of author} + +This program is free software; you can redistribute it and/or +modify it under the terms of the GNU General Public License +as published by the Free Software Foundation; either version 2 +of the License, or (at your option) any later version. + +This program is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +GNU General Public License for more details. + +You should have received a copy of the GNU General Public License +along with this program; if not, write to the +Free Software Foundation, Inc., 675 Mass Ave, +Cambridge, MA 02139, USA. +@end smallexample + +Also add information on how to contact you by electronic and paper mail. + +If the program is interactive, make it output a short notice like this +when it starts in an interactive mode: + +@smallexample +Gnomovision version 69, Copyright (C) 19@var{yy} @var{name of author} +Gnomovision comes with ABSOLUTELY NO WARRANTY; for details +type `show w'. This is free software, and you are welcome +to redistribute it under certain conditions; type `show c' +for details. +@end smallexample + +The hypothetical commands @samp{show w} and @samp{show c} should show +the appropriate parts of the General Public License. Of course, the +commands you use may be called something other than @samp{show w} and +@samp{show c}; they could even be mouse-clicks or menu items---whatever +suits your program. + +You should also get your employer (if you work as a programmer) or your +school, if any, to sign a ``copyright disclaimer'' for the program, if +necessary. Here is a sample; alter the names: + +@smallexample +Yoyodyne, Inc., hereby disclaims all copyright interest in +the program `Gnomovision' (which makes passes at compilers) +written by James Hacker. + +@var{signature of Ty Coon}, 1 April 1989 +Ty Coon, President of Vice +@end smallexample + +This General Public License does not permit incorporating your program into +proprietary programs. If your program is a subroutine library, you may +consider it more useful to permit linking proprietary applications with the +library. If this is what you want to do, use the GNU Library General +Public License instead of this License. + +@node Index, , Copying, Top +@unnumbered Index + +@printindex cp + +@summarycontents +@contents +@bye diff --git a/gnu/usr.bin/gas/doc/config.status b/gnu/usr.bin/gas/doc/config.status new file mode 100644 index 00000000000..f1e7f63fdd3 --- /dev/null +++ b/gnu/usr.bin/gas/doc/config.status @@ -0,0 +1,5 @@ +#!/bin/sh +# This file was generated automatically by configure. Do not edit. +# /d/users/pk/src/gnu/usr.bin/gas.1.93/gas/doc was configured as follows: +/d/users/pk/src/gnu/usr.bin/gas.1.93/./configure i386 -target=i386 -norecursion +# diff --git a/gnu/usr.bin/gas/doc/configure.in b/gnu/usr.bin/gas/doc/configure.in new file mode 100644 index 00000000000..f9820ea1903 --- /dev/null +++ b/gnu/usr.bin/gas/doc/configure.in @@ -0,0 +1,34 @@ +# This file is configure.in +# +# Copyright (C) 1987-1992 Free Software Foundation, Inc. +# +# This file is part of GAS, the GNU Assembler. +# +# GAS is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2, or (at your option) +# any later version. +# +# GAS is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with GAS; see the file COPYING. If not, write to +# the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA. */ +# + +# This file is a shell script that supplies the information necessary +# to tailor a template configure script into the configure script +# appropriate for this directory. For more information, check any +# existing configure script. + +srctrigger=all.m4 +srcname="gas doc" + +# per-host: + +# per-target: + +# end of gas/doc/configure.in diff --git a/gnu/usr.bin/gas/doc/gen.m4 b/gnu/usr.bin/gas/doc/gen.m4 new file mode 100644 index 00000000000..85bf151ea66 --- /dev/null +++ b/gnu/usr.bin/gas/doc/gen.m4 @@ -0,0 +1,14 @@ +_divert__(-1) +<$Id: gen.m4,v 1.1 1995/10/18 08:39:09 deraadt Exp $> +_define__(<_GENERIC__>,<1>) In case none.m4 changes its mind abt default + +_define__(<_AOUT__>,<1>) +_define__(<_COFF__>,<1>) +_define__(<_ELF__>,<1>) + +_define__(<_I80386__>,<1>) +_define__(<_M680X0__>,<1>) +_define__(<_SPARC__>,<1>) +_define__(<_VAX__>,<1>) + +_divert__<> diff --git a/gnu/usr.bin/gas/doc/h8.m4 b/gnu/usr.bin/gas/doc/h8.m4 new file mode 100644 index 00000000000..ed52c857cf6 --- /dev/null +++ b/gnu/usr.bin/gas/doc/h8.m4 @@ -0,0 +1,15 @@ +_divert__(-1) +_define__(<_H8__>,<1>) +_define__(<_AS__>,<as83>) +_define__(<_GENERIC__>,<0>) +_define__(<_HOST__>,<H8/300>) +_define__(<_MACH_DEP__>,<H8/300-Dependent>) +_define__(<_AOUT__>,<0>) +_define__(<_BOUT__>,<0>) +_define__(<_COFF__>,<1>) +_define__(<_ELF__>,<0>) +_define__(<_DIFFTABKLUG__>,0) NO difference-table kluge +_define__(<_IEEEFLOAT__>,1) IEEE floating point +_define__(<_W32__>,0) +_define__(<_W16__>,1) 16-bit words +_divert__<> diff --git a/gnu/usr.bin/gas/doc/i80386.m4 b/gnu/usr.bin/gas/doc/i80386.m4 new file mode 100644 index 00000000000..e8718aa7471 --- /dev/null +++ b/gnu/usr.bin/gas/doc/i80386.m4 @@ -0,0 +1,12 @@ +_divert__(-1) +_define__(<_I80386__>,<1>) +_define__(<_GENERIC__>,<0>) +_define__(<_HOST__>,<Intel 80386>) +_define__(<_MACH_DEP__>,<i386-Dependent>) +_define__(<_AOUT__>,<1>) +_define__(<_BOUT__>,<0>) +_define__(<_COFF__>,<0>) +_define__(<_ELF__>,<0>) +_define__(<_W32__>,0) +_define__(<_W16__>,1) 16-bit words +_divert__<> diff --git a/gnu/usr.bin/gas/doc/i960.m4 b/gnu/usr.bin/gas/doc/i960.m4 new file mode 100644 index 00000000000..1fca14725df --- /dev/null +++ b/gnu/usr.bin/gas/doc/i960.m4 @@ -0,0 +1,16 @@ +_divert__(-1) +_define__(<_I960__>,<1>) +_define__(<_AOUT__>,<0>) +_define__(<_BOUT__>,<1>) +_define__(<_COFF__>,<1>) +_define__(<_AS__>,<gas960>) +_define__(<_GCC__>,<gcc960>) +_define__(<_LD__>,<gld960>) +_define__(<_GDB__>,<gdb960>) +_define__(<_HOST__>,<Intel 960>) +_define__(<_MACH_DEP__>,<i960-Dependent>) +_define__(<_DIFFTABKLUG__>,0) NO difference-table kluge +_define__(<_IEEEFLOAT__>,1) IEEE floating point +_define__(<_W32__>,1) 32-bit words +_define__(<_W16__>,0) +_divert__<> diff --git a/gnu/usr.bin/gas/doc/m680x0.m4 b/gnu/usr.bin/gas/doc/m680x0.m4 new file mode 100644 index 00000000000..4013e72a364 --- /dev/null +++ b/gnu/usr.bin/gas/doc/m680x0.m4 @@ -0,0 +1,8 @@ +_divert__(-1) +_define__(<_GENERIC__>,<0>) +_define__(<_M680X0__>,<1>) +_define__(<_HOST__>,<Motorola 680x0>) +_define__(<_MACH_DEP__>,<M68K-Dependent>) +_define__(<_W32__>,0) +_define__(<_W16__>,1) 16-bit words +_divert__<> diff --git a/gnu/usr.bin/gas/doc/none.m4 b/gnu/usr.bin/gas/doc/none.m4 new file mode 100644 index 00000000000..80bb5172cea --- /dev/null +++ b/gnu/usr.bin/gas/doc/none.m4 @@ -0,0 +1,57 @@ +_divert__(-1) +<$Id: none.m4,v 1.1 1995/10/18 08:39:09 deraadt Exp $> + +Switches: + +_define__(<_ALL_ARCH__>,<0>) (Meant as most inclusive; file turning + it on is expected to also turn on + all arch-related switches including + "_GENERIC__") +_define__(<_GENERIC__>,<1>) (may not be quite all configs; + meant for "most vanilla" manual) +_define__(<_INTERNALS__>,<0>) + +_define__(<_AOUT__>,<1>) Object formats. Note we turn on one. +_define__(<_BOUT__>,<0>) +_define__(<_COFF__>,<0>) +_define__(<_ELF__>,<0>) + + Properties of the assembler +_define__(<_DIFFTABKLUG__>,1) Do we use the difference-table kluge? +_define__(<_IEEEFLOAT__>,0) IEEE floating-point? +_define__(<_W32__>,0) word is 32 bits +_define__(<_W16__>,1) word is 16 bits + +_define__(<_A29K__>,<0>) Specific architectures. Note none +_define__(<_H8__>,<0>) starts out on. +_define__(<_I80386__>,<0>) +_define__(<_I960__>,<0>) +_define__(<_M680X0__>,<0>) +_define__(<_SPARC__>,<0>) +_define__(<_VAX__>,<0>) +_define__(<_VXWORKS__>,<0>) + +Text: + +Default names; individual configs may override +Assembler: +_define__(<_AS__>,<as>) +C Compiler: +_define__(<_GCC__>,<gcc>) +Linker: +_define__(<_LD__>,<ld>) +Debugger name: +_define__(<_GDBN__>,<GDB>) +Debugger program: +_define__(<_GDBP__>,<gdb>) +Debugger init file: +_define__(<_GDBINIT__>,<.gdbinit>) + +Text for host; individual configs *should* override, but this may +catch some flubs +_define__(<_HOST__>,<machine specific>) + +"Machine Dependent" nodename +_define__(<_MACH_DEP__>,<Machine Dependent>) + +_divert__<> diff --git a/gnu/usr.bin/gas/doc/pretex.m4 b/gnu/usr.bin/gas/doc/pretex.m4 new file mode 100644 index 00000000000..dcfd3b0966a --- /dev/null +++ b/gnu/usr.bin/gas/doc/pretex.m4 @@ -0,0 +1,268 @@ +divert(-1) -*-Text-*- +` Copyright (c) 1991 Free Software Foundation, Inc.' +` This file defines and documents the M4 macros used ' +` to preprocess some GNU manuals' +` $Id: pretex.m4,v 1.1 1995/10/18 08:39:09 deraadt Exp $' + +I. INTRODUCTION + +This collection of M4 macros is meant to help in pre-processing texinfo +files to allow configuring them by hosts; for example, the reader of an +as manual who only has access to a 386 may not really want to see crud about +VAXen. + +A preprocessor is used, rather than extending texinfo, because this +way we can hack the conditionals in only one place; otherwise we would +have to write TeX macros, update makeinfo, and update the Emacs +info-formatting functions. + +II. COMPATIBILITY + +These macros should work with GNU m4 and System V m4; they do not work +with Sun or Berkeley M4. + +III. USAGE + +A. M4 INVOCATION +Assume this file is called "pretex.m4". Then, to preprocess a +document "mybook.texinfo" you might do something like the following: + + m4 pretex.m4 none.m4 PARTIC.m4 mybook.texinfo >mybook-PARTIC.texinfo + +---where your path is set to find GNU or SysV "m4", and the other m4 +files mentioned are as follows: + + none.m4: A file that defines, as 0, all the options you might + want to turn on using the conditionals defined below. + Unlike the C preprocessor, m4 does not default + undefined macros to 0. For example, here is a "none.m4" + I have been using: + _divert__(-1) + + _define__(<_ALL_ARCH__>,<0>) + _define__(<_INTERNALS__>,<0>) + + _define__(<_AMD29K__>,<0>) + _define__(<_I80386__>,<0>) + _define__(<_I960__>,<0>) + _define__(<_M680X0__>,<0>) + _define__(<_SPARC__>,<0>) + _define__(<_VAX__>,<0>) + + _divert__<> + + PARTIC.m4: A file that turns on whichever options you actually + want the manual configured for, in this particular + instance. Its contents are similar to one or more of + the lines in "none.m4", but of course the second + argument to _define__ is <1> rather than <0>. + + This is also a convenient place to _define__ any macros + that you want to expand to different text for + different configurations---for example, the name of + the program being described. + +Naturally, these are just suggested conventions; you could put your macro +definitions in any files or combinations of files you like. + +These macros use the characters < and > as m4 quotes; if you need +these characters in your text, you will also want to use the macros +_0__ and _1__ from this package---see the description of "Quote +Handling" in the "Implementation" section below. + +B. WHAT GOES IN THE PRE-TEXINFO SOURCE + +For the most part, the text of your book. In addition, you can +have text that is included only conditionally, using the macros +_if__ and _fi__ defined below. They BOTH take an argument! This is +primarily meant for readability (so a human can more easily see what +conditional end matches what conditional beginning), but the argument +is actually used in the _fi__ as well as the _if__ implementation. +You should always give a _fi__ the same argument as its matching +_if__. Other arguments may appear to work for a while, but are almost +certain to produce the wrong output for some configurations. + +For example, here is an excerpt from the very beginning of the +documentation for GNU as, to name the info file appropriately for +different configurations: + _if__(_ALL_ARCH__) + @setfilename as.info + _fi__(_ALL_ARCH__) + _if__(_M680X0__ && !_ALL_ARCH__) + @setfilename as-m680x0.info + _fi__(_M680X0__ && !_ALL_ARCH__) + _if__(_AMD29K__ && !_ALL_ARCH__) + @setfilename as-29k.info + _fi__(_AMD29K__ && !_ALL_ARCH__) + +Note that you can use Boolean expressions in the arguments; the +expression language is that of the built-in m4 macro `eval', described +in the m4 manual. + +IV. IMPLEMENTATION + +A.PRIMITIVE RENAMING +First, we redefine m4's built-ins to avoid conflict with plain text. +The naming convention used is that our macros all begin with a single +underbar and end with two underbars. The asymmetry is meant to avoid +conflict with some other conventions (which we may want to document) that +are intended to avoid conflict, like ANSI C predefined macros. + +define(`_undefine__',defn(`undefine')) +define(`_define__',defn(`define')) +define(`_defn__',defn(`defn')) +define(`_ppf__',`_define__(`_$1__',_defn__(`$1'))_undefine__(`$1')') +_ppf__(`builtin') +_ppf__(`changecom') +_ppf__(`changequote') +_ppf__(`decr') +_ppf__(`define') +_ppf__(`defn') +_ppf__(`divert') +_ppf__(`divnum') +_ppf__(`dnl') +_ppf__(`dumpdef') +_ppf__(`errprint') +_ppf__(`esyscmd') +_ppf__(`eval') +_ppf__(`format') +_ppf__(`ifdef') +_ppf__(`ifelse') +_ppf__(`include') +_ppf__(`incr') +_ppf__(`index') +_ppf__(`len') +_ppf__(`m4exit') +_ppf__(`m4wrap') +_ppf__(`maketemp') +_ppf__(`patsubst') +_ppf__(`popdef') +_ppf__(`pushdef') +_ppf__(`regexp') +_ppf__(`shift') +_ppf__(`sinclude') +_ppf__(`substr') +_ppf__(`syscmd') +_ppf__(`sysval') +_ppf__(`traceoff') +_ppf__(`traceon') +_ppf__(`translit') +_ppf__(`undefine') +_ppf__(`undivert') +_ppf__(`unix') + +B. QUOTE HANDLING. + +The characters used as quotes by M4, by default, are unfortunately +quite likely to occur in ordinary text. To avoid surprises, we will +use the characters <> ---which are just as suggestive (more so to +Francophones, perhaps) but a little less common in text (save for +those poor Francophones. You win some, you lose some). Still, we +expect also to have to set < and > occasionally in text; to do that, +we define a macro to turn off quote handling (_0__) and a macro to +turn it back on (_1__), according to our convention. + + BEWARE: This seems to make < and > unusable as relational operations + in calls to the builtin "eval". So far I've gotten + along without; but a better choice may be possible. + +Note that we postponed this for a while, for convenience in discussing +the issue and in the primitive renaming---not to mention in defining +_0__ and _1__ themselves! However, the quote redefinitions MUST +precede the _if__ / _fi__ definitions, because M4 will expand the text +as given---if we use the wrong quotes here, we will get the wrong +quotes when we use the conditionals. + +_define__(_0__,`_changequote__(,)')_define__(_1__,`_changequote__(<,>)') +_1__ + +C. CONDITIONALS + +We define two macros, _if__ and _fi__. BOTH take arguments! This is +meant both to help the human reader match up a _fi__ with its +corresponding _if__ and to aid in the implementation. You may use the +full expression syntax supported by M4 (see docn of `eval' builtin in +the m4 manual). + +The conditional macros are carefully defined to avoid introducing +extra whitespace (i.e., blank lines or blank characters). One side +effect exists--- + + BEWARE: text following an `_if__' on the same line is + DISCARDED even if the condition is true; text + following a `_fi__' on the same line is also + always discarded. + +The recommended convention is to always place _if__ and _fi__ on a +line by themselves. This will also aid the human reader. TeX won't +care about the line breaks; as for info, you may want to insert calls +to `@refill' at the end of paragraphs containing conditionalized text, +where you don't want line breaks separating unconditional from +conditional text. info formatting will then give you nice looking +paragraphs in the info file. + +Nesting: conditionals are designed to nest, in the following way: +*nothing* is output between an outer pair of false conditionals, even +if there are true conditionals inside. A false conditional "defeats" +all conditionals within it. The counter _IF_FS__ is used to +implement this; kindly avoid redefining it directly. + +_define__(<_IF_FS__>,<0>) + +NOTE: The definitions for our "pushf" and "popf" macros use eval +rather than incr and decr, because GNU m4 (0.75) tries to call eval +for us when we say "incr" or "decr"---but doesn't notice we've changed +eval's name. + +_define__( + <_pushf__>, + <_define__(<_IF_FS__>, + _eval__((_IF_FS__)+1))>) +_define__( + <_popf__>, + <_ifelse__(0,_IF_FS__, + <<>_dnl__<>>, + <_define__(<_IF_FS__>,_eval__((_IF_FS__)-1))>)>) + +_define__( + <_if__>, + <_ifelse__(1,_eval__( ($1) ), + <<>_dnl__<>>, + <_pushf__<>_divert__(-1)>)>) +_define__( + <_fi__>, + <_ifelse__(1,_eval__( ($1) ), + <<>_dnl__<>>, + <_popf__<>_ifelse__(0,_IF_FS__, + <_divert__<>_dnl__<>>,<>)>)>) + +D. CHAPTER/SECTION MACRO +In a parametrized manual, the heading level may need to be calculated; +for example, a manual that has a chapter on machine dependencies +should be conditionally structured as follows: + - IF the manual is configured for a SINGLE machine type, use +the chapter heading for that machine type, and run headings down +from there (top level for a particular machine is chapter, then within +that we have section, subsection etc); + - ELSE, if MANY machine types are described in the chapter, +use a generic chapter heading such as "@chapter Machine Dependencies", +use "section" for the top level description of EACH machine, and run +headings down from there (top level for a particular machine is +section, then within that we have subsection, subsubsection etc). + +The macro <_CHAPSEC__> is for this purpose: its argument is evaluated (so +you can construct expressions to express choices such as above), then +expands as follows: + 0: @chapter + 1: @section + 2: @subsection + 3: @subsubsection + ...and so on. + +_define__(<_CHAPSEC__>,<@_cs__(_eval__($1))>) +_define__(<_cs__>,<_ifelse__( + 0, $1, <chapter>, + 1, $1, <section>, + <sub<>_cs__(_eval__($1 - 1))>)>) + +_divert__<>_dnl__<> diff --git a/gnu/usr.bin/gas/doc/sparc.m4 b/gnu/usr.bin/gas/doc/sparc.m4 new file mode 100644 index 00000000000..121855a9786 --- /dev/null +++ b/gnu/usr.bin/gas/doc/sparc.m4 @@ -0,0 +1,8 @@ +_divert__(-1) +_define__(<_SPARC__>,<1>) +_define__(<_HOST__>,<SPARC>) +_define__(<_MACH_DEP__>,<Sparc-Dependent>) +_define__(<_IEEEFLOAT__>,1) IEEE floating point +_define__(<_W32__>,1) 32-bit words +_define__(<_W16__>,0) +_divert__<> diff --git a/gnu/usr.bin/gas/doc/vax.m4 b/gnu/usr.bin/gas/doc/vax.m4 new file mode 100644 index 00000000000..009e3343bbf --- /dev/null +++ b/gnu/usr.bin/gas/doc/vax.m4 @@ -0,0 +1,7 @@ +_divert__(-1) +_define__(<_VAX__>,<1>) +_define__(<_HOST__>,<VAX>) +_define__(<_MACH_DEP__>,<VAX-Dependent>) +_define__(<_W32__>,0) +_define__(<_W16__>,1) 16-bit words +_divert__<> diff --git a/gnu/usr.bin/gas/doc/vintage.m4 b/gnu/usr.bin/gas/doc/vintage.m4 new file mode 100644 index 00000000000..e6ab49bdeac --- /dev/null +++ b/gnu/usr.bin/gas/doc/vintage.m4 @@ -0,0 +1,11 @@ +_divert__(-1) +<$Id: vintage.m4,v 1.1 1995/10/18 08:39:09 deraadt Exp $> +_define__(<_ALL_ARCH__>,<1>) +_define__(<_GENERIC__>,<1>) In case none.m4 changes its mind abt default + +_define__(<_AOUT__>,<1>) + +_define__(<_M680X0__>,<1>) +_define__(<_SPARC__>,<1>) + +_divert__<> |