-   [Usage](#usage)
    -   [Dumping](#dumping)
    -   [OS File](#os-file)
    -   [Combining](#combining)
-   [Building rom8x](#building-rom8x)
    -   [PC application](#pc-application)
    -   [Calculator programs](#calculator-programs)
        -   [Manual assembly](#manual-assembly)
-   [Boilerplate](#boilerplate)
    -   [Contact](#contact)
    -   [Version History](#version-history)
    -   [Credits](#credits)
    -   [License](#license)

rom8x is a tool to create ROM files for TI-83+ series calculators which
can be used in emulators. It supports the following calculators.

-   TI-83+ (83PBE)
-   TI-83+ Silver Edition (83PSE)
-   TI-84+ (84PBE)
-   TI-84+ Silver Edition (84PSE)
-   TI-84+ Color Silver Edition (84CSE)

Usage
=====

The general process of building a ROM involves dumping some data from
your calculator, then combining that with a calculator OS upgrade file
to create a ROM.

Before beginning, determine which of the above models your calculator
is, and make note of the 5-character abbreviation that corresponds to
it. You will also need a linking program such as TiLP or TI-Connect and
an appropriate cable to transfer files between your calculator and
computer.

Dumping
-------

To dump the necessary data from your calculator, transfer the one or two
8xp files provided with rom8x that correspond to your calculator model
to the calculator. For example, if you have a TI-83+ use `G83PBE1.8xp`,
or if you have a TI-84+ Silver Edition use `G84PSE1.8xp` and
`G84PSE2.8xp`.

Run the program you just put on your calculator. They are assembly
programs, so be sure to use `Asm(`, like `Asm(G83PBE1`. It will create a
new AppVar in RAM with name corresponding to the program's name. For
example, the program `G83PBE1` creates AppVar `D83PBE1`. Transfer this
AppVar back to your computer and place it in the same directory as
rom8x.

If your calculator takes two programs (all 84+ models), repeat this
process for the second program.

OS File
-------

Now acquire an OS upgrade file for your device. These can be obtained
from [TI's web site](http://education.ti.com/)- find and download an OS
file for your calculator, and save the resultant 8xu or 8Cu (for the
84CSE) in the same directory as rom8x.

Combining
---------

The final step involves running rom8x to combine all the files into a
single ROM. Open a terminal (the exact procedure depends on your
operating system- on Windows, open a Command Prompt) and `cd` to the
directory containing your rom8x files.

Now invoke rom8x with your calculator's model, and the -u option
specifying the name of the OS file you obtained. For example, for a
83PBE:

    rom8x 83PBE -u ti83plus_1.19.8xu

Or for a 84CSE:

    rom8x 84CSE -u Ti84Plus_OS.8Cu

The program automatically looks for AppVar files with names
corresponding to the specified calculator model. If you have renamed
them, use the -1 and -2 options to specify their names as applicable.

    rom8x 84PBE -1 MyDump1.8xv -2 MyDump2.8xv -u 84pbe.8xu

If the process is successful, rom8x will create a new .rom file in your
working directory.

Building rom8x
==============

If you wish to build rom8x from source, there are two components that
must be built separately: the PC-side application that joins dumped ROM
pages with an OS file, and the calculator program that dumps the ROM
pages.

Familiarity with the concepts of compiling software is assumed
throughout this process. For most users, the pre-compiled binaries
provided with distribution packages should be sufficient.

PC application
--------------

Compiling the PC-side application is up to your discretion due to the
wide variety of platforms it should run on. For example, on a typical
Linux system:

    $ gcc -o rom8x rom8x.c

Or perhaps to cross-compile for a Windows target:

    $ i486-mingw32-gcc -o rom8x.exe rom8x.c

Calculator programs
-------------------

Similar to the PC application, assembling the calculator programs may
require some manual configuration. However, two automated build scripts
are provided for Windows and UNIX-like systems.

The build scripts assume you have [SPASM](https://wabbit.codeplex.com/)
on your PATH, which should work for both \*NIX and Windows users. They
will emit .8xp files for each supported calculator into
correspondingly-named directories.

Thus, the following on a \*NIX system generates 8xp files in five
subdirectories of the current directory:

    $ sh build.sh

And functionality is the same using the Windows batch processor:

    C:\>build.bat

### Manual assembly

If you can't or don't want to use the provided build scripts, manually
building binaries is a fairly straightforward process. You must define
`progName`, `pageNum` and `bootPage` appropriate for the target
calculator model. Refer to the build scripts to see what these
"approriate" values are-- they are specified on the assembler command
line as `-d<name>=<value>`.

For example, the configuration for a standard 83+ (83PBE) might be as
follows:

    #define progName "83PBE"
    #define pageNum "1"
    #define bootPage 1Fh

Boilerplate
===========

Contact
-------

Send questions, comments, etc to Peter Marheine: <peter@taricorp.net>.
The canonical source code for rom8x lives on
[Bitbucket](https://bitbucket.org/tari/rom8x/).

Version History
---------------

-   0.3.3 - 20151128
    -   Note in README that programs must be run with `Asm(`.
-   0.3.2 - 20140829
    -   Fix truncation of automatic filenames for 8xv files introduced
        in version 0.3.1.
-   0.3.1 - 20140319
    -   Prepend 'D' to assumed 8xv file names to match generated files
    -   Display a message on success for clarity
-   0.3 - 20131105
    -   Add support for 84CSE (84+ Color Silver Edition)
    -   Updated build scripts (no longer use the obsolete TASM
        and devpac8x)
    -   Revised documentation
    -   Fixed various inefficiencies and security issues.
-   0.2 - 20051209
    -   Bug fix in G8?P?E programs
    -   Completely recoded form scratch in C (v0.1 was in C++)
    -   New, more flexible argument input method
    -   Allows OS upgrade file integration into the ROM
    -   Source! (released under the terms of the GNU GPL license)
-   0.1 - 20050802
    -   First Public Release

Credits
-------

rom8x is the work of Andree Chea, now maintained by Peter Marheine.
Assistance was provided by the following individuals:

-   Benjamin Moody (a.k.a. FloppusMaximus) for TilEm, OS Tools, and his
    invaluable support. :)
-   Tim Singer and Romain LiƩvin (and those who helped them) for making
    the TI-XX Link Protocol Guide.
-   Various testers for testing this package.

License
-------

Copyright (C) 2013 Peter Marheine <peter@taricorp.net>\
Copyright (C) 2005 Andree Chea <andree@ss.ticalc.org>\
Portions copyright (C) 2003 Benjamin Moody <benjamin@ecg.mit.edu>

This program is free software; you can redistribute it and/or modify it
under the terms of the GNU General Public License as published by the
Free Software Foundation; either version 2 of the License, or (at your
option) any later version.

This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General
Public License for more details.

You should have received a copy of the GNU General Public License along
with this program; if not, write to the Free Software Foundation, Inc.,
51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.

ROM images are copyrighted by TI and should not be distributed. The
author of this program is not responsible for any issues that arise from
your (mis)use of this program.