Small-C 'C' Compiler Tools
		       --------------------------

			       Release 0.7
			       -----------

			   A.J.Travis 01-May-89
			   --------------------


--------------------------------------------------------------------------------
INDEX
	as65
	cmp
	crt
	ctype
	demo
	diff
	errors
	get, put
	install
	ld
	lib
	lpr
	makefile [mktcc]
	rm
	sfa
	sh
	shar
	stdio
	sys
	tcc
	tccom
	tcpp
	unpack


--------------------------------------------------------------------------------
NAME
	as65

SYNOPSIS
	as65 [-l] [-o outfile] file1 ... [filen]

DESCRIPTION
	Assembler for the 6502 processor.  This is a two pass assembler
	that processes the concatenation of source files given as
	command-line arguments.  Local symbols are prefixed by tilde '~'
	and are not written to the global symbol output file.  Mnemonics
	are lower-case, and are reserved symbols.  Underline '_' is
	accepted as an alpha character in symbols.  Assembly language
	routines may be called from Small-C programs, provided the
	Small-C parameter passing conventions are observed.  In this
	implementation, parameters are always promoted to 16-bits with
	sign extension to the left and pushed on the data stack in
	'reverse' order.  In addition, the compiler prepends an
	underline '_' to the name of the Small-C function used to call
	the assembly language routine.  The external symbols referring
	to code in the run-time support module, and BBC MOS are passed
	to the assembler by means of equate directives in the external
	symbol file 'ext/s' or 'swext/s'.  If the Small-C 'end' symbols
	~eot (end of text) and ~eod (end of data) are present, the size
	of the text and data segments are printed in decimal, followed
	by the assembly origin, ~eot, and ~eod values in hex.  The
	assembler follows MOS Technology/Rockwell conventions.  Consult
	the manufacturer's 6502 assembly language reference manual for
	more details.

	Options:
		-l		produce assembly language listing
		-o name		specify name of output file

	Note: The assembler can be used without an "optab" file in order
	to generate "optab" itself from .BYTE assembler pseudo-ops.  In
	this situation a warning is issued, but the assembly continues.

BUGS
	JMP expects a 16-bit destination, and JMPs into page zero are
	wrongly flagged as errors.  This arises when the assembler
	origin is not set.  Optab is needed because there is no simple
	way of initialising static data in the current version of tcc.
	Mnemtab is needed to pre-hash the mnemonics into the symbol
	table.

FILES
	as65.c
	optab/s		source code to generate optab
	:0.$.optab	6502 opcode table
	:0.$.mnemtab	6502 mnemonics
	o/out		default output file
	g/out		global symbol file

	
--------------------------------------------------------------------------------
NAME
	cmp

SYNOPSIS
	cmp file1 file2

DESCRIPTION
	Simple byte by byte file comparison.

FILES
	cmp.c


--------------------------------------------------------------------------------
NAME
	crt

SYNOPSIS
	Stand-alone Small-C run-time support

DESCRIPTION
	Large programs such as the compiler "tccom" require the Small-C
	language ROM/RAM image to be present, but smaller programs can
	be made 'stand-alone' using the -A option of "tcc".  This loads
	the run-time support and compiler library in the default text
	area at $1900 in the i/o processor memory area, the usual MOS high
	water mark with just DFS fitted. The default load address is set to
	$1902 in order to avoid error messages from the BASIC language ROM
	which initialises the first two bytes of this area.

BUGS
	The entire run-time support is loaded, even though a large part
	of it may never be referenced by the user program.  A link
	editor is required.
	
FILES
	mkcrt		*exec file to assemble crt
	oshdr/s		MOS entry points, and Small-C workspace definitions
	crt0/s		stand-alone start-up code
	crt1/s		JSR threaded code interpreter
	sys/s		operating system interface
	lib/s		part of the 'standard' C library
	patch/s		control flow patch
	ext/s		external symbol file used to link user programs
	enter/s		entry point patch for user program


--------------------------------------------------------------------------------
NAME
	ctype

SYNOPSIS
	#include <ctype.h>

DESCRIPTION
	This is a dummy file in release 0.7 - the character
	classification table is defined in sys/s, and character
	classification routines are written in assembly language.

BUGS
	Should be done with pre-processor macros ...

FILES
	:0.$.ctype.h
	sys/s

	
--------------------------------------------------------------------------------
NAME
	demo

SYNOPSIS
	tcc -o bm bm/c
	tcc -o fahr fahr/c
	tcc -o hanoi hanoi/c
	tcc -o plot plot/c
	tcc -o sieve sieve/c

DESCRIPTION
	Small-C demonstration programs:

		bm	PCW Benchmarks
		fahr	K & R tutorial example
		hanoi	Towers of Hanoi (uses VDU mode 2)
		plot	Recursive squares (uses VDU mode 2)
		sieve	Sieve of Eratosthenes

FILES
	:2.bm/c
	:2.fahr/c
	:2.hanoi/c
	:2.plot/c
	:2.sieve/c


--------------------------------------------------------------------------------
NAME
	diff

SYNOPSIS
	diff file1 file2

DESCRIPTION
	Line by line file comparison.

BUGS
	Not really diff (as in Unix), but still useful.

FILES
	diff.c


--------------------------------------------------------------------------------
NAME
	errors

SYNOPSIS
	Compiler error codes

DESCRIPTION
	Brief explanation of compiler error codes.  These have been
	deleted from the compiler to save space.

BUGS
	There are errors in the errors ...

FILES
	:0.$.errors	list of error codes
	tccom.c		source shows where errors are detected


--------------------------------------------------------------------------------
NAME
	get, put

SYNOPSIS
	*kermit
	take get

	*kermit
	take put

DESCRIPTION
	Kermit 'take' files to download/upload "tcc" system from MSDOS
	host.  Get "get" onto the BBC Micro first, then download the
	rest of the files automatically using the Kermit take command.
	The take files assume that the MSDOS kermit is in server mode,
	and the BBC Micro kermit is the 'local' kermit.

BUGS
	DFS/ADFS attributes need to be set using "install"

FILES
	get		Kermit takefile
	install		*exec file to set file attributes


--------------------------------------------------------------------------------
NAME
	getshar

SYNOPSIS
	*kermit
	take getshar

DESCRIPTION
	Kermit 'take' file to download "tcc" system from remote
	host.  Get "getshar" onto the BBC Micro first, then download the
	rest of the files automatically using the Kermit take command.
	The take files assume that the MSDOS kermit is in server mode,
	and the BBC Micro kermit is the 'local' kermit.  The shell
	archives are unpacked using the "unpack" command.

BUGS
	"getshar" assumes that two disk drives are available.

FILES
	getshar		Kermit takefile
	unpack		*exec file to unpack shell archives


--------------------------------------------------------------------------------
NAME
	install

SYNOPSIS
	exec install

DESCRIPTION
	Utility to set file attributes after downloading binaries with
	Kermit from MSDOS host.

BUGS
	Language ROM/RAM image must already be loaded.

FILES
	sfa		executable binary of utility to set file attributes
	swcrt		Language ROM/RAM image


--------------------------------------------------------------------------------
NAME
	ld

SYNOPSIS
	ld [-o outfile] [-R] file1 ... [filen]

DESCRIPTION
	Simple loader for stand-alone binaries, and ROM images of
	Small-C programs.  No link editing is done: the loader simply
	concatenates the binaries given as arguments with the
	appropriate run-time support.  All external references are
	resolved by the assembler, using the external symbol file
	"ext/s" or "swext/s".

	Options:
		-o outfile	specify name of output file
		-R		load sideways ROM/RAM image

BUGS
	The order of files in the argument list is critical, and
	relocation is impossible because the assembler produces absolute
	binary modules.

FILES
	a/out		default output file
	crt		stand-alone run-time support
	swcrt		sideways ROM/RAM run-time support


--------------------------------------------------------------------------------
NAME
	lib

SYNOPSIS
	tcc -S lib.c
	exec mkcrt
	exec mkswcrt

DESCRIPTION
	Small-C compiler library.  A few of the 'standard' C library
	routines have been implemented:

		atoi(s)
		fclose(fp)
		fgets(s, n, fp)
		fopen(name, mode)
		fprintf(fp, fmt, arg)
		fputs(s, fp)
		fscanf(fp, fmt, arg)
		gets(s)
		itoa(s, radix)
		printf(fmt, arg)
		puts(s)
		scanf(fmt, arg)
		sscanf(s, fmt, arg)
		sprintf(s, fmt, arg)
		strcat(s1, s2)
		strcmp(s1, s2)
		strcpy(s1, s2)
		strlen(s)
		strncat(s1, s2, n)
		strncmp(s1, s2, n)
		strncpy(s1, s2, n)

BUGS
	There are lots more functions to implement ...

FILES
	lib/c		Small-C source
	lib/s		assembly language file used to create "crt" and
			"swcrt"


--------------------------------------------------------------------------------
NAME
	lpr

SYNOPSIS
	lpr [-p] file

DESCRIPTION
	Expands tabs into spaces (for printers that can't handle tabs),
	and paginates output if required.  Output is directed to the
	screen and printer simultaneously using the MOS VDU driver to
	enable the printer.


	Options:
		-p	paginate output, and print header at top of page.

BUGS
	It's not a spooler - you have to wait until the printer stops.
	
FILES
	lpr.c


--------------------------------------------------------------------------------
NAME
	makefile [mktcc]
	
SYNOPSIS
	make host
	make

DESCRIPTION
	Zorland 'C' makefile for the MSDOS version of the "tcc"
	compiler.  The "host" target generates *.exe files for the MSDOS
	host system, and the default target generates 6502 binaries to
	be downloaded onto a BBC Micro using Kermit.

BUGS
	There is no Small-C make utility.

FILES
	makefile


--------------------------------------------------------------------------------
NAME
	rm

SYNOPSIS
	rm [-f] file1 [... filen]

DESCRIPTION
	Remove the list of files given as arguments.

	Options:
		-f	force removal, even if file is locked, and don't
			complain about non-existent files

BUGS
	Wild cards are not expanded.

FILES
	rm.c


--------------------------------------------------------------------------------
NAME
	sfa

SYNOPSIS
	sfa file

DESCRIPTION
	Set file attributes.  The load and execute addresses are both set
	to $1902.

BUGS
	Can't specify load and exec addresses as arguments.  The file
	access attributes are correct for ADFS, but set the "lock"
	attribute in DFS.

FILES
	sfa.c


--------------------------------------------------------------------------------
NAME
	sh

SYNOPSIS
	*sh

DESCRIPTION
	Small-C command "shell".  This is the Small-C Language ROM/RAM
	image that must be present in order to use the "tcc" compiler.
	The *sh entry into the Small-C Language ROM/RAM allows control
	to fall through to code immediately after the run-time support.
	This entry is patched to main() in the command shell by the -R
	option of "tcc":

		tcc -o sh -R sh/c

	The '*' in "*sh" is used by Basic to pass a command line to the
	MOS OSCLI (operating system command line interpreter).  This is
	necessary when invoking Small-C from Basic or View, but is not
	required when programs or operating system commands are invoked
	from the Small-C command shell.

	The shell implements a 'mode' command to change mode. Shadow screen
	modes are always selected if possible. Additionally, if a command
	if prefixed by '*' then the 'C' escape handler is temporarily
	disabled for the execution of the command. This is the correct way
	to exit the shell - use, for example, '*basic' or '*word', not
	'basic' or 'word'.

	On return to the shell any return value is osbyte 1 set by an
	executed command is displayed.

BUGS
	Global variables should not be used in programs produced with
	the -R option because the compiler places data immediately after
	the program text in what would then be read-only memory.

FILES
	swcrt		Sideways ROM/RAM run-time support
	sh.c		Small-C command shell


--------------------------------------------------------------------------------
NAME
	shar

SYNOPSIS
	shar [-a] [-x] archive file1 [... filen]

DESCRIPTION
	Unix style shell archiver for e-mail distribution of tcc system.
	The "archive" argument specifies the name of the archive file to
	be used.  Note: only text files can be archived with shar.

	Options:
		-a	create archive and add files
		-x	extract file from archive

BUGS
	Individual files cannot be extracted from an archive.  The entire
	contents of an archive are extracted.

FILES
	shar.c


--------------------------------------------------------------------------------
NAME
	stdio

SYNOPSIS
	#include <stdio.h>

DESCRIPTION
	'Standard' i/o header file.  Contains standard i/o channel
	definitions, and the macro definitions of putchar() and
	getchar().

	#define BUFSIZ 256		/* size of disk i/o buffer */
	#define NULL 0			/* null pointer of any type */
	#define EOF (-1)		/* end-of-file 'value' */
	#define stdin 0			/* standard (console) input stream */
	#define stdout 1		/* standard (console) output stream */
	#define stderr 2		/* standard (console) error stream */
	#define FILE int		/* no structures in Small-C ... */
	#define unsigned char *		/* no unsigned type in Small-C ... */

	#define getchar() getc(stdin)
	#define putchar(x) putc(x, stdout)

BUGS
	The FILE typedef cannot be implemented properly in Small-C, but
	the i/o streams are used as if they are implemented as (FILE *)
	to make Small-C a legal subset of full 'C'.  This is ok if no
	reference is made to the FILE structure other than its use to
	identify a stream in the 'f' i/o library (eg.  fprintf()).
	
FILES
	:0.$.stdio/h


--------------------------------------------------------------------------------
NAME
	sys

SYNOPSIS
	Operating system interface

DESCRIPTION
	The interface between Small-C and the underlying BBC Micro
	Machine Operating System (MOS) is written in assembly language.
	The entry points for low-level file i/o are modelled on their
	Unix counterparts, and the character classification routines are
	written in assembly language to increase their speed of
	execution.  Interfaces are also provided to the MOS osbyte 'fx'
	(effects), osword and osfile calls.

	Entry points:

		Assembler	Small_C

		_open		fd = open(name, rwmode);
		_creat		fd = creat(name, pmode);
		_close		status = close(fd);
		_unlink		status = unlink(name);
		_stat		stat(name, fcb);
		_system		system(string);
		__cmdlin	address = _cmdline()
		_read		nread = read(fd, buf, count);
		_write		nwritten = write(fd, buf, count);
		_getc		c = getc(fp);
		_putc		putc(c, fp);
		_vdu		vdu(c);
		_osbyte		osbyte(type, parameters);		
		_osword		osword(type, address);
		_osfile		osfile(name, fcb, type);
		_isalpha	t = isalpha(c);
		_isupper	t = isupper(c);
		_islower	t = islower(c);
		_isdigit	t = isdigit(c);
		_isxdigi	t = isxdigit(c);
		_isspace	t = isspace(c);
		_ispunct	t = ispunct(c);
		_isalnum	t = isalnum(c);
		_isprint	t = isprint(c);
		_iscntrl	t = iscntrl(c);
		_isascii	t = isascii(c);
		_toupper	c2 = toupper(c1);
		_tolower	c2 = tolower(c1);
		_toascii	c2 = toascii(c1);
		_ctype_		char ctype_[127];

BUGS
	File descriptors (fd) are used instead of (FILE *) for getc(),
	and putc() as in the rest of Small-C.  Pmode is ignored by
	creat(), and the system has no record of which files were opened
	by the user.  This means that programs must explicitly close
	files that they open (full 'C' will normally close files opened
	by the user on exit).  The character classification routines
	should be macros that use conditional expressions.  "System"
	doesn't spawn a new process, it just passes the line to the MOS
	command line interpreter (CLI).

FILES
	sys/s
	ext/s		stand-alone entry points
	swext/s		sideways ROM/RAM entry points

--------------------------------------------------------------------------------
NAME
	tcc

SYNOPSIS
	tcc [-o outfile] [-n] [-E] [-S] [-c] [-g] [-R] [-A] [-C] file

DESCRIPTION
	This is the Small-C compilation sequencer.  It arranges the
	various phases of the preprocessor "tcpp", compiler "tccom",
	assembler "as65" and loader "ld" according to a list of
	command-line arguments.  The sequencer generates a *exec file
	on the BBC, or a *.bat file in the MSDOS version, which is then
	executed to carry out the compilation.  By default, the compiler
	produces ROM-dependant code which makes external references into
	the Small-C language ROM.

	Options:
		-o outfile	specify name of output file (default a/out)
		-n		don't execute *exec (*.bat) file
		-E		run preprocessor only (no compilation)
		-S		generate an assembly language output file
		-c		suppress load phase
		-g		keep the global symbol output file "g/out"
		-R		produce ROMable code
		-A		produce 'stand-alone' code
		-C		insert 'C' source as comments
	
BUGS
	The technique of generating a *exec file is a crude alternative
	to the creation of child processes to carry out the compilation
	tasks.  This could be done in the MSDOS version, but requires
	much more effort under the Acorn MOS.  For simplicity, I have
	used the same technique in both.  Only one source file can be
	processed in this version, but the #include preprocessor
	directive can be used to combine several *.c files.

FILES
	tcc/c
	tcpp		Small-C preprocessor
	tccom		Small-C compiler
	as65		6502 assembler
	rm		file remover
	ld		Small-C loader
	:0.$.crt	Stand-alone run-time support, and compiler library
	:0.$.swcrt	Sideways ROM/RAM run-time support, and compiler library
	:0.$.ext/s	Stand-alone external references
	:0.$.swext/s	Sideways ROM/RAM external references
	:0.$.start/s	ROM-dependant startup code
	:0.$.enter/s	Control-flow patch to main() from user entry point
	compile		*exec file produced by sequencer

--------------------------------------------------------------------------------
NAME
	tccom

SYNOPSIS
	tccom [-C] infile [outfile]

DESCRIPTION
	Tiny 'C' compiler for the MOS Technology 6502 microprocessor,
	based on "RatC", Berry and Meeking's version of the original
	Small-C compiler for the Intel 8080 by Ron Cain.  The main
	difference between RatC and Ron Cain's Small-C is the use of a
	generic processor model with two working registers instead of
	8080 architecture.  Otherwise, the two compilers are almost
	identical.  The compiler (tccom) is normally invoked by a
	compilation sequencer (tcc), which arranges the various phases
	of the pre-processor, compiler, assembler amd loader.  The
	language features supported by "tccom" are essentially the same
	as those supported by "RatC", with more complete flow-control,
	and character escape sequences implemented.  Code generation is
	'optimised' for the 6502 in a 'small' machine environment on the
	BBC Micro.  The basic strategy is to generate code for a JSR
	threaded code interpreter, but whenever possible the contents of
	the 'C' primary register are kept in the 6502 X and Y registers.
	Two stacks are used: the 6502 hardware stack is used as the 'C'
	return stack and is used by the JSR threaded code interpreter,
	but the 'C' data stack is implemented in high memory using
	page-zero locations as a stack pointer.  This allows 'C'
	function stack-frames to be realistically large (the 6502
	hardware stack is limited to 256 bytes in page 1).  As with
	other implementations of Small-C, the language features
	supported are a (severely) restricted subset of full 'C' but I
	have made an effort to implement a legal subset that can be
	compiled with little or no modification by a full 'C' compiler.
	Consult the "Small-C Handbook" by James.E.Hendrix for a more
	complete description of the language.  Briefly, the features
	implemented in "tcc" are:

	Options:
		-C	output source code as assembler comments

	Types:
		char	8-bit (signed) promoted to int in expressions
		char[n]	8-bit (signed) promoted to int in expressions
		char *	16-bit (unsigned)
		int	16-bit (signed)
		int[n]	16-bit (signed)
		int *	16-bit (unsigned)
		extern	accepted, but ignored by compiler

		int function()
		int *function()
		char function()
		char *function()

	Operators:
		=	assignment			(low precedence)
		|	bitwise OR
		^	bitwise XOR
		&	bitwise AND
		==	relational equal
		!=	relational not equal
		<=	relational less-than or equal
		>=	relational greater-than or equal
		>>	bitwise right shift
		<<	bitwise left shift
		+	arithmetic add
		-	arithmetic subtract
		*	arithmetic multiply
		/	arithmetic divide (integer)
		%	arithmetic remainder (integer)
		-	arithmetic negation
		*	pointer indirection
		&	address of object
		++	arithmetic increment	
		--	arithmetic decrement
		f()	function call
		a[]	array subscript			(high precedence)

	Function calls:

		direct:
			function(args);

		indirect:
			char *address;
			address = &function;
			address(args);
		
	Control-flow:

		goto label
			...
		label:

		if (expression) {
			...
		}
		else {
			...
		}

		while (expression) {
			...
		}

		do {
			...
		} while (expression);

		for (expression; expression; expression) {
			...
		}

	Literal numbers:
		ddddd	decimal (where d is 0...9)
		0ddd	octal (where d is 0...7)
		0xdddd	hexadecimal (where d is 0...F or 0...f)

	Character escapes:
		\n	newline
		\t	tab
		\b	backspace
		\r	return
		\f	form feed
		\\	backslash
		\0	NULL
		\ddd	octal character code
		\c	any other character (where c is the character)

BUGS
	Arrays of character pointers are (incorrectly) treated as arrays
	of integers.  This leads to problems recovering command line
	options prefixed by '-'.  The fix is to AND with 0xFF, and
	various programs are commented "BUG in compiler" where this is a
	problem.  The code to implement "for" fails on the commonly used
	construct "for (;;)" which is used in 'endless' loops, and the
	code generated to implement "for" needs the entire expression on
	one line of the input stream.  The same is true for function
	calls, where the entire argument list must be on one line.  The
	analysis of the "for" construct is clumsy, and needs re-writing
	to jump round the end loop action, rather than deferring code
	generation which is used at present.  The "switch" construct has
	not yet been implemented.

FILES
	tccom.c


--------------------------------------------------------------------------------
NAME
	tcpp

SYNOPSIS
	tcpp [-Dname] infile outfile

DESCRIPTION
	Small-C preprocessor, with file inclusion and conditional
	compilation directives.  The #asm ...  #endasm directive found
	on other Small-C preprocessors is deliberately omitted because
	it leads to non-portable code.  Assembly language routines are
	incorporated in Small-C programs by combining them with the
	assembler source generated by the compiler, during assembly of
	the program.  This allows machine dependencies to be hidden from
	an applications program.  The preprocessor implements a subset
	of the Unix 'C' preprocessor "cpp":

	File inclusion:

		#include <file>		file in 'standard' directory
		#include "file"		file in current directory

	Macro replacement:

		#define name
		#define name(args)

	Conditional text inclusion:

		#if constant		test for non-zero constant
			...
		#else
			...
		#endif

		#ifdef name		test for defined macro name
			...
		#else
			...
		#endif

		#ifndef name		test for undefined macro name
			...
		#else
			...
		#endif

	Options:
		-Dname			#define name on command line

BUGS
	Constant expressions cannot be used (as in #if expression), and
	the newline escape '\' is not implemented in macro definitions
	which must, therefore, be confined to a single line of text.

FILES
	tcpp/c
	:0.$		'standard' directory for #include <file>
	:0.$.stdio/h	'standard' i/o #include file
	:0.$.ctype/h	dummy character classification #include file


--------------------------------------------------------------------------------
NAME
	unpack

SYNOPSIS
	exec unpack

DESCRIPTION
	The BBC Micro version of tcc is distributed over e-mail or BBSs
	as a collection of Unix 'shell' archives.  This is a convenient
	format for packaging up several files, and protecting them from
	e-mail systems that occasionally interpret parts of unprotected
	files as message headers.  This may cause the file to be
	corrupted, or it may fail to arrive.  The archive files should
	be downloaded onto a BBC Micro as indicated in the FILES section
	below.  An example kermit take file is provided, or the files
	can be downloaded individually.  The unpack utility assumes that
	you have a two-drive system.
	
	The 6502 binaries of the Small-C Language ROM and "shar" program
	must first be de-hexed and the "sh" file loaded into sideways
	RAM.  The unpack script uses the "shar" program to extract the
	other hexfiles from tcc1 and tcc2.  These are dehexed, and the
	remaining source files are extracted.  The resulting disk
	contains the complete tcc source distribution.  Make a copy of
	the disk before attempting to use the compiler, and delete some
	of the source files to make room for temporary files created by
	the compiler.

BUGS
	It takes a  l o n g  time to extract the files.

FILES
	:0.getshar	kermit take file to download shell archives
	:0.mkboot	*exec file to dehex Small-C boot files
	:0.sh/x		6502 hex file of Small-C Language ROM/RAM image
	:0.dehex/x	6502 hex file of Intel hex decoder
	:0.shar/x	6502 hex file of shell archive program
	:1.unpack	*exec file to unpack archives
	:1.tcc1		shell archive #1
	:1.tcc2		shell archive #2
	:3.tcc3		shell archive #3
	:3.tcc4		shell archive #4
	:2.READ/ME	tcc documentation


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