Small-C compiler for the BBC Micro

                              Release 0.71

                         A.J.Travis  01-May-89


INTRODUCTION

Small-C is a subset of the C programming language for which a number of
public-domain compilers have been written.  The original compiler was
written by Ron Cain and appeared in the May 1980 issue of Dr.Dobb's
Journal.  More recently, James E.Hendrix has improved and extended the
original Small-C compiler and published "The Small-C Handbook", ISBN
0-8359-7012-4 (1984).  Both compilers produce 8080 assembly language,
which is the most popular implementation of Small-C to-date.  My 6502
Small-C compiler for the BBC Micro is based on "RatC", a version of the
original Ron Cain compiler described by R.E.Berry and B.A.Meekings in "A
Book on C", ISBN 0-333-36821-5 (1984).  The 6502 compiler is written in
Small-C and was bootstrapped using Zorland C on an Amstrad PC1512 under
MSDOS 3.2, then transferred onto a BBC Micro using Kermit.  The compiler
can be used to cross-compile 6502 code from an MSDOS host, or as a
'resident' Small-C compiler on a BBC Micro.


DEVELOPMENT

I started to implement a Small-C compiler for the BBC Micro in 1985
because I wanted an alternative to assembly language or Forth for writing
6502 image processing software.  I was very impressed by the performance
and portability of Forth, but found the language difficult to use.  I was
aware that a sub-set of Pascal had been implemented in Forth, and I set
about developing my own version.  However, I quickly realised that the
virtues of using a threaded-code interpreted language (TIL) could be
exploited just as easily by generating code for an interpreter
conventionally, instead of using Forth itself to generate a 'target'
vocabulary.  I began to use 'C' and Unix on a DEC pdp11 at the time and I
decided to implement a sub-set of C, instead of Pascal, on the BBC Micro
after reading "The Small-C Handbook" by Hendrix and "A Book on C" by Berry
and Meekings.

I began by implementing "Rat-C" under Unix on the pdp11.  The Rat-C
compiler is much smaller than the Hendrix compiler, and it also produces
'generic' assembly code.  I wrote a translator for the generic code output
by RatC, which generated 'JSR-threaded' code for the 6502.  A JSR-threaded
code interpreter is a form of TIL that uses the hardware call-return
mechanism of the processor as the low-level interpreter and is the most
efficient way of implimenting a TIL.  The code generated was too verbose
to produce a resident Small-C on the BBC Micro with only 29K of usable
memory in mode 7, but I was able to develop the run-time support for the
threaded-code interpreter and code generation model for the 6502.

Because of the severe memory constraints of a 'standard' BBC Micro, I
decided to translate Rat-C into BBC BASIC in order to produce a resident
Small-C compiler that would run in 29K.  This 'tiny' C compiler ("tcc") in
BBC BASIC was intended to be a 'bootstrap' for a Small-C version of the
6502 compiler, and I began distributing copies of the Small-C to friends
and colleagues.  Eventually, I sent a copy of the compiler to Chris Adie
at Edinburgh University Micro Support Unit, and later to Alan Philips at
the Lancaster University Micros Software Distribution Service.

After several more releases of the "tcc" compiler, I was approached by
John Evans of Mijas software for permission to sell the Small-C as part of
his 6502 assembly language development system.  I was pleased to give
Mijas permission to use my code, which they have adapted for use with the
Mijas 6502 symbolic debugger.  I continued to develop the 6502 Small-C by
optimising the code-generator for the 'small-machine' environment of the
BBC Micro and, during this development, I replaced my earlier BBC BASIC
programs with Small-C versions.  Finally, I have produced a resident
Small-C for the BBC Micro that can also be used as a cross compiler for
the 6502 on an MSDOS host.


RELEASES

	0.10  Jan-1986  Original version
	0.20  Apr-1986  Limited distribution
	0.30  Jul-1986  Sent to Chris Adie at ERCC
	0.40  Oct-1986  First version sent to <micros@lancs.vax1>
	0.41  Oct-1986  Bug-fix release
	0.50  Dec-1986  First version used by Mijas
	0.51  Apr-1987  Limited distribution
	0.60  Jul-1988  First DOS cross-compiler
	0.61  Dec-1988  BBC Micro/Master language ROM
	0.70  Apr-1989  Current release
	0.71  Jul-1990  Bug in shell ROM fixed
	0.72  Jun-2005  String buffer increased in printf() family


CHANGES FROM RELEASE 0.5

Release 0.6 of the 6502 Small-C compiler was cross-compiled on an MSDOS
host and has been modified to avoid major incompatibilities with full 'C'. 
Previous BASIC programs, including the compiler itself, have been
re-written in Small-C.  The Zorland C compiler objects to many of the
'liberties' I have taken with full 'C' usage, but compiles the Small-C
programs correctly.  An MSDOS distribution is also available containing
executable binaries of the Small-C compiler and 6502 assembler.

Release 0.61 was a bug-fix release with corrected sideways ROM startup
code and corrections to the "shar" program for extracting shell archives. 
The formatted input functions atoi(), scanf(), fscanf() and sscanf() have
been added to the compiler library in this release, and I have fixed a bug
in "as65" which failed to detect certain illegal expressions in opcode
operands.

The Small-C release 0.70 language ROM works correctly on a BBC Master, and
several minor bugs have been fixed in the run-time library.  Version 0.70
is the first version in which the Small-C command shell is used to compile
and run C programs.  I have also adopted lower-case mnemonics for the 6502
assembler, and extended the range of pre-processor directives supported by
"tcpp".


ACKNOWLEDGEMENTS

I am grateful to Jon Welch, and Dave Prosser from the Department of
Electronic Engineering at Bradford University who weeded out many of the
bugs in release 0.41 of the compiler.  I am also grateful to Alan Philips
at Lancaster University, and Rob McRon at Edinburgh University for their
help in distributing the compiler over electronic mail networks.  A
version of this compiler is distributed, with my permission, by Mijas
Software as part of a 6502 assembly language development system for the
BBC Micro.  I would like to thank John Evans of Mijas for his interest in
the compiler which he has extended and adapted for use with the Mijas 6502
symbolic debugger.


COPYRIGHT

The programs in this distribution remain copyright (c) 1989 A.J.Travis,
and should not be used for any commercial purpose without prior consent in
writing.  The programs may be copied and further distributed for
non-commercial use without restriction, provided a copy of this notice is
also included.


REQUIREMENTS

The "tcc" Small-C compiler requires a 'standard' BBC Micro or BBC Master
and a twin double sided 80-track disk drive in order to recompile itself. 
The run-time support routines and compiler library are contained in a
Small-C language ROM/RAM image that must be present in order to use the
compiler, but stand-alone versions of programs are readily produced using
a compiler option.  Source programs are edited using Acornsoft VIEW or a
similar editor, and any machine code monitor/debugger can be used on the
object programs produced.


INSTALLATION

The following installation instructions are superceed by those in the file
Install. They have been kept within the documentation as part of the
original distribution. [JGH]

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

AVAILABILITY

Send an SAE and Acorn DFS formatted, double-sided 80 track 5.25" floppy
(or 360K DOS formatted, 5.25" floppy for the MSDOS version).
Alternatively, mail me as <ajt@uk.ac.sari.rri> for an e-mail version.

	Home address:				Work address:

	1 St. Nathalan Crescent,		Rowett Research Institute,
	Banchory,				Greenburn Road,
	Kincardineshire.			Bucksburn,
	AB3 3YU					Aberdeen.
						AB2 9SB

	tel. Banchory 2392			tel. Aberdeen 712751 x134
	

DOWNLOADING SHELL ARCHIVES

Several people have reported difficulty in downloading the BBC Micro
Small-C as Unix 'shell' archives.  These are simply a convenient way of
distributing programs over e-mail networks and BBSs.  The "unpack" utility
is intended to simplify the task of unpacking the archives after
downloading them onto BBC Micro disks.  Two blank formatted 80-track disks
are required to download and unpack the archives.  First, download the
kermit takefile "getshar" onto drive 0: and use it to download the shell
archives:

>					; BASIC prompt
> *xoff				; disable ARIES B32 shadow RAM
> <break>				; press break key
> *rload kermit 13			; load kermit ROM image in slot 13
> <break>				; initialise ROM
> *kermit				; invoke kermit
BBC>					; kermit prompt
BBC> set file type ascii cr		; setup for ascii transfer
BBC> get getshar getshar		; transfer kermit take file "getshar"
BBC> take getshar			; transfer shell archives
BBC> *basic				; return to BASIC
>					; BASIC prompt


UNPACKING SHELL ARCHIVES

After downloading the shell archives, the Small-C ROM must be
bootstrapped, and the compiler programs must be 'unpacked' before they can
be used:

>					; BASIC prompt
> *exec mkboot				; dehex Small-C ROM, and utils
> *rload sh 14				; load Small-C ROM image in slot 14
> <break>				; initialise ROM
> *sh					; invoke tcc command shell
$					; Small-C prompt
$ exec :1.unpack			; unpack shell archives
$ access *.* L				; lock all files for safety


DOWNLOADING TCC FROM AN IBM-PC HOST

The MSDOS version of the compiler is distributed via e-mail as 'boo'
encoded archives which must be downloaded onto an IBM-PC or compatible
micro.  The files are then unpacked using the 'deboo' and 'arc' utilities
(available from Lancaster PDSoft distribution service).  The MSDOS version
of the compiler can then be used to cross-compile code for a BBC Micro. 
The DFS version of the compiler was cross-compiled on an Amstrad PC-1512,
then transferred to a BBC Micro fitted with an Aries B32 RAM board using
the following commands:

>					; BASIC prompt
> *xoff				; disable ARIES B32 shadow RAM
> <break>				; press break key
> *rload kermit 13			; load kermit ROM image in slot 13
> <break>				; initialise ROM
> *kermit				; invoke kermit
BBC>					; kermit prompt
BBC> set file type ascii cr		; setup for ascii transfer
BBC> get get get			; transfer kermit take file "get"
BBC> take get				; transfer tcc files
BBC> *basic				; return to BASIC
>					; BASIC prompt


DFS INSTALLATION

After downloading a copy of the DFS distribution disk from an MSDOS host,
the compiler programs must be 'installed' before they can be used:

>					; BASIC prompt
> *rload sh 14				; load Small-C ROM image in slot 14
> <break>				; initialise ROM
> *sh					; invoke tcc command shell
$					; Small-C prompt
$ mode 7				; set vdu mode 7
$ exec install				; set executable file attributes
$ access *.* L				; lock all files for safety


INITIAL SETUP

The system is distributed in DFS format, for use on a 'standard' BBC
Micro, but can be used under ADFS without modification.  Source programs
are edited (using VIEW or whatever editor you have), and saved to disk.
The restricted number of files in the DFS catalogue means that sources are
normally saved in ":2.*/c", and the distributed sources can be found on
side 2 of the disk.  The distribution disk is FULL, and needs to be
reorganised in order to use the compiler.  Side 0 of the disk contains the
executable binaries, #include <files> and Small-C language ROM/RAM image. 
These files must always be present in drive 0.  The files on side 2 must
be copied to other disks in order to recompile the programs. The compiler
program "tccom", in particular, needs a disk to itself in order to
recompile ...  Error recovery is virtually non-existent, and DFS "can't
extend" problems should be avoided by periodically *compacting the disks.


EXAMPLE PROGRAM

The "Towers of Hanoi" example can be compiled using the distribution disk
in BBC drive 1/3, and a blank formatted working disk in drive 0/2 as
follows:

>					; BASIC prompt
> *drive 0				; select drive 0 on distrib. disk
> *xoff				; disable ARIES B32 shadow RAM
> *rload sh 14				; load Small-C ROM image in slot 14
> <break>				; initialise ROM
> *sh					; invoke tcc command shell
$ copy 1 0 *.*				; copy 'system' files onto working disk
$ copy 3 2 hanoi/c			; copy example source file
$ drive 2				; select drive 2 on working disk
$ mode 7				; set vdu mode 7
$ tcc -o hanoi hanoi/c			; compile example
$ mode 2				; set vdu mode for "hanoi"
$ hanoi				; run program
$ mode 7				; reset vdu mode
$ basic				; return to BASIC
>					; BASIC prompt


See the description of each utility program for a detailed explanation of
how to use them.  The Small-C sources are intended to be examples of how
to use the language - if you need more help than this, consult the
excellent "Small-C Handbook" by James E.  Hendrix.  There are also
numerous Small-C programs available from the CP/M user group.