readme

很少见的源码公开的msc51和z80的c编译器。

   number, and should be zero for the first scope, and increment
   for each new scope within the function.  Since NoICE cannot currently
   cope with scope finer than function, it will produce symbols of
   the form:
	FILE text
	FUNC name
	DEFS name2_integer symbolvalue

   The trailing "_integer" will be omitted for integer == 0 (function).

11) The linker will process symbols with names of the form
	text.name..FN

   into NoICE FILE, DEFINE, and FUNCTION commands in the .NOI 
   file (if any), to define the start of a global function:
	FILE text
	DEF  name symbolvalue %code
	FUNC name symbolvalue

12) The linker will process symbols with names of the form
	text.name..SFN

   into NoICE FILE, DEFINESCOPED, and SFUNCTION commands in the .NOI 
   file (if any), to define the start of a file-scope (static)
   function:
	FILE text
	DEFS name symbolvalue %code
	SFUNC name symbolvalue

13) The linker will process symbols with names of the form
	text.name..EFN

   into NoICE ENDFUNCTION commands in the .NOI file (if any) to
   define the end of a global or file-scope function:
	ENDF name symbolvalue

14) The linker will output the symbols in each "area" or memory
   section in order of increasing address.

15) The linker will output the ";!" lines after all symbols
   have been output.

The features listed above may be used to add full source-level
debug information to assembly files produced by a compiler.  The
example file ctest1.c, and the hypothetical ctest1.s produced by
compiling it illustrate this.  The comments in the file describe
the information, but would not be present in an actual implementation.

1) Begin each file with a ";!FILE" specifying the file name and its 
   original extension (usually ".c"), and with the path if the file is 
   not in the current directory.
	;!FILE ctest1.c

2) Define any basic data types: char defaults to S08.  Redefine as U08 or 
   ASCII if you desire.  "int" defaults to S16.  Redefine if necessary.
	;!DEFT 0 char %ASCII

3) Define any data structures, typedefs, enums, etc. (C generally 
   does this per source file.  Types will remain in scope unless 
   redefined).  For example, the C structure

	typedef struct {
	   char  c;
	   int   i;
	   int   ai[ 10 ];
	   int   *pi;
	} STR;

   would generate the commands:
	;!STRUCT 0. STR
	;!DEFT 0. c %char
	;!DEFT 1. i %int
	;!DEFT 3. ai %int[10.]
	;!DEFT 23. pi %*int
	;!ENDS 25.

   Since the user can change input radix at will, it is generally 
   recommended to specify radix explicitly in the ;! commands: by
   a trailing "." for decimal, or leading "0x" for hex.

4) Use ;!FUNC, (or ;!SFUNC), ;!DEFS, and ;!ENDF to define any 
   function arguments and local variables.  The function
	void main( void )
	{
	   /* declare some local variables */
	   char lc, *plc;
	   int *pli;
	   int *lnpi;
	   int *lfpi;
	   ...

   would generate stack-based symbol definitions with their datatypes.
   (Note that the stack offsets are not passed to the assembler by
   name, as they need not be relocated.  Thus, it is the compiler's
   duty to generate these.  Note that the 68HC11 TSX instruction
   increments the value of SP by one.  Thus, "SP+nn" should use
   "nn" values one greater than for use as offsets from X.
	;!FUNC main
	;!DEFS lfpi SP+6. %*int
	;!DEFS lnpi SP+8. %*int
	;!DEFS pli SP+10. %*int
	;!DEFS plc SP+12. %*char
	;!DEFS lc SP+14. %char

   When all local variables and parameters have been defined, the
   function scope must be closed:
	;!ENDF

5) In general, it is desirable to generate two symbols for each
   function:  one with an underbar, at the first byte of the
   function, so that the disassembler will show it as the destination 
   of the JSR; and a second without an underbar at the address of
   the first source line after stack frame is set up.  The latter
   will be a common breakpoint location.

   CUG292 can generate global symbols by using a "::"
	_main::		
		tsx
		xgdx
		subd #44
		xgdx
		txs

6) Once the stack frame is set up, declare the beginning of the
   function body.  The value of this symbol is the lowest address
   which NoICE will consider to be within the function for scoping
   purposes.
	ctest1.main..FN::

7) Each C source line which produces code should emit a symbol
   consisting of the file name without path or extension, followed
   by the line number (in decimal) in the C source file.
	ctest1.56::
		ldd #6
		std  _gestr

8) Declare the end of the function body.  The value of this symbol 
   is the highest address which NoICE will consider to be within the 
   function for scoping purposes.  The address must be on or before 
   the RTS, so that it does not overlap the following function.
   Normally, the address will be the last C source line in the 
   function before stack frame is destroyed.
	ctest1.main..EFN::      
		xgdx
		addd #44
		xgdx
		txs
		rts

9) Global variables defined in the file, and their datatypes, may be
   defined at any time.  Debugging is most convenient if the 
   traditional C leading underbar is omitted.  The global declarations
	int gi;
	STR *pgstr;

   would generate:
	;!DEF gi %*int
	gi::
		.blkb 2

	;!DEF pgstr %*STR
	pgstr::
		.blkb 2

   Here, the ";!" command defines the datatype, which is unknown to
   the assembler, while the "::" defintion defines the value, which
   is unknown until link time.

10) File-scope static variables, and their datatypes, must be defined 
   between the ;!FILE and the ;!ENDFILE in order to set proper scope.
   Debugging is most convenient if the traditional C leading underbar 
   is omitted.  The static declarations
	static int si;
	static STR sstr;

   would generate:
	;!DEFS si %*int
	ctest1.si::
		.blkb 2

	;!DEFS sstr %STR
	ctest1.sstr::
		.blkb 25

   We note that while the ;!DEFS must be between ;!FILE and ;!ENDFILE,
   the "::" definitions may be elsewhere in the file if it is
   convenient, as the symbol name carries the scoping information.

11) Function-scope static variables, and their datatypes, must be 
   defined between the ;!FUNC (or ;!SFUNC) and the corresponding
   ;!ENDF in order to set proper scope.  Debugging is most convenient 
   if the traditional C leading underbar is omitted.  The static 
   declarations
	void main( void )
	{
		static int si;
		static STR sstr;

   would generate:
	;!FUNC main

   at some point, and then
	;!DEFS si %*int
	ctest1.main.si::
		.blkb 2

	;!DEFS sstr %STR
	ctest1.main.sstr::
		.blkb 25

   We note that while the ;!DEFS must be between ;!FUNC and ;!ENDF,
   the "::" definitions may be elsewhere in the file if it is
   convenient, as the symbol name carries the scoping information.

12) After all code, data, and ;! defintions, declare end of file.
   This is necessary to prevent mangled scope when several modules
   are linked together.
	;!ENDFILE

        CTEST1.C - sample C source code
        CTEST1.S - output from ImageCraft compiler, hand-doctored 
                   to add additional debug information
	CTEST2.C - second C module
        CTEST2.S - output from ImageCraft compiler, undoctored
        CTEST.BAT - assemble and link CTEST1+CTEST2

Run CTEST.BAT to produce CTEST1.NOI, a NoICE command file.

end README