------------------------------------------------------------------------------
| INTRODUCTION |
----------------

    The following are some comments and instructions on the 6811 port of the
    gnu gcc compiler done by Coactive Aesthetics.

    The port was written using the GCB11 Network Microcontroller board that
    is manufactured by Coactive Aesthetics. It was hosted on a NeXT system.
    However, there is no assumptions and/or hardcode values within the
    compiler which would prevent the compiler from working on any 6811 board
    or on any host system. A port to another board would require an updated
    crt0.s file which defines where the "pseudo" registers live in the memory
    map and where the startup code lives. A sample crt0.s file has been
    included as part of this release.

    The rest of this readme file has some technical notes relating to the
    port, and installation procedures that can be used in installing the
    compiler.

    Any questions, bug reports, or porting comments/questions should be sent
    to gcc@coactive.com.

    Thanks,

    Otto

    --
    Otto Lind                  Coactive Aesthetics
    otto@coactive.com          P.O. Box 425967, San Francisco, CA 94142
    netcom!coactive!otto       voice:(415)626-5152    fax:(415)626-6320

------------------------------------------------------------------------------
| 6811 RELEASE UPDATE |
-----------------------

    I have just finished updating the port to fix bugs and improve
    optimizations. The biggest change (which affected most instructions)
    was to remove the "0" requirement on multiple arg instructions, which
    caused gcc to assume that args 0 and 1 must be identical. This causes
    a big improvement in reduction of code size. I also fixed a bunch of
    bugs in the various instructions.

    The following are code size numbers on a real world application
    Coactive is developing under contract:

	    compiler		size
	    --------		-------
	    gcc (old)		24326
	    gcc (snapshot)	16166
	    gcc (new)		15030
	    icc			14269
	    archimedes		12975	(this is an _old_ version)

    I feel that the new version is probably as optimal as I can get it,
    given my pseudo register scheme (if anyone want to prove me wrong,
    go for it).

    Latest Changes:

	(See ChangeLog)

------------------------------------------------------------------------------
| 6811 TECHNICAL NOTES |
------------------------

    The following are some notes relating to the Coactive Aesthetics port of
    the gnu gcc compiler to the Motorola M68HC11 microcontroller unit.

    Limitations:

	o Currently, there is no support for floating point arithmetic, and
	  the machine description file does not contain any instruction
	  definitions for floats. The compiler does not deal with missing
	  instructions and may crash at various locations within its code
	  when it encounters floating point numbers (See update above). 

	  If the compiler crashes, the first thing to look for are floating
	  point numbers or use of "float" or "double" variable within your
	  program. Something as innocuous as "printf("%d", 0.0)" will
	  cause a crash.

	o The current version of the port does not support 4 byte longs. The
	  following are the datatype sizes that the compiler supports:

	  	char	8 bits
		short	16 bits
		int	16 bits
		long	16 bits

	  If you absolutely have to have 4 byte longs, you can do the
	  following: 

	    1) Update the tm.h file (local.h) to implement some form of
	       4 byte register.  You may want to take the "pseudo" register
	       approach that was used for the 2 and 1 byte instructions.

	    3) Update the m6811.md file to implement four byte operations on
	       all si mode instructions. As an example, the instruction
	       "tstsi" would need to be added to look at a 4 byte operand,
	       and set the condition code register appropriately.

	       When updating the machine description file, you may want to
	       tighten up what is allowed for operands and constraints for
	       these instruction (to make life a bit easier).

    Assembler/Linker

    	Most of the information for the assembler/linker can be found in the
	documentation located in the xasm/doc directory. What follows are
	some comments on the changes that I have made to the source for the
	assembler and linker.

	    o The original code only support global identifiers of 8 bytes
	      (truncating anything following that). This is a restriction
	      which would break every c++ program on the planet, so I bumped
	      the limit to 32 bytes. This required a change in the output of
	      the list and map files, since the code assumed 8 byte fields.

	    o The file path names limits were increased in 255. They really
	      should used the platforms definition of this, but I didn't want
	      to worry about which includes contained it.

	    o The command line argument processing was changed to allow for
	      output files which don't depend on the name of the input file.
	      The "response file" processing in the linker was removed, and
	      the command line argument processing was expanded. All of the
	      changes were done to allow for the gcc driver to call the
	      assembler and linker with default specs. To pass assembler or
	      linker specific option through gcc, using the -Wa and -Wl
	      options.

	    o I changed the assembler error reporting mechanism to be a
	      little more verbose.

    Some "stupid" things that we are doing.

	Thing that can be considered dumb code generation include:

	    o A more intelligent branching strategy could be implemented.
	      For now, long branchs are the default. You can use
	      -mshort_branch to disable this.

    Known bugs.

	Static variables are not initialized when code is executed.  In a
	sense, this is related more to the startup code and the machine
	operating environment than gcc itself.  If you want, additional
	startup code can be written (in the crt0.s module) to handle this.

	Otherwise, we have run the compiler through a C test suite, which
	hits most of the possible code generation that is defined in
	machine description files. If you do find a bug, please send mail
	to the bug mailing address above.

    Future directions.

    	The current plan is to donate this port to the FSF, and possibly
	find another maintainer for it.

------------------------------------------------------------------------------
| INSTALLATION PROCEDURES FOR UNIX SYSTEMS |
--------------------------------------------

    Get the gnu release of gcc-2.6.3:

	The entire source file distribution is not included here. Instead
	you should go to your favorite ftp site to download the source
	distribution of gcc-2.6.3 and untar it onto disk.

    Install the 6811 source files:

	The following files are the 6811 specific files used in creating the
	cross compiler:

		config/m6811/local.h
		config/m6811/m6811.c
		config/m6811/m6811.md
		config/m6811/xm-local.h

	This should be copied into the source tree containing gcc-2.6.3

    Configure the compiler:

	Run configure to set up a makefile for cross compilation. On our
	systems, we used the following:

		./configure --host=next --target=m6811-local
					--prefix=/usr/local/gnu6811

    Make the C compiler:

	The normal step for making the compiler should be followed, but some
	of the components in the make will fail. To make the compiler with
	the C language, the following make target should be specified:

		make "LANGUAGES=c"

	The compile should continue until you see the following:

		mv: libgcc1.a: Cannot access: No such file or directory
		You must find a way to make libgcc1.a
		*** Exit 1

	This error message can be ignored, since full support for libgcc.a
	does not currently exist. You can also compile the C++ and Object C
	compilers by changing the LANGUAGES list. See the INSTALL file for
	more details on this.

    Installing the compiler:

	To install the front end and the driver, type in:

		mkdir <install>
		make "LANGUAGES=c" install

	The make will fail when trying to compile ./libgcc1.a. This is
	expected, and can be ignore.

	At this stage, you should have lib, bin, and man subdirectories
	installed in the <install> directory (specified by the --prefix
	option, /usr/local is the default). The bin directory should contain
	the executable "m6811-local-gcc". This is the driver module which
	will execute the pre-processor, C compiler, etc. You can rename this
	to whatever name you would like to refer to in you makefiles.

    Installing the assembler:

	Go to the source directory xasm/asm-src which has the assembler
	source, and compile the source into an executable:
	
		make as6811

	Install the executable into the gcc install directory:

		cp as6811 <install>/bin

    Installing the linker:

	Go to the source directory xasm/lnk-src which has the linker
	source, and compile the source into an executable:
	
		make

	Install the executable into the gcc install directory:

		cp aslink <install>/bin

    Configuring the gcc driver:

	The driver module "m6811-local-gcc" looks in a particular path for
	any tools that it should use in compiling source modules. Since we
	want to have it use the as6811 and aslink executables, we need to
	creat symbolic links to them. To do this, do the following:

		cd <install>/lib/gcc-lib/m6811-local/2.6.3
		ln -s <install>/bin/as6811 as
		ln -s <install>/bin/aslink ld

	By default, the gcc install procedures creates some header files in 
	<install>/lib/gcc-lib/m6811-local/2.6.3/include. These should be
	updated to reflect your installation.

    Installing the crt0.o module

    	A sample crt0.s module is located in the samples directory (I have
	not tested this, since I have a Coactive crt0.s module, but it
	generally shows what things need to exist). You should edit this file
	to add/change any board specifics things, then install it into the
	gcc installation. To install it, do the following:

		cd samples
		<install>/bin/as6811 -o crt0.o crt0.s
		cp crt0.o <install>/lib/gcc-lib/m6811-local/2.6.3

	One thing to verify in this module is the starting location for the
	_CODE segment. Currently, I have the startup code fixed at the
	location 0x1000, and use the option "-Wl,-b_CODE=0x1000" to put the
	relocatable code segment right after the startup code. The assembler
	and linker documentation discusses this in more detail.

    After doing the above steps, the the compiler should be installed, and
    ready for testing.

------------------------------------------------------------------------------
