+-------------------------------------+
| HD6303 Assembler Package for the PC |
+-------------------------------------+

Contents:       1. Files in this package
                2. What is this package ?
                3. What is PCMAC ?
                4. Preparing source files
                5. Using the assembler
                6. Using the hex convertor
                7. Sample files provided
                8. Contact Information/Disclaimer

+--------------------------+
| 1. Files in this package |
+--------------------------+

       1.   README.TXT      - a brief description of the package

       2.   ASMDOC.TXT      - this documentation file

       3.   ASM.BAT         - batch file to run the HD6303 assembler
       4.   ASMLIST.BAT     - as ASM.BAT but also makes a listing file

       5.   HITACHI.MAC     - standard INCLUDE file for HD6303 programs
       6.   HD6303.MAC      - macros to turn PCMAC into an HD6303 Assembler
       7.   SERVICES.MAC    - macros to simplify the interface with Psion OS

       8.   EXAMPLE.ASM     - meaningless example showing the assembler syntax
       9.   EXAMPLE.PRN     - the listing file made by the HD6303 assembler

      10.   BOOT.ASM        - a tiny sample HD6303 source file
      11.   BOOT.PRN        - the listing file made by the HD6303 assembler

      12.   MC6303.ASM      - example with the entire HD6303 instruction set

      13.   CONVERT.BAT     - batch file to run the hex convertor (TSK2HEX)
      14.   TSK2HEX.EXE     - utility to convert PCMAC output to ASCII HEX

      15.   PCMAC.EXE       - freeware PCMAC Universal Macro Assembler

      16.   HISTORY.TXT     - development history for HD6303 Assembler

      17.   PCMACEXE.ZIP    - complete PCMAC archive with documentation

+---------------------------+
| 2. What is this package ? |
+---------------------------+

This is a PC-based assembler for the HD6303 microprocessor used in the Psion
Organiser II machines.  It is based  upon the freeware PCMAC Macro Assembler
and comes with additional utilities to make it easy to prepare machine code
programs for use on the Psion Organiser.

+--------------------+
| 3. What is PCMAC ? |
+--------------------+

PCMAC is a Universal Macro Assembler which is not dedicated to a particular
microprocessor.  It is a "skeleton" assembler which can be configured, by
means of a set of macros, to handle any processor. PCMAC was originally
shareware but it generated very little interest so the author, Peter Verhas,
generously transformed it into an unsupported freeware package.

What I have done is create the necessary macros to turn PCMAC into a two-pass
assembler for the Hitachi HD6303 microprocessor which is used in the Psion
Organiser II family of machines and provide some additional utilities.

The only part of the PCMAC package required for this HD6303 Assembler is the
executable, PCMAC.EXE, which has already been extracted from PCMACEXE.ZIP and
is ready for use.

The PCMACEXE.ZIP file is a complete copy of the archive for the freeware
PCMAC Universal Macro Assembler, as distributed on the Internet. Although
none of the files in this archive need to be extracted in order to use the
HD6303 Assembler, I recommend that you extract the manual, USRGUID.TXT, if
you wish to learn more about PCMAC and its macro language. It is a powerful
package with a large number of features so the manual is very long!

+---------------------------+
| 4. Preparing Source Files |
+---------------------------+

The recommended file name extension for assembler source files is
".ASM".  Similarly, any macro files which are INCLUDED should use the
extension ".MAC".

Every ASM file must start with the line

        #include <hitachi.mac>

to configure PCMAC as an HD6303 Assembler and ensure that when a listing
file is requested, it only includes output from the second (final) pass of
the HD6303 Assembler.

Note that the files in this package are configured to reside in the same
directory.  However you may wish to create separate directories for the
utilities and your ASM files.  If you do so, then the environment variable
INCLUDE should be set to point to the directory containing the HITACHI.MAC
and HD6303.MAC files (because the INCLUDE variable supplies the path for
files whose names are enclosed in < and > brackets). Edit the ASM.BAT and
ASMLIST.BAT files if the value of INCLUDE needs to be changed (at present
both files set INCLUDE to point to the current directory).

As an alternative to using the INCLUDE environment variable, you may specify
the full path to the file in the #include and/or #macros directives if
you replace the < and > brackets with double-quotes, e.g. change
        #include <hitachi.mac>
to      #include "c:\psion\include\hitachi.mac".

The file EXAMPLE.ASM shows the format of an ASM file and describes the
different number formats and some of the assembler directives supported.
Section 7 below provides further information on the sample files in this
package.

Note that the HD6303 instructions and pseudo ops in the ASM source files can
be in either uppercase or lowercase. For example, "ASL A" and "asl a" are
equivalent, as are "REPT 255 X 3 TIMES" and "rept 255 x 3 times".

By default relative branch instructions may use labels (e.g. BCS ERROR),
signed numeric offsets (e.g. BNE -9 and BEQ +100) and unsigned positive
numeric offsets (e.g. BCC 127).

However, it is possible to restrict relative branch instructions to use
only labels and signed numeric offsets by defining the variable SIGNEDONLY
in each ASM source file as required, or in the HITACHI.MAC file in order to
affect every ASM source file.

If required, relative branch instructions can even be restricted to use
only labels by defining the variable LABELSONLY in each ASM source file as
required, or in the HITACHI.MAC file in order to affect every ASM file.

+------------------------+
| 5. Using the Assembler |
+------------------------+

There are three essential files in the HD6303 Assembler package: HITACHI.MAC
(the file referenced by the INCLUDE directive in every HD6303 program),
HD6303.MAC (which defines the HD6303 instruction set) and PCMAC.EXE (the
universal macro assembler).

The file SERVICES.MAC is not essential but it makes it much easier to
interface with the Psion Organiser Operating System by providing a new macro
and a long list of Operating System Service names. The two batch files
ASM.BAT and ASMLIST.BAT are not essential, but serve to simplify the user
interface to the assembler.

Once the source file has been prepared, the assembler can be run by using the
command "ASM" or, if a listing file is required, the command "ASMLIST".

For example, to assemble the file EXAMPLE.ASM which is provided in this
package, use the command

                ASM EXAMPLE

or, if a listing is required, use the command

                ASMLIST EXAMPLE

The screen should show a report like this:

        Versoft macro assembler.
        V 1.0
        Pass1
        Error    : 0
        Warning  : 0
        Start of the code : 28672
        End   of the code : 28818
        Pass2
        Error    : 0
        Warning  : 0

        Output listing is in "EXAMPLE.prn"

(NB: The last line only appears if the command "ASMLIST EXAMPLE" was used).

The assembler will create the binary file EXAMPLE.TSK and, if the ASMLIST
command was used, the ASCII file EXAMPLE.PRN will also be created.

The next section explains how to convert a binary "TSK" file into an ASCII
"HEX" file.

+----------------------------+
| 6. Using the hex convertor |
+----------------------------+

The CONVERT.BAT file is a simple front end to the hex convertor (TSK2HEX)
which takes a single parameter (a filename without an extension) and
generates a file with the extension ".HEX".

To convert the binary EXAMPLE.TSK file into an ASCII HEX file, run the
command
                CONVERT EXAMPLE

The screen should show a report similar to this:

        TSK2HEX

        Processing complete. Output is in "EXAMPLE.hex".

To examine this file, use the command "TYPE EXAMPLE.HEX" to produce a report
like this:

        3900000045202020202080808000000000000000006F6620627F7F040914FF41
        327A01020501020304050648656C6C6F210648656C6C6F214572726F72206D65
        7373616765004572726F72206D6573736167650048656C6C6F2C20776F726C64
        210D0A000B507265737320FF206B65790B507265737320FF206B657912345678
        70017004700A0A05702A703870467054706400

If EXAMPLE.ASM was a real program, the contents of EXAMPLE.HEX could then
either be incorporated into an OPL program or processed by a machine code
loader program on the Psion.

The Assembler generates a binary file with the extension ".TSK" (the "task"
file). The batch file CONVERT.BAT uses the TSK2HEX utility to read this TSK
file and generate an ASCII file. Each byte in the TSK file is converted to a
pair of hexadecimal digits. By default TSK2HEX generates lines of 64
characters, representing 32 bytes but the number of bytes per line can be
changed to any value in the range 1 to 128 by means of a command-line switch.

If the number of bytes per line is set to 1 by means of the "-w1" command-line
switch, TSK2HEX will produce output files which are compatible with the MC
Loader program described in Bill Aitken's "Machine Code Programming on the
Psion Organiser" book.

TSK2HEX uses a default value of 32 in order to be compatible with my enhanced
version of Bill Aitken's MC Loader program (still under development!).

TSK2HEX has three different help screens: to see them use the following
commands: TSK2HEX, TSK2HEX -h and TSK2HEX -x

TSK2HEX returns an error code which can be examined in a batch file, for
example.  The "-q" command line switch can be used to run TSK2HEX in "quiet"
mode where most messages are disabled. The error codes are as follows:

        1   -  Help/Version displayed, all other command-line switches ignored
        2   -  Command line has extraneous text
        3   -  No input file was specified
        4   -  The -w parameter was out of range
        5   -  Unable to open the input file
        6   -  Output file already exists and -d was not specified
        7   -  Unable to open the output file
        8   -  Error whilst reading from the input file
        9   -  Error whilst writing to the output file

If no errors are detected and the output file has been created then TSK2HEX
returns error code 0 (i.e. success)

WARNING:
        Note that TSK2HEX is a simple-minded utility which assumes that the
        TSK file contains a single block of binary data.  Care should be
        exercised if it is used on multi-block TSK files.

        By "multi-block", I mean TSK files which contain more than
        one block of code; for example if the BOOT.ASM file used an ORG
        directive for the "UNBOOT" routine and another ORG directive for
        the "BOOT" routine then the BOOT.TSK file would be a multi-block one.

        In multi-block TSK files, the binary data may not represent a single
        contiguous block and so the HEX file produced by TSK2HEX must be
        processed accordingly.

+--------------------------+
| 7. Sample files provided |
+--------------------------+

EXAMPLE.ASM
        This is a meaningless program created to demonstrate some of the
        features of the assembler.  It shows the layout of an ASM file,
        describes the different types of numbers recognised and demonstrates
        the use of data storage directives.

EXAMPLE.PRN
        This is the "listing" file created by using the command "ASMLIST
        EXAMPLE". In it the HD6303 Assembler lists the EXAMPLE.ASM source
        program and shows all the machine code data generated and the
        addresses at which the data is stored.  This file can be printed out
        as a record of the program and the code generated by the assembler.

BOOT.ASM
        A tiny sample HD6303 source file which has two routines in it. This
        example uses some entries from the SERVICES.MAC file, which defines a
        new macro and some constants in order to simplify access to the Psion
        Organiser Operating System.

BOOT.PRN
        This "listing" file was created by using the command "ASMLIST BOOT".
        In it the HD6303 Assembler lists the BOOT.ASM source program and
        shows all the machine code data generated and the addresses at which
        the data is stored.  This file can be printed out as a record of the
        program and the code generated by the assembler.

MC6303.ASM
        This file demonstrates the complete set of HD6303 instructions
        supported by the HD6303 Assembler.  One example of each instruction
        is given, together with a very brief comment describing it.  This file
        is intended as a reference document, which is why the instructions
        are listed in alphabetic order.

        Some instructions have alternate forms, e.g. the assembler will
        accept either "ADD A #123" or "ADDA #123".  Note that the "%" prefix
        is accepted as an alternative to the "#" prefix for immediate data
        values. All of these alternative instruction formats are shown in
        MC6303.ASM.

        If the command "ASMLIST MC6303" is used, the assembler will generate
        a listing file, MC6303.PRN, showing the machine code generated for
        each instruction in order that you can confirm that the assembler has
        generated the correct codes.

+-----------------------------------+
| 8. Contact Information/Disclaimer |
+-----------------------------------+

No responsibility is accepted for any damage or data loss whatsoever due to
the use of the HD6303 Assembler and its associated utilities. This software
is provided "as is" without warranty of any kind.

Although I have tested the assembler, there are so many different ways of
constructing expressions that it is possible that it might fail to assemble a
particular program correctly so please take care when using it!  Remember
that mistakes in machine code programs can destroy all of your data in the
Psion so make sure you have saved vital data in datapacks (and remove the
datapacks to be really sure).

If you have already written some machine code programs, I recommend that you
use the ASMLIST command to assemble them with the HD6303 Assembler and then
compare your machine code against that generated by the assembler.  If they
agree then you have at least gained a formatted listing of your program (and
helped test my assembler).  If they do not agree then you can send me a bug
report!

I have found the Assembler and Hex Convertor useful and hope they can help
you. If you have any comments or suggestions for improvements (or even
corrections) regarding this package, please let me know.

Brian Smith, $Date: 1998/06/08 14:38:59 $

email: bds@sugelan.co.uk

(end of file)
