Creating RPK cartridges

The TI-99/4A emulation offers two kinds of cartridge formats:

• the common ZIP format for ROM packages in MAME
• the RPK format

The first format is used throughout MAME for bundling ROM dumps that belong to some collection, for example, all ROMs for a computer system. In the same way, all ROMs of a cartridge are stored in a single ZIP file, which must be added to the software list, a XML file in the hash subdirectory. For the TI, this would be the file ti99_cart.xml.

The second format was the result of an earlier attempt to find a format for cartridges. Later, the ZIP format became the recommended format for cartridges, but it has a shortcoming: It depends on an update of the mentioned XML file. The RPK format, on the other hand, allows the user to set up a self-contained cartridge package that can be used right away. For this reason, the RPK format was kept in MAME.

Basic concept of a MAME cartridge

A cartridge consists of a printed circuit board (PCB) and some memory circuits mounted on it. A few cartridges may also have additional features like switches, but these are currently not emulated.

In order to emulate the cartridge, we need the contents of the memory circuits and the type of the PCB. Although the PCB may theoretically contain any kind of circuitry, there are only about a dozen different types. All these PCBs are already emulated inside MAME, so we just need to declare which one to choose by name. We have to point out that if a PCB has a different design, this cannot be used in MAME until it is implemented and added to the emulation.

The contents of the memory circuits must be provided by up to three dump files:

• GROM dump: This spans the whole cartridge space of the GROMs. The cartridge GROMs start at address >6000 and reach up to >FFFF (40K). The dump file length should be a multiple of 8K.
• ROM1 dump: This dump contains the whole contents of the cartridge ROM space (unless a ROM2 dump is used), with all banks arranged in ascending order. The ROM1 dump may have any length up to 32 MiB. The selection of banks depends on the PCB type. 
• ROM2 dump: Some cartridges (notably Extended Basic) store a second ROM bank in this dump. Only a few PCB types support this dump. If there is a ROM2 dump, the ROM1 dump is limited to 8 KiB.

The MAME cartridge emulation pretends to have three sockets on the PCB where the contents of these dumps are read from: grom_socket, rom_socket, and rom2_socket.

Creating a RPK cartridge

There are some points to follow, but this is not really difficult.

1. You have to collect all dumps that shall be part of the cartridge. These are the dumps of memory in ROM space and in GROM space. Also, you need to check whether the cartridge offers RAM space or NVRAM space (which is saved on shutting down).
2. You have to determine the type of the cartridge. The type is relevant for the function of the cartridge board where the ROMs are located.
3. Now you have to set up the defining XML file called layout.xml. It must be part of the cartridge package. This is an example for a "gromemu" type:

<?xml version="1.0" encoding="utf-8"?>
<romset version="1.0">
  <resources>
     <rom id="gromimage" file="TETRISg.bin"/>
  </resources>
  <configuration>
      <pcb type="gromemu">
         <socket id="grom_socket" uses="gromimage"/>
      </pcb>
  </configuration>
</romset>

The most important parts are marked up in magenta. The PCB type is gromemu, and the ROM dump file is called TETRISg.bin. It is referenced by the "gromimage" tag, and the "socket" element declares it to be a GROM image by using the ID "grom_socket". You can use any other tag for "gromimage", and the file may also have any name.

Note that there is no format for the dump file name; the "g.bin" at the end of the file name has no special meaning for MAME. This is different to other emulators where the file name also determines its type; in the RPK format, the meaning of the dump file is determined by the socket element.

4. Create a ZIP file from the dump files and the layout.xml. All these files must be part of the package.
5. Change the suffix of the ZIP file to "rpk".

PCB types

The following table shows the possible values for the PCB type in the layout.xml definition. In many cases of recent cartridges, the gromemu type is an appropriate choice.