USER DOCUMENTATION: MOTOROLA 68705 SUPPORT SOFTWARE
===================================================

1. PRELIMINARY
 This program was written by David R. Brooks <daveb@perth.dialix.oz.au>
over the period 1988 - 1991, as part of an academic research project.
That project was commercially sponsored, and permission has been granted
by the sponsor to offer this program (which is considered of no further
commercial value) to the public domain.

 I am therefore making the program, and its source-code, available as
"freeware". You are welcome to copy, translate, alter or improve this
program as you will, and also to re-publish such altered versions.

 Indeed, I rather hope people may be encouraged to produce "derivative
works" for other microcomputers. The code-specific parts are largely
table-driven, so this should not be too painful.

 I ask only three things, as you use this program:

 a) You do not SELL or RENT any copy of the program or a derivative
    (after all, I have not charged you).

 b) You do not ask me to provide support, or to accept any liability
    for your use of the program (it is free).

 c) You leave this notice intact.

Acknowledgements:

 The functions ENVIRONMENT and SUBPROCESS are adapted from code published
by Borland International (publishers of Turbo Pascal), and in the public
domain.

 The arithmetic-expression parser (in file 68705ASM.PAS) is based on the
recursive-descent parser published in "Advanced Turbo-Pascal Programming
and Techniques", by H. Schildt (McGraw Hill, 1986).

 The research project of which this software formed part, was funded by
Magellan Technology Pty Ltd, Perth, Western Australia. Their permission
to publish is gratefully acknowledged.


You may also want to consult the WWW page for Motorola MASM project, which 
contains utilities to generate S-records ie:                                                          
                                                                                
http://freeware.aus.sps.mot.com/freeweb/msa_ndx.html#masm_dos                   
 

2. FILES
 The upload is in two parts: the executable and the source. You only need
source if you want to change the program code.

 Part 1: Executables 
	README   TXT		You are reading it
	68705    COM		The program executable

	A basic demonstration, adapted from a Motorola application note.
	TEST     SRC		Main source code
	68705F2  ASM		Include file
	TEST     LST		Assembler listing
	TEST     HEX		Assembled code, in Motorola S19 format

 Part 2: Source Code
	68705    PAS		Main-line: this 'includes' the others
	68705ASM PAS		Code assembler
	68705DBG PAS		Debugger/emulator
	68705VIW PAS		List-file viewer
	68705OPC PAS		Target machine op-code tables
	68705SVC PAS		Miscellaneous services

	TESTER   PAS		A utility, to aid in testing the code

 The original code was compiled using Borland Turbo Pascal version 3.0
I have not tested it with any later version.


3. INTRODUCTION
 The program 68705.COM provides a basic software-development facility
for the Motorola MC68705 series microcomputers. Integrated facilities
are provided for editing, assembly, emulation/debugging, and load/save
of binary or hexadecimal memory images. The hexadecimal core-image
option saves in Motorola S19 format, which can be read by many device 
programmers.
 The program has been used over the years to produce several real
applications.

4. ENVIRONMENT
 68705 will run on almost any PC. It was originally developed on a
PC/XT, with 640kB, and a CGA screen. It should even run in monochrome,
though I have not tried it. It runs fine in a DOS-box under Windows 3.11
(I have not tried NT), even in a reduced-size box.

 A mouse is not directly supported, though I have used one with a free-
ware TSR which translated mouse actions into cursor keys. (That was
years ago: I no longer recall what that TSR was called.)

 MS-DOS 3.3 or higher will run OK.


5. EDITOR
 68705 is designed to work with an external text editor. The editor may
be pre-defined by setting the DOS environment variable WORDPATH to the
path\name of your editor. If WORDPATH is not defined, you will be offered
a chance to select an editor when the program starts up. If you reject
this chance also, the EDIT selection will be disabled.

 Just about any basic ASCII text editor should do. I have used both
WordStar(tm) and MSDOS Edit successfully.


6. STARTING UP
 After defining your WORDPATH variable (if you choose to), simply execute
68705 <file> at the DOS prompt. An extension on <file> is optional, the
default is .SRC  You can leave <file> blank.

 When 68705 starts up, you will see the opening menu at the left, and its
dialog box at the right. Begin by selecting a filename (if you did not at
the command line), and set the memory size. THIS LAST STEP IS ESSENTIAL, 
as the emulator will look for initialisation vectors at the memory addresses
proper to the device type you select here.

 Most selections will offer you a default file-name: this can be overridden
as necessary. When all necessary file-names have been selected, a final
confirmation (Yes/No) is made, before the task is launched.


7. ASSEMBLER
 The in-built assembler is run from the main menu. It reads source code, and
builds a binary image directly in the emulated memory space.

 The assembler considers the processor memory to be divided into two segments:
RAM and EPROM. Assembly output is directed into one or the other by placing
the DATA and CODE pseudo-ops in the source file. The current assembly address
is tracked independently in the two segments. Note that the assembler does
NOT check the logical sense of your use of these segments: you are quite free
to assemble code into RAM, or run-time data into EPROM!

 The following notes on coding are extracted from the source-code file of the
assembler module, and assume you are already familiar with the Motorola 
assemblers:

                 Code mnemonics as Motorola, plus MSG 'string' defines msg.
                 All expressions are Absolute.
                 The assembler is one-pass, into core.
                 Operand expressions may include
                    Operands:
                       Symbol      - a pre-declared name
                       Dec. Const. - decimal digits
                       Hex. Const. - '$' then hex. digits
                       Char Const. - 1 or 2 chars. in quotes, as 'AB'
                       Current Loc - '$', not followed by hex. digit

                    Operators:
                       ( ) ^ * / & | ~ + -   in order of precedence

                    Logical Operators:
                       &   And
                       |   Or
                       ~   Exclusive Or

                    Note that ^ denotes "raise to the power of".

                 Expressions are evaluated in 16-bit arithmetic.
                 Address expressions may be preceded by one undefined symbol,
                 followed by '+' or '-' (no other operator allowed). The
                 resulting expression is of type "undefined".

                 Immediate operands are preceded by '#' (else they are address
                 references).

                 If several errors occur on one line, only the first is logged.

           NOTE: The error "1-Byte address too large" will be flagged from a
                 forward reference expression, when the expression is RESOLVED.
                 Look immediately above the flagged code line, for the list of
                 locations here resolved; one of them will be the error.
                 From non-forward referenced expressions, the "too large"
                 will be flagged at the line containing the expression.


           PSEUDO-OPS: The following Pseudo-ops. are supported:
                 INCLUDE  'file'    - Include named file in the assembly
                 TITLE  'string'    - Use <string> in page title (also Ejects)
                 EJECT              - Force listing to new page
                 PAGE  n1, n2       - Sets n1 lines/page, n2 cols./line.
                 CODE               - Selects the EPROM memory bank pointer
                 DATA               - Selects the  RAM  memory bank pointer
                 IF                 - Conditional Assembly, op-2     = op-3
                 IFNOT              -  ditto              , op-2 not = op-3
                 ENDIF              -  ditto, end conditional block
                 LISCN              - Allows listing suppressed cond. asm.
                 NOLCN              - Inhibits ditto [LISCN is default]


8. EMULATOR
 Once program code is loaded (either by assembling a source file, or by
explicitly loading a core-image file), the Emulator may be launched.

 You will be invited to specify a "Viewer" file with the emulation. This 
file may be viewed alongside the simulation results. Typically, you would
choose the assembly listing file (this is the default).

 The emulator works in a manner similar to the MS-DOS "Debug" utility. The
valid commands are listed at the bottom of the screen. The program counter 
("P") is initialised from the restart vector in memory.

 When a breakpoint is encountered, execution will halt, and the emulator will
display the following:
  a) Number of emulated bus-cycles since the "Go" command was issued
  b) Locations of the last 16 (or less) instructions executed
  c) Current register contents (as for the "R" command)

 The "Help" command splits the screen, showing the valid command syntax in a
window at the right. Any key-stroke will close the help window, and return
to the emulator.

 The "View" command similarly splits the screen, but shows instead a page of
the selected Viewer file. This page may be scrolled using the keyboard (valid
keys are displayed at the bottom of the screen).


9. LOAD HEX/BINARY FILE
 This choice enables a previously saved memory image to be uploaded. THE CURRENT
MEMORY IMAGE WILL BE DESTROYED. You are invited to save the current image before
it is overwritten.

 The "binary" file format is a direct dump of the simulator memory. Its chief
use is to re-load later, to save having to re-assemble a program.

 The "Hex" format is Motorola S19 records. Besides being re-loadable by the
simulator, this format can be read by most device programmers.


10. SAVE HEX/BINARY FILE
 The converse of the previous command, this writes out the current memory
image.


11. IMPROVEMENTS
 I haven't time to do these myself, but the following ideas are suggested for 
others who may feel like doing enhancements.

 a) Re-write it in "C", and compile under the GNU free compiler, to remove the
    dependence on an obsolete version of Turbo-Pascal.
 b) Add ELSE and ELSEIF pseudo-ops. to the assembler.
 c) Add a CANCEL selection to the Load File selection (at present you are
    committed to losing the current memory load: your only choice is to save
    it first).
 d) Pull out the tables which select CPU type, restart vector and memory size,
    and put these in a separate configuration file, so new CPU versions can be
    easily added.
 e) Add support for newer CPU instructions, eg the 68708 series.
 f) To facilitate adaptation to other than Motorola machines, add a switch which
    causes word data to be stored in little- or big-endian format.

12. RE-COMPILING
 The following notes apply to the original Version 3 Borland Turbo Pascal.
 a) Just compile the main source file (68705.PAS), it includes all the others.
 b) Compile to a .COM target.
 c) Set the maximum stack size to (say) 2000 paragraphs: if you let it take
    everything (the default), you will have no space left to run an editor.

