Blue RAM Utility 3
by Perkins Engineering

Instructions for Cartridge and Final Release Cassette Version

 
     Your 8k Blue Ram utility program contains a variety of routines which are most useful in writing or altering machine language programs such as game cartridges.  Machine Language programs run much faster than programs written in BASIC, allowing smooth animation.  To gain the most from this tape, some familiarity with Machine Language in hexadecimal notation is necessary.  The following books will be helpful in becoming familiar with Z80 programming and peculiarities of your Astrocade:

     Z80 INSTRUCTION HANDBOOK OR Z80 SOFTWARE GOURMET GUIDE & COOKBOOK by Nat Wadsworth (SCELBI Publications).
     PROGRAMMING THE Z80 by Rodney Zaks can be found at most Radio Shack stores.
     Z80/Bally Hardware/Software Manual and various program disassembly listings are available through the "Arcadian."

     Operation of the Blue Ram Utility is controlled by 4 letter words known as commands.  Commands may be entered using the keyboard or keypad whenever the ">" symbol is displayed along with an "Enter Command" prompt.  It is only necessary to enter enough letters to uniquely identify the command.  Upon recognizing the command, the utility will complete the spelling and prompt for additional parameters as necessary to quantify and qualify the command.
     As each parameter is solicited, a default value is provided.  Any or all of the default value characters may be changed by simply writing over them.
Pressing [Return(GO)] or [TAB] accepts the parameter as displayed whether or not it has been modified.  The [SPACE] or A key may be used to skip over (not change) a parameter character.  Press [Delete(ERASE)] or [BACKSPACE] to back up to a prior character or a previous parameter, or to abort the command.
     Most parameters are hexadecimal numbers representing byte addresses or block boundary addresses.  Block size is normally defined decimally in kilobytes (K), where K=1024 bytes, 2K=2048bytes, etc., up to a maximum of 32K.  Alternatively, pressing the E key will allow the entry of a block end address which is required for a block size of other than a kilobyte multiple.  Each parameter is described by its prompt.  Proper format is shown by the default.
     The Blue Ram Utility responds to the following commands:

COPY - Copies an Arcade cartridge as a block of data into the Blue Ram.  This is normally the first step in sequence for analyzing and/or modifying a game cartridge for experimental use.  Other commands in this sequence may include LIST, EDIT, SAVE, and TEST.  The COPY command is not intended as a vehicle for distribution of copyrighted games.

SAVE - Saves a block of data on tape. (Similar to :PRINT with size in bytes)

LOAD - Loads a data block from tape. (Similar to :INPUT)

VRFY - Verifies a data block on tape. (Similar to :List)

DIAG - Verifies the size of your Blue Ram and tests all memory components in the Blue Ram for proper operation.

TEST - Moves a Machine Language block to the 6K address space for operation as a cartridge with the range switch in the 2K position.  Execution of this command overlays the utility program, requiring a reload for further use.

DUMP - Makes a fresh copy of the Blue Ram Utility on tape.  For proper copy, this should be the first command after a fresh utility load, answering yes to the prompt for instructions.

UNPK - Changes an Astro-BASIC format block into a Blue Ram BASIC compatible format, saving the Astro screen image as a Blue Ram BASIC compatible "SNAP."  The Astro program is first loaded into the Blue Ram using the LOAD command.  The UNPK command transforms the Astro program area into a Blue Ram program area (0D08 Hex bytes long) and screen image (0DC4 Hex bytes long) located
1000 Hex bytes higher in memory.  Use SAVE to save these blocks on tape.  An example of UNPK follows:
     LOAD to 8000 (load Astro format tape)
     UNPK from 8000 (convert to BR format)
     SAVE from 8000 thru 8D07 (save BR program)
     SAVE from 9000 thru 9DC3 (save screen)
The resulting tape may then be loaded via Blue Ram BASIC (after RESET) using the statement :INPUT ;:INPUT %(!07000).  The UNPK command does not alter any of the original program statements to use the new Blue Ram BASIC features.  Use SHOW 0,8,0,%(!7000) to see the screen.

DASM - Disassembles a Machine Language program (Hex) to its Assembly Language equivalent.  The listing is presented on the screen (and printer if on-line) in individual pages.  By responding to the (ack) prompt with [delete], an end of DASM occurs.  By pressing any other key, another page is disassembled.

BURN - Burns a 2732/2764 EPROM with an optional Blue Ram EPROM burner.  There are additional instructions with it.  The tape switch must be set to save!  Each time the mount EPROM (ack) prompt is displayed there are 4 responses you may make. Pressing the [DELETE] key terminates the BURN command.  Pressing V verifies that the EPROM is erased.  Pressing C compares the EPROM against Memory for identification.  Pressing any other key starts the burn process.  

SEND - Sends a block of data over the telephone to another Blue Ram (via an optional modem interface and modem).

RECV - Receives a block of data sent over the telephone from another Blue Ram (via the option modem interface and modem).

These two commands transfer programs or other data between Blue Rams.  The first step is to call the other party.  Set your modem to originate frequency and full duplex mode.  The other party should use answer frequency and full duplex mode.  Communications are read when the Carrier Detect (CD) light is lit on your modems.  Once this happens set tape switch to save and execute the SEND and RECV commands.  The party receiving data must execute the RECV command prior to execution of the SEND command by the other party.

LIST - Lists a block of memory to the printer (via the BR printer interface) in both Hex and ASCII formats,

DISP - Allows the default display base (block begin) address to be changed.

BASE - Allows the internal memory base associated with the display base (also normally 8000) to be changed.  Values for DISP and BASE need not be the same (a pseudo-memory-mapping capability).

EDIT - Displays a block (of 208 bytes) and allows it to be edited anywhere on the screen.  [Return(GO)], [TAB], A, and [SPACE] move the cursor right. _ and [delete(ERASE)] move it left.  Use ^ to move the cursor up and ' to move it down (going below the bottom brings up another display line).  Use GOTO to locate a particular address on or off the display (see GOTO command).  Use PAGE to flip forward or backward one display page for editing convenience.  The > key may be used to exit the edit mode to allow entry of other commands.

GOTO - Locates a specified memory byte and allows editing of that or adjacent bytes.  If the specified byte isn't in the current display, a line containing that byte is added to the display.

PAGE - Displays the previous (Back) or next (Fwd) page of data on the screen.  A page must already be displayed.

FILL - Fills each byte of a block of data with a specified value.

MOVE - Moves a block of data to some other location in memory.

SWAP - Exchanges two blocks of data.

CALL - Calls a machine code program as a subroutine. The CALL command may be used to try a routine provided it will operate where it resides in memory.  Caution!!!  This utility occupies the Blue Ram from 6000 through 7FFF Hex.  Do not attempt to COPY, LOAD, UNPK, EDIT, FILL, MOVE, or SWAP into this
Area!  To do so could clobber both the utility and other programs in memory.

It is also important to note that the instructions load from 8000 through
9FFF Hex and will overlay anything in that area when they are requested.

A few final notes:

Once a game cartridge type program has been copied, edited, and saved, the tape may be loaded by AstroBASIC using the statement :INPUT %(24576) [GO]

To abort and command in progress, use the normal "Bomb Recovery" procedure for Blue Ram BASIC and then run the Utility again.


     Happy Programming!


-- Blue Ram instructions retyped by Adam Trionfo from printout sent by Michael White April 19, 2001