Atarimax "Maxflash" Flash MultiCarts

Preliminary Documentation, 07/10/2003

©2003 Steven J Tucker

Important Notice!

The software described below has been superceded by the new Maxflash Studio software application.

This software is still supported for advanced users, but all new users should try the Maxflash Studio suite located here before attempting to use these programs and scripts.

Chapter 4: Installing the MaxFlash software.

The current MaxFlash software package consists of a number of Perl scripts and 6502 assembler files.

The MaxFlash utility maxflash.pl acts as a custom make/build utility for creating custom multicart/disk-cart images for use with your flash cartridge.

To use the MaxFlash software you must install both a working Perl interpreter and the TASM Cross Assembler.

It is recommended your software versions be at least Perl 5.x.x and TASM 3.0.1.

Step 1: Installing Perl

If you already have a working Perl 5 installation, skip ahead to step 3.

Installing Perl on Windows

Perl is a free, powerful scripting language available under the GNU public license. There are many ways to obtain and install it.

By far the easiest way to get Perl running on Windows is to download and install the Perl binary package from ActiveState, a company offering Perl tools and support.

The Perl download is free software, you don't need any of the additional non-free tools to use it.

Go to the ActivePerl download page and click the red "Download" icon on the left. Choose the .msi package for a fully automatic installation using the Windows Installer.

Installing Perl on Linux

All popular linux distributions will either come with Perl already installed, or will have an option to install it.

There are so many different GNU/Linux distributions that instructions for installing Perl on Linux is beyond the scope of this document.

Visit perl.com for more information on installing Perl.

Step 2: Testing the Perl interpreter.

To test that your Perl interpreter is installed and working correctly, open a command prompt window or terminal session and type the command 'perl -V'.

If your perl interpreter is install and working you should se output similar to this:

C:\>perl -v

This is perl, v5.8.0 built for cygwin-multi-64int

Copyright 1987-2002, Larry Wall

Perl may be copied only under the terms of either the Artistic License or the
GNU General Public License, which may be found in the Perl 5 source kit.

Complete documentation for Perl, including FAQ lists, should be found on
this system using `man perl' or `perldoc perl'.  If you have access to the
Internet, point your browser at http://www.perl.com/, the Perl Home Page.

If you receive any error messages go back and retry the installation. On Windows check that the path to the perl interpreter (perl.exe) is included in your Windows PATH variable.

Step 3: Installing TASM

Note: If you already have a working TASM 3.X.X installation, skip ahead to step 5.

TASM is a table-driven cross-assembler that the MaxFlash utility will use to compile the source code included in the MaxFlash software package each time it creates a new cartridge image for you.

TASM is available as shareware for DOS/Windows.

Click here to download the current version of TASM as a ZIP archive.

Once you have download the TASM archive, unzip this file to a new directory on your hard disk. This software does not include its own installer.

Write down the absolute drive/path you installed TASM at, for example, 'C:\TASM' or '/home/user/tasm', you will need it later to configure the MaxFlash build utility.

Step 4: Testing TASM

Open a command prompt or terminal window and change to the directory where TASM is installed.

There type the command 'tasm' with no parameters. If TASM is installed and working you should see a message similar to this:

E:\tasm32>tasm
TASM Assembler.           Version 3.2 September, 2001.
 Copyright (C) 2001 Squak Valley Software
tasm: No files specified.
tasm -[nn] [-options] src_file [obj_file [lst_file [exp_file [sym_file]]]]
Option Flags defined as follows:
  -[nn]    Table (48=8048 65=6502 51=8051 85=8085 80=z80)
                 (68=6800 05=6805 70=TMS7000      96=8096)
                 (3210=TMS32010 3225=TMS32025)
  -t[tab]    Table (alternate form of above)
  -a         Assembly control (strict error checking)
  -b         Produce object in binary format
  -c         Object file written as a contigous block
  -d[macro]  Define macro
  -e         Show source lines with macros expanded
  -f[xx]     Fill entire memory space with 'xx' (hex)
  -g[x]      Obj format (0=Intel,1=MOSTech,2=Motorola,3=bin,4=IntelWord)
  -h         Produce hex table of the assembled code
  -i         Ignore case in labels
  -l[al]     Produce a label table in the listing[l=long,a=all]
  -m         Produce object in MOS Technology format
  -o[xx]     Define number of bytes per obj record = [xx]
  -p[lines]  Page the listing file
  -q         Quiet, disable the listing file
  -s         Write a symbol table file
  -x[xx]     Enable extended instruction set (if any)

E:\tasm32>

If you receive any error messages check your installation and repeat.

Step 5: Installing the MaxFlash software package.

The entire MaxFlash software package, with the temporary exception of one file, is distributed as free software under the version 2 of the GNU Public License.

A copy of the GNU Public License is included with this software and may also be viewed at the gnu.org home page.

The file 'flash.com' included in the MaxFlash download is licensed seperately for non-commercial use until such a time as the source is released. If you wish to redistribute this package under the terms of the GPL, you must remove the flash.com utility.

Click here to download the maxflash.zip file, which contains the current MaxFlash utility and source code.

Unzip this file to a directory of your choice. After installation you should have the following files in the installation directory:

07/10/2003  03:55 PM    [DIR]          flash
05/17/2003  02:31 PM    [DIR]          osb
07/10/2003  03:30 PM            26,107 exepmenu.a65
07/10/2003  03:30 PM             7,158 exeunpak.a65
07/10/2003  03:14 PM            19,966 maxdisk.a65
07/10/2003  03:14 PM             6,236 mempack.a65
07/10/2003  03:14 PM             7,562 softdisk.a65
07/14/2003  03:04 PM            37,650 maxflash.pl
07/10/2003  07:25 PM               836 maxflash.cfg
06/29/2003  04:39 PM            18,349 license.txt

File sizes and dates will vary.

Step 6: Configuring the MaxFlash software.

Unlike Perl, TASM does not put itself in the system PATH, so you must tell the MaxFlash utility where it can locate this program.

In the directory you installed the MaxFlash software in, there is a file called maxflash.cfg. Open maxflash.cfg in any text editor.

This is what the file should look like.

##
## MAXFLASH TASM CONFIGURATION FILE
## Names and values in this file must be seperated by a colon and must not span more than one line.
## 
 
##
## Define the location of the TASM assembler (version 3.2 recommended) here.
##
TASM LOCATION       : E:\tasm32\tasm.exe
TASMTABS DIRECTORY  : E:\tasm32\
 
##
## Changing this will break things.
##
TASM OPTIONS        : -65 -b -f00
 
##
## If your using a version of TASM that returns useless exit codes, set this to ON to ignore them.
##
IGNORE EXIT CODE    : off

Change the value on the line TASM LOCATION to reflect the absolute path to the TASM assembler, TASM.EXE, on your system.

Change the value on the line TASMTABS DIRECTORY to reflect the absolute path to the TASM table files. These files are installed in the same directory as TASM by default, but can be moved.

On Windows, if you are using cygwin Perl instead of ActiveState Perl, you may need to remove the .exe file extension from the tasm.exe filename to get TASM working. Normally this is not required.

Step 7: Testing the MaxFlash utilities.

Now that all the software is installed, we can test your build setup.

To check your work while configuring TASM, execute the maxflash.pl Perl script using the command perl maxflash.pl at the command prompt, in the MaxFlash software directory.

This will cause the Perl interpreter to execute the maxflash.pl script. If you configured the script with the correct location of TASM you should see the list of program options print out.

If you have not configured the location of TASM correctly, the script will instruct you as to which location needs to be corrected.

If everything is installed correctly, you should see a list of options the script accepts similar to that below:

MAXFLASH Multicart Build/Utility Script - c2003 Steven J Tucker
Information and updates at http://www.atarimax.com/

usage: perl maxflash.pl [switches] [hacks] [disk.atr] [cartridge.bin] [dump.a8s]


switches: -4MB        (*) Create image for 4Mb cartridge. (default is 1Mb)
          -8MB        (*) Create image for 8Mb cartridge. (default is 1Mb)
          -ALTPTR     (E) Use alternate address for Atari EXE loader.
          -BASIC      (D) Enable BASIC. (For packing disks that use BASIC)
          -BATCH      (*) Never prompt for optional information.
          -BIN2ALL    (U) Make existing BIN file into CART/ATR images.
          -BIN2ATR    (U) Make existing BIN file into flash programming image.
          -BIN2CART   (U) Make existing BIN file into Atari800 CART image.
          -CART       (*) Write file with Atari800 cartridge header.
          -CHEESE     (E) Enable DLIs, sounds and colors in EXE menu.
          -CLEAN      (U) Remove intermediate files. (lst,bak,atr,com,bin,car)
          -COLORS     (*) Fill color registers while working. (debug)
          -DISKPACKER (K) Pack ATR image into cartridge using MAXFLASH driver.
          -EXEPACKER  (K) Create multi-cart image using directory of EXE files.
          -FASTKEYS   (E) Faster selection in EXE loader menu.
          -FIXSEG     (U) Combine with -SEGCHECK to try and fix an EXE file.
          -FLASHER    (*) Make bootable ATR image for programming MAXFLASH cart
          -HOLMES     (D) Try to follow archive directives (-bas, -osb, etc).
          -LOFLICKER  (D) Reduce flickering in some modes.
          -LOMEM      (D) Force HIMEM to A000 after installation.
          -MEMPACKER  (K) Pack Atari800 A8S image into cartridge.
          -NOBIN      (*) Delete raw binary after processing.
          -NODISK     (D) Create image with blank disk area.
          -NOEXE      (E) Erase EXE files after packing with -EXEPACKER option.
          -OSB        (*) Build automatic OS-B translator into cartridge.
          -PALHACK    (D) Force OS to detect GITA as PAL.
          -RECURSIVE  (*) Process sub-directories in directory mode.
          -REINIT     (E) Force EXE loader to enter RUN vector via warmstart
          -SEGCHECK   (U) Display segment information in an Atari EXE file.
          -TRANSLATOR (D) Replace OS but not not install any drivers.
          -TRIGGERS   (D) Enable sector triggers.
          -UNDEROS    (M) Unpack memory under OS.
          -VERBOSE    (*) Display useless information.

If you see the message shown above, congratulations, you have successfully installed Perl, TASM and the MaxFlash software package.

If you receive an error that Perl or TASM were not found, go back and check your installation at the previous steps.