FMGPUCCRBRR

FMan's General Purpose User-Configurable Custom ROM Builder for Retro Replay v1.20 (24-Sep-06)

This is a great utility program that will let you build your own ROM for the Retro Replay! You will have direct access to almost the entire 64K ROM space of one of the RR ROM banks and you can select up to eight programs to flash onto your RR to start any one of them from a boot menu. First, this is not a flash utility. This produces a ROM image that you'll then program using a tool made for that purpose.

FMGPUCCRBRR is a cross utility. Executables have been compiled for the Amiga and Windows, plus the full source code is provided for porting to other systems! The 6502 assembly source for the ROM code is also included. Just 1K is needed for the boot system. The menu screen is dynamically created from your input.

What FMGPUCCRBRR does, is it makes a Retro Replay ROM with a bootmenu containing programs of your choice. You may specify up to eight programs that will be collected into the ROM image that it creates! Then you'll be able to run any of them instantaneously from your Retro Replay cartridge.

Operation

This is a command-line based tool and the syntax to call it is:

ROMBuild <ROMFile> <File1> [<File2>] [...]

List all of the programs you want included in your ROM after the name of the ROM file to be created. You may specify just one or up to eight. Each program file must be in the CBM format having a loading address in front of the actual content of the file. When you press Return, the programs will be read in and checked out. Then starts the interactive part.

You are asked to enter a description for each program. Type up to 36 characters of any text that you want to appear in the bootmenu next to this program. Keep in mind that the text will be presented on a C64, so don't use non-C64 characters. Initially each program will have its filename as its description.

Don't worry if you make a mistake. You'll have a chance to fix it later. You can just press Return without typing anything to signal no change. This way you can simply go through the descriptions and perhaps make changes to selected ones, or in fact leave the filenames there as their description. After all files are described, you will be asked what you want to do next.

Press the key of your selection followed by Return. Press R to redo the descriptions. Keep in mind you can skip through the ones you don't want to change by just pressing Return. Alternatively, press C to cancel, if you don't want to go through with this ROM. In the other case, press B to build your ROM. Never mind about the "yes" and "no", they are there just to throw off people who didn't bother to read the docs. ;-)

Next you will be asked for a title to be displayed on top of the bootmenu. Again, the maximum length for this text is 36 characters. Just to give you a chance to correct any mistake you made, you'll be asked if this is really the title you want to go with. Answer either Y or K to proceed (you'll see why). Then you are asked which character set you are using.

Answer N if you want the regular one with capital letters and graphic symbols. However, if you want, you can have your bootmenu appear with uppercase and lowercase letters instead. They are correctly translated from what you have typed as the title and descriptions, but decide beforehand if this is what you want. Otherwise only use lowercase letters there, which will be shown as uppercase on C64.

Then, you will be able to set the color scheme in the bootmenu to your liking! Answer Yes if you'd like to do that and then enter the color number for the background, border and text color you'd like, each as it is asked. This is the hardware level color code, ranging from zero to 15. Confirmation for this is also asked. Regular color values are 6, 14, 14 in that order.

Next, you are asked if you want to keep these colors after exiting the bootmenu. If you answer No, you'll be offered a further choice of defining another set of colors to be used when loading the chosen program! Answer Yes and proceed as above to do so, or answer No to have the default colors as listed above restored upon leaving the boot menu.

That completes the configuration for your ROM and everything is now ready, so the ready-to-be-used ROM manufactured per your order is now written out. It will work in Vice for testing mainly, but flash it onto your real RR to reap the real gains from your newly made ROM. Your ROM obviously has no built-in functionality, but one of your chosen programs can easily be for example a fast loader.

Notes

All programs included in your ROM must be in BASIC, or ML programs that have a BASIC line to start them, and therefore they must load to $801. If you try to add a program that loads to another address, this will cause a fatal error and the process will not finish. The other causes for a fatal error are not being able to read in a specified program or either a single program or all of them together being too long.

The maximum length for a single program is 47658 bytes. Of course this would take up almost all of the ROM space alone. Note that even though the upper limit for the amount of programs that can be included is eight, you will normally have 3-5 programs in a single ROM image. Most programs are bigger than 8K, which is the average space available for the full suite of eight programs.

If the total length of the ROM image exceeds 64K (including the bootcode of course) it becomes an impossible mission. If this happens, choose shorter programs. However, if you only use a small part of the space and the ROM image would be smaller than 32 kilobytes, you will be asked if you'd like to create a 32K image instead. This only happens if the programs you have selected will fit into 32K.

Further changes to the behavior of the produced ROM are possible by reassembling the 6502 code. It is loaded by ROMBuild from a file called ROMBuild.cde, which must be located in the same directory with the executable file. The maximum length of this code file is 440 bytes. The rest of the 1K space reserved for booting is used for the menu screen and program data.

Files in the distribution:

ROMBuild - Amiga executable
ROMBuild.exe - Windows executable
ROMBuild.cde - precompiled 6502 code needed by the program
ROMBuild.html - this document
ROMBuild.c, ROMBuild.asm, reset.cde - source code files (and a precompiled code file) not needed to run the program

Version history

Changes for v1.10:

Rather than just overwriting the existing file by the name given as the destination, the program now asks if you want to overwrite it.
The destination file is created later, so you won't end up anymore with a 0-length file if you cancel.
Technical: since all files are read in straight away, there is actually no need to collect all the file pointers to a table, so a single reused file pointer is utilized now.
C64 code: cleaned up the source a bit, removed unused definitions and simplified some. Also, the NMI vector of the created ROM was bogus. Now it points to the reset routine. :-)
Additionally, the reset code (reset.cde) used by the 6502 source is now included in the distribution.

Changes for v1.20:

Prior to this version, pressing a key in the bootmenu that didn't have a program attached to it (ie. 4-8 with three programs), made it crash. ROMs created with this version will ignore those keys and be safer to use.
You can now specify another set of colors that will be in place when you leave the bootmenu. Alternatively, you can have the normal C64 colors restored after using your custom ones in the bootmenu.
Minor upgrades: if you used the uppercase/lowercase charset in the menu, it will now be restored to the default one when leaving the bootmenu.
Instead of having to specify the normal colors if you don't want to use custom ones, you can now simply opt out of color definition and have the default colors automatically in your bootmenu.