Configuring Arcade Roms
The original support for arcade games is in the format of rom files that are stored in the bootrom folder, or in the path in the format a.pacman.rom. These are created by running the windows bat file or linux sh file that is in the release folder of each arcade game. You will need to provide a mame non-merged zip file that matches what the script is looking for.
Because some arcade boards can change games by just putting in new roms, it made sense to move the RBF files out of sight from the menu list, and browse the MRA files instead. These MRA files specify which RBF file to use, and which mame rom zip files to create on the fly into a rom to pass to the arcade core. They will create the old a.pacman.rom style rom on the fly from mame roms, either merged or non-merged.
Here is an example of where the files might go:
/_Arcade/<game name>.mra /_Arcade/cores/<game rbf>.rbf /_Arcade/mame/<mame rom>.zip /_Arcade/hbmame/<hbmame rom>.zip
There are other locations for these files based on search paths.
<misterromdescription> <name>Donkey Kong (US set 1)</name> <mratimestamp>201911270000</mratimestamp> <mameversion>0216</mameversion> <setname>dkong</setname> <year>1981</year> <manufacturer>Nintendo of America</manufacturer> <category>Maze / Monkeys</category> <category>Platform</category> <category>Platform / Mario Bros.</category> <rbf>DonkeyKong</rbf> <!-- dip switch information taken from "Pac-Man (Midway).mra"; for demonstration purposes only --> <switches default="FF,FF,C9"> <dip bits="15" name="Cabinet" ids="Cocktail,Upright"/> <dip bits="16,17" name="Coinage" ids="2c/1cr,1c/1cr,1c/2cr,Free Play" values="3,1,2,0"/> <dip bits="18,19" name="Lives" ids="1,2,3,5"/> <dip bits="20,21" name="Bonus Life After" ids="10000,15000,20000,None"/> <dip bits="22" name="Difficulty" ids="Hard,Normal"/> </switches> <!-- rom index 1 or any other index can pass additional information to a rom. useful to say this rom is game A or game 1. Use it in case of multiple games for the same RBF, ie: Dig Dug 2, Mappy --> <rom index="1"> <part>0A</part> </rom> <!-- rom index 0 is the standard rom. The zip will be added to the name inside the part, unless the part has it's own zip. The md5 will be checked at the end. A file not found error is reported before an md5 error. --> <rom index="0" zip="dkong.zip" md5="05fb1dd1ce6a786c538275d5776b1db1" type="merged|nonmerged|split"> <part crc="ba70b88b" name="c_5et_g.bin"/> <!-- begin kill screen fix --> <patch offset="0xf7d"> FE 04 38 02 3E 04 47 A7 17 A7 17 A7 17 80 80 C6 28 </patch> <!-- end kill screen fix --> <part crc="d6412358" name="c-2j.bpr"/> <part crc="b869b8f5" zip="another.zip" name="v-5e.bpr"/> <part crc="b869b8f5" name="v-5e.bpr" offset="1024" length="1024"/> <part repeat="3328">00</part> <part> 80 80 80 80 80 80 7F 7F 7F 7F 7F 7F 7F 80 80 80 </part> </rom> <!-- if the first rom0 fails the md5 checksum, it will go ahead and try again if another entry is present. Otherwise it will skip the additional entries. --> <rom index="0" zip="dkong.zip" md5="05fb1dd1ce6a786c538275d5776b1db1"> </rom> </misterromdescription>
When creating a core you can pass additional data in using ioctl_index > 0.
// Retrieve Title No. always @(posedge clk_sys) begin if (ioctl_wr & (ioctl_index==1)) tno <= ioctl_dout[3:0]; end
Explanation of certain XML elements and attributes
- name: As an element this indicates how the rom should be called. The value should be taken from MAME. As an attribute this indicates an external rom file (or part thereof) that should be loaded by MiSTer.
- mratimestamp: This indicates the date on which the *.mra-file was created (useful for other users to determine if there is a newer version of the *.mra-file available to which they should upgrade). The date format is yyyymmdd.
- mameversion: This indicates on which version of a MAME romset the *.mra-file is based (which version was used for testing). The dot in MAME's version numbering is omitted.
- setname: This indicates the name of the romset used as given by MAME.
- year: This indicates the year the game was released. The format is YYYY and the value should be taken from MAME.
- manufacturer: This indicates the manufacturer of the game. The value should be taken from MAME.
- rbf: This indicates the filename (sans path and extension) of the core that should be used to run the game.
- part: The part element is only allowed inside a rom element. It is used for specifying a part of the rom. The content of a part can either be embedded as a hex value into the *.mra-file itself (if copyright law allows) or there can be a reference to an external file via the name attribute. If the external file is in a different zip file than the parent rom element, the filename of the zip file must be specified via the zip attribute. The crc attribute specifies the CRC32 checksum of the respective part (format: eight hex digits). If a crc value is specified, MiSTer will try to select the appropriate file by crc (and only revert to the filename specified by the attribute name, if the crc value does not match). This increases compatibility of the *.mra-file with different MAME versions of the romset. As crc values are only relevant for external files, a crc value should only be given to a part element when there is a reference to an external file. The repeat-attribute only applies to embedded parts and indicates for how long (not how many times) the sequence should be repeated. By default decimal numbers are assumed. Hex numbers must be preceded with "0x". Inside the rom element, the offset- and length-attributes only apply to external files. To use the offset-attribute for internal data, the patch element must be used. Offset indicates the location inside the file from where MiSTer should start reading and length indicates the length of the sequence that MiSTer should be reading. By default decimal numbers are assumed. Hex numbers must be preceded with "0x".
- patch: The patch element is only allowed inside a rom element. It is applied after the whole rom is created from its parts and overwrites the content of the rom with the content of the patch element, starting from the specified offset and for the length of the patch element's content.
Dip switch support in the latest version of MRA is used instead of the status bits. The DIP config str is listed in the core, and the core is responsible for reading the up to 64bits of dip data that is sent via ioctl_index 254.
reg [7:0] sw; always @(posedge clk_sys) if (ioctl_wr && (ioctl_index==254) && !ioctl_addr[24:3]) sw[ioctl_addr[2:0]] <= ioctl_dout;
Switches is the dip switch setting. The default are the default bytes. These are used so you can default the arcade into the proper factory settings. This is useful when the factory settings aren't all OFF/OFF/OFF.
The dip tag let's you put in a dip switch entry. The bit number (starting at 0) is based on the way the core was written. Often MAME source code can be used to understand the bits. The numbering will depend on the rom used, the arcade core, and how things are laid out.
- bits: bit number to fill out sent to the core in ioctl_data
- name: title for the OSD
- ids: title for each option in the OSD
- values: if you want the values to be different than 0,1,2,3 you can reorder them
<dip bits="16,17" name="Coinage" ids="2c/1cr,1c/1cr,1c/2cr,Free Play" values="3,1,2,0"/>