
	ASM_C84 -- A Simple One-pass Assembler For The PIC 16C84
	-------    - ------ -------- --------- --- --- --- -----


This is a set of programs that I did for a software tools class in Fall
1995.  Now that I've got my grade, we all get the goods.


			What Is A PIC 16C84?

A 16C84 is a handy little CMOS EEPROM microcontroller that is part of
Microchip Technology's PIC product line.  Thus, it is a complete, but
small, computer that can be reprogrammed electrically (no UV lights
needed!) while still in the target circuit.  It keeps its program even
after it has been turned off.  Because it uses CMOS logic, a PIC 16C84
takes very little power to operate.


			Building The Programs
			======== === ========

If you're not used to building public domain software, just follow these
easy steps:

1) Pick the Makefile that best matches your system's software tools and
make a copy named Makefile.  Example:  Suppose you're running Linux.
Makefile.gnu best matches your system, so type the following:

	cp Makefile.gnu Makefile

(Note:  If you're running an Amiga with SAS/C, just use the SMakefile
that is provided.  SAS likes to start all file names with 's'.)

2) Edit your new Makefile with a text editor.  (*Please* don't use a
word processor!  That would add all kinds of extra format bytes that
will confuse the "make" program.)  Type:

	vi Makefile

	    or

	emacs Makefile

3) If needed, change the lines for CC, YACC, LEX, etc to match your
system.  Example:  Suppose your system comes with byacc instead of bison.

	Remove the '#' character from the following line that contains
	"byacc", and add one in front of the line that contains "bison".

#YACC=	yacc
#YACC=	byacc
YACC=	bison

	You should end up with:

#YACC=	yacc
YACC=	byacc
#YACC=	bison

4) If your C compiler, yacc, or flex programs aren't found on your
execution PATH, you may have to spell out exactly where to find them in
the Makefile.  Example:

	YACC=	/usr/local/bin/bison
	LEX=	/gnu/bin/flex
	CC=	C:\gnu\compiler\gcc

5) When you're done customizing the Makefile, write it out, exit the
text editor, and type:

	make

6) The first time you try this, things will go wrong.  Be prepared to
fix the Makefile and try again.  Ultimately, you will end up with two
new programs:  asm_c84 and dis_c84.  You can use them where they were
built, or move them into a directory on your execution search path.

The Makefile will also automatically assemble and disassemble two 16C84
assembly files.  Please check test.lst and wl_mine.lst for any errors.



			APPENDIX
			--------


	      What *ARE* These Weird YACC And Lex Things?
	      ---- ----- ----- ----- ---- --- --- -------

"Flex" is the Berkeley version of "lex", AT&T's lexical analyzer
generator program.  You feed in a description of what patterns you'd
like matched (the file lex.l), and flex/lex spits out a file that
contains a subroutine named yylex, plus lots of tables and what-not.
When yylex is working, it will take characters from the input stream
(yyin) and match them against your patterns.  When a pattern matches,
yylex executes the associated action.

This all sounds pretty dry -- time for an example:

[0-9]+		{ printf("Got a number:  %d\n", atoi(yytext)); }
  ^                     ^
  |                     |
This is the pattern   This is the action.

The pattern defines a base 10 number.  It means "fire the action when
there is one or more characters in the set of '0' through '9' on the
input.  The characters will be found in yytext.

The example action prints out "Got a number:  " followed by whatever
number matched the pattern.

Flex has been picked up by the GNU folks, so check your local Free
Software Foundation mirror site for a copy.  Its available for just
about everything from Amigas to Atari STs to VAXs to UNIX boxes.  (If
you want working binaries rather than source code, where you look
depends on what kind of computer and OS you have.  Some sites stock
binaries for lots of systems.  In North America, try wuarchive.wustl.edu)

You'll also need a copy of yacc, or a yacc clone like bison or byacc.
Yacc (Yet Another Compiler Compiler) is a program that turns a BNF
grammar file (in this case, gram.y) into C code for a parser.  It is
designed to work with lex.  The parser calls yylex, and expects it to
return groups of matched patterns, or "tokens", which the parser will
try to assemble into meaningful sequences.

Think of it like this:  the lexer groups letters into words, which the
parser then builds into sentences.

However, the parser doesn't just string words together; it can build
them into "tree" structures much like the sentence diagrams that are so
widely hated in English class.  Although incomprehensible to high school
students, a parse tree is a very useful data structure for a computer.



			Version Information

$Id: READ_ME.txt,v 1.1 96/01/25 00:33:48 jamesc Exp Locker: jamesc $
