CERN, European Organization for Nuclear Research
1211 Geneva 23
Switzerland

J.D. Blake
blake@cernvax.cern.ch
1991/2/25


                   GNU C Compiler (gcc) for OS-9/68000
                   -----------------------------------


This directory contains the GNU  C  compiler  (gcc)  for  OS-9/68000.  The
compiler  is  an  adaptation  of gcc version 1.37.1.  It runs at CERN as a
native compiler on OS-9/68000 systems  and,  under  the  name  gccos9,  on
cernvax  as a cross compiler.  It can compile code for the 68000/68010 and
for  the  68020/68030  with  or   without   68881/68882   floating   point
coprocessor.  The compiler uses Microware's assembly code optimizer (o68),
assemblers (r68, r68020), linker (l68), standard header files and run time
libraries.

Gcc is a product of the Free Software Foundation.  Its principal author is
Richard  Stallman of MIT.  Gcc was adapted to OS-9/68000 by Atsushi Seyama
of Tokyo.  Further modifications have been made by Martin Husemann and Kei
Thomsen  of  Paderborn  University,  and by Julian Blake of CERN.  In-line
68881 code for mathematical functions is based on work by Matthew Self  of
NASA.  Comments  on  the  use of the OS-9 version of gcc at CERN should be
addressed to Julian Blake (blake@cernvax.cern.ch).

This directory contains OS-9/68000 executable programs:

    gcc         Gcc compiler driver (edition 11)
    cccp        C preprocessor component of gcc (edition 10)
    cc1         C compiler component of gcc (edition 26)

symbol tables for debugging the executable programs:

    gcc.stb     Symbol table for gcc
    cccp.stb    Symbol table for cccp
    cc1.stb     Symbol table for cc1

standard header files (for #include preprocessor directives):

    assert.h    Defines assert function for run time consistency checks
    limits.h    Defines limiting values for characters and integers
    math.h      Mathematical library declarations
    math881.h   Invoked by math.h when compiling for a 68020 with 68881
    stdarg.h    Defines properties of arguments
    stddef.h    Defines some standard types and values
    varargs.h   Definitions for variable argument lists

a run time library:

    gnulib.l    Run time library for programs compiled by gcc

documentation and other files:

    COPYING     Conditions of distribution (GNU General Public License)
    Comments    Users' reactions to gcc for OS-9/68000
    Doc         Describes Seyama's adaptation of gcc to OS-9/68000
    History     Modification history of gcc for OS-9/68000
    README      This file


Installation of gcc as a native compiler on an OS-9/68000 system
----------------------------------------------------------------

Executable files in /DD/CMDS:
    gcc, cccp, cc1

Symbol table files in /DD/CMDS/STB:
    gcc.stb, cccp.stb, cc1.stb

Standard header files in /DD/GCCDEFS:
    assert.h, limits.h, math.h, math881.h, stdarg.h, stddef.h, varargs.h

Run time library file in /DD/GCCLIB:
    gnulib.l

The standard header files contain ASCII text.  The other files are binary.


Use of gcc as a native compiler on an OS-9/68000 system
-------------------------------------------------------

Build an executable program for 68000:
    gcc -O -fcombine-regs -g -mgss -o68 file.c ... -o file

Build a large executable program for 68020 with 68881:
    gcc -m68020 -m68881 -mremote -O -fcombine-regs -g -mgss file.c ...

List the options of gcc and of cccp:
    gcc -?
    cccp -?

Some options of gcc:
    -m68020             Compile/link for 68020 without 68881
    -m68020 -m68881     Compile/link for 68020 with 68881
    -mremote            Generate 32-bit address offsets
    -S                  Compile into assembly code (file.a)
    -c                  Compile into relocatable object module (file.r)
    -o file             Store compiler output in `file'
    -O -fcombine-regs   Invoke full optimization in cc1
    -g                  Generate symbol table for debugging
    -mgss               Generate debugging symbols for static functions
    -o68                Invoke the assembly code optimizer o68
    -llibfile           Link routines from the library libfile
    -Ldir               Search for libraries in the directory dir
    -x                  Store executable output in the current execution
			directory
    -v                  Show commands generated by gcc
    -debug              Show commands generated by gcc, but do not execute
			them;  show search for executable programs and
			libraries

By default gcc stores its executable output in  the  file  gccout  in  the
current  data directory.  When searching for libraries, gcc looks first in
directories specified with the -L option, then in directories named in the
environment  variable GCCLIB, then in fixed directories, and lastly in the
current data directory.


Installation of gccos9 as a cross compiler
------------------------------------------

Executable file in /usr/local/bin:
    gccos9

Executable files in /usr/local/lib:
    gccos9-cpp
    gccos9-cc1

Standard header files in /usr/local/lib/gccos9-include:
    assert.h, limits.h, math.h, math881.h, stdarg.h, stddef.h, varargs.h

Run time library file in /usr/local/lib/gccos9-lib:
    gnulib.l


Use of gccos9 as a cross compiler
---------------------------------

Build an executable program for 68000:
    gccos9 -O -fcombine-regs -g -mgss -o68 file.c ... -o file

List the options of gcc and of cccp (cpp):
    gccos9 -\?
    /usr/local/lib/gccos9-cpp -\?


Documentation
-------------

There are user guides to gcc and to its preprocessor cccp (cpp):

    Using and Porting GNU CC
    Richard M. Stallman
    188 pages

    The C Preprocessor
    Richard M. Stallman
    43 pages

Files needed to generate printable copies of these manuals are distributed
separately (see below, Afterword).

The OS-9/68000 implementation of gcc is described in  the  files  Doc  and
History  in  this directory.  Information in this file (README) supersedes
information in Doc, which is not up to date.  The file  Comments  contains
criticisms  from  CERN  users  of gcc for OS-9/68000; I have added factual
information but have abstained from value judgements.


Notes
-----

The symbol table generated by  gcc  for  debugging  contains  only  global
symbols:  data  and  functions.  The  -mgss  option of gcc causes a global
symbol of the form function_name@file_name to be generated for each static
function.

Gcc normally uses addressing modes with a 16-bit offset to  access  global
and  static  data,  which  are  placed in the unnamed vsect.  The -mremote
option causes gcc to use 32-bit offsets to access data, and to place  data
in  the  remote vsect.  The option may be used to avoid the 64 Kbyte limit
on the size of the unnamed vsect and, when compiling for a 68020, to avoid
a  similar  limitation  on  references  to  functions and character string
constants.  When compiling for a 68000, registers d2 and d3  are  used  as
temporary  registers  for 32-bit offsets into the remote vsect.  Code with
16-bit offsets is smaller and runs faster than code with  32-bit  offsets,
on both 68000 and 68020.

When compiling for a 68020 with 68881, gcc generates  in-line  68881  code
for  almost  all  the  mathematical  functions  declared  in  math.h.  The
exceptions are atan2 and pow, whose code is  too  large  to  justify  this
treatment.  The  in-line  code does not contain error traps: when an error
occurs, a Not-a-Number is returned in place of the  function  value.  (The
68881  can  operate  in  a  mode  which  traps errors, but this is not its
default behaviour in OS-9 programs.)

The values of IEEE double precision floating point constants generated  by
the cross compiler can differ from those generated by the native compiler,
because of differences between VAX and  OS-9  floating  point  arithmetic.
The  biggest difference that I have seen in practice is 3 in 2**53.  VAX D
format allows greater accuracy  than  IEEE  DP  format  (56  bits  in  the
mantissa  instead  of  53)  but has smaller range (8 bits for the exponent
instead of 11).

Gcc  normally  generates  code  to   check   for   stack   overflow.   The
-mnostack-check option inhibits this.

The environment variables GCC_EXEC_PREFIX,  GCCDEF  and  GCCLIB  influence
gcc's  (and  gccos9's)  search paths when it is looking for its executable
components (cccp, cc1, o68, r68, r68020, l68), for header  files  (invoked
by  #include  directives)  and for run time libraries, respectively.  Each
variable may specify one or more  directories  to  be  searched.  Multiple
directories  should  be separated by colons.  If, for example, gcc and its
ancillary files are installed on a non-standard disk /H2, the  environment
may be set up as follows:

    setenv GCC_EXEC_PREFIX /H2/CMDS/
    setenv GCCDEF /H2/GCCDEFS:/H2/DEFS
    setenv GCCLIB /H2/GCCLIB:/H2/LIB

Note that the value of GCC_EXEC_PREFIX needs the final  slash  ("/").  The
-debug  and -M options of gcc (gccos9) may be used, separately, to see the
effects of gcc's and cccp's file searches.


Known weaknesses
----------------

The assembly code optimizer o68 cannot be used  when  compiling  with  the
-mremote   option,  as  gcc  does  not  generate  the  instruction  length
information on which o68's branch optimization depends.

When compiling without the -mremote option, gcc generates addresses of the
form  "symbol+offset(a6)"  when translating an array reference of the form
"symbol[variable+offset]".  The displacement  "symbol+offset"  can  easily
overflow  its  16-bit field if offset is negative and symbol is one of the
first items of statically allocated data in the program.

The cross assembler r68020 crashes when given a single precision  floating
point  instruction  with  an  immediate  operand.  Given a Fortran program
containing REAL arithmetic, the Fortran to C translator  f2c  generates  C
code  which  causes  gcc to produce such instructions when compiling for a
68020 with 68881.  The OS-9 native version of r68020 does not suffer  from
this weakness.

Gcc generates 16-bit offsets in internal branches, despite the presence of
-m68020  and  -mremote  options.  The  offset  can  overflow in very large
functions.

A variable argument list pointer can only be used inside the function with
the  variable  argument  list.  The  va_arg  macro  in varargs.h refers to
variables in va_alist, whose scope is limited to this function.

Gcc has options (-p and -a) for execution  profiling.  The  implementation
is incomplete, as the profile dump library prof.l is missing.


Afterword
---------

The GNU C compiler is free software.  See the  file  COPYING  for  copying
permission.

Gcc for OS-9/68000 is based on gcc  1.37.1  which  may  be  obtained  from
prep.ai.mit.edu by anonymous FTP; look in the directory pub/gnu.

I plan to distribute gcc for OS-9/68000 by anonymous FTP from friendly FTP
server  sites.  Offers  of  FTP hospitality will be welcomed, as CERN does
not run an anonymous FTP service.  There will be four distribution files:

    gcc-1.37.1-osk-README           Basic information
    gcc-1.37.1-osk-bin.tar.Z        OS-9/68000 executable gcc
    gcc-1.37.1-osk-doc.tar.Z        Gcc and cpp user guides
    gcc-1.37.1-osk-src.tar.Z        Source code (cross and native gcc)

My working assumption is that the recipient will transfer the software  to
a  UNIX system and unpack each distribution file there, using the programs
uncompress and tar; the unpacked files may  then  be  transferred  to  the
target OS-9/68000 system by FTP.

The compiler (gcc, cccp, cc1) and run  time  library  (gnulib.l)  in  this
directory  were  built  on  an  MVME147 (68030/68882) based system running
Microware's OS-9/68000 version 2.4  and  C  version  3.2.  The  executable
components  of  gcc  were  linked with the CIO trap library (cio.l) from C
version 3.1, so that they may run under OS-9/68000 version 2.3 or 2.4.  It
should  be possible to run gcc on a 68000 based system; I have not however
tried to do so.
