MESS cartridge handling

For the MESS emulation of the TI-99 computer family we have two different cartridge handlings.

The RPK files are cartridges which contain the memory dumps as files and another file (layout.xml) which informs the emulation which file belongs to which part of memory. This was designed mainly by me at times where the user had to install the dumps at the proper locations himself.

RPK cartridges have to be installed by giving the path name of the file. That is, you would have to specify /home/michael/mess/carts/editor_assembler.rpk, just like a disk image file.

The ZIP files are a more recent format (and have become the standard MAME/MESS cartridge format) which merely differ from the RPK files by not including the XML file, but only the dump files. The layout is defined inside MAME/MESS. The file name is also defined in that file, so the name of the cartridge zip file must exactly match the name in the internal file.

Both formats have their pros and cons.

RomPacK cartridge images (RPK)

Concept

In early MESS releases, cartridges consisted of separate ROM dumps, namely for ROM and GROM. This requires the user to mount both dumps in one cartridge slot each. The current MESS releases have a different cartridge management that simplifies handling and allows for some additional features:

• Cartridges which consist of multiple dumps (ROM, GROM) can now be stored in a single file.
• Mounting of memory dumps is defined inside the file and is performed automatically after inserting.
• Cartridges can contain RAM (volatile or NVRAM).

This package file (suffixed by .rpk) is essentially a ZIP file which contains all dumps and the information how to set up the cartridge in the emulation. You can use any unzip utility to unpack the RPK file, or to create it again. For instance, the Extended Basic RPK file contains these files:

extendedbasic.rpk:
   exbasicc.bin
   exbasicd.bin
   exbasicg.bin
   layout.xml

The "bin" files are ROM dumps. The layout.xml file defines the meaning of these dumps. For instance, it will declare that:

• exbasicc.bin is the ROM dump of the CPU address area >6000 to >7FFF (bank 0)
• exbasicd.bin is the ROM dump of the CPU address area >6000 to >7FFF (bank 1)
• exbasicg.bin is the GROM dump. All GROM contents are stored in a single file, where each GROM must be padded to a size of 8 KiB.

The layout file defines the role of the respective ROM dumps, and selects one of five predefined handlers in the MESS emulator. This is an extensible concept, which means that as soon as we discover new cartridge types, more handlers can be added to the emulation.

This is the layout file for the Extended Basic cartridge:

<?xml version="1.0" encoding="utf-8"?>
<romset version="1.0">
   <resources>
      <rom id="gromimage" file="exbasicg.bin"/>
      <rom id="romimage1" file="exbasicc.bin"/>
      <rom id="romimage2" file="exbasicd.bin"/>
   </resources>
   <configuration>
      <pcb type="paged">
         <socket id="rom_socket" uses="romimage1"/>
         <socket id="rom2_socket" uses="romimage2"/>
         <socket id="grom_socket" uses="gromimage"/>
      </pcb>
   </configuration>
</romset>

The file contents is an XML document following these conventions:

• The root element is <romset>
• Each dump is found in a <rom> element in the <resources> section.
• In the <configuration> section, the <pcb> element defines the cartridge type.
• Each socket refers to exactly one resource defined above.

Types

The available cartridge types for the TI emulation are defined as follows.

PCB Type	Meaning	Sockets	Used by
standard	Cartridges with 0 or 1 ROM and 0 or 1 GROM dump.	rom_socket, grom_socket	Most cartridges
paged	Cartridges with 2 ROMs and 0 or 1 GROM dump. Extended Basic is known to use this format.	rom_socket, rom2_socket, grom_socket	Extended Basic and many Atarisoft games
minimem	Cartridges with 1 ROM (4K) and 1 persistent RAM (4K) and 0 or 1 GROM dump.	rom_socket, grom_socket, ram_socket	Mini Memory
super	Cartridges with 1 RAM (32K) and 0 or 1 GROM dump.	grom_socket, ram_socket	SuperSpace II
mbx	Cartridges with 1 ROM, 1 RAM (1K, persistent) and 0 or 1 GROM dump.	rom_socket, grom_socket, ram_socket	MBX cartridges
paged379i	Cartridges with one ROM of 8K to 128K	rom_socket	New cartridges with LS379 selector
paged378	High-capacity cartridges with one ROM of up to 512 KiB. GROM space not supported yet.	rom_socket	New cartridges with LS378 selector
paged377	High-capacity cartridges with one ROM of up to 2 MiB	rom_socket	New cartridges with LS377 selector
pagedcru	Cartridges with one ROM of 8K to 64K	rom_socket	Cartridges with CRU banking (like DataBioTics)
gromemu	Paged cartridges with GROM emulation (full 8K)	grom_socket, rom_socket, rom2_socket	RXB and other cartridges with emulated GROMs

Examples

Editor/Assembler:

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

MiniMemory:

<?xml version="1.0" encoding="utf-8"?>
<romset>
   <resources>
      <rom id="gromimage" file="minimemg.bin"/>
      <rom id="romimage" file="minimemc.bin"/>
      <ram id="bufferedRam" type="persistent" file="minimem.nv" length="4096" />
   </resources>
   <configuration>
      <pcb type="minimem">
          <socket id="rom_socket" uses="romimage"/>
          <socket id="grom_socket" uses="gromimage"/>
          <socket id="ram_socket" uses="bufferedRam"/>
      </pcb>
   </configuration>
</romset>

SuperSpace II (do not mount the supcartc.bin which can be found on some servers; it is just the image of the empty ram):

<?xml version="1.0" encoding="utf-8"?>
<romset version="1.0">
   <resources>
      <rom id="gromdump" file="supcartg.bin"/>
      <ram id="ssram" file="superspace.nv" type="persistent" store="external" length="32768" />
   </resources>
   <configuration>
      <pcb type="super">
         <socket id="grom_socket" uses="gromdump"/>
         <socket id="ram_socket" uses="ssram"/>
      </pcb>
   </configuration>
</romset>

Sewermania (although there may be better examples; I don't know whether it makes use of the RAM at all):

<?xml version="1.0" encoding="utf-8"?>
<romset version="1.0">
   <resources>
      <rom id="gromimage" file="sewermaniag.bin"/>
      <ram id="mbxram" store="external" type="persistent" file="sewermania.nv" length="1024" />
   </resources>
   <configuration>
      <pcb type="mbx">
         <socket id="grom_socket" uses="gromimage"/>
         <socket id="ram_socket" uses="mbxram"/>
      </pcb>
   </configuration>
</romset>

Do it yourself

If the cartridge which you want to use is not available as an RPK, just do the following:

• Determine the type of the cartridge. This is something you have to figure out. If you find a *d.bin file, it is "paged"; the "minimem" type is only used by MiniMemory, and the "super" type belongs to SuperSpace II. That is, you need to check whether the cartridge is an MBX cartridge or not, and accordingly use the type "standard", "paged", or "mbx".
• Create a layout file as shown above. Use the rom dump file names in the references. Name the file "layout.xml".
• Create a ZIP archive file named mycartridge.rpk (or any other name). Put the ROM dumps and the XML file in the archive.

Usage notes

You can have several different instances of a cartridges. For example, you could have two different MiniMemories. Since the memory contents are stored in a file in the nvram folder and not in the RPK, you could modify the layout.xml of one cartridge and change the backup file name. That way, either cartridge has its own saved memory without overwriting one another. Also, you can easily change the cartridge contents, in particular when there are new releases. RXB is such a case. Also, not all RPK features have been included in the zip file handling, in particular we do not have NVRAM definitions, which are required by cartridges like MiniMemory or SuperSpace.

Note that names for RPKs are completely free to choose.

MAME cartridge format (ZIP)

Concept

The ZIP format is directly supported by the MAME core. In order to plug in a cartridge you have to specify the name of the cartridge, not the path name of the file.

Unlike the RPK format, the ZIP format only contains the ROM dumps (ROM or GROM), no XML files. Instead of layout.xml, the MAME emulator brings its own cartridge specification, called the software list or softlist. You can consider it to be a concatenation of all layout.xml contents.

Since this softlist is part of the emulator distribution, you cannot change it, especially not add any new cartridges. This must be done my the MAME maintainers. The background of this concept is that it shall be ensured that cartridge contents are preserved in an unchanged way (the archival concept of MAME). That is, the MAME core rejects cartridges that have modified contents, compared to the fingerprints inside the emulation.

Of course, this is only an advantage from the archival viewpoint; it does not consider "homebrew" software that is currently still being developed. Some discussion among the MAME developers mentioned a possible way to allow for a user-defined XML file (somewhat like the internal softlist, but editable and under user control). Other people voted for using the RPK system for this purpose. Until such a solution shows up, the RPK format will continue to be supported.

Types

The available cartridge types for the TI emulation with the ZIP format are defined as follows.

PCB Type	Meaning	Sockets	Used by
standard	Cartridges with 0 or 1 ROM and 0 or 1 GROM dump.	rom_socket, grom_socket	Most cartridges
paged	Cartridges with 2 ROMs and 0 or 1 GROM dump. Extended Basic is known to use this format.	rom_socket, rom2_socket, grom_socket	Extended Basic and many Atarisoft games
gromemu	Paged cartridges with GROM emulation (full 8K)	grom_socket, rom_socket, rom2_socket	RXB and other cartridges with emulated GROMs

As shown, many types are missing, in particular those which contain RAM (which is not yet supported in the ZIP system in MAME) and those that refer to new cartridges (mostly homebrew modules). For those you have to use the RPK system.

Usage notes

Using the ZIP system is more comfortable in many occasions; there is much less typing. To plug in the Editor/Assembler cartridge you just provide the name "editass", but you don't need to remember the file name of the RPK or where it is located. Moreover, the MAME core can look up the cartridge in case you do not know the exact name, and it tries some fuzzy search:

./ti99 -cart edit

"edit" approximately matches the following
supported software items (best match first):

* Software list "ti99_cart" (TI-99/4A cartridges) matches:
editass           Editor/Assembler
edasseb           Editor Assembler 1987 / Easy Debugger 2.1
speeched          Speech Editor
edupack           Edu-Pack
pertest           Peripheral Diagnostic Module
alienadd          Alien Addition
earlyrd           Early Reading
addseq            Milliken Math Sequences - Addition
perrecdi          Personal Record Keeping (German/Italian)
readadv           Reading Adventures
readflt           Reading Flight
readtrl           Reading Trail
centipd           Centipede
escape            Escape
blackhl           Black Hole
burgerbd          Burger Builder

FATALERROR: Device TI-99 cartridge load (edit) failed: File not found