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

                                  RELEASE 3

       Software Development Kit for the General Instruments CP-1600 CPU
==============================================================================

--------------
 Introduction
--------------

This is a very simple Software Development Kit for the General Instruments
CP-1600 family of CPUs, as well as the device they're most often found
in, the Mattel Intellivision.  This kit is an independently produced
product, and is in no way a product of General Instruments, Mattel
Electronics, Intellivision Inc, INTV Corp, or Intellivision Productions.

The aim of this Kit is to provide a Free (both as in 'gratis' and as in
'libre') set of tools for programming devices based around the CP-1600
family of 16-bit microprocessors.

The bulk of the code contained herein is licensed under the GNU
General Public License.  Please see the file "COPYING.txt" for details.
Large portions of the Frankenstein Assembler which is included are also
available in the Public Domain.  The modified version contained herein
is not, however.

----------
 Contents
----------

This simple kit contains the following pieces:

 -- Intro to CP-1600:  A short document describing the CP-1600 CPU
 -- A CP-1600 Assembler, with documentation
 -- A CP-1600 Disassembler, with documentation
 -- Miscellaneous other tools to aid exploration and development
 -- Several short programming examples and library functions
 -- A mini-Exec/GROM combo that will allow you to run the examples on 
    a Intellivision emulator.
 -- Documentation and source code for the ECScable, a peripheral
    that allows your PC to communicate with your Intellivision + ECS.
 -- Source code for everything

All programs are provided with Win32 and Linux executables, as well as 
source code for building on other platforms.

The CP-1600 Assembler provided in this kit is named AS1600, and is based
on the Public Domain 'Frankenstein' assembler that was originally written
by Mark Zenier.  The original code is Public Domain.  My modified version
is being released under the GNU General Public License.

The CP-1600 Disassembler provided is Frank Palazzolo's DASM1600.
Two flavors of DASM1600 are provided -- one which provides a standard
disassembly, and one which provides a disassembly which can be used for
later reassembly.  Frank's disassembler is being released under the GNU
General Public License as well.

The coding examples that I've included are intended to run on a
particularly popular CP-1600 based platform which General Instruments
billed as the GIMINI-8900.  You may know it as the Intellivision.
These programs may be run on directly on the Intellivision using an
Intellicart, or in an emulator for that platform, such as either Carl
Mueller's INTVPC or Joe Zbiciak's jzIntv.

The following utilities are available in the 'bin' directory:

 -- 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.

        show_grom    Generates an ASCII or HTML dump of GROM.BIN's contents
        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


-------
 Setup
-------

The SDK provides a set of command-line oriented tools in the "bin"
directory.  To access these tools, you will need to place this directory
in your execution path, or copy these files to a directory that is
already in your path.

WINDOWS 9x AND DOS:

Windows 9x and DOS users can add this directory to their path by editing
their C:\AUTOEXEC.BAT file and rebooting.  To add SDK-1600 to your path
in this manner, add the following line to the end of C:\AUTOEXEC.BAT.

    PATH=%PATH%;C:\SDK1600\BIN

This assumes SDK1600 is installed in C:\SDK1600.  If you have unpacked
it somewhere else, then replace C:\SDK1600 with the full path to where
SDK1600 is installed.  For instance, if you installed SDK-1600 in the
directory D:\INTV\SDK1600, you would instead write:

    PATH=%PATH%;D:\INTV\SDK1600\BIN

After rebooting, you should be able to access the SDK-1600 programs
directly.  To test this, try typing "as1600" alone and pressing enter.
If you see "as1600: no input files", you're all set.  If you see
"Bad command or file name" or a similar error, then something is wrong.  

If you receive the "Bad command or file name" error, the problem
may be that your PATH is too long.  In this case, you must either
edit your AUTOEXEC.BAT to shorten your PATH, or instead copy the SDK1600
executables to another directory in your path.  Since the details of
this operation may vary greatly by machine, I cannot offer reasonable
directions on how to do this.

An alternative is to copy the tools you need into the directory where
your source files are located.  This is considered by some to be
suboptimal, but it does not require any modification to the PATH.
Another alternative is to always specify the full path when invoking
the tools.  This works as well, and may be acceptible when calling
the tools from scripts.


WINDOWS ME, WINDOWS XP, WINDOWS NT, WINDOWS 2000.

I have not used the SDK with any of these three Windows variants, so I
cannot tell you if the directions above are correct for these platforms.
The above instructions will probably work for Windows ME and maybe for
Windows XP.  They will most likely NOT work for Windows NT.  

I have heard reports that the SDK-1600 tools do work under Windows XP
and Windows NT command-line environments.  I do not, however, know
how to configure the PATH under these Windows variants.

If someone is willing to volunteer to share their experiences using
SDK-1600 with one or more of these Windows variations, please let me know.
Thanks!


LINUX AND UNIX

The first step for Linux and UNIX users is to build the tools.  (Actually,
SDK-1600 provides prebuilt Linux binaries.  Therefore, many, if not most, 
Linux users may be able to skip building SDK-1600.)  Please see the 
README.txt file under the 'src' directory for details on how to build the 
tools.  The build process will place a set of executables in the "bin/" 
directory for you to use.  Once the tools are built, you may proceed with 
the next step below.

The easiest way to set up SDK-1600 for a single user is to add the
directory containing SDK-1600 to that user's PATH variable.  How this
is accomplished depends on the user's login shell.

In the following examples, replace "/path/to/sdk1600" with the full
path to where SDK-1600 is installed.

For Bourne shell (/bin/sh) users, edit the file "$HOME/.profile" and add
the following line near the top of this file.  Do NOT add it as the very
first line.

    PATH=$PATH:/path/to/sdk1600; export PATH
    
For Bourne-again shell (bash) users, edit the file "$HOME/.bash_profile",
and add the following line near the top of this file.  Do NOT add it as
the very first line.

    PATH=$PATH:/path/to/sdk1600; export PATH

For C Shell (csh) and TENEX C Shell (tcsh) users, edit the file
"$HOME/.login" and add the following line near the top of this file.
Do NOT add it as the very first line.

    set $path = ( $path /path/to/sdk1600 );

Users of other shells will need to consult their shell's documentation.

In all cases, you will not see the updates to PATH until you next log
in, unless you force the shell to re-interpret its login scripts.  Consult
the documentation for your shell of choice for more details.



-----------------
 Getting Started
-----------------

I know you're probably excited to get started with the SDK.  See the
file "QuickStart.txt" for more information on getting started with
SDK-1600.

------------------
 Online Resources
------------------

There are a number of online resources which cover Intellivision and
related topics.  Below are some useful links, in no particular order.
Note:  Do NOT contact any of the emulator authors or other sources of
technical information asking for ROMs.  Your request will be promptly
filed in the bitbucket.

EMULATORS
 -- BlissJ, BlissJX, and Bliss32: http://bliss.retrogams.com/   
 -- IntvWIN and IntvDOS:          http://pcae.vg-network.com/intv/intvdos.html
 -- Nostalgia:                    http://www.gotmaille.com/nostalgia/
 -- MESS:                         <link not available yet>
 -- INTVPC:                       <on Intellivision Lives! v1.0 only>
 -- Intellivision Lives! and 
    Intellivision Rocks!:         http://www.intellivisionlives.com/

 
TECHNICAL INFORMATION
 -- The jzIntv website:           http://www.primenet.com/~im14u2c/intv/tech
    Contains some nitty-gritty tech info, but far from complete.

 -- Frank Palazollo's DSPLIB:     http://www.dsplib.com/
    Has PDF files with scans of spec sheets for various Inty chips.

 -- The 4-Tris source code:       http://www.primenet.com/~im14u2c/intv/4-tris/
    A complete, working game--useful as a reference.

MAILING LIST
 -- The INTVPROG list on Yahoo! Groups.  The message history on the
    group has lots of gorey detail.  Sign up here:

        http://groups.yahoo.com/group/intvprog/

----------------
 Special Thanks 
----------------

I'd like to extend a special thanks to my beta testers for this release.
In alphabetical order:  Mike Hayes, Ryan Kinnen, and Joanna Kurki.  All
three have provided tons of valuable feedback, suggestions and ideas as 
I've added documentation, demos and tools.  They've helped make SDK-1600
Release 3 be a solid, comprehensive release.  Thanks!


---------------
 About/Credits
---------------

The SDK-1600 Project is primarly the work of Joe Zbiciak, although it
could not have been possible without the assistance of a large number
of other people.  At this point, I'd like to thank the following 
people for their direct or indirect support:

 -- Frank Palazzolo, for providing technical documentation and the
    DASM1600 disassembler.

 -- Carl Mueller, Jr., for blessing the world with its first full 
    Intellivision emulator, and along with that alot of very, very 
    useful documentation.

 -- William Moeller, for taking Carl's notes and packaging them for
    the masses.  Also, for his boundless enthusiasm for seeing
    the Intellivision platform live on.

 -- Mark Zenier, for placing his excellent Frankenstein Assembler into
    the Public Domain many, many moons ago.

--------------
 Contact Info
--------------

Joe Zbiciak can be reached via email here:  im14u2c@primenet.com

