Apollo m68k support kit for GNU C compiler version 2.6.0.

     It requires a virgin copy of GNU C version 2.6.0.  The GNU assembler
gas-2.3 and parser generator bison-1.22 should be compiled and installed
before building GCC.  The "patch" program is needed to install the patches.
At SR10.3.5 and before, Apollo provided it in /usr/new.  It is included
in the MIT X-window sources.
The GNU debugger gdb-4.13 is supported, but NOT the native DDE debugger.
It uses the GNU stabs-in-COFF format with .stab and .stabstr sections.

     This code has been tested on an Apollo DN4500 running SR10.3.5 with
the ANSI header files and a BSD environment.  It should work for any
68020+-based Apollo running SR10.3 or later.  It may work for earlier SR10
systems, though a new crt0.o file would be needed for C++ global destructors.
It does NOT work for DN10000 systems or OS releases before SR10.

This patch kit contains the following files:

INSTALLATION:  how to install this kit
README:        descriptions of the Apollo modifications
DIFFS:         context diffs for program source files
apollo-pic.c:  new source code
collectshare:  a shell script for use in making C++ shared libraries

     These patches support GCC on Apollo 680xx workstations with GDB as a
debugger.  Most Apollo language extensions are accepted including reference
variables.  The most commonly used Apollo header files are handled properly.
These patches should not affect other platforms, so the modified GCC source
can still be used to build for other systems.

     Some of this code is taken from an older GCC modification done
by John Vasta.  It should be available on labrea.stanford.edu.

Apollo enhancements provided by this kit:

     Reference variables are partially supported in C.  Reference parameters
and simpler variable declarations are supported.  There are limitations on
complex initializers for top level variables.  The Apollo headers require
only simple reference parameters.

     The generated code can go into a read-only text segment unlike in
previous patch kits.  Calls to shared library routines are handled with data
area links in a way similar to what the Apollo compiler does.  The .data
section is used rather than a separate .aptv section.

     The "sized enum" extension is supported.  Use of "-fshort-enums"
disables the explicit sizing.  No consistency-checking is done for these.
Declaring "char enum tag ..." and then using just "enum tag ..." to
declare a variable will produce a normal int-sized enum.
The "attribute" and "options" extensions including the '#' forms are
permitted by the grammar, though not all are acted upon.  The "a0_return",
"aligned", and "volatile" attributes should work.  It is not possible to
define a function with a0_return, but declaring and using an external function
with a0_return is supported.  The "#eject" directive is allowed but not
acted upon.

     In the modified C, structure value comparisons are permitted.  These
blindly include pad fields, so unexpected results are possible.  The Apollo
compiler does the same.  Partially named structure or union members are NOT
supported, so "foo.mumble" is not a synonym for "foo.baz.mumble".  C++ does
NOT have the structure comparison enhancement.

     Apollo C uses a different interpretation of the "aligned" option than
unmodified GCC.  This is used in numerous system header files, so the
modified GCC uses the Apollo interpretation, where aligned(1) is halfword
alignment, aligned(2) longword, and so on.  The Apollo headers also have
aligned typedefs.  The modified GCC accepts but ignores "aligned" for
typedefs.  Most instances of "aligned" in the headers seemed to be for
DN10000 systems.

     The "-fPIC" option works to generate position-independent code, so this
compiler can produce shared libraries.  The calling convention should be
almost identical to that used by Apollo C.  To compile code that calls
routines in a library loaded by "inlib", do an "inlib" of that library from
the shell in which the compiler will be run before running GCC or make.
GCC will then generate appropriate calls for those library routines.
Shared libraries have not been very well tested.
To build a shared library, compile with -fPIC, then use "ld -r -a" to
load all the .o files into one large file.  An existing .a file may be
separated into its .o files with "ar x".  The file produced by ld may
then be used by the "inlib" command.  It will usually be necessary to
use a shared libgcc when making shared libraries.

     Stack handling should be the same as in Apollo C, so object files from
either compiler may be freely mixed.

     The Apollo C "-A" option is not available since GCC has a conflicting
use for it.  Loader options can be passed using "-Xlinker", so most of
the uses for "-A" are still available.  It is necessary to pass both the
"-A" and the option that follows it using "-Xlinker".  Example:
Apollo C:  cc  -c          -A          stacksize,30000 ...
GCC:       gcc -c -Xlinker -A -Xlinker stacksize,30000 ...

     Full emulation of the Apollo compiler would require aborting with
a "compiler backend failure" message for some source files whenever
optimization was used.  It would also require adding busy-wait loops to
make GCC slower.  These "features" did not seem worth implementing.



Apollo shared libraries and text segment code:

     Apollo uses COFF-format executable files that may contain unresolved
external references to shared library routines.  The run-time system marks
the text segment as read-only before resolving the library references, so all
relocations must be in a writable segment.  The Apollo compiler special-cases
potential library references so that a data area link is created.  Functions
get a special writable ".aptv" segment containing links of the form "jmp x"
where x is a relocation target.  Variables get a simple pointer in
the data segment.  The modified GCC uses the PIC mechanism to create data
area links for externals.

     The setjmp-type functions do not save registers.  The Apollo
compiler special-cases these and generates appropriate register saves.
GCC saves all registers in functions that call setjmp-type functions.

     Apollo position-independent code uses an entry stub in the data
section which sets up a data section pointer in register A0.  There are
no actual symbols in the text section.
A position independent function FOO looks something like this:
.data
foo:
	lea <end of data area>,a0
	jmp <foo code>

.text
<foo code>:  (no actual symbol)
	link a6,...
	save a5 somewhere
	moveal a0,a5
	Calls to other functions are looked up in the data area via a5.
	References to the data area are handled through a5.
	No direct addresses can be used in the text section.
	...
	rts

The modified GCC uses this same sequence, though it does not use
the end of the data area for the A0 pointer.

C++ shared libraries that have global constructors or destructors require
an additional stub to be attached to library clients.  This stub contains
the .ctors and .dtors sections from the shared library, so that the
client will initialize everything in the library on startup.
A shell script "collectshare" is provided to build this stub.
The .ctors and .dtors sections are typed as data sections so they may
refer to shared externals.

The modified GCC generates a .unwind section to help the tb (traceback)
command run more quickly.  It does NOT generate the line number information
that would let tb show function names and numbers.  It only makes .unwind
records for functions that use a frame pointer.



Known problems:

     The -fbytecode option causes a segmentation fault.  It may not be
"officially" released on any platform yet, and is not in the info pages.

     Not all of the Apollo-specific directives are supported.  Apollo CC
may still be required for some system programming tasks.



Files changed by DIFFS and description of change:

Makefile.in
   Generate .y files from .in files to conditionally include Apollo
   grammar extensions.
configure
   Turn off fixincludes, do not use collect2.
bc-optab.c
   Add typecasts for "-1" values used to initialize enum values so Apollo
   cc can compile this.  FIXME a named enum value should be used.  The
   "-1" might cause trouble for other compilers.
c-common.c
   decl_attributes ():  different "aligned" option numbers, aligned
   typedefs, other directives
c-decl.c
   shadow_tag_warned ():  sized enum
   grokdeclarator ():  reference variables, sized enum
c-lex.c
   make_reference_declarator ():  new code
   check_newline ():  #eject directive
   yylex ():  #attribute and #options directives
   This part is John Vasta's code with only small changes.
c-lex.h
   Declare make_reference_declarator ().
c-parse.in
   new tokens for #options and #attribute
   new grammar rules for above and reference variables
c-typeck.c
   New routines get_temp_name (), convert_from_reference (),
   and convert_for_initialization ().
   Numerous changes for reference variables.
   build_binary_op (), structure comparison
cccp.c
   pedantic warning for #eject
combine.c:
   bug fix:  simplify_set () bad if_then_else substitution
function.c:
   bug fix:  setjmp_protect () abort problem
genoutput.c:
   bug fix:  change parameter c of n_occurrences from char to int
objc-act.c:
   bug fix:  change parameter mtype of warn_with_method from char to int
optabs.c:
   bug fix:  use emit_library_call_value () so that large values
   are returned according to the Apollo C conventions
reload.c:
   bug fix:  change parameter c of n_occurrences from char to int
toplev.c
   compile_file ():  calls for Apollo PIC if NONSTANDARD_PIC defined
tree.h:
   Apollo-specific fields for identifiers

cp/
Make-lang.in:
   changed CXX_SRCS to use parse.in instead of parse.y
Makefile.in:
   Generate .y files from .in files to conditionally include Apollo
   grammar extensions.  Add $(srcdir) before rules using parse.* so that
   Apollo "make" will work.
decl.c:
   bug fixes:  setjmp_protect () abort problem
   grokdeclarator ():  sized enums
lex.c
   like c-lex.c
parse.in
   made from parse.y.  Like c-parse.y, only no changes for
   reference variables.  The makefile builds parse.y from parse.in.

config/

apollo68.h
   Made compatible with Apollo C, added PIC support.
m68k.c
   Added macros REPLACE_FUNCTION_PROLOGUE, REPLACE_FUNCTION_EPILOGUE, and
   REPLACE_LEGITIMIZE_PIC_ADDRESS to allow apollo-pic.c to replace the
   corresponding routines.
m68k.md
   changes for PIC and stack alignment for QI arguments.  The should not
   affect other systems.
x-apollo68
   New CFLAGS and LDFLAGS, inclusion of apollo-pic.o, crtbegin.o, crtend.o.
   Turned off running fixproto.



New files:

apollo-pic.c
   This has the routines for generating Apollo-style PIC code.  Some new
   fields are added to TREE_IDENTIFIER nodes to accumulate offsets for
   PIC symbols so the assembler does not have to convert them.
   External symbols are checked against all the shared libraries loaded
   in the compiler's address space so that PIC calls are generated
   for all shared library references.  This check sees libraries
   loaded by the "inlib" command as well as those loaded at boot time.
   It also include code to generate .unwind section records and a final
   .mir and .sri section.

DISCLAIMER:  This code has NOT been tested extensively, especially the
shared library support.  Objective C has not been tested at all.
The implementer of the reference variable and sized enum support does not
claim to understand computers, compilers, or GNU software.  He also had
been using dangerous electronic narcotics like USENET and Mosaic while
writing the code.

Questions about this patch kit may be addressed to:

William J. Eaton
Email wje@hoffman.rstnu.bcm.tmc.edu
Phone (USA) (713) 798-5161
