HCS-II C source code compilation
Micro-C modifications

Copyright 1992 Circuit Cellar Inc
Ed Nisley



This file contains the information you need to recompile the Micro-C source code for the Circuit Cellar INK Home control project.  It looks more complex than it really is, so don't lose heart.  Read over the instructions and take your time...


Diskette files

There are four directories on this diskette:

	\		HEX and information files
	\source	project source code files
	\direct	common serial I/O source code
	\custom	additional Micro-C headers and other files

If you just want to burn the HEX files into EPROMs, pick them out of the root directory and skip the rest of this note.


Micro-C directory layout

The directory structure I use is somewhat different from the one Micro-C's INSTALL program sets up for you.  I've used environment variables to point to the various directories so you should be able to use the default layout by modifying SETMC.BAT.  However, I know my setup works, so I'm reluctant to tinker with it...

Basically, I use drive D rather than C, call the base Micro-C directory \mc51 rather than \mc (so I can add other compilers and keep all the programs, headers, and library files separate), and put the header files in a separate directory:

	D:\mc51			Micro-C executable files
	D:\mc51\include		header files normally in \mc51
	D:\mc51\lib		8051 library files, normally \lib51
	D:\mc51\custom		my modified files and so forth

Early versions of the Micro-C install program hang the 8051 run time library (\lib51) off \mc51\pcutil.  You should create \mc51\lib and copy the library files into it (or use a directory mover program if you've got one).  INSTALL may also put several 8051 files into \pcutil, so move those to the appropriate spots.

Once you get the Micro-C files arranged you can add the customized files from the diskette:

	copy a:\custom \mc51\custom

The directions in the next steps will tell you how to move other files from \mc51\custom to their permanent homes.

If you plan to use just the 8051 Micro-C programs you can delete the files for the other CPUs.  Browse through the directories, see what's there, and discard what you don't need.  You can always recover an essential file from the distribution diskettes using the MAR utility if you get carried away.


Include files

INSTALL normally puts Micro-C's *.h files into the \mc51 directory, but early versions tucked them into PCUTIL or elsewhere.  The only ones you need for the 8051 compiler start with 8051, as in 8051bit.h, so you can delete the others.

The *.h files in \mc51\custom should stay there, as the source code includes a direct directory reference that you'll probably have to change to match your system's layout.  Look in the main C file (smartx10.c for the smartx10.hex program) for the #include statements:

	#include "d:\mc51\custom\8051base.h"
	#include "d:\mc51\custom\8051sfb.h" 

I don't know of a good way to parameterize those statements; if you come up with anything, let me know!


Libraries

COMPACT.LIB defines which functions should be linked in from the 8051 run time library files in \mc51\lib.  Because my serial interface handler uses interrupts rather than polling, all the standard functions must be removed.  Use SLIB to do this:

	SLIB i=compact.lib r=llio2.asm r=llio5.asm r=serinit.asm 

This will leave putch, getch, and putstr unresolved because they are in the program source code rather than the library.  You need to edit the library files to remove the external declarations:

	LLIO3.ASM		comment out $EX:putch
	LLIO4.ASM		comment out $EX:getch
	PRINTF.ASM		comment out $EX:putstr

Admittedly, a better way to handle this would be to put the serial functions in the library, but there are complications arising from the way I allocate variables.

My source code also includes different versions of the character classification functions, which are in my FFISFUNS.ASM file.  Use SLIB to replace the library code:

	COPY \mc51\custom\ffisfuns.asm \mc51\lib
	SLIB i=compact.lib r=isfuns.asm a=ffisfuns.asm


Startup code 

8051RLPC.ASM must be modified to locate RAM and EPROM at the right addresses and allow room for the interrupt vectors.  The new values are:

	?RAM		EQU		$A000		* start of RAM
	?RAMEND	EQU		$BFFF		* end of RAM
			ORG		$0000		* start of EPROM

Note that the RAM does not start at 8000 as you might expect.  The HCS COMM-Link board does not include a jumper to hold pin 26 high; that pin is A13 on 32K RAMs and +CE on 8K RAMs.  Locating the RAM variables at A000-BFFF makes A13 high for all references, so the RAM is enabled.  The firmware does not take advantage of a 32K RAM, as it uses addresses in the defined range regardless of which chip in installed.

After the "* Basic Startup code" comment, insert

	* Basic Startup code

			SJMP		?start
			ORG		$0030
	?start	EQU		*

			MOV		SP,#?stk-1		Set up the initial stack

Change the jump just after LCALL main:

			LCALL		main
			LJMP		?start

That will restart the program if the impossible happens and the code falls out of the main loop.  The original jump entered a monitor program that isn't present in my code.  The main loop uses a while(TRUE) construct, to this jump "will never be executed" (in principle, anyway).

These changes apply only to the COMPACT memory model startup code, so you'll have to make similar changes for your other projects.  You may want to create separate versions of 8051RLP*.ASM for those projects, which is what the MCMODEXT environment variable is intended to handle.  Read MCCOMP.BAT to see how and where it's used.


Source code

Set up a directory to hold the project's source code, then copy it from the diskette:

	md \smartx10		(or whatever!)
	copy a:\source \smartx10

The \direct subdirectory holds all the serial-port code needed for the RS-232 connection; the files in this subdirectory are used by all the HCS2 modules. Create a corresponding subdirectory on your disk and copy the source code:

	md \direct
	copy a:\direct \direct

If you are working on several of the HCS-II projects, you might want to arrange the source code in a common tree:

	md \hcs2				-- this will have no "real" files
	md \hcs2\direct			-- you need only one of these
	md \hcs2\smartx10		-- files for X10 interface
	md \hcs2\lcdterm		-- files for LCD terminal


Compilation

You should copy the SETMC.BAT and MCCOMP.BAT files from the \mc51\custom directory to \mc51, because that directory should be in your PATH statement: 

	copy \mc51\custom\*.bat \mc51

SETMC.BAT initializes the environment variables expected by MCCOMP.BAT: check that they point to the right disks and directories for your system!  If MCMODEL isn't defined, SETMC will use COMPACT memory model, which is required for the hardware used in these projects.

If you have a RAM disk (specified by the RAMDISK variable), make sure it's big enough to hold the temporary files created during the compilation; my RAM disk is about 1.4 MB and the temporary files for each project run to about 800K (the LST files are huge!).  You may want to aim the temporary file directory at your hard disk until everything else works correctly.


The BUILD.CTL file contains #define statements that determine how the source code will be compiled.  The REBUILD.BAT file copies various CTL files into BUILD.CTL and then runs MCCOMP to do the compilation.  To rebuild everything run REBUILD and sit back.  It expect to find the *.CTL files in the parent directory, so you sould copy them from the diskette to the parent:

	copy a:*.ctl c:\hcs2

MCCOMP.BAT compiles, source links, and assembles the Micro-C source code, then downloads the HEX file using my Parallax EPROM emulator.  It does much the same thing as Micro-C's control program, but provides finer control over the intermediate steps.  In particular, you can direct the temporary files to strange locations and keep all the temporaries to investigate strange behaviors during compilation.

The best way to verify that you've got everything installed correctly is to compile the source code and compare it with the HEX file on the distribution diskette.  If they match exactly you're in good shape.  If they don't, see if you can track down what's changed.  Pay particular attention to the line addresses in the HEX file; if you forgot to modify 8051RLPC.ASM they'll be entirely different.

However, different versions of the compiler, optimizer, and run time libraries may produce slightly different code from the same C source code.  The ultimate test is, of course, to burn an EPROM and see how it work...


But, if it doesn't work...

Contact us through the Circuit Cellar BBS rather than over the phone.  You are probably not the first person to run into trouble and the BBS is the best way to exchange information!


Enjoy!


Ed Nisley