README for GAS

A number of things have changed since version 1 and the wonderful
world of gas looks very different.  There's still a lot of irrelevant
garbage lying around that will be cleaned up in time.  Documentation
is scarce, as are logs of the changes made since the last gas release.
My apologies, and I'll try to get something useful.

Unpacking and Installation - Summary
====================================

See ../binutils/README.

To build just the assembler, make the target all-gas.

Documentation
=============

The GAS release includes texinfo source for its manual, which can be processed
into `info' or `dvi' forms.

The DVI form is suitable for printing or displaying; the commands for doing
this vary from system to system.  On many systems, `lpr -d' will print a DVI
file.  On others, you may need to run a program such as `dvips' to convert the
DVI file into a form your system can print.

If you wish to build the DVI file, you will need to have TeX installed on your
system.  You can rebuild it by typing:

	cd gas/doc
	make as.dvi

The Info form is viewable with the GNU Emacs `info' subsystem, or the
stand-alone `info' program, available as part of the GNU Texinfo distribution.
To build the info files, you will need the `makeinfo' program.  Type:

	cd gas/doc
	make info

Specifying names for hosts and targets
======================================

   The specifications used for hosts and targets in the `configure'
script are based on a three-part naming scheme, but some short
predefined aliases are also supported.  The full naming scheme encodes
three pieces of information in the following pattern:

     ARCHITECTURE-VENDOR-OS

   For example, you can use the alias `sun4' as a HOST argument or in a
`--target=TARGET' option.  The equivalent full name is
`sparc-sun-sunos4'.

   The `configure' script accompanying GAS does not provide any query
facility to list all supported host and target names or aliases.
`configure' calls the Bourne shell script `config.sub' to map
abbreviations to full names; you can read the script, if you wish, or
you can use it to test your guesses on abbreviations--for example:

     % sh config.sub sun4
     sparc-sun-sunos411
     % sh config.sub sun3
     m68k-sun-sunos411
     % sh config.sub decstation
     mips-dec-ultrix42
     % sh config.sub hp300bsd
     m68k-hp-bsd
     % sh config.sub i386v
     i386-unknown-sysv
     % sh config.sub i786v
     Invalid configuration `i786v': machine `i786v' not recognized


`configure' options
===================

   Here is a summary of the `configure' options and arguments that are
most often useful for building GAS.  `configure' also has several other
options not listed here.

     configure [--help]
               [--prefix=DIR]
               [--srcdir=PATH]
               [--host=HOST]
               [--target=TARGET]
               [--with-OPTION]
               [--enable-OPTION]

You may introduce options with a single `-' rather than `--' if you
prefer; but you may abbreviate option names if you use `--'.

`--help'
     Print a summary of the options to `configure', and exit.

`-prefix=DIR'
     Configure the source to install programs and files under directory
     `DIR'.

`--srcdir=PATH'
     Look for the package's source code in directory DIR.  Usually
     `configure' can determine that directory automatically.

`--host=HOST'
     Configure GAS to run on the specified HOST.  Normally the
     configure script can figure this out automatically.

     There is no convenient way to generate a list of all available
     hosts.

`--target=TARGET'
     Configure GAS for cross-assembling programs for the specified
     TARGET.  Without this option, GAS is configured to assemble .o files
     that run on the same machine (HOST) as GAS itself.

     There is no convenient way to generate a list of all available
     targets.

`--enable-OPTION'
     These flags tell the program or library being configured to
     configure itself differently from the default for the specified
     host/target combination.  See below for a list of `--enable'
     options recognized in the gas distribution.

`configure' accepts other options, for compatibility with configuring
other GNU tools recursively; but these are the only options that affect
GAS or its supporting libraries.

The `--enable' options recognized by software in the gas distribution are:

`--enable-targets=...'
     This causes one or more specified configurations to be added to those for
     which BFD support is compiled.  Currently gas cannot use any format other
     than its compiled-in default, so this option is not very useful.

`--enable-bfd-assembler'
     This causes the assembler to use the new code being merged into it to use
     BFD data structures internally, and use BFD for writing object files.
     For most targets, this isn't supported yet.  For most targets where it has
     been done, it's already the default.  So generally you won't need to use
     this option.

Supported platforms
===================

At this point I believe gas to be ANSI only code for most target cpu's.  That
is, there should be relatively few, if any host system dependencies.  So
porting (as a cross-assembler) to hosts not yet supported should be fairly
easy.  Porting to a new target shouldn't be too tough if it's a variant of one
already supported.

Native assembling should work on:

	sun3
	sun4
	386bsd
	bsd/386
	delta (m68k-sysv from Motorola)
	delta88 (m88k-sysv from Motorola)
	GNU/linux
	m68k hpux 8.0 (hpux 7.0 may be a problem)
	vax bsd, ultrix, vms
	hp9000s300
	decstation
	irix 4
	irix 5
	miniframe (m68k-sysv from Convergent Technologies)
	i386-aix (ps/2)
	hppa (hpux 4.3bsd, osf1)
	AIX
	unixware
	sco 3.2v4.2
	sco openserver 5.0 (a.k.a. 3.2v5.0 )
	sparc solaris
	ns32k (netbsd, lites)

I believe that gas as a cross-assembler can currently be targeted for
most of the above hosts, plus

        arm
	decstation-bsd (a.out format, to be used in BSD 4.4)
	ebmon29k
	go32 (DOS on i386, with DJGPP -- old a.out version)
	H8/300, H8/500 (Hitachi)
	i386-aix (ps/2)
	i960-coff
	mips ecoff (decstation-ultrix, iris, mips magnum, mips-idt-ecoff)
	Mitsubishi d10v and d30v
	nindy960
	powerpc EABI
	SH (Hitachi)
	sco386
	TI tic30 and tic80
	vax bsd or ultrix?
	vms
	vxworks68k
	vxworks960
	z8000 (Zilog)

MIPS ECOFF support has been added, but GAS will not run a C-style
preprocessor.  If you want that, rename your file to have a ".S" suffix, and
run gcc on it.  Or run "gcc -xassembler-with-cpp foo.s".

Support for ELF should work now for sparc, hppa, i386, alpha, m68k,
MIPS, powerpc.

Support for sequent (ns32k), tahoe, i860 may be suffering from bitrot.

If you try out gas on some host or target not listed above, please let me know
the results, so I can update the list.

Compiler Support Hacks
======================

On a few targets, the assembler has been modified to support a feature
that is potentially useful when assembling compiler output, but which
may confuse assembly language programmers.  If assembler encounters a
.word pseudo-op of the form symbol1-symbol2 (the difference of two
symbols), and the difference of those two symbols will not fit in 16
bits, the assembler will create a branch around a long jump to
symbol1, and insert this into the output directly before the next
label: The .word will (instead of containing garbage, or giving an
error message) contain (the address of the long jump)-symbol2.  This
allows the assembler to assemble jump tables that jump to locations
very far away into code that works properly.  If the next label is
more than 32K away from the .word, you lose (silently); RMS claims
this will never happen.  If the -K option is given, you will get a
warning message when this happens.


REPORTING BUGS IN GAS
=====================

Bugs in gas should be reported to:

   bug-binutils@gnu.org.

They may be cross-posted to gcc-bugs@gnu.org if they affect the use of
gas with gcc.  They should not be reported just to gcc-bugs, since not
all of the maintainers read that list.

See ../binutils/README for what we need in a bug report.

	This document explains a couple of things that are specific to VMS.
There are currently two "chapters", the first deals with cross-assembly
issues, and the second deals with the VMS debugger and GNU-CC.


***********************************************************************
****************** Notes for Cross Assembly with VMS ******************
***********************************************************************

	If you wish to build gas on a non-VMS system to cross-assemble,
you should use:

configure ${hosttype} -target=vms

and then follow the usual procedure.  The object files generated on
Unix will be correct from a binary point of view, but the real trick is
getting them to the VMS machine.  The format of the object file is
a variable-length record, but each record contains binary data.  gas
writes the records in the same format that VMS would expect,
namely a two-byte count followed by that number of bytes.

	If you try to copy the file to a VMS system using ftp, the ftp
protocol will screw up the file by looking for nulls (record terminator for
unix) and it will insert it's own record terminators at that point.  This
will obviously corrupt the file.

	If you try to transfer the file with ftp in binary mode, the
file itself will not be corrupt, but VMS will think that the file contains
fixed-length records of 512 bytes.  You can use the public-domain FILE
utility to change this with a command like:

$FILE foo.o/type=variable

If you do not have this utility available, the following program can be
used to perform this task:

	#include <fab.h>

	#define RME$C_SETRFM 1

	struct FAB * fab;

	main(int argc, char * argv[]){
		int i, status;
		fab = (struct FAB*) malloc(sizeof(struct FAB));
		*fab = cc$rms_fab;	/* initialize FAB*/
		fab->fab$b_fac = FAB$M_PUT;
		fab->fab$l_fop |= FAB$M_ESC;
		fab->fab$l_ctx = RME$C_SETRFM;
		fab->fab$w_ifi = 0;
		for(i=1;i<argc;i++){
		  printf("Setting %s to variable length records.\n",argv[i]);
		  fab->fab$l_fna = argv[i];
	       	  fab->fab$b_fns = strlen(argv[i]);
		  status = sys$open(fab,0,0);
		  if((status & 7) != 1) lib$signal(status);
		  fab->fab$b_rfm = FAB$C_VAR;
		  status = sys$modify(fab,0,0);
		  if((status & 7) != 1) lib$signal(status);
		  status = sys$close(fab,0,0);
		  if((status & 7) != 1) lib$signal(status);
		};
	}

	If you have NFS running on the VMS system, what you need to do
depends upon which NFS software you are running on the VMS system.  There
are a number of different TCP/IP packages for VMS available, and only very
limited testing has been performed.   In the tests that has been done so
far, the contents of the file will always be correct when transferring the
file via NFS, but the record attributes may or may not be correct.

	One proprietary TCP/IP/NFS package for VMS is known to
automatically fix the record attributes of the object file if you NFS mount
a unix disk from the VMS system, and if the file has a ".obj" extension on
the unix system.  Other TCP/IP packages might do this for you as well, but
they have not been checked.

No matter what method you use to get the file to the VMS system, it is
always a good idea to check to make sure that it is the correct type by
doing a "$dir/full" on the object file. The desired record attributes will
be "None".  Undesirable record attributes will be "Stream-LF" or anything
else.

Once you get the files on the VMS system, you can check their integrity
with the "$anal/obj" command.  (Naturally at some point you should rename
the .o files to .obj).  As far as the debugger is concerned, the records
will be correct, but the debugger will not be able to find the source files,
since it only has the file name, and not the full directory specification.
You must give the debugger some help by telling it which directories to
search for the individual files - once you have done this you should be
able to proceed normally.

	It is a good idea to use names for your files which will be valid
under VMS, since otherwise you will have no way of getting the debugger to
find the source file when deugging.

The reason for this is that the object file normally contins specific
information that the debugger can use to positively identify a file, and if
you are assembling on a unix system this information simply does not exist
in a meaningful way.  You must help the debugger by using the "SET FILE="
command to tell the debugger where to look for source files. The debugger
records will be correct, except that the debugger will not be initially
able to find the source files.  You can use the "SET FILE" command to tell
the debugger where to look for the source files.

I have only tested this with a SVr4 i486 machine, and everything seems to
work OK, with the limited testing that I have done.  Other machines may
or may not work.  You should read the chapters on cross-compilers in the gcc
manual before fooling with this.  Since gas does not need to do any floating
point arithmetic, the floating point constants that are generated here should
be correct - the only concern is with constant folding in the main compiler.
The range and precision of floats and doubles are similar on the 486 (with
a builtin 80387) and the VAX, although there is a factor of 2 to 4
difference in the range.  The double, as implemented on the 486, is quite
similar to the G_FLOAT on the VAX.

***********************************************************************
****************** Notes for using GNU CC with the VMS debugger********
***********************************************************************


	1) You should be aware that GNU-C, as with any other decent compiler,
will do things when optimization is turned on that you may not expect.
Sometimes intermediate results are not written to variables, if they are only
used in one place, and sometimes variables that are not used at all will not be
written to the symbol table.  Also, parameters to inline functions are often
inaccessible. You can see the assembly code equivalent by using KP7 in the
debugger, and from this you can tell if in fact a variable should have the
value that you expect.  You can find out if a variable lives withing a register
by doing a 'show symbol/addr'.

	2) Overly complex data types, such as:

int (*(*(*(*(*(* sarr6)[1])[1])[2])[3])[4])[5];

will not be debugged properly, since the debugging record overflows an internal
debugger buffer.  gcc-as will convert these to *void as far as the debugger
symbol table is concerned, which will avoid any problems, and the assembler
will give you a message informing you that this has happened.

	3) You must, of course, compile and link with /debug.  If you link
without debug, you still get traceback table in the executable, but there is no
symbol table for variables.

	4) Included in the patches to VMS.C are fixes to two bugs that are
unrelated to the changes that I have made.  One of these made it impossible to
debug small programs sometimes, and the other caused the debugger to become
confused about which routine it was in, and give this incorrect info in
tracebacks.

	5) If you are using the GNU-C++ compiler, you should modify the
compiler driver file GNU_CC:[000000]GCC.COM (or GXX.COM).  If you have a
separate GXX.COM, then you need to change one line in GXX.COM to:
$ if f$locate("D",p2) .ne. P2_Length then Debug = " ""-G0"""
                                       Notice zero--->  ^
If you are using a GCC.COM that does both C and C++, add the following lines to
GCC.COM:

$!
$! Use old style debugging records for VMS
$!
$ if (Debug.nes."" ).and. Plus then Debug = " ""-G0"""

after the variables Plus and Debug are set.  The reason for this, is that C++
compiler by default generates debugging records that are more complex,
with many new syntactical elements that allow for the new features of the
language.  The -G0 switch tells the C++ compiler to use the old style debugging
records.  Until the debugger understands C++ there is not any point to try and
use the expanded syntax.

	6) When you have nested scopes, i.e.:
main(){
	int i;
	{int i;
		{int i;
};};}
and you say "EXAM i" the debugger needs to figure out which variable you
actually want to reference.  I have arranged things to define a block to the
debugger when you use brackets to enter a new scope, so in the example above,
the variables would be described as:
TEST\main\i
TEST\main\$0\i
TEST\main\$0\$0\i
At each level, the block name is a number with a dollar sign prefix, the
numbers start with 0 and count upward.  When you say EXAM i, the debugger looks
at the current PC, and decides which block it is currently in.  It works from
the innermost level outward until it finds a block that has the variable "i"
defined.  You can always specify the scope explicitly.

	7)  With C++, there can be a lot of inline functions, and it would be
rather restrictive to force the user to debug the program by converting all of
the inline functions to normal functions.  What I have done is to essentially
"add" (with the debugger) source lines from the include files that contain the
inline functions.  Thus when you step into an inline function it appears as if
you have called the function, and you can examine variables and so forth.
There are several *very* important differences, however.  First of all, since
there is no function call involved, you cannot step over the inline function
call - you always step into it. Secondly, since the same source lines are used
in many locations, there is a separate copy of the source for *each* usage.
Without this, breakpoints do not work, since we must have a 1-to-1 mapping
between source lines and PC.
	Since you cannot step over inline function calls, it can be a real pain
if you are not really interested in what is going on for that function call.
What I have done is to use the "-D" switch for the assembler to toggle the
following behavior.  With the "-D" switch, all inline functions are included in
the object file, and you can debug everything.  Without the "-D" switch
(default case with VMS implementation), inline functions are included *only* if
they did not come from system header files (i.e. from GNU_CC_INCLUDE: or
GNU_GXX_INCLUDE:).  Thus, without the switch the user only debugs his/her own
inline functions, and not the system ones. (This is especially useful if you do
a lot of stream I/O in C++).  This probably will not provide enough granularity
for many users, but for now this is still somewhat experimental, and I would
like to reflect upon it and get some feedback before I go any further.
Possible solutions include an interactive prompting, a logical name, or a new
command line option in gcc.c (which is then passed through somehow to the guts
of the assembler).
	The inline functions from header files appear after the source code
for the source file.  This has the advantage that the source file itself is
numbered with the same line numbers that you get with an editor.  In addition,
the entire header file is not included, since the assembler makes a list of
the min and max source lines that are used, and only includes those lines from
the first to the last actually used. (It is easy to change it to include the
whole file).

	8) When you are debugging C++ objects, the object "this" is refered to
as "$this".  Actually, the compiler writes it as ".this", but the period is
not good for the debugger, so I have a routine to convert it to a $.  (It
actually converts all periods to $, but only for variables, since this was
intended to allow us to access "this".

	9) If you use the asm("...") keyword for global symbols, you will not
be able to see that symbol with the debugger.  The reason is that there are two
records for the symbol stored in the data structures of the assembler.  One
contains the info such as psect number and offset, and the other one contains
the information having to do with the data type of the variable.  In order to
debug as symbol, you need to be able to coorelate these records, and the only
way to do this is by name.  The record with the storage attributes will take
the name used in the asm directive, and the record that specifies the data type
has the actual variable name, and thus when you use the asm directive to change
a variable name, the symbol becomes invisible.

	10) Older versions of the compiler ( GNU-C 1.37.92 and earlier) place
global constants in the text psect.  This is unfortunate, since to the linker
this appears to be an entry point.  I sent a patch to the compiler to RMS,
which will generate a .const section for these variables, and patched the
assembler to put these variables into a psect just like that for normal
variables, except that they are marked NOWRT.  static constants are still
placed in the text psect, since there is no need for any external access.