diff options
Diffstat (limited to 'contrib/binutils/gas/doc')
| -rw-r--r-- | contrib/binutils/gas/doc/Makefile.am | 100 | ||||
| -rw-r--r-- | contrib/binutils/gas/doc/Makefile.in | 608 | ||||
| -rw-r--r-- | contrib/binutils/gas/doc/all.texi | 87 | ||||
| -rw-r--r-- | contrib/binutils/gas/doc/as.1 | 970 | ||||
| -rw-r--r-- | contrib/binutils/gas/doc/as.texinfo | 6449 | ||||
| -rw-r--r-- | contrib/binutils/gas/doc/c-alpha.texi | 466 | ||||
| -rw-r--r-- | contrib/binutils/gas/doc/c-arc.texi | 207 | ||||
| -rw-r--r-- | contrib/binutils/gas/doc/c-arm.texi | 490 | ||||
| -rw-r--r-- | contrib/binutils/gas/doc/c-i386.texi | 755 | ||||
| -rw-r--r-- | contrib/binutils/gas/doc/c-ia64.texi | 157 | ||||
| -rw-r--r-- | contrib/binutils/gas/doc/c-ppc.texi | 126 | ||||
| -rw-r--r-- | contrib/binutils/gas/doc/c-sh.texi | 327 | ||||
| -rw-r--r-- | contrib/binutils/gas/doc/c-sparc.texi | 195 | ||||
| -rw-r--r-- | contrib/binutils/gas/doc/c-v850.texi | 363 | ||||
| -rw-r--r-- | contrib/binutils/gas/doc/c-z8k.texi | 380 | ||||
| -rw-r--r-- | contrib/binutils/gas/doc/gasp.texi | 1456 | ||||
| -rw-r--r-- | contrib/binutils/gas/doc/gasver.texi | 1 | ||||
| -rw-r--r-- | contrib/binutils/gas/doc/h8.texi | 26 | ||||
| -rw-r--r-- | contrib/binutils/gas/doc/internals.texi | 1948 |
19 files changed, 0 insertions, 15111 deletions
diff --git a/contrib/binutils/gas/doc/Makefile.am b/contrib/binutils/gas/doc/Makefile.am deleted file mode 100644 index 7f0f805fbc587..0000000000000 --- a/contrib/binutils/gas/doc/Makefile.am +++ /dev/null @@ -1,100 +0,0 @@ -## Process this file with automake to generate Makefile.in - -AUTOMAKE_OPTIONS = 1.8 cygnus - -# What version of the manual you want; "all" includes everything -CONFIG=all - -# Options to extract the man page from as.texinfo -MANCONF = -Dman - -TEXI2POD = perl $(top_srcdir)/../etc/texi2pod.pl - -POD2MAN = pod2man --center="GNU Development Tools" \ - --release="binutils-$(VERSION)" --section=1 - -man_MANS = as.1 - -info_TEXINFOS = as.texinfo - -asconfig.texi: $(CONFIG).texi - rm -f asconfig.texi - ln -s $(srcdir)/$(CONFIG).texi ./asconfig.texi >/dev/null 2>&1 \ - || ln $(srcdir)/$(CONFIG).texi ./asconfig.texi >/dev/null 2>&1 \ - || cp $(srcdir)/$(CONFIG).texi ./asconfig.texi - -CPU_DOCS = \ - c-a29k.texi \ - c-alpha.texi \ - c-arc.texi \ - c-arm.texi \ - c-d10v.texi \ - c-cris.texi \ - c-h8300.texi \ - c-h8500.texi \ - c-hppa.texi \ - c-i370.texi \ - c-i386.texi \ - c-i860.texi \ - c-i960.texi \ - c-ip2k.texi \ - c-m32r.texi \ - c-m68hc11.texi \ - c-m68k.texi \ - c-m88k.texi \ - c-mips.texi \ - c-mmix.texi \ - c-msp430.texi \ - c-ns32k.texi \ - c-pdp11.texi \ - c-pj.texi \ - c-ppc.texi \ - c-sh.texi \ - c-sh64.texi \ - c-sparc.texi \ - c-tic54x.texi \ - c-vax.texi \ - c-v850.texi \ - c-xtensa.texi \ - c-z8k.texi - -gasver.texi: Makefile - rm -f $@ - echo '@set VERSION $(VERSION)' > $@ - -as.info: $(srcdir)/as.texinfo asconfig.texi gasver.texi $(CPU_DOCS) -as.dvi: $(srcdir)/as.texinfo asconfig.texi gasver.texi $(CPU_DOCS) - -# We want install to imply install-info as per GNU standards, despite the -# cygnus option. -install-data-local: install-info - -# This one isn't ready for prime time yet. Not even a little bit. - -noinst_TEXINFOS = internals.texi - -DISTCLEANFILES = asconfig.texi - -MAINTAINERCLEANFILES = gasver.texi - -BASEDIR = $(srcdir)/../.. -BFDDIR = $(BASEDIR)/bfd - -CONFIG_STATUS_DEPENDENCIES = $(BFDDIR)/configure.in - -# Maintenance - -# We need it for the taz target in ../../Makefile.in. -info: $(MANS) - -# Build the man page from the texinfo file -# The sed command removes the no-adjust Nroff command so that -# the man output looks standard. -as.1: $(srcdir)/as.texinfo asconfig.texi gasver.texi $(CPU_DOCS) - touch $@ - -$(TEXI2POD) $(MANCONF) < $(srcdir)/as.texinfo > as.pod - -($(POD2MAN) as.pod | \ - sed -e '/^.if n .na/d' > $@.T$$$$ && \ - mv -f $@.T$$$$ $@) || \ - (rm -f $@.T$$$$ && exit 1) - rm -f as.pod diff --git a/contrib/binutils/gas/doc/Makefile.in b/contrib/binutils/gas/doc/Makefile.in deleted file mode 100644 index 0c6a1b0ab986e..0000000000000 --- a/contrib/binutils/gas/doc/Makefile.in +++ /dev/null @@ -1,608 +0,0 @@ -# Makefile.in generated by automake 1.8.4 from Makefile.am. -# @configure_input@ - -# Copyright (C) 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, -# 2003, 2004 Free Software Foundation, Inc. -# This Makefile.in is free software; the Free Software Foundation -# gives unlimited permission to copy and/or distribute it, -# with or without modifications, as long as this notice is preserved. - -# This program is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY, to the extent permitted by law; without -# even the implied warranty of MERCHANTABILITY or FITNESS FOR A -# PARTICULAR PURPOSE. - -@SET_MAKE@ -srcdir = @srcdir@ -top_srcdir = @top_srcdir@ -VPATH = @srcdir@ -pkgdatadir = $(datadir)/@PACKAGE@ -pkglibdir = $(libdir)/@PACKAGE@ -pkgincludedir = $(includedir)/@PACKAGE@ -top_builddir = .. -am__cd = CDPATH="$${ZSH_VERSION+.}$(PATH_SEPARATOR)" && cd -INSTALL = @INSTALL@ -install_sh_DATA = $(install_sh) -c -m 644 -install_sh_PROGRAM = $(install_sh) -c -install_sh_SCRIPT = $(install_sh) -c -INSTALL_HEADER = $(INSTALL_DATA) -transform = $(program_transform_name) -NORMAL_INSTALL = : -PRE_INSTALL = : -POST_INSTALL = : -NORMAL_UNINSTALL = : -PRE_UNINSTALL = : -POST_UNINSTALL = : -build_triplet = @build@ -host_triplet = @host@ -target_triplet = @target@ -subdir = doc -DIST_COMMON = $(srcdir)/Makefile.in $(srcdir)/Makefile.am -ACLOCAL_M4 = $(top_srcdir)/aclocal.m4 -am__aclocal_m4_deps = $(top_srcdir)/acinclude.m4 \ - $(top_srcdir)/../libtool.m4 $(top_srcdir)/../gettext.m4 \ - $(top_srcdir)/configure.in -am__configure_deps = $(am__aclocal_m4_deps) $(CONFIGURE_DEPENDENCIES) \ - $(ACLOCAL_M4) -mkinstalldirs = $(SHELL) $(top_srcdir)/../mkinstalldirs -CONFIG_HEADER = $(top_builddir)/config.h -CONFIG_CLEAN_FILES = -depcomp = -am__depfiles_maybe = -SOURCES = -DIST_SOURCES = -INFO_DEPS = $(srcdir)/as.info -TEXINFO_TEX = $(top_srcdir)/../texinfo/texinfo.tex -am__TEXINFO_TEX_DIR = $(top_srcdir)/../texinfo -DVIS = as.dvi -PDFS = as.pdf -PSS = as.ps -HTMLS = as.html -TEXINFOS = as.texinfo -TEXI2DVI = `if test -f $(top_srcdir)/../texinfo/util/texi2dvi; then \ - echo $(top_srcdir)/../texinfo/util/texi2dvi; \ - else \ - echo texi2dvi; \ - fi` -TEXI2PDF = $(TEXI2DVI) --pdf --batch -MAKEINFOHTML = $(MAKEINFO) --html -AM_MAKEINFOHTMLFLAGS = $(AM_MAKEINFOFLAGS) -DVIPS = dvips -man1dir = $(mandir)/man1 -am__installdirs = "$(DESTDIR)$(man1dir)" -NROFF = nroff -MANS = $(man_MANS) -ACLOCAL = @ACLOCAL@ -ALLOCA = @ALLOCA@ -ALL_OBJ_DEPS = @ALL_OBJ_DEPS@ -AMDEP_FALSE = @AMDEP_FALSE@ -AMDEP_TRUE = @AMDEP_TRUE@ -AMTAR = @AMTAR@ -AUTOCONF = @AUTOCONF@ -AUTOHEADER = @AUTOHEADER@ -AUTOMAKE = @AUTOMAKE@ -AWK = @AWK@ -BFDLIB = @BFDLIB@ -BFDVER_H = @BFDVER_H@ -CATALOGS = @CATALOGS@ -CATOBJEXT = @CATOBJEXT@ -CC = @CC@ -CCDEPMODE = @CCDEPMODE@ -CFLAGS = @CFLAGS@ -CPP = @CPP@ -CPPFLAGS = @CPPFLAGS@ -CYGPATH_W = @CYGPATH_W@ -DATADIRNAME = @DATADIRNAME@ -DEFS = @DEFS@ -DEPDIR = @DEPDIR@ -ECHO_C = @ECHO_C@ -ECHO_N = @ECHO_N@ -ECHO_T = @ECHO_T@ -EGREP = @EGREP@ -EXEEXT = @EXEEXT@ -GDBINIT = @GDBINIT@ -GMOFILES = @GMOFILES@ -GMSGFMT = @GMSGFMT@ -GT_NO = @GT_NO@ -GT_YES = @GT_YES@ -INCLUDE_LOCALE_H = @INCLUDE_LOCALE_H@ -INSTALL_DATA = @INSTALL_DATA@ -INSTALL_PROGRAM = @INSTALL_PROGRAM@ -INSTALL_SCRIPT = @INSTALL_SCRIPT@ -INSTALL_STRIP_PROGRAM = @INSTALL_STRIP_PROGRAM@ -INSTOBJEXT = @INSTOBJEXT@ -INTLDEPS = @INTLDEPS@ -INTLLIBS = @INTLLIBS@ -INTLOBJS = @INTLOBJS@ -LDFLAGS = @LDFLAGS@ -LEX = @LEX@ -LEXLIB = @LEXLIB@ -LEX_OUTPUT_ROOT = @LEX_OUTPUT_ROOT@ -LIBM = @LIBM@ -LIBOBJS = @LIBOBJS@ -LIBS = @LIBS@ -LIBTOOL = @LIBTOOL@ -LN_S = @LN_S@ -LTLIBOBJS = @LTLIBOBJS@ -MAINT = @MAINT@ -MAINTAINER_MODE_FALSE = @MAINTAINER_MODE_FALSE@ -MAINTAINER_MODE_TRUE = @MAINTAINER_MODE_TRUE@ -MAKEINFO = @MAKEINFO@ -MKINSTALLDIRS = @MKINSTALLDIRS@ -MSGFMT = @MSGFMT@ -OBJEXT = @OBJEXT@ -OPCODES_LIB = @OPCODES_LIB@ -PACKAGE = @PACKAGE@ -PACKAGE_BUGREPORT = @PACKAGE_BUGREPORT@ -PACKAGE_NAME = @PACKAGE_NAME@ -PACKAGE_STRING = @PACKAGE_STRING@ -PACKAGE_TARNAME = @PACKAGE_TARNAME@ -PACKAGE_VERSION = @PACKAGE_VERSION@ -PATH_SEPARATOR = @PATH_SEPARATOR@ -POFILES = @POFILES@ -POSUB = @POSUB@ -RANLIB = @RANLIB@ -SET_MAKE = @SET_MAKE@ -SHELL = @SHELL@ -STRIP = @STRIP@ -USE_INCLUDED_LIBINTL = @USE_INCLUDED_LIBINTL@ -USE_NLS = @USE_NLS@ -VERSION = @VERSION@ -WARN_CFLAGS = @WARN_CFLAGS@ -XGETTEXT = @XGETTEXT@ -YACC = @YACC@ -ac_ct_CC = @ac_ct_CC@ -ac_ct_RANLIB = @ac_ct_RANLIB@ -ac_ct_STRIP = @ac_ct_STRIP@ -am__fastdepCC_FALSE = @am__fastdepCC_FALSE@ -am__fastdepCC_TRUE = @am__fastdepCC_TRUE@ -am__include = @am__include@ -am__leading_dot = @am__leading_dot@ -am__quote = @am__quote@ -atof = @atof@ -bindir = @bindir@ -build = @build@ -build_alias = @build_alias@ -build_cpu = @build_cpu@ -build_os = @build_os@ -build_vendor = @build_vendor@ -cgen_cpu_prefix = @cgen_cpu_prefix@ -datadir = @datadir@ -exec_prefix = @exec_prefix@ -extra_objects = @extra_objects@ -host = @host@ -host_alias = @host_alias@ -host_cpu = @host_cpu@ -host_os = @host_os@ -host_vendor = @host_vendor@ -includedir = @includedir@ -infodir = @infodir@ -install_sh = @install_sh@ -install_tooldir = @install_tooldir@ -l = @l@ -libdir = @libdir@ -libexecdir = @libexecdir@ -localstatedir = @localstatedir@ -mandir = @mandir@ -mkdir_p = @mkdir_p@ -obj_format = @obj_format@ -oldincludedir = @oldincludedir@ -prefix = @prefix@ -program_transform_name = @program_transform_name@ -sbindir = @sbindir@ -sharedstatedir = @sharedstatedir@ -sysconfdir = @sysconfdir@ -target = @target@ -target_alias = @target_alias@ -target_cpu = @target_cpu@ -target_cpu_type = @target_cpu_type@ -target_os = @target_os@ -target_vendor = @target_vendor@ -te_file = @te_file@ -AUTOMAKE_OPTIONS = 1.8 cygnus - -# What version of the manual you want; "all" includes everything -CONFIG = all - -# Options to extract the man page from as.texinfo -MANCONF = -Dman -TEXI2POD = perl $(top_srcdir)/../etc/texi2pod.pl -POD2MAN = pod2man --center="GNU Development Tools" \ - --release="binutils-$(VERSION)" --section=1 - -man_MANS = as.1 -info_TEXINFOS = as.texinfo -CPU_DOCS = \ - c-a29k.texi \ - c-alpha.texi \ - c-arc.texi \ - c-arm.texi \ - c-d10v.texi \ - c-cris.texi \ - c-h8300.texi \ - c-h8500.texi \ - c-hppa.texi \ - c-i370.texi \ - c-i386.texi \ - c-i860.texi \ - c-i960.texi \ - c-ip2k.texi \ - c-m32r.texi \ - c-m68hc11.texi \ - c-m68k.texi \ - c-m88k.texi \ - c-mips.texi \ - c-mmix.texi \ - c-msp430.texi \ - c-ns32k.texi \ - c-pdp11.texi \ - c-pj.texi \ - c-ppc.texi \ - c-sh.texi \ - c-sh64.texi \ - c-sparc.texi \ - c-tic54x.texi \ - c-vax.texi \ - c-v850.texi \ - c-xtensa.texi \ - c-z8k.texi - - -# This one isn't ready for prime time yet. Not even a little bit. -noinst_TEXINFOS = internals.texi -DISTCLEANFILES = asconfig.texi -MAINTAINERCLEANFILES = gasver.texi -BASEDIR = $(srcdir)/../.. -BFDDIR = $(BASEDIR)/bfd -CONFIG_STATUS_DEPENDENCIES = $(BFDDIR)/configure.in -all: all-am - -.SUFFIXES: -.SUFFIXES: .dvi .html .info .pdf .ps .texinfo -$(srcdir)/Makefile.in: @MAINTAINER_MODE_TRUE@ $(srcdir)/Makefile.am $(am__configure_deps) - @for dep in $?; do \ - case '$(am__configure_deps)' in \ - *$$dep*) \ - cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh \ - && exit 0; \ - exit 1;; \ - esac; \ - done; \ - echo ' cd $(top_srcdir) && $(AUTOMAKE) --foreign doc/Makefile'; \ - cd $(top_srcdir) && \ - $(AUTOMAKE) --foreign doc/Makefile -.PRECIOUS: Makefile -Makefile: $(srcdir)/Makefile.in $(top_builddir)/config.status - @case '$?' in \ - *config.status*) \ - cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh;; \ - *) \ - echo ' cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__depfiles_maybe)'; \ - cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__depfiles_maybe);; \ - esac; - -$(top_builddir)/config.status: $(top_srcdir)/configure $(CONFIG_STATUS_DEPENDENCIES) - cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh - -$(top_srcdir)/configure: @MAINTAINER_MODE_TRUE@ $(am__configure_deps) - cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh -$(ACLOCAL_M4): @MAINTAINER_MODE_TRUE@ $(am__aclocal_m4_deps) - cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh - -mostlyclean-libtool: - -rm -f *.lo - -clean-libtool: - -rm -rf .libs _libs - -distclean-libtool: - -rm -f libtool - -.texinfo.info: - restore=: && \ - backupdir="$(am__leading_dot)am$$$$" && \ - am__cwd=`pwd` && cd $(srcdir) && \ - rm -rf $$backupdir && mkdir $$backupdir && \ - for f in $@ $@-[0-9] $@-[0-9][0-9] $(@:.info=).i[0-9] $(@:.info=).i[0-9][0-9]; do \ - if test -f $$f; then \ - mv $$f $$backupdir; \ - restore=mv; \ - fi; \ - done; \ - cd "$$am__cwd"; \ - if $(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I $(srcdir) \ - -o $@ $<; \ - then \ - rc=0; \ - cd $(srcdir); \ - else \ - rc=$$?; \ - cd $(srcdir) && \ - $$restore $$backupdir/* `echo "./$@" | sed 's|[^/]*$$||'`; \ - fi; \ - rm -rf $$backupdir; \ - exit $$rc - -.texinfo.dvi: - TEXINPUTS="$(am__TEXINFO_TEX_DIR)$(PATH_SEPARATOR)$$TEXINPUTS" \ - MAKEINFO='$(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I $(srcdir)' \ - $(TEXI2DVI) $< - -.texinfo.pdf: - TEXINPUTS="$(am__TEXINFO_TEX_DIR)$(PATH_SEPARATOR)$$TEXINPUTS" \ - MAKEINFO='$(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I $(srcdir)' \ - $(TEXI2PDF) $< - -.texinfo.html: - $(MAKEINFOHTML) $(AM_MAKEINFOHTMLFLAGS) $(MAKEINFOFLAGS) -I $(srcdir) \ - -o $@ $< - if test ! -d $@ && test -d $(@:.html=); then \ - mv $(@:.html=) $@; else :; fi -$(srcdir)/as.info: as.texinfo -as.pdf: as.texinfo -as.html: as.texinfo -.dvi.ps: - $(DVIPS) -o $@ $< - -uninstall-info-am: - $(PRE_UNINSTALL) - @if (install-info --version && \ - install-info --version 2>&1 | sed 1q | grep -i -v debian) >/dev/null 2>&1; then \ - list='$(INFO_DEPS)'; \ - for file in $$list; do \ - relfile=`echo "$$file" | sed 's|^.*/||'`; \ - echo " install-info --info-dir='$(DESTDIR)$(infodir)' --remove '$(DESTDIR)$(infodir)/$$relfile'"; \ - install-info --info-dir="$(DESTDIR)$(infodir)" --remove "$(DESTDIR)$(infodir)/$$relfile"; \ - done; \ - else :; fi - @$(NORMAL_UNINSTALL) - @list='$(INFO_DEPS)'; \ - for file in $$list; do \ - relfile=`echo "$$file" | sed 's|^.*/||'`; \ - relfile_i=`echo "$$relfile" | sed 's|\.info$$||;s|$$|.i|'`; \ - (if cd "$(DESTDIR)$(infodir)"; then \ - echo " rm -f $$relfile $$relfile-[0-9] $$relfile-[0-9][0-9] $$relfile_i[0-9] $$relfile_i[0-9][0-9])"; \ - rm -f $$relfile $$relfile-[0-9] $$relfile-[0-9][0-9] $$relfile_i[0-9] $$relfile_i[0-9][0-9]; \ - else :; fi); \ - done - -dist-info: $(INFO_DEPS) - @srcdirstrip=`echo "$(srcdir)" | sed 's|.|.|g'`; \ - list='$(INFO_DEPS)'; \ - for base in $$list; do \ - case $$base in \ - $(srcdir)/*) base=`echo "$$base" | sed "s|^$$srcdirstrip/||"`;; \ - esac; \ - if test -f $$base; then d=.; else d=$(srcdir); fi; \ - for file in $$d/$$base*; do \ - relfile=`expr "$$file" : "$$d/\(.*\)"`; \ - test -f $(distdir)/$$relfile || \ - cp -p $$file $(distdir)/$$relfile; \ - done; \ - done - -mostlyclean-aminfo: - -rm -rf as.aux as.cp as.cps as.fn as.fns as.ky as.log as.pg as.pgs as.tmp \ - as.toc as.tp as.tps as.vr as.vrs as.dvi as.pdf as.ps as.html - -maintainer-clean-aminfo: - @list='$(INFO_DEPS)'; for i in $$list; do \ - i_i=`echo "$$i" | sed 's|\.info$$||;s|$$|.i|'`; \ - echo " rm -f $$i $$i-[0-9] $$i-[0-9][0-9] $$i_i[0-9] $$i_i[0-9][0-9]"; \ - rm -f $$i $$i-[0-9] $$i-[0-9][0-9] $$i_i[0-9] $$i_i[0-9][0-9]; \ - done - -clean-info: mostlyclean-aminfo -install-man1: $(man1_MANS) $(man_MANS) - @$(NORMAL_INSTALL) - test -z "$(man1dir)" || $(mkdir_p) "$(DESTDIR)$(man1dir)" - @list='$(man1_MANS) $(dist_man1_MANS) $(nodist_man1_MANS)'; \ - l2='$(man_MANS) $(dist_man_MANS) $(nodist_man_MANS)'; \ - for i in $$l2; do \ - case "$$i" in \ - *.1*) list="$$list $$i" ;; \ - esac; \ - done; \ - for i in $$list; do \ - if test -f $(srcdir)/$$i; then file=$(srcdir)/$$i; \ - else file=$$i; fi; \ - ext=`echo $$i | sed -e 's/^.*\\.//'`; \ - case "$$ext" in \ - 1*) ;; \ - *) ext='1' ;; \ - esac; \ - inst=`echo $$i | sed -e 's/\\.[0-9a-z]*$$//'`; \ - inst=`echo $$inst | sed -e 's/^.*\///'`; \ - inst=`echo $$inst | sed '$(transform)'`.$$ext; \ - echo " $(INSTALL_DATA) '$$file' '$(DESTDIR)$(man1dir)/$$inst'"; \ - $(INSTALL_DATA) "$$file" "$(DESTDIR)$(man1dir)/$$inst"; \ - done -uninstall-man1: - @$(NORMAL_UNINSTALL) - @list='$(man1_MANS) $(dist_man1_MANS) $(nodist_man1_MANS)'; \ - l2='$(man_MANS) $(dist_man_MANS) $(nodist_man_MANS)'; \ - for i in $$l2; do \ - case "$$i" in \ - *.1*) list="$$list $$i" ;; \ - esac; \ - done; \ - for i in $$list; do \ - ext=`echo $$i | sed -e 's/^.*\\.//'`; \ - case "$$ext" in \ - 1*) ;; \ - *) ext='1' ;; \ - esac; \ - inst=`echo $$i | sed -e 's/\\.[0-9a-z]*$$//'`; \ - inst=`echo $$inst | sed -e 's/^.*\///'`; \ - inst=`echo $$inst | sed '$(transform)'`.$$ext; \ - echo " rm -f '$(DESTDIR)$(man1dir)/$$inst'"; \ - rm -f "$(DESTDIR)$(man1dir)/$$inst"; \ - done -tags: TAGS -TAGS: - -ctags: CTAGS -CTAGS: - -check-am: -check: check-am -all-am: Makefile $(MANS) -installdirs: - for dir in "$(DESTDIR)$(man1dir)"; do \ - test -z "$$dir" || $(mkdir_p) "$$dir"; \ - done -install: install-am -install-exec: install-exec-am -install-data: install-data-am -uninstall: uninstall-am - -install-am: all-am - @$(MAKE) $(AM_MAKEFLAGS) install-exec-am install-data-am - -installcheck: installcheck-am -install-strip: - $(MAKE) $(AM_MAKEFLAGS) INSTALL_PROGRAM="$(INSTALL_STRIP_PROGRAM)" \ - install_sh_PROGRAM="$(INSTALL_STRIP_PROGRAM)" INSTALL_STRIP_FLAG=-s \ - `test -z '$(STRIP)' || \ - echo "INSTALL_PROGRAM_ENV=STRIPPROG='$(STRIP)'"` install -mostlyclean-generic: - -clean-generic: - -distclean-generic: - -rm -f $(CONFIG_CLEAN_FILES) - -test -z "$(DISTCLEANFILES)" || rm -f $(DISTCLEANFILES) - -maintainer-clean-generic: - @echo "This command is intended for maintainers to use" - @echo "it deletes files that may require special tools to rebuild." - -test -z "$(MAINTAINERCLEANFILES)" || rm -f $(MAINTAINERCLEANFILES) -clean: clean-am - -clean-am: clean-generic clean-libtool mostlyclean-am - -distclean: distclean-am - -rm -f Makefile -distclean-am: clean-am distclean-generic distclean-libtool - -dvi: dvi-am - -dvi-am: $(DVIS) - -html: html-am - -html-am: $(HTMLS) - -info-am: $(INFO_DEPS) - -install-data-am: install-data-local install-man - -install-exec-am: - -install-info: install-info-am - -install-info-am: $(INFO_DEPS) - @$(NORMAL_INSTALL) - test -z "$(infodir)" || $(mkdir_p) "$(DESTDIR)$(infodir)" - @srcdirstrip=`echo "$(srcdir)" | sed 's|.|.|g'`; \ - list='$(INFO_DEPS)'; \ - for file in $$list; do \ - case $$file in \ - $(srcdir)/*) file=`echo "$$file" | sed "s|^$$srcdirstrip/||"`;; \ - esac; \ - if test -f $$file; then d=.; else d=$(srcdir); fi; \ - file_i=`echo "$$file" | sed 's|\.info$$||;s|$$|.i|'`; \ - for ifile in $$d/$$file $$d/$$file-[0-9] $$d/$$file-[0-9][0-9] \ - $$d/$$file_i[0-9] $$d/$$file_i[0-9][0-9] ; do \ - if test -f $$ifile; then \ - relfile=`echo "$$ifile" | sed 's|^.*/||'`; \ - echo " $(INSTALL_DATA) '$$ifile' '$(DESTDIR)$(infodir)/$$relfile'"; \ - $(INSTALL_DATA) "$$ifile" "$(DESTDIR)$(infodir)/$$relfile"; \ - else : ; fi; \ - done; \ - done - @$(POST_INSTALL) - @if (install-info --version && \ - install-info --version 2>&1 | sed 1q | grep -i -v debian) >/dev/null 2>&1; then \ - list='$(INFO_DEPS)'; \ - for file in $$list; do \ - relfile=`echo "$$file" | sed 's|^.*/||'`; \ - echo " install-info --info-dir='$(DESTDIR)$(infodir)' '$(DESTDIR)$(infodir)/$$relfile'";\ - install-info --info-dir="$(DESTDIR)$(infodir)" "$(DESTDIR)$(infodir)/$$relfile" || :;\ - done; \ - else : ; fi -install-man: install-man1 - -installcheck-am: - -maintainer-clean: maintainer-clean-am - -rm -f Makefile -maintainer-clean-am: distclean-am maintainer-clean-aminfo \ - maintainer-clean-generic - -mostlyclean: mostlyclean-am - -mostlyclean-am: mostlyclean-aminfo mostlyclean-generic \ - mostlyclean-libtool - -pdf: pdf-am - -pdf-am: $(PDFS) - -ps: ps-am - -ps-am: $(PSS) - -uninstall-am: uninstall-man - -uninstall-man: uninstall-man1 - -.PHONY: all all-am check check-am clean clean-generic clean-info \ - clean-libtool dist-info distclean distclean-generic \ - distclean-libtool dvi dvi-am html html-am info info-am install \ - install-am install-data install-data-am install-data-local \ - install-exec install-exec-am install-info install-info-am \ - install-man install-man1 install-strip installcheck \ - installcheck-am installdirs maintainer-clean \ - maintainer-clean-aminfo maintainer-clean-generic mostlyclean \ - mostlyclean-aminfo mostlyclean-generic mostlyclean-libtool pdf \ - pdf-am ps ps-am uninstall uninstall-am uninstall-info-am \ - uninstall-man uninstall-man1 - - -asconfig.texi: $(CONFIG).texi - rm -f asconfig.texi - ln -s $(srcdir)/$(CONFIG).texi ./asconfig.texi >/dev/null 2>&1 \ - || ln $(srcdir)/$(CONFIG).texi ./asconfig.texi >/dev/null 2>&1 \ - || cp $(srcdir)/$(CONFIG).texi ./asconfig.texi - -gasver.texi: Makefile - rm -f $@ - echo '@set VERSION $(VERSION)' > $@ - -as.info: $(srcdir)/as.texinfo asconfig.texi gasver.texi $(CPU_DOCS) -as.dvi: $(srcdir)/as.texinfo asconfig.texi gasver.texi $(CPU_DOCS) - -# We want install to imply install-info as per GNU standards, despite the -# cygnus option. -install-data-local: install-info - -# Maintenance - -# We need it for the taz target in ../../Makefile.in. -info: $(MANS) - -# Build the man page from the texinfo file -# The sed command removes the no-adjust Nroff command so that -# the man output looks standard. -as.1: $(srcdir)/as.texinfo asconfig.texi gasver.texi $(CPU_DOCS) - touch $@ - -$(TEXI2POD) $(MANCONF) < $(srcdir)/as.texinfo > as.pod - -($(POD2MAN) as.pod | \ - sed -e '/^.if n .na/d' > $@.T$$$$ && \ - mv -f $@.T$$$$ $@) || \ - (rm -f $@.T$$$$ && exit 1) - rm -f as.pod -# Tell versions [3.59,3.63) of GNU make to not export all variables. -# Otherwise a system limit (for SysV at least) may be exceeded. -.NOEXPORT: diff --git a/contrib/binutils/gas/doc/all.texi b/contrib/binutils/gas/doc/all.texi deleted file mode 100644 index 4e302cea1f6cc..0000000000000 --- a/contrib/binutils/gas/doc/all.texi +++ /dev/null @@ -1,87 +0,0 @@ -@c Copyright 1992, 1993, 1994, 1996, 1997, 1999, 2000, 2001, 2002 -@c Free Software Foundation, Inc. -@c This file is part of the documentation for the GAS manual - -@c Configuration settings for all-inclusive version of manual - -@c switches:------------------------------------------------------------ -@c Properties of the manual -@c ======================== -@c Discuss all architectures? -@set ALL-ARCH -@c A generic form of manual (not tailored to specific target)? -@set GENERIC -@c Include text on assembler internals? -@clear INTERNALS -@c Many object formats supported in this config? -@set MULTI-OBJ - -@c Object formats of interest -@c ========================== -@set AOUT -@set BOUT -@set COFF -@set ELF -@set SOM - -@c CPUs of interest -@c ================ -@set A29K -@set ALPHA -@set ARC -@set ARM -@set CRIS -@set D10V -@set D30V -@set H8/300 -@set H8/500 -@set HPPA -@set I370 -@set I80386 -@set I860 -@set I960 -@set IP2K -@set M32R -@set M68HC11 -@set M680X0 -@set M880X0 -@set MCORE -@set MIPS -@set MMIX -@set MSP430 -@set PDP11 -@set PJ -@set PPC -@set SH -@set SPARC -@set TIC54X -@set V850 -@set VAX -@set VXWORKS -@set XTENSA -@set Z8000 - -@c Does this version of the assembler use the difference-table kluge? -@set DIFF-TBL-KLUGE - -@c Do all machines described use IEEE floating point? -@clear IEEEFLOAT - -@c Is a word 32 bits, or 16? -@clear W32 -@set W16 - -@c Do symbols have different characters than usual? -@clear SPECIAL-SYMS - -@c strings:------------------------------------------------------------ -@c Name of the assembler: -@set AS as -@c Name of C compiler: -@set GCC gcc -@c Name of linker: -@set LD ld -@c Text for target machine (best not used in generic case; but just in case...) -@set TARGET machine specific -@c Name of object format NOT SET in generic version -@clear OBJ-NAME diff --git a/contrib/binutils/gas/doc/as.1 b/contrib/binutils/gas/doc/as.1 deleted file mode 100644 index e16cbe920aa2a..0000000000000 --- a/contrib/binutils/gas/doc/as.1 +++ /dev/null @@ -1,970 +0,0 @@ -.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.14 -.\" -.\" Standard preamble: -.\" ======================================================================== -.de Sh \" Subsection heading -.br -.if t .Sp -.ne 5 -.PP -\fB\\$1\fR -.PP -.. -.de Sp \" Vertical space (when we can't use .PP) -.if t .sp .5v -.if n .sp -.. -.de Vb \" Begin verbatim text -.ft CW -.nf -.ne \\$1 -.. -.de Ve \" End verbatim text -.ft R -.fi -.. -.\" Set up some character translations and predefined strings. \*(-- will -.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left -.\" double quote, and \*(R" will give a right double quote. | will give a -.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to -.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C' -.\" expand to `' in nroff, nothing in troff, for use with C<>. -.tr \(*W-|\(bv\*(Tr -.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' -.ie n \{\ -. ds -- \(*W- -. ds PI pi -. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch -. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch -. ds L" "" -. ds R" "" -. ds C` "" -. ds C' "" -'br\} -.el\{\ -. ds -- \|\(em\| -. ds PI \(*p -. ds L" `` -. ds R" '' -'br\} -.\" -.\" If the F register is turned on, we'll generate index entries on stderr for -.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index -.\" entries marked with X<> in POD. Of course, you'll have to process the -.\" output yourself in some meaningful fashion. -.if \nF \{\ -. de IX -. tm Index:\\$1\t\\n%\t"\\$2" -.. -. nr % 0 -. rr F -.\} -.\" -.\" For nroff, turn off justification. Always turn off hyphenation; it makes -.\" way too many mistakes in technical documents. -.hy 0 -.\" -.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). -.\" Fear. Run. Save yourself. No user-serviceable parts. -. \" fudge factors for nroff and troff -.if n \{\ -. ds #H 0 -. ds #V .8m -. ds #F .3m -. ds #[ \f1 -. ds #] \fP -.\} -.if t \{\ -. ds #H ((1u-(\\\\n(.fu%2u))*.13m) -. ds #V .6m -. ds #F 0 -. ds #[ \& -. ds #] \& -.\} -. \" simple accents for nroff and troff -.if n \{\ -. ds ' \& -. ds ` \& -. ds ^ \& -. ds , \& -. ds ~ ~ -. ds / -.\} -.if t \{\ -. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" -. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' -. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' -. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' -. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' -. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' -.\} -. \" troff and (daisy-wheel) nroff accents -.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' -.ds 8 \h'\*(#H'\(*b\h'-\*(#H' -.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] -.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' -.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' -.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] -.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] -.ds ae a\h'-(\w'a'u*4/10)'e -.ds Ae A\h'-(\w'A'u*4/10)'E -. \" corrections for vroff -.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' -.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' -. \" for low resolution devices (crt and lpr) -.if \n(.H>23 .if \n(.V>19 \ -\{\ -. ds : e -. ds 8 ss -. ds o a -. ds d- d\h'-1'\(ga -. ds D- D\h'-1'\(hy -. ds th \o'bp' -. ds Th \o'LP' -. ds ae ae -. ds Ae AE -.\} -.rm #[ #] #H #V #F C -.\" ======================================================================== -.\" -.IX Title "AS 1" -.TH AS 1 "2004-05-17" "binutils-2.15" "GNU Development Tools" -.SH "NAME" -AS \- the portable GNU assembler. -.SH "SYNOPSIS" -.IX Header "SYNOPSIS" -as [\fB\-a\fR[\fBcdhlns\fR][=\fIfile\fR]] [\fB\-D\fR] [\fB\-\-defsym\fR \fIsym\fR=\fIval\fR] - [\fB\-f\fR] [\fB\-\-gstabs\fR] [\fB\-\-gstabs+\fR] [\fB\-\-gdwarf2\fR] [\fB\-\-help\fR] - [\fB\-I\fR \fIdir\fR] [\fB\-J\fR] [\fB\-K\fR] [\fB\-L\fR] - [\fB\-\-listing\-lhs\-width\fR=\fI\s-1NUM\s0\fR] [\fB\-\-listing\-lhs\-width2\fR=\fI\s-1NUM\s0\fR] - [\fB\-\-listing\-rhs\-width\fR=\fI\s-1NUM\s0\fR] [\fB\-\-listing\-cont\-lines\fR=\fI\s-1NUM\s0\fR] - [\fB\-\-keep\-locals\fR] [\fB\-o\fR \fIobjfile\fR] [\fB\-R\fR] [\fB\-\-statistics\fR] [\fB\-v\fR] - [\fB\-version\fR] [\fB\-\-version\fR] [\fB\-W\fR] [\fB\-\-warn\fR] [\fB\-\-fatal\-warnings\fR] - [\fB\-w\fR] [\fB\-x\fR] [\fB\-Z\fR] [\fB\-\-target\-help\fR] [\fItarget-options\fR] - [\fB\-\-\fR|\fIfiles\fR ...] -.PP -\&\fITarget Alpha options:\fR - [\fB\-m\fR\fIcpu\fR] - [\fB\-mdebug\fR | \fB\-no\-mdebug\fR] - [\fB\-relax\fR] [\fB\-g\fR] [\fB\-G\fR\fIsize\fR] - [\fB\-F\fR] [\fB\-32addr\fR] -.PP -\&\fITarget \s-1ARC\s0 options:\fR - [\fB\-marc[5|6|7|8]\fR] - [\fB\-EB\fR|\fB\-EL\fR] -.PP -\&\fITarget \s-1ARM\s0 options:\fR - [\fB\-mcpu\fR=\fIprocessor\fR[+\fIextension\fR...]] - [\fB\-march\fR=\fIarchitecture\fR[+\fIextension\fR...]] - [\fB\-mfpu\fR=\fIfloating-point-format\fR] - [\fB\-mfloat\-abi\fR=\fIabi\fR] - [\fB\-mthumb\fR] - [\fB\-EB\fR|\fB\-EL\fR] - [\fB\-mapcs\-32\fR|\fB\-mapcs\-26\fR|\fB\-mapcs\-float\fR| - \fB\-mapcs\-reentrant\fR] - [\fB\-mthumb\-interwork\fR] [\fB\-moabi\fR] [\fB\-k\fR] -.PP -\&\fITarget \s-1CRIS\s0 options:\fR - [\fB\-\-underscore\fR | \fB\-\-no\-underscore\fR] - [\fB\-\-pic\fR] [\fB\-N\fR] - [\fB\-\-emulation=criself\fR | \fB\-\-emulation=crisaout\fR] -.PP -\&\fITarget D10V options:\fR - [\fB\-O\fR] -.PP -\&\fITarget D30V options:\fR - [\fB\-O\fR|\fB\-n\fR|\fB\-N\fR] -.PP -\&\fITarget i386 options:\fR - [\fB\-\-32\fR|\fB\-\-64\fR] [\fB\-n\fR] -.PP -\&\fITarget i960 options:\fR - [\fB\-ACA\fR|\fB\-ACA_A\fR|\fB\-ACB\fR|\fB\-ACC\fR|\fB\-AKA\fR|\fB\-AKB\fR| - \fB\-AKC\fR|\fB\-AMC\fR] - [\fB\-b\fR] [\fB\-no\-relax\fR] -.PP -\&\fITarget \s-1IP2K\s0 options:\fR - [\fB\-mip2022\fR|\fB\-mip2022ext\fR] -.PP -\&\fITarget M32R options:\fR - [\fB\-\-m32rx\fR|\fB\-\-[no\-]warn\-explicit\-parallel\-conflicts\fR| - \fB\-\-W[n]p\fR] -.PP -\&\fITarget M680X0 options:\fR - [\fB\-l\fR] [\fB\-m68000\fR|\fB\-m68010\fR|\fB\-m68020\fR|...] -.PP -\&\fITarget M68HC11 options:\fR - [\fB\-m68hc11\fR|\fB\-m68hc12\fR|\fB\-m68hcs12\fR] - [\fB\-mshort\fR|\fB\-mlong\fR] - [\fB\-mshort\-double\fR|\fB\-mlong\-double\fR] - [\fB\-\-force\-long\-branchs\fR] [\fB\-\-short\-branchs\fR] - [\fB\-\-strict\-direct\-mode\fR] [\fB\-\-print\-insn\-syntax\fR] - [\fB\-\-print\-opcodes\fR] [\fB\-\-generate\-example\fR] -.PP -\&\fITarget \s-1MCORE\s0 options:\fR - [\fB\-jsri2bsr\fR] [\fB\-sifilter\fR] [\fB\-relax\fR] - [\fB\-mcpu=[210|340]\fR] -.PP -\&\fITarget \s-1MIPS\s0 options:\fR - [\fB\-nocpp\fR] [\fB\-EL\fR] [\fB\-EB\fR] [\fB\-O\fR[\fIoptimization level\fR]] - [\fB\-g\fR[\fIdebug level\fR]] [\fB\-G\fR \fInum\fR] [\fB\-KPIC\fR] [\fB\-call_shared\fR] - [\fB\-non_shared\fR] [\fB\-xgot\fR] [\fB\-\-membedded\-pic\fR] - [\fB\-mabi\fR=\fI\s-1ABI\s0\fR] [\fB\-32\fR] [\fB\-n32\fR] [\fB\-64\fR] [\fB\-mfp32\fR] [\fB\-mgp32\fR] - [\fB\-march\fR=\fI\s-1CPU\s0\fR] [\fB\-mtune\fR=\fI\s-1CPU\s0\fR] [\fB\-mips1\fR] [\fB\-mips2\fR] - [\fB\-mips3\fR] [\fB\-mips4\fR] [\fB\-mips5\fR] [\fB\-mips32\fR] [\fB\-mips32r2\fR] - [\fB\-mips64\fR] [\fB\-mips64r2\fR] - [\fB\-construct\-floats\fR] [\fB\-no\-construct\-floats\fR] - [\fB\-trap\fR] [\fB\-no\-break\fR] [\fB\-break\fR] [\fB\-no\-trap\fR] - [\fB\-mfix7000\fR] [\fB\-mno\-fix7000\fR] - [\fB\-mips16\fR] [\fB\-no\-mips16\fR] - [\fB\-mips3d\fR] [\fB\-no\-mips3d\fR] - [\fB\-mdmx\fR] [\fB\-no\-mdmx\fR] - [\fB\-mdebug\fR] [\fB\-no\-mdebug\fR] - [\fB\-mpdr\fR] [\fB\-mno\-pdr\fR] -.PP -\&\fITarget \s-1MMIX\s0 options:\fR - [\fB\-\-fixed\-special\-register\-names\fR] [\fB\-\-globalize\-symbols\fR] - [\fB\-\-gnu\-syntax\fR] [\fB\-\-relax\fR] [\fB\-\-no\-predefined\-symbols\fR] - [\fB\-\-no\-expand\fR] [\fB\-\-no\-merge\-gregs\fR] [\fB\-x\fR] - [\fB\-\-linker\-allocated\-gregs\fR] -.PP -\&\fITarget \s-1PDP11\s0 options:\fR - [\fB\-mpic\fR|\fB\-mno\-pic\fR] [\fB\-mall\fR] [\fB\-mno\-extensions\fR] - [\fB\-m\fR\fIextension\fR|\fB\-mno\-\fR\fIextension\fR] - [\fB\-m\fR\fIcpu\fR] [\fB\-m\fR\fImachine\fR] -.PP -\&\fITarget picoJava options:\fR - [\fB\-mb\fR|\fB\-me\fR] -.PP -\&\fITarget PowerPC options:\fR - [\fB\-mpwrx\fR|\fB\-mpwr2\fR|\fB\-mpwr\fR|\fB\-m601\fR|\fB\-mppc\fR|\fB\-mppc32\fR|\fB\-m603\fR|\fB\-m604\fR| - \fB\-m403\fR|\fB\-m405\fR|\fB\-mppc64\fR|\fB\-m620\fR|\fB\-mppc64bridge\fR|\fB\-mbooke\fR| - \fB\-mbooke32\fR|\fB\-mbooke64\fR] - [\fB\-mcom\fR|\fB\-many\fR|\fB\-maltivec\fR] [\fB\-memb\fR] - [\fB\-mregnames\fR|\fB\-mno\-regnames\fR] - [\fB\-mrelocatable\fR|\fB\-mrelocatable\-lib\fR] - [\fB\-mlittle\fR|\fB\-mlittle\-endian\fR|\fB\-mbig\fR|\fB\-mbig\-endian\fR] - [\fB\-msolaris\fR|\fB\-mno\-solaris\fR] -.PP -\&\fITarget \s-1SPARC\s0 options:\fR - [\fB\-Av6\fR|\fB\-Av7\fR|\fB\-Av8\fR|\fB\-Asparclet\fR|\fB\-Asparclite\fR - \fB\-Av8plus\fR|\fB\-Av8plusa\fR|\fB\-Av9\fR|\fB\-Av9a\fR] - [\fB\-xarch=v8plus\fR|\fB\-xarch=v8plusa\fR] [\fB\-bump\fR] - [\fB\-32\fR|\fB\-64\fR] -.PP -\&\fITarget \s-1TIC54X\s0 options:\fR - [\fB\-mcpu=54[123589]\fR|\fB\-mcpu=54[56]lp\fR] [\fB\-mfar\-mode\fR|\fB\-mf\fR] - [\fB\-merrors\-to\-file\fR \fI<filename>\fR|\fB\-me\fR \fI<filename>\fR] -.PP -\&\fITarget Xtensa options:\fR - [\fB\-\-[no\-]density\fR] [\fB\-\-[no\-]relax\fR] [\fB\-\-[no\-]generics\fR] - [\fB\-\-[no\-]text\-section\-literals\fR] - [\fB\-\-[no\-]target\-align\fR] [\fB\-\-[no\-]longcalls\fR] -.SH "DESCRIPTION" -.IX Header "DESCRIPTION" -\&\s-1GNU\s0 \fBas\fR is really a family of assemblers. -If you use (or have used) the \s-1GNU\s0 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 -\&\fIpseudo-ops\fR) and assembler syntax. -.PP -\&\fBas\fR is primarily intended to assemble the output of the -\&\s-1GNU\s0 C compiler \f(CW\*(C`gcc\*(C'\fR for use by the linker -\&\f(CW\*(C`ld\*(C'\fR. Nevertheless, we've tried to make \fBas\fR -assemble correctly everything that other assemblers for the same -machine would assemble. -Any exceptions are documented explicitly. -This doesn't mean \fBas\fR 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. -.PP -Each time you run \fBas\fR it assembles exactly one source -program. The source program is made up of one or more files. -(The standard input is also a file.) -.PP -You give \fBas\fR 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. -.PP -If you give \fBas\fR no file names it attempts to read one input file -from the \fBas\fR standard input, which is normally your terminal. You -may have to type \fBctl-D\fR to tell \fBas\fR there is no more program -to assemble. -.PP -Use \fB\-\-\fR if you need to explicitly name the standard input file -in your command line. -.PP -If the source is empty, \fBas\fR produces a small, empty object -file. -.PP -\&\fBas\fR may write warnings and error messages to the standard error -file (usually your terminal). This should not happen when a compiler -runs \fBas\fR automatically. Warnings report an assumption made so -that \fBas\fR could keep assembling a flawed program; errors report a -grave problem that stops the assembly. -.PP -If you are invoking \fBas\fR via the \s-1GNU\s0 C compiler, -you can use the \fB\-Wa\fR option to pass arguments through to the assembler. -The assembler arguments must be separated from each other (and the \fB\-Wa\fR) -by commas. For example: -.PP -.Vb 1 -\& gcc -c -g -O -Wa,-alh,-L file.c -.Ve -.PP -This passes two options to the assembler: \fB\-alh\fR (emit a listing to -standard output with high-level and assembly source) and \fB\-L\fR (retain -local symbols in the symbol table). -.PP -Usually you do not need to use this \fB\-Wa\fR mechanism, since many compiler -command-line options are automatically passed to the assembler by the compiler. -(You can call the \s-1GNU\s0 compiler driver with the \fB\-v\fR option to see -precisely what options it passes to each compilation pass, including the -assembler.) -.SH "OPTIONS" -.IX Header "OPTIONS" -.IP "\fB\-a[cdhlmns]\fR" 4 -.IX Item "-a[cdhlmns]" -Turn on listings, in any of a variety of ways: -.RS 4 -.IP "\fB\-ac\fR" 4 -.IX Item "-ac" -omit false conditionals -.IP "\fB\-ad\fR" 4 -.IX Item "-ad" -omit debugging directives -.IP "\fB\-ah\fR" 4 -.IX Item "-ah" -include high-level source -.IP "\fB\-al\fR" 4 -.IX Item "-al" -include assembly -.IP "\fB\-am\fR" 4 -.IX Item "-am" -include macro expansions -.IP "\fB\-an\fR" 4 -.IX Item "-an" -omit forms processing -.IP "\fB\-as\fR" 4 -.IX Item "-as" -include symbols -.IP "\fB=file\fR" 4 -.IX Item "=file" -set the name of the listing file -.RE -.RS 4 -.Sp -You may combine these options; for example, use \fB\-aln\fR for assembly -listing without forms processing. The \fB=file\fR option, if used, must be -the last one. By itself, \fB\-a\fR defaults to \fB\-ahls\fR. -.RE -.IP "\fB\-D\fR" 4 -.IX Item "-D" -Ignored. This option is accepted for script compatibility with calls to -other assemblers. -.IP "\fB\-\-defsym\fR \fIsym\fR\fB=\fR\fIvalue\fR" 4 -.IX Item "--defsym sym=value" -Define the symbol \fIsym\fR to be \fIvalue\fR before assembling the input file. -\&\fIvalue\fR must be an integer constant. As in C, a leading \fB0x\fR -indicates a hexadecimal value, and a leading \fB0\fR indicates an octal value. -.IP "\fB\-f\fR" 4 -.IX Item "-f" -``fast''\-\-\-skip whitespace and comment preprocessing (assume source is -compiler output). -.IP "\fB\-\-gstabs\fR" 4 -.IX Item "--gstabs" -Generate stabs debugging information for each assembler line. This -may help debugging assembler code, if the debugger can handle it. -.IP "\fB\-\-gstabs+\fR" 4 -.IX Item "--gstabs+" -Generate stabs debugging information for each assembler line, with \s-1GNU\s0 -extensions that probably only gdb can handle, and that could make other -debuggers crash or refuse to read your program. This -may help debugging assembler code. Currently the only \s-1GNU\s0 extension is -the location of the current working directory at assembling time. -.IP "\fB\-\-gdwarf2\fR" 4 -.IX Item "--gdwarf2" -Generate \s-1DWARF2\s0 debugging information for each assembler line. This -may help debugging assembler code, if the debugger can handle it. Note\-\-\-this -option is only supported by some targets, not all of them. -.IP "\fB\-\-help\fR" 4 -.IX Item "--help" -Print a summary of the command line options and exit. -.IP "\fB\-\-target\-help\fR" 4 -.IX Item "--target-help" -Print a summary of all target specific options and exit. -.IP "\fB\-I\fR \fIdir\fR" 4 -.IX Item "-I dir" -Add directory \fIdir\fR to the search list for \f(CW\*(C`.include\*(C'\fR directives. -.IP "\fB\-J\fR" 4 -.IX Item "-J" -Don't warn about signed overflow. -.IP "\fB\-K\fR" 4 -.IX Item "-K" -Issue warnings when difference tables altered for long displacements. -.IP "\fB\-L\fR" 4 -.IX Item "-L" -.PD 0 -.IP "\fB\-\-keep\-locals\fR" 4 -.IX Item "--keep-locals" -.PD -Keep (in the symbol table) local symbols. On traditional a.out systems -these start with \fBL\fR, but different systems have different local -label prefixes. -.IP "\fB\-\-listing\-lhs\-width=\fR\fInumber\fR" 4 -.IX Item "--listing-lhs-width=number" -Set the maximum width, in words, of the output data column for an assembler -listing to \fInumber\fR. -.IP "\fB\-\-listing\-lhs\-width2=\fR\fInumber\fR" 4 -.IX Item "--listing-lhs-width2=number" -Set the maximum width, in words, of the output data column for continuation -lines in an assembler listing to \fInumber\fR. -.IP "\fB\-\-listing\-rhs\-width=\fR\fInumber\fR" 4 -.IX Item "--listing-rhs-width=number" -Set the maximum width of an input source line, as displayed in a listing, to -\&\fInumber\fR bytes. -.IP "\fB\-\-listing\-cont\-lines=\fR\fInumber\fR" 4 -.IX Item "--listing-cont-lines=number" -Set the maximum number of lines printed in a listing for a single line of input -to \fInumber\fR + 1. -.IP "\fB\-o\fR \fIobjfile\fR" 4 -.IX Item "-o objfile" -Name the object-file output from \fBas\fR \fIobjfile\fR. -.IP "\fB\-R\fR" 4 -.IX Item "-R" -Fold the data section into the text section. -.IP "\fB\-\-statistics\fR" 4 -.IX Item "--statistics" -Print the maximum space (in bytes) and total time (in seconds) used by -assembly. -.IP "\fB\-\-strip\-local\-absolute\fR" 4 -.IX Item "--strip-local-absolute" -Remove local absolute symbols from the outgoing symbol table. -.IP "\fB\-v\fR" 4 -.IX Item "-v" -.PD 0 -.IP "\fB\-version\fR" 4 -.IX Item "-version" -.PD -Print the \fBas\fR version. -.IP "\fB\-\-version\fR" 4 -.IX Item "--version" -Print the \fBas\fR version and exit. -.IP "\fB\-W\fR" 4 -.IX Item "-W" -.PD 0 -.IP "\fB\-\-no\-warn\fR" 4 -.IX Item "--no-warn" -.PD -Suppress warning messages. -.IP "\fB\-\-fatal\-warnings\fR" 4 -.IX Item "--fatal-warnings" -Treat warnings as errors. -.IP "\fB\-\-warn\fR" 4 -.IX Item "--warn" -Don't suppress warning messages or treat them as errors. -.IP "\fB\-w\fR" 4 -.IX Item "-w" -Ignored. -.IP "\fB\-x\fR" 4 -.IX Item "-x" -Ignored. -.IP "\fB\-Z\fR" 4 -.IX Item "-Z" -Generate an object file even after errors. -.IP "\fB\-\- |\fR \fIfiles\fR \fB...\fR" 4 -.IX Item "-- | files ..." -Standard input, or source files to assemble. -.PP -The following options are available when as is configured for -an \s-1ARC\s0 processor. -.IP "\fB\-marc[5|6|7|8]\fR" 4 -.IX Item "-marc[5|6|7|8]" -This option selects the core processor variant. -.IP "\fB\-EB | \-EL\fR" 4 -.IX Item "-EB | -EL" -Select either big-endian (\-EB) or little-endian (\-EL) output. -.PP -The following options are available when as is configured for the \s-1ARM\s0 -processor family. -.IP "\fB\-mcpu=\fR\fIprocessor\fR\fB[+\fR\fIextension\fR\fB...]\fR" 4 -.IX Item "-mcpu=processor[+extension...]" -Specify which \s-1ARM\s0 processor variant is the target. -.IP "\fB\-march=\fR\fIarchitecture\fR\fB[+\fR\fIextension\fR\fB...]\fR" 4 -.IX Item "-march=architecture[+extension...]" -Specify which \s-1ARM\s0 architecture variant is used by the target. -.IP "\fB\-mfpu=\fR\fIfloating-point-format\fR" 4 -.IX Item "-mfpu=floating-point-format" -Select which Floating Point architecture is the target. -.IP "\fB\-mfloat\-abi=\fR\fIabi\fR" 4 -.IX Item "-mfloat-abi=abi" -Select which floating point \s-1ABI\s0 is in use. -.IP "\fB\-mthumb\fR" 4 -.IX Item "-mthumb" -Enable Thumb only instruction decoding. -.IP "\fB\-mapcs\-32 | \-mapcs\-26 | \-mapcs\-float | \-mapcs\-reentrant | \-moabi\fR" 4 -.IX Item "-mapcs-32 | -mapcs-26 | -mapcs-float | -mapcs-reentrant | -moabi" -Select which procedure calling convention is in use. -.IP "\fB\-EB | \-EL\fR" 4 -.IX Item "-EB | -EL" -Select either big-endian (\-EB) or little-endian (\-EL) output. -.IP "\fB\-mthumb\-interwork\fR" 4 -.IX Item "-mthumb-interwork" -Specify that the code has been generated with interworking between Thumb and -\&\s-1ARM\s0 code in mind. -.IP "\fB\-k\fR" 4 -.IX Item "-k" -Specify that \s-1PIC\s0 code has been generated. -.PP -See the info pages for documentation of the CRIS-specific options. -.PP -The following options are available when as is configured for -a D10V processor. -.IP "\fB\-O\fR" 4 -.IX Item "-O" -Optimize output by parallelizing instructions. -.PP -The following options are available when as is configured for a D30V -processor. -.IP "\fB\-O\fR" 4 -.IX Item "-O" -Optimize output by parallelizing instructions. -.IP "\fB\-n\fR" 4 -.IX Item "-n" -Warn when nops are generated. -.IP "\fB\-N\fR" 4 -.IX Item "-N" -Warn when a nop after a 32\-bit multiply instruction is generated. -.PP -The following options are available when as is configured for the -Intel 80960 processor. -.IP "\fB\-ACA | \-ACA_A | \-ACB | \-ACC | \-AKA | \-AKB | \-AKC | \-AMC\fR" 4 -.IX Item "-ACA | -ACA_A | -ACB | -ACC | -AKA | -AKB | -AKC | -AMC" -Specify which variant of the 960 architecture is the target. -.IP "\fB\-b\fR" 4 -.IX Item "-b" -Add code to collect statistics about branches taken. -.IP "\fB\-no\-relax\fR" 4 -.IX Item "-no-relax" -Do not alter compare-and-branch instructions for long displacements; -error if necessary. -.PP -The following options are available when as is configured for the -Ubicom \s-1IP2K\s0 series. -.IP "\fB\-mip2022ext\fR" 4 -.IX Item "-mip2022ext" -Specifies that the extended \s-1IP2022\s0 instructions are allowed. -.IP "\fB\-mip2022\fR" 4 -.IX Item "-mip2022" -Restores the default behaviour, which restricts the permitted instructions to -just the basic \s-1IP2022\s0 ones. -.PP -The following options are available when as is configured for the -Renesas M32R (formerly Mitsubishi M32R) series. -.IP "\fB\-\-m32rx\fR" 4 -.IX Item "--m32rx" -Specify which processor in the M32R family is the target. The default -is normally the M32R, but this option changes it to the M32RX. -.IP "\fB\-\-warn\-explicit\-parallel\-conflicts or \-\-Wp\fR" 4 -.IX Item "--warn-explicit-parallel-conflicts or --Wp" -Produce warning messages when questionable parallel constructs are -encountered. -.IP "\fB\-\-no\-warn\-explicit\-parallel\-conflicts or \-\-Wnp\fR" 4 -.IX Item "--no-warn-explicit-parallel-conflicts or --Wnp" -Do not produce warning messages when questionable parallel constructs are -encountered. -.PP -The following options are available when as is configured for the -Motorola 68000 series. -.IP "\fB\-l\fR" 4 -.IX Item "-l" -Shorten references to undefined symbols, to one word instead of two. -.IP "\fB\-m68000 | \-m68008 | \-m68010 | \-m68020 | \-m68030\fR" 4 -.IX Item "-m68000 | -m68008 | -m68010 | -m68020 | -m68030" -.PD 0 -.IP "\fB| \-m68040 | \-m68060 | \-m68302 | \-m68331 | \-m68332\fR" 4 -.IX Item "| -m68040 | -m68060 | -m68302 | -m68331 | -m68332" -.IP "\fB| \-m68333 | \-m68340 | \-mcpu32 | \-m5200\fR" 4 -.IX Item "| -m68333 | -m68340 | -mcpu32 | -m5200" -.PD -Specify what processor in the 68000 family is the target. The default -is normally the 68020, but this can be changed at configuration time. -.IP "\fB\-m68881 | \-m68882 | \-mno\-68881 | \-mno\-68882\fR" 4 -.IX Item "-m68881 | -m68882 | -mno-68881 | -mno-68882" -The target machine does (or does not) have a floating-point coprocessor. -The default is to assume a coprocessor for 68020, 68030, and cpu32. Although -the basic 68000 is not compatible with the 68881, a combination of the -two can be specified, since it's possible to do emulation of the -coprocessor instructions with the main processor. -.IP "\fB\-m68851 | \-mno\-68851\fR" 4 -.IX Item "-m68851 | -mno-68851" -The target machine does (or does not) have a memory-management -unit coprocessor. The default is to assume an \s-1MMU\s0 for 68020 and up. -.PP -For details about the \s-1PDP\-11\s0 machine dependent features options, -see \f(CW@ref\fR{PDP\-11\-Options}. -.IP "\fB\-mpic | \-mno\-pic\fR" 4 -.IX Item "-mpic | -mno-pic" -Generate position-independent (or position\-dependent) code. The -default is \fB\-mpic\fR. -.IP "\fB\-mall\fR" 4 -.IX Item "-mall" -.PD 0 -.IP "\fB\-mall\-extensions\fR" 4 -.IX Item "-mall-extensions" -.PD -Enable all instruction set extensions. This is the default. -.IP "\fB\-mno\-extensions\fR" 4 -.IX Item "-mno-extensions" -Disable all instruction set extensions. -.IP "\fB\-m\fR\fIextension\fR \fB| \-mno\-\fR\fIextension\fR" 4 -.IX Item "-mextension | -mno-extension" -Enable (or disable) a particular instruction set extension. -.IP "\fB\-m\fR\fIcpu\fR" 4 -.IX Item "-mcpu" -Enable the instruction set extensions supported by a particular \s-1CPU\s0, and -disable all other extensions. -.IP "\fB\-m\fR\fImachine\fR" 4 -.IX Item "-mmachine" -Enable the instruction set extensions supported by a particular machine -model, and disable all other extensions. -.PP -The following options are available when as is configured for -a picoJava processor. -.IP "\fB\-mb\fR" 4 -.IX Item "-mb" -Generate ``big endian'' format output. -.IP "\fB\-ml\fR" 4 -.IX Item "-ml" -Generate ``little endian'' format output. -.PP -The following options are available when as is configured for the -Motorola 68HC11 or 68HC12 series. -.IP "\fB\-m68hc11 | \-m68hc12 | \-m68hcs12\fR" 4 -.IX Item "-m68hc11 | -m68hc12 | -m68hcs12" -Specify what processor is the target. The default is -defined by the configuration option when building the assembler. -.IP "\fB\-mshort\fR" 4 -.IX Item "-mshort" -Specify to use the 16\-bit integer \s-1ABI\s0. -.IP "\fB\-mlong\fR" 4 -.IX Item "-mlong" -Specify to use the 32\-bit integer \s-1ABI\s0. -.IP "\fB\-mshort\-double\fR" 4 -.IX Item "-mshort-double" -Specify to use the 32\-bit double \s-1ABI\s0. -.IP "\fB\-mlong\-double\fR" 4 -.IX Item "-mlong-double" -Specify to use the 64\-bit double \s-1ABI\s0. -.IP "\fB\-\-force\-long\-branchs\fR" 4 -.IX Item "--force-long-branchs" -Relative branches are turned into absolute ones. This concerns -conditional branches, unconditional branches and branches to a -sub routine. -.IP "\fB\-S | \-\-short\-branchs\fR" 4 -.IX Item "-S | --short-branchs" -Do not turn relative branchs into absolute ones -when the offset is out of range. -.IP "\fB\-\-strict\-direct\-mode\fR" 4 -.IX Item "--strict-direct-mode" -Do not turn the direct addressing mode into extended addressing mode -when the instruction does not support direct addressing mode. -.IP "\fB\-\-print\-insn\-syntax\fR" 4 -.IX Item "--print-insn-syntax" -Print the syntax of instruction in case of error. -.IP "\fB\-\-print\-opcodes\fR" 4 -.IX Item "--print-opcodes" -print the list of instructions with syntax and then exit. -.IP "\fB\-\-generate\-example\fR" 4 -.IX Item "--generate-example" -print an example of instruction for each possible instruction and then exit. -This option is only useful for testing \fBas\fR. -.PP -The following options are available when \fBas\fR is configured -for the \s-1SPARC\s0 architecture: -.IP "\fB\-Av6 | \-Av7 | \-Av8 | \-Asparclet | \-Asparclite\fR" 4 -.IX Item "-Av6 | -Av7 | -Av8 | -Asparclet | -Asparclite" -.PD 0 -.IP "\fB\-Av8plus | \-Av8plusa | \-Av9 | \-Av9a\fR" 4 -.IX Item "-Av8plus | -Av8plusa | -Av9 | -Av9a" -.PD -Explicitly select a variant of the \s-1SPARC\s0 architecture. -.Sp -\&\fB\-Av8plus\fR and \fB\-Av8plusa\fR select a 32 bit environment. -\&\fB\-Av9\fR and \fB\-Av9a\fR select a 64 bit environment. -.Sp -\&\fB\-Av8plusa\fR and \fB\-Av9a\fR enable the \s-1SPARC\s0 V9 instruction set with -UltraSPARC extensions. -.IP "\fB\-xarch=v8plus | \-xarch=v8plusa\fR" 4 -.IX Item "-xarch=v8plus | -xarch=v8plusa" -For compatibility with the Solaris v9 assembler. These options are -equivalent to \-Av8plus and \-Av8plusa, respectively. -.IP "\fB\-bump\fR" 4 -.IX Item "-bump" -Warn when the assembler switches to another architecture. -.PP -The following options are available when as is configured for the 'c54x -architecture. -.IP "\fB\-mfar\-mode\fR" 4 -.IX Item "-mfar-mode" -Enable extended addressing mode. All addresses and relocations will assume -extended addressing (usually 23 bits). -.IP "\fB\-mcpu=\fR\fI\s-1CPU_VERSION\s0\fR" 4 -.IX Item "-mcpu=CPU_VERSION" -Sets the \s-1CPU\s0 version being compiled for. -.IP "\fB\-merrors\-to\-file\fR \fI\s-1FILENAME\s0\fR" 4 -.IX Item "-merrors-to-file FILENAME" -Redirect error output to a file, for broken systems which don't support such -behaviour in the shell. -.PP -The following options are available when as is configured for -a \s-1MIPS\s0 processor. -.IP "\fB\-G\fR \fInum\fR" 4 -.IX Item "-G num" -This option sets the largest size of an object that can be referenced -implicitly with the \f(CW\*(C`gp\*(C'\fR register. It is only accepted for targets that -use \s-1ECOFF\s0 format, such as a DECstation running Ultrix. The default value is 8. -.IP "\fB\-EB\fR" 4 -.IX Item "-EB" -Generate ``big endian'' format output. -.IP "\fB\-EL\fR" 4 -.IX Item "-EL" -Generate ``little endian'' format output. -.IP "\fB\-mips1\fR" 4 -.IX Item "-mips1" -.PD 0 -.IP "\fB\-mips2\fR" 4 -.IX Item "-mips2" -.IP "\fB\-mips3\fR" 4 -.IX Item "-mips3" -.IP "\fB\-mips4\fR" 4 -.IX Item "-mips4" -.IP "\fB\-mips5\fR" 4 -.IX Item "-mips5" -.IP "\fB\-mips32\fR" 4 -.IX Item "-mips32" -.IP "\fB\-mips32r2\fR" 4 -.IX Item "-mips32r2" -.IP "\fB\-mips64\fR" 4 -.IX Item "-mips64" -.IP "\fB\-mips64r2\fR" 4 -.IX Item "-mips64r2" -.PD -Generate code for a particular \s-1MIPS\s0 Instruction Set Architecture level. -\&\fB\-mips1\fR is an alias for \fB\-march=r3000\fR, \fB\-mips2\fR is an -alias for \fB\-march=r6000\fR, \fB\-mips3\fR is an alias for -\&\fB\-march=r4000\fR and \fB\-mips4\fR is an alias for \fB\-march=r8000\fR. -\&\fB\-mips5\fR, \fB\-mips32\fR, \fB\-mips32r2\fR, \fB\-mips64\fR, and -\&\fB\-mips64r2\fR -correspond to generic -\&\fB\s-1MIPS\s0 V\fR, \fB\s-1MIPS32\s0\fR, \fB\s-1MIPS32\s0 Release 2\fR, \fB\s-1MIPS64\s0\fR, -and \fB\s-1MIPS64\s0 Release 2\fR -\&\s-1ISA\s0 processors, respectively. -.IP "\fB\-march=\fR\fI\s-1CPU\s0\fR" 4 -.IX Item "-march=CPU" -Generate code for a particular \s-1MIPS\s0 cpu. -.IP "\fB\-mtune=\fR\fIcpu\fR" 4 -.IX Item "-mtune=cpu" -Schedule and tune for a particular \s-1MIPS\s0 cpu. -.IP "\fB\-mfix7000\fR" 4 -.IX Item "-mfix7000" -.PD 0 -.IP "\fB\-mno\-fix7000\fR" 4 -.IX Item "-mno-fix7000" -.PD -Cause nops to be inserted if the read of the destination register -of an mfhi or mflo instruction occurs in the following two instructions. -.IP "\fB\-mdebug\fR" 4 -.IX Item "-mdebug" -.PD 0 -.IP "\fB\-no\-mdebug\fR" 4 -.IX Item "-no-mdebug" -.PD -Cause stabs-style debugging output to go into an ECOFF-style .mdebug -section instead of the standard \s-1ELF\s0 .stabs sections. -.IP "\fB\-mpdr\fR" 4 -.IX Item "-mpdr" -.PD 0 -.IP "\fB\-mno\-pdr\fR" 4 -.IX Item "-mno-pdr" -.PD -Control generation of \f(CW\*(C`.pdr\*(C'\fR sections. -.IP "\fB\-mgp32\fR" 4 -.IX Item "-mgp32" -.PD 0 -.IP "\fB\-mfp32\fR" 4 -.IX Item "-mfp32" -.PD -The register sizes are normally inferred from the \s-1ISA\s0 and \s-1ABI\s0, but these -flags force a certain group of registers to be treated as 32 bits wide at -all times. \fB\-mgp32\fR controls the size of general-purpose registers -and \fB\-mfp32\fR controls the size of floating-point registers. -.IP "\fB\-mips16\fR" 4 -.IX Item "-mips16" -.PD 0 -.IP "\fB\-no\-mips16\fR" 4 -.IX Item "-no-mips16" -.PD -Generate code for the \s-1MIPS\s0 16 processor. This is equivalent to putting -\&\f(CW\*(C`.set mips16\*(C'\fR at the start of the assembly file. \fB\-no\-mips16\fR -turns off this option. -.IP "\fB\-mips3d\fR" 4 -.IX Item "-mips3d" -.PD 0 -.IP "\fB\-no\-mips3d\fR" 4 -.IX Item "-no-mips3d" -.PD -Generate code for the \s-1MIPS\-3D\s0 Application Specific Extension. -This tells the assembler to accept \s-1MIPS\-3D\s0 instructions. -\&\fB\-no\-mips3d\fR turns off this option. -.IP "\fB\-mdmx\fR" 4 -.IX Item "-mdmx" -.PD 0 -.IP "\fB\-no\-mdmx\fR" 4 -.IX Item "-no-mdmx" -.PD -Generate code for the \s-1MDMX\s0 Application Specific Extension. -This tells the assembler to accept \s-1MDMX\s0 instructions. -\&\fB\-no\-mdmx\fR turns off this option. -.IP "\fB\-\-construct\-floats\fR" 4 -.IX Item "--construct-floats" -.PD 0 -.IP "\fB\-\-no\-construct\-floats\fR" 4 -.IX Item "--no-construct-floats" -.PD -The \fB\-\-no\-construct\-floats\fR option disables the construction of -double width floating point constants by loading the two halves of the -value into the two single width floating point registers that make up -the double width register. By default \fB\-\-construct\-floats\fR is -selected, allowing construction of these floating point constants. -.IP "\fB\-\-emulation=\fR\fIname\fR" 4 -.IX Item "--emulation=name" -This option causes \fBas\fR to emulate \fBas\fR configured -for some other target, in all respects, including output format (choosing -between \s-1ELF\s0 and \s-1ECOFF\s0 only), handling of pseudo-opcodes which may generate -debugging information or store symbol table information, and default -endianness. The available configuration names are: \fBmipsecoff\fR, -\&\fBmipself\fR, \fBmipslecoff\fR, \fBmipsbecoff\fR, \fBmipslelf\fR, -\&\fBmipsbelf\fR. The first two do not alter the default endianness from that -of the primary target for which the assembler was configured; the others change -the default to little\- or big-endian as indicated by the \fBb\fR or \fBl\fR -in the name. Using \fB\-EB\fR or \fB\-EL\fR will override the endianness -selection in any case. -.Sp -This option is currently supported only when the primary target -\&\fBas\fR is configured for is a \s-1MIPS\s0 \s-1ELF\s0 or \s-1ECOFF\s0 target. -Furthermore, the primary target or others specified with -\&\fB\-\-enable\-targets=...\fR at configuration time must include support for -the other format, if both are to be available. For example, the Irix 5 -configuration includes support for both. -.Sp -Eventually, this option will support more configurations, with more -fine-grained control over the assembler's behavior, and will be supported for -more processors. -.IP "\fB\-nocpp\fR" 4 -.IX Item "-nocpp" -\&\fBas\fR ignores this option. It is accepted for compatibility with -the native tools. -.IP "\fB\-\-trap\fR" 4 -.IX Item "--trap" -.PD 0 -.IP "\fB\-\-no\-trap\fR" 4 -.IX Item "--no-trap" -.IP "\fB\-\-break\fR" 4 -.IX Item "--break" -.IP "\fB\-\-no\-break\fR" 4 -.IX Item "--no-break" -.PD -Control how to deal with multiplication overflow and division by zero. -\&\fB\-\-trap\fR or \fB\-\-no\-break\fR (which are synonyms) take a trap exception -(and only work for Instruction Set Architecture level 2 and higher); -\&\fB\-\-break\fR or \fB\-\-no\-trap\fR (also synonyms, and the default) take a -break exception. -.IP "\fB\-n\fR" 4 -.IX Item "-n" -When this option is used, \fBas\fR will issue a warning every -time it generates a nop instruction from a macro. -.PP -The following options are available when as is configured for -an MCore processor. -.IP "\fB\-jsri2bsr\fR" 4 -.IX Item "-jsri2bsr" -.PD 0 -.IP "\fB\-nojsri2bsr\fR" 4 -.IX Item "-nojsri2bsr" -.PD -Enable or disable the \s-1JSRI\s0 to \s-1BSR\s0 transformation. By default this is enabled. -The command line option \fB\-nojsri2bsr\fR can be used to disable it. -.IP "\fB\-sifilter\fR" 4 -.IX Item "-sifilter" -.PD 0 -.IP "\fB\-nosifilter\fR" 4 -.IX Item "-nosifilter" -.PD -Enable or disable the silicon filter behaviour. By default this is disabled. -The default can be overridden by the \fB\-sifilter\fR command line option. -.IP "\fB\-relax\fR" 4 -.IX Item "-relax" -Alter jump instructions for long displacements. -.IP "\fB\-mcpu=[210|340]\fR" 4 -.IX Item "-mcpu=[210|340]" -Select the cpu type on the target hardware. This controls which instructions -can be assembled. -.IP "\fB\-EB\fR" 4 -.IX Item "-EB" -Assemble for a big endian target. -.IP "\fB\-EL\fR" 4 -.IX Item "-EL" -Assemble for a little endian target. -.PP -See the info pages for documentation of the MMIX-specific options. -.PP -The following options are available when as is configured for -an Xtensa processor. -.IP "\fB\-\-density | \-\-no\-density\fR" 4 -.IX Item "--density | --no-density" -Enable or disable use of instructions from the Xtensa code density -option. This is enabled by default when the Xtensa processor supports -the code density option. -.IP "\fB\-\-relax | \-\-no\-relax\fR" 4 -.IX Item "--relax | --no-relax" -Enable or disable instruction relaxation. This is enabled by default. -Note: In the current implementation, these options also control whether -assembler optimizations are performed, making these options equivalent -to \fB\-\-generics\fR and \fB\-\-no\-generics\fR. -.IP "\fB\-\-generics | \-\-no\-generics\fR" 4 -.IX Item "--generics | --no-generics" -Enable or disable all assembler transformations of Xtensa instructions. -The default is \fB\-\-generics\fR; -\&\fB\-\-no\-generics\fR should be used only in the rare cases when the -instructions must be exactly as specified in the assembly source. -.IP "\fB\-\-text\-section\-literals | \-\-no\-text\-section\-literals\fR" 4 -.IX Item "--text-section-literals | --no-text-section-literals" -With \fB\-\-text\-section\-literals\fR, literal pools are interspersed -in the text section. The default is -\&\fB\-\-no\-text\-section\-literals\fR, which places literals in a -separate section in the output file. -.IP "\fB\-\-target\-align | \-\-no\-target\-align\fR" 4 -.IX Item "--target-align | --no-target-align" -Enable or disable automatic alignment to reduce branch penalties at the -expense of some code density. The default is \fB\-\-target\-align\fR. -.IP "\fB\-\-longcalls | \-\-no\-longcalls\fR" 4 -.IX Item "--longcalls | --no-longcalls" -Enable or disable transformation of call instructions to allow calls -across a greater range of addresses. The default is -\&\fB\-\-no\-longcalls\fR. -.SH "SEE ALSO" -.IX Header "SEE ALSO" -\&\fIgcc\fR\|(1), \fIld\fR\|(1), and the Info entries for \fIbinutils\fR and \fIld\fR. -.SH "COPYRIGHT" -.IX Header "COPYRIGHT" -Copyright (C) 1991, 92, 93, 94, 95, 96, 97, 98, 99, 2000, 2001, 2002 Free Software Foundation, Inc. -.PP -Permission is granted to copy, distribute and/or modify this document -under the terms of the \s-1GNU\s0 Free Documentation License, Version 1.1 -or any later version published by the Free Software Foundation; -with no Invariant Sections, with no Front-Cover Texts, and with no -Back-Cover Texts. A copy of the license is included in the -section entitled ``\s-1GNU\s0 Free Documentation License''. diff --git a/contrib/binutils/gas/doc/as.texinfo b/contrib/binutils/gas/doc/as.texinfo deleted file mode 100644 index d9d23dff59f4a..0000000000000 --- a/contrib/binutils/gas/doc/as.texinfo +++ /dev/null @@ -1,6449 +0,0 @@ -\input texinfo @c -*-Texinfo-*- -@c Copyright 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000, -@c 2001, 2002, 2003, 2004 -@c Free Software Foundation, Inc. -@c UPDATE!! On future updates-- -@c (1) check for new machine-dep cmdline options in -@c md_parse_option definitions in config/tc-*.c -@c (2) for platform-specific directives, examine md_pseudo_op -@c in config/tc-*.c -@c (3) for object-format specific directives, examine obj_pseudo_op -@c in config/obj-*.c -@c (4) portable directives in potable[] in read.c -@c %**start of header -@setfilename as.info -@c ---config--- -@macro gcctabopt{body} -@code{\body\} -@end macro -@c defaults, config file may override: -@set have-stabs -@c --- -@c man begin NAME -@c --- -@include asconfig.texi -@include gasver.texi -@c --- -@c man end -@c --- -@c common OR combinations of conditions -@ifset COFF -@set COFF-ELF -@end ifset -@ifset ELF -@set COFF-ELF -@end ifset -@ifset AOUT -@set aout-bout -@end ifset -@ifset ARM/Thumb -@set ARM -@end ifset -@ifset BOUT -@set aout-bout -@end ifset -@ifset H8/300 -@set H8 -@end ifset -@ifset H8/500 -@set H8 -@end ifset -@ifset SH -@set H8 -@end ifset -@ifset HPPA -@set abnormal-separator -@end ifset -@c ------------ -@ifset GENERIC -@settitle Using @value{AS} -@end ifset -@ifclear GENERIC -@settitle Using @value{AS} (@value{TARGET}) -@end ifclear -@setchapternewpage odd -@c %**end of header - -@c @smallbook -@c @set SMALL -@c WARE! Some of the machine-dependent sections contain tables of machine -@c instructions. Except in multi-column format, these tables look silly. -@c Unfortunately, Texinfo doesn't have a general-purpose multi-col format, so -@c the multi-col format is faked within @example sections. -@c -@c Again unfortunately, the natural size that fits on a page, for these tables, -@c is different depending on whether or not smallbook is turned on. -@c This matters, because of order: text flow switches columns at each page -@c break. -@c -@c The format faked in this source works reasonably well for smallbook, -@c not well for the default large-page format. This manual expects that if you -@c turn on @smallbook, you will also uncomment the "@set SMALL" to enable the -@c tables in question. You can turn on one without the other at your -@c discretion, of course. -@ifinfo -@set SMALL -@c the insn tables look just as silly in info files regardless of smallbook, -@c might as well show 'em anyways. -@end ifinfo - -@ifinfo -@format -START-INFO-DIR-ENTRY -* As: (as). The GNU assembler. -* Gas: (as). The GNU assembler. -END-INFO-DIR-ENTRY -@end format -@end ifinfo - -@finalout -@syncodeindex ky cp - -@ifinfo -This file documents the GNU Assembler "@value{AS}". - -@c man begin COPYRIGHT -Copyright (C) 1991, 92, 93, 94, 95, 96, 97, 98, 99, 2000, 2001, 2002 Free Software Foundation, Inc. - -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.1 -or any later version published by the Free Software Foundation; -with no Invariant Sections, with no Front-Cover Texts, and with no -Back-Cover Texts. A copy of the license is included in the -section entitled ``GNU Free Documentation License''. - -@c man end - -@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 -@end ifinfo - -@titlepage -@title Using @value{AS} -@subtitle The @sc{gnu} Assembler -@ifclear GENERIC -@subtitle for the @value{TARGET} family -@end ifclear -@sp 1 -@subtitle Version @value{VERSION} -@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 @command{as} for Project @sc{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 -@page -@tex -{\parskip=0pt -\hfill {\it Using {\tt @value{AS}}}\par -\hfill Edited by Cygnus Support\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 - -@vskip 0pt plus 1filll -Copyright @copyright{} 1991, 92, 93, 94, 95, 96, 97, 98, 99, 2000, 2001, 2002 Free Software Foundation, Inc. - - Permission is granted to copy, distribute and/or modify this document - under the terms of the GNU Free Documentation License, Version 1.1 - or any later version published by the Free Software Foundation; - with no Invariant Sections, with no Front-Cover Texts, and with no - Back-Cover Texts. A copy of the license is included in the - section entitled ``GNU Free Documentation License''. - -@end titlepage - -@ifnottex -@node Top -@top Using @value{AS} - -This file is a user guide to the @sc{gnu} assembler @command{@value{AS}} version -@value{VERSION}. -@ifclear GENERIC -This version of the file describes @command{@value{AS}} configured to generate -code for @value{TARGET} architectures. -@end ifclear - -This document is distributed under the terms of the GNU Free -Documentation License. A copy of the license is included in the -section entitled ``GNU Free Documentation License''. - -@menu -* Overview:: Overview -* Invoking:: Command-Line Options -* Syntax:: Syntax -* Sections:: Sections and Relocation -* Symbols:: Symbols -* Expressions:: Expressions -* Pseudo Ops:: Assembler Directives -* Machine Dependencies:: Machine Dependent Features -* Reporting Bugs:: Reporting Bugs -* Acknowledgements:: Who Did What -* GNU Free Documentation License:: GNU Free Documentation License -* Index:: Index -@end menu -@end ifnottex - -@node Overview -@chapter Overview -@iftex -This manual is a user guide to the @sc{gnu} assembler @command{@value{AS}}. -@ifclear GENERIC -This version of the manual describes @command{@value{AS}} configured to generate -code for @value{TARGET} architectures. -@end ifclear -@end iftex - -@cindex invocation summary -@cindex option summary -@cindex summary of options -Here is a brief summary of how to invoke @command{@value{AS}}. For details, -@pxref{Invoking,,Command-Line Options}. - -@c man title AS the portable GNU assembler. - -@ignore -@c man begin SEEALSO -gcc(1), ld(1), and the Info entries for @file{binutils} and @file{ld}. -@c man end -@end ignore - -@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 -@c man begin SYNOPSIS -@value{AS} [@b{-a}[@b{cdhlns}][=@var{file}]] [@b{-D}] [@b{--defsym} @var{sym}=@var{val}] - [@b{-f}] [@b{--gstabs}] [@b{--gstabs+}] [@b{--gdwarf2}] [@b{--help}] - [@b{-I} @var{dir}] [@b{-J}] [@b{-K}] [@b{-L}] - [@b{--listing-lhs-width}=@var{NUM}] [@b{--listing-lhs-width2}=@var{NUM}] - [@b{--listing-rhs-width}=@var{NUM}] [@b{--listing-cont-lines}=@var{NUM}] - [@b{--keep-locals}] [@b{-o} @var{objfile}] [@b{-R}] [@b{--statistics}] [@b{-v}] - [@b{-version}] [@b{--version}] [@b{-W}] [@b{--warn}] [@b{--fatal-warnings}] - [@b{-w}] [@b{-x}] [@b{-Z}] [@b{--target-help}] [@var{target-options}] - [@b{--}|@var{files} @dots{}] -@c -@c Target dependent options are listed below. Keep the list sorted. -@c Add an empty line for separation. -@ifset A29K -@c am29k has no machine-dependent assembler options -@end ifset -@ifset ALPHA - -@emph{Target Alpha options:} - [@b{-m@var{cpu}}] - [@b{-mdebug} | @b{-no-mdebug}] - [@b{-relax}] [@b{-g}] [@b{-G@var{size}}] - [@b{-F}] [@b{-32addr}] -@end ifset -@ifset ARC - -@emph{Target ARC options:} - [@b{-marc[5|6|7|8]}] - [@b{-EB}|@b{-EL}] -@end ifset -@ifset ARM - -@emph{Target ARM options:} -@c Don't document the deprecated options - [@b{-mcpu}=@var{processor}[+@var{extension}@dots{}]] - [@b{-march}=@var{architecture}[+@var{extension}@dots{}]] - [@b{-mfpu}=@var{floating-point-format}] - [@b{-mfloat-abi}=@var{abi}] - [@b{-mthumb}] - [@b{-EB}|@b{-EL}] - [@b{-mapcs-32}|@b{-mapcs-26}|@b{-mapcs-float}| - @b{-mapcs-reentrant}] - [@b{-mthumb-interwork}] [@b{-moabi}] [@b{-k}] -@end ifset -@ifset CRIS - -@emph{Target CRIS options:} - [@b{--underscore} | @b{--no-underscore}] - [@b{--pic}] [@b{-N}] - [@b{--emulation=criself} | @b{--emulation=crisaout}] -@c Deprecated -- deliberately not documented. -@c [@b{-h}] [@b{-H}] -@end ifset -@ifset D10V - -@emph{Target D10V options:} - [@b{-O}] -@end ifset -@ifset D30V - -@emph{Target D30V options:} - [@b{-O}|@b{-n}|@b{-N}] -@end ifset -@ifset H8 -@c Renesas family chips have no machine-dependent assembler options -@end ifset -@ifset HPPA -@c HPPA has no machine-dependent assembler options (yet). -@end ifset -@ifset I80386 - -@emph{Target i386 options:} - [@b{--32}|@b{--64}] [@b{-n}] -@end ifset -@ifset I960 - -@emph{Target i960 options:} -@c see md_parse_option in tc-i960.c - [@b{-ACA}|@b{-ACA_A}|@b{-ACB}|@b{-ACC}|@b{-AKA}|@b{-AKB}| - @b{-AKC}|@b{-AMC}] - [@b{-b}] [@b{-no-relax}] -@end ifset -@ifset IA64 - -@emph{Target IA-64 options:} - [@b{-mconstant-gp}|@b{-mauto-pic}] - [@b{-milp32}|@b{-milp64}|@b{-mlp64}|@b{-mp64}] - [@b{-mle}|@b{mbe}] - [@b{-x}|@b{-xexplicit}] [@b{-xauto}] [@b{-xdebug}] -@end ifset -@ifset IP2K - -@emph{Target IP2K options:} - [@b{-mip2022}|@b{-mip2022ext}] -@end ifset -@ifset M32R - -@emph{Target M32R options:} - [@b{--m32rx}|@b{--[no-]warn-explicit-parallel-conflicts}| - @b{--W[n]p}] -@end ifset -@ifset M680X0 - -@emph{Target M680X0 options:} - [@b{-l}] [@b{-m68000}|@b{-m68010}|@b{-m68020}|@dots{}] -@end ifset -@ifset M68HC11 - -@emph{Target M68HC11 options:} - [@b{-m68hc11}|@b{-m68hc12}|@b{-m68hcs12}] - [@b{-mshort}|@b{-mlong}] - [@b{-mshort-double}|@b{-mlong-double}] - [@b{--force-long-branchs}] [@b{--short-branchs}] - [@b{--strict-direct-mode}] [@b{--print-insn-syntax}] - [@b{--print-opcodes}] [@b{--generate-example}] -@end ifset -@ifset MCORE - -@emph{Target MCORE options:} - [@b{-jsri2bsr}] [@b{-sifilter}] [@b{-relax}] - [@b{-mcpu=[210|340]}] -@end ifset -@ifset MIPS - -@emph{Target MIPS options:} - [@b{-nocpp}] [@b{-EL}] [@b{-EB}] [@b{-O}[@var{optimization level}]] - [@b{-g}[@var{debug level}]] [@b{-G} @var{num}] [@b{-KPIC}] [@b{-call_shared}] - [@b{-non_shared}] [@b{-xgot}] [@b{--membedded-pic}] - [@b{-mabi}=@var{ABI}] [@b{-32}] [@b{-n32}] [@b{-64}] [@b{-mfp32}] [@b{-mgp32}] - [@b{-march}=@var{CPU}] [@b{-mtune}=@var{CPU}] [@b{-mips1}] [@b{-mips2}] - [@b{-mips3}] [@b{-mips4}] [@b{-mips5}] [@b{-mips32}] [@b{-mips32r2}] - [@b{-mips64}] [@b{-mips64r2}] - [@b{-construct-floats}] [@b{-no-construct-floats}] - [@b{-trap}] [@b{-no-break}] [@b{-break}] [@b{-no-trap}] - [@b{-mfix7000}] [@b{-mno-fix7000}] - [@b{-mips16}] [@b{-no-mips16}] - [@b{-mips3d}] [@b{-no-mips3d}] - [@b{-mdmx}] [@b{-no-mdmx}] - [@b{-mdebug}] [@b{-no-mdebug}] - [@b{-mpdr}] [@b{-mno-pdr}] -@end ifset -@ifset MMIX - -@emph{Target MMIX options:} - [@b{--fixed-special-register-names}] [@b{--globalize-symbols}] - [@b{--gnu-syntax}] [@b{--relax}] [@b{--no-predefined-symbols}] - [@b{--no-expand}] [@b{--no-merge-gregs}] [@b{-x}] - [@b{--linker-allocated-gregs}] -@end ifset -@ifset PDP11 - -@emph{Target PDP11 options:} - [@b{-mpic}|@b{-mno-pic}] [@b{-mall}] [@b{-mno-extensions}] - [@b{-m}@var{extension}|@b{-mno-}@var{extension}] - [@b{-m}@var{cpu}] [@b{-m}@var{machine}] -@end ifset -@ifset PJ - -@emph{Target picoJava options:} - [@b{-mb}|@b{-me}] -@end ifset -@ifset PPC - -@emph{Target PowerPC options:} - [@b{-mpwrx}|@b{-mpwr2}|@b{-mpwr}|@b{-m601}|@b{-mppc}|@b{-mppc32}|@b{-m603}|@b{-m604}| - @b{-m403}|@b{-m405}|@b{-mppc64}|@b{-m620}|@b{-mppc64bridge}|@b{-mbooke}| - @b{-mbooke32}|@b{-mbooke64}] - [@b{-mcom}|@b{-many}|@b{-maltivec}] [@b{-memb}] - [@b{-mregnames}|@b{-mno-regnames}] - [@b{-mrelocatable}|@b{-mrelocatable-lib}] - [@b{-mlittle}|@b{-mlittle-endian}|@b{-mbig}|@b{-mbig-endian}] - [@b{-msolaris}|@b{-mno-solaris}] -@end ifset -@ifset SPARC - -@emph{Target SPARC options:} -@c The order here is important. See c-sparc.texi. - [@b{-Av6}|@b{-Av7}|@b{-Av8}|@b{-Asparclet}|@b{-Asparclite} - @b{-Av8plus}|@b{-Av8plusa}|@b{-Av9}|@b{-Av9a}] - [@b{-xarch=v8plus}|@b{-xarch=v8plusa}] [@b{-bump}] - [@b{-32}|@b{-64}] -@end ifset -@ifset TIC54X - -@emph{Target TIC54X options:} - [@b{-mcpu=54[123589]}|@b{-mcpu=54[56]lp}] [@b{-mfar-mode}|@b{-mf}] - [@b{-merrors-to-file} @var{<filename>}|@b{-me} @var{<filename>}] -@end ifset -@ifset Z8000 -@c Z8000 has no machine-dependent assembler options -@end ifset -@ifset XTENSA - -@emph{Target Xtensa options:} - [@b{--[no-]density}] [@b{--[no-]relax}] [@b{--[no-]generics}] - [@b{--[no-]text-section-literals}] - [@b{--[no-]target-align}] [@b{--[no-]longcalls}] -@end ifset -@c man end -@end smallexample - -@c man begin OPTIONS - -@table @gcctabopt -@item -a[cdhlmns] -Turn on listings, in any of a variety of ways: - -@table @gcctabopt -@item -ac -omit false conditionals - -@item -ad -omit debugging directives - -@item -ah -include high-level source - -@item -al -include assembly - -@item -am -include macro expansions - -@item -an -omit forms processing - -@item -as -include symbols - -@item =file -set the name of the listing file -@end table - -You may combine these options; for example, use @samp{-aln} for assembly -listing without forms processing. The @samp{=file} option, if used, must be -the last one. By itself, @samp{-a} defaults to @samp{-ahls}. - -@item -D -Ignored. This option is accepted for script compatibility with calls to -other assemblers. - -@item --defsym @var{sym}=@var{value} -Define the symbol @var{sym} to be @var{value} before assembling the input file. -@var{value} must be an integer constant. As in C, a leading @samp{0x} -indicates a hexadecimal value, and a leading @samp{0} indicates an octal value. - -@item -f -``fast''---skip whitespace and comment preprocessing (assume source is -compiler output). - -@item --gstabs -Generate stabs debugging information for each assembler line. This -may help debugging assembler code, if the debugger can handle it. - -@item --gstabs+ -Generate stabs debugging information for each assembler line, with GNU -extensions that probably only gdb can handle, and that could make other -debuggers crash or refuse to read your program. This -may help debugging assembler code. Currently the only GNU extension is -the location of the current working directory at assembling time. - -@item --gdwarf2 -Generate DWARF2 debugging information for each assembler line. This -may help debugging assembler code, if the debugger can handle it. Note---this -option is only supported by some targets, not all of them. - -@item --help -Print a summary of the command line options and exit. - -@item --target-help -Print a summary of all target specific options and exit. - -@item -I @var{dir} -Add directory @var{dir} to the search list for @code{.include} directives. - -@item -J -Don't warn about signed overflow. - -@item -K -@ifclear DIFF-TBL-KLUGE -This option is accepted but has no effect on the @value{TARGET} family. -@end ifclear -@ifset DIFF-TBL-KLUGE -Issue warnings when difference tables altered for long displacements. -@end ifset - -@item -L -@itemx --keep-locals -Keep (in the symbol table) local symbols. On traditional a.out systems -these start with @samp{L}, but different systems have different local -label prefixes. - -@item --listing-lhs-width=@var{number} -Set the maximum width, in words, of the output data column for an assembler -listing to @var{number}. - -@item --listing-lhs-width2=@var{number} -Set the maximum width, in words, of the output data column for continuation -lines in an assembler listing to @var{number}. - -@item --listing-rhs-width=@var{number} -Set the maximum width of an input source line, as displayed in a listing, to -@var{number} bytes. - -@item --listing-cont-lines=@var{number} -Set the maximum number of lines printed in a listing for a single line of input -to @var{number} + 1. - -@item -o @var{objfile} -Name the object-file output from @command{@value{AS}} @var{objfile}. - -@item -R -Fold the data section into the text section. - -@item --statistics -Print the maximum space (in bytes) and total time (in seconds) used by -assembly. - -@item --strip-local-absolute -Remove local absolute symbols from the outgoing symbol table. - -@item -v -@itemx -version -Print the @command{as} version. - -@item --version -Print the @command{as} version and exit. - -@item -W -@itemx --no-warn -Suppress warning messages. - -@item --fatal-warnings -Treat warnings as errors. - -@item --warn -Don't suppress warning messages or treat them as errors. - -@item -w -Ignored. - -@item -x -Ignored. - -@item -Z -Generate an object file even after errors. - -@item -- | @var{files} @dots{} -Standard input, or source files to assemble. - -@end table - -@ifset ARC -The following options are available when @value{AS} is configured for -an ARC processor. - -@table @gcctabopt -@item -marc[5|6|7|8] -This option selects the core processor variant. -@item -EB | -EL -Select either big-endian (-EB) or little-endian (-EL) output. -@end table -@end ifset - -@ifset ARM -The following options are available when @value{AS} is configured for the ARM -processor family. - -@table @gcctabopt -@item -mcpu=@var{processor}[+@var{extension}@dots{}] -Specify which ARM processor variant is the target. -@item -march=@var{architecture}[+@var{extension}@dots{}] -Specify which ARM architecture variant is used by the target. -@item -mfpu=@var{floating-point-format} -Select which Floating Point architecture is the target. -@item -mfloat-abi=@var{abi} -Select which floating point ABI is in use. -@item -mthumb -Enable Thumb only instruction decoding. -@item -mapcs-32 | -mapcs-26 | -mapcs-float | -mapcs-reentrant | -moabi -Select which procedure calling convention is in use. -@item -EB | -EL -Select either big-endian (-EB) or little-endian (-EL) output. -@item -mthumb-interwork -Specify that the code has been generated with interworking between Thumb and -ARM code in mind. -@item -k -Specify that PIC code has been generated. -@end table -@end ifset - -@ifset CRIS -See the info pages for documentation of the CRIS-specific options. -@end ifset - -@ifset D10V -The following options are available when @value{AS} is configured for -a D10V processor. -@table @gcctabopt -@cindex D10V optimization -@cindex optimization, D10V -@item -O -Optimize output by parallelizing instructions. -@end table -@end ifset - -@ifset D30V -The following options are available when @value{AS} is configured for a D30V -processor. -@table @gcctabopt -@cindex D30V optimization -@cindex optimization, D30V -@item -O -Optimize output by parallelizing instructions. - -@cindex D30V nops -@item -n -Warn when nops are generated. - -@cindex D30V nops after 32-bit multiply -@item -N -Warn when a nop after a 32-bit multiply instruction is generated. -@end table -@end ifset - -@ifset I960 -The following options are available when @value{AS} is configured for the -Intel 80960 processor. - -@table @gcctabopt -@item -ACA | -ACA_A | -ACB | -ACC | -AKA | -AKB | -AKC | -AMC -Specify which variant of the 960 architecture is the target. - -@item -b -Add code to collect statistics about branches taken. - -@item -no-relax -Do not alter compare-and-branch instructions for long displacements; -error if necessary. - -@end table -@end ifset - -@ifset IP2K -The following options are available when @value{AS} is configured for the -Ubicom IP2K series. - -@table @gcctabopt - -@item -mip2022ext -Specifies that the extended IP2022 instructions are allowed. - -@item -mip2022 -Restores the default behaviour, which restricts the permitted instructions to -just the basic IP2022 ones. - -@end table -@end ifset - -@ifset M32R -The following options are available when @value{AS} is configured for the -Renesas M32R (formerly Mitsubishi M32R) series. - -@table @gcctabopt - -@item --m32rx -Specify which processor in the M32R family is the target. The default -is normally the M32R, but this option changes it to the M32RX. - -@item --warn-explicit-parallel-conflicts or --Wp -Produce warning messages when questionable parallel constructs are -encountered. - -@item --no-warn-explicit-parallel-conflicts or --Wnp -Do not produce warning messages when questionable parallel constructs are -encountered. - -@end table -@end ifset - -@ifset M680X0 -The following options are available when @value{AS} is configured for the -Motorola 68000 series. - -@table @gcctabopt - -@item -l -Shorten references to undefined symbols, to one word instead of two. - -@item -m68000 | -m68008 | -m68010 | -m68020 | -m68030 -@itemx | -m68040 | -m68060 | -m68302 | -m68331 | -m68332 -@itemx | -m68333 | -m68340 | -mcpu32 | -m5200 -Specify what processor in the 68000 family is the target. The default -is normally the 68020, but this can be changed at configuration time. - -@item -m68881 | -m68882 | -mno-68881 | -mno-68882 -The target machine does (or does not) have a floating-point coprocessor. -The default is to assume a coprocessor for 68020, 68030, and cpu32. Although -the basic 68000 is not compatible with the 68881, a combination of the -two can be specified, since it's possible to do emulation of the -coprocessor instructions with the main processor. - -@item -m68851 | -mno-68851 -The target machine does (or does not) have a memory-management -unit coprocessor. The default is to assume an MMU for 68020 and up. - -@end table -@end ifset - -@ifset PDP11 - -For details about the PDP-11 machine dependent features options, -see @ref{PDP-11-Options}. - -@table @gcctabopt -@item -mpic | -mno-pic -Generate position-independent (or position-dependent) code. The -default is @option{-mpic}. - -@item -mall -@itemx -mall-extensions -Enable all instruction set extensions. This is the default. - -@item -mno-extensions -Disable all instruction set extensions. - -@item -m@var{extension} | -mno-@var{extension} -Enable (or disable) a particular instruction set extension. - -@item -m@var{cpu} -Enable the instruction set extensions supported by a particular CPU, and -disable all other extensions. - -@item -m@var{machine} -Enable the instruction set extensions supported by a particular machine -model, and disable all other extensions. -@end table - -@end ifset - -@ifset PJ -The following options are available when @value{AS} is configured for -a picoJava processor. - -@table @gcctabopt - -@cindex PJ endianness -@cindex endianness, PJ -@cindex big endian output, PJ -@item -mb -Generate ``big endian'' format output. - -@cindex little endian output, PJ -@item -ml -Generate ``little endian'' format output. - -@end table -@end ifset - -@ifset M68HC11 -The following options are available when @value{AS} is configured for the -Motorola 68HC11 or 68HC12 series. - -@table @gcctabopt - -@item -m68hc11 | -m68hc12 | -m68hcs12 -Specify what processor is the target. The default is -defined by the configuration option when building the assembler. - -@item -mshort -Specify to use the 16-bit integer ABI. - -@item -mlong -Specify to use the 32-bit integer ABI. - -@item -mshort-double -Specify to use the 32-bit double ABI. - -@item -mlong-double -Specify to use the 64-bit double ABI. - -@item --force-long-branchs -Relative branches are turned into absolute ones. This concerns -conditional branches, unconditional branches and branches to a -sub routine. - -@item -S | --short-branchs -Do not turn relative branchs into absolute ones -when the offset is out of range. - -@item --strict-direct-mode -Do not turn the direct addressing mode into extended addressing mode -when the instruction does not support direct addressing mode. - -@item --print-insn-syntax -Print the syntax of instruction in case of error. - -@item --print-opcodes -print the list of instructions with syntax and then exit. - -@item --generate-example -print an example of instruction for each possible instruction and then exit. -This option is only useful for testing @command{@value{AS}}. - -@end table -@end ifset - -@ifset SPARC -The following options are available when @command{@value{AS}} is configured -for the SPARC architecture: - -@table @gcctabopt -@item -Av6 | -Av7 | -Av8 | -Asparclet | -Asparclite -@itemx -Av8plus | -Av8plusa | -Av9 | -Av9a -Explicitly select a variant of the SPARC architecture. - -@samp{-Av8plus} and @samp{-Av8plusa} select a 32 bit environment. -@samp{-Av9} and @samp{-Av9a} select a 64 bit environment. - -@samp{-Av8plusa} and @samp{-Av9a} enable the SPARC V9 instruction set with -UltraSPARC extensions. - -@item -xarch=v8plus | -xarch=v8plusa -For compatibility with the Solaris v9 assembler. These options are -equivalent to -Av8plus and -Av8plusa, respectively. - -@item -bump -Warn when the assembler switches to another architecture. -@end table -@end ifset - -@ifset TIC54X -The following options are available when @value{AS} is configured for the 'c54x -architecture. - -@table @gcctabopt -@item -mfar-mode -Enable extended addressing mode. All addresses and relocations will assume -extended addressing (usually 23 bits). -@item -mcpu=@var{CPU_VERSION} -Sets the CPU version being compiled for. -@item -merrors-to-file @var{FILENAME} -Redirect error output to a file, for broken systems which don't support such -behaviour in the shell. -@end table -@end ifset - -@ifset MIPS -The following options are available when @value{AS} is configured for -a @sc{mips} processor. - -@table @gcctabopt -@item -G @var{num} -This option sets the largest size of an object that can be referenced -implicitly with the @code{gp} register. It is only accepted for targets that -use ECOFF format, such as a DECstation running Ultrix. The default value is 8. - -@cindex MIPS endianness -@cindex endianness, MIPS -@cindex big endian output, MIPS -@item -EB -Generate ``big endian'' format output. - -@cindex little endian output, MIPS -@item -EL -Generate ``little endian'' format output. - -@cindex MIPS ISA -@item -mips1 -@itemx -mips2 -@itemx -mips3 -@itemx -mips4 -@itemx -mips5 -@itemx -mips32 -@itemx -mips32r2 -@itemx -mips64 -@itemx -mips64r2 -Generate code for a particular @sc{mips} Instruction Set Architecture level. -@samp{-mips1} is an alias for @samp{-march=r3000}, @samp{-mips2} is an -alias for @samp{-march=r6000}, @samp{-mips3} is an alias for -@samp{-march=r4000} and @samp{-mips4} is an alias for @samp{-march=r8000}. -@samp{-mips5}, @samp{-mips32}, @samp{-mips32r2}, @samp{-mips64}, and -@samp{-mips64r2} -correspond to generic -@samp{MIPS V}, @samp{MIPS32}, @samp{MIPS32 Release 2}, @samp{MIPS64}, -and @samp{MIPS64 Release 2} -ISA processors, respectively. - -@item -march=@var{CPU} -Generate code for a particular @sc{mips} cpu. - -@item -mtune=@var{cpu} -Schedule and tune for a particular @sc{mips} cpu. - -@item -mfix7000 -@itemx -mno-fix7000 -Cause nops to be inserted if the read of the destination register -of an mfhi or mflo instruction occurs in the following two instructions. - -@item -mdebug -@itemx -no-mdebug -Cause stabs-style debugging output to go into an ECOFF-style .mdebug -section instead of the standard ELF .stabs sections. - -@item -mpdr -@itemx -mno-pdr -Control generation of @code{.pdr} sections. - -@item -mgp32 -@itemx -mfp32 -The register sizes are normally inferred from the ISA and ABI, but these -flags force a certain group of registers to be treated as 32 bits wide at -all times. @samp{-mgp32} controls the size of general-purpose registers -and @samp{-mfp32} controls the size of floating-point registers. - -@item -mips16 -@itemx -no-mips16 -Generate code for the MIPS 16 processor. This is equivalent to putting -@code{.set mips16} at the start of the assembly file. @samp{-no-mips16} -turns off this option. - -@item -mips3d -@itemx -no-mips3d -Generate code for the MIPS-3D Application Specific Extension. -This tells the assembler to accept MIPS-3D instructions. -@samp{-no-mips3d} turns off this option. - -@item -mdmx -@itemx -no-mdmx -Generate code for the MDMX Application Specific Extension. -This tells the assembler to accept MDMX instructions. -@samp{-no-mdmx} turns off this option. - -@item --construct-floats -@itemx --no-construct-floats -The @samp{--no-construct-floats} option disables the construction of -double width floating point constants by loading the two halves of the -value into the two single width floating point registers that make up -the double width register. By default @samp{--construct-floats} is -selected, allowing construction of these floating point constants. - -@cindex emulation -@item --emulation=@var{name} -This option causes @command{@value{AS}} to emulate @command{@value{AS}} configured -for some other target, in all respects, including output format (choosing -between ELF and ECOFF only), handling of pseudo-opcodes which may generate -debugging information or store symbol table information, and default -endianness. The available configuration names are: @samp{mipsecoff}, -@samp{mipself}, @samp{mipslecoff}, @samp{mipsbecoff}, @samp{mipslelf}, -@samp{mipsbelf}. The first two do not alter the default endianness from that -of the primary target for which the assembler was configured; the others change -the default to little- or big-endian as indicated by the @samp{b} or @samp{l} -in the name. Using @samp{-EB} or @samp{-EL} will override the endianness -selection in any case. - -This option is currently supported only when the primary target -@command{@value{AS}} is configured for is a @sc{mips} ELF or ECOFF target. -Furthermore, the primary target or others specified with -@samp{--enable-targets=@dots{}} at configuration time must include support for -the other format, if both are to be available. For example, the Irix 5 -configuration includes support for both. - -Eventually, this option will support more configurations, with more -fine-grained control over the assembler's behavior, and will be supported for -more processors. - -@item -nocpp -@command{@value{AS}} ignores this option. It is accepted for compatibility with -the native tools. - -@item --trap -@itemx --no-trap -@itemx --break -@itemx --no-break -Control how to deal with multiplication overflow and division by zero. -@samp{--trap} or @samp{--no-break} (which are synonyms) take a trap exception -(and only work for Instruction Set Architecture level 2 and higher); -@samp{--break} or @samp{--no-trap} (also synonyms, and the default) take a -break exception. - -@item -n -When this option is used, @command{@value{AS}} will issue a warning every -time it generates a nop instruction from a macro. -@end table -@end ifset - -@ifset MCORE -The following options are available when @value{AS} is configured for -an MCore processor. - -@table @gcctabopt -@item -jsri2bsr -@itemx -nojsri2bsr -Enable or disable the JSRI to BSR transformation. By default this is enabled. -The command line option @samp{-nojsri2bsr} can be used to disable it. - -@item -sifilter -@itemx -nosifilter -Enable or disable the silicon filter behaviour. By default this is disabled. -The default can be overridden by the @samp{-sifilter} command line option. - -@item -relax -Alter jump instructions for long displacements. - -@item -mcpu=[210|340] -Select the cpu type on the target hardware. This controls which instructions -can be assembled. - -@item -EB -Assemble for a big endian target. - -@item -EL -Assemble for a little endian target. - -@end table -@end ifset - -@ifset MMIX -See the info pages for documentation of the MMIX-specific options. -@end ifset - -@ifset XTENSA -The following options are available when @value{AS} is configured for -an Xtensa processor. - -@table @gcctabopt -@item --density | --no-density -Enable or disable use of instructions from the Xtensa code density -option. This is enabled by default when the Xtensa processor supports -the code density option. - -@item --relax | --no-relax -Enable or disable instruction relaxation. This is enabled by default. -Note: In the current implementation, these options also control whether -assembler optimizations are performed, making these options equivalent -to @option{--generics} and @option{--no-generics}. - -@item --generics | --no-generics -Enable or disable all assembler transformations of Xtensa instructions. -The default is @option{--generics}; -@option{--no-generics} should be used only in the rare cases when the -instructions must be exactly as specified in the assembly source. - -@item --text-section-literals | --no-text-section-literals -With @option{--text-@-section-@-literals}, literal pools are interspersed -in the text section. The default is -@option{--no-@-text-@-section-@-literals}, which places literals in a -separate section in the output file. - -@item --target-align | --no-target-align -Enable or disable automatic alignment to reduce branch penalties at the -expense of some code density. The default is @option{--target-@-align}. - -@item --longcalls | --no-longcalls -Enable or disable transformation of call instructions to allow calls -across a greater range of addresses. The default is -@option{--no-@-longcalls}. -@end table -@end ifset - -@c man end - -@menu -* Manual:: Structure of this Manual -* GNU Assembler:: 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 -@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} @command{@value{AS}}. We cover the syntax expected in source files, including -notation for symbols, constants, and expressions; the directives that -@command{@value{AS}} understands; and of course how to invoke @command{@value{AS}}. - -@ifclear GENERIC -We also cover special features in the @value{TARGET} -configuration of @command{@value{AS}}, including assembler directives. -@end ifclear -@ifset GENERIC -This manual also describes some of the machine-dependent features of -various flavors of the assembler. -@end ifset - -@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. -@ifset GENERIC -You may want to consult the manufacturer's -machine architecture manual for this information. -@end ifset -@ifclear GENERIC -@ifset H8/300 -For information on the H8/300 machine instruction set, see @cite{H8/300 -Series Programming Manual}. For the H8/300H, see @cite{H8/300H Series -Programming Manual} (Renesas). -@end ifset -@ifset H8/500 -For information on the H8/500 machine instruction set, see @cite{H8/500 -Series Programming Manual} (Renesas M21T001). -@end ifset -@ifset SH -For information on the Renesas (formerly Hitachi) / SuperH SH machine instruction set, -see @cite{SH-Microcomputer User's Manual} (Renesas) or -@cite{SH-4 32-bit CPU Core Architecture} (SuperH) and -@cite{SuperH (SH) 64-Bit RISC Series} (SuperH). -@end ifset -@ifset Z8000 -For information on the Z8000 machine instruction set, see @cite{Z8000 CPU Technical Manual} -@end ifset -@end ifclear - -@c I think this is premature---doc@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 @sc{gnu} can run on); -once this assumption is granted examples and definitions need less -qualification. - -@command{@value{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 -@command{@value{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 -@section The GNU Assembler - -@c man begin DESCRIPTION - -@sc{gnu} @command{as} is really a family of assemblers. -@ifclear GENERIC -This manual describes @command{@value{AS}}, a member of that family which is -configured for the @value{TARGET} architectures. -@end ifclear -If you use (or have used) the @sc{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 - -@cindex purpose of @sc{gnu} assembler -@command{@value{AS}} is primarily intended to assemble the output of the -@sc{gnu} C compiler @code{@value{GCC}} for use by the linker -@code{@value{LD}}. Nevertheless, we've tried to make @command{@value{AS}} -assemble correctly everything that other assemblers for the same -machine would assemble. -@ifset VAX -Any exceptions are documented explicitly (@pxref{Machine Dependencies}). -@end ifset -@ifset M680X0 -@c This remark should appear in generic version of manual; assumption -@c here is that generic version sets M680x0. -This doesn't mean @command{@value{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. -@end ifset - -@c man end - -Unlike older assemblers, @command{@value{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 -@section Object File Formats - -@cindex object file format -The @sc{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}. -@ifclear GENERIC -@ifclear MULTI-OBJ -For the @value{TARGET} target, @command{@value{AS}} is configured to produce -@value{OBJ-NAME} format object files. -@end ifclear -@c The following should exhaust all configs that set MULTI-OBJ, ideally -@ifset A29K -On the @value{TARGET}, @command{@value{AS}} can be configured to produce either -@code{a.out} or COFF format object files. -@end ifset -@ifset I960 -On the @value{TARGET}, @command{@value{AS}} can be configured to produce either -@code{b.out} or COFF format object files. -@end ifset -@ifset HPPA -On the @value{TARGET}, @command{@value{AS}} can be configured to produce either -SOM or ELF format object files. -@end ifset -@end ifclear - -@node Command Line -@section Command Line - -@cindex command line conventions - -After the program name @command{@value{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 @command{@value{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 -@command{@value{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 (@sc{gnu} -standard). These two command lines are equivalent: - -@smallexample -@value{AS} -o my-object-file.o mumble.s -@value{AS} -omy-object-file.o mumble.s -@end smallexample - -@node Input Files -@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 @command{@value{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... doc@cygnus.com -The source program is a concatenation of the text in all the files, in the -order specified. - -@c man begin DESCRIPTION -Each time you run @command{@value{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 @command{@value{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 @command{@value{AS}} no file names it attempts to read one input file -from the @command{@value{AS}} standard input, which is normally your terminal. You -may have to type @key{ctl-D} to tell @command{@value{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, @command{@value{AS}} produces a small, empty object -file. - -@c man end - -@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 @command{@value{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 @command{@value{AS}} source -is itself synthesized from other files. @command{@value{AS}} understands the -@samp{#} directives emitted by the @code{@value{GCC}} preprocessor. See also -@ref{File,,@code{.file}}. - -@node Object -@section Output (Object) File - -@cindex object file -@cindex output file -@kindex a.out -@kindex .o -Every time you run @command{@value{AS}} it produces an output file, which is -your assembly language program translated into numbers. This file -is the object file. Its default name is -@ifclear BOUT -@code{a.out}. -@end ifclear -@ifset BOUT -@ifset GENERIC -@code{a.out}, or -@end ifset -@code{b.out} when @command{@value{AS}} is configured for the Intel 80960. -@end ifset -You can give it another name by using the @option{-o} option. Conventionally, -object file names end with @file{.o}. The default name is used for historical -reasons: older assemblers were capable of assembling self-contained programs -directly into a runnable program. (For some formats, this isn't currently -possible, but it can be done for the @code{a.out} format.) - -@cindex linker -@kindex ld -The object file is meant for input to the linker @code{@value{LD}}. It contains -assembled program code, information to help @code{@value{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 @sc{gnu} info as well as Unix lossage. - -@node Errors -@section Error and Warning Messages - -@c man begin DESCRIPTION - -@cindex error messages -@cindex warning messages -@cindex messages from assembler -@command{@value{AS}} may write warnings and error messages to the standard error -file (usually your terminal). This should not happen when a compiler -runs @command{@value{AS}} automatically. Warnings report an assumption made so -that @command{@value{AS}} could keep assembling a flawed program; errors report a -grave problem that stops the assembly. - -@c man end - -@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{File,,@code{.file}}) it is used for the filename, otherwise the name of -the current input file is used. If a logical line number was given -@ifset GENERIC -(@pxref{Line,,@code{.line}}) -@end ifset -@ifclear GENERIC -@ifclear A29K -(@pxref{Line,,@code{.line}}) -@end ifclear -@ifset A29K -(@pxref{Ln,,@code{.ln}}) -@end ifset -@end ifclear -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). - -@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 -@chapter Command-Line Options - -@cindex options, all versions of assembler -This chapter describes command-line options available in @emph{all} -versions of the @sc{gnu} assembler; @pxref{Machine Dependencies}, for options specific -@ifclear GENERIC -to the @value{TARGET} target. -@end ifclear -@ifset GENERIC -to particular machine architectures. -@end ifset - -@c man begin DESCRIPTION - -If you are invoking @command{@value{AS}} via the @sc{gnu} C compiler, -you can use the @samp{-Wa} option to pass arguments through to the assembler. -The assembler arguments must be separated from each other (and the @samp{-Wa}) -by commas. For example: - -@smallexample -gcc -c -g -O -Wa,-alh,-L file.c -@end smallexample - -@noindent -This passes two options to the assembler: @samp{-alh} (emit a listing to -standard output with high-level and assembly source) and @samp{-L} (retain -local symbols in the symbol table). - -Usually you do not need to use this @samp{-Wa} mechanism, since many compiler -command-line options are automatically passed to the assembler by the compiler. -(You can call the @sc{gnu} compiler driver with the @samp{-v} option to see -precisely what options it passes to each compilation pass, including the -assembler.) - -@c man end - -@menu -* a:: -a[cdhlns] enable listings -* D:: -D for compatibility -* f:: -f to work faster -* I:: -I for .include search path -@ifclear DIFF-TBL-KLUGE -* K:: -K for compatibility -@end ifclear -@ifset DIFF-TBL-KLUGE -* K:: -K for difference tables -@end ifset - -* L:: -L to retain local labels -* listing:: --listing-XXX to configure listing output -* M:: -M or --mri to assemble in MRI compatibility mode -* MD:: --MD for dependency tracking -* o:: -o to name the object file -* R:: -R to join data and text sections -* statistics:: --statistics to see statistics about assembly -* traditional-format:: --traditional-format for compatible output -* v:: -v to announce version -* W:: -W, --no-warn, --warn, --fatal-warnings to control warnings -* Z:: -Z to make object file even after errors -@end menu - -@node a -@section Enable Listings: @option{-a[cdhlns]} - -@kindex -a -@kindex -ac -@kindex -ad -@kindex -ah -@kindex -al -@kindex -an -@kindex -as -@cindex listings, enabling -@cindex assembly listings, enabling - -These options enable listing output from the assembler. By itself, -@samp{-a} requests high-level, assembly, and symbols listing. -You can use other letters to select specific options for the list: -@samp{-ah} requests a high-level language listing, -@samp{-al} requests an output-program assembly listing, and -@samp{-as} requests a symbol table listing. -High-level listings require that a compiler debugging option like -@samp{-g} be used, and that assembly listings (@samp{-al}) be requested -also. - -Use the @samp{-ac} option to omit false conditionals from a listing. Any lines -which are not assembled because of a false @code{.if} (or @code{.ifdef}, or any -other conditional), or a true @code{.if} followed by an @code{.else}, will be -omitted from the listing. - -Use the @samp{-ad} option to omit debugging directives from the -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}. -The @samp{-an} option turns off all forms processing. -If you do not request listing output with one of the @samp{-a} options, the -listing-control directives have no effect. - -The letters after @samp{-a} may be combined into one option, -@emph{e.g.}, @samp{-aln}. - -Note if the assembler source is coming from the standard input (eg because it -is being created by @code{@value{GCC}} and the @samp{-pipe} command line switch -is being used) then the listing will not contain any comments or preprocessor -directives. This is because the listing code buffers input source lines from -stdin only after they have been preprocessed by the assembler. This reduces -memory usage and makes the code more efficient. - -@node D -@section @option{-D} - -@kindex -D -This option has no effect whatsoever, but it is accepted to make it more -likely that scripts written for other assemblers also work with -@command{@value{AS}}. - -@node f -@section Work Faster: @option{-f} - -@kindex -f -@cindex trusted compiler -@cindex faster processing (@option{-f}) -@samp{-f} should only be used when assembling programs written by a -(trusted) compiler. @samp{-f} stops the assembler from doing whitespace -and comment preprocessing on -the input file(s) before assembling them. @xref{Preprocessing, -,Preprocessing}. - -@quotation -@emph{Warning:} if you use @samp{-f} when the files actually need to be -preprocessed (if they contain comments, for example), @command{@value{AS}} does -not work correctly. -@end quotation - -@node I -@section @code{.include} Search Path: @option{-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 -@command{@value{AS}} searches for files specified in @code{.include} -directives (@pxref{Include,,@code{.include}}). You may use @option{-I} as -many times as necessary to include a variety of paths. The current -working directory is always searched first; after that, @command{@value{AS}} -searches any @samp{-I} directories in the same order as they were -specified (left to right) on the command line. - -@node K -@section Difference Tables: @option{-K} - -@kindex -K -@ifclear DIFF-TBL-KLUGE -On the @value{TARGET} family, this option is allowed, but has no effect. It is -permitted for compatibility with the @sc{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 @value{TARGET} -family does not have the addressing limitations that sometimes lead to this -alteration on other platforms. -@end ifclear - -@ifset DIFF-TBL-KLUGE -@cindex difference tables, warning -@cindex warning for altered difference tables -@command{@value{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. -@end ifset - -@node L -@section Include Local Labels: @option{-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 do not 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 @command{@value{AS}} and @code{@value{LD}} discard such labels, so you do not -normally debug with them. - -This option tells @command{@value{AS}} to retain those @samp{L@dots{}} symbols -in the object file. Usually if you do this you also tell the linker -@code{@value{LD}} to preserve symbols whose names begin with @samp{L}. - -By default, a local label is any label beginning with @samp{L}, but each -target is allowed to redefine the local label prefix. -@ifset HPPA -On the HPPA local labels begin with @samp{L$}. -@end ifset - -@node listing -@section Configuring listing output: @option{--listing} - -The listing feature of the assembler can be enabled via the command line switch -@samp{-a} (@pxref{a}). This feature combines the input source file(s) with a -hex dump of the corresponding locations in the output object file, and displays -them as a listing file. The format of this listing can be controlled by pseudo -ops inside the assembler source (@pxref{List} @pxref{Title} @pxref{Sbttl} -@pxref{Psize} @pxref{Eject}) and also by the following switches: - -@table @gcctabopt -@item --listing-lhs-width=@samp{number} -@kindex --listing-lhs-width -@cindex Width of first line disassembly output -Sets the maximum width, in words, of the first line of the hex byte dump. This -dump appears on the left hand side of the listing output. - -@item --listing-lhs-width2=@samp{number} -@kindex --listing-lhs-width2 -@cindex Width of continuation lines of disassembly output -Sets the maximum width, in words, of any further lines of the hex byte dump for -a given input source line. If this value is not specified, it defaults to being -the same as the value specified for @samp{--listing-lhs-width}. If neither -switch is used the default is to one. - -@item --listing-rhs-width=@samp{number} -@kindex --listing-rhs-width -@cindex Width of source line output -Sets the maximum width, in characters, of the source line that is displayed -alongside the hex dump. The default value for this parameter is 100. The -source line is displayed on the right hand side of the listing output. - -@item --listing-cont-lines=@samp{number} -@kindex --listing-cont-lines -@cindex Maximum number of continuation lines -Sets the maximum number of continuation lines of hex dump that will be -displayed for a given single line of source input. The default value is 4. -@end table - -@node M -@section Assemble in MRI Compatibility Mode: @option{-M} - -@kindex -M -@cindex MRI compatibility mode -The @option{-M} or @option{--mri} option selects MRI compatibility mode. This -changes the syntax and pseudo-op handling of @command{@value{AS}} to make it -compatible with the @code{ASM68K} or the @code{ASM960} (depending upon the -configured target) assembler from Microtec Research. The exact nature of the -MRI syntax will not be documented here; see the MRI manuals for more -information. Note in particular that the handling of macros and macro -arguments is somewhat different. The purpose of this option is to permit -assembling existing MRI assembler code using @command{@value{AS}}. - -The MRI compatibility is not complete. Certain operations of the MRI assembler -depend upon its object file format, and can not be supported using other object -file formats. Supporting these would require enhancing each object file format -individually. These are: - -@itemize @bullet -@item global symbols in common section - -The m68k MRI assembler supports common sections which are merged by the linker. -Other object file formats do not support this. @command{@value{AS}} handles -common sections by treating them as a single common symbol. It permits local -symbols to be defined within a common section, but it can not support global -symbols, since it has no way to describe them. - -@item complex relocations - -The MRI assemblers support relocations against a negated section address, and -relocations which combine the start addresses of two or more sections. These -are not support by other object file formats. - -@item @code{END} pseudo-op specifying start address - -The MRI @code{END} pseudo-op permits the specification of a start address. -This is not supported by other object file formats. The start address may -instead be specified using the @option{-e} option to the linker, or in a linker -script. - -@item @code{IDNT}, @code{.ident} and @code{NAME} pseudo-ops - -The MRI @code{IDNT}, @code{.ident} and @code{NAME} pseudo-ops assign a module -name to the output file. This is not supported by other object file formats. - -@item @code{ORG} pseudo-op - -The m68k MRI @code{ORG} pseudo-op begins an absolute section at a given -address. This differs from the usual @command{@value{AS}} @code{.org} pseudo-op, -which changes the location within the current section. Absolute sections are -not supported by other object file formats. The address of a section may be -assigned within a linker script. -@end itemize - -There are some other features of the MRI assembler which are not supported by -@command{@value{AS}}, typically either because they are difficult or because they -seem of little consequence. Some of these may be supported in future releases. - -@itemize @bullet - -@item EBCDIC strings - -EBCDIC strings are not supported. - -@item packed binary coded decimal - -Packed binary coded decimal is not supported. This means that the @code{DC.P} -and @code{DCB.P} pseudo-ops are not supported. - -@item @code{FEQU} pseudo-op - -The m68k @code{FEQU} pseudo-op is not supported. - -@item @code{NOOBJ} pseudo-op - -The m68k @code{NOOBJ} pseudo-op is not supported. - -@item @code{OPT} branch control options - -The m68k @code{OPT} branch control options---@code{B}, @code{BRS}, @code{BRB}, -@code{BRL}, and @code{BRW}---are ignored. @command{@value{AS}} automatically -relaxes all branches, whether forward or backward, to an appropriate size, so -these options serve no purpose. - -@item @code{OPT} list control options - -The following m68k @code{OPT} list control options are ignored: @code{C}, -@code{CEX}, @code{CL}, @code{CRE}, @code{E}, @code{G}, @code{I}, @code{M}, -@code{MEX}, @code{MC}, @code{MD}, @code{X}. - -@item other @code{OPT} options - -The following m68k @code{OPT} options are ignored: @code{NEST}, @code{O}, -@code{OLD}, @code{OP}, @code{P}, @code{PCO}, @code{PCR}, @code{PCS}, @code{R}. - -@item @code{OPT} @code{D} option is default - -The m68k @code{OPT} @code{D} option is the default, unlike the MRI assembler. -@code{OPT NOD} may be used to turn it off. - -@item @code{XREF} pseudo-op. - -The m68k @code{XREF} pseudo-op is ignored. - -@item @code{.debug} pseudo-op - -The i960 @code{.debug} pseudo-op is not supported. - -@item @code{.extended} pseudo-op - -The i960 @code{.extended} pseudo-op is not supported. - -@item @code{.list} pseudo-op. - -The various options of the i960 @code{.list} pseudo-op are not supported. - -@item @code{.optimize} pseudo-op - -The i960 @code{.optimize} pseudo-op is not supported. - -@item @code{.output} pseudo-op - -The i960 @code{.output} pseudo-op is not supported. - -@item @code{.setreal} pseudo-op - -The i960 @code{.setreal} pseudo-op is not supported. - -@end itemize - -@node MD -@section Dependency Tracking: @option{--MD} - -@kindex --MD -@cindex dependency tracking -@cindex make rules - -@command{@value{AS}} can generate a dependency file for the file it creates. This -file consists of a single rule suitable for @code{make} describing the -dependencies of the main source file. - -The rule is written to the file named in its argument. - -This feature is used in the automatic updating of makefiles. - -@node o -@section Name the Object File: @option{-o} - -@kindex -o -@cindex naming object file -@cindex object file name -There is always one object file output when you run @command{@value{AS}}. By -default it has the name -@ifset GENERIC -@ifset I960 -@file{a.out} (or @file{b.out}, for Intel 960 targets only). -@end ifset -@ifclear I960 -@file{a.out}. -@end ifclear -@end ifset -@ifclear GENERIC -@ifset I960 -@file{b.out}. -@end ifset -@ifclear I960 -@file{a.out}. -@end ifclear -@end ifclear -You use this option (which takes exactly one filename) to give the -object file a different name. - -Whatever the object file is called, @command{@value{AS}} overwrites any -existing file of the same name. - -@node R -@section Join Data and Text Sections: @option{-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 -@option{-R} tells @command{@value{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 its bytes are -appended to the text section. (@xref{Sections,,Sections and Relocation}.) - -When you specify @option{-R} it would be possible to generate shorter -address displacements (because we do not have to cross between text and -data section). We refrain from doing this simply for compatibility with -older versions of @command{@value{AS}}. In future, @option{-R} may work this way. - -@ifset COFF-ELF -When @command{@value{AS}} is configured for COFF or ELF output, -this option is only useful if you use sections named @samp{.text} and -@samp{.data}. -@end ifset - -@ifset HPPA -@option{-R} is not supported for any of the HPPA targets. Using -@option{-R} generates a warning from @command{@value{AS}}. -@end ifset - -@node statistics -@section Display Assembly Statistics: @option{--statistics} - -@kindex --statistics -@cindex statistics, about assembly -@cindex time, total for assembly -@cindex space used, maximum for assembly -Use @samp{--statistics} to display two statistics about the resources used by -@command{@value{AS}}: the maximum amount of space allocated during the assembly -(in bytes), and the total execution time taken for the assembly (in @sc{cpu} -seconds). - -@node traditional-format -@section Compatible Output: @option{--traditional-format} - -@kindex --traditional-format -For some targets, the output of @command{@value{AS}} is different in some ways -from the output of some existing assembler. This switch requests -@command{@value{AS}} to use the traditional format instead. - -For example, it disables the exception frame optimizations which -@command{@value{AS}} normally does by default on @code{@value{GCC}} output. - -@node v -@section Announce Version: @option{-v} - -@kindex -v -@kindex -version -@cindex assembler version -@cindex version of assembler -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. - -@node W -@section Control Warnings: @option{-W}, @option{--warn}, @option{--no-warn}, @option{--fatal-warnings} - -@command{@value{AS}} should never give a warning or error message when -assembling compiler output. But programs written by people often -cause @command{@value{AS}} to give a warning that a particular assumption was -made. All such warnings are directed to the standard error file. - -@kindex -W -@kindex --no-warn -@cindex suppressing warnings -@cindex warnings, suppressing -If you use the @option{-W} and @option{--no-warn} options, no warnings are issued. -This only affects the warning messages: it does not change any particular of -how @command{@value{AS}} assembles your file. Errors, which stop the assembly, -are still reported. - -@kindex --fatal-warnings -@cindex errors, caused by warnings -@cindex warnings, causing error -If you use the @option{--fatal-warnings} option, @command{@value{AS}} considers -files that generate warnings to be in error. - -@kindex --warn -@cindex warnings, switching on -You can switch these options off again by specifying @option{--warn}, which -causes warnings to be output as usual. - -@node Z -@section Generate Object File in Spite of Errors: @option{-Z} -@cindex object file, after errors -@cindex errors, continuing after -After an error message, @command{@value{AS}} normally produces no output. If for -some reason you are interested in object file output even after -@command{@value{AS}} gives an error message on your program, use the @samp{-Z} -option. If there are any errors, @command{@value{AS}} continues anyways, and -writes an object file after a final warning message of the form @samp{@var{n} -errors, @var{m} warnings, generating bad object file.} - -@node Syntax -@chapter Syntax - -@cindex machine-independent syntax -@cindex syntax, machine-independent -This chapter describes the machine-independent syntax allowed in a -source file. @command{@value{AS}} syntax is similar to what many other -assemblers use; it is inspired by the BSD 4.2 -@ifclear VAX -assembler. -@end ifclear -@ifset VAX -assembler, except that @command{@value{AS}} does not assemble Vax bit-fields. -@end ifset - -@menu -* Preprocessing:: Preprocessing -* Whitespace:: Whitespace -* Comments:: Comments -* Symbol Intro:: Symbols -* Statements:: Statements -* Constants:: Constants -@end menu - -@node Preprocessing -@section Preprocessing - -@cindex preprocessing -The @command{@value{AS}} internal preprocessor: -@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 - -It does not do macro processing, include file handling, or -anything else you may get from your C compiler's preprocessor. You can -do include file processing with the @code{.include} directive -(@pxref{Include,,@code{.include}}). You can use the @sc{gnu} C compiler driver -to get other ``CPP'' style preprocessing by giving the input file a -@samp{.S} suffix. @xref{Overall Options,, Options Controlling the Kind of -Output, gcc.info, Using GNU CC}. - -Excess whitespace, comments, and character constants -cannot be used in the portions of the input text that are not -preprocessed. - -@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 if you use the -@samp{-f} option, whitespace and comments are not removed from the input file. -Within an input file, you can ask for whitespace and comment removal in -specific portions of the by putting a line that says @code{#APP} before the -text that may contain whitespace or comments, and putting a line that says -@code{#NO_APP} after this text. This feature is mainly intend to support -@code{asm} statements in compilers whose output is otherwise free of comments -and whitespace. - -@node Whitespace -@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 -@section Comments - -@cindex comments -There are two ways of rendering comments to @command{@value{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 -@ifset A29K -@samp{;} for the AMD 29K family; -@end ifset -@ifset ARC -@samp{;} on the ARC; -@end ifset -@ifset ARM -@samp{@@} on the ARM; -@end ifset -@ifset H8/300 -@samp{;} for the H8/300 family; -@end ifset -@ifset H8/500 -@samp{!} for the H8/500 family; -@end ifset -@ifset HPPA -@samp{;} for the HPPA; -@end ifset -@ifset I80386 -@samp{#} on the i386 and x86-64; -@end ifset -@ifset I960 -@samp{#} on the i960; -@end ifset -@ifset PDP11 -@samp{;} for the PDP-11; -@end ifset -@ifset PJ -@samp{;} for picoJava; -@end ifset -@ifset PPC -@samp{#} for Motorola PowerPC; -@end ifset -@ifset SH -@samp{!} for the Renesas / SuperH SH; -@end ifset -@ifset SPARC -@samp{!} on the SPARC; -@end ifset -@ifset IP2K -@samp{#} on the ip2k; -@end ifset -@ifset M32R -@samp{#} on the m32r; -@end ifset -@ifset M680X0 -@samp{|} on the 680x0; -@end ifset -@ifset M68HC11 -@samp{#} on the 68HC11 and 68HC12; -@end ifset -@ifset M880X0 -@samp{;} on the M880x0; -@end ifset -@ifset VAX -@samp{#} on the Vax; -@end ifset -@ifset Z8000 -@samp{!} for the Z8000; -@end ifset -@ifset V850 -@samp{#} on the V850; -@end ifset -@ifset XTENSA -@samp{#} for Xtensa systems; -@end ifset -see @ref{Machine Dependencies}. @refill -@c FIXME What about i860? - -@ifset GENERIC -On some machines there are two different line comment characters. One -character only begins a comment if it is the first non-whitespace character on -a line, while the other always begins a comment. -@end ifset - -@ifset V850 -The V850 assembler also supports a double dash as starting a comment that -extends to the end of the line. - -@samp{--}; -@end ifset - -@kindex # -@cindex lines starting with @code{#} -@cindex logical line numbers -To be compatible with past assemblers, lines that begin with @samp{#} have a -special interpretation. Following the @samp{#} should be an absolute -expression (@pxref{Expressions}): the logical line number of the @emph{next} -line. Then a string (@pxref{Strings,, 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 @command{@value{AS}}. - -@node Symbol Intro -@section Symbols - -@cindex characters used in symbols -@ifclear SPECIAL-SYMS -A @dfn{symbol} is one or more characters chosen from the set of all -letters (both upper and lower case), digits and the three characters -@samp{_.$}. -@end ifclear -@ifset SPECIAL-SYMS -@ifclear GENERIC -@ifset H8 -A @dfn{symbol} is one or more characters chosen from the set of all -letters (both upper and lower case), digits and the three characters -@samp{._$}. (Save that, on the H8/300 only, you may not use @samp{$} in -symbol names.) -@end ifset -@end ifclear -@end ifset -@ifset GENERIC -On most machines, you can also use @code{$} in symbol names; exceptions -are noted in @ref{Machine Dependencies}. -@end ifset -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 -@section Statements - -@cindex statements, structure of -@cindex line separator character -@cindex statement separator character -@ifclear GENERIC -@ifclear abnormal-separator -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 do not end statements. -@end ifclear -@ifset abnormal-separator -@ifset 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 do not end statements. -@end ifset -@ifset HPPA -A @dfn{statement} ends at a newline character (@samp{\n}) or an exclamation -point (@samp{!}). The newline or exclamation point is considered part of the -preceding statement. Newlines and exclamation points within character -constants are an exception: they do not end statements. -@end ifset -@ifset H8 -A @dfn{statement} ends at a newline character (@samp{\n}); or (for the -H8/300) a dollar sign (@samp{$}); or (for the -Renesas-SH or the -H8/500) a semicolon -(@samp{;}). The newline or separator character is considered part of -the preceding statement. Newlines and separators within character -constants are an exception: they do not end statements. -@end ifset -@end ifset -@end ifclear -@ifset 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{Machine Dependencies}.) The -newline or separator character is considered part of the preceding -statement. Newlines and separators within character constants are an -exception: they do not end statements. -@end ifset - -@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 - -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... doc@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 -assembles into a machine language instruction. -@ifset GENERIC -Different versions of @command{@value{AS}} for different computers -recognize different instructions. In fact, the same symbol may -represent a different instruction in a different computer's assembly -language.@refill -@end ifset - -@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}. - -@ifset HPPA -For HPPA targets, labels need not be immediately followed by a colon, but -the definition of a label must begin in column zero. This also implies that -only one label may be defined on each line. -@end ifset - -@smallexample -label: .directive followed by something -another_label: # This is an empty statement. - instruction operand_1, operand_2, @dots{} -@end smallexample - -@node Constants -@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 -@group -.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 group -@end smallexample - -@menu -* Characters:: Character Constants -* Numbers:: Number Constants -@end menu - -@node Characters -@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 -@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 -@command{@value{AS}} to interpret the second character literally as a backslash -(which prevents @command{@value{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 -@cindex @code{\b} (backspace character) -@cindex backspace (@code{\b}) -@item \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 -@cindex @code{\f} (formfeed character) -@cindex formfeed (@code{\f}) -@item \f -Mnemonic for FormFeed; for ASCII this is octal code 014. - -@cindex @code{\n} (newline character) -@cindex newline (@code{\n}) -@item \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 -@cindex @code{\r} (carriage return character) -@cindex carriage return (@code{\r}) -@item \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 -@cindex @code{\t} (tab) -@cindex tab (@code{\t}) -@item \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 -@cindex @code{\@var{ddd}} (octal character code) -@cindex octal character code (@code{\@var{ddd}}) -@item \ @var{digit} @var{digit} @var{digit} -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. - -@cindex @code{\@var{xd...}} (hex character code) -@cindex hex character code (@code{\@var{xd...}}) -@item \@code{x} @var{hex-digits...} -A hex character code. All trailing hex digits are combined. Either upper or -lower case @code{x} works. - -@cindex @code{\\} (@samp{\} character) -@cindex backslash (@code{\\}) -@item \\ -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 -@cindex @code{\"} (doublequote character) -@cindex doublequote (@code{\"}) -@item \" -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{\} gives a warning, but -assembles 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 @command{@value{AS}} has no -other interpretation, so @command{@value{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, do not use an escape -sequence. - -@node Chars -@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 -@ifclear GENERIC -@ifclear abnormal-separator -(or semicolon @samp{;}) -@end ifclear -@ifset abnormal-separator -@ifset A29K -(or at sign @samp{@@}) -@end ifset -@ifset H8 -(or dollar sign @samp{$}, for the H8/300; or semicolon @samp{;} for the -Renesas SH or H8/500) -@end ifset -@end ifset -@end ifclear -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. @command{@value{AS}} assumes your character code is ASCII: -@kbd{'A} means 65, @kbd{'B} means 66, and so on. @refill - -@node Numbers -@subsection Number Constants - -@cindex constants, number -@cindex number constants -@command{@value{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 -@ifclear GENERIC -@ifset I960 -* Bit Fields:: Bit Fields -@end ifset -@end ifclear -@end menu - -@node Integers -@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 -@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. - -@node Flonums -@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 -@command{@value{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 @command{@value{AS}} specialized to that computer. - -A flonum is written by writing (in order) -@itemize @bullet -@item -The digit @samp{0}. -@ifset HPPA -(@samp{0} is optional on the HPPA.) -@end ifset - -@item -A letter, to tell @command{@value{AS}} the rest of the number is a flonum. -@ifset 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 works here, but that might be changed. Vax BSD -4.2 assembler seems to allow any of @samp{defghDEFGH}.) -@end ignore - -On the H8/300, H8/500, -Renesas / SuperH SH, -and AMD 29K architectures, the letter must be -one of the letters @samp{DFPRSX} (in upper or lower case). - -On the ARC, the letter must be one of the letters @samp{DFRS} -(in upper or lower case). - -On the Intel 960 architecture, the letter must be -one of the letters @samp{DFT} (in upper or lower case). - -On the HPPA architecture, the letter must be @samp{E} (upper case only). -@end ifset -@ifclear GENERIC -@ifset A29K -One of the letters @samp{DFPRSX} (in upper or lower case). -@end ifset -@ifset ARC -One of the letters @samp{DFRS} (in upper or lower case). -@end ifset -@ifset H8 -One of the letters @samp{DFPRSX} (in upper or lower case). -@end ifset -@ifset HPPA -The letter @samp{E} (upper case only). -@end ifset -@ifset I960 -One of the letters @samp{DFT} (in upper or lower case). -@end ifset -@end ifclear - -@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. - -@command{@value{AS}} does all processing using integers. Flonums are computed -independently of any floating point hardware in the computer running -@command{@value{AS}}. - -@ifclear GENERIC -@ifset I960 -@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 -@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 -@command{@value{AS}} applies a bitwise @sc{and} between @var{mask} and -@var{value}. - -The resulting number is then packed -@ifset GENERIC -@c this conditional paren in case bit fields turned on elsewhere than 960 -(in host-dependent byte order) -@end ifset -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. -@end ifset -@end ifclear - -@node Sections -@chapter Sections and Relocation -@cindex sections -@cindex relocation - -@menu -* Secs Background:: Background -* Ld Sections:: Linker Sections -* As Sections:: Assembler Internal Sections -* Sub-Sections:: Sub-Sections -* bss:: bss Section -@end menu - -@node Secs Background -@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{@value{LD}} reads many object files (partial programs) and -combines their contents to form a runnable program. When @command{@value{AS}} -emits an object file, the partial program is assumed to start at address 0. -@code{@value{LD}} assigns the final addresses for the partial program, so that -different partial programs do not overlap. This is actually an -oversimplification, but it suffices to explain how @command{@value{AS}} uses -sections. - -@code{@value{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. -@ifset H8 -For the H8/300 and H8/500, -and for the Renesas / SuperH SH, -@command{@value{AS}} pads sections if needed to -ensure they end on a word (sixteen bit) boundary. -@end ifset - -@cindex standard assembler sections -An object file written by @command{@value{AS}} has at least three sections, any -of which may be empty. These are named @dfn{text}, @dfn{data} and -@dfn{bss} sections. - -@ifset COFF-ELF -@ifset GENERIC -When it generates COFF or ELF output, -@end ifset -@command{@value{AS}} can also generate whatever other named sections you specify -using the @samp{.section} directive (@pxref{Section,,@code{.section}}). -If you do not use any directives that place output in the @samp{.text} -or @samp{.data} sections, these sections still exist, but are empty. -@end ifset - -@ifset HPPA -@ifset GENERIC -When @command{@value{AS}} generates SOM or ELF output for the HPPA, -@end ifset -@command{@value{AS}} can also generate whatever other named sections you -specify using the @samp{.space} and @samp{.subspace} directives. See -@cite{HP9000 Series 800 Assembly Language Reference Manual} -(HP 92432-90001) for details on the @samp{.space} and @samp{.subspace} -assembler directives. - -@ifset SOM -Additionally, @command{@value{AS}} uses different names for the standard -text, data, and bss sections when generating SOM output. Program text -is placed into the @samp{$CODE$} section, data into @samp{$DATA$}, and -BSS into @samp{$BSS$}. -@end ifset -@end ifset - -Within the object file, the text section starts at address @code{0}, the -data section follows, and the bss section follows the data section. - -@ifset HPPA -When generating either SOM or ELF output files on the HPPA, the text -section starts at address @code{0}, the data section at address -@code{0x4000000}, and the bss section follows the data section. -@end ifset - -To let @code{@value{LD}} know which data changes when the sections are -relocated, and how to change that data, @command{@value{AS}} also writes to the -object file details of the relocation needed. To perform relocation -@code{@value{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 @command{@value{AS}} ever uses is expressed as -@display -(@var{section}) + (@var{offset into section}) -@end display -@noindent -Further, most expressions @command{@value{AS}} computes have this section-relative -nature. -@ifset SOM -(For some object formats, such as SOM for the HPPA, some expressions are -symbol-relative instead.) -@end ifset - -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{@value{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{@value{LD}}. Although the linker never arranges two partial programs' -data sections with overlapping addresses after linking, @emph{by definition} -their absolute sections must overlap. Address @code{@{absolute@ 239@}} in one -part of a program is always the same address when the program is running as -address @code{@{absolute@ 239@}} in any other part of the 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} is 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{@value{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 programs' text sections. Likewise for -data and bss sections. - -Some sections are manipulated by @code{@value{LD}}; others are invented for -use of @command{@value{AS}} and have no meaning except during assembly. - -@node Ld Sections -@section Linker Sections -@code{@value{LD}} deals with just four kinds of sections, summarized below. - -@table @strong - -@ifset COFF-ELF -@cindex named sections -@cindex sections, named -@item named sections -@end ifset -@ifset aout-bout -@cindex text section -@cindex data section -@itemx text section -@itemx data section -@end ifset -These sections hold your program. @command{@value{AS}} and @code{@value{LD}} treat them as -separate but equal sections. Anything you can say of one section is -true of another. -@c @ifset 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 contains -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. -@c @end ifset - -@cindex bss section -@item bss section -This section contains zeroed bytes when your program begins running. It -is used to hold uninitialized 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{@value{LD}} must -not change when relocating. In this sense we speak of absolute -addresses being ``unrelocatable'': they do not 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. -@ifset COFF-ELF -The example uses the traditional section names @samp{.text} and @samp{.data}. -@end ifset -Memory addresses are on the horizontal axis. - -@c TEXI2ROFF-KILL -@ifnottex -@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 ifnottex -@need 5000 -@tex -\bigskip -\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 -@section Assembler Internal Sections - -@cindex internal assembler sections -@cindex sections in messages, internal -These sections are meant only for the internal use of @command{@value{AS}}. They -have no meaning at run-time. You do not really need to know about these -sections for most purposes; but they can be mentioned in @command{@value{AS}} -warning messages, so it might be helpful to have an idea of their -meanings to @command{@value{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 -@cindex assembler internal logic error -@item ASSEMBLER-INTERNAL-LOGIC-ERROR! -An internal assembler logic error has been found. This means there is a -bug in the assembler. - -@cindex expr (internal section) -@item expr section -The assembler stores complex expression internally as combinations of -symbols. When it needs to represent an expression as a symbol, it puts -it in the expr section. -@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 -@section Sub-Sections - -@cindex numbered subsections -@cindex grouping data -@ifset aout-bout -Assembled bytes -@ifset COFF-ELF -conventionally -@end ifset -fall into two sections: text and data. -@end ifset -You may have separate groups of -@ifset GENERIC -data in named sections -@end ifset -@ifclear GENERIC -@ifclear aout-bout -data in named sections -@end ifclear -@ifset aout-bout -text or data -@end ifset -@end ifclear -that you want to end up near to each other in the object file, even though they -are not contiguous in the assembler source. @command{@value{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 go into the object file together with other objects in the same -subsection. 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 do not use subsections, everything -goes in subsection number zero. - -@ifset GENERIC -Each subsection is zero-padded up to a multiple of four bytes. -(Subsections may be padded a different amount on different flavors -of @command{@value{AS}}.) -@end ifset -@ifclear GENERIC -@ifset H8 -On the H8/300 and H8/500 platforms, each subsection is zero-padded to a word -boundary (two bytes). -The same is true on the Renesas SH. -@end ifset -@ifset 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). -@end ifset -@ifset A29K -On the AMD 29K family, no particular padding is added to section or -subsection sizes; @value{AS} forces no alignment on this platform. -@end ifset -@end ifclear - -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{@value{LD}} and -other programs that manipulate object files 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. -@ifset COFF-ELF -@ifset GENERIC -When generating COFF or ELF output, you -@end ifset -@ifclear GENERIC -You -@end ifclear -can also use an extra subsection -argument with arbitrary named sections: @samp{.section @var{name}, -@var{expression}}. -@end ifset -@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 @command{@value{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 changes it, and any label definition captures its -current value. The location counter of the section where statements are being -assembled is said to be the @dfn{active} location counter. - -@node bss -@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. - -The @code{.lcomm} pseudo-op defines a symbol in the bss section; see -@ref{Lcomm,,@code{.lcomm}}. - -The @code{.comm} pseudo-op may be used to declare a common symbol, which is -another form of uninitialized symbol; see @xref{Comm,,@code{.comm}}. - -@ifset GENERIC -When assembling for a target which supports multiple sections, such as ELF or -COFF, you may switch into the @code{.bss} section and define symbols as usual; -see @ref{Section,,@code{.section}}. You may only assemble zero values into the -section. Typically the section will only contain symbol definitions and -@code{.skip} directives (@pxref{Skip,,@code{.skip}}). -@end ifset - -@node Symbols -@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:} @command{@value{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 -@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. - -@ifset HPPA -On the HPPA, the usual form for a label need not be immediately followed by a -colon, but instead must start in column zero. Only one label may be defined on -a single line. To work around this, the HPPA version of @command{@value{AS}} also -provides a special directive @code{.label} for defining labels more flexibly. -@end ifset - -@node Setting 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 -@section Symbol Names - -@cindex symbol names -@cindex names, symbol -@ifclear SPECIAL-SYMS -Symbol names begin with a letter or with one of @samp{._}. On most -machines, you can also use @code{$} in symbol names; exceptions are -noted in @ref{Machine Dependencies}. That character may be followed by any -string of digits, letters, dollar signs (unless otherwise noted in -@ref{Machine Dependencies}), and underscores. -@end ifclear -@ifset A29K -For the AMD 29K family, @samp{?} is also allowed in the -body of a symbol name, though not at its beginning. -@end ifset - -@ifset SPECIAL-SYMS -@ifset H8 -Symbol names begin with a letter or with one of @samp{._}. On the -Renesas SH or the H8/500, you can also use @code{$} in symbol names. That -character may be followed by any string of digits, letters, dollar signs (save -on the H8/300), and underscores. -@end ifset -@end ifset - -Case of letters is significant: @code{foo} is a different symbol name -than @code{Foo}. - -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. -They create symbols which are guaranteed to be unique over the entire scope of -the input source code and which can be referred to by a simple notation. -To define a local symbol, write a label of the form @samp{@b{N}:} (where @b{N} -represents any positive integer). To refer to the most recent previous -definition of that symbol write @samp{@b{N}b}, using the same number as when -you defined the label. To refer to the next definition of a local label, write -@samp{@b{N}f}--- The @samp{b} stands for``backwards'' and the @samp{f} stands -for ``forwards''. - -There is no restriction on how you can use these labels, and you can reuse them -too. So that it is possible to repeatedly define the same local label (using -the same number @samp{@b{N}}), although you can only refer to the most recently -defined local label of that number (for a backwards reference) or the next -definition of a specific local label for a forward reference. It is also worth -noting that the first 10 local labels (@samp{@b{0:}}@dots{}@samp{@b{9:}}) are -implemented in a slightly more efficient manner than the others. - -Here is an example: - -@smallexample -1: branch 1f -2: branch 1b -1: branch 2f -2: branch 1b -@end smallexample - -Which is the equivalent of: - -@smallexample -label_1: branch label_3 -label_2: branch label_1 -label_3: branch label_4 -label_4: branch label_3 -@end smallexample - -Local symbol names are only a notational 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. The names are constructed using these -parts: - -@table @code -@item L -All local labels begin with @samp{L}. Normally both @command{@value{AS}} and -@code{@value{LD}} forget symbols that start with @samp{L}. These labels are -used for symbols you are never intended to see. If you use the -@samp{-L} option then @command{@value{AS}} retains these symbols in the -object file. If you also instruct @code{@value{LD}} to retain these symbols, -you may use them in debugging. - -@item @var{number} -This is the number that was used in the local label definition. So if the -label is written @samp{55:} then the number is @samp{55}. - -@item @kbd{C-B} -This unusual character is included so you do not accidentally invent a symbol -of the same name. The character has ASCII value of @samp{\002} (control-B). - -@item @emph{ordinal number} -This is a serial number to keep the labels distinct. The first definition of -@samp{0:} gets the number @samp{1}. The 15th definition of @samp{0:} gets the -number @samp{15}, and so on. Likewise the first definition of @samp{1:} gets -the number @samp{1} and its 15th defintion gets @samp{15} as well. -@end table - -So for example, the first @code{1:} is named @code{L1@kbd{C-B}1}, the 44th -@code{3:} is named @code{L3@kbd{C-B}44}. - -@subheading Dollar Local Labels -@cindex dollar local symbols - -@code{@value{AS}} also supports an even more local form of local labels called -dollar labels. These labels go out of scope (ie they become undefined) as soon -as a non-local label is defined. Thus they remain valid for only a small -region of the input source code. Normal local labels, by contrast, remain in -scope for the entire file, or until they are redefined by another occurrence of -the same local label. - -Dollar labels are defined in exactly the same way as ordinary local labels, -except that instead of being terminated by a colon, they are terminated by a -dollar sign. eg @samp{@b{55$}}. - -They can also be distinguished from ordinary local labels by their transformed -name which uses ASCII character @samp{\001} (control-A) as the magic character -to distinguish them from ordinary labels. Thus the 5th defintion of @samp{6$} -is named @samp{L6@kbd{C-A}5}. - -@node Dot -@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 -@command{@value{AS}} is assembling into. Thus, the expression @samp{melvin: -.long .} defines @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 -@ifclear no-space-dir -@samp{.space 4}. -@end ifclear -@ifset no-space-dir -@ifset A29K -@samp{.block 4}. -@end ifset -@end ifset - -@node Symbol Attributes -@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. -@ifset INTERNALS -The detailed definitions are in @file{a.out.h}. -@end ifset - -If you use a symbol without defining it, @command{@value{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 -@ifset aout-bout -@ifset GENERIC -* a.out Symbols:: Symbol Attributes: @code{a.out} -@end ifset -@ifclear GENERIC -@ifclear BOUT -* a.out Symbols:: Symbol Attributes: @code{a.out} -@end ifclear -@ifset BOUT -* a.out Symbols:: Symbol Attributes: @code{a.out}, @code{b.out} -@end ifset -@end ifclear -@end ifset -@ifset COFF -* COFF Symbols:: Symbol Attributes for COFF -@end ifset -@ifset SOM -* SOM Symbols:: Symbol Attributes for SOM -@end ifset -@end menu - -@node Symbol Value -@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{@value{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 file, and -@code{@value{LD}} tries to determine its value from other files linked into the -same program. 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. - -@node Symbol Type -@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. - -@ifset aout-bout -@ifclear GENERIC -@ifset BOUT -@c The following avoids a "widow" subsection title. @group would be -@c better if it were available outside examples. -@need 1000 -@node a.out Symbols -@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 @command{@value{AS}} is configured for -one of the Berkeley-descended object output formats---@code{a.out} or -@code{b.out}. - -@end ifset -@ifclear BOUT -@node a.out Symbols -@subsection Symbol Attributes: @code{a.out} - -@cindex @code{a.out} symbol attributes -@cindex symbol attributes, @code{a.out} - -@end ifclear -@end ifclear -@ifset GENERIC -@node a.out Symbols -@subsection Symbol Attributes: @code{a.out} - -@cindex @code{a.out} symbol attributes -@cindex symbol attributes, @code{a.out} - -@end ifset -@menu -* Symbol Desc:: Descriptor -* Symbol Other:: Other -@end menu - -@node Symbol Desc -@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 -@command{@value{AS}}. - -@node Symbol Other -@subsubsection Other - -@cindex other attribute, of @code{a.out} symbol -This is an arbitrary 8-bit value. It means nothing to @command{@value{AS}}. -@end ifset - -@ifset COFF -@node COFF Symbols -@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 @command{@value{AS}} directives @code{.dim}, @code{.line}, @code{.scl}, -@code{.size}, and @code{.tag} can generate auxiliary symbol table -information for COFF. -@end ifset - -@ifset SOM -@node SOM Symbols -@subsection Symbol Attributes for SOM - -@cindex SOM symbol attributes -@cindex symbol attributes, SOM - -The SOM format for the HPPA supports a multitude of symbol attributes set with -the @code{.EXPORT} and @code{.IMPORT} directives. - -The attributes are described in @cite{HP9000 Series 800 Assembly -Language Reference Manual} (HP 92432-90001) under the @code{IMPORT} and -@code{EXPORT} assembler directive documentation. -@end ifset - -@node Expressions -@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. - -The result of an expression must be an absolute number, or else an offset into -a particular section. If an expression is not absolute, and there is not -enough information when @command{@value{AS}} sees the expression to know its -section, a second pass over the source program might be necessary to interpret -the expression---but the second pass is currently not implemented. -@command{@value{AS}} aborts with an error message in this situation. - -@menu -* Empty Exprs:: Empty Expressions -* Integer Exprs:: Integer Expressions -@end menu - -@node Empty Exprs -@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 @command{@value{AS}} assumes a value of (absolute) 0. This -is compatible with other assemblers. - -@node Integer Exprs -@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 -@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 @command{@value{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 -@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 -@subsection Prefix Operator - -@cindex prefix operators -@command{@value{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 -@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 @option{-}, 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 < -@itemx << -@dfn{Shift Left}. Same as the C operator @samp{<<}. - -@item > -@itemx >> -@dfn{Shift Right}. Same as the C operator @samp{>>}. -@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 -Low Precedence - -@table @code -@cindex addition, permitted arguments -@cindex plus, permitted arguments -@cindex arguments for addition -@item + -@dfn{Addition}. If either argument is absolute, the result has the section of -the other argument. You may not add together arguments from different -sections. - -@cindex subtraction, permitted arguments -@cindex minus, permitted arguments -@cindex arguments for subtraction -@item - -@dfn{Subtraction}. If the right argument is absolute, the -result has the section of the left argument. -If both arguments are in the same section, the result is absolute. -You may not subtract arguments from different sections. -@c FIXME is there still something useful to say about undefined - undefined ? - -@cindex comparison expressions -@cindex expressions, comparison -@item == -@dfn{Is Equal To} -@item <> -@dfn{Is Not Equal To} -@item < -@dfn{Is Less Than} -@itemx > -@dfn{Is Greater Than} -@itemx >= -@dfn{Is Greater Than Or Equal To} -@itemx <= -@dfn{Is Less Than Or Equal To} - -The comparison operators can be used as infix operators. A true results has a -value of -1 whereas a false result has a value of 0. Note, these operators -perform signed comparisons. -@end table - -@item Lowest Precedence - -@table @code -@item && -@dfn{Logical And}. - -@item || -@dfn{Logical Or}. - -These two logical operations can be used to combine the results of sub -expressions. Note, unlike the comparison operators a true result returns a -value of 1 but a false results does still return 0. Also note that the logical -or operator has a slightly lower precedence than logical and. - -@end table -@end enumerate - -In short, it's only meaningful to add or subtract the @emph{offsets} in an -address; you can only have a defined section in one of the two arguments. - -@node Pseudo Ops -@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 that are available regardless of the -target machine configuration for the @sc{gnu} assembler. -@ifset GENERIC -Some machine configurations provide additional directives. -@xref{Machine Dependencies}. -@end ifset -@ifclear GENERIC -@ifset machine-directives -@xref{Machine Dependencies} for additional directives. -@end ifset -@end ifclear - -@menu -* Abort:: @code{.abort} -@ifset COFF -* ABORT:: @code{.ABORT} -@end ifset - -* Align:: @code{.align @var{abs-expr} , @var{abs-expr}} -* Ascii:: @code{.ascii "@var{string}"}@dots{} -* Asciz:: @code{.asciz "@var{string}"}@dots{} -* Balign:: @code{.balign @var{abs-expr} , @var{abs-expr}} -* Byte:: @code{.byte @var{expressions}} -* Comm:: @code{.comm @var{symbol} , @var{length} } - -* CFI directives:: @code{.cfi_startproc}, @code{.cfi_endproc}, etc. - -* Data:: @code{.data @var{subsection}} -@ifset COFF -* Def:: @code{.def @var{name}} -@end ifset -@ifset aout-bout -* Desc:: @code{.desc @var{symbol}, @var{abs-expression}} -@end ifset -@ifset COFF -* Dim:: @code{.dim} -@end ifset - -* Double:: @code{.double @var{flonums}} -* Eject:: @code{.eject} -* Else:: @code{.else} -* Elseif:: @code{.elseif} -* End:: @code{.end} -@ifset COFF -* Endef:: @code{.endef} -@end ifset - -* Endfunc:: @code{.endfunc} -* Endif:: @code{.endif} -* Equ:: @code{.equ @var{symbol}, @var{expression}} -* Equiv:: @code{.equiv @var{symbol}, @var{expression}} -* Err:: @code{.err} -* Exitm:: @code{.exitm} -* Extern:: @code{.extern} -* Fail:: @code{.fail} -@ifclear no-file-dir -* File:: @code{.file @var{string}} -@end ifclear - -* Fill:: @code{.fill @var{repeat} , @var{size} , @var{value}} -* Float:: @code{.float @var{flonums}} -* Func:: @code{.func} -* Global:: @code{.global @var{symbol}}, @code{.globl @var{symbol}} -@ifset ELF -* Hidden:: @code{.hidden @var{names}} -@end ifset - -* hword:: @code{.hword @var{expressions}} -* Ident:: @code{.ident} -* If:: @code{.if @var{absolute expression}} -* Incbin:: @code{.incbin "@var{file}"[,@var{skip}[,@var{count}]]} -* Include:: @code{.include "@var{file}"} -* Int:: @code{.int @var{expressions}} -@ifset ELF -* Internal:: @code{.internal @var{names}} -@end ifset - -* Irp:: @code{.irp @var{symbol},@var{values}}@dots{} -* Irpc:: @code{.irpc @var{symbol},@var{values}}@dots{} -* Lcomm:: @code{.lcomm @var{symbol} , @var{length}} -* Lflags:: @code{.lflags} -@ifclear no-line-dir -* Line:: @code{.line @var{line-number}} -@end ifclear - -* Ln:: @code{.ln @var{line-number}} -* Linkonce:: @code{.linkonce [@var{type}]} -* List:: @code{.list} -* Long:: @code{.long @var{expressions}} -@ignore -* Lsym:: @code{.lsym @var{symbol}, @var{expression}} -@end ignore - -* Macro:: @code{.macro @var{name} @var{args}}@dots{} -* MRI:: @code{.mri @var{val}} -* Nolist:: @code{.nolist} -* Octa:: @code{.octa @var{bignums}} -* Org:: @code{.org @var{new-lc} , @var{fill}} -* P2align:: @code{.p2align @var{abs-expr} , @var{abs-expr}} -@ifset ELF -* PopSection:: @code{.popsection} -* Previous:: @code{.previous} -@end ifset - -* Print:: @code{.print @var{string}} -@ifset ELF -* Protected:: @code{.protected @var{names}} -@end ifset - -* Psize:: @code{.psize @var{lines}, @var{columns}} -* Purgem:: @code{.purgem @var{name}} -@ifset ELF -* PushSection:: @code{.pushsection @var{name}} -@end ifset - -* Quad:: @code{.quad @var{bignums}} -* Rept:: @code{.rept @var{count}} -* Sbttl:: @code{.sbttl "@var{subheading}"} -@ifset COFF -* Scl:: @code{.scl @var{class}} -@end ifset -@ifset COFF-ELF -* Section:: @code{.section @var{name}} -@end ifset - -* Set:: @code{.set @var{symbol}, @var{expression}} -* Short:: @code{.short @var{expressions}} -* Single:: @code{.single @var{flonums}} -@ifset COFF-ELF -* Size:: @code{.size [@var{name} , @var{expression}]} -@end ifset - -* Skip:: @code{.skip @var{size} , @var{fill}} -* Sleb128:: @code{.sleb128 @var{expressions}} -* Space:: @code{.space @var{size} , @var{fill}} -@ifset have-stabs -* Stab:: @code{.stabd, .stabn, .stabs} -@end ifset - -* String:: @code{.string "@var{str}"} -* Struct:: @code{.struct @var{expression}} -@ifset ELF -* SubSection:: @code{.subsection} -* Symver:: @code{.symver @var{name},@var{name2@@nodename}} -@end ifset - -@ifset COFF -* Tag:: @code{.tag @var{structname}} -@end ifset - -* Text:: @code{.text @var{subsection}} -* Title:: @code{.title "@var{heading}"} -@ifset COFF-ELF -* Type:: @code{.type <@var{int} | @var{name} , @var{type description}>} -@end ifset - -* Uleb128:: @code{.uleb128 @var{expressions}} -@ifset COFF -* Val:: @code{.val @var{addr}} -@end ifset - -@ifset ELF -* Version:: @code{.version "@var{string}"} -* VTableEntry:: @code{.vtable_entry @var{table}, @var{offset}} -* VTableInherit:: @code{.vtable_inherit @var{child}, @var{parent}} -* Weak:: @code{.weak @var{names}} -@end ifset - -* Word:: @code{.word @var{expressions}} -* Deprecated:: Deprecated Directives -@end menu - -@node Abort -@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 @command{@value{AS}} to -quit also. One day @code{.abort} will not be supported. - -@ifset COFF -@node ABORT -@section @code{.ABORT} - -@cindex @code{ABORT} directive -When producing COFF output, @command{@value{AS}} accepts this directive as a -synonym for @samp{.abort}. - -@ifset BOUT -When producing @code{b.out} output, @command{@value{AS}} accepts this directive, -but ignores it. -@end ifset -@end ifset - -@node Align -@section @code{.align @var{abs-expr}, @var{abs-expr}, @var{abs-expr}} - -@cindex padding the location counter -@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 alignment -required, as described below. - -The second expression (also absolute) gives the fill value to be stored in the -padding bytes. It (and the comma) may be omitted. If it is omitted, the -padding bytes are normally zero. However, on some systems, if the section is -marked as containing code and the fill value is omitted, the space is filled -with no-op instructions. - -The third expression is also absolute, and is also optional. If it is present, -it is the maximum number of bytes that should be skipped by this alignment -directive. If doing the alignment would require skipping more bytes than the -specified maximum, then the alignment is not done at all. You can omit the -fill value (the second argument) entirely by simply using two commas after the -required alignment; this can be useful if you want the alignment to be filled -with no-op instructions when appropriate. - -The way the required alignment is specified varies from system to system. -For the a29k, arc, hppa, i386 using ELF, i860, iq2000, m68k, m88k, or32, -s390, sparc, tic4x, tic80 and xtensa, the first expression is the -alignment request in bytes. For example @samp{.align 8} advances -the location counter until it is a multiple of 8. If the location counter -is already a multiple of 8, no change is needed. For the tic54x, the -first expression is the alignment request in words. - -For other systems, including the i386 using a.out format, and the arm and -strongarm, it is the -number of low-order zero bits the location counter must have after -advancement. For example @samp{.align 3} advances the location -counter until it a multiple of 8. If the location counter is already a -multiple of 8, no change is needed. - -This inconsistency is due to the different behaviors of the various -native assemblers for these systems which GAS must emulate. -GAS also provides @code{.balign} and @code{.p2align} directives, -described later, which have a consistent behavior across all -architectures (but are specific to GAS). - -@node Ascii -@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 -@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 Balign -@section @code{.balign[wl] @var{abs-expr}, @var{abs-expr}, @var{abs-expr}} - -@cindex padding the location counter given number of bytes -@cindex @code{balign} directive -Pad the location counter (in the current subsection) to a particular -storage boundary. The first expression (which must be absolute) is the -alignment request in bytes. For example @samp{.balign 8} advances -the location counter until it is 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 fill value to be stored in the -padding bytes. It (and the comma) may be omitted. If it is omitted, the -padding bytes are normally zero. However, on some systems, if the section is -marked as containing code and the fill value is omitted, the space is filled -with no-op instructions. - -The third expression is also absolute, and is also optional. If it is present, -it is the maximum number of bytes that should be skipped by this alignment -directive. If doing the alignment would require skipping more bytes than the -specified maximum, then the alignment is not done at all. You can omit the -fill value (the second argument) entirely by simply using two commas after the -required alignment; this can be useful if you want the alignment to be filled -with no-op instructions when appropriate. - -@cindex @code{balignw} directive -@cindex @code{balignl} directive -The @code{.balignw} and @code{.balignl} directives are variants of the -@code{.balign} directive. The @code{.balignw} directive treats the fill -pattern as a two byte word value. The @code{.balignl} directives treats the -fill pattern as a four byte longword value. For example, @code{.balignw -4,0x368d} will align to a multiple of 4. If it skips two bytes, they will be -filled in with the value 0x368d (the exact placement of the bytes depends upon -the endianness of the processor). If it skips 1 or 3 bytes, the fill value is -undefined. - -@node Byte -@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 -@section @code{.comm @var{symbol} , @var{length} } - -@cindex @code{comm} directive -@cindex symbol, common -@code{.comm} declares a common symbol named @var{symbol}. When linking, a -common symbol in one object file may be merged with a defined or common symbol -of the same name in another object file. If @code{@value{LD}} does not see a -definition for the symbol--just one or more common symbols--then it will -allocate @var{length} bytes of uninitialized memory. @var{length} must be an -absolute expression. If @code{@value{LD}} sees multiple common symbols with -the same name, and they do not all have the same size, it will allocate space -using the largest size. - -@ifset ELF -When using ELF, the @code{.comm} directive takes an optional third argument. -This is the desired alignment of the symbol, specified as a byte boundary (for -example, an alignment of 16 means that the least significant 4 bits of the -address should be zero). The alignment must be an absolute expression, and it -must be a power of two. If @code{@value{LD}} allocates uninitialized memory -for the common symbol, it will use the alignment when placing the symbol. If -no alignment is specified, @command{@value{AS}} will set the alignment to the -largest power of two less than or equal to the size of the symbol, up to a -maximum of 16. -@end ifset - -@ifset HPPA -The syntax for @code{.comm} differs slightly on the HPPA. The syntax is -@samp{@var{symbol} .comm, @var{length}}; @var{symbol} is optional. -@end ifset - -@node CFI directives -@section @code{.cfi_startproc} -@cindex @code{cfi_startproc} directive -@code{.cfi_startproc} is used at the beginning of each function that -should have an entry in @code{.eh_frame}. It initializes some internal -data structures and emits architecture dependent initial CFI instructions. -Don't forget to close the function by -@code{.cfi_endproc}. - -@section @code{.cfi_endproc} -@cindex @code{cfi_endproc} directive -@code{.cfi_endproc} is used at the end of a function where it closes its -unwind entry previously opened by -@code{.cfi_startproc}. and emits it to @code{.eh_frame}. - -@section @code{.cfi_def_cfa @var{register}, @var{offset}} -@code{.cfi_def_cfa} defines a rule for computing CFA as: @i{take -address from @var{register} and add @var{offset} to it}. - -@section @code{.cfi_def_cfa_register @var{register}} -@code{.cfi_def_cfa_register} modifies a rule for computing CFA. From -now on @var{register} will be used instead of the old one. Offset -remains the same. - -@section @code{.cfi_def_cfa_offset @var{offset}} -@code{.cfi_def_cfa_offset} modifies a rule for computing CFA. Register -remains the same, but @var{offset} is new. Note that it is the -absolute offset that will be added to a defined register to compute -CFA address. - -@section @code{.cfi_adjust_cfa_offset @var{offset}} -Same as @code{.cfi_def_cfa_offset} but @var{offset} is a relative -value that is added/substracted from the previous offset. - -@section @code{.cfi_offset @var{register}, @var{offset}} -Previous value of @var{register} is saved at offset @var{offset} from -CFA. - -@section @code{.cfi_rel_offset @var{register}, @var{offset}} -Previous value of @var{register} is saved at offset @var{offset} from -the current CFA register. This is transformed to @code{.cfi_offset} -using the known displacement of the CFA register from the CFA. -This is often easier to use, because the number will match the -code it's annotating. - -@section @code{.cfi_window_save} -SPARC register window has been saved. - -@section @code{.cfi_escape} @var{expression}[, @dots{}] -Allows the user to add arbitrary bytes to the unwind info. One -might use this to add OS-specific CFI opcodes, or generic CFI -opcodes that GAS does not yet support. - -@node Data -@section @code{.data @var{subsection}} - -@cindex @code{data} directive -@code{.data} tells @command{@value{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. - -@ifset COFF -@node Def -@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. -@ifset BOUT - -This directive is only observed when @command{@value{AS}} is configured for COFF -format output; when producing @code{b.out}, @samp{.def} is recognized, -but ignored. -@end ifset -@end ifset - -@ifset aout-bout -@node Desc -@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. - -@ifset COFF -The @samp{.desc} directive is not available when @command{@value{AS}} is -configured for COFF output; it is only for @code{a.out} or @code{b.out} -object format. For the sake of compatibility, @command{@value{AS}} accepts -it, but produces no output, when configured for COFF. -@end ifset -@end ifset - -@ifset COFF -@node Dim -@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. -@ifset BOUT - -@samp{.dim} is only meaningful when generating COFF format output; when -@command{@value{AS}} is generating @code{b.out}, it accepts this directive but -ignores it. -@end ifset -@end ifset - -@node Double -@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. -@ifset GENERIC -The exact kind of floating point numbers emitted depends on how -@command{@value{AS}} is configured. @xref{Machine Dependencies}. -@end ifset -@ifclear GENERIC -@ifset IEEEFLOAT -On the @value{TARGET} family @samp{.double} emits 64-bit floating-point numbers -in @sc{ieee} format. -@end ifset -@end ifclear - -@node Eject -@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. - -@node Else -@section @code{.else} - -@cindex @code{else} directive -@code{.else} is part of the @command{@value{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. - -@node Elseif -@section @code{.elseif} - -@cindex @code{elseif} directive -@code{.elseif} is part of the @command{@value{AS}} support for conditional -assembly; @pxref{If,,@code{.if}}. It is shorthand for beginning a new -@code{.if} block that would otherwise fill the entire @code{.else} section. - -@node End -@section @code{.end} - -@cindex @code{end} directive -@code{.end} marks the end of the assembly file. @command{@value{AS}} does not -process anything in the file past the @code{.end} directive. - -@ifset COFF -@node Endef -@section @code{.endef} - -@cindex @code{endef} directive -This directive flags the end of a symbol definition begun with -@code{.def}. -@ifset BOUT - -@samp{.endef} is only meaningful when generating COFF format output; if -@command{@value{AS}} is configured to generate @code{b.out}, it accepts this -directive but ignores it. -@end ifset -@end ifset - -@node Endfunc -@section @code{.endfunc} -@cindex @code{endfunc} directive -@code{.endfunc} marks the end of a function specified with @code{.func}. - -@node Endif -@section @code{.endif} - -@cindex @code{endif} directive -@code{.endif} is part of the @command{@value{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 -@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}}. - -@ifset HPPA -The syntax for @code{equ} on the HPPA is -@samp{@var{symbol} .equ @var{expression}}. -@end ifset - -@node Equiv -@section @code{.equiv @var{symbol}, @var{expression}} -@cindex @code{equiv} directive -The @code{.equiv} directive is like @code{.equ} and @code{.set}, except that -the assembler will signal an error if @var{symbol} is already defined. Note a -symbol which has been referenced but not actually defined is considered to be -undefined. - -Except for the contents of the error message, this is roughly equivalent to -@smallexample -.ifdef SYM -.err -.endif -.equ SYM,VAL -@end smallexample - -@node Err -@section @code{.err} -@cindex @code{err} directive -If @command{@value{AS}} assembles a @code{.err} directive, it will print an error -message and, unless the @option{-Z} option was used, it will not generate an -object file. This can be used to signal error an conditionally compiled code. - -@node Exitm -@section @code{.exitm} -Exit early from the current macro definition. @xref{Macro}. - -@node Extern -@section @code{.extern} - -@cindex @code{extern} directive -@code{.extern} is accepted in the source program---for compatibility -with other assemblers---but it is ignored. @command{@value{AS}} treats -all undefined symbols as external. - -@node Fail -@section @code{.fail @var{expression}} - -@cindex @code{fail} directive -Generates an error or a warning. If the value of the @var{expression} is 500 -or more, @command{@value{AS}} will print a warning message. If the value is less -than 500, @command{@value{AS}} will print an error message. The message will -include the value of @var{expression}. This can occasionally be useful inside -complex nested macros or conditional assembly. - -@ifclear no-file-dir -@node File -@section @code{.file @var{string}} - -@cindex @code{file} directive -@cindex logical file name -@cindex file name, logical -@code{.file} tells @command{@value{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 @command{@value{AS}} programs. -@ifset A29K -In some configurations of @command{@value{AS}}, @code{.file} has already been -removed to avoid conflicts with other assemblers. @xref{Machine Dependencies}. -@end ifset -@end ifclear - -@node Fill -@section @code{.fill @var{repeat} , @var{size} , @var{value}} - -@cindex @code{fill} directive -@cindex writing patterns in memory -@cindex patterns, writing in memory -@var{repeat}, @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 @command{@value{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 -@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}. -@ifset GENERIC -The exact kind of floating point numbers emitted depends on how -@command{@value{AS}} is configured. -@xref{Machine Dependencies}. -@end ifset -@ifclear GENERIC -@ifset IEEEFLOAT -On the @value{TARGET} family, @code{.float} emits 32-bit floating point numbers -in @sc{ieee} format. -@end ifset -@end ifclear - -@node Func -@section @code{.func @var{name}[,@var{label}]} -@cindex @code{func} directive -@code{.func} emits debugging information to denote function @var{name}, and -is ignored unless the file is assembled with debugging enabled. -Only @samp{--gstabs[+]} is currently supported. -@var{label} is the entry point of the function and if omitted @var{name} -prepended with the @samp{leading char} is used. -@samp{leading char} is usually @code{_} or nothing, depending on the target. -All functions are currently defined to have @code{void} return type. -The function must be terminated with @code{.endfunc}. - -@node Global -@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{@value{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} takes its attributes from a symbol of the same name -from another file linked into the same program. - -Both spellings (@samp{.globl} and @samp{.global}) are accepted, for -compatibility with other assemblers. - -@ifset HPPA -On the HPPA, @code{.global} is not always enough to make it accessible to other -partial programs. You may need the HPPA-only @code{.EXPORT} directive as well. -@xref{HPPA Directives,, HPPA Assembler Directives}. -@end ifset - -@ifset ELF -@node Hidden -@section @code{.hidden @var{names}} - -@cindex @code{hidden} directive -@cindex visibility -This one of the ELF visibility directives. The other two are -@code{.internal} (@pxref{Internal,,@code{.internal}}) and -@code{.protected} (@pxref{Protected,,@code{.protected}}). - -This directive overrides the named symbols default visibility (which is set by -their binding: local, global or weak). The directive sets the visibility to -@code{hidden} which means that the symbols are not visible to other components. -Such symbols are always considered to be @code{protected} as well. -@end ifset - -@node hword -@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. - -@ifset GENERIC -This directive is a synonym for @samp{.short}; depending on the target -architecture, it may also be a synonym for @samp{.word}. -@end ifset -@ifclear GENERIC -@ifset W32 -This directive is a synonym for @samp{.short}. -@end ifset -@ifset W16 -This directive is a synonym for both @samp{.short} and @samp{.word}. -@end ifset -@end ifclear - -@node Ident -@section @code{.ident} - -@cindex @code{ident} directive -This directive is used by some assemblers to place tags in object files. -@command{@value{AS}} simply accepts the directive for source-file -compatibility with such assemblers, but does not actually emit anything -for it. - -@node If -@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}}). -If you have several conditions to check, @code{.elseif} may be used to avoid -nesting blocks if/else within each subsequent @code{.else} block. - -The following variants of @code{.if} are also supported: -@table @code -@cindex @code{ifdef} directive -@item .ifdef @var{symbol} -Assembles the following section of code if the specified @var{symbol} -has been defined. Note a symbol which has been referenced but not yet defined -is considered to be undefined. - -@cindex @code{ifc} directive -@item .ifc @var{string1},@var{string2} -Assembles the following section of code if the two strings are the same. The -strings may be optionally quoted with single quotes. If they are not quoted, -the first string stops at the first comma, and the second string stops at the -end of the line. Strings which contain whitespace should be quoted. The -string comparison is case sensitive. - -@cindex @code{ifeq} directive -@item .ifeq @var{absolute expression} -Assembles the following section of code if the argument is zero. - -@cindex @code{ifeqs} directive -@item .ifeqs @var{string1},@var{string2} -Another form of @code{.ifc}. The strings must be quoted using double quotes. - -@cindex @code{ifge} directive -@item .ifge @var{absolute expression} -Assembles the following section of code if the argument is greater than or -equal to zero. - -@cindex @code{ifgt} directive -@item .ifgt @var{absolute expression} -Assembles the following section of code if the argument is greater than zero. - -@cindex @code{ifle} directive -@item .ifle @var{absolute expression} -Assembles the following section of code if the argument is less than or equal -to zero. - -@cindex @code{iflt} directive -@item .iflt @var{absolute expression} -Assembles the following section of code if the argument is less than zero. - -@cindex @code{ifnc} directive -@item .ifnc @var{string1},@var{string2}. -Like @code{.ifc}, but the sense of the test is reversed: this assembles the -following section of code if the two strings are not the same. - -@cindex @code{ifndef} directive -@cindex @code{ifnotdef} directive -@item .ifndef @var{symbol} -@itemx .ifnotdef @var{symbol} -Assembles the following section of code if the specified @var{symbol} -has not been defined. Both spelling variants are equivalent. Note a symbol -which has been referenced but not yet defined is considered to be undefined. - -@cindex @code{ifne} directive -@item .ifne @var{absolute expression} -Assembles the following section of code if the argument is not equal to zero -(in other words, this is equivalent to @code{.if}). - -@cindex @code{ifnes} directive -@item .ifnes @var{string1},@var{string2} -Like @code{.ifeqs}, but the sense of the test is reversed: this assembles the -following section of code if the two strings are not the same. -@end table - -@node Incbin -@section @code{.incbin "@var{file}"[,@var{skip}[,@var{count}]]} - -@cindex @code{incbin} directive -@cindex binary files, including -The @code{incbin} directive includes @var{file} verbatim at the current -location. 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}. - -The @var{skip} argument skips a number of bytes from the start of the -@var{file}. The @var{count} argument indicates the maximum number of bytes to -read. Note that the data is not aligned in any way, so it is the user's -responsibility to make sure that proper alignment is provided both before and -after the @code{incbin} directive. - -@node Include -@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 -@section @code{.int @var{expressions}} - -@cindex @code{int} directive -@cindex integers, 32-bit -Expect zero or more @var{expressions}, of any section, separated by commas. -For each expression, emit a number that, at run time, is the value of that -expression. The byte order and bit size of the number depends on what kind -of target the assembly is for. - -@ifclear GENERIC -@ifset H8 -On the H8/500 and most forms of the H8/300, @code{.int} emits 16-bit -integers. On the H8/300H and the Renesas SH, however, @code{.int} emits -32-bit integers. -@end ifset -@end ifclear - -@ifset ELF -@node Internal -@section @code{.internal @var{names}} - -@cindex @code{internal} directive -@cindex visibility -This one of the ELF visibility directives. The other two are -@code{.hidden} (@pxref{Hidden,,@code{.hidden}}) and -@code{.protected} (@pxref{Protected,,@code{.protected}}). - -This directive overrides the named symbols default visibility (which is set by -their binding: local, global or weak). The directive sets the visibility to -@code{internal} which means that the symbols are considered to be @code{hidden} -(i.e., not visible to other components), and that some extra, processor specific -processing must also be performed upon the symbols as well. -@end ifset - -@node Irp -@section @code{.irp @var{symbol},@var{values}}@dots{} - -@cindex @code{irp} directive -Evaluate a sequence of statements assigning different values to @var{symbol}. -The sequence of statements starts at the @code{.irp} directive, and is -terminated by an @code{.endr} directive. For each @var{value}, @var{symbol} is -set to @var{value}, and the sequence of statements is assembled. If no -@var{value} is listed, the sequence of statements is assembled once, with -@var{symbol} set to the null string. To refer to @var{symbol} within the -sequence of statements, use @var{\symbol}. - -For example, assembling - -@example - .irp param,1,2,3 - move d\param,sp@@- - .endr -@end example - -is equivalent to assembling - -@example - move d1,sp@@- - move d2,sp@@- - move d3,sp@@- -@end example - -@node Irpc -@section @code{.irpc @var{symbol},@var{values}}@dots{} - -@cindex @code{irpc} directive -Evaluate a sequence of statements assigning different values to @var{symbol}. -The sequence of statements starts at the @code{.irpc} directive, and is -terminated by an @code{.endr} directive. For each character in @var{value}, -@var{symbol} is set to the character, and the sequence of statements is -assembled. If no @var{value} is listed, the sequence of statements is -assembled once, with @var{symbol} set to the null string. To refer to -@var{symbol} within the sequence of statements, use @var{\symbol}. - -For example, assembling - -@example - .irpc param,123 - move d\param,sp@@- - .endr -@end example - -is equivalent to assembling - -@example - move d1,sp@@- - move d2,sp@@- - move d3,sp@@- -@end example - -@node Lcomm -@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 that at run-time the bytes start off zeroed. @var{Symbol} -is not declared global (@pxref{Global,,@code{.global}}), so is normally -not visible to @code{@value{LD}}. - -@ifset GENERIC -Some targets permit a third argument to be used with @code{.lcomm}. This -argument specifies the desired alignment of the symbol in the bss section. -@end ifset - -@ifset HPPA -The syntax for @code{.lcomm} differs slightly on the HPPA. The syntax is -@samp{@var{symbol} .lcomm, @var{length}}; @var{symbol} is optional. -@end ifset - -@node Lflags -@section @code{.lflags} - -@cindex @code{lflags} directive (ignored) -@command{@value{AS}} accepts this directive, for compatibility with other -assemblers, but ignores it. - -@ifclear no-line-dir -@node Line -@section @code{.line @var{line-number}} - -@cindex @code{line} directive -@end ifclear -@ifset no-line-dir -@node Ln -@section @code{.ln @var{line-number}} - -@cindex @code{ln} directive -@end ifset -@cindex logical line number -@ifset aout-bout -Change the logical line number. @var{line-number} must be an absolute -expression. The next line has that logical line number. Therefore any other -statements on the current line (after a statement separator character) are -reported as on logical line number @var{line-number} @minus{} 1. One day -@command{@value{AS}} will no longer support this directive: it is recognized only -for compatibility with existing assembler programs. - -@ifset GENERIC -@ifset A29K -@emph{Warning:} In the AMD29K configuration of @value{AS}, this command is -not available; use the synonym @code{.ln} in that context. -@end ifset -@end ifset -@end ifset - -@ifclear no-line-dir -Even though this is a directive associated with the @code{a.out} or -@code{b.out} object-code formats, @command{@value{AS}} still recognizes it -when producing COFF output, and treats @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. -@end ifclear - -@node Linkonce -@section @code{.linkonce [@var{type}]} -@cindex COMDAT -@cindex @code{linkonce} directive -@cindex common sections -Mark the current section so that the linker only includes a single copy of it. -This may be used to include the same section in several different object files, -but ensure that the linker will only include it once in the final output file. -The @code{.linkonce} pseudo-op must be used for each instance of the section. -Duplicate sections are detected based on the section name, so it should be -unique. - -This directive is only supported by a few object file formats; as of this -writing, the only object file format which supports it is the Portable -Executable format used on Windows NT. - -The @var{type} argument is optional. If specified, it must be one of the -following strings. For example: -@smallexample -.linkonce same_size -@end smallexample -Not all types may be supported on all object file formats. - -@table @code -@item discard -Silently discard duplicate sections. This is the default. - -@item one_only -Warn if there are duplicate sections, but still keep only one copy. - -@item same_size -Warn if any of the duplicates have different sizes. - -@item same_contents -Warn if any of the duplicates do not have exactly the same contents. -@end table - -@node Ln -@section @code{.ln @var{line-number}} - -@cindex @code{ln} directive -@ifclear no-line-dir -@samp{.ln} is a synonym for @samp{.line}. -@end ifclear -@ifset no-line-dir -Tell @command{@value{AS}} to change the logical line number. @var{line-number} -must be an absolute expression. The next line has that logical -line number, so any other statements on the current line (after a -statement separator character @code{;}) are reported as on logical -line number @var{line-number} @minus{} 1. -@ifset BOUT - -This directive is accepted, but ignored, when @command{@value{AS}} is -configured for @code{b.out}; its effect is only associated with COFF -output format. -@end ifset -@end ifset - -@node MRI -@section @code{.mri @var{val}} - -@cindex @code{mri} directive -@cindex MRI mode, temporarily -If @var{val} is non-zero, this tells @command{@value{AS}} to enter MRI mode. If -@var{val} is zero, this tells @command{@value{AS}} to exit MRI mode. This change -affects code assembled until the next @code{.mri} directive, or until the end -of the file. @xref{M, MRI mode, MRI mode}. - -@node List -@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 -@section @code{.long @var{expressions}} - -@cindex @code{long} directive -@code{.long} is the same as @samp{.int}, @pxref{Int,,@code{.int}}. - -@ignore -@c no one seems to know what this is for or whether this description is -@c what it really ought to do -@node Lsym -@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. -@end ignore - -@node Macro -@section @code{.macro} - -@cindex macros -The commands @code{.macro} and @code{.endm} allow you to define macros that -generate assembly output. For example, this definition specifies a macro -@code{sum} that puts a sequence of numbers into memory: - -@example - .macro sum from=0, to=5 - .long \from - .if \to-\from - sum "(\from+1)",\to - .endif - .endm -@end example - -@noindent -With that definition, @samp{SUM 0,5} is equivalent to this assembly input: - -@example - .long 0 - .long 1 - .long 2 - .long 3 - .long 4 - .long 5 -@end example - -@ftable @code -@item .macro @var{macname} -@itemx .macro @var{macname} @var{macargs} @dots{} -@cindex @code{macro} directive -Begin the definition of a macro called @var{macname}. If your macro -definition requires arguments, specify their names after the macro name, -separated by commas or spaces. You can supply a default value for any -macro argument by following the name with @samp{=@var{deflt}}. For -example, these are all valid @code{.macro} statements: - -@table @code -@item .macro comm -Begin the definition of a macro called @code{comm}, which takes no -arguments. - -@item .macro plus1 p, p1 -@itemx .macro plus1 p p1 -Either statement begins the definition of a macro called @code{plus1}, -which takes two arguments; within the macro definition, write -@samp{\p} or @samp{\p1} to evaluate the arguments. - -@item .macro reserve_str p1=0 p2 -Begin the definition of a macro called @code{reserve_str}, with two -arguments. The first argument has a default value, but not the second. -After the definition is complete, you can call the macro either as -@samp{reserve_str @var{a},@var{b}} (with @samp{\p1} evaluating to -@var{a} and @samp{\p2} evaluating to @var{b}), or as @samp{reserve_str -,@var{b}} (with @samp{\p1} evaluating as the default, in this case -@samp{0}, and @samp{\p2} evaluating to @var{b}). -@end table - -When you call a macro, you can specify the argument values either by -position, or by keyword. For example, @samp{sum 9,17} is equivalent to -@samp{sum to=17, from=9}. - -@item .endm -@cindex @code{endm} directive -Mark the end of a macro definition. - -@item .exitm -@cindex @code{exitm} directive -Exit early from the current macro definition. - -@cindex number of macros executed -@cindex macros, count executed -@item \@@ -@command{@value{AS}} maintains a counter of how many macros it has -executed in this pseudo-variable; you can copy that number to your -output with @samp{\@@}, but @emph{only within a macro definition}. - -@ignore -@item LOCAL @var{name} [ , @dots{} ] -@emph{Warning: @code{LOCAL} is only available if you select ``alternate -macro syntax'' with @samp{-a} or @samp{--alternate}.} @xref{Alternate,, -Alternate macro syntax}. - -Generate a string replacement for each of the @var{name} arguments, and -replace any instances of @var{name} in each macro expansion. The -replacement string is unique in the assembly, and different for each -separate macro expansion. @code{LOCAL} allows you to write macros that -define symbols, without fear of conflict between separate macro expansions. -@end ignore -@end ftable - -@node Nolist -@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 -@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 -@section @code{.org @var{new-lc} , @var{fill}} - -@cindex @code{org} directive -@cindex location counter, advancing -@cindex advancing location counter -@cindex current address, advancing -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, -@command{@value{AS}} issues a warning, then pretends 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. doc@cygnus.com 18feb91 -Because @command{@value{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 P2align -@section @code{.p2align[wl] @var{abs-expr}, @var{abs-expr}, @var{abs-expr}} - -@cindex padding the location counter given a power of two -@cindex @code{p2align} 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 must have after -advancement. For example @samp{.p2align 3} advances 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 fill value to be stored in the -padding bytes. It (and the comma) may be omitted. If it is omitted, the -padding bytes are normally zero. However, on some systems, if the section is -marked as containing code and the fill value is omitted, the space is filled -with no-op instructions. - -The third expression is also absolute, and is also optional. If it is present, -it is the maximum number of bytes that should be skipped by this alignment -directive. If doing the alignment would require skipping more bytes than the -specified maximum, then the alignment is not done at all. You can omit the -fill value (the second argument) entirely by simply using two commas after the -required alignment; this can be useful if you want the alignment to be filled -with no-op instructions when appropriate. - -@cindex @code{p2alignw} directive -@cindex @code{p2alignl} directive -The @code{.p2alignw} and @code{.p2alignl} directives are variants of the -@code{.p2align} directive. The @code{.p2alignw} directive treats the fill -pattern as a two byte word value. The @code{.p2alignl} directives treats the -fill pattern as a four byte longword value. For example, @code{.p2alignw -2,0x368d} will align to a multiple of 4. If it skips two bytes, they will be -filled in with the value 0x368d (the exact placement of the bytes depends upon -the endianness of the processor). If it skips 1 or 3 bytes, the fill value is -undefined. - -@ifset ELF -@node Previous -@section @code{.previous} - -@cindex @code{previous} directive -@cindex Section Stack -This is one of the ELF section stack manipulation directives. The others are -@code{.section} (@pxref{Section}), @code{.subsection} (@pxref{SubSection}), -@code{.pushsection} (@pxref{PushSection}), and @code{.popsection} -(@pxref{PopSection}). - -This directive swaps the current section (and subsection) with most recently -referenced section (and subsection) prior to this one. Multiple -@code{.previous} directives in a row will flip between two sections (and their -subsections). - -In terms of the section stack, this directive swaps the current section with -the top section on the section stack. -@end ifset - -@ifset ELF -@node PopSection -@section @code{.popsection} - -@cindex @code{popsection} directive -@cindex Section Stack -This is one of the ELF section stack manipulation directives. The others are -@code{.section} (@pxref{Section}), @code{.subsection} (@pxref{SubSection}), -@code{.pushsection} (@pxref{PushSection}), and @code{.previous} -(@pxref{Previous}). - -This directive replaces the current section (and subsection) with the top -section (and subsection) on the section stack. This section is popped off the -stack. -@end ifset - -@node Print -@section @code{.print @var{string}} - -@cindex @code{print} directive -@command{@value{AS}} will print @var{string} on the standard output during -assembly. You must put @var{string} in double quotes. - -@ifset ELF -@node Protected -@section @code{.protected @var{names}} - -@cindex @code{protected} directive -@cindex visibility -This one of the ELF visibility directives. The other two are -@code{.hidden} (@pxref{Hidden}) and @code{.internal} (@pxref{Internal}). - -This directive overrides the named symbols default visibility (which is set by -their binding: local, global or weak). The directive sets the visibility to -@code{protected} which means that any references to the symbols from within the -components that defines them must be resolved to the definition in that -component, even if a definition in another component would normally preempt -this. -@end ifset - -@node Psize -@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 do not use @code{.psize}, listings use a default line-count -of 60. You may omit the comma and @var{columns} specification; the -default width is 200 columns. - -@command{@value{AS}} generates 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 Purgem -@section @code{.purgem @var{name}} - -@cindex @code{purgem} directive -Undefine the macro @var{name}, so that later uses of the string will not be -expanded. @xref{Macro}. - -@ifset ELF -@node PushSection -@section @code{.pushsection @var{name} , @var{subsection}} - -@cindex @code{pushsection} directive -@cindex Section Stack -This is one of the ELF section stack manipulation directives. The others are -@code{.section} (@pxref{Section}), @code{.subsection} (@pxref{SubSection}), -@code{.popsection} (@pxref{PopSection}), and @code{.previous} -(@pxref{Previous}). - -This directive is a synonym for @code{.section}. It pushes the current section -(and subsection) onto the top of the section stack, and then replaces the -current section and subsection with @code{name} and @code{subsection}. -@end ifset - -@node Quad -@section @code{.quad @var{bignums}} - -@cindex @code{quad} directive -@code{.quad} expects zero or more bignums, separated by commas. For -each bignum, it emits -@ifclear bignum-16 -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. -@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. -@end ifclear -@ifset bignum-16 -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. -@cindex sixteen-byte integer -@cindex integer, 16-byte -@end ifset - -@node Rept -@section @code{.rept @var{count}} - -@cindex @code{rept} directive -Repeat the sequence of lines between the @code{.rept} directive and the next -@code{.endr} directive @var{count} times. - -For example, assembling - -@example - .rept 3 - .long 0 - .endr -@end example - -is equivalent to assembling - -@example - .long 0 - .long 0 - .long 0 -@end example - -@node Sbttl -@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. - -@ifset COFF -@node Scl -@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. -@ifset BOUT - -The @samp{.scl} directive is primarily associated with COFF output; when -configured to generate @code{b.out} output format, @command{@value{AS}} -accepts this directive but ignores it. -@end ifset -@end ifset - -@ifset COFF-ELF -@node Section -@section @code{.section @var{name}} - -@cindex named section -Use the @code{.section} directive to assemble the following code into a section -named @var{name}. - -This directive is only supported for targets that actually support arbitrarily -named sections; on @code{a.out} targets, for example, it is not accepted, even -with a standard @code{a.out} section name. - -@ifset COFF -@ifset ELF -@c only print the extra heading if both COFF and ELF are set -@subheading COFF Version -@end ifset - -@cindex @code{section} directive (COFF version) -For COFF targets, the @code{.section} directive is used in one of the following -ways: - -@smallexample -.section @var{name}[, "@var{flags}"] -.section @var{name}[, @var{subsegment}] -@end smallexample - -If the optional argument is quoted, it is taken as flags to use for the -section. Each flag is a single character. The following flags are recognized: -@table @code -@item b -bss section (uninitialized data) -@item n -section is not loaded -@item w -writable section -@item d -data section -@item r -read-only section -@item x -executable section -@item s -shared section (meaningful for PE targets) -@item a -ignored. (For compatibility with the ELF version) -@end table - -If no flags are specified, the default flags depend upon the section name. If -the section name is not recognized, the default will be for the section to be -loaded and writable. Note the @code{n} and @code{w} flags remove attributes -from the section, rather than adding them, so if they are used on their own it -will be as if no flags had been specified at all. - -If the optional argument to the @code{.section} directive is not quoted, it is -taken as a subsegment number (@pxref{Sub-Sections}). -@end ifset - -@ifset ELF -@ifset COFF -@c only print the extra heading if both COFF and ELF are set -@subheading ELF Version -@end ifset - -@cindex Section Stack -This is one of the ELF section stack manipulation directives. The others are -@code{.subsection} (@pxref{SubSection}), @code{.pushsection} -(@pxref{PushSection}), @code{.popsection} (@pxref{PopSection}), and -@code{.previous} (@pxref{Previous}). - -@cindex @code{section} directive (ELF version) -For ELF targets, the @code{.section} directive is used like this: - -@smallexample -.section @var{name} [, "@var{flags}"[, @@@var{type}[, @@@var{entsize}]]] -@end smallexample - -The optional @var{flags} argument is a quoted string which may contain any -combination of the following characters: -@table @code -@item a -section is allocatable -@item w -section is writable -@item x -section is executable -@item M -section is mergeable -@item S -section contains zero terminated strings -@end table - -The optional @var{type} argument may contain one of the following constants: -@table @code -@item @@progbits -section contains data -@item @@nobits -section does not contain data (i.e., section only occupies space) -@end table - -Note on targets where the @code{@@} character is the start of a comment (eg -ARM) then another character is used instead. For example the ARM port uses the -@code{%} character. - -If @var{flags} contains @code{M} flag, @var{type} argument must be specified -as well as @var{entsize} argument. Sections with @code{M} flag but not -@code{S} flag must contain fixed size constants, each @var{entsize} octets -long. Sections with both @code{M} and @code{S} must contain zero terminated -strings where each character is @var{entsize} bytes long. The linker may remove -duplicates within sections with the same name, same entity size and same flags. - -If no flags are specified, the default flags depend upon the section name. If -the section name is not recognized, the default will be for the section to have -none of the above flags: it will not be allocated in memory, nor writable, nor -executable. The section will contain data. - -For ELF targets, the assembler supports another type of @code{.section} -directive for compatibility with the Solaris assembler: - -@smallexample -.section "@var{name}"[, @var{flags}...] -@end smallexample - -Note that the section name is quoted. There may be a sequence of comma -separated flags: -@table @code -@item #alloc -section is allocatable -@item #write -section is writable -@item #execinstr -section is executable -@end table - -This directive replaces the current section and subsection. The replaced -section and subsection are pushed onto the section stack. See the contents of -the gas testsuite directory @code{gas/testsuite/gas/elf} for some examples of -how this directive and the other section stack directives work. -@end ifset -@end ifset - -@node Set -@section @code{.set @var{symbol}, @var{expression}} - -@cindex @code{set} directive -@cindex symbol value, setting -Set the value of @var{symbol} to @var{expression}. This -changes @var{symbol}'s value and type to conform to -@var{expression}. If @var{symbol} was flagged as external, it remains -flagged (@pxref{Symbol Attributes}). - -You may @code{.set} a symbol many times in the same assembly. - -If you @code{.set} a global symbol, the value stored in the object -file is the last value stored into it. - -@ifset HPPA -The syntax for @code{set} on the HPPA is -@samp{@var{symbol} .set @var{expression}}. -@end ifset - -@node Short -@section @code{.short @var{expressions}} - -@cindex @code{short} directive -@ifset GENERIC -@code{.short} is normally the same as @samp{.word}. -@xref{Word,,@code{.word}}. - -In some configurations, however, @code{.short} and @code{.word} generate -numbers of different lengths; @pxref{Machine Dependencies}. -@end ifset -@ifclear GENERIC -@ifset W16 -@code{.short} is the same as @samp{.word}. @xref{Word,,@code{.word}}. -@end ifset -@ifset W32 -This expects zero or more @var{expressions}, and emits -a 16 bit number for each. -@end ifset -@end ifclear - -@node Single -@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}. -@ifset GENERIC -The exact kind of floating point numbers emitted depends on how -@command{@value{AS}} is configured. @xref{Machine Dependencies}. -@end ifset -@ifclear GENERIC -@ifset IEEEFLOAT -On the @value{TARGET} family, @code{.single} emits 32-bit floating point -numbers in @sc{ieee} format. -@end ifset -@end ifclear - -@ifset COFF-ELF -@node Size -@section @code{.size} - -This directive is used to set the size associated with a symbol. - -@ifset COFF -@ifset ELF -@c only print the extra heading if both COFF and ELF are set -@subheading COFF Version -@end ifset - -@cindex @code{size} directive (COFF version) -For COFF targets, the @code{.size} directive is only permitted inside -@code{.def}/@code{.endef} pairs. It is used like this: - -@smallexample -.size @var{expression} -@end smallexample - -@ifset BOUT -@samp{.size} is only meaningful when generating COFF format output; when -@command{@value{AS}} is generating @code{b.out}, it accepts this directive but -ignores it. -@end ifset -@end ifset - -@ifset ELF -@ifset COFF -@c only print the extra heading if both COFF and ELF are set -@subheading ELF Version -@end ifset - -@cindex @code{size} directive (ELF version) -For ELF targets, the @code{.size} directive is used like this: - -@smallexample -.size @var{name} , @var{expression} -@end smallexample - -This directive sets the size associated with a symbol @var{name}. -The size in bytes is computed from @var{expression} which can make use of label -arithmetic. This directive is typically used to set the size of function -symbols. -@end ifset -@end ifset - -@node Sleb128 -@section @code{.sleb128 @var{expressions}} - -@cindex @code{sleb128} directive -@var{sleb128} stands for ``signed little endian base 128.'' This is a -compact, variable length representation of numbers used by the DWARF -symbolic debugging format. @xref{Uleb128,@code{.uleb128}}. - -@ifclear no-space-dir -@node Skip -@section @code{.skip @var{size} , @var{fill}} - -@cindex @code{skip} 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. This is the same as -@samp{.space}. - -@node Space -@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. This is the same -as @samp{.skip}. - -@ifset HPPA -@quotation -@emph{Warning:} @code{.space} has a completely different meaning for HPPA -targets; use @code{.block} as a substitute. See @cite{HP9000 Series 800 -Assembly Language Reference Manual} (HP 92432-90001) for the meaning of the -@code{.space} directive. @xref{HPPA Directives,,HPPA Assembler Directives}, -for a summary. -@end quotation -@end ifset -@end ifclear - -@ifset A29K -@ifclear GENERIC -@node Space -@section @code{.space} -@cindex @code{space} directive -@end ifclear -On the AMD 29K, this directive is ignored; it is accepted for -compatibility with other AMD 29K assemblers. - -@quotation -@emph{Warning:} In most versions of the @sc{gnu} assembler, the directive -@code{.space} has the effect of @code{.block} @xref{Machine Dependencies}. -@end quotation -@end ifset - -@ifset have-stabs -@node Stab -@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 @command{@value{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{@value{LD}} -and debuggers 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; -you 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 -is the address of the location counter when the @code{.stabd} was -assembled. - -@cindex @code{stabn} directive -@item .stabn @var{type} , @var{other} , @var{desc} , @var{value} -The name of the symbol is set to the empty string @code{""}. - -@cindex @code{stabs} directive -@item .stabs @var{string} , @var{type} , @var{other} , @var{desc} , @var{value} -All five fields are specified. -@end table -@end ifset -@c end have-stabs - -@node String -@section @code{.string} "@var{str}" - -@cindex string, copying to object file -@cindex @code{string} directive - -Copy the characters in @var{str} to the object file. You may specify more than -one string to copy, separated by commas. Unless otherwise specified for a -particular machine, the assembler marks the end of each string with a 0 byte. -You can use any of the escape sequences described in @ref{Strings,,Strings}. - -@node Struct -@section @code{.struct @var{expression}} - -@cindex @code{struct} directive -Switch to the absolute section, and set the section offset to @var{expression}, -which must be an absolute expression. You might use this as follows: -@smallexample - .struct 0 -field1: - .struct field1 + 4 -field2: - .struct field2 + 4 -field3: -@end smallexample -This would define the symbol @code{field1} to have the value 0, the symbol -@code{field2} to have the value 4, and the symbol @code{field3} to have the -value 8. Assembly would be left in the absolute section, and you would need to -use a @code{.section} directive of some sort to change to some other section -before further assembly. - -@ifset ELF -@node SubSection -@section @code{.subsection @var{name}} - -@cindex @code{subsection} directive -@cindex Section Stack -This is one of the ELF section stack manipulation directives. The others are -@code{.section} (@pxref{Section}), @code{.pushsection} (@pxref{PushSection}), -@code{.popsection} (@pxref{PopSection}), and @code{.previous} -(@pxref{Previous}). - -This directive replaces the current subsection with @code{name}. The current -section is not changed. The replaced subsection is put onto the section stack -in place of the then current top of stack subsection. -@end ifset - -@ifset ELF -@node Symver -@section @code{.symver} -@cindex @code{symver} directive -@cindex symbol versioning -@cindex versions of symbols -Use the @code{.symver} directive to bind symbols to specific version nodes -within a source file. This is only supported on ELF platforms, and is -typically used when assembling files to be linked into a shared library. -There are cases where it may make sense to use this in objects to be bound -into an application itself so as to override a versioned symbol from a -shared library. - -For ELF targets, the @code{.symver} directive can be used like this: -@smallexample -.symver @var{name}, @var{name2@@nodename} -@end smallexample -If the symbol @var{name} is defined within the file -being assembled, the @code{.symver} directive effectively creates a symbol -alias with the name @var{name2@@nodename}, and in fact the main reason that we -just don't try and create a regular alias is that the @var{@@} character isn't -permitted in symbol names. The @var{name2} part of the name is the actual name -of the symbol by which it will be externally referenced. The name @var{name} -itself is merely a name of convenience that is used so that it is possible to -have definitions for multiple versions of a function within a single source -file, and so that the compiler can unambiguously know which version of a -function is being mentioned. The @var{nodename} portion of the alias should be -the name of a node specified in the version script supplied to the linker when -building a shared library. If you are attempting to override a versioned -symbol from a shared library, then @var{nodename} should correspond to the -nodename of the symbol you are trying to override. - -If the symbol @var{name} is not defined within the file being assembled, all -references to @var{name} will be changed to @var{name2@@nodename}. If no -reference to @var{name} is made, @var{name2@@nodename} will be removed from the -symbol table. - -Another usage of the @code{.symver} directive is: -@smallexample -.symver @var{name}, @var{name2@@@@nodename} -@end smallexample -In this case, the symbol @var{name} must exist and be defined within -the file being assembled. It is similar to @var{name2@@nodename}. The -difference is @var{name2@@@@nodename} will also be used to resolve -references to @var{name2} by the linker. - -The third usage of the @code{.symver} directive is: -@smallexample -.symver @var{name}, @var{name2@@@@@@nodename} -@end smallexample -When @var{name} is not defined within the -file being assembled, it is treated as @var{name2@@nodename}. When -@var{name} is defined within the file being assembled, the symbol -name, @var{name}, will be changed to @var{name2@@@@nodename}. -@end ifset - -@ifset COFF -@node Tag -@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. -@ifset BOUT - -@samp{.tag} is only used when generating COFF format output; when -@command{@value{AS}} is generating @code{b.out}, it accepts this directive but -ignores it. -@end ifset -@end ifset - -@node Text -@section @code{.text @var{subsection}} - -@cindex @code{text} directive -Tells @command{@value{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. - -@node Title -@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. - -@ifset COFF-ELF -@node Type -@section @code{.type} - -This directive is used to set the type of a symbol. - -@ifset COFF -@ifset ELF -@c only print the extra heading if both COFF and ELF are set -@subheading COFF Version -@end ifset - -@cindex COFF symbol type -@cindex symbol type, COFF -@cindex @code{type} directive (COFF version) -For COFF targets, this directive is permitted only within -@code{.def}/@code{.endef} pairs. It is used like this: - -@smallexample -.type @var{int} -@end smallexample - -This records the integer @var{int} as the type attribute of a symbol table -entry. - -@ifset BOUT -@samp{.type} is associated only with COFF format output; when -@command{@value{AS}} is configured for @code{b.out} output, it accepts this -directive but ignores it. -@end ifset -@end ifset - -@ifset ELF -@ifset COFF -@c only print the extra heading if both COFF and ELF are set -@subheading ELF Version -@end ifset - -@cindex ELF symbol type -@cindex symbol type, ELF -@cindex @code{type} directive (ELF version) -For ELF targets, the @code{.type} directive is used like this: - -@smallexample -.type @var{name} , @var{type description} -@end smallexample - -This sets the type of symbol @var{name} to be either a -function symbol or an object symbol. There are five different syntaxes -supported for the @var{type description} field, in order to provide -compatibility with various other assemblers. The syntaxes supported are: - -@smallexample - .type <name>,#function - .type <name>,#object - - .type <name>,@@function - .type <name>,@@object - - .type <name>,%function - .type <name>,%object - - .type <name>,"function" - .type <name>,"object" - - .type <name> STT_FUNCTION - .type <name> STT_OBJECT -@end smallexample -@end ifset -@end ifset - -@node Uleb128 -@section @code{.uleb128 @var{expressions}} - -@cindex @code{uleb128} directive -@var{uleb128} stands for ``unsigned little endian base 128.'' This is a -compact, variable length representation of numbers used by the DWARF -symbolic debugging format. @xref{Sleb128,@code{.sleb128}}. - -@ifset COFF -@node Val -@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. -@ifset BOUT - -@samp{.val} is used only for COFF output; when @command{@value{AS}} is -configured for @code{b.out}, it accepts this directive but ignores it. -@end ifset -@end ifset - -@ifset ELF -@node Version -@section @code{.version "@var{string}"} - -@cindex @code{version} directive -This directive creates a @code{.note} section and places into it an ELF -formatted note of type NT_VERSION. The note's name is set to @code{string}. -@end ifset - -@ifset ELF -@node VTableEntry -@section @code{.vtable_entry @var{table}, @var{offset}} - -@cindex @code{vtable_entry} -This directive finds or creates a symbol @code{table} and creates a -@code{VTABLE_ENTRY} relocation for it with an addend of @code{offset}. - -@node VTableInherit -@section @code{.vtable_inherit @var{child}, @var{parent}} - -@cindex @code{vtable_inherit} -This directive finds the symbol @code{child} and finds or creates the symbol -@code{parent} and then creates a @code{VTABLE_INHERIT} relocation for the -parent whose addend is the value of the child symbol. As a special case the -parent name of @code{0} is treated as refering the @code{*ABS*} section. -@end ifset - -@ifset ELF -@node Weak -@section @code{.weak @var{names}} - -@cindex @code{weak} directive -This directive sets the weak attribute on the comma separated list of symbol -@code{names}. If the symbols do not already exist, they will be created. -@end ifset - -@node Word -@section @code{.word @var{expressions}} - -@cindex @code{word} directive -This directive expects zero or more @var{expressions}, of any section, -separated by commas. -@ifclear GENERIC -@ifset W32 -For each expression, @command{@value{AS}} emits a 32-bit number. -@end ifset -@ifset W16 -For each expression, @command{@value{AS}} emits a 16-bit number. -@end ifset -@end ifclear -@ifset GENERIC - -The size of the number emitted, and its byte order, -depend on what target computer the assembly is for. -@end ifset - -@c on amd29k, i960, sparc the "special treatment to support compilers" doesn't -@c happen---32-bit addressability, period; no long/short jumps. -@ifset DIFF-TBL-KLUGE -@cindex difference tables altered -@cindex altered difference tables -@quotation -@emph{Warning: Special Treatment to support Compilers} -@end quotation - -@ifset 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{Machine Dependencies}), you can ignore this issue. - -@end ifset -In order to assemble compiler output into something that works, -@command{@value{AS}} occasionally does 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 @command{@value{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, @command{@value{AS}} -creates a @dfn{secondary jump table}, immediately before the next label. -This secondary jump table is 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 is a long-jump to @code{sym2}. The original @samp{.word} -contains @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 are adjusted. If there was a -@samp{.word sym3-sym4}, that also did not fit in sixteen bits, a -long-jump to @code{sym4} is included in the secondary jump table, -and the @code{.word} directives are 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. - -@ifset INTERNALS -@emph{This feature may be disabled by compiling @command{@value{AS}} with the -@samp{-DWORKING_DOT_WORD} option.} This feature is likely to confuse -assembly language programmers. -@end ifset -@end ifset -@c end DIFF-TBL-KLUGE - -@node Deprecated -@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 .line -@end table - -@ifset GENERIC -@node Machine Dependencies -@chapter Machine Dependent Features - -@cindex machine dependencies -The machine instruction sets are (almost by definition) different on -each machine where @command{@value{AS}} runs. Floating point representations -vary as well, and @command{@value{AS}} often supports a few additional -directives or command-line options for compatibility with other -assemblers on a particular platform. Finally, some versions of -@command{@value{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 -@ifset A29K -* AMD29K-Dependent:: AMD 29K Dependent Features -@end ifset -@ifset ALPHA -* Alpha-Dependent:: Alpha Dependent Features -@end ifset -@ifset ARC -* ARC-Dependent:: ARC Dependent Features -@end ifset -@ifset ARM -* ARM-Dependent:: ARM Dependent Features -@end ifset -@ifset CRIS -* CRIS-Dependent:: CRIS Dependent Features -@end ifset -@ifset D10V -* D10V-Dependent:: D10V Dependent Features -@end ifset -@ifset D30V -* D30V-Dependent:: D30V Dependent Features -@end ifset -@ifset H8/300 -* H8/300-Dependent:: Renesas H8/300 Dependent Features -@end ifset -@ifset H8/500 -* H8/500-Dependent:: Renesas H8/500 Dependent Features -@end ifset -@ifset HPPA -* HPPA-Dependent:: HPPA Dependent Features -@end ifset -@ifset I370 -* ESA/390-Dependent:: IBM ESA/390 Dependent Features -@end ifset -@ifset I80386 -* i386-Dependent:: Intel 80386 and AMD x86-64 Dependent Features -@end ifset -@ifset I860 -* i860-Dependent:: Intel 80860 Dependent Features -@end ifset -@ifset I960 -* i960-Dependent:: Intel 80960 Dependent Features -@end ifset -@ifset IP2K -* IP2K-Dependent:: IP2K Dependent Features -@end ifset -@ifset M32R -* M32R-Dependent:: M32R Dependent Features -@end ifset -@ifset M680X0 -* M68K-Dependent:: M680x0 Dependent Features -@end ifset -@ifset M68HC11 -* M68HC11-Dependent:: M68HC11 and 68HC12 Dependent Features -@end ifset -@ifset M880X0 -* M88K-Dependent:: M880x0 Dependent Features -@end ifset -@ifset MIPS -* MIPS-Dependent:: MIPS Dependent Features -@end ifset -@ifset MMIX -* MMIX-Dependent:: MMIX Dependent Features -@end ifset -@ifset MSP430 -* MSP430-Dependent:: MSP430 Dependent Features -@end ifset -@ifset SH -* SH-Dependent:: Renesas / SuperH SH Dependent Features -* SH64-Dependent:: SuperH SH64 Dependent Features -@end ifset -@ifset PDP11 -* PDP-11-Dependent:: PDP-11 Dependent Features -@end ifset -@ifset PJ -* PJ-Dependent:: picoJava Dependent Features -@end ifset -@ifset PPC -* PPC-Dependent:: PowerPC Dependent Features -@end ifset -@ifset SPARC -* Sparc-Dependent:: SPARC Dependent Features -@end ifset -@ifset TIC54X -* TIC54X-Dependent:: TI TMS320C54x Dependent Features -@end ifset -@ifset V850 -* V850-Dependent:: V850 Dependent Features -@end ifset -@ifset XTENSA -* Xtensa-Dependent:: Xtensa Dependent Features -@end ifset -@ifset Z8000 -* Z8000-Dependent:: Z8000 Dependent Features -@end ifset -@ifset VAX -* Vax-Dependent:: VAX Dependent Features -@end ifset -@end menu - -@lowersections -@end ifset - -@c The following major nodes are *sections* in the GENERIC version, *chapters* -@c in single-cpu versions. This is mainly achieved by @lowersections. There is a -@c peculiarity: to preserve cross-references, there must be a node called -@c "Machine Dependencies". Hence the conditional nodenames in each -@c major node below. Node defaulting in makeinfo requires adjacency of -@c node and sectioning commands; hence the repetition of @chapter BLAH -@c in both conditional blocks. - -@ifset A29K -@include c-a29k.texi -@end ifset - -@ifset ALPHA -@include c-alpha.texi -@end ifset - -@ifset ARC -@include c-arc.texi -@end ifset - -@ifset ARM -@include c-arm.texi -@end ifset - -@ifset CRIS -@include c-cris.texi -@end ifset - -@ifset Renesas-all -@ifclear GENERIC -@node Machine Dependencies -@chapter Machine Dependent Features - -The machine instruction sets are different on each Renesas chip family, -and there are also some syntax differences among the families. This -chapter describes the specific @command{@value{AS}} features for each -family. - -@menu -* H8/300-Dependent:: Renesas H8/300 Dependent Features -* H8/500-Dependent:: Renesas H8/500 Dependent Features -* SH-Dependent:: Renesas SH Dependent Features -@end menu -@lowersections -@end ifclear -@end ifset - -@ifset D10V -@include c-d10v.texi -@end ifset - -@ifset D30V -@include c-d30v.texi -@end ifset - -@ifset H8/300 -@include c-h8300.texi -@end ifset - -@ifset H8/500 -@include c-h8500.texi -@end ifset - -@ifset HPPA -@include c-hppa.texi -@end ifset - -@ifset I370 -@include c-i370.texi -@end ifset - -@ifset I80386 -@include c-i386.texi -@end ifset - -@ifset I860 -@include c-i860.texi -@end ifset - -@ifset I960 -@include c-i960.texi -@end ifset - -@ifset IA64 -@include c-ia64.texi -@end ifset - -@ifset IP2K -@include c-ip2k.texi -@end ifset - -@ifset M32R -@include c-m32r.texi -@end ifset - -@ifset M680X0 -@include c-m68k.texi -@end ifset - -@ifset M68HC11 -@include c-m68hc11.texi -@end ifset - -@ifset M880X0 -@include c-m88k.texi -@end ifset - -@ifset MIPS -@include c-mips.texi -@end ifset - -@ifset MMIX -@include c-mmix.texi -@end ifset - -@ifset MSP430 -@include c-msp430.texi -@end ifset - -@ifset NS32K -@include c-ns32k.texi -@end ifset - -@ifset PDP11 -@include c-pdp11.texi -@end ifset - -@ifset PJ -@include c-pj.texi -@end ifset - -@ifset PPC -@include c-ppc.texi -@end ifset - -@ifset SH -@include c-sh.texi -@include c-sh64.texi -@end ifset - -@ifset SPARC -@include c-sparc.texi -@end ifset - -@ifset TIC54X -@include c-tic54x.texi -@end ifset - -@ifset Z8000 -@include c-z8k.texi -@end ifset - -@ifset VAX -@include c-vax.texi -@end ifset - -@ifset V850 -@include c-v850.texi -@end ifset - -@ifset XTENSA -@include c-xtensa.texi -@end ifset - -@ifset GENERIC -@c reverse effect of @down at top of generic Machine-Dep chapter -@raisesections -@end ifset - -@node Reporting Bugs -@chapter Reporting Bugs -@cindex bugs in assembler -@cindex reporting bugs in assembler - -Your bug reports play an essential role in making @command{@value{AS}} reliable. - -Reporting a bug may help you by bringing a solution to your problem, or it may -not. But in any case the principal function of a bug report is to help the -entire community by making the next version of @command{@value{AS}} work better. -Bug reports are your contribution to the maintenance of @command{@value{AS}}. - -In order for a bug report to serve its purpose, you must include the -information that enables us to fix the bug. - -@menu -* Bug Criteria:: Have you found a bug? -* Bug Reporting:: How to report bugs -@end menu - -@node Bug Criteria -@section Have You Found a Bug? -@cindex bug criteria - -If you are not sure whether you have found a bug, here are some guidelines: - -@itemize @bullet -@cindex fatal signal -@cindex assembler crash -@cindex crash of assembler -@item -If the assembler gets a fatal signal, for any input whatever, that is a -@command{@value{AS}} bug. Reliable assemblers never crash. - -@cindex error on valid input -@item -If @command{@value{AS}} produces an error message for valid input, that is a bug. - -@cindex invalid input -@item -If @command{@value{AS}} does not produce an error message for invalid input, that -is a bug. However, you should note that your idea of ``invalid input'' might -be our idea of ``an extension'' or ``support for traditional practice''. - -@item -If you are an experienced user of assemblers, your suggestions for improvement -of @command{@value{AS}} are welcome in any case. -@end itemize - -@node Bug Reporting -@section How to Report Bugs -@cindex bug reports -@cindex assembler bugs, reporting - -A number of companies and individuals offer support for @sc{gnu} products. If -you obtained @command{@value{AS}} from a support organization, we recommend you -contact that organization first. - -You can find contact information for many support companies and -individuals in the file @file{etc/SERVICE} in the @sc{gnu} Emacs -distribution. - -In any event, we also recommend that you send bug reports for @command{@value{AS}} -to @samp{bug-binutils@@gnu.org}. - -The fundamental principle of reporting bugs usefully is this: -@strong{report all the facts}. If you are not sure whether to state a -fact or leave it out, state it! - -Often people omit facts because they think they know what causes the problem -and assume that some details do not matter. Thus, you might assume that the -name of a symbol you use in an example does not matter. Well, probably it does -not, but one cannot be sure. Perhaps the bug is a stray memory reference which -happens to fetch from the location where that name is stored in memory; -perhaps, if the name were different, the contents of that location would fool -the assembler into doing the right thing despite the bug. Play it safe and -give a specific, complete example. That is the easiest thing for you to do, -and the most helpful. - -Keep in mind that the purpose of a bug report is to enable us to fix the bug if -it is new to us. Therefore, always write your bug reports on the assumption -that the bug has not been reported previously. - -Sometimes people give a few sketchy facts and ask, ``Does this ring a -bell?'' This cannot help us fix a bug, so it is basically useless. We -respond by asking for enough details to enable us to investigate. -You might as well expedite matters by sending them to begin with. - -To enable us to fix the bug, you should include all these things: - -@itemize @bullet -@item -The version of @command{@value{AS}}. @command{@value{AS}} announces it if you start -it with the @samp{--version} argument. - -Without this, we will not know whether there is any point in looking for -the bug in the current version of @command{@value{AS}}. - -@item -Any patches you may have applied to the @command{@value{AS}} source. - -@item -The type of machine you are using, and the operating system name and -version number. - -@item -What compiler (and its version) was used to compile @command{@value{AS}}---e.g. -``@code{gcc-2.7}''. - -@item -The command arguments you gave the assembler to assemble your example and -observe the bug. To guarantee you will not omit something important, list them -all. A copy of the Makefile (or the output from make) is sufficient. - -If we were to try to guess the arguments, we would probably guess wrong -and then we might not encounter the bug. - -@item -A complete input file that will reproduce the bug. If the bug is observed when -the assembler is invoked via a compiler, send the assembler source, not the -high level language source. Most compilers will produce the assembler source -when run with the @samp{-S} option. If you are using @code{@value{GCC}}, use -the options @samp{-v --save-temps}; this will save the assembler source in a -file with an extension of @file{.s}, and also show you exactly how -@command{@value{AS}} is being run. - -@item -A description of what behavior you observe that you believe is -incorrect. For example, ``It gets a fatal signal.'' - -Of course, if the bug is that @command{@value{AS}} gets a fatal signal, then we -will certainly notice it. But if the bug is incorrect output, we might not -notice unless it is glaringly wrong. You might as well not give us a chance to -make a mistake. - -Even if the problem you experience is a fatal signal, you should still say so -explicitly. Suppose something strange is going on, such as, your copy of -@command{@value{AS}} is out of synch, or you have encountered a bug in the C -library on your system. (This has happened!) Your copy might crash and ours -would not. If you told us to expect a crash, then when ours fails to crash, we -would know that the bug was not happening for us. If you had not told us to -expect a crash, then we would not be able to draw any conclusion from our -observations. - -@item -If you wish to suggest changes to the @command{@value{AS}} source, send us context -diffs, as generated by @code{diff} with the @samp{-u}, @samp{-c}, or @samp{-p} -option. Always send diffs from the old file to the new file. If you even -discuss something in the @command{@value{AS}} source, refer to it by context, not -by line number. - -The line numbers in our development sources will not match those in your -sources. Your line numbers would convey no useful information to us. -@end itemize - -Here are some things that are not necessary: - -@itemize @bullet -@item -A description of the envelope of the bug. - -Often people who encounter a bug spend a lot of time investigating -which changes to the input file will make the bug go away and which -changes will not affect it. - -This is often time consuming and not very useful, because the way we -will find the bug is by running a single example under the debugger -with breakpoints, not by pure deduction from a series of examples. -We recommend that you save your time for something else. - -Of course, if you can find a simpler example to report @emph{instead} -of the original one, that is a convenience for us. Errors in the -output will be easier to spot, running under the debugger will take -less time, and so on. - -However, simplification is not vital; if you do not want to do this, -report the bug anyway and send us the entire test case you used. - -@item -A patch for the bug. - -A patch for the bug does help us if it is a good one. But do not omit -the necessary information, such as the test case, on the assumption that -a patch is all we need. We might see problems with your patch and decide -to fix the problem another way, or we might not understand it at all. - -Sometimes with a program as complicated as @command{@value{AS}} it is very hard to -construct an example that will make the program follow a certain path through -the code. If you do not send us the example, we will not be able to construct -one, so we will not be able to verify that the bug is fixed. - -And if we cannot understand what bug you are trying to fix, or why your -patch should be an improvement, we will not install it. A test case will -help us to understand. - -@item -A guess about what the bug is or what it depends on. - -Such guesses are usually wrong. Even we cannot guess right about such -things without first using the debugger to find the facts. -@end itemize - -@node Acknowledgements -@chapter Acknowledgements - -If you have contributed to @command{@value{AS}} and your name isn't listed here, -it is not meant as a slight. We just don't know about it. Send mail to the -maintainer, and we'll correct the situation. Currently -@c (January 1994), -the maintainer is Ken Raeburn (email address @code{raeburn@@cygnus.com}). - -Dean Elsner wrote the original @sc{gnu} assembler for the VAX.@footnote{Any -more details?} - -Jay Fenlason maintained GAS for a while, adding support for GDB-specific debug -information and the 68k series machines, most of the preprocessing pass, and -extensive changes in @file{messages.c}, @file{input-file.c}, @file{write.c}. - -K. Richard Pixley maintained GAS for a while, adding various enhancements and -many bug fixes, including merging support for several processors, breaking GAS -up to handle multiple object file format back ends (including heavy rewrite, -testing, an integration of the coff and b.out back ends), adding configuration -including heavy testing and verification of cross assemblers and file splits -and renaming, converted GAS to strictly ANSI C including full prototypes, added -support for m680[34]0 and cpu32, did considerable work on i960 including a COFF -port (including considerable amounts of reverse engineering), a SPARC opcode -file rewrite, DECstation, rs6000, and hp300hpux host ports, updated ``know'' -assertions and made them work, much other reorganization, cleanup, and lint. - -Ken Raeburn wrote the high-level BFD interface code to replace most of the code -in format-specific I/O modules. - -The original VMS support was contributed by David L. Kashtan. Eric Youngdale -has done much work with it since. - -The Intel 80386 machine description was written by Eliot Dresselhaus. - -Minh Tran-Le at IntelliCorp contributed some AIX 386 support. - -The Motorola 88k machine description was contributed by Devon Bowen of Buffalo -University and Torbjorn Granlund of the Swedish Institute of Computer Science. - -Keith Knowles at the Open Software Foundation wrote the original MIPS back end -(@file{tc-mips.c}, @file{tc-mips.h}), and contributed Rose format support -(which hasn't been merged in yet). Ralph Campbell worked with the MIPS code to -support a.out format. - -Support for the Zilog Z8k and Renesas H8/300 and H8/500 processors (tc-z8k, -tc-h8300, tc-h8500), and IEEE 695 object file format (obj-ieee), was written by -Steve Chamberlain of Cygnus Support. Steve also modified the COFF back end to -use BFD for some low-level operations, for use with the H8/300 and AMD 29k -targets. - -John Gilmore built the AMD 29000 support, added @code{.include} support, and -simplified the configuration of which versions accept which directives. He -updated the 68k machine description so that Motorola's opcodes always produced -fixed-size instructions (e.g., @code{jsr}), while synthetic instructions -remained shrinkable (@code{jbsr}). John fixed many bugs, including true tested -cross-compilation support, and one bug in relaxation that took a week and -required the proverbial one-bit fix. - -Ian Lance Taylor of Cygnus Support merged the Motorola and MIT syntax for the -68k, completed support for some COFF targets (68k, i386 SVR3, and SCO Unix), -added support for MIPS ECOFF and ELF targets, wrote the initial RS/6000 and -PowerPC assembler, and made a few other minor patches. - -Steve Chamberlain made @command{@value{AS}} able to generate listings. - -Hewlett-Packard contributed support for the HP9000/300. - -Jeff Law wrote GAS and BFD support for the native HPPA object format (SOM) -along with a fairly extensive HPPA testsuite (for both SOM and ELF object -formats). This work was supported by both the Center for Software Science at -the University of Utah and Cygnus Support. - -Support for ELF format files has been worked on by Mark Eichin of Cygnus -Support (original, incomplete implementation for SPARC), Pete Hoogenboom and -Jeff Law at the University of Utah (HPPA mainly), Michael Meissner of the Open -Software Foundation (i386 mainly), and Ken Raeburn of Cygnus Support (sparc, -and some initial 64-bit support). - -Linas Vepstas added GAS support for the ESA/390 ``IBM 370'' architecture. - -Richard Henderson rewrote the Alpha assembler. Klaus Kaempf wrote GAS and BFD -support for openVMS/Alpha. - -Timothy Wall, Michael Hayes, and Greg Smart contributed to the various tic* -flavors. - -David Heine, Sterling Augustine, Bob Wilson and John Ruttenberg from Tensilica, -Inc. added support for Xtensa processors. - -Several engineers at Cygnus Support have also provided many small bug fixes and -configuration enhancements. - -Many others have contributed large or small bugfixes and enhancements. If -you have contributed significant work and are not mentioned on this list, and -want to be, let us know. Some of the history has been lost; we are not -intentionally leaving anyone out. - -@include fdl.texi - -@node Index -@unnumbered Index - -@printindex cp - -@contents -@bye -@c Local Variables: -@c fill-column: 79 -@c End: diff --git a/contrib/binutils/gas/doc/c-alpha.texi b/contrib/binutils/gas/doc/c-alpha.texi deleted file mode 100644 index 0aee06b2d8be6..0000000000000 --- a/contrib/binutils/gas/doc/c-alpha.texi +++ /dev/null @@ -1,466 +0,0 @@ -@c Copyright 2002 -@c Free Software Foundation, Inc. -@c This is part of the GAS manual. -@c For copying conditions, see the file as.texinfo. - -@ifset GENERIC -@page -@node Alpha-Dependent -@chapter Alpha Dependent Features -@end ifset - -@ifclear GENERIC -@node Machine Dependencies -@chapter Alpha Dependent Features -@end ifclear - -@cindex Alpha support -@menu -* Alpha Notes:: Notes -* Alpha Options:: Options -* Alpha Syntax:: Syntax -* Alpha Floating Point:: Floating Point -* Alpha Directives:: Alpha Machine Directives -* Alpha Opcodes:: Opcodes -@end menu - -@node Alpha Notes -@section Notes -@cindex Alpha notes -@cindex notes for Alpha - -The documentation here is primarily for the ELF object format. -@code{@value{AS}} also supports the ECOFF and EVAX formats, but -features specific to these formats are not yet documented. - -@node Alpha Options -@section Options -@cindex Alpha options -@cindex options for Alpha - -@table @option -@cindex @code{-m@var{cpu}} command line option, Alpha -@item -m@var{cpu} -This option specifies the target processor. If an attempt is made to -assemble an instruction which will not execute on the target processor, -the assembler may either expand the instruction as a macro or issue an -error message. This option is equivalent to the @code{.arch} directive. - -The following processor names are recognized: -@code{21064}, -@code{21064a}, -@code{21066}, -@code{21068}, -@code{21164}, -@code{21164a}, -@code{21164pc}, -@code{21264}, -@code{21264a}, -@code{21264b}, -@code{ev4}, -@code{ev5}, -@code{lca45}, -@code{ev5}, -@code{ev56}, -@code{pca56}, -@code{ev6}, -@code{ev67}, -@code{ev68}. -The special name @code{all} may be used to allow the assembler to accept -instructions valid for any Alpha processor. - -In order to support existing practice in OSF/1 with respect to @code{.arch}, -and existing practice within @command{MILO} (the Linux ARC bootloader), the -numbered processor names (e.g.@: 21064) enable the processor-specific PALcode -instructions, while the ``electro-vlasic'' names (e.g.@: @code{ev4}) do not. - -@cindex @code{-mdebug} command line option, Alpha -@cindex @code{-no-mdebug} command line option, Alpha -@item -mdebug -@itemx -no-mdebug -Enables or disables the generation of @code{.mdebug} encapsulation for -stabs directives and procedure descriptors. The default is to automatically -enable @code{.mdebug} when the first stabs directive is seen. - -@cindex @code{-relax} command line option, Alpha -@item -relax -This option forces all relocations to be put into the object file, instead -of saving space and resolving some relocations at assembly time. Note that -this option does not propagate all symbol arithmetic into the object file, -because not all symbol arithmetic can be represented. However, the option -can still be useful in specific applications. - -@cindex @code{-g} command line option, Alpha -@item -g -This option is used when the compiler generates debug information. When -@command{gcc} is using @command{mips-tfile} to generate debug -information for ECOFF, local labels must be passed through to the object -file. Otherwise this option has no effect. - -@cindex @code{-G} command line option, Alpha -@item -G@var{size} -A local common symbol larger than @var{size} is placed in @code{.bss}, -while smaller symbols are placed in @code{.sbss}. - -@cindex @code{-F} command line option, Alpha -@cindex @code{-32addr} command line option, Alpha -@item -F -@itemx -32addr -These options are ignored for backward compatibility. -@end table - -@cindex Alpha Syntax -@node Alpha Syntax -@section Syntax -The assembler syntax closely follow the Alpha Reference Manual; -assembler directives and general syntax closely follow the OSF/1 and -OpenVMS syntax, with a few differences for ELF. - -@menu -* Alpha-Chars:: Special Characters -* Alpha-Regs:: Register Names -* Alpha-Relocs:: Relocations -@end menu - -@node Alpha-Chars -@subsection Special Characters - -@cindex line comment character, Alpha -@cindex Alpha line comment character -@samp{#} is the line comment character. - -@cindex line separator, Alpha -@cindex statement separator, Alpha -@cindex Alpha line separator -@samp{;} can be used instead of a newline to separate statements. - -@node Alpha-Regs -@subsection Register Names -@cindex Alpha registers -@cindex register names, Alpha - -The 32 integer registers are referred to as @samp{$@var{n}} or -@samp{$r@var{n}}. In addition, registers 15, 28, 29, and 30 may -be referred to by the symbols @samp{$fp}, @samp{$at}, @samp{$gp}, -and @samp{$sp} respectively. - -The 32 floating-point registers are referred to as @samp{$f@var{n}}. - -@node Alpha-Relocs -@subsection Relocations -@cindex Alpha relocations -@cindex relocations, Alpha - -Some of these relocations are available for ECOFF, but mostly -only for ELF. They are modeled after the relocation format -introduced in Digital Unix 4.0, but there are additions. - -The format is @samp{!@var{tag}} or @samp{!@var{tag}!@var{number}} -where @var{tag} is the name of the relocation. In some cases -@var{number} is used to relate specific instructions. - -The relocation is placed at the end of the instruction like so: - -@example -ldah $0,a($29) !gprelhigh -lda $0,a($0) !gprellow -ldq $1,b($29) !literal!100 -ldl $2,0($1) !lituse_base!100 -@end example - -@table @code -@item !literal -@itemx !literal!@var{N} -Used with an @code{ldq} instruction to load the address of a symbol -from the GOT. - -A sequence number @var{N} is optional, and if present is used to pair -@code{lituse} relocations with this @code{literal} relocation. The -@code{lituse} relocations are used by the linker to optimize the code -based on the final location of the symbol. - -Note that these optimizations are dependent on the data flow of the -program. Therefore, if @emph{any} @code{lituse} is paired with a -@code{literal} relocation, then @emph{all} uses of the register set by -the @code{literal} instruction must also be marked with @code{lituse} -relocations. This is because the original @code{literal} instruction -may be deleted or transformed into another instruction. - -Also note that there may be a one-to-many relationship between -@code{literal} and @code{lituse}, but not a many-to-one. That is, if -there are two code paths that load up the same address and feed the -value to a single use, then the use may not use a @code{lituse} -relocation. - -@item !lituse_base!@var{N} -Used with any memory format instruction (e.g.@: @code{ldl}) to indicate -that the literal is used for an address load. The offset field of the -instruction must be zero. During relaxation, the code may be altered -to use a gp-relative load. - -@item !lituse_jsr!@var{N} -Used with a register branch format instruction (e.g.@: @code{jsr}) to -indicate that the literal is used for a call. During relaxation, the -code may be altered to use a direct branch (e.g.@: @code{bsr}). - -@item !lituse_bytoff!@var{N} -Used with a byte mask instruction (e.g.@: @code{extbl}) to indicate -that only the low 3 bits of the address are relevant. During relaxation, -the code may be altered to use an immediate instead of a register shift. - -@item !lituse_addr!@var{N} -Used with any other instruction to indicate that the original address -is in fact used, and the original @code{ldq} instruction may not be -altered or deleted. This is useful in conjunction with @code{lituse_jsr} -to test whether a weak symbol is defined. - -@example -ldq $27,foo($29) !literal!1 -beq $27,is_undef !lituse_addr!1 -jsr $26,($27),foo !lituse_jsr!1 -@end example - -@item !lituse_tlsgd!@var{N} -Used with a register branch format instruction to indicate that the -literal is the call to @code{__tls_get_addr} used to compute the -address of the thread-local storage variable whose descriptor was -loaded with @code{!tlsgd!@var{N}}. - -@item !lituse_tlsldm!@var{N} -Used with a register branch format instruction to indicate that the -literal is the call to @code{__tls_get_addr} used to compute the -address of the base of the thread-local storage block for the current -module. The descriptor for the module must have been loaded with -@code{!tlsldm!@var{N}}. - -@item !gpdisp!@var{N} -Used with @code{ldah} and @code{lda} to load the GP from the current -address, a-la the @code{ldgp} macro. The source register for the -@code{ldah} instruction must contain the address of the @code{ldah} -instruction. There must be exactly one @code{lda} instruction paired -with the @code{ldah} instruction, though it may appear anywhere in -the instruction stream. The immediate operands must be zero. - -@example -bsr $26,foo -ldah $29,0($26) !gpdisp!1 -lda $29,0($29) !gpdisp!1 -@end example - -@item !gprelhigh -Used with an @code{ldah} instruction to add the high 16 bits of a -32-bit displacement from the GP. - -@item !gprellow -Used with any memory format instruction to add the low 16 bits of a -32-bit displacement from the GP. - -@item !gprel -Used with any memory format instruction to add a 16-bit displacement -from the GP. - -@item !samegp -Used with any branch format instruction to skip the GP load at the -target address. The referenced symbol must have the same GP as the -source object file, and it must be declared to either not use @code{$27} -or perform a standard GP load in the first two instructions via the -@code{.prologue} directive. - -@item !tlsgd -@itemx !tlsgd!@var{N} -Used with an @code{lda} instruction to load the address of a TLS -descriptor for a symbol in the GOT. - -The sequence number @var{N} is optional, and if present it used to -pair the descriptor load with both the @code{literal} loading the -address of the @code{__tls_get_addr} function and the @code{lituse_tlsgd} -marking the call to that function. - -For proper relaxation, both the @code{tlsgd}, @code{literal} and -@code{lituse} relocations must be in the same extended basic block. -That is, the relocation with the lowest address must be executed -first at runtime. - -@item !tlsldm -@itemx !tlsldm!@var{N} -Used with an @code{lda} instruction to load the address of a TLS -descriptor for the current module in the GOT. - -Similar in other respects to @code{tlsgd}. - -@item !gotdtprel -Used with an @code{ldq} instruction to load the offset of the TLS -symbol within its module's thread-local storage block. Also known -as the dynamic thread pointer offset or dtp-relative offset. - -@item !dtprelhi -@itemx !dtprello -@itemx !dtprel -Like @code{gprel} relocations except they compute dtp-relative offsets. - -@item !gottprel -Used with an @code{ldq} instruction to load the offset of the TLS -symbol from the thread pointer. Also known as the tp-relative offset. - -@item !tprelhi -@itemx !tprello -@itemx !tprel -Like @code{gprel} relocations except they compute tp-relative offsets. -@end table - -@node Alpha Floating Point -@section Floating Point -@cindex floating point, Alpha (@sc{ieee}) -@cindex Alpha floating point (@sc{ieee}) -The Alpha family uses both @sc{ieee} and VAX floating-point numbers. - -@node Alpha Directives -@section Alpha Assembler Directives - -@command{@value{AS}} for the Alpha supports many additional directives for -compatibility with the native assembler. This section describes them only -briefly. - -@cindex Alpha-only directives -These are the additional directives in @code{@value{AS}} for the Alpha: - -@table @code -@item .arch @var{cpu} -Specifies the target processor. This is equivalent to the -@option{-m@var{cpu}} command-line option. @xref{Alpha Options, Options}, -for a list of values for @var{cpu}. - -@item .ent @var{function}[, @var{n}] -Mark the beginning of @var{function}. An optional number may follow for -compatibility with the OSF/1 assembler, but is ignored. When generating -@code{.mdebug} information, this will create a procedure descriptor for -the function. In ELF, it will mark the symbol as a function a-la the -generic @code{.type} directive. - -@item .end @var{function} -Mark the end of @var{function}. In ELF, it will set the size of the symbol -a-la the generic @code{.size} directive. - -@item .mask @var{mask}, @var{offset} -Indicate which of the integer registers are saved in the current -function's stack frame. @var{mask} is interpreted a bit mask in which -bit @var{n} set indicates that register @var{n} is saved. The registers -are saved in a block located @var{offset} bytes from the @dfn{canonical -frame address} (CFA) which is the value of the stack pointer on entry to -the function. The registers are saved sequentially, except that the -return address register (normally @code{$26}) is saved first. - -This and the other directives that describe the stack frame are -currently only used when generating @code{.mdebug} information. They -may in the future be used to generate DWARF2 @code{.debug_frame} unwind -information for hand written assembly. - -@item .fmask @var{mask}, @var{offset} -Indicate which of the floating-point registers are saved in the current -stack frame. The @var{mask} and @var{offset} parameters are interpreted -as with @code{.mask}. - -@item .frame @var{framereg}, @var{frameoffset}, @var{retreg}[, @var{argoffset}] -Describes the shape of the stack frame. The frame pointer in use is -@var{framereg}; normally this is either @code{$fp} or @code{$sp}. The -frame pointer is @var{frameoffset} bytes below the CFA. The return -address is initially located in @var{retreg} until it is saved as -indicated in @code{.mask}. For compatibility with OSF/1 an optional -@var{argoffset} parameter is accepted and ignored. It is believed to -indicate the offset from the CFA to the saved argument registers. - -@item .prologue @var{n} -Indicate that the stack frame is set up and all registers have been -spilled. The argument @var{n} indicates whether and how the function -uses the incoming @dfn{procedure vector} (the address of the called -function) in @code{$27}. 0 indicates that @code{$27} is not used; 1 -indicates that the first two instructions of the function use @code{$27} -to perform a load of the GP register; 2 indicates that @code{$27} is -used in some non-standard way and so the linker cannot elide the load of -the procedure vector during relaxation. - -@item .usepv @var{function}, @var{which} -Used to indicate the use of the @code{$27} register, similar to -@code{.prologue}, but without the other semantics of needing to -be inside an open @code{.ent}/@code{.end} block. - -The @var{which} argument should be either @code{no}, indicating that -@code{$27} is not used, or @code{std}, indicating that the first two -instructions of the function perform a GP load. - -One might use this directive instead of @code{.prologue} if you are -also using dwarf2 CFI directives. - -@item .gprel32 @var{expression} -Computes the difference between the address in @var{expression} and the -GP for the current object file, and stores it in 4 bytes. In addition -to being smaller than a full 8 byte address, this also does not require -a dynamic relocation when used in a shared library. - -@item .t_floating @var{expression} -Stores @var{expression} as an @sc{ieee} double precision value. - -@item .s_floating @var{expression} -Stores @var{expression} as an @sc{ieee} single precision value. - -@item .f_floating @var{expression} -Stores @var{expression} as a VAX F format value. - -@item .g_floating @var{expression} -Stores @var{expression} as a VAX G format value. - -@item .d_floating @var{expression} -Stores @var{expression} as a VAX D format value. - -@item .set @var{feature} -Enables or disables various assembler features. Using the positive -name of the feature enables while using @samp{no@var{feature}} disables. - -@table @code -@item at -Indicates that macro expansions may clobber the @dfn{assembler -temporary} (@code{$at} or @code{$28}) register. Some macros may not be -expanded without this and will generate an error message if @code{noat} -is in effect. When @code{at} is in effect, a warning will be generated -if @code{$at} is used by the programmer. - -@item macro -Enables the expansion of macro instructions. Note that variants of real -instructions, such as @code{br label} vs @code{br $31,label} are -considered alternate forms and not macros. - -@item move -@itemx reorder -@itemx volatile -These control whether and how the assembler may re-order instructions. -Accepted for compatibility with the OSF/1 assembler, but @command{@value{AS}} -does not do instruction scheduling, so these features are ignored. -@end table -@end table - -The following directives are recognized for compatibility with the OSF/1 -assembler but are ignored. - -@example -.proc .aproc -.reguse .livereg -.option .aent -.ugen .eflag -.alias .noalias -@end example - -@node Alpha Opcodes -@section Opcodes -For detailed information on the Alpha machine instruction set, see the -@c Attempt to work around a very overfull hbox. -@iftex -Alpha Architecture Handbook located at -@smallfonts -@example -ftp://ftp.digital.com/pub/Digital/info/semiconductor/literature/alphaahb.pdf -@end example -@textfonts -@end iftex -@ifnottex -@uref{ftp://ftp.digital.com/pub/Digital/info/semiconductor/literature/alphaahb.pdf,Alpha Architecture Handbook}. -@end ifnottex diff --git a/contrib/binutils/gas/doc/c-arc.texi b/contrib/binutils/gas/doc/c-arc.texi deleted file mode 100644 index 700a01d15d8c0..0000000000000 --- a/contrib/binutils/gas/doc/c-arc.texi +++ /dev/null @@ -1,207 +0,0 @@ -@c Copyright 2000, 2001 Free Software Foundation, Inc. -@c This is part of the GAS manual. -@c For copying conditions, see the file as.texinfo. - -@ifset GENERIC -@page -@node ARC-Dependent -@chapter ARC Dependent Features -@end ifset - -@ifclear GENERIC -@node Machine Dependencies -@chapter ARC Dependent Features -@end ifclear - -@set ARC_CORE_DEFAULT 6 - -@cindex ARC support -@menu -* ARC Options:: Options -* ARC Syntax:: Syntax -* ARC Floating Point:: Floating Point -* ARC Directives:: ARC Machine Directives -* ARC Opcodes:: Opcodes -@end menu - - -@node ARC Options -@section Options -@cindex ARC options (none) -@cindex options for ARC (none) - -@table @code - -@cindex @code{-marc[5|6|7|8]} command line option, ARC -@item -marc[5|6|7|8] -This option selects the core processor variant. Using -@code{-marc} is the same as @code{-marc@value{ARC_CORE_DEFAULT}}, which -is also the default. - -@table @code - -@cindex @code{arc5} arc5, ARC -@item arc5 -Base instruction set. - -@cindex @code{arc6} arc6, ARC -@item arc6 -Jump-and-link (jl) instruction. No requirement of an instruction between -setting flags and conditional jump. For example: - -@smallexample - mov.f r0,r1 - beq foo -@end smallexample - -@cindex @code{arc7} arc7, ARC -@item arc7 -Break (brk) and sleep (sleep) instructions. - -@cindex @code{arc8} arc8, ARC -@item arc8 -Software interrupt (swi) instruction. - -@end table - -Note: the @code{.option} directive can to be used to select a core -variant from within assembly code. - -@cindex @code{-EB} command line option, ARC -@item -EB -This option specifies that the output generated by the assembler should -be marked as being encoded for a big-endian processor. - -@cindex @code{-EL} command line option, ARC -@item -EL -This option specifies that the output generated by the assembler should -be marked as being encoded for a little-endian processor - this is the -default. - -@end table - - -@node ARC Syntax -@section Syntax -@menu -* ARC-Chars:: Special Characters -* ARC-Regs:: Register Names -@end menu - -@node ARC-Chars -@subsection Special Characters - -@cindex ARC special characters -@cindex special characters, ARC -*TODO* - -@node ARC-Regs -@subsection Register Names - -@cindex ARC register names -@cindex register names, ARC -*TODO* - - -@node ARC Floating Point -@section Floating Point - -@cindex floating point, ARC (@sc{ieee}) -@cindex ARC floating point (@sc{ieee}) -The ARC core does not currently have hardware floating point -support. Software floating point support is provided by @code{GCC} -and uses @sc{ieee} floating-point numbers. - - -@node ARC Directives -@section ARC Machine Directives - -@cindex machine directives, ARC -@cindex ARC machine directives -The ARC version of @code{@value{AS}} supports the following additional -machine directives: - -@table @code - -@cindex @code{2byte} directive, ARC -@item .2byte @var{expressions} -*TODO* - -@cindex @code{3byte} directive, ARC -@item .3byte @var{expressions} -*TODO* - -@cindex @code{4byte} directive, ARC -@item .4byte @var{expressions} -*TODO* - -@cindex @code{extAuxRegister} directive, ARC -@item .extAuxRegister @var{name},@var{address},@var{mode} -*TODO* - -@smallexample - .extAuxRegister mulhi,0x12,w -@end smallexample - -@cindex @code{extCondCode} directive, ARC -@item .extCondCode @var{suffix},@var{value} -*TODO* - -@smallexample - .extCondCode is_busy,0x14 -@end smallexample - -@cindex @code{extCoreRegister} directive, ARC -@item .extCoreRegister @var{name},@var{regnum},@var{mode},@var{shortcut} -*TODO* - -@smallexample - .extCoreRegister mlo,57,r,can_shortcut -@end smallexample - -@cindex @code{extInstruction} directive, ARC -@item .extInstruction @var{name},@var{opcode},@var{subopcode},@var{suffixclass},@var{syntaxclass} -*TODO* - -@smallexample - .extInstruction mul64,0x14,0x0,SUFFIX_COND,SYNTAX_3OP|OP1_MUST_BE_IMM -@end smallexample - -@cindex @code{half} directive, ARC -@item .half @var{expressions} -*TODO* - -@cindex @code{long} directive, ARC -@item .long @var{expressions} -*TODO* - -@cindex @code{option} directive, ARC -@item .option @var{arc|arc5|arc6|arc7|arc8} -The @code{.option} directive must be followed by the desired core -version. Again @code{arc} is an alias for -@code{arc@value{ARC_CORE_DEFAULT}}. - -Note: the @code{.option} directive overrides the command line option -@code{-marc}; a warning is emitted when the version is not consistent -between the two - even for the implicit default core version -(arc@value{ARC_CORE_DEFAULT}). - -@cindex @code{short} directive, ARC -@item .short @var{expressions} -*TODO* - -@cindex @code{word} directive, ARC -@item .word @var{expressions} -*TODO* - -@end table - - -@node ARC Opcodes -@section Opcodes - -@cindex ARC opcodes -@cindex opcodes for ARC - -For information on the ARC instruction set, see @cite{ARC Programmers -Reference Manual}, ARC Cores Ltd. diff --git a/contrib/binutils/gas/doc/c-arm.texi b/contrib/binutils/gas/doc/c-arm.texi deleted file mode 100644 index 23cd7bb3fef61..0000000000000 --- a/contrib/binutils/gas/doc/c-arm.texi +++ /dev/null @@ -1,490 +0,0 @@ -@c Copyright 1996, 1997, 1998, 1999, 2000, 2001, 2003 -@c Free Software Foundation, Inc. -@c This is part of the GAS manual. -@c For copying conditions, see the file as.texinfo. - -@ifset GENERIC -@page -@node ARM-Dependent -@chapter ARM Dependent Features -@end ifset - -@ifclear GENERIC -@node Machine Dependencies -@chapter ARM Dependent Features -@end ifclear - -@cindex ARM support -@cindex Thumb support -@menu -* ARM Options:: Options -* ARM Syntax:: Syntax -* ARM Floating Point:: Floating Point -* ARM Directives:: ARM Machine Directives -* ARM Opcodes:: Opcodes -* ARM Mapping Symbols:: Mapping Symbols -@end menu - -@node ARM Options -@section Options -@cindex ARM options (none) -@cindex options for ARM (none) - -@table @code - -@cindex @code{-mcpu=} command line option, ARM -@item -mcpu=@var{processor}[+@var{extension}@dots{}] -This option specifies the target processor. The assembler will issue an -error message if an attempt is made to assemble an instruction which -will not execute on the target processor. The following processor names are -recognized: -@code{arm1}, -@code{arm2}, -@code{arm250}, -@code{arm3}, -@code{arm6}, -@code{arm60}, -@code{arm600}, -@code{arm610}, -@code{arm620}, -@code{arm7}, -@code{arm7m}, -@code{arm7d}, -@code{arm7dm}, -@code{arm7di}, -@code{arm7dmi}, -@code{arm70}, -@code{arm700}, -@code{arm700i}, -@code{arm710}, -@code{arm710t}, -@code{arm720}, -@code{arm720t}, -@code{arm740t}, -@code{arm710c}, -@code{arm7100}, -@code{arm7500}, -@code{arm7500fe}, -@code{arm7t}, -@code{arm7tdmi}, -@code{arm8}, -@code{arm810}, -@code{strongarm}, -@code{strongarm1}, -@code{strongarm110}, -@code{strongarm1100}, -@code{strongarm1110}, -@code{arm9}, -@code{arm920}, -@code{arm920t}, -@code{arm922t}, -@code{arm940t}, -@code{arm9tdmi}, -@code{arm9e}, -@code{arm926e}, -@code{arm926ejs}, -@code{arm946e-r0}, -@code{arm946e}, -@code{arm966e-r0}, -@code{arm966e}, -@code{arm10t}, -@code{arm10e}, -@code{arm1020}, -@code{arm1020t}, -@code{arm1020e}, -@code{arm1026ejs}, -@code{arm1136js}, -@code{arm1136jfs}, -@code{ep9312} (ARM920 with Cirrus Maverick coprocessor), -@code{i80200} (Intel XScale processor) -@code{iwmmxt} (Intel(r) XScale processor with Wireless MMX(tm) technology coprocessor) -and -@code{xscale}. -The special name @code{all} may be used to allow the -assembler to accept instructions valid for any ARM processor. - -In addition to the basic instruction set, the assembler can be told to -accept various extension mnemonics that extend the processor using the -co-processor instruction space. For example, @code{-mcpu=arm920+maverick} -is equivalent to specifying @code{-mcpu=ep9312}. The following extensions -are currently supported: -@code{+maverick} -@code{+iwmmxt} -and -@code{+xscale}. - -@cindex @code{-march=} command line option, ARM -@item -march=@var{architecture}[+@var{extension}@dots{}] -This option specifies the target architecture. The assembler will issue -an error message if an attempt is made to assemble an instruction which -will not execute on the target architecture. The following architecture -names are recognized: -@code{armv1}, -@code{armv2}, -@code{armv2a}, -@code{armv2s}, -@code{armv3}, -@code{armv3m}, -@code{armv4}, -@code{armv4xm}, -@code{armv4t}, -@code{armv4txm}, -@code{armv5}, -@code{armv5t}, -@code{armv5txm}, -@code{armv5te}, -@code{armv5texp}, -@code{armv6}, -@code{armv6j}, -@code{iwmmxt} -and -@code{xscale}. -If both @code{-mcpu} and -@code{-march} are specified, the assembler will use -the setting for @code{-mcpu}. - -The architecture option can be extended with the same instruction set -extension options as the @code{-mcpu} option. - -@cindex @code{-mfpu=} command line option, ARM -@item -mfpu=@var{floating-point-format} - -This option specifies the floating point format to assemble for. The -assembler will issue an error message if an attempt is made to assemble -an instruction which will not execute on the target floating point unit. -The following format options are recognized: -@code{softfpa}, -@code{fpe}, -@code{fpe2}, -@code{fpe3}, -@code{fpa}, -@code{fpa10}, -@code{fpa11}, -@code{arm7500fe}, -@code{softvfp}, -@code{softvfp+vfp}, -@code{vfp}, -@code{vfp10}, -@code{vfp10-r0}, -@code{vfp9}, -@code{vfpxd}, -@code{arm1020t}, -@code{arm1020e}, -@code{arm1136jfs} -and -@code{maverick}. - -In addition to determining which instructions are assembled, this option -also affects the way in which the @code{.double} assembler directive behaves -when assembling little-endian code. - -The default is dependent on the processor selected. For Architecture 5 or -later, the default is to assembler for VFP instructions; for earlier -architectures the default is to assemble for FPA instructions. - -@cindex @code{-mthumb} command line option, ARM -@item -mthumb -This option specifies that the assembler should start assembling Thumb -instructions; that is, it should behave as though the file starts with a -@code{.code 16} directive. - -@cindex @code{-mthumb-interwork} command line option, ARM -@item -mthumb-interwork -This option specifies that the output generated by the assembler should -be marked as supporting interworking. - -@cindex @code{-mapcs} command line option, ARM -@item -mapcs @code{[26|32]} -This option specifies that the output generated by the assembler should -be marked as supporting the indicated version of the Arm Procedure. -Calling Standard. - -@cindex @code{-matpcs} command line option, ARM -@item -matpcs -This option specifies that the output generated by the assembler should -be marked as supporting the Arm/Thumb Procedure Calling Standard. If -enabled this option will cause the assembler to create an empty -debugging section in the object file called .arm.atpcs. Debuggers can -use this to determine the ABI being used by. - -@cindex @code{-mapcs-float} command line option, ARM -@item -mapcs-float -This indicates the floating point variant of the APCS should be -used. In this variant floating point arguments are passed in FP -registers rather than integer registers. - -@cindex @code{-mapcs-reentrant} command line option, ARM -@item -mapcs-reentrant -This indicates that the reentrant variant of the APCS should be used. -This variant supports position independent code. - -@cindex @code{-mfloat-abi=} command line option, ARM -@item -mfloat-abi=@var{abi} -This option specifies that the output generated by the assembler should be -marked as using specified floating point ABI. -The following values are recognized: -@code{soft}, -@code{softfp} -and -@code{hard}. - -@cindex @code{-EB} command line option, ARM -@item -EB -This option specifies that the output generated by the assembler should -be marked as being encoded for a big-endian processor. - -@cindex @code{-EL} command line option, ARM -@item -EL -This option specifies that the output generated by the assembler should -be marked as being encoded for a little-endian processor. - -@cindex @code{-k} command line option, ARM -@cindex PIC code generation for ARM -@item -k -This option specifies that the output of the assembler should be marked -as position-independent code (PIC). - -@cindex @code{-moabi} command line option, ARM -@item -moabi -This indicates that the code should be assembled using the old ARM ELF -conventions, based on a beta release release of the ARM-ELF -specifications, rather than the default conventions which are based on -the final release of the ARM-ELF specifications. - -@end table - - -@node ARM Syntax -@section Syntax -@menu -* ARM-Chars:: Special Characters -* ARM-Regs:: Register Names -@end menu - -@node ARM-Chars -@subsection Special Characters - -@cindex line comment character, ARM -@cindex ARM line comment character -The presence of a @samp{@@} on a line indicates the start of a comment -that extends to the end of the current line. If a @samp{#} appears as -the first character of a line, the whole line is treated as a comment. - -@cindex line separator, ARM -@cindex statement separator, ARM -@cindex ARM line separator -The @samp{;} character can be used instead of a newline to separate -statements. - -@cindex immediate character, ARM -@cindex ARM immediate character -Either @samp{#} or @samp{$} can be used to indicate immediate operands. - -@cindex identifiers, ARM -@cindex ARM identifiers -*TODO* Explain about /data modifier on symbols. - -@node ARM-Regs -@subsection Register Names - -@cindex ARM register names -@cindex register names, ARM -*TODO* Explain about ARM register naming, and the predefined names. - -@node ARM Floating Point -@section Floating Point - -@cindex floating point, ARM (@sc{ieee}) -@cindex ARM floating point (@sc{ieee}) -The ARM family uses @sc{ieee} floating-point numbers. - - - -@node ARM Directives -@section ARM Machine Directives - -@cindex machine directives, ARM -@cindex ARM machine directives -@table @code - -@cindex @code{align} directive, ARM -@item .align @var{expression} [, @var{expression}] -This is the generic @var{.align} directive. For the ARM however if the -first argument is zero (ie no alignment is needed) the assembler will -behave as if the argument had been 2 (ie pad to the next four byte -boundary). This is for compatibility with ARM's own assembler. - -@cindex @code{req} directive, ARM -@item @var{name} .req @var{register name} -This creates an alias for @var{register name} called @var{name}. For -example: - -@smallexample - foo .req r0 -@end smallexample - -@cindex @code{unreq} directive, ARM -@item .unreq @var{alias-name} -This undefines a register alias which was previously defined using the -@code{req} directive. For example: - -@smallexample - foo .req r0 - .unreq foo -@end smallexample - -An error occurs if the name is undefined. Note - this pseudo op can -be used to delete builtin in register name aliases (eg 'r0'). This -should only be done if it is really necessary. - -@cindex @code{code} directive, ARM -@item .code @code{[16|32]} -This directive selects the instruction set being generated. The value 16 -selects Thumb, with the value 32 selecting ARM. - -@cindex @code{thumb} directive, ARM -@item .thumb -This performs the same action as @var{.code 16}. - -@cindex @code{arm} directive, ARM -@item .arm -This performs the same action as @var{.code 32}. - -@cindex @code{force_thumb} directive, ARM -@item .force_thumb -This directive forces the selection of Thumb instructions, even if the -target processor does not support those instructions - -@cindex @code{thumb_func} directive, ARM -@item .thumb_func -This directive specifies that the following symbol is the name of a -Thumb encoded function. This information is necessary in order to allow -the assembler and linker to generate correct code for interworking -between Arm and Thumb instructions and should be used even if -interworking is not going to be performed. The presence of this -directive also implies @code{.thumb} - -@cindex @code{thumb_set} directive, ARM -@item .thumb_set -This performs the equivalent of a @code{.set} directive in that it -creates a symbol which is an alias for another symbol (possibly not yet -defined). This directive also has the added property in that it marks -the aliased symbol as being a thumb function entry point, in the same -way that the @code{.thumb_func} directive does. - -@cindex @code{.ltorg} directive, ARM -@item .ltorg -This directive causes the current contents of the literal pool to be -dumped into the current section (which is assumed to be the .text -section) at the current location (aligned to a word boundary). -@code{GAS} maintains a separate literal pool for each section and each -sub-section. The @code{.ltorg} directive will only affect the literal -pool of the current section and sub-section. At the end of assembly -all remaining, un-empty literal pools will automatically be dumped. - -Note - older versions of @code{GAS} would dump the current literal -pool any time a section change occurred. This is no longer done, since -it prevents accurate control of the placement of literal pools. - -@cindex @code{.pool} directive, ARM -@item .pool -This is a synonym for .ltorg. - -@end table - -@node ARM Opcodes -@section Opcodes - -@cindex ARM opcodes -@cindex opcodes for ARM -@code{@value{AS}} implements all the standard ARM opcodes. It also -implements several pseudo opcodes, including several synthetic load -instructions. - -@table @code - -@cindex @code{NOP} pseudo op, ARM -@item NOP -@smallexample - nop -@end smallexample - -This pseudo op will always evaluate to a legal ARM instruction that does -nothing. Currently it will evaluate to MOV r0, r0. - -@cindex @code{LDR reg,=<label>} pseudo op, ARM -@item LDR -@smallexample - ldr <register> , = <expression> -@end smallexample - -If expression evaluates to a numeric constant then a MOV or MVN -instruction will be used in place of the LDR instruction, if the -constant can be generated by either of these instructions. Otherwise -the constant will be placed into the nearest literal pool (if it not -already there) and a PC relative LDR instruction will be generated. - -@cindex @code{ADR reg,<label>} pseudo op, ARM -@item ADR -@smallexample - adr <register> <label> -@end smallexample - -This instruction will load the address of @var{label} into the indicated -register. The instruction will evaluate to a PC relative ADD or SUB -instruction depending upon where the label is located. If the label is -out of range, or if it is not defined in the same file (and section) as -the ADR instruction, then an error will be generated. This instruction -will not make use of the literal pool. - -@cindex @code{ADRL reg,<label>} pseudo op, ARM -@item ADRL -@smallexample - adrl <register> <label> -@end smallexample - -This instruction will load the address of @var{label} into the indicated -register. The instruction will evaluate to one or two PC relative ADD -or SUB instructions depending upon where the label is located. If a -second instruction is not needed a NOP instruction will be generated in -its place, so that this instruction is always 8 bytes long. - -If the label is out of range, or if it is not defined in the same file -(and section) as the ADRL instruction, then an error will be generated. -This instruction will not make use of the literal pool. - -@end table - -For information on the ARM or Thumb instruction sets, see @cite{ARM -Software Development Toolkit Reference Manual}, Advanced RISC Machines -Ltd. - -@node ARM Mapping Symbols -@section Mapping Symbols - -The ARM ELF specification requires that special symbols be inserted -into object files to mark certain features: - -@table @code - -@cindex @code{$a} -@item $a -At the start of a region of code containing ARM instructions. - -@cindex @code{$t} -@item $t -At the start of a region of code containing THUMB instructions. - -@cindex @code{$d} -@item $d -At the start of a region of data. - -@end table - -The assembler will automatically insert these symbols for you - there -is no need to code them yourself. Support for tagging symbols ($b, -$f, $p and $m) which is also mentioned in the current ARM ELF -specification is not implemented. This is because they have been -dropped from the new EABI and so tools cannot rely upon their -presence. - diff --git a/contrib/binutils/gas/doc/c-i386.texi b/contrib/binutils/gas/doc/c-i386.texi deleted file mode 100644 index f0047f93825a0..0000000000000 --- a/contrib/binutils/gas/doc/c-i386.texi +++ /dev/null @@ -1,755 +0,0 @@ -@c Copyright 1991, 1992, 1993, 1994, 1995, 1997, 1998, 1999, 2000, 2001 -@c Free Software Foundation, Inc. -@c This is part of the GAS manual. -@c For copying conditions, see the file as.texinfo. -@ifset GENERIC -@page -@node i386-Dependent -@chapter 80386 Dependent Features -@end ifset -@ifclear GENERIC -@node Machine Dependencies -@chapter 80386 Dependent Features -@end ifclear - -@cindex i386 support -@cindex i80306 support -@cindex x86-64 support - -The i386 version @code{@value{AS}} supports both the original Intel 386 -architecture in both 16 and 32-bit mode as well as AMD x86-64 architecture -extending the Intel architecture to 64-bits. - -@menu -* i386-Options:: Options -* i386-Syntax:: AT&T Syntax versus Intel Syntax -* i386-Mnemonics:: Instruction Naming -* i386-Regs:: Register Naming -* i386-Prefixes:: Instruction Prefixes -* i386-Memory:: Memory References -* i386-Jumps:: Handling of Jump Instructions -* i386-Float:: Floating Point -* i386-SIMD:: Intel's MMX and AMD's 3DNow! SIMD Operations -* i386-16bit:: Writing 16-bit Code -* i386-Arch:: Specifying an x86 CPU architecture -* i386-Bugs:: AT&T Syntax bugs -* i386-Notes:: Notes -@end menu - -@node i386-Options -@section Options - -@cindex options for i386 -@cindex options for x86-64 -@cindex i386 options -@cindex x86-64 options - -The i386 version of @code{@value{AS}} has a few machine -dependent options: - -@table @code -@cindex @samp{--32} option, i386 -@cindex @samp{--32} option, x86-64 -@cindex @samp{--64} option, i386 -@cindex @samp{--64} option, x86-64 -@item --32 | --64 -Select the word size, either 32 bits or 64 bits. Selecting 32-bit -implies Intel i386 architecture, while 64-bit implies AMD x86-64 -architecture. - -These options are only available with the ELF object file format, and -require that the necessary BFD support has been included (on a 32-bit -platform you have to add --enable-64-bit-bfd to configure enable 64-bit -usage and use x86-64 as target platform). - -@item -n -By default, x86 GAS replaces multiple nop instructions used for -alignment within code sections with multi-byte nop instructions such -as leal 0(%esi,1),%esi. This switch disables the optimization. -@end table - -@node i386-Syntax -@section AT&T Syntax versus Intel Syntax - -@cindex i386 intel_syntax pseudo op -@cindex intel_syntax pseudo op, i386 -@cindex i386 att_syntax pseudo op -@cindex att_syntax pseudo op, i386 -@cindex i386 syntax compatibility -@cindex syntax compatibility, i386 -@cindex x86-64 intel_syntax pseudo op -@cindex intel_syntax pseudo op, x86-64 -@cindex x86-64 att_syntax pseudo op -@cindex att_syntax pseudo op, x86-64 -@cindex x86-64 syntax compatibility -@cindex syntax compatibility, x86-64 - -@code{@value{AS}} now supports assembly using Intel assembler syntax. -@code{.intel_syntax} selects Intel mode, and @code{.att_syntax} switches -back to the usual AT&T mode for compatibility with the output of -@code{@value{GCC}}. Either of these directives may have an optional -argument, @code{prefix}, or @code{noprefix} specifying whether registers -require a @samp{%} prefix. AT&T System V/386 assembler syntax is quite -different from Intel syntax. We mention these differences because -almost all 80386 documents use Intel syntax. Notable differences -between the two syntaxes are: - -@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 - -@cindex immediate operands, x86-64 -@cindex x86-64 immediate operands -@cindex register operands, x86-64 -@cindex x86-64 register operands -@cindex jump/call operands, x86-64 -@cindex x86-64 jump/call operands -@cindex operand delimiters, x86-64 -@itemize @bullet -@item -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. - -@cindex i386 source, destination operands -@cindex source, destination operands; i386 -@cindex x86-64 source, destination operands -@cindex source, destination operands; x86-64 -@item -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. Note that instructions with more than one -source operand, such as the @samp{enter} instruction, do @emph{not} have -reversed order. @ref{i386-Bugs}. - -@cindex mnemonic suffixes, i386 -@cindex sizes operands, i386 -@cindex i386 size suffixes -@cindex mnemonic suffixes, x86-64 -@cindex sizes operands, x86-64 -@cindex x86-64 size suffixes -@item -In AT&T syntax the size of memory operands is determined from the last -character of the instruction mnemonic. Mnemonic suffixes of @samp{b}, -@samp{w}, @samp{l} and @samp{q} specify byte (8-bit), word (16-bit), long -(32-bit) and quadruple word (64-bit) memory references. Intel syntax accomplishes -this by prefixing memory operands (@emph{not} the instruction mnemonics) with -@samp{byte ptr}, @samp{word ptr}, @samp{dword ptr} and @samp{qword ptr}. Thus, -Intel @samp{mov al, byte ptr @var{foo}} is @samp{movb @var{foo}, %al} in AT&T -syntax. - -@cindex return instructions, i386 -@cindex i386 jump, call, return -@cindex return instructions, x86-64 -@cindex x86-64 jump, call, return -@item -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}}. - -@cindex sections, i386 -@cindex i386 sections -@cindex sections, x86-64 -@cindex x86-64 sections -@item -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-Mnemonics -@section Instruction Naming - -@cindex i386 instruction naming -@cindex instruction naming, i386 -@cindex x86-64 instruction naming -@cindex instruction naming, x86-64 - -Instruction mnemonics are suffixed with one character modifiers which -specify the size of operands. The letters @samp{b}, @samp{w}, @samp{l} -and @samp{q} specify byte, word, long and quadruple word operands. If -no suffix is specified by an instruction then @code{@value{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 mnemonic suffix implies long -operand size. (This incompatibility does not affect compiler output -since compilers always explicitly specify the mnemonic suffix.) - -Almost all instructions 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 instruction mnemonic 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 instruction mnemonic 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), -@samp{wl} (from word to long), @samp{bq} (from byte to quadruple word), -@samp{wq} (from word to quadruple word), and @samp{lq} (from long to -quadruple word). - -@cindex conversion instructions, i386 -@cindex i386 conversion instructions -@cindex conversion instructions, x86-64 -@cindex x86-64 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}, - -@item -@samp{cdqe} --- sign-extend dword in @samp{%eax} to quad in @samp{%rax} -(x86-64 only), - -@item -@samp{cdo} --- sign-extend quad in @samp{%rax} to octuple in -@samp{%rdx:%rax} (x86-64 only), -@end itemize - -@noindent -are called @samp{cbtw}, @samp{cwtl}, @samp{cwtd}, @samp{cltd}, @samp{cltq}, and -@samp{cqto} in AT&T naming. @code{@value{AS}} accepts either naming for these -instructions. - -@cindex jump instructions, i386 -@cindex call instructions, i386 -@cindex jump instructions, x86-64 -@cindex call instructions, x86-64 -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 -@section Register Naming - -@cindex i386 registers -@cindex registers, i386 -@cindex x86-64 registers -@cindex registers, x86-64 -Register operands are always prefixed 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)}. -These registers are overloaded by 8 MMX registers @samp{%mm0}, -@samp{%mm1}, @samp{%mm2}, @samp{%mm3}, @samp{%mm4}, @samp{%mm5}, -@samp{%mm6} and @samp{%mm7}. - -@item -the 8 SSE registers registers @samp{%xmm0}, @samp{%xmm1}, @samp{%xmm2}, -@samp{%xmm3}, @samp{%xmm4}, @samp{%xmm5}, @samp{%xmm6} and @samp{%xmm7}. -@end itemize - -The AMD x86-64 architecture extends the register set by: - -@itemize @bullet -@item -enhancing the 8 32-bit registers to 64-bit: @samp{%rax} (the -accumulator), @samp{%rbx}, @samp{%rcx}, @samp{%rdx}, @samp{%rdi}, -@samp{%rsi}, @samp{%rbp} (the frame pointer), @samp{%rsp} (the stack -pointer) - -@item -the 8 extended registers @samp{%r8}--@samp{%r15}. - -@item -the 8 32-bit low ends of the extended registers: @samp{%r8d}--@samp{%r15d} - -@item -the 8 16-bit low ends of the extended registers: @samp{%r8w}--@samp{%r15w} - -@item -the 8 8-bit low ends of the extended registers: @samp{%r8b}--@samp{%r15b} - -@item -the 4 8-bit registers: @samp{%sil}, @samp{%dil}, @samp{%bpl}, @samp{%spl}. - -@item -the 8 debug registers: @samp{%db8}--@samp{%db15}. - -@item -the 8 SSE registers: @samp{%xmm8}--@samp{%xmm15}. -@end itemize - -@node i386-Prefixes -@section Instruction Prefixes - -@cindex i386 instruction prefixes -@cindex instruction prefixes, i386 -@cindex prefixes, i386 -Instruction prefixes are used to modify the following instruction. They -are used to repeat string instructions, to provide section overrides, to -perform bus lock operations, and to change operand and address sizes. -(Most instructions that normally operate on 32-bit operands will use -16-bit operands if the instruction has an ``operand size'' prefix.) -Instruction prefixes are best written on the same line as the instruction -they act upon. For example, the @samp{scas} (scan string) instruction is -repeated with: - -@smallexample - repne scas %es:(%edi),%al -@end smallexample - -You may also place prefixes on the lines immediately preceding the -instruction, but this circumvents checks that @code{@value{AS}} does -with prefixes, and will not work with all prefixes. - -Here is a list of instruction prefixes: - -@cindex section override prefixes, i386 -@itemize @bullet -@item -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. - -@cindex size prefixes, i386 -@item -Operand/Address size prefixes @samp{data16} and @samp{addr16} -change 32-bit operands/addresses into 16-bit operands/addresses, -while @samp{data32} and @samp{addr32} change 16-bit ones (in a -@code{.code16} section) into 32-bit operands/addresses. These prefixes -@emph{must} appear on the same line of code as the instruction they -modify. For example, in a 16-bit @code{.code16} section, you might -write: - -@smallexample - addr32 jmpl *(%ebx) -@end smallexample - -@cindex bus lock prefixes, i386 -@cindex inhibiting interrupts, i386 -@item -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). - -@cindex coprocessor wait, i386 -@item -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. - -@cindex repeat prefixes, i386 -@item -The @samp{rep}, @samp{repe}, and @samp{repne} prefixes are added -to string instructions to make them repeat @samp{%ecx} times (@samp{%cx} -times if the current address size is 16-bits). -@cindex REX prefixes, i386 -@item -The @samp{rex} family of prefixes is used by x86-64 to encode -extensions to i386 instruction set. The @samp{rex} prefix has four -bits --- an operand size overwrite (@code{64}) used to change operand size -from 32-bit to 64-bit and X, Y and Z extensions bits used to extend the -register set. - -You may write the @samp{rex} prefixes directly. The @samp{rex64xyz} -instruction emits @samp{rex} prefix with all the bits set. By omitting -the @code{64}, @code{x}, @code{y} or @code{z} you may write other -prefixes as well. Normally, there is no need to write the prefixes -explicitly, since gas will automatically generate them based on the -instruction operands. -@end itemize - -@node i386-Memory -@section Memory References - -@cindex i386 memory references -@cindex memory references, i386 -@cindex x86-64 memory references -@cindex memory references, x86-64 -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} -be preceded by a @samp{%}. If you specify a section override which -coincides with the default section register, @code{@value{AS}} does @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{@value{AS}} -always chooses PC relative addressing for jump/call labels. - -Any instruction that has a memory operand, but no register operand, -@emph{must} specify its size (byte, word, long, or quadruple) with an -instruction mnemonic suffix (@samp{b}, @samp{w}, @samp{l} or @samp{q}, -respectively). - -The x86-64 architecture adds an RIP (instruction pointer relative) -addressing. This addressing mode is specified by using @samp{rip} as a -base register. Only constant offsets are valid. For example: - -@table @asis -@item AT&T: @samp{1234(%rip)}, Intel: @samp{[rip + 1234]} -Points to the address 1234 bytes past the end of the current -instruction. - -@item AT&T: @samp{symbol(%rip)}, Intel: @samp{[rip + symbol]} -Points to the @code{symbol} in RIP relative way, this is shorter than -the default absolute addressing. -@end table - -Other addressing modes remain unchanged in x86-64 architecture, except -registers used are 64-bit instead of 32-bit. - -@node i386-Jumps -@section Handling of Jump Instructions - -@cindex jump optimization, i386 -@cindex i386 jump optimization -@cindex jump optimization, x86-64 -@cindex x86-64 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 displacement is used. We do not support -word (16-bit) displacement jumps in 32-bit mode (i.e. prefixing the jump -instruction with the @samp{data16} instruction prefix), since the 80386 -insists upon masking @samp{%eip} to 16 bits after the word displacement -is added. (See also @pxref{i386-Arch}) - -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 if you use these instructions (@code{@value{GCC}} does -not use them) you may get an error message (and 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 -@section Floating Point - -@cindex i386 floating point -@cindex floating point, i386 -@cindex x86-64 floating point -@cindex floating point, x86-64 -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 instruction mnemonic suffix and a constructor -associated with it. Instruction mnemonic suffixes specify the operand's -data type. Constructors build these data types into memory. - -@cindex @code{float} directive, i386 -@cindex @code{single} directive, i386 -@cindex @code{double} directive, i386 -@cindex @code{tfloat} directive, i386 -@cindex @code{float} directive, x86-64 -@cindex @code{single} directive, x86-64 -@cindex @code{double} directive, x86-64 -@cindex @code{tfloat} directive, x86-64 -@itemize @bullet -@item -Floating point constructors are @samp{.float} or @samp{.single}, -@samp{.double}, and @samp{.tfloat} for 32-, 64-, and 80-bit formats. -These correspond to instruction mnemonic suffixes @samp{s}, @samp{l}, -and @samp{t}. @samp{t} stands for 80-bit (ten byte) real. The 80387 -only supports this format via the @samp{fldt} (load 80-bit real to stack -top) and @samp{fstpt} (store 80-bit real and pop stack) instructions. - -@cindex @code{word} directive, i386 -@cindex @code{long} directive, i386 -@cindex @code{int} directive, i386 -@cindex @code{quad} directive, i386 -@cindex @code{word} directive, x86-64 -@cindex @code{long} directive, x86-64 -@cindex @code{int} directive, x86-64 -@cindex @code{quad} directive, x86-64 -@item -Integer constructors are @samp{.word}, @samp{.long} or @samp{.int}, and -@samp{.quad} for the 16-, 32-, and 64-bit integer formats. The -corresponding instruction mnemonic suffixes are @samp{s} (single), -@samp{l} (long), and @samp{q} (quad). As with the 80-bit 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 should not use instruction mnemonic suffixes. -@samp{fstl %st, %st(1)} will give a warning, and be assembled as if you -wrote @samp{fst %st, %st(1)}, since all register to register operations -use 80-bit floating point operands. (Contrast this with @samp{fstl %st, mem}, -which converts @samp{%st} from 80-bit to 64-bit floating point format, -then stores the result in the 4 byte location @samp{mem}) - -@node i386-SIMD -@section Intel's MMX and AMD's 3DNow! SIMD Operations - -@cindex MMX, i386 -@cindex 3DNow!, i386 -@cindex SIMD, i386 -@cindex MMX, x86-64 -@cindex 3DNow!, x86-64 -@cindex SIMD, x86-64 - -@code{@value{AS}} supports Intel's MMX instruction set (SIMD -instructions for integer data), available on Intel's Pentium MMX -processors and Pentium II processors, AMD's K6 and K6-2 processors, -Cyrix' M2 processor, and probably others. It also supports AMD's 3DNow! -instruction set (SIMD instructions for 32-bit floating point data) -available on AMD's K6-2 processor and possibly others in the future. - -Currently, @code{@value{AS}} does not support Intel's floating point -SIMD, Katmai (KNI). - -The eight 64-bit MMX operands, also used by 3DNow!, are called @samp{%mm0}, -@samp{%mm1}, ... @samp{%mm7}. They contain eight 8-bit integers, four -16-bit integers, two 32-bit integers, one 64-bit integer, or two 32-bit -floating point values. The MMX registers cannot be used at the same time -as the floating point stack. - -See Intel and AMD documentation, keeping in mind that the operand order in -instructions is reversed from the Intel syntax. - -@node i386-16bit -@section Writing 16-bit Code - -@cindex i386 16-bit code -@cindex 16-bit code, i386 -@cindex real-mode code, i386 -@cindex @code{code16gcc} directive, i386 -@cindex @code{code16} directive, i386 -@cindex @code{code32} directive, i386 -@cindex @code{code64} directive, i386 -@cindex @code{code64} directive, x86-64 -While @code{@value{AS}} normally writes only ``pure'' 32-bit i386 code -or 64-bit x86-64 code depending on the default configuration, -it also supports writing code to run in real mode or in 16-bit protected -mode code segments. To do this, put a @samp{.code16} or -@samp{.code16gcc} directive before the assembly language instructions to -be run in 16-bit mode. You can switch @code{@value{AS}} back to writing -normal 32-bit code with the @samp{.code32} directive. - -@samp{.code16gcc} provides experimental support for generating 16-bit -code from gcc, and differs from @samp{.code16} in that @samp{call}, -@samp{ret}, @samp{enter}, @samp{leave}, @samp{push}, @samp{pop}, -@samp{pusha}, @samp{popa}, @samp{pushf}, and @samp{popf} instructions -default to 32-bit size. This is so that the stack pointer is -manipulated in the same way over function calls, allowing access to -function parameters at the same stack offsets as in 32-bit mode. -@samp{.code16gcc} also automatically adds address size prefixes where -necessary to use the 32-bit addressing modes that gcc generates. - -The code which @code{@value{AS}} generates in 16-bit mode will not -necessarily run on a 16-bit pre-80386 processor. To write code that -runs on such a processor, you must refrain from using @emph{any} 32-bit -constructs which require @code{@value{AS}} to output address or operand -size prefixes. - -Note that writing 16-bit code instructions by explicitly specifying a -prefix or an instruction mnemonic suffix within a 32-bit code section -generates different machine instructions than those generated for a -16-bit code segment. In a 32-bit code section, the following code -generates the machine opcode bytes @samp{66 6a 04}, which pushes the -value @samp{4} onto the stack, decrementing @samp{%esp} by 2. - -@smallexample - pushw $4 -@end smallexample - -The same code in a 16-bit code section would generate the machine -opcode bytes @samp{6a 04} (ie. without the operand size prefix), which -is correct since the processor default operand size is assumed to be 16 -bits in a 16-bit code section. - -@node i386-Bugs -@section AT&T Syntax bugs - -The UnixWare assembler, and probably other AT&T derived ix86 Unix -assemblers, generate floating point instructions with reversed source -and destination registers in certain cases. Unfortunately, gcc and -possibly many other programs use this reversed syntax, so we're stuck -with it. - -For example - -@smallexample - fsub %st,%st(3) -@end smallexample -@noindent -results in @samp{%st(3)} being updated to @samp{%st - %st(3)} rather -than the expected @samp{%st(3) - %st}. This happens with all the -non-commutative arithmetic floating point operations with two register -operands where the source register is @samp{%st} and the destination -register is @samp{%st(i)}. - -@node i386-Arch -@section Specifying CPU Architecture - -@cindex arch directive, i386 -@cindex i386 arch directive -@cindex arch directive, x86-64 -@cindex x86-64 arch directive - -@code{@value{AS}} may be told to assemble for a particular CPU -architecture with the @code{.arch @var{cpu_type}} directive. This -directive enables a warning when gas detects an instruction that is not -supported on the CPU specified. The choices for @var{cpu_type} are: - -@multitable @columnfractions .20 .20 .20 .20 -@item @samp{i8086} @tab @samp{i186} @tab @samp{i286} @tab @samp{i386} -@item @samp{i486} @tab @samp{i586} @tab @samp{i686} @tab @samp{pentium} -@item @samp{pentiumpro} @tab @samp{pentium4} @tab @samp{k6} @tab @samp{athlon} -@item @samp{sledgehammer} -@end multitable - -Apart from the warning, there are only two other effects on -@code{@value{AS}} operation; Firstly, if you specify a CPU other than -@samp{i486}, then shift by one instructions such as @samp{sarl $1, %eax} -will automatically use a two byte opcode sequence. The larger three -byte opcode sequence is used on the 486 (and when no architecture is -specified) because it executes faster on the 486. Note that you can -explicitly request the two byte opcode by writing @samp{sarl %eax}. -Secondly, if you specify @samp{i8086}, @samp{i186}, or @samp{i286}, -@emph{and} @samp{.code16} or @samp{.code16gcc} then byte offset -conditional jumps will be promoted when necessary to a two instruction -sequence consisting of a conditional jump of the opposite sense around -an unconditional jump to the target. - -Following the CPU architecture, you may specify @samp{jumps} or -@samp{nojumps} to control automatic promotion of conditional jumps. -@samp{jumps} is the default, and enables jump promotion; All external -jumps will be of the long variety, and file-local jumps will be promoted -as necessary. (@pxref{i386-Jumps}) @samp{nojumps} leaves external -conditional jumps as byte offset jumps, and warns about file-local -conditional jumps that @code{@value{AS}} promotes. -Unconditional jumps are treated as for @samp{jumps}. - -For example - -@smallexample - .arch i8086,nojumps -@end smallexample - -@node i386-Notes -@section Notes - -@cindex i386 @code{mul}, @code{imul} instructions -@cindex @code{mul} instruction, i386 -@cindex @code{imul} instruction, i386 -@cindex @code{mul} instruction, x86-64 -@cindex @code{imul} instruction, x86-64 -There is some trickery concerning the @samp{mul} and @samp{imul} -instructions that deserves mention. The 16-, 32-, 64- and 128-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{@value{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}. - diff --git a/contrib/binutils/gas/doc/c-ia64.texi b/contrib/binutils/gas/doc/c-ia64.texi deleted file mode 100644 index b62c05eb88d0d..0000000000000 --- a/contrib/binutils/gas/doc/c-ia64.texi +++ /dev/null @@ -1,157 +0,0 @@ -@c Copyright 2002 -@c Free Software Foundation, Inc. -@c Contributed by David Mosberger-Tang <davidm@hpl.hp.com> -@c This is part of the GAS manual. -@c For copying conditions, see the file as.texinfo. - -@ifset GENERIC -@page -@node IA-64-Dependent -@chapter IA-64 Dependent Features -@end ifset - -@ifclear GENERIC -@node Machine Dependencies -@chapter IA-64 Dependent Features -@end ifclear - -@cindex IA-64 support -@menu -* IA-64 Options:: Options -* IA-64 Syntax:: Syntax -@c * IA-64 Floating Point:: Floating Point // to be written -@c * IA-64 Directives:: IA-64 Machine Directives // to be written -* IA-64 Opcodes:: Opcodes -@end menu - -@node IA-64 Options -@section Options -@cindex IA-64 options -@cindex options for IA-64 - -@table @option -@cindex @code{-mconstant-gp} command line option, IA-64 - -@item -mconstant-gp -This option instructs the assembler to mark the resulting object file -as using the ``constant GP'' model. With this model, it is assumed -that the entire program uses a single global pointer (GP) value. Note -that this option does not in any fashion affect the machine code -emitted by the assembler. All it does is turn on the EF_IA_64_CONS_GP -flag in the ELF file header. - -@item -mauto-pic -This option instructs the assembler to mark the resulting object file -as using the ``constant GP without function descriptor'' data model. -This model is like the ``constant GP'' model, except that it -additionally does away with function descriptors. What this means is -that the address of a function refers directly to the function's code -entry-point. Normally, such an address would refer to a function -descriptor, which contains both the code entry-point and the GP-value -needed by the function. Note that this option does not in any fashion -affect the machine code emitted by the assembler. All it does is -turn on the EF_IA_64_NOFUNCDESC_CONS_GP flag in the ELF file header. - -@item -milp32 -@item -milp64 -@item -mlp64 -@item -mp64 -These options select the data model. The assembler defaults to @code{-mlp64} -(LP64 data model). - -@item -mle -@item -mbe -These options select the byte order. The @code{-mle} option selects little-endian -byte order (default) and @code{-mbe} selects big-endian byte order. Note that -IA-64 machine code always uses little-endian byte order. - -@item -x -@item -xexplicit -These options turn on dependency violation checking. This checking is turned on by -default. - -@item -xauto -This option instructs the assembler to automatically insert stop bits where necessary -to remove dependency violations. - -@item -xdebug -This turns on debug output intended to help tracking down bugs in the dependency -violation checker. - -@end table - -@cindex IA-64 Syntax -@node IA-64 Syntax -@section Syntax -The assembler syntax closely follows the IA-64 Assembly Language -Reference Guide. - -@menu -* IA-64-Chars:: Special Characters -* IA-64-Regs:: Register Names -* IA-64-Bits:: Bit Names -* IA-64-Relocs:: Relocations -@end menu - -@node IA-64-Chars -@subsection Special Characters - -@cindex line comment character, IA-64 -@cindex IA-64 line comment character -@samp{//} is the line comment token. - -@cindex line separator, IA-64 -@cindex statement separator, IA-64 -@cindex IA-64 line separator -@samp{;} can be used instead of a newline to separate statements. - -@node IA-64-Regs -@subsection Register Names -@cindex IA-64 registers -@cindex register names, IA-64 - -The 128 integer registers are referred to as @samp{r@var{n}}. -The 128 floating-point registers are referred to as @samp{f@var{n}}. -The 128 application registers are referred to as @samp{ar@var{n}}. -The 128 control registers are referred to as @samp{cr@var{n}}. -The 64 one-bit predicate registers are referred to as @samp{p@var{n}}. -The 8 branch registers are referred to as @samp{b@var{n}}. -In addition, the assembler defines a number of aliases: -@samp{gp} (@samp{r1}), @samp{sp} (@samp{r12}), @samp{rp} (@samp{b0}), -@samp{ret0} (@samp{r8}), @samp{ret1} (@samp{r9}), @samp{ret2} (@samp{r10}), -@samp{ret3} (@samp{r9}), @samp{farg@var{n}} (@samp{f8+@var{n}}), and -@samp{fret@var{n}} (@samp{f8+@var{n}}). - -For convenience, the assembler also defines aliases for all named application -and control registers. For example, @samp{ar.bsp} refers to the register -backing store pointer (@samp{ar17}). Similarly, @samp{cr.eoi} refers to -the end-of-interrupt register (@samp{cr67}). - -@node IA-64-Bits -@subsection IA-64 Processor-Status-Register (PSR) Bit Names -@cindex IA-64 Processor-status-Register bit names -@cindex PSR bits -@cindex bit names, IA-64 - -The assembler defines bit masks for each of the bits in the IA-64 -processor status register. For example, @samp{psr.ic} corresponds to -a value of 0x2000. These masks are primarily intended for use with -the @sample{ssm}/@sample{sum} and @sample{rsm}/@sample{rum} -instructions, but they can be used anywhere else where an integer -constant is expected. - -@node IA-64 Opcodes -@section Opcodes -For detailed information on the IA-64 machine instruction set, see the -@c Attempt to work around a very overfull hbox. -@iftex -IA-64 Assembly Language Reference Guide available at -@smallfonts -@example -http://developer.intel.com/design/itanium/arch_spec.htm -@end example -@textfonts -@end iftex -@ifnottex -@uref{http://developer.intel.com/design/itanium/arch_spec.htm,IA-64 Architecture Handbook}. -@end ifnottex diff --git a/contrib/binutils/gas/doc/c-ppc.texi b/contrib/binutils/gas/doc/c-ppc.texi deleted file mode 100644 index be90e336f8bd3..0000000000000 --- a/contrib/binutils/gas/doc/c-ppc.texi +++ /dev/null @@ -1,126 +0,0 @@ -@c Copyright 2001, 2002 -@c Free Software Foundation, Inc. -@c This is part of the GAS manual. -@c For copying conditions, see the file as.texinfo. -@ifset GENERIC -@page -@node PPC-Dependent -@chapter PowerPC Dependent Features -@end ifset -@ifclear GENERIC -@node Machine Dependencies -@chapter PowerPC Dependent Features -@end ifclear - -@cindex PowerPC support -@menu -* PowerPC-Opts:: Options -* PowerPC-Pseudo:: PowerPC Assembler Directives -@end menu - -@node PowerPC-Opts -@section Options - -@cindex options for PowerPC -@cindex PowerPC options -@cindex architectures, PowerPC -@cindex PowerPC architectures -The PowerPC chip family includes several successive levels, using the same -core instruction set, but including a few additional instructions at -each level. There are exceptions to this however. For details on what -instructions each variant supports, please see the chip's architecture -reference manual. - -The following table lists all available PowerPC options. - -@table @code -@item -mpwrx | -mpwr2 -Generate code for POWER/2 (RIOS2). - -@item -mpwr -Generate code for POWER (RIOS1) - -@item -m601 -Generate code for PowerPC 601. - -@item -mppc, -mppc32, -m603, -m604 -Generate code for PowerPC 603/604. - -@item -m403, -m405 -Generate code for PowerPC 403/405. - -@item -m440 -Generate code for PowerPC 440. BookE and some 405 instructions. - -@item -m7400, -m7410, -m7450, -m7455 -Generate code for PowerPC 7400/7410/7450/7455. - -@item -mppc64, -m620 -Generate code for PowerPC 620/625/630. - -@item -mppc64bridge -Generate code for PowerPC 64, including bridge insns. - -@item -mbooke64 -Generate code for 64-bit BookE. - -@item -mbooke, mbooke32 -Generate code for 32-bit BookE. - -@item -maltivec -Generate code for processors with AltiVec instructions. - -@item -mpower4 -Generate code for Power4 architecture. - -@item -mcom -Generate code Power/PowerPC common instructions. - -@item -many -Generate code for any architecture (PWR/PWRX/PPC). - -@item -mregnames -Allow symbolic names for registers. - -@item -mno-regnames -Do not allow symbolic names for registers. - -@item -mrelocatable -Support for GCC's -mrelocatble option. - -@item -mrelocatable-lib -Support for GCC's -mrelocatble-lib option. - -@item -memb -Set PPC_EMB bit in ELF flags. - -@item -mlittle, -mlittle-endian -Generate code for a little endian machine. - -@item -mbig, -mbig-endian -Generate code for a big endian machine. - -@item -msolaris -Generate code for Solaris. - -@item -mno-solaris -Do not generate code for Solaris. -@end table - - -@node PowerPC-Pseudo -@section PowerPC Assembler Directives - -@cindex directives for PowerPC -@cindex PowerPC directives -A number of assembler directives are available for PowerPC. The -following table is far from complete. - -@table @code -@item .machine "string" -This directive allows you to change the machine for which code is -generated. @code{"string"} may be any of the -m cpu selection options -(without the -m) enclosed in double quotes, @code{"push"}, or -@code{"pop"}. @code{.machine "push"} saves the currently selected -cpu, which may be restored with @code{.machine "pop"}. -@end table diff --git a/contrib/binutils/gas/doc/c-sh.texi b/contrib/binutils/gas/doc/c-sh.texi deleted file mode 100644 index b08f325ee08e0..0000000000000 --- a/contrib/binutils/gas/doc/c-sh.texi +++ /dev/null @@ -1,327 +0,0 @@ -@c Copyright 1991, 1992, 1993, 1994, 1995, 1997, 2001, 2004 -@c Free Software Foundation, Inc. -@c This is part of the GAS manual. -@c For copying conditions, see the file as.texinfo. -@page -@node SH-Dependent -@chapter Renesas / SuperH SH Dependent Features - -@cindex SH support -@menu -* SH Options:: Options -* SH Syntax:: Syntax -* SH Floating Point:: Floating Point -* SH Directives:: SH Machine Directives -* SH Opcodes:: Opcodes -@end menu - -@node SH Options -@section Options - -@cindex SH options -@cindex options, SH -@code{@value{AS}} has following command-line options for the Renesas -(formerly Hitachi) / SuperH SH family. - -@table @code -@kindex -little -@kindex -big -@kindex -relax -@kindex -small -@kindex -dsp -@kindex -renesas - -@item -little -Generate little endian code. - -@item -big -Generate big endian code. - -@item -relax -Alter jump instructions for long displacements. - -@item -small -Align sections to 4 byte boundaries, not 16. - -@item -dsp -Enable sh-dsp insns, and disable sh3e / sh4 insns. - -@item -renesas -Disable optimization with section symbol for compatibility with -Renesas assembler. - -@item -isa=sh4 | sh4a -Specify the sh4 or sh4a instruction set. -@item -isa=dsp -Enable sh-dsp insns, and disable sh3e / sh4 insns. -@item -isa=fp -Enable sh2e, sh3e, sh4, and sh4a insn sets. -@item -isa=all -Enable sh1, sh2, sh2e, sh3, sh3e, sh4, sh4a, and sh-dsp insn sets. - -@end table - -@node SH Syntax -@section Syntax - -@menu -* SH-Chars:: Special Characters -* SH-Regs:: Register Names -* SH-Addressing:: Addressing Modes -@end menu - -@node SH-Chars -@subsection Special Characters - -@cindex line comment character, SH -@cindex SH line comment character -@samp{!} is the line comment character. - -@cindex line separator, SH -@cindex statement separator, SH -@cindex SH line separator -You can use @samp{;} instead of a newline to separate statements. - -@cindex symbol names, @samp{$} in -@cindex @code{$} in symbol names -Since @samp{$} has no special meaning, you may use it in symbol names. - -@node SH-Regs -@subsection Register Names - -@cindex SH registers -@cindex registers, SH -You can use the predefined symbols @samp{r0}, @samp{r1}, @samp{r2}, -@samp{r3}, @samp{r4}, @samp{r5}, @samp{r6}, @samp{r7}, @samp{r8}, -@samp{r9}, @samp{r10}, @samp{r11}, @samp{r12}, @samp{r13}, @samp{r14}, -and @samp{r15} to refer to the SH registers. - -The SH also has these control registers: - -@table @code -@item pr -procedure register (holds return address) - -@item pc -program counter - -@item mach -@itemx macl -high and low multiply accumulator registers - -@item sr -status register - -@item gbr -global base register - -@item vbr -vector base register (for interrupt vectors) -@end table - -@node SH-Addressing -@subsection Addressing Modes - -@cindex addressing modes, SH -@cindex SH addressing modes -@code{@value{AS}} understands the following addressing modes for the SH. -@code{R@var{n}} in the following refers to any of the numbered -registers, but @emph{not} the control registers. - -@table @code -@item R@var{n} -Register direct - -@item @@R@var{n} -Register indirect - -@item @@-R@var{n} -Register indirect with pre-decrement - -@item @@R@var{n}+ -Register indirect with post-increment - -@item @@(@var{disp}, R@var{n}) -Register indirect with displacement - -@item @@(R0, R@var{n}) -Register indexed - -@item @@(@var{disp}, GBR) -@code{GBR} offset - -@item @@(R0, GBR) -GBR indexed - -@item @var{addr} -@itemx @@(@var{disp}, PC) -PC relative address (for branch or for addressing memory). The -@code{@value{AS}} implementation allows you to use the simpler form -@var{addr} anywhere a PC relative address is called for; the alternate -form is supported for compatibility with other assemblers. - -@item #@var{imm} -Immediate data -@end table - -@node SH Floating Point -@section Floating Point - -@cindex floating point, SH (@sc{ieee}) -@cindex SH floating point (@sc{ieee}) -SH2E, SH3E and SH4 groups have on-chip floating-point unit (FPU). Other -SH groups can use @code{.float} directive to generate @sc{ieee} -floating-point numbers. - -SH2E and SH3E support single-precision floating point calculations as -well as entirely PCAPI compatible emulation of double-precision -floating point calculations. SH2E and SH3E instructions are a subset of -the floating point calculations conforming to the IEEE754 standard. - -In addition to single-precision and double-precision floating-point -operation capability, the on-chip FPU of SH4 has a 128-bit graphic -engine that enables 32-bit floating-point data to be processed 128 -bits at a time. It also supports 4 * 4 array operations and inner -product operations. Also, a superscalar architecture is employed that -enables simultaneous execution of two instructions (including FPU -instructions), providing performance of up to twice that of -conventional architectures at the same frequency. - -@node SH Directives -@section SH Machine Directives - -@cindex SH machine directives -@cindex machine directives, SH -@cindex @code{uaword} directive, SH -@cindex @code{ualong} directive, SH - -@table @code -@item uaword -@itemx ualong -@code{@value{AS}} will issue a warning when a misaligned @code{.word} or -@code{.long} directive is used. You may use @code{.uaword} or -@code{.ualong} to indicate that the value is intentionally misaligned. -@end table - -@node SH Opcodes -@section Opcodes - -@cindex SH opcode summary -@cindex opcode summary, SH -@cindex mnemonics, SH -@cindex instruction summary, SH -For detailed information on the SH machine instruction set, see -@cite{SH-Microcomputer User's Manual} (Renesas) or -@cite{SH-4 32-bit CPU Core Architecture} (SuperH) and -@cite{SuperH (SH) 64-Bit RISC Series} (SuperH). - -@code{@value{AS}} implements all the standard SH opcodes. No additional -pseudo-instructions are needed on this family. Note, however, that -because @code{@value{AS}} supports a simpler form of PC-relative -addressing, you may simply write (for example) - -@example -mov.l bar,r0 -@end example - -@noindent -where other assemblers might require an explicit displacement to -@code{bar} from the program counter: - -@example -mov.l @@(@var{disp}, PC) -@end example - -@ifset SMALL -@c this table, due to the multi-col faking and hardcoded order, looks silly -@c except in smallbook. See comments below "@set SMALL" near top of this file. - -Here is a summary of SH opcodes: - -@page -@smallexample -@i{Legend:} -Rn @r{a numbered register} -Rm @r{another numbered register} -#imm @r{immediate data} -disp @r{displacement} -disp8 @r{8-bit displacement} -disp12 @r{12-bit displacement} - -add #imm,Rn lds.l @@Rn+,PR -add Rm,Rn mac.w @@Rm+,@@Rn+ -addc Rm,Rn mov #imm,Rn -addv Rm,Rn mov Rm,Rn -and #imm,R0 mov.b Rm,@@(R0,Rn) -and Rm,Rn mov.b Rm,@@-Rn -and.b #imm,@@(R0,GBR) mov.b Rm,@@Rn -bf disp8 mov.b @@(disp,Rm),R0 -bra disp12 mov.b @@(disp,GBR),R0 -bsr disp12 mov.b @@(R0,Rm),Rn -bt disp8 mov.b @@Rm+,Rn -clrmac mov.b @@Rm,Rn -clrt mov.b R0,@@(disp,Rm) -cmp/eq #imm,R0 mov.b R0,@@(disp,GBR) -cmp/eq Rm,Rn mov.l Rm,@@(disp,Rn) -cmp/ge Rm,Rn mov.l Rm,@@(R0,Rn) -cmp/gt Rm,Rn mov.l Rm,@@-Rn -cmp/hi Rm,Rn mov.l Rm,@@Rn -cmp/hs Rm,Rn mov.l @@(disp,Rn),Rm -cmp/pl Rn mov.l @@(disp,GBR),R0 -cmp/pz Rn mov.l @@(disp,PC),Rn -cmp/str Rm,Rn mov.l @@(R0,Rm),Rn -div0s Rm,Rn mov.l @@Rm+,Rn -div0u mov.l @@Rm,Rn -div1 Rm,Rn mov.l R0,@@(disp,GBR) -exts.b Rm,Rn mov.w Rm,@@(R0,Rn) -exts.w Rm,Rn mov.w Rm,@@-Rn -extu.b Rm,Rn mov.w Rm,@@Rn -extu.w Rm,Rn mov.w @@(disp,Rm),R0 -jmp @@Rn mov.w @@(disp,GBR),R0 -jsr @@Rn mov.w @@(disp,PC),Rn -ldc Rn,GBR mov.w @@(R0,Rm),Rn -ldc Rn,SR mov.w @@Rm+,Rn -ldc Rn,VBR mov.w @@Rm,Rn -ldc.l @@Rn+,GBR mov.w R0,@@(disp,Rm) -ldc.l @@Rn+,SR mov.w R0,@@(disp,GBR) -ldc.l @@Rn+,VBR mova @@(disp,PC),R0 -lds Rn,MACH movt Rn -lds Rn,MACL muls Rm,Rn -lds Rn,PR mulu Rm,Rn -lds.l @@Rn+,MACH neg Rm,Rn -lds.l @@Rn+,MACL negc Rm,Rn -@page -nop stc VBR,Rn -not Rm,Rn stc.l GBR,@@-Rn -or #imm,R0 stc.l SR,@@-Rn -or Rm,Rn stc.l VBR,@@-Rn -or.b #imm,@@(R0,GBR) sts MACH,Rn -rotcl Rn sts MACL,Rn -rotcr Rn sts PR,Rn -rotl Rn sts.l MACH,@@-Rn -rotr Rn sts.l MACL,@@-Rn -rte sts.l PR,@@-Rn -rts sub Rm,Rn -sett subc Rm,Rn -shal Rn subv Rm,Rn -shar Rn swap.b Rm,Rn -shll Rn swap.w Rm,Rn -shll16 Rn tas.b @@Rn -shll2 Rn trapa #imm -shll8 Rn tst #imm,R0 -shlr Rn tst Rm,Rn -shlr16 Rn tst.b #imm,@@(R0,GBR) -shlr2 Rn xor #imm,R0 -shlr8 Rn xor Rm,Rn -sleep xor.b #imm,@@(R0,GBR) -stc GBR,Rn xtrct Rm,Rn -stc SR,Rn -@end smallexample -@end ifset - -@ifset Renesas-all -@ifclear GENERIC -@raisesections -@end ifclear -@end ifset - diff --git a/contrib/binutils/gas/doc/c-sparc.texi b/contrib/binutils/gas/doc/c-sparc.texi deleted file mode 100644 index c34950e13f7fc..0000000000000 --- a/contrib/binutils/gas/doc/c-sparc.texi +++ /dev/null @@ -1,195 +0,0 @@ -@c Copyright 1991, 1992, 1993, 1994, 1995, 1997, 1999 -@c Free Software Foundation, Inc. -@c This is part of the GAS manual. -@c For copying conditions, see the file as.texinfo. -@ifset GENERIC -@page -@node Sparc-Dependent -@chapter SPARC Dependent Features -@end ifset -@ifclear GENERIC -@node Machine Dependencies -@chapter SPARC Dependent Features -@end ifclear - -@cindex SPARC support -@menu -* Sparc-Opts:: Options -* Sparc-Aligned-Data:: Option to enforce aligned data -* Sparc-Float:: Floating Point -* Sparc-Directives:: Sparc Machine Directives -@end menu - -@node Sparc-Opts -@section Options - -@cindex options for SPARC -@cindex SPARC options -@cindex architectures, SPARC -@cindex SPARC architectures -The SPARC chip family includes several successive levels, using the same -core instruction set, but including a few additional instructions at -each level. There are exceptions to this however. For details on what -instructions each variant supports, please see the chip's architecture -reference manual. - -By default, @code{@value{AS}} assumes the core instruction set (SPARC -v6), but ``bumps'' the architecture level as needed: it switches to -successively higher architectures as it encounters instructions that -only exist in the higher levels. - -If not configured for SPARC v9 (@code{sparc64-*-*}) GAS will not bump -passed sparclite by default, an option must be passed to enable the -v9 instructions. - -GAS treats sparclite as being compatible with v8, unless an architecture -is explicitly requested. SPARC v9 is always incompatible with sparclite. - -@c The order here is the same as the order of enum sparc_opcode_arch_val -@c to give the user a sense of the order of the "bumping". - -@table @code -@kindex -Av6 -@kindex Av7 -@kindex -Av8 -@kindex -Asparclet -@kindex -Asparclite -@kindex -Av9 -@kindex -Av9a -@item -Av6 | -Av7 | -Av8 | -Asparclet | -Asparclite -@itemx -Av8plus | -Av8plusa | -Av9 | -Av9a -Use one of the @samp{-A} options to select one of the SPARC -architectures explicitly. If you select an architecture explicitly, -@code{@value{AS}} reports a fatal error if it encounters an instruction -or feature requiring an incompatible or higher level. - -@samp{-Av8plus} and @samp{-Av8plusa} select a 32 bit environment. - -@samp{-Av9} and @samp{-Av9a} select a 64 bit environment and are not -available unless GAS is explicitly configured with 64 bit environment -support. - -@samp{-Av8plusa} and @samp{-Av9a} enable the SPARC V9 instruction set with -UltraSPARC extensions. - -@item -xarch=v8plus | -xarch=v8plusa -For compatibility with the Solaris v9 assembler. These options are -equivalent to -Av8plus and -Av8plusa, respectively. - -@item -bump -Warn whenever it is necessary to switch to another level. -If an architecture level is explicitly requested, GAS will not issue -warnings until that level is reached, and will then bump the level -as required (except between incompatible levels). - -@item -32 | -64 -Select the word size, either 32 bits or 64 bits. -These options are only available with the ELF object file format, -and require that the necessary BFD support has been included. -@end table - -@node Sparc-Aligned-Data -@section Enforcing aligned data - -@cindex data alignment on SPARC -@cindex SPARC data alignment -SPARC GAS normally permits data to be misaligned. For example, it -permits the @code{.long} pseudo-op to be used on a byte boundary. -However, the native SunOS and Solaris assemblers issue an error when -they see misaligned data. - -@kindex --enforce-aligned-data -You can use the @code{--enforce-aligned-data} option to make SPARC GAS -also issue an error about misaligned data, just as the SunOS and Solaris -assemblers do. - -The @code{--enforce-aligned-data} option is not the default because gcc -issues misaligned data pseudo-ops when it initializes certain packed -data structures (structures defined using the @code{packed} attribute). -You may have to assemble with GAS in order to initialize packed data -structures in your own code. - -@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 -@section 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 -@section Sparc Machine Directives - -@cindex SPARC machine directives -@cindex machine directives, SPARC -The Sparc version of @code{@value{AS}} supports the following additional -machine directives: - -@table @code -@cindex @code{align} directive, SPARC -@item .align -This must be followed by the desired alignment in bytes. - -@cindex @code{common} directive, SPARC -@item .common -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. - -@cindex @code{half} directive, SPARC -@item .half -This is functionally identical to @code{.short}. - -@cindex @code{nword} directive, SPARC -@item .nword -On the Sparc, the @code{.nword} directive produces native word sized value, -ie. if assembling with -32 it is equivalent to @code{.word}, if assembling -with -64 it is equivalent to @code{.xword}. - -@cindex @code{proc} directive, SPARC -@item .proc -This directive is ignored. Any text following it on the same -line is also ignored. - -@cindex @code{register} directive, SPARC -@item .register -This directive declares use of a global application or system register. -It must be followed by a register name %g2, %g3, %g6 or %g7, comma and -the symbol name for that register. If symbol name is @code{#scratch}, -it is a scratch register, if it is @code{#ignore}, it just suppresses any -errors about using undeclared global register, but does not emit any -information about it into the object file. This can be useful e.g. if you -save the register before use and restore it after. - -@cindex @code{reserve} directive, SPARC -@item .reserve -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. - -@cindex @code{seg} directive, SPARC -@item .seg -This must be followed by @code{"text"}, @code{"data"}, or -@code{"data1"}. It behaves like @code{.text}, @code{.data}, or -@code{.data 1}. - -@cindex @code{skip} directive, SPARC -@item .skip -This is functionally identical to the @code{.space} directive. - -@cindex @code{word} directive, SPARC -@item .word -On the Sparc, the @code{.word} directive produces 32 bit values, -instead of the 16 bit values it produces on many other machines. - -@cindex @code{xword} directive, SPARC -@item .xword -On the Sparc V9 processor, the @code{.xword} directive produces -64 bit values. -@end table diff --git a/contrib/binutils/gas/doc/c-v850.texi b/contrib/binutils/gas/doc/c-v850.texi deleted file mode 100644 index 4b36461ee52b6..0000000000000 --- a/contrib/binutils/gas/doc/c-v850.texi +++ /dev/null @@ -1,363 +0,0 @@ -@c Copyright 1997 Free Software Foundation, Inc. -@c This is part of the GAS manual. -@c For copying conditions, see the file as.texinfo. - -@node V850-Dependent -@chapter v850 Dependent Features - -@cindex V850 support -@menu -* V850 Options:: Options -* V850 Syntax:: Syntax -* V850 Floating Point:: Floating Point -* V850 Directives:: V850 Machine Directives -* V850 Opcodes:: Opcodes -@end menu - -@node V850 Options -@section Options -@cindex V850 options (none) -@cindex options for V850 (none) -@code{@value{AS}} supports the following additional command-line options -for the V850 processor family: - -@cindex command line options, V850 -@cindex V850 command line options -@table @code - -@cindex @code{-wsigned_overflow} command line option, V850 -@item -wsigned_overflow -Causes warnings to be produced when signed immediate values overflow the -space available for then within their opcodes. By default this option -is disabled as it is possible to receive spurious warnings due to using -exact bit patterns as immediate constants. - -@cindex @code{-wunsigned_overflow} command line option, V850 -@item -wunsigned_overflow -Causes warnings to be produced when unsigned immediate values overflow -the space available for then within their opcodes. By default this -option is disabled as it is possible to receive spurious warnings due to -using exact bit patterns as immediate constants. - -@cindex @code{-mv850} command line option, V850 -@item -mv850 -Specifies that the assembled code should be marked as being targeted at -the V850 processor. This allows the linker to detect attempts to link -such code with code assembled for other processors. - -@cindex @code{-mv850e} command line option, V850 -@item -mv850e -Specifies that the assembled code should be marked as being targeted at -the V850E processor. This allows the linker to detect attempts to link -such code with code assembled for other processors. - -@cindex @code{-mv850any} command line option, V850 -@item -mv850any -Specifies that the assembled code should be marked as being targeted at -the V850 processor but support instructions that are specific to the -extended variants of the process. This allows the production of -binaries that contain target specific code, but which are also intended -to be used in a generic fashion. For example libgcc.a contains generic -routines used by the code produced by GCC for all versions of the v850 -architecture, together with support routines only used by the V850E -architecture. - -@end table - - -@node V850 Syntax -@section Syntax -@menu -* V850-Chars:: Special Characters -* V850-Regs:: Register Names -@end menu - -@node V850-Chars -@subsection Special Characters - -@cindex line comment character, V850 -@cindex V850 line comment character -@samp{#} is the line comment character. -@node V850-Regs -@subsection Register Names - -@cindex V850 register names -@cindex register names, V850 -@code{@value{AS}} supports the following names for registers: -@table @code -@cindex @code{zero} register, V850 -@item general register 0 -r0, zero -@item general register 1 -r1 -@item general register 2 -r2, hp -@cindex @code{sp} register, V850 -@item general register 3 -r3, sp -@cindex @code{gp} register, V850 -@item general register 4 -r4, gp -@cindex @code{tp} register, V850 -@item general register 5 -r5, tp -@item general register 6 -r6 -@item general register 7 -r7 -@item general register 8 -r8 -@item general register 9 -r9 -@item general register 10 -r10 -@item general register 11 -r11 -@item general register 12 -r12 -@item general register 13 -r13 -@item general register 14 -r14 -@item general register 15 -r15 -@item general register 16 -r16 -@item general register 17 -r17 -@item general register 18 -r18 -@item general register 19 -r19 -@item general register 20 -r20 -@item general register 21 -r21 -@item general register 22 -r22 -@item general register 23 -r23 -@item general register 24 -r24 -@item general register 25 -r25 -@item general register 26 -r26 -@item general register 27 -r27 -@item general register 28 -r28 -@item general register 29 -r29 -@cindex @code{ep} register, V850 -@item general register 30 -r30, ep -@cindex @code{lp} register, V850 -@item general register 31 -r31, lp -@cindex @code{eipc} register, V850 -@item system register 0 -eipc -@cindex @code{eipsw} register, V850 -@item system register 1 -eipsw -@cindex @code{fepc} register, V850 -@item system register 2 -fepc -@cindex @code{fepsw} register, V850 -@item system register 3 -fepsw -@cindex @code{ecr} register, V850 -@item system register 4 -ecr -@cindex @code{psw} register, V850 -@item system register 5 -psw -@cindex @code{ctpc} register, V850 -@item system register 16 -ctpc -@cindex @code{ctpsw} register, V850 -@item system register 17 -ctpsw -@cindex @code{dbpc} register, V850 -@item system register 18 -dbpc -@cindex @code{dbpsw} register, V850 -@item system register 19 -dbpsw -@cindex @code{ctbp} register, V850 -@item system register 20 -ctbp -@end table - -@node V850 Floating Point -@section Floating Point - -@cindex floating point, V850 (@sc{ieee}) -@cindex V850 floating point (@sc{ieee}) -The V850 family uses @sc{ieee} floating-point numbers. - -@node V850 Directives -@section V850 Machine Directives - -@cindex machine directives, V850 -@cindex V850 machine directives -@table @code -@cindex @code{offset} directive, V850 -@item .offset @var{<expression>} -Moves the offset into the current section to the specified amount. - -@cindex @code{section} directive, V850 -@item .section "name", <type> -This is an extension to the standard .section directive. It sets the -current section to be <type> and creates an alias for this section -called "name". - -@cindex @code{.v850} directive, V850 -@item .v850 -Specifies that the assembled code should be marked as being targeted at -the V850 processor. This allows the linker to detect attempts to link -such code with code assembled for other processors. - -@cindex @code{.v850e} directive, V850 -@item .v850e -Specifies that the assembled code should be marked as being targeted at -the V850E processor. This allows the linker to detect attempts to link -such code with code assembled for other processors. - -@end table - -@node V850 Opcodes -@section Opcodes - -@cindex V850 opcodes -@cindex opcodes for V850 -@code{@value{AS}} implements all the standard V850 opcodes. - -@code{@value{AS}} also implements the following pseudo ops: - -@table @code - -@cindex @code{hi0} pseudo-op, V850 -@item hi0() -Computes the higher 16 bits of the given expression and stores it into -the immediate operand field of the given instruction. For example: - - @samp{mulhi hi0(here - there), r5, r6} - -computes the difference between the address of labels 'here' and -'there', takes the upper 16 bits of this difference, shifts it down 16 -bits and then mutliplies it by the lower 16 bits in register 5, putting -the result into register 6. - -@cindex @code{lo} pseudo-op, V850 -@item lo() -Computes the lower 16 bits of the given expression and stores it into -the immediate operand field of the given instruction. For example: - - @samp{addi lo(here - there), r5, r6} - -computes the difference between the address of labels 'here' and -'there', takes the lower 16 bits of this difference and adds it to -register 5, putting the result into register 6. - -@cindex @code{hi} pseudo-op, V850 -@item hi() -Computes the higher 16 bits of the given expression and then adds the -value of the most significant bit of the lower 16 bits of the expression -and stores the result into the immediate operand field of the given -instruction. For example the following code can be used to compute the -address of the label 'here' and store it into register 6: - - @samp{movhi hi(here), r0, r6} - @samp{movea lo(here), r6, r6} - -The reason for this special behaviour is that movea performs a sign -extention on its immediate operand. So for example if the address of -'here' was 0xFFFFFFFF then without the special behaviour of the hi() -pseudo-op the movhi instruction would put 0xFFFF0000 into r6, then the -movea instruction would takes its immediate operand, 0xFFFF, sign extend -it to 32 bits, 0xFFFFFFFF, and then add it into r6 giving 0xFFFEFFFF -which is wrong (the fifth nibble is E). With the hi() pseudo op adding -in the top bit of the lo() pseudo op, the movhi instruction actually -stores 0 into r6 (0xFFFF + 1 = 0x0000), so that the movea instruction -stores 0xFFFFFFFF into r6 - the right value. - -@cindex @code{hilo} pseudo-op, V850 -@item hilo() -Computes the 32 bit value of the given expression and stores it into -the immediate operand field of the given instruction (which must be a -mov instruction). For example: - - @samp{mov hilo(here), r6} - -computes the absolute address of label 'here' and puts the result into -register 6. - -@cindex @code{sdaoff} pseudo-op, V850 -@item sdaoff() -Computes the offset of the named variable from the start of the Small -Data Area (whoes address is held in register 4, the GP register) and -stores the result as a 16 bit signed value in the immediate operand -field of the given instruction. For example: - - @samp{ld.w sdaoff(_a_variable)[gp],r6} - -loads the contents of the location pointed to by the label '_a_variable' -into register 6, provided that the label is located somewhere within +/- -32K of the address held in the GP register. [Note the linker assumes -that the GP register contains a fixed address set to the address of the -label called '__gp'. This can either be set up automatically by the -linker, or specifically set by using the @samp{--defsym __gp=<value>} -command line option]. - -@cindex @code{tdaoff} pseudo-op, V850 -@item tdaoff() -Computes the offset of the named variable from the start of the Tiny -Data Area (whoes address is held in register 30, the EP register) and -stores the result as a 4,5, 7 or 8 bit unsigned value in the immediate -operand field of the given instruction. For example: - - @samp{sld.w tdaoff(_a_variable)[ep],r6} - -loads the contents of the location pointed to by the label '_a_variable' -into register 6, provided that the label is located somewhere within +256 -bytes of the address held in the EP register. [Note the linker assumes -that the EP register contains a fixed address set to the address of the -label called '__ep'. This can either be set up automatically by the -linker, or specifically set by using the @samp{--defsym __ep=<value>} -command line option]. - -@cindex @code{zdaoff} pseudo-op, V850 -@item zdaoff() -Computes the offset of the named variable from address 0 and stores the -result as a 16 bit signed value in the immediate operand field of the -given instruction. For example: - - @samp{movea zdaoff(_a_variable),zero,r6} - -puts the address of the label '_a_variable' into register 6, assuming -that the label is somewhere within the first 32K of memory. (Strictly -speaking it also possible to access the last 32K of memory as well, as -the offsets are signed). - -@cindex @code{ctoff} pseudo-op, V850 -@item ctoff() -Computes the offset of the named variable from the start of the Call -Table Area (whoes address is helg in system register 20, the CTBP -register) and stores the result a 6 or 16 bit unsigned value in the -immediate field of then given instruction or piece of data. For -example: - - @samp{callt ctoff(table_func1)} - -will put the call the function whoes address is held in the call table -at the location labeled 'table_func1'. - -@end table - - -For information on the V850 instruction set, see @cite{V850 -Family 32-/16-Bit single-Chip Microcontroller Architecture Manual} from NEC. -Ltd. - diff --git a/contrib/binutils/gas/doc/c-z8k.texi b/contrib/binutils/gas/doc/c-z8k.texi deleted file mode 100644 index d98adeaf04aa1..0000000000000 --- a/contrib/binutils/gas/doc/c-z8k.texi +++ /dev/null @@ -1,380 +0,0 @@ -@c Copyright 1991, 1992, 1993, 1994, 1995 Free Software Foundation, Inc. -@c This is part of the GAS manual. -@c For copying conditions, see the file as.texinfo. -@ifset GENERIC -@page -@node Z8000-Dependent -@chapter Z8000 Dependent Features -@end ifset -@ifclear GENERIC -@node Machine Dependencies -@chapter Z8000 Dependent Features -@end ifclear - -@cindex Z8000 support -The Z8000 @value{AS} supports both members of the Z8000 family: the -unsegmented Z8002, with 16 bit addresses, and the segmented Z8001 with -24 bit addresses. - -When the assembler is in unsegmented mode (specified with the -@code{unsegm} directive), an address takes up one word (16 bit) -sized register. When the assembler is in segmented mode (specified with -the @code{segm} directive), a 24-bit address takes up a long (32 bit) -register. @xref{Z8000 Directives,,Assembler Directives for the Z8000}, -for a list of other Z8000 specific assembler directives. - -@menu -* Z8000 Options:: No special command-line options for Z8000 -* Z8000 Syntax:: Assembler syntax for the Z8000 -* Z8000 Directives:: Special directives for the Z8000 -* Z8000 Opcodes:: Opcodes -@end menu - -@node Z8000 Options -@section Options - -@cindex Z8000 options -@cindex options, Z8000 -@code{@value{AS}} has no additional command-line options for the Zilog -Z8000 family. - -@node Z8000 Syntax -@section Syntax -@menu -* Z8000-Chars:: Special Characters -* Z8000-Regs:: Register Names -* Z8000-Addressing:: Addressing Modes -@end menu - -@node Z8000-Chars -@subsection Special Characters - -@cindex line comment character, Z8000 -@cindex Z8000 line comment character -@samp{!} is the line comment character. - -@cindex line separator, Z8000 -@cindex statement separator, Z8000 -@cindex Z8000 line separator -You can use @samp{;} instead of a newline to separate statements. - -@node Z8000-Regs -@subsection Register Names - -@cindex Z8000 registers -@cindex registers, Z8000 -The Z8000 has sixteen 16 bit registers, numbered 0 to 15. You can refer -to different sized groups of registers by register number, with the -prefix @samp{r} for 16 bit registers, @samp{rr} for 32 bit registers and -@samp{rq} for 64 bit registers. You can also refer to the contents of -the first eight (of the sixteen 16 bit registers) by bytes. They are -named @samp{r@var{n}h} and @samp{r@var{n}l}. - -@smallexample -@exdent @emph{byte registers} -r0l r0h r1h r1l r2h r2l r3h r3l -r4h r4l r5h r5l r6h r6l r7h r7l - -@exdent @emph{word registers} -r0 r1 r2 r3 r4 r5 r6 r7 r8 r9 r10 r11 r12 r13 r14 r15 - -@exdent @emph{long word registers} -rr0 rr2 rr4 rr6 rr8 rr10 rr12 rr14 - -@exdent @emph{quad word registers} -rq0 rq4 rq8 rq12 -@end smallexample - -@node Z8000-Addressing -@subsection Addressing Modes - -@cindex addressing modes, Z8000 -@cindex Z800 addressing modes -@value{AS} understands the following addressing modes for the Z8000: - -@table @code -@item r@var{n} -Register direct - -@item @@r@var{n} -Indirect register - -@item @var{addr} -Direct: the 16 bit or 24 bit address (depending on whether the assembler -is in segmented or unsegmented mode) of the operand is in the instruction. - -@item address(r@var{n}) -Indexed: the 16 or 24 bit address is added to the 16 bit register to produce -the final address in memory of the operand. - -@item r@var{n}(#@var{imm}) -Base Address: the 16 or 24 bit register is added to the 16 bit sign -extended immediate displacement to produce the final address in memory -of the operand. - -@item r@var{n}(r@var{m}) -Base Index: the 16 or 24 bit register r@var{n} is added to the sign -extended 16 bit index register r@var{m} to produce the final address in -memory of the operand. - -@item #@var{xx} -Immediate data @var{xx}. -@end table - -@node Z8000 Directives -@section Assembler Directives for the Z8000 - -@cindex Z8000 directives -@cindex directives, Z8000 -The Z8000 port of @value{AS} includes these additional assembler directives, -for compatibility with other Z8000 assemblers. As shown, these do not -begin with @samp{.} (unlike the ordinary @value{AS} directives). - -@table @code -@kindex segm -@item segm -Generates code for the segmented Z8001. - -@kindex unsegm -@item unsegm -Generates code for the unsegmented Z8002. - -@kindex name -@item name -Synonym for @code{.file} - -@kindex global -@item global -Synonym for @code{.global} - -@kindex wval -@item wval -Synonym for @code{.word} - -@kindex lval -@item lval -Synonym for @code{.long} - -@kindex bval -@item bval -Synonym for @code{.byte} - -@kindex sval -@item sval -Assemble a string. @code{sval} expects one string literal, delimited by -single quotes. It assembles each byte of the string into consecutive -addresses. You can use the escape sequence @samp{%@var{xx}} (where -@var{xx} represents a two-digit hexadecimal number) to represent the -character whose @sc{ascii} value is @var{xx}. Use this feature to -describe single quote and other characters that may not appear in string -literals as themselves. For example, the C statement @w{@samp{char *a = -"he said \"it's 50% off\"";}} is represented in Z8000 assembly language -(shown with the assembler output in hex at the left) as - -@iftex -@begingroup -@let@nonarrowing=@comment -@end iftex -@smallexample -68652073 sval 'he said %22it%27s 50%25 off%22%00' -61696420 -22697427 -73203530 -25206F66 -662200 -@end smallexample -@iftex -@endgroup -@end iftex - -@kindex rsect -@item rsect -synonym for @code{.section} - -@kindex block -@item block -synonym for @code{.space} - -@kindex even -@item even -special case of @code{.align}; aligns output to even byte boundary. -@end table - -@node Z8000 Opcodes -@section Opcodes - -@cindex Z8000 opcode summary -@cindex opcode summary, Z8000 -@cindex mnemonics, Z8000 -@cindex instruction summary, Z8000 -For detailed information on the Z8000 machine instruction set, see -@cite{Z8000 Technical Manual}. - -@ifset SMALL -@c this table, due to the multi-col faking and hardcoded order, looks silly -@c except in smallbook. See comments below "@set SMALL" near top of this file. - -The following table summarizes the opcodes and their arguments: -@iftex -@begingroup -@let@nonarrowing=@comment -@end iftex -@smallexample - - rs @r{16 bit source register} - rd @r{16 bit destination register} - rbs @r{8 bit source register} - rbd @r{8 bit destination register} - rrs @r{32 bit source register} - rrd @r{32 bit destination register} - rqs @r{64 bit source register} - rqd @r{64 bit destination register} - addr @r{16/24 bit address} - imm @r{immediate data} - -adc rd,rs clrb addr cpsir @@rd,@@rs,rr,cc -adcb rbd,rbs clrb addr(rd) cpsirb @@rd,@@rs,rr,cc -add rd,@@rs clrb rbd dab rbd -add rd,addr com @@rd dbjnz rbd,disp7 -add rd,addr(rs) com addr dec @@rd,imm4m1 -add rd,imm16 com addr(rd) dec addr(rd),imm4m1 -add rd,rs com rd dec addr,imm4m1 -addb rbd,@@rs comb @@rd dec rd,imm4m1 -addb rbd,addr comb addr decb @@rd,imm4m1 -addb rbd,addr(rs) comb addr(rd) decb addr(rd),imm4m1 -addb rbd,imm8 comb rbd decb addr,imm4m1 -addb rbd,rbs comflg flags decb rbd,imm4m1 -addl rrd,@@rs cp @@rd,imm16 di i2 -addl rrd,addr cp addr(rd),imm16 div rrd,@@rs -addl rrd,addr(rs) cp addr,imm16 div rrd,addr -addl rrd,imm32 cp rd,@@rs div rrd,addr(rs) -addl rrd,rrs cp rd,addr div rrd,imm16 -and rd,@@rs cp rd,addr(rs) div rrd,rs -and rd,addr cp rd,imm16 divl rqd,@@rs -and rd,addr(rs) cp rd,rs divl rqd,addr -and rd,imm16 cpb @@rd,imm8 divl rqd,addr(rs) -and rd,rs cpb addr(rd),imm8 divl rqd,imm32 -andb rbd,@@rs cpb addr,imm8 divl rqd,rrs -andb rbd,addr cpb rbd,@@rs djnz rd,disp7 -andb rbd,addr(rs) cpb rbd,addr ei i2 -andb rbd,imm8 cpb rbd,addr(rs) ex rd,@@rs -andb rbd,rbs cpb rbd,imm8 ex rd,addr -bit @@rd,imm4 cpb rbd,rbs ex rd,addr(rs) -bit addr(rd),imm4 cpd rd,@@rs,rr,cc ex rd,rs -bit addr,imm4 cpdb rbd,@@rs,rr,cc exb rbd,@@rs -bit rd,imm4 cpdr rd,@@rs,rr,cc exb rbd,addr -bit rd,rs cpdrb rbd,@@rs,rr,cc exb rbd,addr(rs) -bitb @@rd,imm4 cpi rd,@@rs,rr,cc exb rbd,rbs -bitb addr(rd),imm4 cpib rbd,@@rs,rr,cc ext0e imm8 -bitb addr,imm4 cpir rd,@@rs,rr,cc ext0f imm8 -bitb rbd,imm4 cpirb rbd,@@rs,rr,cc ext8e imm8 -bitb rbd,rs cpl rrd,@@rs ext8f imm8 -bpt cpl rrd,addr exts rrd -call @@rd cpl rrd,addr(rs) extsb rd -call addr cpl rrd,imm32 extsl rqd -call addr(rd) cpl rrd,rrs halt -calr disp12 cpsd @@rd,@@rs,rr,cc in rd,@@rs -clr @@rd cpsdb @@rd,@@rs,rr,cc in rd,imm16 -clr addr cpsdr @@rd,@@rs,rr,cc inb rbd,@@rs -clr addr(rd) cpsdrb @@rd,@@rs,rr,cc inb rbd,imm16 -clr rd cpsi @@rd,@@rs,rr,cc inc @@rd,imm4m1 -clrb @@rd cpsib @@rd,@@rs,rr,cc inc addr(rd),imm4m1 -inc addr,imm4m1 ldb rbd,rs(rx) mult rrd,addr(rs) -inc rd,imm4m1 ldb rd(imm16),rbs mult rrd,imm16 -incb @@rd,imm4m1 ldb rd(rx),rbs mult rrd,rs -incb addr(rd),imm4m1 ldctl ctrl,rs multl rqd,@@rs -incb addr,imm4m1 ldctl rd,ctrl multl rqd,addr -incb rbd,imm4m1 ldd @@rs,@@rd,rr multl rqd,addr(rs) -ind @@rd,@@rs,ra lddb @@rs,@@rd,rr multl rqd,imm32 -indb @@rd,@@rs,rba lddr @@rs,@@rd,rr multl rqd,rrs -inib @@rd,@@rs,ra lddrb @@rs,@@rd,rr neg @@rd -inibr @@rd,@@rs,ra ldi @@rd,@@rs,rr neg addr -iret ldib @@rd,@@rs,rr neg addr(rd) -jp cc,@@rd ldir @@rd,@@rs,rr neg rd -jp cc,addr ldirb @@rd,@@rs,rr negb @@rd -jp cc,addr(rd) ldk rd,imm4 negb addr -jr cc,disp8 ldl @@rd,rrs negb addr(rd) -ld @@rd,imm16 ldl addr(rd),rrs negb rbd -ld @@rd,rs ldl addr,rrs nop -ld addr(rd),imm16 ldl rd(imm16),rrs or rd,@@rs -ld addr(rd),rs ldl rd(rx),rrs or rd,addr -ld addr,imm16 ldl rrd,@@rs or rd,addr(rs) -ld addr,rs ldl rrd,addr or rd,imm16 -ld rd(imm16),rs ldl rrd,addr(rs) or rd,rs -ld rd(rx),rs ldl rrd,imm32 orb rbd,@@rs -ld rd,@@rs ldl rrd,rrs orb rbd,addr -ld rd,addr ldl rrd,rs(imm16) orb rbd,addr(rs) -ld rd,addr(rs) ldl rrd,rs(rx) orb rbd,imm8 -ld rd,imm16 ldm @@rd,rs,n orb rbd,rbs -ld rd,rs ldm addr(rd),rs,n out @@rd,rs -ld rd,rs(imm16) ldm addr,rs,n out imm16,rs -ld rd,rs(rx) ldm rd,@@rs,n outb @@rd,rbs -lda rd,addr ldm rd,addr(rs),n outb imm16,rbs -lda rd,addr(rs) ldm rd,addr,n outd @@rd,@@rs,ra -lda rd,rs(imm16) ldps @@rs outdb @@rd,@@rs,rba -lda rd,rs(rx) ldps addr outib @@rd,@@rs,ra -ldar rd,disp16 ldps addr(rs) outibr @@rd,@@rs,ra -ldb @@rd,imm8 ldr disp16,rs pop @@rd,@@rs -ldb @@rd,rbs ldr rd,disp16 pop addr(rd),@@rs -ldb addr(rd),imm8 ldrb disp16,rbs pop addr,@@rs -ldb addr(rd),rbs ldrb rbd,disp16 pop rd,@@rs -ldb addr,imm8 ldrl disp16,rrs popl @@rd,@@rs -ldb addr,rbs ldrl rrd,disp16 popl addr(rd),@@rs -ldb rbd,@@rs mbit popl addr,@@rs -ldb rbd,addr mreq rd popl rrd,@@rs -ldb rbd,addr(rs) mres push @@rd,@@rs -ldb rbd,imm8 mset push @@rd,addr -ldb rbd,rbs mult rrd,@@rs push @@rd,addr(rs) -ldb rbd,rs(imm16) mult rrd,addr push @@rd,imm16 -push @@rd,rs set addr,imm4 subl rrd,imm32 -pushl @@rd,@@rs set rd,imm4 subl rrd,rrs -pushl @@rd,addr set rd,rs tcc cc,rd -pushl @@rd,addr(rs) setb @@rd,imm4 tccb cc,rbd -pushl @@rd,rrs setb addr(rd),imm4 test @@rd -res @@rd,imm4 setb addr,imm4 test addr -res addr(rd),imm4 setb rbd,imm4 test addr(rd) -res addr,imm4 setb rbd,rs test rd -res rd,imm4 setflg imm4 testb @@rd -res rd,rs sinb rbd,imm16 testb addr -resb @@rd,imm4 sinb rd,imm16 testb addr(rd) -resb addr(rd),imm4 sind @@rd,@@rs,ra testb rbd -resb addr,imm4 sindb @@rd,@@rs,rba testl @@rd -resb rbd,imm4 sinib @@rd,@@rs,ra testl addr -resb rbd,rs sinibr @@rd,@@rs,ra testl addr(rd) -resflg imm4 sla rd,imm8 testl rrd -ret cc slab rbd,imm8 trdb @@rd,@@rs,rba -rl rd,imm1or2 slal rrd,imm8 trdrb @@rd,@@rs,rba -rlb rbd,imm1or2 sll rd,imm8 trib @@rd,@@rs,rbr -rlc rd,imm1or2 sllb rbd,imm8 trirb @@rd,@@rs,rbr -rlcb rbd,imm1or2 slll rrd,imm8 trtdrb @@ra,@@rb,rbr -rldb rbb,rba sout imm16,rs trtib @@ra,@@rb,rr -rr rd,imm1or2 soutb imm16,rbs trtirb @@ra,@@rb,rbr -rrb rbd,imm1or2 soutd @@rd,@@rs,ra trtrb @@ra,@@rb,rbr -rrc rd,imm1or2 soutdb @@rd,@@rs,rba tset @@rd -rrcb rbd,imm1or2 soutib @@rd,@@rs,ra tset addr -rrdb rbb,rba soutibr @@rd,@@rs,ra tset addr(rd) -rsvd36 sra rd,imm8 tset rd -rsvd38 srab rbd,imm8 tsetb @@rd -rsvd78 sral rrd,imm8 tsetb addr -rsvd7e srl rd,imm8 tsetb addr(rd) -rsvd9d srlb rbd,imm8 tsetb rbd -rsvd9f srll rrd,imm8 xor rd,@@rs -rsvdb9 sub rd,@@rs xor rd,addr -rsvdbf sub rd,addr xor rd,addr(rs) -sbc rd,rs sub rd,addr(rs) xor rd,imm16 -sbcb rbd,rbs sub rd,imm16 xor rd,rs -sc imm8 sub rd,rs xorb rbd,@@rs -sda rd,rs subb rbd,@@rs xorb rbd,addr -sdab rbd,rs subb rbd,addr xorb rbd,addr(rs) -sdal rrd,rs subb rbd,addr(rs) xorb rbd,imm8 -sdl rd,rs subb rbd,imm8 xorb rbd,rbs -sdlb rbd,rs subb rbd,rbs xorb rbd,rbs -sdll rrd,rs subl rrd,@@rs -set @@rd,imm4 subl rrd,addr -set addr(rd),imm4 subl rrd,addr(rs) -@end smallexample -@iftex -@endgroup -@end iftex -@end ifset - diff --git a/contrib/binutils/gas/doc/gasp.texi b/contrib/binutils/gas/doc/gasp.texi deleted file mode 100644 index 889e997105ce9..0000000000000 --- a/contrib/binutils/gas/doc/gasp.texi +++ /dev/null @@ -1,1456 +0,0 @@ -\input texinfo @c -*- Texinfo -*- -@setfilename gasp.info -@c -@c This file documents the assembly preprocessor "GASP" -@c -@c Copyright 1994, 1995, 2000, 2002 Free Software Foundation, Inc. -@c -@c Permission is granted to copy, distribute and/or modify this document -@c under the terms of the GNU Free Documentation License, Version 1.1 -@c or any later version published by the Free Software Foundation; -@c with no Invariant Sections, with no Front-Cover Texts, and with no -@c Back-Cover Texts. A copy of the license is included in the -@c section entitled "GNU Free Documentation License". - -@ifinfo -@format -START-INFO-DIR-ENTRY -* gasp: (gasp). The GNU Assembler Preprocessor -END-INFO-DIR-ENTRY -@end format -@end ifinfo - -@syncodeindex ky cp -@syncodeindex fn cp - -@finalout -@setchapternewpage odd -@settitle GASP -@titlepage -@c FIXME boring title -@title GASP, an assembly preprocessor -@subtitle for GASP version 1 -@sp 1 -@subtitle March 1994 -@author Roland Pesch -@page - -@tex -{\parskip=0pt \hfill Cygnus Support\par -} -@end tex - -@vskip 0pt plus 1filll -Copyright @copyright{} 1994, 1995, 2000, 2002 Free Software Foundation, Inc. - - Permission is granted to copy, distribute and/or modify this document - under the terms of the GNU Free Documentation License, Version 1.1 - or any later version published by the Free Software Foundation; - with no Invariant Sections, with no Front-Cover Texts, and with no - Back-Cover Texts. A copy of the license is included in the - section entitled "GNU Free Documentation License". - -@end titlepage - -@ifinfo -Copyright @copyright{} 1994, 1995, 2000, 2002 Free Software Foundation, Inc. - -@ignore -Permission is granted to process this file through TeX and print the -results, provided the printed document carries a 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, distribute and/or modify this document - under the terms of the GNU Free Documentation License, Version 1.1 - or any later version published by the Free Software Foundation; - with no Invariant Sections, with no Front-Cover Texts, and with no - Back-Cover Texts. A copy of the license is included in the - section entitled "GNU Free Documentation License". - - -@node Top -@top GASP - -GASP is a preprocessor for assembly programs. - -This file describes version 1 of GASP. - -Steve Chamberlain wrote GASP; Roland Pesch wrote this manual. - -@menu -* Overview:: What is GASP? -* Invoking GASP:: Command line options. -* Commands:: Preprocessor commands. -* GNU Free Documentation License:: GNU Free Documentation License -* Index:: Index. -@end menu -@end ifinfo - -@node Overview -@chapter What is GASP? - -The primary purpose of the @sc{gnu} assembler is to assemble the output of -other programs---notably compilers. When you have to hand-code -specialized routines in assembly, that means the @sc{gnu} assembler is -an unfriendly processor: it has no directives for macros, conditionals, -or many other conveniences that you might expect. - -In some cases you can simply use the C preprocessor, or a generalized -preprocessor like @sc{m4}; but this can be awkward, since none of these -things are designed with assembly in mind. - -@sc{gasp} fills this need. It is expressly designed to provide the -facilities you need with hand-coded assembly code. Implementing it as a -preprocessor, rather than part of the assembler, allows the maximum -flexibility: you can use it with hand-coded assembly, without paying a -penalty of added complexity in the assembler you use for compiler -output. - -@emph{Note} The use of @sc{gasp} has now been deprecated. Anything -that it could do can now be done by the macro facilities built into -@sc{gas} itself. At some point in the future the @sc{gasp} sources will -be removed entirely from the binutils distribution. - -Here is a small example to give the flavor of @sc{gasp}. This input to -@sc{gasp} - -@cartouche -@example - .MACRO saveregs from=8 to=14 -count .ASSIGNA \from - ! save r\from..r\to - .AWHILE \&count LE \to - mov r\&count,@@-sp -count .ASSIGNA \&count + 1 - .AENDW - .ENDM - - saveregs from=12 - -bar: mov #H'dead+10,r0 -foo .SDATAC "hello"<10> - .END -@end example -@end cartouche - -@noindent -generates this assembly program: - -@cartouche -@example - ! save r12..r14 - mov r12,@@-sp - mov r13,@@-sp - mov r14,@@-sp - -bar: mov #57005+10,r0 -foo: .byte 6,104,101,108,108,111,10 -@end example -@end cartouche - -@node Invoking GASP -@chapter Command Line Options - -@c FIXME! Or is there a simpler way, calling from GAS option? -The simplest way to use @sc{gasp} is to run it as a filter and assemble -its output. In Unix and its ilk, you can do this, for example: - -@c FIXME! GASP filename suffix convention? -@example -$ gasp prog.asm | as -o prog.o -@end example - -Naturally, there are also a few command-line options to allow you to -request variations on this basic theme. Here is the full set of -possibilities for the @sc{gasp} command line. - -@example -gasp [ -a | --alternate ] - [ -c @var{char} | --commentchar @var{char} ] - [ -d | --debug ] [ -h | --help ] [ -M | --mri ] - [ -o @var{outfile} | --output @var{outfile} ] - [ -p | --print ] [ -s | --copysource ] - [ -u | --unreasonable ] [ -v | --version ] - @var{infile} @dots{} -@end example - -@ftable @code -@item @var{infile} @dots{} -@c FIXME! Why not stdin as default infile? -The input file names. You must specify at least one input file; if you -specify more, @sc{gasp} preprocesses them all, concatenating the output -in the order you list the @var{infile} arguments. - -Mark the end of each input file with the preprocessor command -@code{.END}. @xref{Other Commands,, Miscellaneous commands}. - -@item -a -@itemx --alternate -Use alternative macro syntax. @xref{Alternate,, Alternate macro -syntax}, for a discussion of how this syntax differs from the default -@sc{gasp} syntax. - -@cindex comment character, changing -@cindex semicolon, as comment -@cindex exclamation mark, as comment -@cindex shriek, as comment -@cindex bang, as comment -@cindex @code{!} default comment char -@cindex @code{;} as comment char -@item -c '@var{char}' -@itemx --commentchar '@var{char}' -Use @var{char} as the comment character. The default comment character -is @samp{!}. For example, to use a semicolon as the comment character, -specify @w{@samp{-c ';'}} on the @sc{gasp} command line. Since -assembler command characters often have special significance to command -shells, it is a good idea to quote or escape @var{char} when you specify -a comment character. - -For the sake of simplicity, all examples in this manual use the default -comment character @samp{!}. - -@item -d -@itemx --debug -Show debugging statistics. In this version of @sc{gasp}, this option -produces statistics about the string buffers that @sc{gasp} allocates -internally. For each defined buffersize @var{s}, @sc{gasp} shows the -number of strings @var{n} that it allocated, with a line like this: - -@example -strings size @var{s} : @var{n} -@end example - -@noindent -@sc{gasp} displays these statistics on the standard error stream, when -done preprocessing. - -@item -h -@itemx --help -Display a summary of the @sc{gasp} command line options. - -@item -M -@itemx --mri -Use MRI compatibility mode. Using this option causes @sc{gasp} to -accept the syntax and pseudo-ops used by the Microtec Research -@code{ASM68K} assembler. - -@item -o @var{outfile} -@itemx --output @var{outfile} -Write the output in a file called @var{outfile}. If you do not use the -@samp{-o} option, @sc{gasp} writes its output on the standard output -stream. - -@item -p -@itemx --print -Print line numbers. @sc{gasp} obeys this option @emph{only} if you also -specify @samp{-s} to copy source lines to its output. With @samp{-s --p}, @sc{gasp} displays the line number of each source line copied -(immediately after the comment character at the beginning of the line). - -@item -s -@itemx --copysource -Copy the source lines to the output file. Use this option -to see the effect of each preprocessor line on the @sc{gasp} output. -@sc{gasp} places a comment character (@samp{!} by default) at -the beginning of each source line it copies, so that you can use this -option and still assemble the result. - -@item -u -@itemx --unreasonable -Bypass ``unreasonable expansion'' limit. Since you can define @sc{gasp} -macros inside other macro definitions, the preprocessor normally -includes a sanity check. If your program requires more than 1,000 -nested expansions, @sc{gasp} normally exits with an error message. Use -this option to turn off this check, allowing unlimited nested -expansions. - -@item -v -@itemx --version -Display the @sc{gasp} version number. -@end ftable - -@node Commands -@chapter Preprocessor Commands - -@sc{gasp} commands have a straightforward syntax that fits in well with -assembly conventions. In general, a command extends for a line, and may -have up to three fields: an optional label, the command itself, and -optional arguments to the command. You can write commands in upper or -lower case, though this manual shows them in upper case. @xref{Syntax -Details,, Details of the GASP syntax}, for more information. - -@menu -* Conditionals:: -* Loops:: -* Variables:: -* Macros:: -* Data:: -* Listings:: -* Other Commands:: -* Syntax Details:: -* Alternate:: -@end menu - -@node Conditionals -@section Conditional assembly - -The conditional-assembly directives allow you to include or exclude -portions of an assembly depending on how a pair of expressions, or a -pair of strings, compare. - -The overall structure of conditionals is familiar from many other -contexts. @code{.AIF} marks the start of a conditional, and precedes -assembly for the case when the condition is true. An optional -@code{.AELSE} precedes assembly for the converse case, and an -@code{.AENDI} marks the end of the condition. - -@c FIXME! Why doesn't -u turn off this check? -You may nest conditionals up to a depth of 100; @sc{gasp} rejects -nesting beyond that, because it may indicate a bug in your macro -structure. - -@c FIXME! Why isn't there something like cpp's -D option? Conditionals -@c would be much more useful if there were. -Conditionals are primarily useful inside macro definitions, where you -often need different effects depending on argument values. -@xref{Macros,, Defining your own directives}, for details about defining -macros. - -@ftable @code -@item .AIF @var{expra} @var{cmp} @var{exprb} -@itemx .AIF "@var{stra}" @var{cmp} "@var{strb}" - -The governing condition goes on the same line as the @code{.AIF} -preprocessor command. You may compare either two strings, or two -expressions. - -When you compare strings, only two conditional @var{cmp} comparison -operators are available: @samp{EQ} (true if @var{stra} and @var{strb} -are identical), and @samp{NE} (the opposite). - -When you compare two expressions, @emph{both expressions must be -absolute} (@pxref{Expressions,, Arithmetic expressions in GASP}). You -can use these @var{cmp} comparison operators with expressions: - -@ftable @code -@item EQ -Are @var{expra} and @var{exprb} equal? (For strings, are @var{stra} and -@var{strb} identical?) - -@item NE -Are @var{expra} and @var{exprb} different? (For strings, are @var{stra} -and @var{strb} different? - -@item LT -Is @var{expra} less than @var{exprb}? (Not allowed for strings.) - -@item LE -Is @var{expra} less than or equal to @var{exprb}? (Not allowed for strings.) - -@item GT -Is @var{expra} greater than @var{exprb}? (Not allowed for strings.) - -@item GE -Is @var{expra} greater than or equal to @var{exprb}? (Not allowed for -strings.) -@end ftable - -@item .AELSE -Marks the start of assembly code to be included if the condition fails. -Optional, and only allowed within a conditional (between @code{.AIF} and -@code{.AENDI}). - -@item .AENDI -Marks the end of a conditional assembly. -@end ftable - -@node Loops -@section Repetitive sections of assembly - -Two preprocessor directives allow you to repeatedly issue copies of the -same block of assembly code. - -@ftable @code -@item .AREPEAT @var{aexp} -@itemx .AENDR -If you simply need to repeat the same block of assembly over and over a -fixed number of times, sandwich one instance of the repeated block -between @code{.AREPEAT} and @code{.AENDR}. Specify the number of -copies as @var{aexp} (which must be an absolute expression). For -example, this repeats two assembly statements three times in succession: - -@cartouche -@example - .AREPEAT 3 - rotcl r2 - div1 r0,r1 - .AENDR -@end example -@end cartouche - -@item .AWHILE @var{expra} @var{cmp} @var{exprb} -@itemx .AENDW -@itemx .AWHILE @var{stra} @var{cmp} @var{strb} -@itemx .AENDW -To repeat a block of assembly depending on a conditional test, rather -than repeating it for a specific number of times, use @code{.AWHILE}. -@code{.AENDW} marks the end of the repeated block. The conditional -comparison works exactly the same way as for @code{.AIF}, with the same -comparison operators (@pxref{Conditionals,, Conditional assembly}). - -Since the terms of the comparison must be absolute expression, -@code{.AWHILE} is primarily useful within macros. @xref{Macros,, -Defining your own directives}. -@end ftable - -@cindex loops, breaking out of -@cindex breaking out of loops -You can use the @code{.EXITM} preprocessor directive to break out of -loops early (as well as to break out of macros). @xref{Macros,, -Defining your own directives}. - -@node Variables -@section Preprocessor variables - -You can use variables in @sc{gasp} to represent strings, registers, or -the results of expressions. - -You must distinguish two kinds of variables: -@enumerate -@item -Variables defined with @code{.EQU} or @code{.ASSIGN}. To evaluate this -kind of variable in your assembly output, simply mention its name. For -example, these two lines define and use a variable @samp{eg}: - -@cartouche -@example -eg .EQU FLIP-64 - @dots{} - mov.l eg,r0 -@end example -@end cartouche - -@emph{Do not use} this kind of variable in conditional expressions or -while loops; @sc{gasp} only evaluates these variables when writing -assembly output. - -@item -Variables for use during preprocessing. You can define these -with @code{.ASSIGNC} or @code{.ASSIGNA}. To evaluate this -kind of variable, write @samp{\&} before the variable name; for example, - -@cartouche -@example -opcit .ASSIGNA 47 - @dots{} - .AWHILE \&opcit GT 0 - @dots{} - .AENDW -@end example -@end cartouche - -@sc{gasp} treats macro arguments almost the same way, but to evaluate -them you use the prefix @samp{\} rather than @samp{\&}. -@xref{Macros,, Defining your own directives}. -@end enumerate - -@ftable @code -@item @var{pvar} .EQU @var{expr} -@c FIXME! Anything to beware of re GAS directive of same name? -Assign preprocessor variable @var{pvar} the value of the expression -@var{expr}. There are no restrictions on redefinition; use @samp{.EQU} -with the same @var{pvar} as often as you find it convenient. - -@item @var{pvar} .ASSIGN @var{expr} -Almost the same as @code{.EQU}, save that you may not redefine -@var{pvar} using @code{.ASSIGN} once it has a value. -@c FIXME!! Supposed to work this way, apparently, but on 9feb94 works -@c just like .EQU - -@item @var{pvar} .ASSIGNA @var{aexpr} -Define a variable with a numeric value, for use during preprocessing. -@var{aexpr} must be an absolute expression. You can redefine variables -with @code{.ASSIGNA} at any time. - -@item @var{pvar} .ASSIGNC "@var{str}" -Define a variable with a string value, for use during preprocessing. -You can redefine variables with @code{.ASSIGNC} at any time. - -@item @var{pvar} .REG (@var{register}) -Use @code{.REG} to define a variable that represents a register. In -particular, @var{register} is @emph{not evaluated} as an expression. -You may use @code{.REG} at will to redefine register variables. -@end ftable - -All these directives accept the variable name in the ``label'' position, -that is at the left margin. You may specify a colon after the variable -name if you wish; the first example above could have started @samp{eg:} -with the same effect. - -@c pagebreak makes for better aesthetics---ensures macro and expansion together -@page -@node Macros -@section Defining your own directives - -The commands @code{.MACRO} and @code{.ENDM} allow you to define macros -that generate assembly output. You can use these macros with a syntax -similar to built-in @sc{gasp} or assembler directives. For example, -this definition specifies a macro @code{SUM} that adds together a range of -consecutive registers: - -@cartouche -@example - .MACRO SUM FROM=0, TO=9 - ! \FROM \TO - mov r\FROM,r10 -COUNT .ASSIGNA \FROM+1 - .AWHILE \&COUNT LE \TO - add r\&COUNT,r10 -COUNT .ASSIGNA \&COUNT+1 - .AENDW - .ENDM -@end example -@end cartouche - -@noindent -With that definition, @samp{SUM 0,5} generates this assembly output: - -@cartouche -@example - ! 0 5 - mov r0,r10 - add r1,r10 - add r2,r10 - add r3,r10 - add r4,r10 - add r5,r10 -@end example -@end cartouche - -@ftable @code -@item .MACRO @var{macname} -@itemx .MACRO @var{macname} @var{macargs} @dots{} -Begin the definition of a macro called @var{macname}. If your macro -definition requires arguments, specify their names after the macro name, -separated by commas or spaces. You can supply a default value for any -macro argument by following the name with @samp{=@var{deflt}}. For -example, these are all valid @code{.MACRO} statements: - -@table @code -@item .MACRO COMM -Begin the definition of a macro called @code{COMM}, which takes no -arguments. - -@item .MACRO PLUS1 P, P1 -@itemx .MACRO PLUS1 P P1 -Either statement begins the definition of a macro called @code{PLUS1}, -which takes two arguments; within the macro definition, write -@samp{\P} or @samp{\P1} to evaluate the arguments. - -@item .MACRO RESERVE_STR P1=0 P2 -Begin the definition of a macro called @code{RESERVE_STR}, with two -arguments. The first argument has a default value, but not the second. -After the definition is complete, you can call the macro either as -@samp{RESERVE_STR @var{a},@var{b}} (with @samp{\P1} evaluating to -@var{a} and @samp{\P2} evaluating to @var{b}), or as @samp{RESERVE_STR -,@var{b}} (with @samp{\P1} evaluating as the default, in this case -@samp{0}, and @samp{\P2} evaluating to @var{b}). -@end table - -When you call a macro, you can specify the argument values either by -position, or by keyword. For example, @samp{SUM 9,17} is equivalent to -@samp{SUM TO=17, FROM=9}. Macro arguments are preprocessor variables -similar to the variables you define with @samp{.ASSIGNA} or -@samp{.ASSIGNC}; in particular, you can use them in conditionals or for -loop control. (The only difference is the prefix you write to evaluate -the variable: for a macro argument, write @samp{\@var{argname}}, but for -a preprocessor variable, write @samp{\&@var{varname}}.) - -@item @var{name} .MACRO -@itemx @var{name} .MACRO ( @var{macargs} @dots{} ) -@c FIXME check: I think no error _and_ no args recognized if I use form -@c NAME .MACRO ARG ARG -An alternative form of introducing a macro definition: specify the macro -name in the label position, and the arguments (if any) between -parentheses after the name. Defaulting rules and usage work the same -way as for the other macro definition syntax. - -@item .ENDM -Mark the end of a macro definition. - -@item .EXITM -Exit early from the current macro definition, @code{.AREPEAT} loop, or -@code{.AWHILE} loop. - -@cindex number of macros executed -@cindex macros, count executed -@item \@@ -@sc{gasp} maintains a counter of how many macros it has -executed in this pseudo-variable; you can copy that number to your -output with @samp{\@@}, but @emph{only within a macro definition}. - -@item LOCAL @var{name} [ , @dots{} ] -@emph{Warning: @code{LOCAL} is only available if you select ``alternate -macro syntax'' with @samp{-a} or @samp{--alternate}.} @xref{Alternate,, -Alternate macro syntax}. - -Generate a string replacement for each of the @var{name} arguments, and -replace any instances of @var{name} in each macro expansion. The -replacement string is unique in the assembly, and different for each -separate macro expansion. @code{LOCAL} allows you to write macros that -define symbols, without fear of conflict between separate macro expansions. -@end ftable - -@node Data -@section Data output - -In assembly code, you often need to specify working areas of memory; -depending on the application, you may want to initialize such memory or -not. @sc{gasp} provides preprocessor directives to help you avoid -repetitive coding for both purposes. - -You can use labels as usual to mark the data areas. - -@menu -* Initialized:: -* Uninitialized:: -@end menu - -@node Initialized -@subsection Initialized data - -These are the @sc{gasp} directives for initialized data, and the standard -@sc{gnu} assembler directives they expand to: - -@ftable @code -@item .DATA @var{expr}, @var{expr}, @dots{} -@itemx .DATA.B @var{expr}, @var{expr}, @dots{} -@itemx .DATA.W @var{expr}, @var{expr}, @dots{} -@itemx .DATA.L @var{expr}, @var{expr}, @dots{} -Evaluate arithmetic expressions @var{expr}, and emit the corresponding -@code{as} directive (labelled with @var{lab}). The unqualified -@code{.DATA} emits @samp{.long}; @code{.DATA.B} emits @samp{.byte}; -@code{.DATA.W} emits @samp{.short}; and @code{.DATA.L} emits -@samp{.long}. - -For example, @samp{foo .DATA 1,2,3} emits @samp{foo: .long 1,2,3}. - -@item .DATAB @var{repeat}, @var{expr} -@itemx .DATAB.B @var{repeat}, @var{expr} -@itemx .DATAB.W @var{repeat}, @var{expr} -@itemx .DATAB.L @var{repeat}, @var{expr} -@c FIXME! Looks like gasp accepts and ignores args after 2nd. -Make @code{as} emit @var{repeat} copies of the value of the expression -@var{expr} (using the @code{as} directive @code{.fill}). -@samp{.DATAB.B} repeats one-byte values; @samp{.DATAB.W} repeats -two-byte values; and @samp{.DATAB.L} repeats four-byte values. -@samp{.DATAB} without a suffix repeats four-byte values, just like -@samp{.DATAB.L}. - -@c FIXME! Allowing zero might be useful for edge conditions in macros. -@var{repeat} must be an absolute expression with a positive value. - -@item .SDATA "@var{str}" @dots{} -String data. Emits a concatenation of bytes, precisely as you specify -them (in particular, @emph{nothing is added to mark the end} of the -string). @xref{Constants,, String and numeric constants}, for details -about how to write strings. @code{.SDATA} concatenates multiple -arguments, making it easy to switch between string representations. You -can use commas to separate the individual arguments for clarity, if you -choose. - -@item .SDATAB @var{repeat}, "@var{str}" @dots{} -Repeated string data. The first argument specifies how many copies of -the string to emit; the remaining arguments specify the string, in the -same way as the arguments to @code{.SDATA}. - -@item .SDATAZ "@var{str}" @dots{} -Zero-terminated string data. Just like @code{.SDATA}, except that -@code{.SDATAZ} writes a zero byte at the end of the string. - -@item .SDATAC "@var{str}" @dots{} -Count-prefixed string data. Just like @code{.SDATA}, except that -@sc{gasp} precedes the string with a leading one-byte count. For -example, @samp{.SDATAC "HI"} generates @samp{.byte 2,72,73}. Since the -count field is only one byte, you can only use @code{.SDATAC} for -strings less than 256 bytes in length. -@end ftable - -@node Uninitialized -@subsection Uninitialized data - -@c FIXME! .space different on some platforms, notably HPPA. Config? -Use the @code{.RES}, @code{.SRES}, @code{.SRESC}, and @code{.SRESZ} -directives to reserve memory and leave it uninitialized. @sc{gasp} -resolves these directives to appropriate calls of the @sc{gnu} -@code{as} @code{.space} directive. - -@ftable @code -@item .RES @var{count} -@itemx .RES.B @var{count} -@itemx .RES.W @var{count} -@itemx .RES.L @var{count} -Reserve room for @var{count} uninitialized elements of data. The -suffix specifies the size of each element: @code{.RES.B} reserves -@var{count} bytes, @code{.RES.W} reserves @var{count} pairs of bytes, -and @code{.RES.L} reserves @var{count} quartets. @code{.RES} without a -suffix is equivalent to @code{.RES.L}. - -@item .SRES @var{count} -@itemx .SRES.B @var{count} -@itemx .SRES.W @var{count} -@itemx .SRES.L @var{count} -@c FIXME! This is boring. Shouldn't it at least have a different -@c default size? (e.g. the "S" suggests "string", for which .B -@c would be more appropriate) -@code{.SRES} is a synonym for @samp{.RES}. - -@item .SRESC @var{count} -@itemx .SRESC.B @var{count} -@itemx .SRESC.W @var{count} -@itemx .SRESC.L @var{count} -Like @code{.SRES}, but reserves space for @code{@var{count}+1} elements. - -@item .SRESZ @var{count} -@itemx .SRESZ.B @var{count} -@itemx .SRESZ.W @var{count} -@itemx .SRESZ.L @var{count} -Like @code{.SRES}, but reserves space for @code{@var{count}+1} elements. -@end ftable - -@node Listings -@section Assembly listing control - -The @sc{gasp} listing-control directives correspond to -related @sc{gnu} @code{as} directives. - -@ftable @code -@item .PRINT LIST -@itemx .PRINT NOLIST -Print control. This directive emits the @sc{gnu} @code{as} directive -@code{.list} or @code{.nolist}, according to its argument. @xref{List,, -@code{.list}, as.info, Using as}, for details on how these directives -interact. - -@item .FORM LIN=@var{ln} -@itemx .FORM COL=@var{cols} -@itemx .FORM LIN=@var{ln} COL=@var{cols} -Specify the page size for assembly listings: @var{ln} represents the -number of lines, and @var{cols} the number of columns. You may specify -either page dimension independently, or both together. If you do not -specify the number of lines, @sc{gasp} assumes 60 lines; if you do not -specify the number of columns, @sc{gasp} assumes 132 columns. -(Any values you may have specified in previous instances of @code{.FORM} -do @emph{not} carry over as defaults.) Emits the @code{.psize} -assembler directive. - -@item .HEADING @var{string} -Specify @var{string} as the title of your assembly listings. Emits -@samp{.title "@var{string}"}. - -@item .PAGE -Force a new page in assembly listings. Emits @samp{.eject}. -@end ftable - -@node Other Commands -@section Miscellaneous commands - -@ftable @code -@item .ALTERNATE -Use the alternate macro syntax henceforth in the assembly. -@xref{Alternate,, Alternate macro syntax}. - -@item .ORG -@c FIXME! This is very strange, since _GAS_ understands .org -This command is recognized, but not yet implemented. @sc{gasp} -generates an error message for programs that use @code{.ORG}. - -@item .RADIX @var{s} -@c FIXME no test cases in testsuite/gasp -@sc{gasp} understands numbers in any of base two, eight, ten, or -sixteen. You can encode the base explicitly in any numeric constant -(@pxref{Constants,, String and numeric constants}). If you write -numbers without an explicit indication of the base, the most recent -@samp{.RADIX @var{s}} command determines how they are interpreted. -@var{s} is a single letter, one of the following: - -@table @code -@item .RADIX B -Base 2. - -@item .RADIX Q -Base 8. - -@item .RADIX D -Base 10. This is the original default radix. - -@item .RADIX H -Base 16. -@end table - -You may specify the argument @var{s} in lower case (any of @samp{bqdh}) -with the same effects. - -@item .EXPORT @var{name} -@itemx .GLOBAL @var{name} -@c FIXME! No test cases in testsuite/gasp -Declare @var{name} global (emits @samp{.global @var{name}}). The two -directives are synonymous. - -@item .PROGRAM -No effect: @sc{gasp} accepts this directive, and silently ignores it. - -@item .END -Mark end of each preprocessor file. @sc{gasp} issues a warning if it -reaches end of file without seeing this command. - -@item .INCLUDE "@var{str}" -Preprocess the file named by @var{str}, as if its contents appeared -where the @code{.INCLUDE} directive does. @sc{gasp} imposes a maximum -limit of 30 stacked include files, as a sanity check. -@c FIXME! Why is include depth not affected by -u? - -@item .ALIGN @var{size} -@c FIXME! Why is this not utterly pointless? -Evaluate the absolute expression @var{size}, and emit the assembly -instruction @samp{.align @var{size}} using the result. -@end ftable - -@node Syntax Details -@section Details of the GASP syntax - -Since @sc{gasp} is meant to work with assembly code, its statement -syntax has no surprises for the assembly programmer. - -@cindex whitespace -@emph{Whitespace} (blanks or tabs; @emph{not} newline) is partially -significant, in that it delimits up to three fields in a line. The -amount of whitespace does not matter; you may line up fields in separate -lines if you wish, but @sc{gasp} does not require that. - -@cindex fields of @sc{gasp} source line -@cindex label field -The @emph{first field}, an optional @dfn{label}, must be flush left in a -line (with no leading whitespace) if it appears at all. You may use a -colon after the label if you wish; @sc{gasp} neither requires the colon -nor objects to it (but will not include it as part of the label name). - -@cindex directive field -The @emph{second field}, which must appear after some whitespace, -contains a @sc{gasp} or assembly @dfn{directive}. - -@cindex argument fields -Any @emph{further fields} on a line are @dfn{arguments} to the -directive; you can separate them from one another using either commas or -whitespace. - -@menu -* Markers:: -* Constants:: -* Symbols:: -* Expressions:: -* String Builtins:: -@end menu - -@node Markers -@subsection Special syntactic markers - -@sc{gasp} recognizes a few special markers: to delimit comments, to -continue a statement on the next line, to separate symbols from other -characters, and to copy text to the output literally. (One other -special marker, @samp{\@@}, works only within macro definitions; -@pxref{Macros,, Defining your own directives}.) - -@cindex comments -The trailing part of any @sc{gasp} source line may be a @dfn{comment}. -A comment begins with the first unquoted comment character (@samp{!} by -default), or an escaped or doubled comment character (@samp{\!} or -@samp{!!} by default), and extends to the end of a line. You can -specify what comment character to use with the @samp{-c} option -(@pxref{Invoking GASP,, Command Line Options}). The two kinds of -comment markers lead to slightly different treatment: - -@table @code -@item ! -A single, un-escaped comment character generates an assembly comment in -the @sc{gasp} output. @sc{gasp} evaluates any preprocessor variables -(macro arguments, or variables defined with @code{.ASSIGNA} or -@code{.ASSIGNC}) present. For example, a macro that begins like this - -@example - .MACRO SUM FROM=0, TO=9 - ! \FROM \TO -@end example - -@noindent -issues as the first line of output a comment that records the -values you used to call the macro. - -@c comments, preprocessor-only -@c preprocessor-only comments -@c GASP-only comments -@item \! -@itemx !! -Either an escaped comment character, or a double comment character, -marks a @sc{gasp} source comment. @sc{gasp} does not copy such comments -to the assembly output. -@end table - -@cindex continuation character -@kindex + -To @emph{continue a statement} on the next line of the file, begin the -second line with the character @samp{+}. - -@cindex literal copy to output -@cindex copying literally to output -@cindex preprocessing, avoiding -@cindex avoiding preprocessing -Occasionally you may want to prevent @sc{gasp} from preprocessing some -particular bit of text. To @emph{copy literally} from the @sc{gasp} -source to its output, place @samp{\(} before the string to copy, and -@samp{)} at the end. For example, write @samp{\(\!)} if you need the -characters @samp{\!} in your assembly output. - -@cindex symbol separator -@cindex text, separating from symbols -@cindex symbols, separating from text -To @emph{separate a preprocessor variable} from text to appear -immediately after its value, write a single quote (@code{'}). For -example, @samp{.SDATA "\P'1"} writes a string built by concatenating the -value of @code{P} and the digit @samp{1}. (You cannot achieve this by -writing just @samp{\P1}, since @samp{P1} is itself a valid name for a -preprocessor variable.) - -@node Constants -@subsection String and numeric constants - -There are two ways of writing @dfn{string constants} in @sc{gasp}: as -literal text, and by numeric byte value. Specify a string literal -between double quotes (@code{"@var{str}"}). Specify an individual -numeric byte value as an absolute expression between angle brackets -(@code{<@var{expr}>}. Directives that output strings allow you to -specify any number of either kind of value, in whatever order is -convenient, and concatenate the result. (Alternate syntax mode -introduces a number of alternative string notations; @pxref{Alternate,, -Alternate macro syntax}.) - -@c Details of numeric notation, e.g. base prefixes -You can write @dfn{numeric constants} either in a specific base, or in -whatever base is currently selected (either 10, or selected by the most -recent @code{.RADIX}). - -To write a number in a @emph{specific base}, use the pattern -@code{@var{s}'@var{ddd}}: a base specifier character @var{s}, followed -by a single quote followed by digits @var{ddd}. The base specifier -character matches those you can specify with @code{.RADIX}: @samp{B} for -base 2, @samp{Q} for base 8, @samp{D} for base 10, and @samp{H} for base -16. (You can write this character in lower case if you prefer.) - -You can write floating point constants using the same syntax recognised -by GAS @ref{Flonums,,Flonums,as,The GNU Assembler.}. A constraint is -that these constants will be interpreted as decimal values irrespective -of the currently selected base. - -@c FIXME! What are rules for recognizing number in deflt base? Whatever -@c is left over after parsing other things?? - -@node Symbols -@subsection Symbols - -@sc{gasp} recognizes symbol names that start with any alphabetic character, -@samp{_}, or @samp{$}, and continue with any of the same characters or -with digits. Label names follow the same rules. - -@node Expressions -@subsection Arithmetic expressions in GASP - -@cindex absolute expressions -@cindex relocatable expressions -There are two kinds of expressions, depending on their result: -@dfn{absolute} expressions, which resolve to a constant (that is, they -do not involve any values unknown to @sc{gasp}), and @dfn{relocatable} -expressions, which must reduce to the form - -@example -@var{addsym}+@var{const}-@var{subsym} -@end example - -@noindent -where @var{addsym} and @var{subsym} are assembly symbols of unknown -value, and @var{const} is a constant. - -Arithmetic for @sc{gasp} expressions follows very similar rules to C. -You can use parentheses to change precedence; otherwise, arithmetic -primitives have decreasing precedence in the order of the following -list. - -@enumerate -@item -Single-argument @code{+} (identity), @code{-} (arithmetic opposite), or -@code{~} (bitwise negation). @emph{The argument must be an absolute -expression.} - -@item -@code{*} (multiplication) and @code{/} (division). @emph{Both arguments -must be absolute expressions.} - -@item -@code{+} (addition) and @code{-} (subtraction). @emph{At least one argument -must be absolute.} -@c FIXME! Actually, subtraction doesn't check for this. - -@item -@code{&} (bitwise and). @emph{Both arguments must be absolute.} - -@item -@c FIXME! I agree ~ is a better notation than ^ for xor, but is the -@c improvement worth differing from C? -@code{|} (bitwise or) and @code{~} (bitwise exclusive or; @code{^} in -C). @emph{Both arguments must be absolute.} -@end enumerate - -@node String Builtins -@subsection String primitives - -You can use these primitives to manipulate strings (in the argument -field of @sc{gasp} statements): - -@ftable @code -@item .LEN("@var{str}") -Calculate the length of string @code{"@var{str}"}, as an absolute -expression. For example, @samp{.RES.B .LEN("sample")} reserves six -bytes of memory. - -@item .INSTR("@var{string}", "@var{seg}", @var{ix}) -Search for the first occurrence of @var{seg} after position @var{ix} of -@var{string}. For example, @samp{.INSTR("ABCDEFG", "CDE", 0)} evaluates -to the absolute result @code{2}. - -The result is @code{-1} if @var{seg} does not occur in @var{string} -after position @var{ix}. - -@item .SUBSTR("@var{string}",@var{start},@var{len}) -The substring of @var{string} beginning at byte number @var{start} and -extending for @var{len} bytes. -@end ftable - -@node Alternate -@section Alternate macro syntax - -If you specify @samp{-a} or @samp{--alternate} on the @sc{gasp} command -line, the preprocessor uses somewhat different syntax. This syntax is -reminiscent of the syntax of Phar Lap macro assembler, but it -is @emph{not} meant to be a full emulation of Phar Lap or similar -assemblers. In particular, @sc{gasp} does not support directives such -as @code{DB} and @code{IRP}, even in alternate syntax mode. - -In particular, @samp{-a} (or @samp{--alternate}) elicits these -differences: - -@table @emph -@item Preprocessor directives -You can use @sc{gasp} preprocessor directives without a leading @samp{.} -dot. For example, you can write @samp{SDATA} with the same effect as -@samp{.SDATA}. - -@item LOCAL -One additional directive, @code{LOCAL}, is available. @xref{Macros,, -Defining your own directives}, for an explanation of how to use -@code{LOCAL}. - -@need 2000 -@item String delimiters -You can write strings delimited in these other ways besides -@code{"@var{string}"}: - -@table @code -@item '@var{string}' -You can delimit strings with single-quote charaters. - -@item <@var{string}> -You can delimit strings with matching angle brackets. -@end table - -@item single-character string escape -To include any single character literally in a string (even if the -character would otherwise have some special meaning), you can prefix the -character with @samp{!} (an exclamation mark). For example, you can -write @samp{<4.3 !> 5.4!!>} to get the literal text @samp{4.3 > 5.4!}. - -@item Expression results as strings -You can write @samp{%@var{expr}} to evaluate the expression @var{expr} -and use the result as a string. -@end table - -@node GNU Free Documentation License -@chapter GNU Free Documentation License - - GNU Free Documentation License - - Version 1.1, March 2000 - - Copyright (C) 2000 Free Software Foundation, Inc. - 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA - - Everyone is permitted to copy and distribute verbatim copies - of this license document, but changing it is not allowed. - - -0. PREAMBLE - -The purpose of this License is to make a manual, textbook, or other -written document "free" in the sense of freedom: to assure everyone -the effective freedom to copy and redistribute it, with or without -modifying it, either commercially or noncommercially. Secondarily, -this License preserves for the author and publisher a way to get -credit for their work, while not being considered responsible for -modifications made by others. - -This License is a kind of "copyleft", which means that derivative -works of the document must themselves be free in the same sense. It -complements the GNU General Public License, which is a copyleft -license designed for free software. - -We have designed this License in order to use it for manuals for free -software, because free software needs free documentation: a free -program should come with manuals providing the same freedoms that the -software does. But this License is not limited to software manuals; -it can be used for any textual work, regardless of subject matter or -whether it is published as a printed book. We recommend this License -principally for works whose purpose is instruction or reference. - - -1. APPLICABILITY AND DEFINITIONS - -This License applies to any manual or other work that contains a -notice placed by the copyright holder saying it can be distributed -under the terms of this License. The "Document", below, refers to any -such manual or work. Any member of the public is a licensee, and is -addressed as "you". - -A "Modified Version" of the Document means any work containing the -Document or a portion of it, either copied verbatim, or with -modifications and/or translated into another language. - -A "Secondary Section" is a named appendix or a front-matter section of -the Document that deals exclusively with the relationship of the -publishers or authors of the Document to the Document's overall subject -(or to related matters) and contains nothing that could fall directly -within that overall subject. (For example, if the Document is in part a -textbook of mathematics, a Secondary Section may not explain any -mathematics.) The relationship could be a matter of historical -connection with the subject or with related matters, or of legal, -commercial, philosophical, ethical or political position regarding -them. - -The "Invariant Sections" are certain Secondary Sections whose titles -are designated, as being those of Invariant Sections, in the notice -that says that the Document is released under this License. - -The "Cover Texts" are certain short passages of text that are listed, -as Front-Cover Texts or Back-Cover Texts, in the notice that says that -the Document is released under this License. - -A "Transparent" copy of the Document means a machine-readable copy, -represented in a format whose specification is available to the -general public, whose contents can be viewed and edited directly and -straightforwardly with generic text editors or (for images composed of -pixels) generic paint programs or (for drawings) some widely available -drawing editor, and that is suitable for input to text formatters or -for automatic translation to a variety of formats suitable for input -to text formatters. A copy made in an otherwise Transparent file -format whose markup has been designed to thwart or discourage -subsequent modification by readers is not Transparent. A copy that is -not "Transparent" is called "Opaque". - -Examples of suitable formats for Transparent copies include plain -ASCII without markup, Texinfo input format, LaTeX input format, SGML -or XML using a publicly available DTD, and standard-conforming simple -HTML designed for human modification. Opaque formats include -PostScript, PDF, proprietary formats that can be read and edited only -by proprietary word processors, SGML or XML for which the DTD and/or -processing tools are not generally available, and the -machine-generated HTML produced by some word processors for output -purposes only. - -The "Title Page" means, for a printed book, the title page itself, -plus such following pages as are needed to hold, legibly, the material -this License requires to appear in the title page. For works in -formats which do not have any title page as such, "Title Page" means -the text near the most prominent appearance of the work's title, -preceding the beginning of the body of the text. - - -2. VERBATIM COPYING - -You may copy and distribute the Document in any medium, either -commercially or noncommercially, provided that this License, the -copyright notices, and the license notice saying this License applies -to the Document are reproduced in all copies, and that you add no other -conditions whatsoever to those of this License. You may not use -technical measures to obstruct or control the reading or further -copying of the copies you make or distribute. However, you may accept -compensation in exchange for copies. If you distribute a large enough -number of copies you must also follow the conditions in section 3. - -You may also lend copies, under the same conditions stated above, and -you may publicly display copies. - - -3. COPYING IN QUANTITY - -If you publish printed copies of the Document numbering more than 100, -and the Document's license notice requires Cover Texts, you must enclose -the copies in covers that carry, clearly and legibly, all these Cover -Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on -the back cover. Both covers must also clearly and legibly identify -you as the publisher of these copies. The front cover must present -the full title with all words of the title equally prominent and -visible. You may add other material on the covers in addition. -Copying with changes limited to the covers, as long as they preserve -the title of the Document and satisfy these conditions, can be treated -as verbatim copying in other respects. - -If the required texts for either cover are too voluminous to fit -legibly, you should put the first ones listed (as many as fit -reasonably) on the actual cover, and continue the rest onto adjacent -pages. - -If you publish or distribute Opaque copies of the Document numbering -more than 100, you must either include a machine-readable Transparent -copy along with each Opaque copy, or state in or with each Opaque copy -a publicly-accessible computer-network location containing a complete -Transparent copy of the Document, free of added material, which the -general network-using public has access to download anonymously at no -charge using public-standard network protocols. If you use the latter -option, you must take reasonably prudent steps, when you begin -distribution of Opaque copies in quantity, to ensure that this -Transparent copy will remain thus accessible at the stated location -until at least one year after the last time you distribute an Opaque -copy (directly or through your agents or retailers) of that edition to -the public. - -It is requested, but not required, that you contact the authors of the -Document well before redistributing any large number of copies, to give -them a chance to provide you with an updated version of the Document. - - -4. MODIFICATIONS - -You may copy and distribute a Modified Version of the Document under -the conditions of sections 2 and 3 above, provided that you release -the Modified Version under precisely this License, with the Modified -Version filling the role of the Document, thus licensing distribution -and modification of the Modified Version to whoever possesses a copy -of it. In addition, you must do these things in the Modified Version: - -A. Use in the Title Page (and on the covers, if any) a title distinct - from that of the Document, and from those of previous versions - (which should, if there were any, be listed in the History section - of the Document). You may use the same title as a previous version - if the original publisher of that version gives permission. -B. List on the Title Page, as authors, one or more persons or entities - responsible for authorship of the modifications in the Modified - Version, together with at least five of the principal authors of the - Document (all of its principal authors, if it has less than five). -C. State on the Title page the name of the publisher of the - Modified Version, as the publisher. -D. Preserve all the copyright notices of the Document. -E. Add an appropriate copyright notice for your modifications - adjacent to the other copyright notices. -F. Include, immediately after the copyright notices, a license notice - giving the public permission to use the Modified Version under the - terms of this License, in the form shown in the Addendum below. -G. Preserve in that license notice the full lists of Invariant Sections - and required Cover Texts given in the Document's license notice. -H. Include an unaltered copy of this License. -I. Preserve the section entitled "History", and its title, and add to - it an item stating at least the title, year, new authors, and - publisher of the Modified Version as given on the Title Page. If - there is no section entitled "History" in the Document, create one - stating the title, year, authors, and publisher of the Document as - given on its Title Page, then add an item describing the Modified - Version as stated in the previous sentence. -J. Preserve the network location, if any, given in the Document for - public access to a Transparent copy of the Document, and likewise - the network locations given in the Document for previous versions - it was based on. These may be placed in the "History" section. - You may omit a network location for a work that was published at - least four years before the Document itself, or if the original - publisher of the version it refers to gives permission. -K. In any section entitled "Acknowledgements" or "Dedications", - preserve the section's title, and preserve in the section all the - substance and tone of each of the contributor acknowledgements - and/or dedications given therein. -L. Preserve all the Invariant Sections of the Document, - unaltered in their text and in their titles. Section numbers - or the equivalent are not considered part of the section titles. -M. Delete any section entitled "Endorsements". Such a section - may not be included in the Modified Version. -N. Do not retitle any existing section as "Endorsements" - or to conflict in title with any Invariant Section. - -If the Modified Version includes new front-matter sections or -appendices that qualify as Secondary Sections and contain no material -copied from the Document, you may at your option designate some or all -of these sections as invariant. To do this, add their titles to the -list of Invariant Sections in the Modified Version's license notice. -These titles must be distinct from any other section titles. - -You may add a section entitled "Endorsements", provided it contains -nothing but endorsements of your Modified Version by various -parties--for example, statements of peer review or that the text has -been approved by an organization as the authoritative definition of a -standard. - -You may add a passage of up to five words as a Front-Cover Text, and a -passage of up to 25 words as a Back-Cover Text, to the end of the list -of Cover Texts in the Modified Version. Only one passage of -Front-Cover Text and one of Back-Cover Text may be added by (or -through arrangements made by) any one entity. If the Document already -includes a cover text for the same cover, previously added by you or -by arrangement made by the same entity you are acting on behalf of, -you may not add another; but you may replace the old one, on explicit -permission from the previous publisher that added the old one. - -The author(s) and publisher(s) of the Document do not by this License -give permission to use their names for publicity for or to assert or -imply endorsement of any Modified Version. - - -5. COMBINING DOCUMENTS - -You may combine the Document with other documents released under this -License, under the terms defined in section 4 above for modified -versions, provided that you include in the combination all of the -Invariant Sections of all of the original documents, unmodified, and -list them all as Invariant Sections of your combined work in its -license notice. - -The combined work need only contain one copy of this License, and -multiple identical Invariant Sections may be replaced with a single -copy. If there are multiple Invariant Sections with the same name but -different contents, make the title of each such section unique by -adding at the end of it, in parentheses, the name of the original -author or publisher of that section if known, or else a unique number. -Make the same adjustment to the section titles in the list of -Invariant Sections in the license notice of the combined work. - -In the combination, you must combine any sections entitled "History" -in the various original documents, forming one section entitled -"History"; likewise combine any sections entitled "Acknowledgements", -and any sections entitled "Dedications". You must delete all sections -entitled "Endorsements." - - -6. COLLECTIONS OF DOCUMENTS - -You may make a collection consisting of the Document and other documents -released under this License, and replace the individual copies of this -License in the various documents with a single copy that is included in -the collection, provided that you follow the rules of this License for -verbatim copying of each of the documents in all other respects. - -You may extract a single document from such a collection, and distribute -it individually under this License, provided you insert a copy of this -License into the extracted document, and follow this License in all -other respects regarding verbatim copying of that document. - - -7. AGGREGATION WITH INDEPENDENT WORKS - -A compilation of the Document or its derivatives with other separate -and independent documents or works, in or on a volume of a storage or -distribution medium, does not as a whole count as a Modified Version -of the Document, provided no compilation copyright is claimed for the -compilation. Such a compilation is called an "aggregate", and this -License does not apply to the other self-contained works thus compiled -with the Document, on account of their being thus compiled, if they -are not themselves derivative works of the Document. - -If the Cover Text requirement of section 3 is applicable to these -copies of the Document, then if the Document is less than one quarter -of the entire aggregate, the Document's Cover Texts may be placed on -covers that surround only the Document within the aggregate. -Otherwise they must appear on covers around the whole aggregate. - - -8. TRANSLATION - -Translation is considered a kind of modification, so you may -distribute translations of the Document under the terms of section 4. -Replacing Invariant Sections with translations requires special -permission from their copyright holders, but you may include -translations of some or all Invariant Sections in addition to the -original versions of these Invariant Sections. You may include a -translation of this License provided that you also include the -original English version of this License. In case of a disagreement -between the translation and the original English version of this -License, the original English version will prevail. - - -9. TERMINATION - -You may not copy, modify, sublicense, or distribute the Document except -as expressly provided for under this License. Any other attempt to -copy, modify, sublicense or distribute the Document 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. - - -10. FUTURE REVISIONS OF THIS LICENSE - -The Free Software Foundation may publish new, revised versions -of the GNU Free Documentation 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. See -http://www.gnu.org/copyleft/. - -Each version of the License is given a distinguishing version number. -If the Document specifies that a particular numbered version of this -License "or any later version" applies to it, you have the option of -following the terms and conditions either of that specified version or -of any later version that has been published (not as a draft) by the -Free Software Foundation. If the Document does not specify a version -number of this License, you may choose any version ever published (not -as a draft) by the Free Software Foundation. - - -ADDENDUM: How to use this License for your documents - -To use this License in a document you have written, include a copy of -the License in the document and put the following copyright and -license notices just after the title page: - -@smallexample - Copyright (c) YEAR YOUR NAME. - Permission is granted to copy, distribute and/or modify this document - under the terms of the GNU Free Documentation License, Version 1.1 - or any later version published by the Free Software Foundation; - with the Invariant Sections being LIST THEIR TITLES, with the - Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST. - A copy of the license is included in the section entitled "GNU - Free Documentation License". -@end smallexample - -If you have no Invariant Sections, write "with no Invariant Sections" -instead of saying which ones are invariant. If you have no -Front-Cover Texts, write "no Front-Cover Texts" instead of -"Front-Cover Texts being LIST"; likewise for Back-Cover Texts. - -If your document contains nontrivial examples of program code, we -recommend releasing these examples in parallel under your choice of -free software license, such as the GNU General Public License, -to permit their use in free software. - -@node Index -@unnumbered Index - -@printindex cp - -@contents -@bye diff --git a/contrib/binutils/gas/doc/gasver.texi b/contrib/binutils/gas/doc/gasver.texi deleted file mode 100644 index 3610a96b96714..0000000000000 --- a/contrib/binutils/gas/doc/gasver.texi +++ /dev/null @@ -1 +0,0 @@ -@set VERSION 2.15 diff --git a/contrib/binutils/gas/doc/h8.texi b/contrib/binutils/gas/doc/h8.texi deleted file mode 100644 index 6eb02f8cbf2dd..0000000000000 --- a/contrib/binutils/gas/doc/h8.texi +++ /dev/null @@ -1,26 +0,0 @@ -@clear ALL-ARCH -@clear GENERIC -@clear INTERNALS -@clear MULTI-OBJ -@clear AOUT -@clear BOUT -@set COFF -@clear ELF -@set Renesas-all -@set H8/300 -@set H8/500 -@set SH -@clear DIFF-TBL-KLUGE -@set IEEEFLOAT -@clear W32 -@set W16 -@set SPECIAL-SYMS -@set AS as -@set GCC gcc -@set LD ld -@set TARGET H8/300 and H8/500 -@set TARGET H8/300, H8/500, and Renesas SH -@set OBJ-NAME COFF -@c -@clear have-stabs -@set abnormal-separator diff --git a/contrib/binutils/gas/doc/internals.texi b/contrib/binutils/gas/doc/internals.texi deleted file mode 100644 index 6719bbf945d35..0000000000000 --- a/contrib/binutils/gas/doc/internals.texi +++ /dev/null @@ -1,1948 +0,0 @@ -\input texinfo -@c Copyright 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000, -@c 2001, 2002, 2003 -@c Free Software Foundation, Inc. -@setfilename internals.info -@node Top -@top Assembler Internals -@raisesections -@cindex internals - -This chapter describes the internals of the assembler. It is incomplete, but -it may help a bit. - -This chapter is not updated regularly, and it may be out of date. - -@menu -* GAS versions:: GAS versions -* Data types:: Data types -* GAS processing:: What GAS does when it runs -* Porting GAS:: Porting GAS -* Relaxation:: Relaxation -* Broken words:: Broken words -* Internal functions:: Internal functions -* Test suite:: Test suite -@end menu - -@node GAS versions -@section GAS versions - -GAS has acquired layers of code over time. The original GAS only supported the -a.out object file format, with three sections. Support for multiple sections -has been added in two different ways. - -The preferred approach is to use the version of GAS created when the symbol -@code{BFD_ASSEMBLER} is defined. The other versions of GAS are documented for -historical purposes, and to help anybody who has to debug code written for -them. - -The type @code{segT} is used to represent a section in code which must work -with all versions of GAS. - -@menu -* Original GAS:: Original GAS version -* MANY_SEGMENTS:: MANY_SEGMENTS gas version -* BFD_ASSEMBLER:: BFD_ASSEMBLER gas version -@end menu - -@node Original GAS -@subsection Original GAS - -The original GAS only supported the a.out object file format with three -sections: @samp{.text}, @samp{.data}, and @samp{.bss}. This is the version of -GAS that is compiled if neither @code{BFD_ASSEMBLER} nor @code{MANY_SEGMENTS} -is defined. This version of GAS is still used for the m68k-aout target, and -perhaps others. - -This version of GAS should not be used for any new development. - -There is still code that is specific to this version of GAS, notably in -@file{write.c}. There is no way for this code to loop through all the -sections; it simply looks at global variables like @code{text_frag_root} and -@code{data_frag_root}. - -The type @code{segT} is an enum. - -@node MANY_SEGMENTS -@subsection MANY_SEGMENTS gas version -@cindex MANY_SEGMENTS - -The @code{MANY_SEGMENTS} version of gas is only used for COFF. It uses the BFD -library, but it writes out all the data itself using @code{bfd_write}. This -version of gas supports up to 40 normal sections. The section names are stored -in the @code{seg_name} array. Other information is stored in the -@code{segment_info} array. - -The type @code{segT} is an enum. Code that wants to examine all the sections -can use a @code{segT} variable as loop index from @code{SEG_E0} up to but not -including @code{SEG_UNKNOWN}. - -Most of the code specific to this version of GAS is in the file -@file{config/obj-coff.c}, in the portion of that file that is compiled when -@code{BFD_ASSEMBLER} is not defined. - -This version of GAS is still used for several COFF targets. - -@node BFD_ASSEMBLER -@subsection BFD_ASSEMBLER gas version -@cindex BFD_ASSEMBLER - -The preferred version of GAS is the @code{BFD_ASSEMBLER} version. In this -version of GAS, the output file is a normal BFD, and the BFD routines are used -to generate the output. - -@code{BFD_ASSEMBLER} will automatically be used for certain targets, including -those that use the ELF, ECOFF, and SOM object file formats, and also all Alpha, -MIPS, PowerPC, and SPARC targets. You can force the use of -@code{BFD_ASSEMBLER} for other targets with the configure option -@samp{--enable-bfd-assembler}; however, it has not been tested for many -targets, and can not be assumed to work. - -@node Data types -@section Data types -@cindex internals, data types - -This section describes some fundamental GAS data types. - -@menu -* Symbols:: The symbolS structure -* Expressions:: The expressionS structure -* Fixups:: The fixS structure -* Frags:: The fragS structure -@end menu - -@node Symbols -@subsection Symbols -@cindex internals, symbols -@cindex symbols, internal -@cindex symbolS structure - -The definition for the symbol structure, @code{symbolS}, is located in -@file{struc-symbol.h}. - -In general, the fields of this structure may not be referred to directly. -Instead, you must use one of the accessor functions defined in @file{symbol.h}. -These accessor functions should work for any GAS version. - -Symbol structures contain the following fields: - -@table @code -@item sy_value -This is an @code{expressionS} that describes the value of the symbol. It might -refer to one or more other symbols; if so, its true value may not be known -until @code{resolve_symbol_value} is called with @var{finalize_syms} non-zero -in @code{write_object_file}. - -The expression is often simply a constant. Before @code{resolve_symbol_value} -is called with @var{finalize_syms} set, the value is the offset from the frag -(@pxref{Frags}). Afterward, the frag address has been added in. - -@item sy_resolved -This field is non-zero if the symbol's value has been completely resolved. It -is used during the final pass over the symbol table. - -@item sy_resolving -This field is used to detect loops while resolving the symbol's value. - -@item sy_used_in_reloc -This field is non-zero if the symbol is used by a relocation entry. If a local -symbol is used in a relocation entry, it must be possible to redirect those -relocations to other symbols, or this symbol cannot be removed from the final -symbol list. - -@item sy_next -@itemx sy_previous -These pointers to other @code{symbolS} structures describe a singly or doubly -linked list. (If @code{SYMBOLS_NEED_BACKPOINTERS} is not defined, the -@code{sy_previous} field will be omitted; @code{SYMBOLS_NEED_BACKPOINTERS} is -always defined if @code{BFD_ASSEMBLER}.) These fields should be accessed with -the @code{symbol_next} and @code{symbol_previous} macros. - -@item sy_frag -This points to the frag (@pxref{Frags}) that this symbol is attached to. - -@item sy_used -Whether the symbol is used as an operand or in an expression. Note: Not all of -the backends keep this information accurate; backends which use this bit are -responsible for setting it when a symbol is used in backend routines. - -@item sy_mri_common -Whether the symbol is an MRI common symbol created by the @code{COMMON} -pseudo-op when assembling in MRI mode. - -@item bsym -If @code{BFD_ASSEMBLER} is defined, this points to the BFD @code{asymbol} that -will be used in writing the object file. - -@item sy_name_offset -(Only used if @code{BFD_ASSEMBLER} is not defined.) This is the position of -the symbol's name in the string table of the object file. On some formats, -this will start at position 4, with position 0 reserved for unnamed symbols. -This field is not used until @code{write_object_file} is called. - -@item sy_symbol -(Only used if @code{BFD_ASSEMBLER} is not defined.) This is the -format-specific symbol structure, as it would be written into the object file. - -@item sy_number -(Only used if @code{BFD_ASSEMBLER} is not defined.) This is a 24-bit symbol -number, for use in constructing relocation table entries. - -@item sy_obj -This format-specific data is of type @code{OBJ_SYMFIELD_TYPE}. If no macro by -that name is defined in @file{obj-format.h}, this field is not defined. - -@item sy_tc -This processor-specific data is of type @code{TC_SYMFIELD_TYPE}. If no macro -by that name is defined in @file{targ-cpu.h}, this field is not defined. - -@end table - -Here is a description of the accessor functions. These should be used rather -than referring to the fields of @code{symbolS} directly. - -@table @code -@item S_SET_VALUE -@cindex S_SET_VALUE -Set the symbol's value. - -@item S_GET_VALUE -@cindex S_GET_VALUE -Get the symbol's value. This will cause @code{resolve_symbol_value} to be -called if necessary. - -@item S_SET_SEGMENT -@cindex S_SET_SEGMENT -Set the section of the symbol. - -@item S_GET_SEGMENT -@cindex S_GET_SEGMENT -Get the symbol's section. - -@item S_GET_NAME -@cindex S_GET_NAME -Get the name of the symbol. - -@item S_SET_NAME -@cindex S_SET_NAME -Set the name of the symbol. - -@item S_IS_EXTERNAL -@cindex S_IS_EXTERNAL -Return non-zero if the symbol is externally visible. - -@item S_IS_EXTERN -@cindex S_IS_EXTERN -A synonym for @code{S_IS_EXTERNAL}. Don't use it. - -@item S_IS_WEAK -@cindex S_IS_WEAK -Return non-zero if the symbol is weak. - -@item S_IS_COMMON -@cindex S_IS_COMMON -Return non-zero if this is a common symbol. Common symbols are sometimes -represented as undefined symbols with a value, in which case this function will -not be reliable. - -@item S_IS_DEFINED -@cindex S_IS_DEFINED -Return non-zero if this symbol is defined. This function is not reliable when -called on a common symbol. - -@item S_IS_DEBUG -@cindex S_IS_DEBUG -Return non-zero if this is a debugging symbol. - -@item S_IS_LOCAL -@cindex S_IS_LOCAL -Return non-zero if this is a local assembler symbol which should not be -included in the final symbol table. Note that this is not the opposite of -@code{S_IS_EXTERNAL}. The @samp{-L} assembler option affects the return value -of this function. - -@item S_SET_EXTERNAL -@cindex S_SET_EXTERNAL -Mark the symbol as externally visible. - -@item S_CLEAR_EXTERNAL -@cindex S_CLEAR_EXTERNAL -Mark the symbol as not externally visible. - -@item S_SET_WEAK -@cindex S_SET_WEAK -Mark the symbol as weak. - -@item S_GET_TYPE -@item S_GET_DESC -@item S_GET_OTHER -@cindex S_GET_TYPE -@cindex S_GET_DESC -@cindex S_GET_OTHER -Get the @code{type}, @code{desc}, and @code{other} fields of the symbol. These -are only defined for object file formats for which they make sense (primarily -a.out). - -@item S_SET_TYPE -@item S_SET_DESC -@item S_SET_OTHER -@cindex S_SET_TYPE -@cindex S_SET_DESC -@cindex S_SET_OTHER -Set the @code{type}, @code{desc}, and @code{other} fields of the symbol. These -are only defined for object file formats for which they make sense (primarily -a.out). - -@item S_GET_SIZE -@cindex S_GET_SIZE -Get the size of a symbol. This is only defined for object file formats for -which it makes sense (primarily ELF). - -@item S_SET_SIZE -@cindex S_SET_SIZE -Set the size of a symbol. This is only defined for object file formats for -which it makes sense (primarily ELF). - -@item symbol_get_value_expression -@cindex symbol_get_value_expression -Get a pointer to an @code{expressionS} structure which represents the value of -the symbol as an expression. - -@item symbol_set_value_expression -@cindex symbol_set_value_expression -Set the value of a symbol to an expression. - -@item symbol_set_frag -@cindex symbol_set_frag -Set the frag where a symbol is defined. - -@item symbol_get_frag -@cindex symbol_get_frag -Get the frag where a symbol is defined. - -@item symbol_mark_used -@cindex symbol_mark_used -Mark a symbol as having been used in an expression. - -@item symbol_clear_used -@cindex symbol_clear_used -Clear the mark indicating that a symbol was used in an expression. - -@item symbol_used_p -@cindex symbol_used_p -Return whether a symbol was used in an expression. - -@item symbol_mark_used_in_reloc -@cindex symbol_mark_used_in_reloc -Mark a symbol as having been used by a relocation. - -@item symbol_clear_used_in_reloc -@cindex symbol_clear_used_in_reloc -Clear the mark indicating that a symbol was used in a relocation. - -@item symbol_used_in_reloc_p -@cindex symbol_used_in_reloc_p -Return whether a symbol was used in a relocation. - -@item symbol_mark_mri_common -@cindex symbol_mark_mri_common -Mark a symbol as an MRI common symbol. - -@item symbol_clear_mri_common -@cindex symbol_clear_mri_common -Clear the mark indicating that a symbol is an MRI common symbol. - -@item symbol_mri_common_p -@cindex symbol_mri_common_p -Return whether a symbol is an MRI common symbol. - -@item symbol_mark_written -@cindex symbol_mark_written -Mark a symbol as having been written. - -@item symbol_clear_written -@cindex symbol_clear_written -Clear the mark indicating that a symbol was written. - -@item symbol_written_p -@cindex symbol_written_p -Return whether a symbol was written. - -@item symbol_mark_resolved -@cindex symbol_mark_resolved -Mark a symbol as having been resolved. - -@item symbol_resolved_p -@cindex symbol_resolved_p -Return whether a symbol has been resolved. - -@item symbol_section_p -@cindex symbol_section_p -Return whether a symbol is a section symbol. - -@item symbol_equated_p -@cindex symbol_equated_p -Return whether a symbol is equated to another symbol. - -@item symbol_constant_p -@cindex symbol_constant_p -Return whether a symbol has a constant value, including being an offset within -some frag. - -@item symbol_get_bfdsym -@cindex symbol_get_bfdsym -Return the BFD symbol associated with a symbol. - -@item symbol_set_bfdsym -@cindex symbol_set_bfdsym -Set the BFD symbol associated with a symbol. - -@item symbol_get_obj -@cindex symbol_get_obj -Return a pointer to the @code{OBJ_SYMFIELD_TYPE} field of a symbol. - -@item symbol_set_obj -@cindex symbol_set_obj -Set the @code{OBJ_SYMFIELD_TYPE} field of a symbol. - -@item symbol_get_tc -@cindex symbol_get_tc -Return a pointer to the @code{TC_SYMFIELD_TYPE} field of a symbol. - -@item symbol_set_tc -@cindex symbol_set_tc -Set the @code{TC_SYMFIELD_TYPE} field of a symbol. - -@end table - -When @code{BFD_ASSEMBLER} is defined, GAS attempts to store local -symbols--symbols which will not be written to the output file--using a -different structure, @code{struct local_symbol}. This structure can only -represent symbols whose value is an offset within a frag. - -Code outside of the symbol handler will always deal with @code{symbolS} -structures and use the accessor functions. The accessor functions correctly -deal with local symbols. @code{struct local_symbol} is much smaller than -@code{symbolS} (which also automatically creates a bfd @code{asymbol} -structure), so this saves space when assembling large files. - -The first field of @code{symbolS} is @code{bsym}, the pointer to the BFD -symbol. The first field of @code{struct local_symbol} is a pointer which is -always set to NULL. This is how the symbol accessor functions can distinguish -local symbols from ordinary symbols. The symbol accessor functions -automatically convert a local symbol into an ordinary symbol when necessary. - -@node Expressions -@subsection Expressions -@cindex internals, expressions -@cindex expressions, internal -@cindex expressionS structure - -Expressions are stored in an @code{expressionS} structure. The structure is -defined in @file{expr.h}. - -@cindex expression -The macro @code{expression} will create an @code{expressionS} structure based -on the text found at the global variable @code{input_line_pointer}. - -@cindex make_expr_symbol -@cindex expr_symbol_where -A single @code{expressionS} structure can represent a single operation. -Complex expressions are formed by creating @dfn{expression symbols} and -combining them in @code{expressionS} structures. An expression symbol is -created by calling @code{make_expr_symbol}. An expression symbol should -naturally never appear in a symbol table, and the implementation of -@code{S_IS_LOCAL} (@pxref{Symbols}) reflects that. The function -@code{expr_symbol_where} returns non-zero if a symbol is an expression symbol, -and also returns the file and line for the expression which caused it to be -created. - -The @code{expressionS} structure has two symbol fields, a number field, an -operator field, and a field indicating whether the number is unsigned. - -The operator field is of type @code{operatorT}, and describes how to interpret -the other fields; see the definition in @file{expr.h} for the possibilities. - -An @code{operatorT} value of @code{O_big} indicates either a floating point -number, stored in the global variable @code{generic_floating_point_number}, or -an integer too large to store in an @code{offsetT} type, stored in the global -array @code{generic_bignum}. This rather inflexible approach makes it -impossible to use floating point numbers or large expressions in complex -expressions. - -@node Fixups -@subsection Fixups -@cindex internals, fixups -@cindex fixups -@cindex fixS structure - -A @dfn{fixup} is basically anything which can not be resolved in the first -pass. Sometimes a fixup can be resolved by the end of the assembly; if not, -the fixup becomes a relocation entry in the object file. - -@cindex fix_new -@cindex fix_new_exp -A fixup is created by a call to @code{fix_new} or @code{fix_new_exp}. Both -take a frag (@pxref{Frags}), a position within the frag, a size, an indication -of whether the fixup is PC relative, and a type. In a @code{BFD_ASSEMBLER} -GAS, the type is nominally a @code{bfd_reloc_code_real_type}, but several -targets use other type codes to represent fixups that can not be described as -relocations. - -The @code{fixS} structure has a number of fields, several of which are obsolete -or are only used by a particular target. The important fields are: - -@table @code -@item fx_frag -The frag (@pxref{Frags}) this fixup is in. - -@item fx_where -The location within the frag where the fixup occurs. - -@item fx_addsy -The symbol this fixup is against. Typically, the value of this symbol is added -into the object contents. This may be NULL. - -@item fx_subsy -The value of this symbol is subtracted from the object contents. This is -normally NULL. - -@item fx_offset -A number which is added into the fixup. - -@item fx_addnumber -Some CPU backends use this field to convey information between -@code{md_apply_fix3} and @code{tc_gen_reloc}. The machine independent code does -not use it. - -@item fx_next -The next fixup in the section. - -@item fx_r_type -The type of the fixup. This field is only defined if @code{BFD_ASSEMBLER}, or -if the target defines @code{NEED_FX_R_TYPE}. - -@item fx_size -The size of the fixup. This is mostly used for error checking. - -@item fx_pcrel -Whether the fixup is PC relative. - -@item fx_done -Non-zero if the fixup has been applied, and no relocation entry needs to be -generated. - -@item fx_file -@itemx fx_line -The file and line where the fixup was created. - -@item tc_fix_data -This has the type @code{TC_FIX_TYPE}, and is only defined if the target defines -that macro. -@end table - -@node Frags -@subsection Frags -@cindex internals, frags -@cindex frags -@cindex fragS structure. - -The @code{fragS} structure is defined in @file{as.h}. Each frag represents a -portion of the final object file. As GAS reads the source file, it creates -frags to hold the data that it reads. At the end of the assembly the frags and -fixups are processed to produce the final contents. - -@table @code -@item fr_address -The address of the frag. This is not set until the assembler rescans the list -of all frags after the entire input file is parsed. The function -@code{relax_segment} fills in this field. - -@item fr_next -Pointer to the next frag in this (sub)section. - -@item fr_fix -Fixed number of characters we know we're going to emit to the output file. May -be zero. - -@item fr_var -Variable number of characters we may output, after the initial @code{fr_fix} -characters. May be zero. - -@item fr_offset -The interpretation of this field is controlled by @code{fr_type}. Generally, -if @code{fr_var} is non-zero, this is a repeat count: the @code{fr_var} -characters are output @code{fr_offset} times. - -@item line -Holds line number info when an assembler listing was requested. - -@item fr_type -Relaxation state. This field indicates the interpretation of @code{fr_offset}, -@code{fr_symbol} and the variable-length tail of the frag, as well as the -treatment it gets in various phases of processing. It does not affect the -initial @code{fr_fix} characters; they are always supposed to be output -verbatim (fixups aside). See below for specific values this field can have. - -@item fr_subtype -Relaxation substate. If the macro @code{md_relax_frag} isn't defined, this is -assumed to be an index into @code{TC_GENERIC_RELAX_TABLE} for the generic -relaxation code to process (@pxref{Relaxation}). If @code{md_relax_frag} is -defined, this field is available for any use by the CPU-specific code. - -@item fr_symbol -This normally indicates the symbol to use when relaxing the frag according to -@code{fr_type}. - -@item fr_opcode -Points to the lowest-addressed byte of the opcode, for use in relaxation. - -@item tc_frag_data -Target specific fragment data of type TC_FRAG_TYPE. -Only present if @code{TC_FRAG_TYPE} is defined. - -@item fr_file -@itemx fr_line -The file and line where this frag was last modified. - -@item fr_literal -Declared as a one-character array, this last field grows arbitrarily large to -hold the actual contents of the frag. -@end table - -These are the possible relaxation states, provided in the enumeration type -@code{relax_stateT}, and the interpretations they represent for the other -fields: - -@table @code -@item rs_align -@itemx rs_align_code -The start of the following frag should be aligned on some boundary. In this -frag, @code{fr_offset} is the logarithm (base 2) of the alignment in bytes. -(For example, if alignment on an 8-byte boundary were desired, @code{fr_offset} -would have a value of 3.) The variable characters indicate the fill pattern to -be used. The @code{fr_subtype} field holds the maximum number of bytes to skip -when doing this alignment. If more bytes are needed, the alignment is not -done. An @code{fr_subtype} value of 0 means no maximum, which is the normal -case. Target backends can use @code{rs_align_code} to handle certain types of -alignment differently. - -@item rs_broken_word -This indicates that ``broken word'' processing should be done (@pxref{Broken -words}). If broken word processing is not necessary on the target machine, -this enumerator value will not be defined. - -@item rs_cfa -This state is used to implement exception frame optimizations. The -@code{fr_symbol} is an expression symbol for the subtraction which may be -relaxed. The @code{fr_opcode} field holds the frag for the preceding command -byte. The @code{fr_offset} field holds the offset within that frag. The -@code{fr_subtype} field is used during relaxation to hold the current size of -the frag. - -@item rs_fill -The variable characters are to be repeated @code{fr_offset} times. If -@code{fr_offset} is 0, this frag has a length of @code{fr_fix}. Most frags -have this type. - -@item rs_leb128 -This state is used to implement the DWARF ``little endian base 128'' -variable length number format. The @code{fr_symbol} is always an expression -symbol, as constant expressions are emitted directly. The @code{fr_offset} -field is used during relaxation to hold the previous size of the number so -that we can determine if the fragment changed size. - -@item rs_machine_dependent -Displacement relaxation is to be done on this frag. The target is indicated by -@code{fr_symbol} and @code{fr_offset}, and @code{fr_subtype} indicates the -particular machine-specific addressing mode desired. @xref{Relaxation}. - -@item rs_org -The start of the following frag should be pushed back to some specific offset -within the section. (Some assemblers use the value as an absolute address; GAS -does not handle final absolute addresses, but rather requires that the linker -set them.) The offset is given by @code{fr_symbol} and @code{fr_offset}; one -character from the variable-length tail is used as the fill character. -@end table - -@cindex frchainS structure -A chain of frags is built up for each subsection. The data structure -describing a chain is called a @code{frchainS}, and contains the following -fields: - -@table @code -@item frch_root -Points to the first frag in the chain. May be NULL if there are no frags in -this chain. -@item frch_last -Points to the last frag in the chain, or NULL if there are none. -@item frch_next -Next in the list of @code{frchainS} structures. -@item frch_seg -Indicates the section this frag chain belongs to. -@item frch_subseg -Subsection (subsegment) number of this frag chain. -@item fix_root, fix_tail -(Defined only if @code{BFD_ASSEMBLER} is defined). Point to first and last -@code{fixS} structures associated with this subsection. -@item frch_obstack -Not currently used. Intended to be used for frag allocation for this -subsection. This should reduce frag generation caused by switching sections. -@item frch_frag_now -The current frag for this subsegment. -@end table - -A @code{frchainS} corresponds to a subsection; each section has a list of -@code{frchainS} records associated with it. In most cases, only one subsection -of each section is used, so the list will only be one element long, but any -processing of frag chains should be prepared to deal with multiple chains per -section. - -After the input files have been completely processed, and no more frags are to -be generated, the frag chains are joined into one per section for further -processing. After this point, it is safe to operate on one chain per section. - -The assembler always has a current frag, named @code{frag_now}. More space is -allocated for the current frag using the @code{frag_more} function; this -returns a pointer to the amount of requested space. The function -@code{frag_room} says by how much the current frag can be extended. -Relaxing is done using variant frags allocated by @code{frag_var} -or @code{frag_variant} (@pxref{Relaxation}). - -@node GAS processing -@section What GAS does when it runs -@cindex internals, overview - -This is a quick look at what an assembler run looks like. - -@itemize @bullet -@item -The assembler initializes itself by calling various init routines. - -@item -For each source file, the @code{read_a_source_file} function reads in the file -and parses it. The global variable @code{input_line_pointer} points to the -current text; it is guaranteed to be correct up to the end of the line, but not -farther. - -@item -For each line, the assembler passes labels to the @code{colon} function, and -isolates the first word. If it looks like a pseudo-op, the word is looked up -in the pseudo-op hash table @code{po_hash} and dispatched to a pseudo-op -routine. Otherwise, the target dependent @code{md_assemble} routine is called -to parse the instruction. - -@item -When pseudo-ops or instructions output data, they add it to a frag, calling -@code{frag_more} to get space to store it in. - -@item -Pseudo-ops and instructions can also output fixups created by @code{fix_new} or -@code{fix_new_exp}. - -@item -For certain targets, instructions can create variant frags which are used to -store relaxation information (@pxref{Relaxation}). - -@item -When the input file is finished, the @code{write_object_file} routine is -called. It assigns addresses to all the frags (@code{relax_segment}), resolves -all the fixups (@code{fixup_segment}), resolves all the symbol values (using -@code{resolve_symbol_value}), and finally writes out the file (in the -@code{BFD_ASSEMBLER} case, this is done by simply calling @code{bfd_close}). -@end itemize - -@node Porting GAS -@section Porting GAS -@cindex porting - -Each GAS target specifies two main things: the CPU file and the object format -file. Two main switches in the @file{configure.in} file handle this. The -first switches on CPU type to set the shell variable @code{cpu_type}. The -second switches on the entire target to set the shell variable @code{fmt}. - -The configure script uses the value of @code{cpu_type} to select two files in -the @file{config} directory: @file{tc-@var{CPU}.c} and @file{tc-@var{CPU}.h}. -The configuration process will create a file named @file{targ-cpu.h} in the -build directory which includes @file{tc-@var{CPU}.h}. - -The configure script also uses the value of @code{fmt} to select two files: -@file{obj-@var{fmt}.c} and @file{obj-@var{fmt}.h}. The configuration process -will create a file named @file{obj-format.h} in the build directory which -includes @file{obj-@var{fmt}.h}. - -You can also set the emulation in the configure script by setting the @code{em} -variable. Normally the default value of @samp{generic} is fine. The -configuration process will create a file named @file{targ-env.h} in the build -directory which includes @file{te-@var{em}.h}. - -There is a special case for COFF. For historical reason, the GNU COFF -assembler doesn't follow the documented behavior on certain debug symbols for -the compatibility with other COFF assemblers. A port can define -@code{STRICTCOFF} in the configure script to make the GNU COFF assembler -to follow the documented behavior. - -Porting GAS to a new CPU requires writing the @file{tc-@var{CPU}} files. -Porting GAS to a new object file format requires writing the -@file{obj-@var{fmt}} files. There is sometimes some interaction between these -two files, but it is normally minimal. - -The best approach is, of course, to copy existing files. The documentation -below assumes that you are looking at existing files to see usage details. - -These interfaces have grown over time, and have never been carefully thought -out or designed. Nothing about the interfaces described here is cast in stone. -It is possible that they will change from one version of the assembler to the -next. Also, new macros are added all the time as they are needed. - -@menu -* CPU backend:: Writing a CPU backend -* Object format backend:: Writing an object format backend -* Emulations:: Writing emulation files -@end menu - -@node CPU backend -@subsection Writing a CPU backend -@cindex CPU backend -@cindex @file{tc-@var{CPU}} - -The CPU backend files are the heart of the assembler. They are the only parts -of the assembler which actually know anything about the instruction set of the -processor. - -You must define a reasonably small list of macros and functions in the CPU -backend files. You may define a large number of additional macros in the CPU -backend files, not all of which are documented here. You must, of course, -define macros in the @file{.h} file, which is included by every assembler -source file. You may define the functions as macros in the @file{.h} file, or -as functions in the @file{.c} file. - -@table @code -@item TC_@var{CPU} -@cindex TC_@var{CPU} -By convention, you should define this macro in the @file{.h} file. For -example, @file{tc-m68k.h} defines @code{TC_M68K}. You might have to use this -if it is necessary to add CPU specific code to the object format file. - -@item TARGET_FORMAT -This macro is the BFD target name to use when creating the output file. This -will normally depend upon the @code{OBJ_@var{FMT}} macro. - -@item TARGET_ARCH -This macro is the BFD architecture to pass to @code{bfd_set_arch_mach}. - -@item TARGET_MACH -This macro is the BFD machine number to pass to @code{bfd_set_arch_mach}. If -it is not defined, GAS will use 0. - -@item TARGET_BYTES_BIG_ENDIAN -You should define this macro to be non-zero if the target is big endian, and -zero if the target is little endian. - -@item md_shortopts -@itemx md_longopts -@itemx md_longopts_size -@itemx md_parse_option -@itemx md_show_usage -@itemx md_after_parse_args -@cindex md_shortopts -@cindex md_longopts -@cindex md_longopts_size -@cindex md_parse_option -@cindex md_show_usage -@cindex md_after_parse_args -GAS uses these variables and functions during option processing. -@code{md_shortopts} is a @code{const char *} which GAS adds to the machine -independent string passed to @code{getopt}. @code{md_longopts} is a -@code{struct option []} which GAS adds to the machine independent long options -passed to @code{getopt}; you may use @code{OPTION_MD_BASE}, defined in -@file{as.h}, as the start of a set of long option indices, if necessary. -@code{md_longopts_size} is a @code{size_t} holding the size @code{md_longopts}. -GAS will call @code{md_parse_option} whenever @code{getopt} returns an -unrecognized code, presumably indicating a special code value which appears in -@code{md_longopts}. GAS will call @code{md_show_usage} when a usage message is -printed; it should print a description of the machine specific options. -@code{md_after_pase_args}, if defined, is called after all options are -processed, to let the backend override settings done by the generic option -parsing. - -@item md_begin -@cindex md_begin -GAS will call this function at the start of the assembly, after the command -line arguments have been parsed and all the machine independent initializations -have been completed. - -@item md_cleanup -@cindex md_cleanup -If you define this macro, GAS will call it at the end of each input file. - -@item md_assemble -@cindex md_assemble -GAS will call this function for each input line which does not contain a -pseudo-op. The argument is a null terminated string. The function should -assemble the string as an instruction with operands. Normally -@code{md_assemble} will do this by calling @code{frag_more} and writing out -some bytes (@pxref{Frags}). @code{md_assemble} will call @code{fix_new} to -create fixups as needed (@pxref{Fixups}). Targets which need to do special -purpose relaxation will call @code{frag_var}. - -@item md_pseudo_table -@cindex md_pseudo_table -This is a const array of type @code{pseudo_typeS}. It is a mapping from -pseudo-op names to functions. You should use this table to implement -pseudo-ops which are specific to the CPU. - -@item tc_conditional_pseudoop -@cindex tc_conditional_pseudoop -If this macro is defined, GAS will call it with a @code{pseudo_typeS} argument. -It should return non-zero if the pseudo-op is a conditional which controls -whether code is assembled, such as @samp{.if}. GAS knows about the normal -conditional pseudo-ops, and you should normally not have to define this macro. - -@item comment_chars -@cindex comment_chars -This is a null terminated @code{const char} array of characters which start a -comment. - -@item tc_comment_chars -@cindex tc_comment_chars -If this macro is defined, GAS will use it instead of @code{comment_chars}. - -@item tc_symbol_chars -@cindex tc_symbol_chars -If this macro is defined, it is a pointer to a null terminated list of -characters which may appear in an operand. GAS already assumes that all -alphanumberic characters, and @samp{$}, @samp{.}, and @samp{_} may appear in an -operand (see @samp{symbol_chars} in @file{app.c}). This macro may be defined -to treat additional characters as appearing in an operand. This affects the -way in which GAS removes whitespace before passing the string to -@samp{md_assemble}. - -@item line_comment_chars -@cindex line_comment_chars -This is a null terminated @code{const char} array of characters which start a -comment when they appear at the start of a line. - -@item line_separator_chars -@cindex line_separator_chars -This is a null terminated @code{const char} array of characters which separate -lines (null and newline are such characters by default, and need not be -listed in this array). Note that line_separator_chars do not separate lines -if found in a comment, such as after a character in line_comment_chars or -comment_chars. - -@item EXP_CHARS -@cindex EXP_CHARS -This is a null terminated @code{const char} array of characters which may be -used as the exponent character in a floating point number. This is normally -@code{"eE"}. - -@item FLT_CHARS -@cindex FLT_CHARS -This is a null terminated @code{const char} array of characters which may be -used to indicate a floating point constant. A zero followed by one of these -characters is assumed to be followed by a floating point number; thus they -operate the way that @code{0x} is used to indicate a hexadecimal constant. -Usually this includes @samp{r} and @samp{f}. - -@item LEX_AT -@cindex LEX_AT -You may define this macro to the lexical type of the @kbd{@@} character. The -default is zero. - -Lexical types are a combination of @code{LEX_NAME} and @code{LEX_BEGIN_NAME}, -both defined in @file{read.h}. @code{LEX_NAME} indicates that the character -may appear in a name. @code{LEX_BEGIN_NAME} indicates that the character may -appear at the beginning of a name. - -@item LEX_BR -@cindex LEX_BR -You may define this macro to the lexical type of the brace characters @kbd{@{}, -@kbd{@}}, @kbd{[}, and @kbd{]}. The default value is zero. - -@item LEX_PCT -@cindex LEX_PCT -You may define this macro to the lexical type of the @kbd{%} character. The -default value is zero. - -@item LEX_QM -@cindex LEX_QM -You may define this macro to the lexical type of the @kbd{?} character. The -default value it zero. - -@item LEX_DOLLAR -@cindex LEX_DOLLAR -You may define this macro to the lexical type of the @kbd{$} character. The -default value is @code{LEX_NAME | LEX_BEGIN_NAME}. - -@item NUMBERS_WITH_SUFFIX -@cindex NUMBERS_WITH_SUFFIX -When this macro is defined to be non-zero, the parser allows the radix of a -constant to be indicated with a suffix. Valid suffixes are binary (B), -octal (Q), and hexadecimal (H). Case is not significant. - -@item SINGLE_QUOTE_STRINGS -@cindex SINGLE_QUOTE_STRINGS -If you define this macro, GAS will treat single quotes as string delimiters. -Normally only double quotes are accepted as string delimiters. - -@item NO_STRING_ESCAPES -@cindex NO_STRING_ESCAPES -If you define this macro, GAS will not permit escape sequences in a string. - -@item ONLY_STANDARD_ESCAPES -@cindex ONLY_STANDARD_ESCAPES -If you define this macro, GAS will warn about the use of nonstandard escape -sequences in a string. - -@item md_start_line_hook -@cindex md_start_line_hook -If you define this macro, GAS will call it at the start of each line. - -@item LABELS_WITHOUT_COLONS -@cindex LABELS_WITHOUT_COLONS -If you define this macro, GAS will assume that any text at the start of a line -is a label, even if it does not have a colon. - -@item TC_START_LABEL -@itemx TC_START_LABEL_WITHOUT_COLON -@cindex TC_START_LABEL -You may define this macro to control what GAS considers to be a label. The -default definition is to accept any name followed by a colon character. - -@item TC_START_LABEL_WITHOUT_COLON -@cindex TC_START_LABEL_WITHOUT_COLON -Same as TC_START_LABEL, but should be used instead of TC_START_LABEL when -LABELS_WITHOUT_COLONS is defined. - -@item NO_PSEUDO_DOT -@cindex NO_PSEUDO_DOT -If you define this macro, GAS will not require pseudo-ops to start with a -@kbd{.} character. - -@item TC_EQUAL_IN_INSN -@cindex TC_EQUAL_IN_INSN -If you define this macro, it should return nonzero if the instruction is -permitted to contain an @kbd{=} character. GAS will call it with two -arguments, the character before the @kbd{=} character, and the value of -@code{input_line_pointer} at that point. GAS uses this macro to decide if a -@kbd{=} is an assignment or an instruction. - -@item TC_EOL_IN_INSN -@cindex TC_EOL_IN_INSN -If you define this macro, it should return nonzero if the current input line -pointer should be treated as the end of a line. - -@item TC_CASE_SENSITIVE -@cindex TC_CASE_SENSITIVE -Define this macro if instruction mnemonics and pseudos are case sensitive. -The default is to have it undefined giving case insensitive names. - -@item md_parse_name -@cindex md_parse_name -If this macro is defined, GAS will call it for any symbol found in an -expression. You can define this to handle special symbols in a special way. -If a symbol always has a certain value, you should normally enter it in the -symbol table, perhaps using @code{reg_section}. - -@item md_undefined_symbol -@cindex md_undefined_symbol -GAS will call this function when a symbol table lookup fails, before it -creates a new symbol. Typically this would be used to supply symbols whose -name or value changes dynamically, possibly in a context sensitive way. -Predefined symbols with fixed values, such as register names or condition -codes, are typically entered directly into the symbol table when @code{md_begin} -is called. One argument is passed, a @code{char *} for the symbol. - -@item md_operand -@cindex md_operand -GAS will call this function with one argument, an @code{expressionS} -pointer, for any expression that can not be recognized. When the function -is called, @code{input_line_pointer} will point to the start of the -expression. - -@item tc_unrecognized_line -@cindex tc_unrecognized_line -If you define this macro, GAS will call it when it finds a line that it can not -parse. - -@item md_do_align -@cindex md_do_align -You may define this macro to handle an alignment directive. GAS will call it -when the directive is seen in the input file. For example, the i386 backend -uses this to generate efficient nop instructions of varying lengths, depending -upon the number of bytes that the alignment will skip. - -@item HANDLE_ALIGN -@cindex HANDLE_ALIGN -You may define this macro to do special handling for an alignment directive. -GAS will call it at the end of the assembly. - -@item TC_IMPLICIT_LCOMM_ALIGNMENT (@var{size}, @var{p2var}) -@cindex TC_IMPLICIT_LCOMM_ALIGNMENT -An @code{.lcomm} directive with no explicit alignment parameter will use this -macro to set @var{p2var} to the alignment that a request for @var{size} bytes -will have. The alignment is expressed as a power of two. If no alignment -should take place, the macro definition should do nothing. Some targets define -a @code{.bss} directive that is also affected by this macro. The default -definition will set @var{p2var} to the truncated power of two of sizes up to -eight bytes. - -@item md_flush_pending_output -@cindex md_flush_pending_output -If you define this macro, GAS will call it each time it skips any space because of a -space filling or alignment or data allocation pseudo-op. - -@item TC_PARSE_CONS_EXPRESSION -@cindex TC_PARSE_CONS_EXPRESSION -You may define this macro to parse an expression used in a data allocation -pseudo-op such as @code{.word}. You can use this to recognize relocation -directives that may appear in such directives. - -@item BITFIELD_CONS_EXPRESSION -@cindex BITFIELD_CONS_EXPRESSION -If you define this macro, GAS will recognize bitfield instructions in data -allocation pseudo-ops, as used on the i960. - -@item REPEAT_CONS_EXPRESSION -@cindex REPEAT_CONS_EXPRESSION -If you define this macro, GAS will recognize repeat counts in data allocation -pseudo-ops, as used on the MIPS. - -@item md_cons_align -@cindex md_cons_align -You may define this macro to do any special alignment before a data allocation -pseudo-op. - -@item TC_CONS_FIX_NEW -@cindex TC_CONS_FIX_NEW -You may define this macro to generate a fixup for a data allocation pseudo-op. - -@item TC_INIT_FIX_DATA (@var{fixp}) -@cindex TC_INIT_FIX_DATA -A C statement to initialize the target specific fields of fixup @var{fixp}. -These fields are defined with the @code{TC_FIX_TYPE} macro. - -@item TC_FIX_DATA_PRINT (@var{stream}, @var{fixp}) -@cindex TC_FIX_DATA_PRINT -A C statement to output target specific debugging information for -fixup @var{fixp} to @var{stream}. This macro is called by @code{print_fixup}. - -@item TC_FRAG_INIT (@var{fragp}) -@cindex TC_FRAG_INIT -A C statement to initialize the target specific fields of frag @var{fragp}. -These fields are defined with the @code{TC_FRAG_TYPE} macro. - -@item md_number_to_chars -@cindex md_number_to_chars -This should just call either @code{number_to_chars_bigendian} or -@code{number_to_chars_littleendian}, whichever is appropriate. On targets like -the MIPS which support options to change the endianness, which function to call -is a runtime decision. On other targets, @code{md_number_to_chars} can be a -simple macro. - -@item md_atof (@var{type},@var{litP},@var{sizeP}) -@cindex md_atof -This function is called to convert an ASCII string into a floating point value -in format used by the CPU. It takes three arguments. The first is @var{type} -which is a byte describing the type of floating point number to be created. -Possible values are @var{'f'} or @var{'s'} for single precision, @var{'d'} or -@var{'r'} for double precision and @var{'x'} or @var{'p'} for extended -precision. Either lower or upper case versions of these letters can be used. - -The second parameter is @var{litP} which is a pointer to a byte array where the -converted value should be stored. The third argument is @var{sizeP}, which is -a pointer to a integer that should be filled in with the number of -@var{LITTLENUM}s emitted into the byte array. (@var{LITTLENUM} is defined in -gas/bignum.h). The function should return NULL upon success or an error string -upon failure. - -@item TC_LARGEST_EXPONENT_IS_NORMAL -@cindex TC_LARGEST_EXPONENT_IS_NORMAL (@var{precision}) -This macro is used only by @file{atof-ieee.c}. It should evaluate to true -if floats of the given precision use the largest exponent for normal numbers -instead of NaNs and infinities. @var{precision} is @samp{F_PRECISION} for -single precision, @samp{D_PRECISION} for double precision, or -@samp{X_PRECISION} for extended double precision. - -The macro has a default definition which returns 0 for all cases. - -@item md_reloc_size -@cindex md_reloc_size -This variable is only used in the original version of gas (not -@code{BFD_ASSEMBLER} and not @code{MANY_SEGMENTS}). It holds the size of a -relocation entry. - -@item WORKING_DOT_WORD -@itemx md_short_jump_size -@itemx md_long_jump_size -@itemx md_create_short_jump -@itemx md_create_long_jump -@itemx TC_CHECK_ADJUSTED_BROKEN_DOT_WORD -@cindex WORKING_DOT_WORD -@cindex md_short_jump_size -@cindex md_long_jump_size -@cindex md_create_short_jump -@cindex md_create_long_jump -@cindex TC_CHECK_ADJUSTED_BROKEN_DOT_WORD -If @code{WORKING_DOT_WORD} is defined, GAS will not do broken word processing -(@pxref{Broken words}). Otherwise, you should set @code{md_short_jump_size} to -the size of a short jump (a jump that is just long enough to jump around a -number of long jumps) and @code{md_long_jump_size} to the size of a long jump -(a jump that can go anywhere in the function). You should define -@code{md_create_short_jump} to create a short jump around a number of long -jumps, and define @code{md_create_long_jump} to create a long jump. -If defined, the macro TC_CHECK_ADJUSTED_BROKEN_DOT_WORD will be called for each -adjusted word just before the word is output. The macro takes two arguments, -an @code{addressT} with the adjusted word and a pointer to the current -@code{struct broken_word}. - -@item md_estimate_size_before_relax -@cindex md_estimate_size_before_relax -This function returns an estimate of the size of a @code{rs_machine_dependent} -frag before any relaxing is done. It may also create any necessary -relocations. - -@item md_relax_frag -@cindex md_relax_frag -This macro may be defined to relax a frag. GAS will call this with the -segment, the frag, and the change in size of all previous frags; -@code{md_relax_frag} should return the change in size of the frag. -@xref{Relaxation}. - -@item TC_GENERIC_RELAX_TABLE -@cindex TC_GENERIC_RELAX_TABLE -If you do not define @code{md_relax_frag}, you may define -@code{TC_GENERIC_RELAX_TABLE} as a table of @code{relax_typeS} structures. The -machine independent code knows how to use such a table to relax PC relative -references. See @file{tc-m68k.c} for an example. @xref{Relaxation}. - -@item md_prepare_relax_scan -@cindex md_prepare_relax_scan -If defined, it is a C statement that is invoked prior to scanning -the relax table. - -@item LINKER_RELAXING_SHRINKS_ONLY -@cindex LINKER_RELAXING_SHRINKS_ONLY -If you define this macro, and the global variable @samp{linkrelax} is set -(because of a command line option, or unconditionally in @code{md_begin}), a -@samp{.align} directive will cause extra space to be allocated. The linker can -then discard this space when relaxing the section. - -@item TC_LINKRELAX_FIXUP (@var{segT}) -@cindex TC_LINKRELAX_FIXUP -If defined, this macro allows control over whether fixups for a -given section will be processed when the @var{linkrelax} variable is -set. The macro is given the N_TYPE bits for the section in its -@var{segT} argument. If the macro evaluates to a non-zero value -then the fixups will be converted into relocs, otherwise they will -be passed to @var{md_apply_fix3} as normal. - -@item md_convert_frag -@cindex md_convert_frag -GAS will call this for each rs_machine_dependent fragment. -The instruction is completed using the data from the relaxation pass. -It may also create any necessary relocations. -@xref{Relaxation}. - -@item TC_FINALIZE_SYMS_BEFORE_SIZE_SEG -@cindex TC_FINALIZE_SYMS_BEFORE_SIZE_SEG -Specifies the value to be assigned to @code{finalize_syms} before the function -@code{size_segs} is called. Since @code{size_segs} calls @code{cvt_frag_to_fill} -which can call @code{md_convert_frag}, this constant governs whether the symbols -accessed in @code{md_convert_frag} will be fully resolved. In particular it -governs whether local symbols will have been resolved, and had their frag -information removed. Depending upon the processing performed by -@code{md_convert_frag} the frag information may or may not be necessary, as may -the resolved values of the symbols. The default value is 1. - -@item TC_VALIDATE_FIX (@var{fixP}, @var{seg}, @var{skip}) -@cindex TC_VALIDATE_FIX -This macro is evaluated for each fixup (when @var{linkrelax} is not set). -It may be used to change the fixup in @code{struct fix *@var{fixP}} before -the generic code sees it, or to fully process the fixup. In the latter case, -a @code{goto @var{skip}} will bypass the generic code. - -@item md_apply_fix3 (@var{fixP}, @var{valP}, @var{seg}) -@cindex md_apply_fix3 -GAS will call this for each fixup that passes the @code{TC_VALIDATE_FIX} test -when @var{linkrelax} is not set. It should store the correct value in the -object file. @code{struct fix *@var{fixP}} is the fixup @code{md_apply_fix3} -is operating on. @code{valueT *@var{valP}} is the value to store into the -object files, or at least is the generic code's best guess. Specifically, -*@var{valP} is the value of the fixup symbol, perhaps modified by -@code{MD_APPLY_SYM_VALUE}, plus @code{@var{fixP}->fx_offset} (symbol addend), -less @code{MD_PCREL_FROM_SECTION} for pc-relative fixups. -@code{segT @var{seg}} is the section the fix is in. -@code{fixup_segment} performs a generic overflow check on *@var{valP} after -@code{md_apply_fix3} returns. If the overflow check is relevant for the target -machine, then @code{md_apply_fix3} should modify *@var{valP}, typically to the -value stored in the object file. - -@item TC_FORCE_RELOCATION (@var{fix}) -@cindex TC_FORCE_RELOCATION -If this macro returns non-zero, it guarantees that a relocation will be emitted -even when the value can be resolved locally, as @code{fixup_segment} tries to -reduce the number of relocations emitted. For example, a fixup expression -against an absolute symbol will normally not require a reloc. If undefined, -a default of @w{@code{(S_FORCE_RELOC ((@var{fix})->fx_addsy))}} is used. - -@item TC_FORCE_RELOCATION_ABS (@var{fix}) -@cindex TC_FORCE_RELOCATION_ABS -Like @code{TC_FORCE_RELOCATION}, but used only for fixup expressions against an -absolute symbol. If undefined, @code{TC_FORCE_RELOCATION} will be used. - -@item TC_FORCE_RELOCATION_LOCAL (@var{fix}) -@cindex TC_FORCE_RELOCATION_LOCAL -Like @code{TC_FORCE_RELOCATION}, but used only for fixup expressions against a -symbol in the current section. If undefined, fixups that are not -@code{fx_pcrel} or @code{fx_plt} or for which @code{TC_FORCE_RELOCATION} -returns non-zero, will emit relocs. - -@item TC_FORCE_RELOCATION_SUB_SAME (@var{fix}, @var{seg}) -@cindex TC_FORCE_RELOCATION_SUB_SAME -This macro controls resolution of fixup expressions involving the -difference of two symbols in the same section. If this macro returns zero, -the subtrahend will be resolved and @code{fx_subsy} set to @code{NULL} for -@code{md_apply_fix3}. If undefined, the default of -@w{@code{! SEG_NORMAL (@var{seg}) || TC_FORCE_RELOCATION (@var{fix})}} will -be used. - -@item TC_FORCE_RELOCATION_SUB_ABS (@var{fix}) -@cindex TC_FORCE_RELOCATION_SUB_ABS -Like @code{TC_FORCE_RELOCATION_SUB_SAME}, but used when the subtrahend is an -absolute symbol. If the macro is undefined a default of @code{0} is used. - -@item TC_FORCE_RELOCATION_SUB_LOCAL (@var{fix}) -@cindex TC_FORCE_RELOCATION_SUB_LOCAL -Like @code{TC_FORCE_RELOCATION_SUB_ABS}, but the subtrahend is a symbol in the -same section as the fixup. - -@item TC_VALIDATE_FIX_SUB (@var{fix}) -@cindex TC_VALIDATE_FIX_SUB -This macro is evaluated for any fixup with a @code{fx_subsy} that -@code{fixup_segment} cannot reduce to a number. If the macro returns -@code{false} an error will be reported. - -@item MD_APPLY_SYM_VALUE (@var{fix}) -@cindex MD_APPLY_SYM_VALUE -This macro controls whether the symbol value becomes part of the value passed -to @code{md_apply_fix3}. If the macro is undefined, or returns non-zero, the -symbol value will be included. For ELF, a suitable definition might simply be -@code{0}, because ELF relocations don't include the symbol value in the addend. - -@item S_FORCE_RELOC (@var{sym}, @var{strict}) -@cindex S_FORCE_RELOC -This macro (or function, for @code{BFD_ASSEMBLER} gas) returns true for symbols -that should not be reduced to section symbols or eliminated from expressions, -because they may be overridden by the linker. ie. for symbols that are -undefined or common, and when @var{strict} is set, weak, or global (for ELF -assemblers that support ELF shared library linking semantics). - -@item EXTERN_FORCE_RELOC -@cindex EXTERN_FORCE_RELOC -This macro controls whether @code{S_FORCE_RELOC} returns true for global -symbols. If undefined, the default is @code{true} for ELF assemblers, and -@code{false} for non-ELF. - -@item tc_gen_reloc -@cindex tc_gen_reloc -A @code{BFD_ASSEMBLER} GAS will call this to generate a reloc. GAS will pass -the resulting reloc to @code{bfd_install_relocation}. This currently works -poorly, as @code{bfd_install_relocation} often does the wrong thing, and -instances of @code{tc_gen_reloc} have been written to work around the problems, -which in turns makes it difficult to fix @code{bfd_install_relocation}. - -@item RELOC_EXPANSION_POSSIBLE -@cindex RELOC_EXPANSION_POSSIBLE -If you define this macro, it means that @code{tc_gen_reloc} may return multiple -relocation entries for a single fixup. In this case, the return value of -@code{tc_gen_reloc} is a pointer to a null terminated array. - -@item MAX_RELOC_EXPANSION -@cindex MAX_RELOC_EXPANSION -You must define this if @code{RELOC_EXPANSION_POSSIBLE} is defined; it -indicates the largest number of relocs which @code{tc_gen_reloc} may return for -a single fixup. - -@item tc_fix_adjustable -@cindex tc_fix_adjustable -You may define this macro to indicate whether a fixup against a locally defined -symbol should be adjusted to be against the section symbol. It should return a -non-zero value if the adjustment is acceptable. - -@item MD_PCREL_FROM_SECTION (@var{fixp}, @var{section}) -@cindex MD_PCREL_FROM_SECTION -If you define this macro, it should return the position from which the PC -relative adjustment for a PC relative fixup should be made. On many -processors, the base of a PC relative instruction is the next instruction, -so this macro would return the length of an instruction, plus the address of -the PC relative fixup. The latter can be calculated as -@var{fixp}->fx_where + @var{fixp}->fx_frag->fr_address . - -@item md_pcrel_from -@cindex md_pcrel_from -This is the default value of @code{MD_PCREL_FROM_SECTION}. The difference is -that @code{md_pcrel_from} does not take a section argument. - -@item tc_frob_label -@cindex tc_frob_label -If you define this macro, GAS will call it each time a label is defined. - -@item md_section_align -@cindex md_section_align -GAS will call this function for each section at the end of the assembly, to -permit the CPU backend to adjust the alignment of a section. The function -must take two arguments, a @code{segT} for the section and a @code{valueT} -for the size of the section, and return a @code{valueT} for the rounded -size. - -@item md_macro_start -@cindex md_macro_start -If defined, GAS will call this macro when it starts to include a macro -expansion. @code{macro_nest} indicates the current macro nesting level, which -includes the one being expanded. - -@item md_macro_info -@cindex md_macro_info -If defined, GAS will call this macro after the macro expansion has been -included in the input and after parsing the macro arguments. The single -argument is a pointer to the macro processing's internal representation of the -macro (macro_entry *), which includes expansion of the formal arguments. - -@item md_macro_end -@cindex md_macro_end -Complement to md_macro_start. If defined, it is called when finished -processing an inserted macro expansion, just before decrementing macro_nest. - -@item DOUBLEBAR_PARALLEL -@cindex DOUBLEBAR_PARALLEL -Affects the preprocessor so that lines containing '||' don't have their -whitespace stripped following the double bar. This is useful for targets that -implement parallel instructions. - -@item KEEP_WHITE_AROUND_COLON -@cindex KEEP_WHITE_AROUND_COLON -Normally, whitespace is compressed and removed when, in the presence of the -colon, the adjoining tokens can be distinguished. This option affects the -preprocessor so that whitespace around colons is preserved. This is useful -when colons might be removed from the input after preprocessing but before -assembling, so that adjoining tokens can still be distinguished if there is -whitespace, or concatenated if there is not. - -@item tc_frob_section -@cindex tc_frob_section -If you define this macro, a @code{BFD_ASSEMBLER} GAS will call it for each -section at the end of the assembly. - -@item tc_frob_file_before_adjust -@cindex tc_frob_file_before_adjust -If you define this macro, GAS will call it after the symbol values are -resolved, but before the fixups have been changed from local symbols to section -symbols. - -@item tc_frob_symbol -@cindex tc_frob_symbol -If you define this macro, GAS will call it for each symbol. You can indicate -that the symbol should not be included in the object file by defining this -macro to set its second argument to a non-zero value. - -@item tc_frob_file -@cindex tc_frob_file -If you define this macro, GAS will call it after the symbol table has been -completed, but before the relocations have been generated. - -@item tc_frob_file_after_relocs -If you define this macro, GAS will call it after the relocs have been -generated. - -@item md_post_relax_hook -If you define this macro, GAS will call it after relaxing and sizing the -segments. - -@item LISTING_HEADER -A string to use on the header line of a listing. The default value is simply -@code{"GAS LISTING"}. - -@item LISTING_WORD_SIZE -The number of bytes to put into a word in a listing. This affects the way the -bytes are clumped together in the listing. For example, a value of 2 might -print @samp{1234 5678} where a value of 1 would print @samp{12 34 56 78}. The -default value is 4. - -@item LISTING_LHS_WIDTH -The number of words of data to print on the first line of a listing for a -particular source line, where each word is @code{LISTING_WORD_SIZE} bytes. The -default value is 1. - -@item LISTING_LHS_WIDTH_SECOND -Like @code{LISTING_LHS_WIDTH}, but applying to the second and subsequent line -of the data printed for a particular source line. The default value is 1. - -@item LISTING_LHS_CONT_LINES -The maximum number of continuation lines to print in a listing for a particular -source line. The default value is 4. - -@item LISTING_RHS_WIDTH -The maximum number of characters to print from one line of the input file. The -default value is 100. - -@item TC_COFF_SECTION_DEFAULT_ATTRIBUTES -@cindex TC_COFF_SECTION_DEFAULT_ATTRIBUTES -The COFF @code{.section} directive will use the value of this macro to set -a new section's attributes when a directive has no valid flags or when the -flag is @code{w}. The default value of the macro is @code{SEC_LOAD | SEC_DATA}. - -@item DWARF2_FORMAT () -@cindex DWARF2_FORMAT -If you define this, it should return one of @code{dwarf2_format_32bit}, -@code{dwarf2_format_64bit}, or @code{dwarf2_format_64bit_irix} to indicate -the size of internal DWARF section offsets and the format of the DWARF initial -length fields. When @code{dwarf2_format_32bit} is returned, the initial -length field will be 4 bytes long and section offsets are 32 bits in size. -For @code{dwarf2_format_64bit} and @code{dwarf2_format_64bit_irix}, section -offsets are 64 bits in size, but the initial length field differs. An 8 byte -initial length is indicated by @code{dwarf2_format_64bit_irix} and -@code{dwarf2_format_64bit} indicates a 12 byte initial length field in -which the first four bytes are 0xffffffff and the next 8 bytes are -the section's length. - -If you don't define this, @code{dwarf2_format_32bit} will be used as -the default. - -This define only affects @code{.debug_info} and @code{.debug_line} -sections generated by the assembler. DWARF 2 sections generated by -other tools will be unaffected by this setting. - -@item DWARF2_ADDR_SIZE (@var{bfd}) -@cindex DWARF2_ADDR_SIZE -It should return the size of an address, as it should be represented in -debugging info. If you don't define this macro, the default definition uses -the number of bits per address, as defined in @var{bfd}, divided by 8. - -@end table - -@node Object format backend -@subsection Writing an object format backend -@cindex object format backend -@cindex @file{obj-@var{fmt}} - -As with the CPU backend, the object format backend must define a few things, -and may define some other things. The interface to the object format backend -is generally simpler; most of the support for an object file format consists of -defining a number of pseudo-ops. - -The object format @file{.h} file must include @file{targ-cpu.h}. - -This section will only define the @code{BFD_ASSEMBLER} version of GAS. It is -impossible to support a new object file format using any other version anyhow, -as the original GAS version only supports a.out, and the @code{MANY_SEGMENTS} -GAS version only supports COFF. - -@table @code -@item OBJ_@var{format} -@cindex OBJ_@var{format} -By convention, you should define this macro in the @file{.h} file. For -example, @file{obj-elf.h} defines @code{OBJ_ELF}. You might have to use this -if it is necessary to add object file format specific code to the CPU file. - -@item obj_begin -If you define this macro, GAS will call it at the start of the assembly, after -the command line arguments have been parsed and all the machine independent -initializations have been completed. - -@item obj_app_file -@cindex obj_app_file -If you define this macro, GAS will invoke it when it sees a @code{.file} -pseudo-op or a @samp{#} line as used by the C preprocessor. - -@item OBJ_COPY_SYMBOL_ATTRIBUTES -@cindex OBJ_COPY_SYMBOL_ATTRIBUTES -You should define this macro to copy object format specific information from -one symbol to another. GAS will call it when one symbol is equated to -another. - -@item obj_sec_sym_ok_for_reloc -@cindex obj_sec_sym_ok_for_reloc -You may define this macro to indicate that it is OK to use a section symbol in -a relocation entry. If it is not, GAS will define a new symbol at the start -of a section. - -@item EMIT_SECTION_SYMBOLS -@cindex EMIT_SECTION_SYMBOLS -You should define this macro with a zero value if you do not want to include -section symbols in the output symbol table. The default value for this macro -is one. - -@item obj_adjust_symtab -@cindex obj_adjust_symtab -If you define this macro, GAS will invoke it just before setting the symbol -table of the output BFD. For example, the COFF support uses this macro to -generate a @code{.file} symbol if none was generated previously. - -@item SEPARATE_STAB_SECTIONS -@cindex SEPARATE_STAB_SECTIONS -You may define this macro to a nonzero value to indicate that stabs should be -placed in separate sections, as in ELF. - -@item INIT_STAB_SECTION -@cindex INIT_STAB_SECTION -You may define this macro to initialize the stabs section in the output file. - -@item OBJ_PROCESS_STAB -@cindex OBJ_PROCESS_STAB -You may define this macro to do specific processing on a stabs entry. - -@item obj_frob_section -@cindex obj_frob_section -If you define this macro, GAS will call it for each section at the end of the -assembly. - -@item obj_frob_file_before_adjust -@cindex obj_frob_file_before_adjust -If you define this macro, GAS will call it after the symbol values are -resolved, but before the fixups have been changed from local symbols to section -symbols. - -@item obj_frob_symbol -@cindex obj_frob_symbol -If you define this macro, GAS will call it for each symbol. You can indicate -that the symbol should not be included in the object file by defining this -macro to set its second argument to a non-zero value. - -@item obj_frob_file -@cindex obj_frob_file -If you define this macro, GAS will call it after the symbol table has been -completed, but before the relocations have been generated. - -@item obj_frob_file_after_relocs -If you define this macro, GAS will call it after the relocs have been -generated. - -@item SET_SECTION_RELOCS (@var{sec}, @var{relocs}, @var{n}) -@cindex SET_SECTION_RELOCS -If you define this, it will be called after the relocations have been set for -the section @var{sec}. The list of relocations is in @var{relocs}, and the -number of relocations is in @var{n}. This is only used with -@code{BFD_ASSEMBLER}. -@end table - -@node Emulations -@subsection Writing emulation files - -Normally you do not have to write an emulation file. You can just use -@file{te-generic.h}. - -If you do write your own emulation file, it must include @file{obj-format.h}. - -An emulation file will often define @code{TE_@var{EM}}; this may then be used -in other files to change the output. - -@node Relaxation -@section Relaxation -@cindex relaxation - -@dfn{Relaxation} is a generic term used when the size of some instruction or -data depends upon the value of some symbol or other data. - -GAS knows to relax a particular type of PC relative relocation using a table. -You can also define arbitrarily complex forms of relaxation yourself. - -@menu -* Relaxing with a table:: Relaxing with a table -* General relaxing:: General relaxing -@end menu - -@node Relaxing with a table -@subsection Relaxing with a table - -If you do not define @code{md_relax_frag}, and you do define -@code{TC_GENERIC_RELAX_TABLE}, GAS will relax @code{rs_machine_dependent} frags -based on the frag subtype and the displacement to some specified target -address. The basic idea is that several machines have different addressing -modes for instructions that can specify different ranges of values, with -successive modes able to access wider ranges, including the entirety of the -previous range. Smaller ranges are assumed to be more desirable (perhaps the -instruction requires one word instead of two or three); if this is not the -case, don't describe the smaller-range, inferior mode. - -The @code{fr_subtype} field of a frag is an index into a CPU-specific -relaxation table. That table entry indicates the range of values that can be -stored, the number of bytes that will have to be added to the frag to -accommodate the addressing mode, and the index of the next entry to examine if -the value to be stored is outside the range accessible by the current -addressing mode. The @code{fr_symbol} field of the frag indicates what symbol -is to be accessed; the @code{fr_offset} field is added in. - -If the @code{TC_PCREL_ADJUST} macro is defined, which currently should only happen -for the NS32k family, the @code{TC_PCREL_ADJUST} macro is called on the frag to -compute an adjustment to be made to the displacement. - -The value fitted by the relaxation code is always assumed to be a displacement -from the current frag. (More specifically, from @code{fr_fix} bytes into the -frag.) -@ignore -This seems kinda silly. What about fitting small absolute values? I suppose -@code{md_assemble} is supposed to take care of that, but if the operand is a -difference between symbols, it might not be able to, if the difference was not -computable yet. -@end ignore - -The end of the relaxation sequence is indicated by a ``next'' value of 0. This -means that the first entry in the table can't be used. - -For some configurations, the linker can do relaxing within a section of an -object file. If call instructions of various sizes exist, the linker can -determine which should be used in each instance, when a symbol's value is -resolved. In order for the linker to avoid wasting space and having to insert -no-op instructions, it must be able to expand or shrink the section contents -while still preserving intra-section references and meeting alignment -requirements. - -For the i960 using b.out format, no expansion is done; instead, each -@samp{.align} directive causes extra space to be allocated, enough that when -the linker is relaxing a section and removing unneeded space, it can discard -some or all of this extra padding and cause the following data to be correctly -aligned. - -For the H8/300, I think the linker expands calls that can't reach, and doesn't -worry about alignment issues; the cpu probably never needs any significant -alignment beyond the instruction size. - -The relaxation table type contains these fields: - -@table @code -@item long rlx_forward -Forward reach, must be non-negative. -@item long rlx_backward -Backward reach, must be zero or negative. -@item rlx_length -Length in bytes of this addressing mode. -@item rlx_more -Index of the next-longer relax state, or zero if there is no next relax state. -@end table - -The relaxation is done in @code{relax_segment} in @file{write.c}. The -difference in the length fields between the original mode and the one finally -chosen by the relaxing code is taken as the size by which the current frag will -be increased in size. For example, if the initial relaxing mode has a length -of 2 bytes, and because of the size of the displacement, it gets upgraded to a -mode with a size of 6 bytes, it is assumed that the frag will grow by 4 bytes. -(The initial two bytes should have been part of the fixed portion of the frag, -since it is already known that they will be output.) This growth must be -effected by @code{md_convert_frag}; it should increase the @code{fr_fix} field -by the appropriate size, and fill in the appropriate bytes of the frag. -(Enough space for the maximum growth should have been allocated in the call to -frag_var as the second argument.) - -If relocation records are needed, they should be emitted by -@code{md_estimate_size_before_relax}. This function should examine the target -symbol of the supplied frag and correct the @code{fr_subtype} of the frag if -needed. When this function is called, if the symbol has not yet been defined, -it will not become defined later; however, its value may still change if the -section it is in gets relaxed. - -Usually, if the symbol is in the same section as the frag (given by the -@var{sec} argument), the narrowest likely relaxation mode is stored in -@code{fr_subtype}, and that's that. - -If the symbol is undefined, or in a different section (and therefore movable -to an arbitrarily large distance), the largest available relaxation mode is -specified, @code{fix_new} is called to produce the relocation record, -@code{fr_fix} is increased to include the relocated field (remember, this -storage was allocated when @code{frag_var} was called), and @code{frag_wane} is -called to convert the frag to an @code{rs_fill} frag with no variant part. -Sometimes changing addressing modes may also require rewriting the instruction. -It can be accessed via @code{fr_opcode} or @code{fr_fix}. - -If you generate frags separately for the basic insn opcode and any relaxable -operands, do not call @code{fix_new} thinking you can emit fixups for the -opcode field from the relaxable frag. It is not guaranteed to be the same frag. -If you need to emit fixups for the opcode field from inspection of the -relaxable frag, then you need to generate a common frag for both the basic -opcode and relaxable fields, or you need to provide the frag for the opcode to -pass to @code{fix_new}. The latter can be done for example by defining -@code{TC_FRAG_TYPE} to include a pointer to it and defining @code{TC_FRAG_INIT} -to set the pointer. - -Sometimes @code{fr_var} is increased instead, and @code{frag_wane} is not -called. I'm not sure, but I think this is to keep @code{fr_fix} referring to -an earlier byte, and @code{fr_subtype} set to @code{rs_machine_dependent} so -that @code{md_convert_frag} will get called. - -@node General relaxing -@subsection General relaxing - -If using a simple table is not suitable, you may implement arbitrarily complex -relaxation semantics yourself. For example, the MIPS backend uses this to emit -different instruction sequences depending upon the size of the symbol being -accessed. - -When you assemble an instruction that may need relaxation, you should allocate -a frag using @code{frag_var} or @code{frag_variant} with a type of -@code{rs_machine_dependent}. You should store some sort of information in the -@code{fr_subtype} field so that you can figure out what to do with the frag -later. - -When GAS reaches the end of the input file, it will look through the frags and -work out their final sizes. - -GAS will first call @code{md_estimate_size_before_relax} on each -@code{rs_machine_dependent} frag. This function must return an estimated size -for the frag. - -GAS will then loop over the frags, calling @code{md_relax_frag} on each -@code{rs_machine_dependent} frag. This function should return the change in -size of the frag. GAS will keep looping over the frags until none of the frags -changes size. - -@node Broken words -@section Broken words -@cindex internals, broken words -@cindex broken words - -Some compilers, including GCC, will sometimes emit switch tables specifying -16-bit @code{.word} displacements to branch targets, and branch instructions -that load entries from that table to compute the target address. If this is -done on a 32-bit machine, there is a chance (at least with really large -functions) that the displacement will not fit in 16 bits. The assembler -handles this using a concept called @dfn{broken words}. This idea is well -named, since there is an implied promise that the 16-bit field will in fact -hold the specified displacement. - -If broken word processing is enabled, and a situation like this is encountered, -the assembler will insert a jump instruction into the instruction stream, close -enough to be reached with the 16-bit displacement. This jump instruction will -transfer to the real desired target address. Thus, as long as the @code{.word} -value really is used as a displacement to compute an address to jump to, the -net effect will be correct (minus a very small efficiency cost). If -@code{.word} directives with label differences for values are used for other -purposes, however, things may not work properly. For targets which use broken -words, the @samp{-K} option will warn when a broken word is discovered. - -The broken word code is turned off by the @code{WORKING_DOT_WORD} macro. It -isn't needed if @code{.word} emits a value large enough to contain an address -(or, more correctly, any possible difference between two addresses). - -@node Internal functions -@section Internal functions - -This section describes basic internal functions used by GAS. - -@menu -* Warning and error messages:: Warning and error messages -* Hash tables:: Hash tables -@end menu - -@node Warning and error messages -@subsection Warning and error messages - -@deftypefun @{@} int had_warnings (void) -@deftypefunx @{@} int had_errors (void) -Returns non-zero if any warnings or errors, respectively, have been printed -during this invocation. -@end deftypefun - -@deftypefun @{@} void as_perror (const char *@var{gripe}, const char *@var{filename}) -Displays a BFD or system error, then clears the error status. -@end deftypefun - -@deftypefun @{@} void as_tsktsk (const char *@var{format}, ...) -@deftypefunx @{@} void as_warn (const char *@var{format}, ...) -@deftypefunx @{@} void as_bad (const char *@var{format}, ...) -@deftypefunx @{@} void as_fatal (const char *@var{format}, ...) -These functions display messages about something amiss with the input file, or -internal problems in the assembler itself. The current file name and line -number are printed, followed by the supplied message, formatted using -@code{vfprintf}, and a final newline. - -An error indicated by @code{as_bad} will result in a non-zero exit status when -the assembler has finished. Calling @code{as_fatal} will result in immediate -termination of the assembler process. -@end deftypefun - -@deftypefun @{@} void as_warn_where (char *@var{file}, unsigned int @var{line}, const char *@var{format}, ...) -@deftypefunx @{@} void as_bad_where (char *@var{file}, unsigned int @var{line}, const char *@var{format}, ...) -These variants permit specification of the file name and line number, and are -used when problems are detected when reprocessing information saved away when -processing some earlier part of the file. For example, fixups are processed -after all input has been read, but messages about fixups should refer to the -original filename and line number that they are applicable to. -@end deftypefun - -@deftypefun @{@} void fprint_value (FILE *@var{file}, valueT @var{val}) -@deftypefunx @{@} void sprint_value (char *@var{buf}, valueT @var{val}) -These functions are helpful for converting a @code{valueT} value into printable -format, in case it's wider than modes that @code{*printf} can handle. If the -type is narrow enough, a decimal number will be produced; otherwise, it will be -in hexadecimal. The value itself is not examined to make this determination. -@end deftypefun - -@node Hash tables -@subsection Hash tables -@cindex hash tables - -@deftypefun @{@} @{struct hash_control *@} hash_new (void) -Creates the hash table control structure. -@end deftypefun - -@deftypefun @{@} void hash_die (struct hash_control *) -Destroy a hash table. -@end deftypefun - -@deftypefun @{@} PTR hash_delete (struct hash_control *, const char *) -Deletes entry from the hash table, returns the value it had. -@end deftypefun - -@deftypefun @{@} PTR hash_replace (struct hash_control *, const char *, PTR) -Updates the value for an entry already in the table, returning the old value. -If no entry was found, just returns NULL. -@end deftypefun - -@deftypefun @{@} @{const char *@} hash_insert (struct hash_control *, const char *, PTR) -Inserting a value already in the table is an error. -Returns an error message or NULL. -@end deftypefun - -@deftypefun @{@} @{const char *@} hash_jam (struct hash_control *, const char *, PTR) -Inserts if the value isn't already present, updates it if it is. -@end deftypefun - -@node Test suite -@section Test suite -@cindex test suite - -The test suite is kind of lame for most processors. Often it only checks to -see if a couple of files can be assembled without the assembler reporting any -errors. For more complete testing, write a test which either examines the -assembler listing, or runs @code{objdump} and examines its output. For the -latter, the TCL procedure @code{run_dump_test} may come in handy. It takes the -base name of a file, and looks for @file{@var{file}.d}. This file should -contain as its initial lines a set of variable settings in @samp{#} comments, -in the form: - -@example - #@var{varname}: @var{value} -@end example - -The @var{varname} may be @code{objdump}, @code{nm}, or @code{as}, in which case -it specifies the options to be passed to the specified programs. Exactly one -of @code{objdump} or @code{nm} must be specified, as that also specifies which -program to run after the assembler has finished. If @var{varname} is -@code{source}, it specifies the name of the source file; otherwise, -@file{@var{file}.s} is used. If @var{varname} is @code{name}, it specifies the -name of the test to be used in the @code{pass} or @code{fail} messages. - -The non-commented parts of the file are interpreted as regular expressions, one -per line. Blank lines in the @code{objdump} or @code{nm} output are skipped, -as are blank lines in the @code{.d} file; the other lines are tested to see if -the regular expression matches the program output. If it does not, the test -fails. - -Note that this means the tests must be modified if the @code{objdump} output -style is changed. - -@bye -@c Local Variables: -@c fill-column: 79 -@c End: |