==============================================================================
        ######  #####   ##  ##
        ##  ##  ##  ##  ##  ##           ###    ###### ####### #######
        ##      ##  ##  ## ##             ##    ##     ##   ## ##   ##
        ######  ##  ##  ####    ######    ##    ###### ## # ## ## # ##
            ##  ##  ##  ##  ##            ##    ##  ## ## # ## ## # ##
        ##  ##  ##  ##  ##  ##            ##    ##  ## ##   ## ##   ##
        ######  #####   ##  ##          ######  ###### ####### #######

                                 RELEASE 3

       Software Development Kit for the General Instruments CP-1600 CPU
------------------------------------------------------------------------------
                     Q U I C K S T A R T    G U I D E
==============================================================================


Welcome to the QuickStart guide.  This is intended to be an introduction
to SDK-1600, illustrating what the SDK provides and how to use it.

----------------
 Directory Tree
----------------

 sdk1600
    |-- bin          Executable versions of all the SDK-1600 tools
    |-- doc          Documentation for SDK-1600 and the Intellivision
    |-- examples     Various programming examples
    `-- src          Source code for the SDK-1600 tools.

The parts you'll need the most are the 'bin' files (indirectly), the 'doc'
files (for reference), and the 'examples'.  You probably won't need the
'ecscable' or 'src' for much early on.  (That is, unless you're running
under Linux or UNIX and you need to build the tools.)

----------------
 Tools Overview
----------------

SDK-1600 provides a broad array of tools for Intellivision development
purposes.  The most important tool you will likely be using is the
assembler, as1600.  The other tools may or may not come into play,
depending on what you're doing.

The SDK-1600 tools can be divided into a few groups:

 -- Code Generation:  Tools for generating ROMs and binary images.

        as1600       Assembler for the CP-1600 (the Intellivision's CPU)
        rom2bin      Converts Intellicart .ROM to BIN+CFG
        bin2rom      Converts BIN+CFG to Intellicart .ROM

 -- Inspection and Hacking:  Tools for disassembling existing code
    and for pulling ROM images apart and putting them back together 
    again.

        dasm1600     Disassembler for CP-1600 code (reassemblable output)
        dasm1600o    Alternate version of CP-1600 disassembler
        dasm0256     Disassembler for SP-0256 speech data

        tohex        Generates an editable hex-dump of a binary file
        tobit        Generates an editable bit-dump of a binary file
        tobit_f      Like tobit, except slightly different output format
        tobit_r      Like tobit, only bits are in opposite order in each byte

        fromhex      Regenerates binary file from hex-dump 
        frombit      Regenerates binary file from bit-dump (forward order)
        frombit_r    Regenerates binary file from bit-dump (reverse order)
  
 -- Physical Interface Utilities:  Tools for interfacing to various hardware,
    such as INTV2PC, cart readers, and the ECScable.

        ec_dump      ECScable-based ROM dumper (for EXEC, GROM, ECS roms)
        ec_load      ECScable-based game loader
        ec_test      ECScable confidence test
        ec_watch     ECScable-based variable watcher

        test_cart    Test Moeller/Nudds cart-reader via built-in loopback
        ivplay       Play voice data on the Intellivoice via cart-reader
        ivreset      Reset the Intellivoice atttached to the cart-reader

        test_hcif    Test INTV2PC Hand Controller Interface

 -- Odds and Ends:  Tools that don't really fit anywhere else.

        gms2rom      Convert INTVPC .GMS game-save file to .ROM format
        gromfix      Fix the GROM file generated by minigrom.asm



---------------------
 Assembling Programs
---------------------

>>  NOTE:  The following assumes that the SDK has been set up as described
>>         under "Setup" in the README file in this directory.  If you
>>         have not yet set up the SDK so that the SDK's tools are in
>>         your path, please do so now.


As noted above, the tool you'll likely be using the most is the assembler.
Using it is very straightforward.  The assember takes a small number
of flags and produces an executable.  The basic commandline is as follows:

    as1600 [-o output.rom] [-l listing.lst] [-s symbols.sym] source.asm

The -o flag specifies the output executable file.  The executable file
is the file you will eventually download to the Intellivision, or load
within the emulator.  The assembler supports two different executable
formats.  More on this in a second.

The -l flag specifies a listing file.  The listing file contains a copy
of your original source code alongside a textual description of what
the assembler produced.  That is, each line contains the address of the
instructions and the numerical values the instrucitons assembled to.
This is useful for seeing where and how your code assembled in the memory 
map.  This becomes most useful when you're in the debugger, single
stepping through code.

The -s flag specifies a symbol file.  The symbol file contains a listing
of all the symbols in your program and their values.  This can be useful
if you have a debugger that knows how to read the file.  At the time
of this writing (April 2002), there are no such debuggers available for
the Intellivision.  *sigh*  Typically, this flag is omitted as a result.

The final argument is the name of your source file.  The assembler only
accepts a single source file.  If you have a large project, you may
wish to separate it into several source files, and have a top-level
source file "include" them all.  But let's not get ahead of ourselves.


--------------
 Hello World!
--------------

To see the assembler in action, let's assemble an example.  Change
directories to "examples/hello" (or "examples\hello" if you're a
Windows or DOS user).  In that directory, type the following:

    as1600 -o hello.bin -l hello.lst hello.asm

This should assemble te source file "hello.asm" and produce three
output files: 

    hello.bin    This is the executable file containing "Hello World"
    hello.cfg    This is a configuration file which accompanies the binary
    hello.lst    This a listing file showing how hello.asm assembled.

The assembler should report:

 ERROR SUMMARY - ERRORS DETECTED 0
               -  WARNINGS       0
 
This means everything went smoothly.  If you get an error message
such as "Bad command or file name", or "command not found", double-check
your setup.  (See the README file.)  If you get assembly errors,
soemthing else is wrong.  Contact Joe Zbiciak <im14u2c@primenet.com>
and let him know something strange is afoot.

Assuming everything assembled correctly, you should now be able to load
this into the emulator of your choice (provided it allows for arbitrary
programs in BIN format to be loaded).  Alternately, you could download
this example to an Intellivision with an Intellicart.


-----------------------------
 Introduction to ROM Formats
-----------------------------

The command in the Hello World example above produced an executable
in a format I call "BIN+CFG".  This format uses two files -- a raw
binary file and a textual configuraiton file -- to hold the ROM image
and information about its memory map.  This format is the native format
of INTVPC, the world's first complete Intellivision emulator.  A couple
of other emulators understand the BIN+CFG format as well.  It is also
the default format that the Intellicart GUI loader expects on Windows
and Macintosh.  (The Macintosh Intellicart GUI also supports the ROM
format described below.)

The assembler also supports a second format, which I refer to as the
Intellicart .ROM format, or simply ".ROM" for short.  This format
places the entire ROM image plus information on the memory map into a
single file.  The reason I call it Intellicart .ROM is that it in the
same format that the Intellicart itself expects for a cartridge image.
That is, it is the same as the byte sequence the Intellicart loader
produces for sending to the Intellicart.  This format is useful if you're
on a Unix platform (which lacks a GUI-based loader), since you can simply
"cat file.rom > serialport" to download a ROM image in this format.
Also, jzIntv and the Java version of Bliss support this format directly.

The assembler looks at the extension on the output file name to decide
which format to write.  For this example, if we had wanted a .ROM 
file, we would have written:

    as1600 -o hello.rom -l hello.lst hello.asm

This command will generate hello.rom instead of generating hello.bin and 
hello.cfg.


------------
 Handy Tips
------------

For many projects, you'll be invoking the same as1600 command-line 
over and over.  That makes it a primary candidate for scripting.
Another nice feature of scripting is that as your project gets more
complex, you can add the additional build steps to the script so 
you don't need to execute them manually.

Under DOS / Windows, you can use a batch file to accomplish this.
Under UNIX and Linux, you can use a shell script.  On either 
platform, if you have the Make utility installed, you can also use
a Makefile.  (Makefiles, however, are beyond the scope of this
QuickStart.) 

Under DOS and Windows, a batch file is simply a text file which contains
commands that you want executed.  It can include some simple control
flow in the form of "if [condition] goto [label]".  For example, the
following batch file will build the "Hello World" example in .ROM format,
and then generate .BIN and .CFG files as well.  If any errors occur, it'll
stop:


as1600 -o hello.rom -l hello.lst hello.asm
@if errorlevel 1 goto err
rom2bin hello.rom
@if errorlevel 1 goto err
@goto end
:err
echo BUILD ABORTED DUE TO ERRORS
:end


The 'if errorlevel' statements check for errors returned from the various
tools.  The lines starting with ":" are labels.  For more information
on DOS batch files, take a look at these online MS-DOS resources:

    http://www.maem.umr.edu/~batch/batchtoc.htm
    http://www3.sympatico.ca/rhwatson/dos7/links.html

(I did not author and I'm not associated with the authors of those pages.)


Under Linux and UNIX, you can use a shell-script to accomplish the same
thing.  The following shell script will build the "Hello World" example
in .ROM format, and then generate .BIN and .CFG files as well.  If any
errors occur, it'll stop:


#!/bin/sh

die () { echo "BUILD ABORTED DUE TO ERRORS"; exit 1; }

as1600 -o hello.rom -l hello.lst hello.asm  || die
rom2bin hello.rom                           || die


The "|| die" construct at the end captures errors and aborts.  For more
information on shell scripts, consult the documentation that accompanies
your shell.

--------------------------------------
 About the Examples and Library Files
--------------------------------------

Each of the examples is intended to be assembled within its own directory.
For example, we assembled "Hello World" above from within the "hello"
subdirectory.  

Most of these demos use the "INCLUDE" assembler directive to include 
various functions that are stored in the "library" directory.  They expect 
the library directory to be in the same location relative to the example 
program as it is in SDK-1600's default directory layout.

If you copy an example program to another directory (say, to adapt it 
into a program of your own), you may need to adjust the INCLUDE directives 
appropriately.  In addition to adjusting the INCLUDE directives, you might 
consider copying the required library files to the new directory, and/or 
setting up AS1600_PATH as described in "doc/utilities/as1600.txt".


----------------
 And that's it!
----------------

If there were much more info here, it wouldn't be a Quick Start, would it?
Now you're ready to start diving into the examples and so on.  

I'd recommend you look over the examples in the "examples" directory,
and read over the various documentation in the "doc" directory.  
You may find the document "Intro to CP-1600" in "doc/programming"
especially helpful if you're relatively new to assembly programming.

Best of luck!

--Joe

