MAMEDEV Wiki - User contributions [en-gb]

MadSkunk

2009-04-28T22:20:48Z

Madskunk: New page: MadSkunk is the pseudonym of Matthew Taylor, a UK software and web site developer.

MadSkunk is the pseudonym of Matthew Taylor, a UK software and web site developer.

Programmable Logic Devices in MAME

2008-07-17T13:26:10Z

Madskunk: New page: One of the best uses of MAME is the identification of random video game parts. Thanks to the -romident feature, you can dump a ROM or PROM from a game and pretty quickly identify what game...

One of the best uses of MAME is the identification of random video game parts. Thanks to the -romident feature, you can dump a ROM or PROM from a game and pretty quickly identify what game you have. If you've ever owned a giant pile of PCBs, you'll know it's not always easy to tell.

In theory, MAME should catalog all the programmable parts on an arcade PCB. This is useful not only because of the -romident feature, but also because if a part fails due to bit rot or corrosion or some other kind of damage (or is just missing), you can identify it, track down the data, and program yourself a new one. Up until now, we have only been really cataloging ROM-based devices, in spite of the fact that another class of device -- the Programmable Logic Device (PLD) -- is often found on PCBs, especially those dating from the mid-80's onward. PLDs are a class of device that includes PALs, GALs, and other related devices, which are programmable in much the same way that ROMs and EPROMs are.

One of the big reasons why we haven't been including PLDs is because they are generally not stored in raw binary format, like ROM data. Rather, they are stored in a format known as the JEDEC file format (.JED), which is basically a text file containing all the data, with lots of room for programmer-inserted comments and many optional fields.

This is not really a big problem in and of itself, except for the fact that every single programmer out there, when reading a PLD, will produce slightly different output. This in turn makes tools such as the -romident feature useless for such devices because -romident works by comparing the CRCs and SHA1s of the files, which would be different even for the same PLD read by different programmers.

== The solution ==
At the creamy center of a .JED file is what is known as the "fuse map".
This is the raw set of binary 1s and 0s that get programmed into the PLD. In fact, the rest of the .JED file beyond that is mostly filler:
some checksums, default states for unspecified fuses, etc. The final fuse map is really the important data, along with the type of device that was used (was it a GAL16V8A or a PAL16L8?)

So the basic premise for logic devices in MAME works like this: the fuse map is stored in raw binary form, preceded by a single 32-bit (big-endian) value that specifies the total number of fuses. Each bit of the fuse map is packed into a byte from LSB to MSB. This, it turns out, is the exact format that is used for the internal fuse map checksum, so it is a natural arrangement. I decided not to try and encode the device type into the file because (a) there are way too many devices to be concerned with, and (b) many devices with similar but not identical names are equivalent. Rather, PLDs that are added to MAME should specify the device type in the filename. (Also keep in mind that if the device type were encoded into the file itself, then if person A reads a GAL16V8 and person B reads a GAL16V8A that contain identical data, they would not match.)

How do you get data in and out of this format? Since [[MAME 0.105u4|0.105u4]], the default build of MAME will build a new utility called jedutil, which can convert a .JED file into its binary form, and vice-versa. This means that you can find the binary form of a PLD, run jedutil on it, and extract a .JED which can be programmed into a real life PLD using any standard programmer.

So how does this help -romident? Well, if you read a PLD from a board and want to see if it matches anything we've cataloged, you can do one of two things. You can take the resulting .JED and run jedutil on it to convert it to binary form. Or, you can just point -romident to the .JED file directly, because code has been added to the romident feature that recognizes .JED files and automatically parses them into binary form on the fly.

The first experiments in using this will be the mid-80's and later Atari games. There are several other games out there that we already have good PAL/GAL dumps from as well. Hopefully we can produce an even more complete catalog of arcade game devices as a result.

How MAME Works

2008-07-17T13:15:48Z

Madskunk: Updated 'Programmable logic...' /* For Driver Writers */

The following is a list of documents describing the internal workings (core) of the MAME emulator. Most are penned by Aaron Giles.

== Building MAME ==
* [[Building MAME using Microsoft Visual Studio compilers]]

== Writing for MAME ==
* [[MAME Coding Conventions]]

== For Driver Writers ==
* [[Game Drivers]]
* [[Resource Management in MAME]]
* [[DIP Switches in MAME]]
* [[MAME Interrupt Function Review]]
* [[Using MAME's tilemap system]]
* [[Programmable Logic Devices in MAME]]
* [[CPUs and Address Spaces]]
* [[Address Maps]]

== Core Internals ==
* [[Filters and streams in the MAME Sound System]]
* [[Save State Fundamentals]]
* [[Using the GFX/TileMap viewer (F4)]]
* [[How To Use the 'New' Renderer]]
* [[Layouts and Rendering for MAME Artwork System]]
* [[LAY File Basics - Part I]]

== CPU Emulation ==
* [[Virtual TLB]]
* [[CPU Scheduling in MAME]]

== Universal Dynamic Recompiler ==
* [[Core Concepts]]
* [[UML Architecture]]
** [[UML Control Flow Opcodes]]
** [[UML Internal Register Opcodes]]
** [[UML Integer Opcodes]]
** [[UML Floating Point Opcodes]]
* [[Dynamic Recompiler Author's Guide]]
* [[Back-End Author's Guide]]

== Tips & Tricks ==
* [[Executing Code Out of a Memory Region With a Read Handler]]
* [[Checklist for Cleaning Up Drivers]]
* [[Writing Messages to the Screen In a MAME Driver]]

Filters and streams in the MAME Sound System

2008-07-17T13:14:40Z

Madskunk: New page: The old MAME sound design came about as a result of an evolution from the original MAME code. The problem with evolutionary coding is that at some point it gets gross and unmanageable. Thi...

The old MAME sound design came about as a result of an evolution from the original MAME code. The problem with evolutionary coding is that at some point it gets gross and unmanageable. This is exactly what happened with the existing sound core. The flow of sound is essentially:

sound core -> stream -> mixer -> OSD

This isn't really so bad, except that streams were something we added later, so a lot of old code is still left directly talking to the mixer. On top of that bit of fun, some basic RC filters were added to the streams engine, and some other filter types were added to the mixer engine.

In the new order of things, as said before, there is no separate mixer engine. In addition, the functionality of a stream has been enhanced. Originally, a stream was a single output channel of audio. Chips that output stereo, for example, would end up allocating a special "joined stream", which was really two streams, but which act kind of like a single stream. Confused yet?

Anyway, the new streams are more flexible. Each stream can have multiple output channels, as well as multiple input channels. Each input channel can be connected to a single output from another stream. And each output channel can be connected to multiple input channels on other streams.

Here are some examples.

Two chips with a single output each, routed to a mono speaker. In this case the mixer is created with two inputs and one output:

chip #1 ---+
+---> mixer filter ---> mono speaker
chip #2 ---+

One mono chip with a single output, routed to both the left and right speakers. In this case we have two speaker outputs, and two mixers, each with one input. The output from the mono chip is split to the input of two filters:

+---> left mixer filter ---> left speaker
chip ---+
+---> right mixer filter ---> right speaker

Now the creation of filters becomes dead easy. The RC filter that is in the stream engine now just becomes another sound component that you need to wire up. Let's say you want an RC filter on the output of one of the chips in the first example. It's just:

chip #1 ---> RC filter---+
+---> mixer filter ---> mono speaker
chip #2 -----------------+

And the one other nice thing is that with a few minor tweaks to the discrete sound engine, it can also make use of these input sound streams in order to do much more complex and accurate filtering than was possible with the hacked-in basic filters.

How MAME Works

2008-07-17T13:08:36Z

Madskunk: Updated 'filters and streeams...' /* Core Internals */

The following is a list of documents describing the internal workings (core) of the MAME emulator. Most are penned by Aaron Giles.

== Building MAME ==
* [[Building MAME using Microsoft Visual Studio compilers]]

== Writing for MAME ==
* [[MAME Coding Conventions]]

== For Driver Writers ==
* [[Game Drivers]]
* [[Resource Management in MAME]]
* [[DIP Switches in MAME]]
* [[MAME Interrupt Function Review]]
* [[Using MAME's tilemap system]]
* [http://aarongiles.com/?p=159 Programmable Logic Devices in MAME]
* [[CPUs and Address Spaces]]
* [[Address Maps]]

== Core Internals ==
* [[Filters and streams in the MAME Sound System]]
* [[Save State Fundamentals]]
* [[Using the GFX/TileMap viewer (F4)]]
* [[How To Use the 'New' Renderer]]
* [[Layouts and Rendering for MAME Artwork System]]
* [[LAY File Basics - Part I]]

== CPU Emulation ==
* [[Virtual TLB]]
* [[CPU Scheduling in MAME]]

== Universal Dynamic Recompiler ==
* [[Core Concepts]]
* [[UML Architecture]]
** [[UML Control Flow Opcodes]]
** [[UML Internal Register Opcodes]]
** [[UML Integer Opcodes]]
** [[UML Floating Point Opcodes]]
* [[Dynamic Recompiler Author's Guide]]
* [[Back-End Author's Guide]]

== Tips & Tricks ==
* [[Executing Code Out of a Memory Region With a Read Handler]]
* [[Checklist for Cleaning Up Drivers]]
* [[Writing Messages to the Screen In a MAME Driver]]

Save State Fundamentals

2008-06-28T11:39:11Z

Madskunk: Removed the unneeded <code> tags

Before adding save state support to a driver in MAME, it's important to understand how the overall save state system works. But first, a word of warning: it's been said in the past that adding save state support to a driver is easy. Let's clarify that by saying: adding save state support a driver is relatively easy ''if you know C well''. How do you know whether or not you know C well? Read on...

The basic concept of saving the state of any emulator involves first identifying all the information that represents the current state of the system, and then writing that data out to disk in some fashion for later retrieval. There are many ways this can be done. Let's look at the first step: what comprises the set of data that needs to be saved in order to fully represent the state of an emulated system?

Some obvious candidates are:
# the registers and internal state on each CPU
# information about what each sound chip is doing
# the contents of all RAM (including video, palette, sound RAM) in the system
# all timing information
# the state of any peripheral devices (EEPROMs, IDE controllers, etc.)
# the currently selected memory bank for banked RAM/ROM
# the state of any driver-specific devices

Fortunately, due to MAME's modular design, a lot of this is taken care of centrally. For example, many common CPU cores already have built-in support for saving their registers and internal state, as do many common sound chip emulators. Similarly, the MAME core handles saving the contents of all RAM and timers. And many peripheral devices can save their state as well, as long as they have some sort of <code>init()</code> function that is called to set them up. This leaves memory banks and driver-specific devices as the two main things that need to be managed manually for each driver.

== Saving the Data ==

In MAME, the save state system is designed as a primarily passive system. That is, MAME's save state code assumes that all the data you want to save lives in memory somewhere. It is the client's responsibility to inform the save state system where in memory that data lies, and in what format it exists. This is generally done at initialization time. The save state system manages the rest of the process from there.

Each piece of data that is registered is required to have a unique signature. This signature is actually a combination of three pieces of data: the module name, the instance number, and the data name.

The module name is a string that is intended to represent the name of the module that is saving the data; generally this is the name of the CPU (e.g., "Z80") or driver (e.g., "pacman"), but really can be any unique identifier at all.

The instance number specifies an index within the module; for example, the first Z80 in the system will use a module name "Z80" with an instance number of 0, while the second one will also use a module name "Z80" but with an instance number of 1.

The data name is a string that represents the name of the specific piece of data. For example, the AF register on a Z80 might be registered with a data name of "AF".

Keep in mind that the combination of these three pieces of data must be 100% unique within the system. Any attempt to re-register an identical set of data will abort out of MAME with an error.

So, how do you register this data? Well, you use one of the many different registration functions available in state.h:
void state_save_register_UINT8
void state_save_register_INT8
void state_save_register_UINT16
void state_save_register_INT16
void state_save_register_UINT32
void state_save_register_INT32
void state_save_register_UINT64
void state_save_register_INT64
void state_save_register_double
void state_save_register_float
Each of these functions takes a module name, an instance number, a data name, a pointer to the variable to be saved, and a count. The first three parameters I've already explained above. The pointer is just that: the address of where the data currently lives in memory. And the count is there so that you can register a whole array of data in a single call.

Let's look at an example. In this example, we have several global variables that need to be saved, one of which is an array, and one of which is dynamically allocated. For this example, we register in the MACHINE_INIT callback:

static UINT8 irq_state;
static UINT8 irq_vector;
static UINT16 irq_mask[16];
static UINT32 *allocated_data;

MACHINE_INIT( example1 )
{
state_save_register_UINT8("example1", 0, "irq_state", &irq_state, 1);
state_save_register_UINT8("example1", 0, "irq_vector", &irq_vector, 1);
state_save_register_UINT16("example1", 0, "irq_mask", irq_mask, 16);

allocated_data = auto_malloc(1000 * sizeof(*allocated_data));

state_save_register_UINT32("example1", 0, "allocated_data", allocated_data, 1000);
}
A few observations here. First, you'll notice that we've set the data name equal to the name of the variable we're saving. Since these are just global variables, they don't need special instance numbers (those are mainly useful if you have a peripheral device that could have multiple instances). "example1" was arbitrarily picked as the module name, though any name would have sufficed.

The first two items are single variables, so we pass the address of the variable and a count of 1. The third item is an array, so we pass the address of the array and a count equal to the number of items in the array. The last item is similar, except that the data is allocated dynamically before passing the pointer and length into the registration function.

You'll notice that writing that is kind of tedious, and there are some obvious patterns. For example, the module name for global variables is pretty much irrelevant, the instance number is always 0 here, and the data names are consistently related to the variable names. Furthermore, the compiler knows the type of each variable, so having to specify it explicitly is just extra work. Plus, the count for single variables is always 1, and the count for arrays can be determined at compile-time. To this end, there are some macros that simplify matters:

static UINT8 irq_state;
static UINT8 irq_vector;
static UINT16 irq_mask[16];
static UINT32 *allocated_data;

MACHINE_INIT( example1 )
{
state_save_register_global(irq_state);
state_save_register_global(irq_vector);
state_save_register_global_array(irq_mask);

allocated_data = auto_malloc(1000 * sizeof(*allocated_data));

state_save_register_global_pointer(allocated_data, 1000);
}
Ah, much simpler! All "global" items are registered with the "globals" module name and instance number 0. The '''state_save_register_global''' macro registers a single variable, while '''state_save_register_global_array''' registers an array, and '''state_save_register_global_pointer''' registers a dynamically allocated array.

This is the part where it is crucial to have a good, basic understanding of C. You need to understand how pointers, arrays, and variables work in C, and how they differ. You also need to understand the answers to questions like: Why don't you need to save the pointers themselves? If you can't answer that last one, you'll probably be a bit out of your depth trying to add save state support to drivers in MAME.

The final thing to mention about registering data for save states is that there is only a small window of time in which registrations are allowed, starting from early in initialization until just after the driver's MACHINE_INIT callback is called. This means that at init time, you need to register everything you might want to save up front. The reason for this will become clearer in a future article which explains how restore works.

Checklist for Cleaning Up Drivers

2008-06-28T11:35:08Z

Madskunk: Simple Wiki formatting changes

Over the past year(s), Aaron has done some driver "cleanup" work. This generally involves picking apart a driver, revisiting all the assumptions using whatever information is available, and updating it to take advantage of newer features in MAME that have been introduced since it was first written. To do this work, Aaron keeps a checklist of things to do, just to make sure all bases are covered. This list is constantly updated, but since it is a good set of guidelines for updating a driver, or writing a new one from scratch, it is provided here.

'''Timing/interrupts:'''
* all crystals on the PCB documented via #defines
* all CPU and sound clocks derived from #defined crystal values
* re-verify interrupt generation timing and sources
* implement interrupt acknowledges (many older drivers didn't bother)
*add accurate watchdog durations

'''Memory:'''
* unified read/write memory maps (they used to be separate)
* map the entire address space fully, if possible from schematics
* use AM_SHARE where appropriate (better than sharedram read/write handlers)
* convert memory banking to the new system (memory_configure_bank)

'''Graphics:'''
* gfx layouts should use RGN_FRAC wherever possible instead of hard-coded values
* gfx layouts that are common should be shared (vidhrdw/generic.c)
* accurate hblank/vblank/visible areas, derived from schematics if possible
* convert from old macros to new screen macros for display info
* use new more accurate screen timing routines for H/V positions
* convert to tilemaps, if applicable
* change to use resistors for palette generation
* add limits on sprite drawing (e.g., how many per scanline), if known

'''Inputs:'''
* tag all input ports
* change all port references in code to use tags
* convert non-DIP configurations to configs
* use PORT_CUSTOM where appropriate instead of memory overrides
* connect coin counters (often missing)
* connect PCB outputs via the new output system
* add DIPLOCATIONS
* verify DIPs and inputs

'''ROMs:'''
* memory regions reduced to minimum size (they don't have to cover the whole address space)
* make sure ROM names are good and accurate to what we know
* check for any unemulated clones

'''General:'''
* update source files to be in order: header, includes, constants, typedefs, macros, globals, inlines, code
* update driver file to be in the same order, followed by: address maps, input ports, graphics definitions, sound configs, machine driver, ROMs, driver init code, drivers
* add save state support
* move all globals to hang off of driver_data
* de-obfuscate the code where it is confusing

Some recent driver updates that are pretty up to date include: <code>ccastles.c, cloud9.c, missile.c, turbo.c, zaxxon.c.</code>

Writing Messages to the Screen in a MAME Driver

2008-06-28T11:27:01Z

Madskunk: Corrected a missing ''''

One of the side-effects of the new video system is that drivers aren't allowed to write to the UI layer directly. They can call <code>popmessage()</code> to display a popup at the bottom of the screen, but that's about it in the new system. The problem is that a few drivers were displaying important game-related information using the UI font. Specifically, Atari Football was using it to show which plays had been selected, and the Exidy Max-a-Flex system was using it to draw the status of the lamps and timer. In retrospect, it is actually good that these cases broke because the way it was being done before was a big hack. For one thing, it meant that the game screen area was artificially increased to make room for the text. And second, the state of these lamps was not being properly exposed to the outside world (or in the case of Football, it was being changed via the rendering system in addition to being displayed on screen).

Ideally, the state of these indicators should be made visible via the rendering system. This is great, except that in the absence of an external artwork file, there would be no visible indication at all. This is one of the reasons why it's good to have built-in layouts in the MAME code -- even if they are crude approximations of the original artwork, they at least can reflect important functional information. The problem is, built-in layouts can't really reference image files. All they can do is draw rectangles and disks, which is sufficient for basic overlays on top of old black & white games, but isn't really enough to provide textual information.

In order to solve this problem, a couple of new primitives have been added to the layouts. In addition to rect and disk primitives, the two new primitives are: text and led7seg.

The text primitive lets you add text anywhere within the artwork area. You can specify color and bounds just like the other primitives. The text is drawn using the built-in fixed-width MAME font (even if you have a different UI font), and is centered within the bounds. If there is too much text to fit in the area provided, the font will be squashed horizontally to fit. Here's an example that positions the text "GAME OVER" in red centered within the given rectangle:

<code><text string="GAME OVER">
<bounds x="0" y="0" height="10" width="200" />
<color red="1.0" green="0.0" blue="0.0" />
</text></code>

The led7seg primitive lets you position a standard 7-segment LED somewhere in the artwork. The LEDs are drawn in a high resolution and oversampled down so they look nice. Typically these are used to specify a digit from 0-9, Turbo is one example. To use this, you would typically create an element with multiple states, each state reflecting the corresponding digit. Here's an example that positions a red LED with the number "2" that is only visible with the containing element is in state "2":

<code><led7seg pattern="10111010" state="2">
<color red="1.0" green="0.0" blue="0.0" />
</led7seg></code>

The pattern attribute specifies which of the segments is visible. A 1 means "on", and a 0 means "off". They are specified in the following order:

# Top horizontal segment
# Upper left vertical segment
# Upper right vertical segment
# Middle horizontal segment
# Lower left vertical segment
# Lower right vertical segment
# Bottom horizontal segment
# Decimal point

Using these two new primitives, built-in layouts have been created for the Atari sports games ('''Football''' and '''Baseball'''), the Sega Z80 scaling games ('''Turbo''', '''Subroc 3D''', '''Buck Rogers'''), Taito's '''Super Speed Race''', and the Exidy Max-a-Flex system that display all the essential lamps and score/timing information. Of course, you can continue to use the externally-provided artwork for a better visual appearance, but now it's possible to provide vital lamps and LEDs via the new built-in layouts without affecting the core game screen or abusing the UI system.

Writing Messages to the Screen in a MAME Driver

2008-06-28T11:25:33Z

Madskunk: A couple of Wiki style changes

One of the side-effects of the new video system is that drivers aren't allowed to write to the UI layer directly. They can call <code>popmessage()</code> to display a popup at the bottom of the screen, but that's about it in the new system. The problem is that a few drivers were displaying important game-related information using the UI font. Specifically, Atari Football was using it to show which plays had been selected, and the Exidy Max-a-Flex system was using it to draw the status of the lamps and timer. In retrospect, it is actually good that these cases broke because the way it was being done before was a big hack. For one thing, it meant that the game screen area was artificially increased to make room for the text. And second, the state of these lamps was not being properly exposed to the outside world (or in the case of Football, it was being changed via the rendering system in addition to being displayed on screen).

Ideally, the state of these indicators should be made visible via the rendering system. This is great, except that in the absence of an external artwork file, there would be no visible indication at all. This is one of the reasons why it's good to have built-in layouts in the MAME code -- even if they are crude approximations of the original artwork, they at least can reflect important functional information. The problem is, built-in layouts can't really reference image files. All they can do is draw rectangles and disks, which is sufficient for basic overlays on top of old black & white games, but isn't really enough to provide textual information.

In order to solve this problem, a couple of new primitives have been added to the layouts. In addition to rect and disk primitives, the two new primitives are: text and led7seg.

The text primitive lets you add text anywhere within the artwork area. You can specify color and bounds just like the other primitives. The text is drawn using the built-in fixed-width MAME font (even if you have a different UI font), and is centered within the bounds. If there is too much text to fit in the area provided, the font will be squashed horizontally to fit. Here's an example that positions the text "GAME OVER" in red centered within the given rectangle:

<code><text string="GAME OVER">
<bounds x="0" y="0" height="10" width="200" />
<color red="1.0" green="0.0" blue="0.0" />
</text></code>

The led7seg primitive lets you position a standard 7-segment LED somewhere in the artwork. The LEDs are drawn in a high resolution and oversampled down so they look nice. Typically these are used to specify a digit from 0-9, Turbo is one example. To use this, you would typically create an element with multiple states, each state reflecting the corresponding digit. Here's an example that positions a red LED with the number "2" that is only visible with the containing element is in state "2":

<code><led7seg pattern="10111010" state="2">
<color red="1.0" green="0.0" blue="0.0" />
</led7seg></code>

The pattern attribute specifies which of the segments is visible. A 1 means "on", and a 0 means "off". They are specified in the following order:

# Top horizontal segment
# Upper left vertical segment
# Upper right vertical segment
# Middle horizontal segment
# Lower left vertical segment
# Lower right vertical segment
# Bottom horizontal segment
# Decimal point

Using these two new primitives, built-in layouts have been created for the Atari sports games ('''Football''' and '''Baseball'''), the Sega Z80 scaling games ('''Turbo''', '''Subroc 3D''', '''Buck Rogers), Taito's '''Super Speed Race''', and the Exidy Max-a-Flex system that display all the essential lamps and score/timing information. Of course, you can continue to use the externally-provided artwork for a better visual appearance, but now it's possible to provide vital lamps and LEDs via the new built-in layouts without affecting the core game screen or abusing the UI system.

Save State Fundamentals

2008-06-28T11:22:53Z

Madskunk:

Before adding save state support to a driver in MAME, it's important to understand how the overall save state system works. But first, a word of warning: it's been said in the past that adding save state support to a driver is easy. Let's clarify that by saying: adding save state support a driver is relatively easy ''if you know C well''. How do you know whether or not you know C well? Read on...

The basic concept of saving the state of any emulator involves first identifying all the information that represents the current state of the system, and then writing that data out to disk in some fashion for later retrieval. There are many ways this can be done. Let's look at the first step: what comprises the set of data that needs to be saved in order to fully represent the state of an emulated system?

Some obvious candidates are:
# the registers and internal state on each CPU
# information about what each sound chip is doing
# the contents of all RAM (including video, palette, sound RAM) in the system
# all timing information
# the state of any peripheral devices (EEPROMs, IDE controllers, etc.)
# the currently selected memory bank for banked RAM/ROM
# the state of any driver-specific devices

Fortunately, due to MAME's modular design, a lot of this is taken care of centrally. For example, many common CPU cores already have built-in support for saving their registers and internal state, as do many common sound chip emulators. Similarly, the MAME core handles saving the contents of all RAM and timers. And many peripheral devices can save their state as well, as long as they have some sort of <code>init()</code> function that is called to set them up. This leaves memory banks and driver-specific devices as the two main things that need to be managed manually for each driver.

== Saving the Data ==

In MAME, the save state system is designed as a primarily passive system. That is, MAME's save state code assumes that all the data you want to save lives in memory somewhere. It is the client's responsibility to inform the save state system where in memory that data lies, and in what format it exists. This is generally done at initialization time. The save state system manages the rest of the process from there.

Each piece of data that is registered is required to have a unique signature. This signature is actually a combination of three pieces of data: the module name, the instance number, and the data name.

The module name is a string that is intended to represent the name of the module that is saving the data; generally this is the name of the CPU (e.g., "Z80") or driver (e.g., "pacman"), but really can be any unique identifier at all.

The instance number specifies an index within the module; for example, the first Z80 in the system will use a module name "Z80" with an instance number of 0, while the second one will also use a module name "Z80" but with an instance number of 1.

The data name is a string that represents the name of the specific piece of data. For example, the AF register on a Z80 might be registered with a data name of "AF".

Keep in mind that the combination of these three pieces of data must be 100% unique within the system. Any attempt to re-register an identical set of data will abort out of MAME with an error.

So, how do you register this data? Well, you use one of the many different registration functions available in state.h:
<code>void state_save_register_UINT8
void state_save_register_INT8
void state_save_register_UINT16
void state_save_register_INT16
void state_save_register_UINT32
void state_save_register_INT32
void state_save_register_UINT64
void state_save_register_INT64
void state_save_register_double
void state_save_register_float</code>
Each of these functions takes a module name, an instance number, a data name, a pointer to the variable to be saved, and a count. The first three parameters I've already explained above. The pointer is just that: the address of where the data currently lives in memory. And the count is there so that you can register a whole array of data in a single call.

Let's look at an example. In this example, we have several global variables that need to be saved, one of which is an array, and one of which is dynamically allocated. For this example, we register in the MACHINE_INIT callback:

<code>static UINT8 irq_state;
static UINT8 irq_vector;
static UINT16 irq_mask[16];
static UINT32 *allocated_data;

MACHINE_INIT( example1 )
{
state_save_register_UINT8("example1", 0, "irq_state", &irq_state, 1);
state_save_register_UINT8("example1", 0, "irq_vector", &irq_vector, 1);
state_save_register_UINT16("example1", 0, "irq_mask", irq_mask, 16);

allocated_data = auto_malloc(1000 * sizeof(*allocated_data));

state_save_register_UINT32("example1", 0, "allocated_data", allocated_data, 1000);
}</code>
A few observations here. First, you'll notice that we've set the data name equal to the name of the variable we're saving. Since these are just global variables, they don't need special instance numbers (those are mainly useful if you have a peripheral device that could have multiple instances). "example1" was arbitrarily picked as the module name, though any name would have sufficed.

The first two items are single variables, so we pass the address of the variable and a count of 1. The third item is an array, so we pass the address of the array and a count equal to the number of items in the array. The last item is similar, except that the data is allocated dynamically before passing the pointer and length into the registration function.

You'll notice that writing that is kind of tedious, and there are some obvious patterns. For example, the module name for global variables is pretty much irrelevant, the instance number is always 0 here, and the data names are consistently related to the variable names. Furthermore, the compiler knows the type of each variable, so having to specify it explicitly is just extra work. Plus, the count for single variables is always 1, and the count for arrays can be determined at compile-time. To this end, there are some macros that simplify matters:

<code>static UINT8 irq_state;
static UINT8 irq_vector;
static UINT16 irq_mask[16];
static UINT32 *allocated_data;

MACHINE_INIT( example1 )
{
state_save_register_global(irq_state);
state_save_register_global(irq_vector);
state_save_register_global_array(irq_mask);

allocated_data = auto_malloc(1000 * sizeof(*allocated_data));

state_save_register_global_pointer(allocated_data, 1000);
}</code>
Ah, much simpler! All "global" items are registered with the "globals" module name and instance number 0. The '''state_save_register_global''' macro registers a single variable, while '''state_save_register_global_array''' registers an array, and '''state_save_register_global_pointer''' registers a dynamically allocated array.

This is the part where it is crucial to have a good, basic understanding of C. You need to understand how pointers, arrays, and variables work in C, and how they differ. You also need to understand the answers to questions like: Why don't you need to save the pointers themselves? If you can't answer that last one, you'll probably be a bit out of your depth trying to add save state support to drivers in MAME.

The final thing to mention about registering data for save states is that there is only a small window of time in which registrations are allowed, starting from early in initialization until just after the driver's MACHINE_INIT callback is called. This means that at init time, you need to register everything you might want to save up front. The reason for this will become clearer in a future article which explains how restore works.

Save State Fundamentals

2008-06-28T11:12:29Z

Madskunk: New page: Before adding save state support to a driver in MAME, it's important to understand how the overall save state system works. But first, a word of warning: it's been said in the past that ad...

Before adding save state support to a driver in MAME, it's important to understand how the overall save state system works. But first, a word of warning: it's been said in the past that adding save state support to a driver is easy. Let's clarify that by saying: adding save state support a driver is relatively easy ''if you know C well''. How do you know whether or not you know C well? Read on...

The basic concept of saving the state of any emulator involves first identifying all the information that represents the current state of the system, and then writing that data out to disk in some fashion for later retrieval. There are many ways this can be done. Let's look at the first step: what comprises the set of data that needs to be saved in order to fully represent the state of an emulated system?

Some obvious candidates are:
# the registers and internal state on each CPU
# information about what each sound chip is doing
# the contents of all RAM (including video, palette, sound RAM) in the system
# all timing information
# the state of any peripheral devices (EEPROMs, IDE controllers, etc.)
# the currently selected memory bank for banked RAM/ROM
# the state of any driver-specific devices

Fortunately, due to MAME's modular design, a lot of this is taken care of centrally. For example, many common CPU cores already have built-in support for saving their registers and internal state, as do many common sound chip emulators. Similarly, the MAME core handles saving the contents of all RAM and timers. And many peripheral devices can save their state as well, as long as they have some sort of <code>init()</code> function that is called to set them up. This leaves memory banks and driver-specific devices as the two main things that need to be managed manually for each driver.

== Saving the Data ==

In MAME, the save state system is designed as a primarily passive system. That is, MAME's save state code assumes that all the data you want to save lives in memory somewhere. It is the client's responsibility to inform the save state system where in memory that data lies, and in what format it exists. This is generally done at initialization time. The save state system manages the rest of the process from there.

Each piece of data that is registered is required to have a unique signature. This signature is actually a combination of three pieces of data: the module name, the instance number, and the data name.

The module name is a string that is intended to represent the name of the module that is saving the data; generally this is the name of the CPU (e.g., "Z80") or driver (e.g., "pacman"), but really can be any unique identifier at all.

The instance number specifies an index within the module; for example, the first Z80 in the system will use a module name "Z80" with an instance number of 0, while the second one will also use a module name "Z80" but with an instance number of 1.

The data name is a string that represents the name of the specific piece of data. For example, the AF register on a Z80 might be registered with a data name of "AF".

Keep in mind that the combination of these three pieces of data must be 100% unique within the system. Any attempt to re-register an identical set of data will abort out of MAME with an error.

So, how do you register this data? Well, you use one of the many different registration functions available in state.h:
<source lang=c>void state_save_register_UINT8
void state_save_register_INT8
void state_save_register_UINT16
void state_save_register_INT16
void state_save_register_UINT32
void state_save_register_INT32
void state_save_register_UINT64
void state_save_register_INT64
void state_save_register_double
void state_save_register_float</source>
Each of these functions takes a module name, an instance number, a data name, a pointer to the variable to be saved, and a count. The first three parameters I've already explained above. The pointer is just that: the address of where the data currently lives in memory. And the count is there so that you can register a whole array of data in a single call.

Let's look at an example. In this example, we have several global variables that need to be saved, one of which is an array, and one of which is dynamically allocated. For this example, we register in the MACHINE_INIT callback:

<code>static UINT8 irq_state;
static UINT8 irq_vector;
static UINT16 irq_mask[16];
static UINT32 *allocated_data;

MACHINE_INIT( example1 )
{
state_save_register_UINT8("example1", 0, "irq_state", &irq_state, 1);
state_save_register_UINT8("example1", 0, "irq_vector", &irq_vector, 1);
state_save_register_UINT16("example1", 0, "irq_mask", irq_mask, 16);

allocated_data = auto_malloc(1000 * sizeof(*allocated_data));

state_save_register_UINT32("example1", 0, "allocated_data", allocated_data, 1000);
}</code>
A few observations here. First, you'll notice that I tend to set the data name equal to the name of the variable I'm saving. Since these are just global variables, they don't need special instance numbers (those are mainly useful if you have a peripheral device that could have multiple instances). I arbitrarily picked "example1" as my module name, though any name would have sufficed.

The first two items are single variables, so we pass the address of the variable and a count of 1. The third item is an array, so we pass the address of the array and a count equal to the number of items in the array. The last item is similar, except that the data is allocated dynamically before passing the pointer and length into the registration function.

You'll notice that writing that is kind of tedious, and there are some obvious patterns. For example, the module name for global variables is pretty much irrelevant, the instance number is always 0 here, and the data names are consistently related to the variable names. Furthermore, the compiler knows the type of each variable, so having to specify it explicitly is just extra work. Plus, the count for single variables is always 1, and the count for arrays can be determined at compile-time. To this end, there are some macros that simplify matters:

<code>static UINT8 irq_state;
static UINT8 irq_vector;
static UINT16 irq_mask[16];
static UINT32 *allocated_data;

MACHINE_INIT( example1 )
{
state_save_register_global(irq_state);
state_save_register_global(irq_vector);
state_save_register_global_array(irq_mask);

allocated_data = auto_malloc(1000 * sizeof(*allocated_data));

state_save_register_global_pointer(allocated_data, 1000);
}</code>
Ah, much simpler! All "global" items are registered with the "globals" module name and instance number 0. The state_save_register_global macro registers a single variable, while state_save_register_global_array registers an array, and state_save_register_global_pointer registers a dynamically allocated array.

This is the part where it is crucial to have a good, basic understanding of C. You need to understand how pointers, arrays, and variables work in C, and how they differ. You also need to understand the answers to questions like: Why don't you need to save the pointers themselves? If you can't answer that last one, you'll probably be a bit out of your depth trying to add save state support to drivers in MAME.

The final thing I will mention about registering data for save states is that there is only a small window of timeâ€”starting from early in initialization until just after the driver's MACHINE_INIT callback is calledâ€”during which registrations are allowed. This means that at init time, you need to register everything you might want to save up front. The reason for this will become clearer in a future article which explains how restore works.

How MAME Works

2008-06-28T10:41:57Z

Madskunk: /* Core Internals */

The following is a list of documents describing the internal workings (core) of the MAME emulator. Most are penned by Aaron Giles.

== Building MAME ==
* [[Building MAME using Microsoft Visual Studio compilers]]

== Writing for MAME ==
* [[MAME Coding Conventions]]

== For Driver Writers ==
* [[Resource Management in MAME]]
* [[DIP Switches in MAME]]
* [[MAME Interrupt Function Review]]
* [[Using MAME's tilemap system]]
* [http://aarongiles.com/?p=159 Programmable Logic Devices in MAME]
* [[CPUs and Address Spaces]]
* [[Address Maps]]

== Core Internals ==
* [http://aarongiles.com/?p=74 Filters and streams in the MAME Sound System]
* [[Save State Fundamentals]]
* [[Using the GFX/TileMap viewer (F4)]]
* [[How To Use the 'New' Renderer]]
* [[Layouts and Rendering for MAME Artwork System]]
* [[LAY File Basics - Part I]]

== CPU Emulation ==
* [[Virtual TLB]]
* [[CPU Scheduling in MAME]]

== Universal Dynamic Recompiler ==
* [[Core Concepts]]
* [[UML Architecture]]
** [[UML Control Flow Opcodes]]
** [[UML Internal Register Opcodes]]
** [[UML Integer Opcodes]]
** [[UML Floating Point Opcodes]]
* [[Dynamic Recompiler Author's Guide]]
* [[Back-End Author's Guide]]

== Tips & Tricks ==
* [[Executing Code Out of a Memory Region With a Read Handler]]
* [[Checklist for Cleaning Up Drivers]]
* [[Writing Messages to the Screen In a MAME Driver]]

CPU Scheduling in MAME

2008-06-28T10:39:20Z

Madskunk: Slight grammatical change

Multi-CPU games in MAME are scheduled in a round-robin fashion. The order of the round robin execution is strictly defined by the order of the CPUs in the machine driver. There is no way to alter this order; however, you can affect the scheduling by suspending CPUs or adjusting the granularity of the scheduling.

The scheduler relies on the timer system, which knows when the next timer is scheduled. All scheduling happens between firings of timers, similarly, timers are never fired while a CPU is executing. This important to keep in mind.

The scheduler queries the timer system to find out when the next timer is set to fire. It then loops over each CPU, computes how many cycles that CPU needs to execute to reach that time, and runs the CPU for that many cycles. When the CPU is finished executing, the CPU core returns how many cycles it actually executed. This information is accumulated and converted back into a "local CPU time", in order to account for overshooting or early exiting from the CPU core.

For example....

Let's say that CPU #0 is running at 14MHz, and CPU #1 is running at 2MHz. Let's also say that we're starting at time 0 (local CPU time for both CPUs is 0), and a timer is scheduled to go off in 150 microseconds (time = 0.000150).

The round robin logic will start with CPU #0 and compute how many cycles it needs to execute to reach 0.000150. Since we're starting from time 0, we need to execute for at least 150usec. 0.000150 * 14,000,000 = 2100 cycles. It then calls that CPU's execute function with 2100 cycles; when the execute function returns, it specifies how many cycles it actually ran. Let's say it returns saying that it ran 2112 cycles. (CPU cores generally overshoot because many instructions take more than 1 cycle each to execute.) 2112 cycles puts the local CPU time for CPU #0 at
0.000150857 (2112 / 14,000,000).

Now it's time for CPU #1 to execute. 0.000150 * 2,000,000 = 300 cycles.
So we call execute(300), and get back 300 cycles. CPU #1 local time is now 0.000150.

At this point, both CPUs have executed, and both their local times are greater than or equal to the target time 0.000150. So the scheduler calls the timer system to let it process the timers. When finished, it again asks when the next timer will fire. Let's say it's set to fire exactly 150usec later at time = 0.000300.

Back to the scheduler, we start the round robin over again. CPU #0 needs to execute (0.000300 - 0.000150857) * 14,000,000 = 2088 cycles to reach a local time of 0.300. Note that we took into account the extra cycles that we executed last time. So we call execute(2088), and we get back, say, 2091. That puts our local time at 0.000150857 + 0.000149357 = 0.000300214.

Now it's CPU #1's turn. (0.000300 - 0.000150) * 2,000,000 = 300 cycles again. Calling execute(300), we get back 302 cycles. This puts CPU #1's local time at 0.000150 + 0.000151 = 0.000301.

Again, both CPUs have executed, both their local times are greater than or equal to 0.000300, so we contact the timer system to let it run its timers. This procedure continues throughout the execution of the system.

Some things to note here, firstly, after the first round robin, CPU #0's local time was slightly ahead of CPU #1's local time. After the second pass, the opposite was true. Thus, you can't guarantee at any time that any given CPU is ahead of or behind the others.

Also, be sure to keep in mind that each CPU has its own local time. The timer system also has a "global time". The global time is generally the minimum of all the CPU local times. Which time is used when calling the timer system depends entirely upon which CPU context is currently active. If a CPU context is active (generally true only while a CPU is executing; for example, in read/write callbacks), then all timer operations treat the "current time" as the CPU local time, accounting for all cycles that have been executed on that CPU so far in the current timeslice. If a CPU context is not active (all other times; for example, in timer callbacks), then the "current time" is the global time.

The global time is updated at the end of each timeslice before the scheduler calls into the timer system to let it run its timers, and that global time is used to dispatch the timers.

CPU Scheduling in MAME

2008-06-28T00:13:53Z

Madskunk: New page: Multi-CPU games in MAME are scheduled in a round-robin fashion. The order of the round robin execution is strictly defined by the order of the CPUs in the machine driver. There is no way t...

Multi-CPU games in MAME are scheduled in a round-robin fashion. The order of the round robin execution is strictly defined by the order of the CPUs in the machine driver. There is no way to alter this order; however, you can affect the scheduling by suspending CPUs or adjusting the granularity of the scheduling.

The scheduler relies on the timer system, which knows when the next timer is scheduled. All scheduling happens between firings of timers, similarly, timers are never fired while a CPU is executing. This important to keep in mind.

The scheduler queries the timer system to find out when the next timer is set to fire. It then loops over each CPU, computes how many cycles that CPU needs to execute to reach that time, and runs the CPU for that many cycles. When the CPU is finished executing, the CPU core returns how many cycles it actually executed. This information is accumulated and converted back into a "local CPU time", in order to account for overshooting or early exiting from the CPU core.

For example....

Let's say that CPU #0 is running at 14MHz, and CPU #1 is running at 2MHz. Let's also say that we're starting at time 0 (local CPU time for both CPUs is 0), and a timer is scheduled to go off in 150 microseconds (time = 0.000150).

The round robin logic will start with CPU #0 and compute how many cycles it needs to execute to reach 0.000150. Since we're starting from time 0, we need to execute for at least 150usec. 0.000150 * 14,000,000 = 2100 cycles. It then calls that CPU's execute function with 2100 cycles; when the execute function returns, it specifies how many cycles it actually ran. Let's say it returns saying that it ran 2112 cycles. (CPU cores generally overshoot because many instructions take more than 1 cycle each to execute.) 2112 cycles puts the local CPU time for CPU #0 at
0.000150857 (2112 / 14,000,000).

Now it's time for CPU #1 to execute. 0.000150 * 2,000,000 = 300 cycles.
So we call execute(300), and get back 300 cycles. CPU #1 local time is now 0.000150.

At this point, both CPUs have executed, and both their local times are greater than or equal to the target time 0.000150. So the scheduler calls the timer system to let it process the timers. When finished, it again asks when the next timer will fire. Let's say it's set to fire exactly 150usec later at time = 0.000300.

Back to the scheduler, we start the round robin over again. CPU #0 needs to execute (0.000300 - 0.000150857) * 14,000,000 = 2088 cycles to reach a local time of 0.300. Note that we took into account the extra cycles that we executed last time. So we call execute(2088), and we get back, say, 2091. That puts our local time at 0.000150857 + 0.000149357 = 0.000300214.

Now it's CPU #1's turn. (0.000300 - 0.000150) * 2,000,000 = 300 cycles again. Calling execute(300), we get back 302 cycles. This puts CPU #1's local time at 0.000150 + 0.000151 = 0.000301.

Again, both CPUs have executed, both their local times are greater than or equal to 0.000300, so we contact the timer system to let it run its timers. This procedure continues throughout the execution of the system.

Some things to note here, firstly, after the first round robin, CPU #0's local time was slightly ahead of CPU #1's local time. After the second pass, the opposite was true. Thus, you can't be guaranteed at any time that any given CPU is ahead of or behind the others.

Also, be sure to keep in mind that each CPU has its own local time. The timer system also has a "global time". The global time is generally the minimum of all the CPU local times. Which time is used when calling the timer system depends entirely upon which CPU context is currently active. If a CPU context is active (generally true only while a CPU is executing; for example, in read/write callbacks), then all timer operations treat the "current time" as the CPU local time, accounting for all cycles that have been executed on that CPU so far in the current timeslice. If a CPU context is not active (all other times; for example, in timer callbacks), then the "current time" is the global time.

The global time is updated at the end of each timeslice before the scheduler calls into the timer system to let it run its timers, and that global time is used to dispatch the timers.

How MAME Works

2008-06-28T00:05:51Z

Madskunk: /* CPU Emulation */

The following is a list of documents describing the internal workings (core) of the MAME emulator. Most are penned by Aaron Giles.

== Building MAME ==
* [[Building MAME using Microsoft Visual Studio compilers]]

== Writing for MAME ==
* [[MAME Coding Conventions]]

== For Driver Writers ==
* [[Resource Management in MAME]]
* [[DIP Switches in MAME]]
* [[MAME Interrupt Function Review]]
* [[Using MAME's tilemap system]]
* [http://aarongiles.com/?p=159 Programmable Logic Devices in MAME]
* [[CPUs and Address Spaces]]
* [[Address Maps]]

== Core Internals ==
* [http://aarongiles.com/?p=74 Filters and streams in the MAME Sound System]
* [http://aarongiles.com/?p=149 Save State Fundamentals]
* [[Using the GFX/TileMap viewer (F4)]]
* [[How To Use the 'New' Renderer]]
* [[Layouts and Rendering for MAME Artwork System]]
* [[LAY File Basics - Part I]]

== CPU Emulation ==
* [[Virtual TLB]]
* [[CPU Scheduling in MAME]]

== Universal Dynamic Recompiler ==
* [[Core Concepts]]
* [[UML Architecture]]
** [[UML Control Flow Opcodes]]
** [[UML Internal Register Opcodes]]
** [[UML Integer Opcodes]]
** [[UML Floating Point Opcodes]]
* [[Dynamic Recompiler Author's Guide]]
* [[Back-End Author's Guide]]

== Tips & Tricks ==
* [[Executing Code Out of a Memory Region With a Read Handler]]
* [[Checklist for Cleaning Up Drivers]]
* [[Writing Messages to the Screen In a MAME Driver]]

How To Use the 'New' Renderer

2008-06-25T15:43:45Z

Madskunk:

There are really two ways to use the new renderer. (Well, there are really an infinite number, but these two ways were what motivated the feature set as it exists today.) Both ways will produce similar results, and both have their uses.

The first thing to understand is the concept of a render_target. A render_target is really a rendering context. It is an object that holds all the information about how you would like the renderer to assemble the primitives that make up the final result. From the OSD perspective, this is really the only object you need to talk to. You can allocate as many render_targets as you like; in the Windows OSD code, we allocate one per window. The MAME core also allocates one internally for taking snapshots.

There are a number of knobs you can twiddle on each render_target. You can enumerate all of the views available for each target, find out which game screens are present on each view, and select which one to use. You can specify the orientation of the target, which rotates all of the primitives in the appropriate direction. You can specify flags that
control which types of artwork are visible. You can tell the renderer what the maximum texture size is. You can ask it to compute the smallest size that will ensure each game screen pixel maps to at least one output pixel. And most importantly, you can specify the size or bounds of the target.

How you specify the bounds of a render_target fundamentally determines how you are using the renderer. And here is where the two approaches differ.

The first approach is to tell the render_target the absolute truth about what it is drawing to. This entails calling <code>render_target_set_bounds</code> with the actual width, height, and pixel aspect ratio of the screen you are drawing to. Thus, if the output is a 1600x1200 monitor with square pixels, you would call <code>render_target_set_bounds(1600, 1200, 1.0)</code>. This works well if your final result will be hardware accelerated. Under the covers, the renderer will assemble all the pieces to be placed within the 1600x1200 area you specified, and -- here's the key -- it will perform a high-quality resampling of any artwork to the final output resolution. This is much better quality and much more efficient than simply uploading the entire artwork as a giant texture and letting your video card filter it. Because it's not expected that you will change this size too often, the expensive overhead of resampling the artwork is usually just taken once. In contrast, the game screen textures are not resampled in this way; rather, they are always uploaded at their native resolution and your video card is expected to do the resampling.

This first approach is what you get when you run the Windows build with -video d3d or -video gdi. This is also why -video gdi is incredibly slow unless it's in a tiny window: all of that pixel pushing at full resolution is being done in software, and it ain't cheap.

The second approach is to lie to the render_target about what it is drawing to. The usual way to do this is to compute the minimum size via the <code>render_target_get_minimum_size</code> function, and then pass that width and height (or some integral multiple of such) into <code>render_target_set_bounds</code> as the target size. What happens in this case is that, as far as the renderer knows, you are drawing to a low resolution output device. It will still do high quality artwork resampling, but just to a much lower resolution. Why would you do this? The main motivation is to support limited or non-existant hardware acceleration cases.

Consider a situation where you can use your graphics hardware to accelerate only a final bitmap scaling operation, but none of the more advanced blending features required to assemble a full image. In this case, you could fall back to drawing everything in software at full resolution, but it is going to be very slow. The alternative is to lie
about the actual resolution. Instead, allocate a buffer at the render_target's minimum size, draw to that buffer, and then use the graphics hardware to scale that buffer to full screen.

This second approach is what you get when you run with Windows build with -video ddraw. And in fact, the second approach produces output that is almost identical to what MAME produced before the new renderer went in, with the addition of more flexible features.

One thing you'll notice if you look at the Windows code is that it ends up calling <code>render_target_set_bounds</code> each frame, immediately before calling <code>render_target_get_primitives</code>. The main reason for this is that the Windows system lives in a dynamic environment. We support live resizing of windows in windowed mode, which means the output resolution can change at any time when using the first method. Furthermore, games in MAME can dynamically change their resolution, and users are free to change the currently selected view, meaning that the minimum size can change from frame to frame within a game when we use the second method. For these reasons, it is just simpler to update the output size each frame before requesting the primitives so that we
ensure we're in sync.

How To Use the 'New' Renderer

2008-06-25T15:35:10Z

Madskunk: New page: Since I've had a few questions asked recently about how the new renderer works from an OSD developer's point of view, I figured this would be a good chance to kickstart things again. Ther...

Since I've had a few questions asked recently about how the new renderer
works from an OSD developer's point of view, I figured this would be a
good chance to kickstart things again.

There are really two ways to use the new renderer. (Well, there are
really an infinite number, but these two ways were what motivated the
feature set as it exists today.) Both ways will produce similar results,
and both have their uses.

The first thing to understand is the concept of a render_target.
A render_target is really a rendering context. It is an object that
holds all the information about how you would like the renderer to
assemble the primitives that make up the final result. From the OSD
perspective, this is really the only object you need to talk to. You can
allocate as many render_targets as you like; in the Windows OSD code, I
allocate one per window. The MAME core also allocates one internally for
taking snapshots.

There are a number of knobs you can twiddle on each render_target. You
can enumerate all of the views available for each target, find out which
game screens are present on each view, and select which one to use. You
can specify the orientation of the target, which rotates all of the
primitives in the appropriate direction. You can specify flags that
control which types of artwork are visible. You can tell the renderer
what the maximum texture size is. You can ask it to compute the smallest
size that will ensure each game screen pixel maps to at least one output
pixel. And most importantly, you can specify the size or bounds of the
target.

How you specify the bounds of a render_target fundamentally determines
how you are using the renderer. And here is where the two approaches
differ.

The first approach is to tell the render_target the absolute truth about
what it is drawing to. This entails calling
render_target_set_bounds with the actual width, height, and pixel
aspect ratio of the screen you are drawing to. Thus, if the output is a
1600x1200 monitor with square pixels, you would call
render_target_set_bounds(1600, 1200, 1.0). This works well if your final
result will be hardware accelerated. Under the covers, the renderer will
assemble all the pieces to be placed within the 1600x1200 area you
specified, and -- here's the key -- it will perform a high-quality
resampling of any artwork to the final output resolution. This is much
better quality and much more efficient than simply uploading the entire
artwork as a giant texture and letting your video card filter it.
Because it's not expected that you will change this size too often, the
expensive overhead of resampling the artwork is usually just taken once.
In contrast, the game screen textures are not resampled in this way;
rather, they are always uploaded at their native resolution and your
video card is expected to do the resampling.

This first approach is what you get when you run the Windows build with
-video d3d or -video gdi. This is also why -video gdi is incredibly slow
unless it's in a tiny window: all of that pixel pushing at full
resolution is being done in software, and it ain't cheap.

The second approach is to lie to the render_target about what it is
drawing to. The usual way to do this is to compute the minimum size via
the render_target_get_minimum_size function, and then pass that
width and height (or some integral multiple of such) into
render_target_set_bounds as the target size. What happens in this
case is that, as far as the renderer knows, you are drawing to a low
resolution output device. It will still do high quality artwork
resampling, but just to a much lower resolution. Why would you do this?
The main motivation is to support limited or non-existant hardware
acceleration cases.

Consider a situation where you can use your graphics hardware to
accelerate only a final bitmap scaling operation, but none of the more
advanced blending features required to assemble a full image. In this
case, you could fall back to drawing everything in software at full
resolution, but it is going to be very slow. The alternative is to lie
about the actual resolution. Instead, allocate a buffer at the
render_target's minimum size, draw to that buffer, and then use the
graphics hardware to scale that buffer to full screen.

This second approach is what you get when you run with Windows build
with -video ddraw. And in fact, the second approach produces output that
is almost identical to what MAME produced before the new renderer went
in, with the addition of more flexible features.

One thing you'll notice if you look at the Windows code is that it ends
up calling render_target_set_bounds each frame, immediately
before calling render_target_get_primitives. The main reason for
this is that the Windows system lives in a dynamic environment. We
support live resizing of windows in windowed mode, which means the
output resolution can change at any time when using the first method.
Furthermore, games in MAME can dynamically change their resolution, and
users are free to change the currently selected view, meaning that the
minimum size can change from frame to frame within a game when we use
the second method. For these reasons, it is just simpler to update the
output size each frame before requesting the primitives so that we
ensure we're in sync.

How MAME Works

2008-06-25T15:34:17Z

Madskunk: /* Core Internals */

The following is a list of documents describing the internal workings (core) of the MAME emulator. Most are penned by Aaron Giles.

== Building MAME ==
* [[Building MAME using Microsoft Visual Studio compilers]]

== Writing for MAME ==
* [[MAME Coding Conventions]]

== For Driver Writers ==
* [[Resource Management in MAME]]
* [[DIP Switches in MAME]]
* [[MAME Interrupt Function Review]]
* [[Using MAME's tilemap system]]
* [http://aarongiles.com/?p=159 Programmable Logic Devices in MAME]
* [[CPUs and Address Spaces]]
* [[Address Maps]]

== Core Internals ==
* [http://aarongiles.com/?p=137 CPU Scheduling in MAME]
* [http://aarongiles.com/?p=74 Filters and streams in the MAME Sound System]
* [http://aarongiles.com/?p=149 Save State Fundamentals]
* [[Using the GFX/TileMap viewer (F4)]]
* [[How To Use the 'New' Renderer]]
* [[Layouts and Rendering for MAME Artwork System]]
* [[LAY File Basics - Part I]]

== Universal Dynamic Recompiler ==
* [[Core Concepts]]
* [[UML Architecture]]
** [[UML Control Flow Opcodes]]
** [[UML Internal Register Opcodes]]
** [[UML Integer Opcodes]]
** [[UML Floating Point Opcodes]]
* [[Dynamic Recompiler Author's Guide]]
* [[Back-End Author's Guide]]

== Tips & Tricks ==
* [[Executing Code Out of a Memory Region With a Read Handler]]
* [[Checklist for Cleaning Up Drivers]]
* [[Writing Messages to the Screen In a MAME Driver]]

Layouts and Rendering for MAME Artwork System

2008-06-24T13:49:51Z

Madskunk: Fixed typo

MAME 0.106u2 introduced a major change that needs a more detailed description, the concept of layouts and views.

As a simplistic explanation, layouts are the replacement for the artwork description files (.art) that were previously used to describe artwork to be displayed with a game. However, layouts are much more flexible and much more deeply integrated into the rendering system than the artwork files ever were. You literally can't run the new renderer without a layout loaded.

A layout consists of two parts: a list of zero or more elements, and a list of one or more views. The elements represent a sort of database of artwork pieces that can be assembled in various ways. The views represent the actual positioning of these elements relative to the game screens. The easiest way to understand this is to look at the simplest example, which is the default layout used for regular horizontal 4:3 games:

<code><?xml version="1.0"?>
<mamelayout version="2">
<view name="Standard">
<screen index="0">
<bounds left="0" top="0" right="4" bottom="3" />
</screen>
</view>
</mamelayout></code>

This particular layout has no elements described, and only a single view. The name of the view is "Standard." This is important because there is a new menu in the UI that lets you select on the fly which view to display, and this is the name that is displayed in that menu. Within the view, there can be a number of items:

<ul>
<li>backdrops specify the attributes of elements that are drawn first and which cover the background of the screen areas; they are rendered against each other using regular alpha blending, so they can have cut-out areas and other effects</li>
<li>screens specify the attributes of the various screens that make up a game; they are referenced by index, and are rendered on top of the backdrop layer using additive blending (alpha values applied to the source but not the destination)</li>
<li>overlays specify the attributes of elements that are drawn over top of the screens and backdrops; they are rendered on top of the screens and backdrops using RGB multiplicative blending (the RGB values of the overlays are multiplied by the RGB values of the destination)</li>
<li>bezels specify the attributes of elements that are drawn last, over all the other elements; they are rendered using regular alpha blending, like the backdrops were</li> </ul>

Everything in the new system is rendered back-to-front, so first all backdrop items are drawn, then all screens, then all overlays, and finally all bezels. If more than one item of a given type is present, it is rendered in the order specified in the layout XML data.

Looking back at the example, you can see that a single item has been specified for our view, which is screen index 0 (this will be the first screen in the system). Within the item are some parameters that describe the bounds of the screen within the view. You'll notice that the width of the screen is 4 and the height is 3, this is a fairly arbitrary coordinate system. The layout system will read all the items described, and compute the outer bounds of all of the rectangles specified. It will then scale that to fit whatever screen you have configured. Thus, you can specify your coordinates in pixels or whatever is most convenient. The key here is that the screen as described is a standard 4:3 aspect ratio screen oriented horizontally.

Now, if you're familiar with the old artwork system, you may be scratching your head and thinking, why do we have to specify the aspect ratio of the screen? In the old system, the screen was always positioned from (0,0)-(1,1) and the aspect ratio of the screen (and the resulting artwork) was determined by flags in the game. This is true, and in retrospect, was a mistake. Not only did it make things confusing for positioning purposes, but it meant a lot of the artwork needed to be rotated and tweaked so that it stretched correctly. In addition, in the new world, there is nothing preventing you from having one screen rotated vertically and a second screen rotated horizontally, all within the same view (and yes, there is at least one dual monitor game that is set up that way).

The next obvious question is, so are we going to need files for all these layouts, even the standard ones? The answer is no. The layout system will load a number of layouts from different sources, and offer you the option of switching between all of the views specified by all of the interesting layouts. The search order is:

<ol>
<li>Explicitly specified files (on the command line)</li>
<li>gamename.lay</li>
<li>Game-specific built-in layouts</li>
<li>parentname.lay</li>
<li>Generic built-in layouts</li> </ol>

The key are the built-in layouts. First, each game can specify a built-in layout as a parameter to the new GAMEL macro, which mimics the existing GAME macro but takes a final parameter which a pointer to an embedded XML string that holds the game-specific built-in layouts.

Second, there are a number of built-in layouts. By default, each screen in the game gets a Standard layout, which is simply a single screen displayed at its appropriate aspect ratio. Each screen in the game also gets a Native layout, which is a single screen displayed 1:1 with the height/width ratio of the pixels. This produces, for example, widescreen Capcom games for those who still believe they should be widescreen.
Multi-screen games get a few additional options for displaying both screens at the same time, either on top of each other or side-by-side.
And finally, just for kicks, there is a "cocktail" layout that displays two copies of screen 0, one rotated 180 degrees for a pseudo-cocktail view. How is that done? With a layout something like this:

<code><?xml version="1.0"?>
<mamelayout version="2">
<view name="Cocktail">
<screen index="0">
<bounds left="-1.33333" top="0.0" right="0.0" bottom="1.0" />
</screen>
<screen index="0">
<bounds left="0.01" top="0.0" right="1.34333" bottom="1.0" />
<orientation rotate="180" />
</screen>
</view>
</mamelayout></code>

You'll notice a couple of interesting things here. The first is that you can repeat the same screen multiple times in a view. For fun, you could even create a "quad" view that displays the screen 4 times rotated in all four directions. The second is that you can specify an orientation for screens and actually for any item. This allows rotation and flipping of items, and even works with vector games or other special cases. Finally, you see how the coordinate system really is arbitrary. Here we're using 1.333 as the width of each screen and 1.0 as the height. This is the essentially the same as 4:3.

For completeness sake, here are all the attributes you can specify for items:

<code><bounds left="0" top="0" right="4" bottom="3" />
<bounds x="0" y="0" width="4" height="3" />
<color red="1.0" green="1.0" blue="1.0" alpha="0.5" />
<orientation rotate="90" swapxy="yes" flipx="yes" flipy="no" /></code>

You can control the bounds either by specifying left/top/right/bottom coordinates, or by specifying x/y/width/height coordinates. But only one or the other. The color tag lets you affect the overall color and alpha blending factors of the item. Each color value ranges from 0-1. And you can control orientation of the item via both a rotate parameter as well as through more primitive flipping and swapping controls.

Layouts and Rendering for MAME Artwork System

2008-06-24T13:49:09Z

Madskunk:

MAME 0.106u2 introduced a major change that needs a more detailed description, the concept of layouts and views.

As a simplistic explanation, layouts are the replacement for the artwork description files (.art) that were previously used to describe artwork to be displayed with a game. However, layouts are much more flexible and much more deeply integrated into the rendering system than the artwork files ever were. You literally can't run the new renderer without a layout loaded.

A layout consists of two parts: a list of zero or more elements, and a list of one or more views. The elements represent a sort of database of artwork pieces that can be assembled in various ways. The views represent the actual positioning of these elements relative to the game screens. The easiest way to understand this is to look at the simplest example, which is the default layout used for regular horizontal 4:3 games:

<code><?xml version="1.0"?>
<mamelayout version="2">
<view name="Standard">
<screen index="0">
<bounds left="0" top="0" right="4" bottom="3" />
</screen>
</view>
</mamelayout></code>

This particular layout has no elements described, and only a single view. The name of the view is "Standard." This is important because there is a new menu in the UI that lets you select on the fly which view to display, and this is the name that is displayed in that menu. Within the view, there can be a number of items:

<ul>
<li>backdrops specify the attributes of elements that are drawn first and which cover the background of the screen areas; they are rendered against each other using regular alpha blending, so they can have cut-out areas and other effects</li>
<li>screens specify the attributes of the various screens that make up a game; they are referenced by index, and are rendered on top of the backdrop layer using additive blending (alpha values applied to the source but not the destination)</li>
<li>overlays specify the attributes of elements that are drawn over top of the screens and backdrops; they are rendered on top of the screens and backdrops using RGB multiplicative blending (the RGB values of the overlays are multiplied by the RGB values of the destination)</li>
<li>bezels specify the attributes of elements that are drawn last, over all the other elements; they are rendered using regular alpha blending, like the backdrops were</li> </ul>

Everything in the new system is rendered back-to-front, so first all backdrop items are drawn, then all screens, then all overlays, and finally all bezels. If more than one item of a given type is present, it is rendered in the order specified in the layout XML data.

Looking back at the example, you can see that a single item has been specified for our view, which is screen index 0 (this will be the first screen in the system). Within the item are some parameters that describe the bounds of the screen within the view. You'll notice that the width of the screen is 4 and the height is 3, this is a fairly arbitrary coordinate system. The layout system will read all the items described, and compute the outer bounds of all of the rectangles specified. It will then scale that to fit whatever screen you have configured. Thus, you can specify your coordinates in pixels or whatever is most convenient. The key here is that the screen as described is a standard 4:3 aspect ratio screen oriented horizontally.

Now, if you're familiar with the old artwork system, you may be scratching your head and thinking, why do we have to specify the aspect ratio of the screen? In the old system, the screen was always positioned from (0,0)-(1,1) and the aspect ratio of the screen (and the resulting artwork) was determined by flags in the game. This is true, and in retrospect, was a mistake. Not only did it make things confusing for positioning purposes, but it meant a lot of the artwork needed to be rotated and tweaked so that it stretched correctly. In addition, in the new world, there is nothing preventing you from having one screen rotated vertically and a second screen rotated horizontally, all within the same view (and yes, there is at least one dual monitor game that is set up that way).

The next obvious question is, so are we going to need files for all these layouts, even the standard ones? The answer is no. The layout system will load a number of layouts from different sources, and offer you the option of switching between all of the views specified by all of the interesting layouts. The search order is:

<ol>
<li>Explicitly specified files (on the command line)</li>
<li>gamename.lay</li>
<li>Game-specific built-in layouts</li>
<li>parentname.lay</li>
<li>Generic built-in layouts</li> </ol>

The key are the built-in layouts. First, each game can specify a built-in layout as a parameter to the new GAMEL macro, which mimics the existing GAME macro but takes a final parameter which a pointer to an embedded XML string that holds the game-specific built-in layouts.

Second, there are a number of built-in layouts. By default, each screen in the game gets a Standard layout, which is simply a single screen displayed at its appropriate aspect ratio. Each screen in the game also gets a Native layout, which is a single screen displayed 1:1 with the height/width ratio of the pixels. This produces, for example, widescreen Capcom games for those who still believe they should be widescreen.
Multi-screen games get a few additional options for displaying both screens at the same time, either on top of each other or side-by-side.
And finally, just for kicks, there is a "cocktail" layout that displays two copies of screen 0, one rotated 180 degrees for a pseudo-cocktail view. How is that done? With a layout something like this:

<code><?xml version="1.0"?>
<mamelayout version="2">
<view name="Cocktail">
<screen index="0">
<bounds left="-1.33333" top="0.0" right="0.0" bottom="1.0" />
</screen>
<screen index="0">
<bounds left="0.01" top="0.0" right="1.34333" bottom="1.0" />
<orientation rotate="180" />
</screen>
</view>
</mamelayout></code>

You'll notice a couple of interesting things here. The first is that you can repeat the same screen multiple times in a view. For fun, you could even creat a "quad" view that displays the screen 4 times rotated in all four directions. The second is that you can specify an orientation for screens and actually for any item. This allows rotation and flipping of items, and even works with vector games or other special cases. Finally, you see how the coordinate system really is arbitrary. Here we're using 1.333 as the width of each screen and 1.0 as the height. This is the essentially the same as 4:3.

For completeness sake, here are all the attributes you can specify for items:

<code><bounds left="0" top="0" right="4" bottom="3" />
<bounds x="0" y="0" width="4" height="3" />
<color red="1.0" green="1.0" blue="1.0" alpha="0.5" />
<orientation rotate="90" swapxy="yes" flipx="yes" flipy="no" /></code>

You can control the bounds either by specifying left/top/right/bottom coordinates, or by specifying x/y/width/height coordinates. But only one or the other. The color tag lets you affect the overall color and alpha blending factors of the item. Each color value ranges from 0-1. And you can control orientation of the item via both a rotate parameter as well as through more primitive flipping and swapping controls.

Layouts and Rendering for MAME Artwork System

2008-06-24T13:29:42Z

Madskunk: New page: Today is when MAME 0.106u2 should <a href="http://mamedev.org/release.html">be available</a>. I'm sure there will be lots of questions as a result, but the one major change that needs some...

Today is when MAME 0.106u2 should <a
href="http://mamedev.org/release.html">be available</a>. I'm sure there will be lots of questions as a result, but the one major change that needs some more detailed description is the concept of layouts and views.

As a simplistic explanation, layouts are the replacement for the artwork description files (.art) that were previously used to describe artwork to be displayed with a game. However, layouts are much more flexible and much more deeply integrated into the rendering system than the artwork files ever were. You literally can't run the new renderer without a layout loaded.

A layout consists of two parts: a list of zero or more elements, and a list of one or more views. The elements represent a sort of database of artwork pieces that can be assembled in various ways. The views represent the actual positioning of these elements relative to the game screens. The easiest way to understand this is to look at the simplest example, which is the default layout used for regular horizontal 4:3
games:

<code><?xml version="1.0"?>
<mamelayout version="2">
    <view name="Standard">         <screen index="0">             
<bounds left="0" top="0" right="4" bottom="3" />         </screen>
    </view>
</mamelayout></code>

This particular layout has no elements described, and only a single view. The name of the view is "Standard." This is important because there is a new menu in the UI that lets you select on the fly which view to display, and this is the name that is displayed in that menu. Within the view, there can be a number of items:

<ul>
<li>backdrops specify the attributes of elements that are drawn first and which cover the background of the screen areas; they are rendered against each other using regular alpha blending, so they can have cut-out areas and other effects</li> <li>screens specify the attributes of the various screens that make up a game; they are referenced by index, and are rendered on top of the backdrop layer using additive blending (alpha values applied to the source but not the destination)</li> <li>overlays specify the attributes of elements that are drawn over top of the screens and backdrops; they are rendered on top of the screens and backdrops using RGB multiplicative blending (the RGB values of the overlays are multiplied by the RGB values of the destination)</li> <li>bezels specify the attributes of elements that are drawn last, over all the other elements; they are rendered using regular alpha blending, like the backdrops were</li> </ul>

Everything in the new system is rendered back-to-front, so first all backdrop items are drawn, then all screens, then all overlays, and finally all bezels. If more than one item of a given type is present, it is rendered in the order specified in the layout XML data.

So looking back at the example, you can see that we've specified a single item for our view, which is screen index 0 (this will be the first screen in the system). Within the item are some parameters that describe the bounds of the screen within the view. You'll notice that the width of the screen is 4 and the height is 3. What kind of coordinate system is this? Well, it's an arbitrary system, really. The layout system will read all the items described, and compute the outer bounds of all of the rectangles specified. It will then scale that to fit whatever screen you have configured. Thus, you can specify your coordinates in pixels or whatever is most convenient. The key here is that the screen as described is a standard 4:3 aspect ratio screen oriented horizontally.

Now, if you're familiar with the old artwork system, you may be scratching your head and thinking, why do we have to specify the aspect ratio of the screen? In the old system, the screen was always positioned from (0,0)-(1,1) and the aspect ratio of the screen (and the resulting
artwork) was determined by flags in the game. This is true. And in retrospect, it was a mistake. Not only did it make things confusing for positioning purposes, but it meant a lot of the artwork needed to be rotated and tweaked so that it stretched correctly. In addition, in the new world, there is nothing preventing you from having one screen rotated vertically and a second screen rotated horizontally, all within the same view (and yes, there is at least one dual monitor game that is set up that way).

The next obvious question is, so are we going to need files for all these layouts, even the standard ones? The answer is no. The layout system will load a number of layouts from different sources, and offer you the option of switching between all of the views specified by all of the interesting layouts. The search order is:

<ol>
<li>Explicitly specified files (on the command line)</li> <li>gamename.lay</li> <li>Game-specific built-in layouts</li> <li>parentname.lay</li> <li>Generic built-in layouts</li> </ol>

The key are the built-in layouts. First, each game can specify a built-in layout as a parameter to the new GAMEL macro, which mimics the existing GAME macro but takes a final parameter which a pointer to an embedded XML string that holds the game-specific built-in layouts.

Second, there are a number of built-in layouts. By default, each screen in the game gets a Standard layout, which is simply a single screen displayed at its appropriate aspect ratio. Each screen in the game also gets a Native layout, which is a single screen displayed 1:1 with the height/width ratio of the pixels. This produces, for example, widescreen Capcom games for those who still believe they should be widescreen.
Multi-screen games get a few additional options for displaying both screens at the same time, either on top of each other or side-by-side.
And finally, just for kicks, there is a "cocktail" layout that displays two copies of screen 0, one rotated 180 degrees for a pseudo-cocktail view. How is that done? With a layout something like this:

<code><?xml version="1.0"?>
<mamelayout version="2">
    <view name="Cocktail">         <screen index="0">             
<bounds left="-1.33333" top="0.0" right="0.0" bottom="1.0" />         </screen>
        <screen index="0">             
<bounds left="0.01" top="0.0" right="1.34333" bottom="1.0" />             
<orientation rotate="180" />
        </screen>
    </view>
</mamelayout></code>

You'll notice a couple of interesting things here. First is, you can repeat the same screen multiple times in a view if you'd like. For fun, I've even created a "quad" view that displays the screen 4 times rotated all four directions. Second is that you can specify an orientation for screens and actually for any item. This allows rotation and flipping of items, and even works with vector games or other special cases. Finally, you see how the coordinate system really is arbitrary. Here I'm using
1.333 as the width of each screen and 1.0 as the height. This is the same as 4:3. Really. :)

For completeness sake, here are all the attributes you can specify for
items:

<code><bounds left="0" top="0" right="4" bottom="3" /> <bounds x="0" y="0" width="4" height="3" /> <color red="1.0" green="1.0" blue="1.0" alpha="0.5" /> <orientation rotate="90" swapxy="yes" flipx="yes" flipy="no"
/></code>

You can control the bounds either by specifying left/top/right/bottom coordinates, or by specifying x/y/width/height coordinates. But only one or the other. The color tag lets you affect the overall color and alpha blending factors of the item. Each color value ranges from 0-1. And you can control orientation of the item via both a rotate parameter as well as through more primitive flipping and swapping controls.

Well, that seems like enough for a single article. I'll talk about elements and artwork and how they work in the next article.

How MAME Works

2008-06-24T13:29:24Z

Madskunk: /* Core Internals */

The following is a list of documents describing the internal workings (core) of the MAME emulator. Most are penned by Aaron Giles.

== Building MAME ==
* [[Building MAME using Microsoft Visual Studio compilers]]

== Writing for MAME ==
* [[MAME Coding Conventions]]

== For Driver Writers ==
* [[Resource Management in MAME]]
* [[DIP Switches in MAME]]
* [[MAME Interrupt Function Review]]
* [[Using MAME's tilemap system]]
* [http://aarongiles.com/?p=159 Programmable Logic Devices in MAME]
* [[CPUs and Address Spaces]]
* [[Address Maps]]

== Core Internals ==
* [http://aarongiles.com/?p=137 CPU Scheduling in MAME]
* [http://aarongiles.com/?p=74 Filters and streams in the MAME Sound System]
* [http://aarongiles.com/?p=149 Save State Fundamentals]
* [[Using the GFX/TileMap viewer (F4)]]
* [http://aarongiles.com/?p=182 How To Use the 'New' Renderer]
* [[Layouts and Rendering for MAME Artwork System]]
* [[LAY File Basics - Part I]]

== Universal Dynamic Recompiler ==
* [[Core Concepts]]
* [[UML Architecture]]
** [[UML Control Flow Opcodes]]
** [[UML Internal Register Opcodes]]
** [[UML Integer Opcodes]]
** [[UML Floating Point Opcodes]]
* [[Dynamic Recompiler Author's Guide]]
* [[Back-End Author's Guide]]

== Tips & Tricks ==
* [[Executing Code Out of a Memory Region With a Read Handler]]
* [[Checklist for Cleaning Up Drivers]]
* [[Writing Messages to the Screen In a MAME Driver]]

Writing Messages to the Screen in a MAME Driver

2008-06-24T13:27:15Z

Madskunk: Changes to remove references to 'I'

One of the side-effects of the new video system is that drivers aren't allowed to write to the UI layer directly. They can call <code>popmessage()</code> to display a popup at the bottom of the screen, but that's about it in the new system. The problem is that a few drivers were displaying important game-related information using the UI font. Specifically, Atari Football was using it to show which plays had been selected, and the Exidy Max-a-Flex system was using it to draw the status of the lamps and timer. In retrospect, it is actually good that these cases broke because the way it was being done before was a big hack. For one thing, it meant that the game screen area was artificially increased to make room for the text. And second, the state of these lamps was not being properly exposed to the outside world (or in the case of Football, it was being changed via the rendering system in addition to being displayed on screen).

Ideally, the state of these indicators should be made visible via the rendering system. This is great, except that in the absence of an external artwork file, there would be no visible indication at all. This is one of the reasons why it's good to have built-in layouts in the MAME code -- even if they are crude approximations of the original artwork, they at least can reflect important functional information. The problem is, built-in layouts can't really reference image files. All they can do is draw rectangles and disks, which is sufficient for basic overlays on top of old black & white games, but isn't really enough to provide textual information.

In order to solve this problem, a couple of new primitives have been added to the layouts. In addition to rect and disk primitives, the two new primitives are: text and led7seg.

The text primitive lets you add text anywhere within the artwork area. You can specify color and bounds just like the other primitives. The text is drawn using the built-in fixed-width MAME font (even if you have a different UI font), and is centered within the bounds. If there is too much text to fit in the area provided, the font will be squashed horizontally to fit. Here's an example that positions the text "GAME OVER" in red centered within the given rectangle:

<code><text string="GAME OVER">
<bounds x="0" y="0" height="10" width="200" />
<color red="1.0" green="0.0" blue="0.0" />
</text></code>

The led7seg primitive lets you position a standard 7-segment LED somewhere in the artwork. The LEDs are drawn in a high resolution and oversampled down so they look nice. Typically these are used to specify a digit from 0-9, Turbo is one example. To use this, you would typically create an element with multiple states, each state reflecting the corresponding digit. Here's an example that positions a red LED with the number "2" that is only visible with the containing element is in state "2":

<code><led7seg pattern="10111010" state="2">
<color red="1.0" green="0.0" blue="0.0" />
</led7seg></code>

The pattern attribute specifies which of the segments is visible. A 1 means "on", and a 0 means "off". They are specified in the following order:

<ol>
<li>Top horizontal segment</li>
<li>Upper left vertical segment</li>
<li>Upper right vertical segment</li>
<li>Middle horizontal segment</li>
<li>Lower left vertical segment</li>
<li>Lower right vertical segment</li>
<li>Bottom horizontal segment</li>
<li>Decimal point</li>
</ol>

Using these two new primitives, built-in layouts have been created for the Atari sports games (Football and Baseball), the Sega Z80 scaling games (Turbo, Subroc 3D, Buck Rogers), Taito's Super Speed Race, and the Exidy Max-a-Flex system that display all the essential lamps and score/timing information. Of course, you can continue to use the externally-provided artwork for a better visual appearance, but now it's possible to provide vital lamps and LEDs via the new built-in layouts without affecting the core game screen or abusing the UI system.

Checklist for Cleaning Up Drivers

2008-06-24T13:23:47Z

Madskunk:

Over the past year(s), Aaron has done some driver "cleanup" work. This generally involves picking apart a driver, revisiting all the assumptions using whatever information is available, and updating it to take advantage of newer features in MAME that have been introduced since it was first written. To do this work, Aaron keeps a checklist of things to do, just to make sure all bases are covered. This list is constantly updated, but since it is a good set of guidelines for updating a driver, or writing a new one from scratch, it is provided here.

Timing/interrupts:
<ul><li>all crystals on the PCB documented via #defines</li>
<li>all CPU and sound clocks derived from #defined crystal values</li>
<li>re-verify interrupt generation timing and sources</li> <li>implement interrupt acknowledges (many older drivers didn't bother)</li>
<li>add accurate watchdog durations</li> </ul>

Memory:
<ul><li>unified read/write memory maps (they used to be separate)</li>
<li>map the entire address space fully, if possible from schematics</li>
<li>use AM_SHARE where appropriate (better than sharedram read/write handlers)</li> <li>convert memory banking to the new system (memory_configure_bank)</li> </ul>

Graphics:
<ul><li>gfx layouts should use RGN_FRAC wherever possible instead of hard-coded values</li>
<li>gfx layouts that are common should be shared (vidhrdw/generic.c)</li>
<li>accurate hblank/vblank/visible areas, derived from schematics if possible</li>
<li>convert from old macros to new screen macros for display info</li>
<li>use new more accurate screen timing routines for H/V positions</li>
<li>convert to tilemaps, if applicable</li>
<li>change to use resistors for palette generation</li>
<li>add limits on sprite drawing (e.g., how many per scanline), if known</li> </ul>

Inputs:
<ul><li>tag all input ports</li>
<li>change all port references in code to use tags</li>
<li>convert non-DIP configurations to configs</li>
<li>use PORT_CUSTOM where appropriate instead of memory overrides</li>
<li>connect coin counters (often missing)</li>
<li>connect PCB outputs via the new output system</li>
<li>add DIPLOCATIONS</li>
<li>verify DIPs and inputs</li> </ul>

ROMs:
<ul><li>memory regions reduced to minimum size (they don't have to cover the whole address space)</li>
<li>make sure ROM names are good and accurate to what we know</li>
<li>check for any unemulated clones</li> </ul>

General:
<ul><li>update source files to be in order: header, includes, constants, typedefs, macros, globals, inlines, code</li>
<li>update driver file to be in the same order, followed by: address maps, input ports, graphics definitions, sound configs, machine driver, ROMs, driver init code, drivers</li>
<li>add save state support</li>
<li>move all globals to hang off of driver_data</li>
<li>de-obfuscate the code where it is confusing</li> </ul>

Some recent driver updates that are pretty up to date include: <code>ccastles.c, cloud9.c, missile.c, turbo.c, zaxxon.c.</code>

Checklist for Cleaning Up Drivers

2008-06-24T13:15:34Z

Madskunk: New page: Over the past year, I've done some driver "cleanup" work. This generally involves picking apart a driver, revisiting all the assumptions using whatever information is available, and updati...

Over the past year, I've done some driver "cleanup" work. This generally involves picking apart a driver, revisiting all the assumptions using whatever information is available, and updating it to take advantage of newer features in MAME that have been introduced since it was first written. To do this work, I keep a checklist of things to do, just to make sure I've covered all the bases. This list is constantly updated, but I figured I would share it, since it is a good set of guidelines when updating a driver or writing a new one from scratch.

Timing/interrupts:
<ul>
<li>all crystals on the PCB documented via #defines</li> <li>all CPU and sound clocks derived from #defined crystal values</li> <li>re-verify interrupt generation timing and sources</li> <li>implement interrupt acknowledges (many older drivers didn't bother)</li> <li>add accurate watchdog durations</li> </ul>

Memory:
<ul>
<li>unified read/write memory maps (they used to be separate)</li> <li>map the entire address space fully, if possible from schematics</li> <li>use AM_SHARE where appropriate (better than sharedram read/write handlers)</li> <li>convert memory banking to the new system (memory_configure_bank)</li> </ul>

Graphics:
<ul>
<li>gfx layouts should use RGN_FRAC wherever possible instead of hard-coded values</li> <li>gfx layouts that are common should be shared (vidhrdw/generic.c)</li> <li>accurate hblank/vblank/visible areas, derived from schematics if possible</li> <li>convert from old macros to new screen macros for display info</li> <li>use new more accurate screen timing routines for H/V positions</li> <li>convert to tilemaps, if applicable</li> <li>change to use resistors for palette generation</li> <li>add limits on sprite drawing (i.e., how many per scanline) if known</li> </ul>

Inputs:
<ul>
<li>tag all input ports</li>
<li>change all port references in code to use tags</li> <li>convert non-DIP configurations to configs</li> <li>use PORT_CUSTOM where appropriate instead of memory overrides</li> <li>connect coin counters (often missing)</li> <li>connect PCB outputs via the new output system</li> <li>add DIPLOCATIONS</li> <li>verify DIPs and inputs</li> </ul>

ROMs:
<ul>
<li>memory regions reduced to minimum size (they don't have to cover the whole address space)</li> <li>make sure ROM names are good and accurate to what we know</li> <li>check for any unemulated clones</li> </ul>

General:
<ul>
<li>update source files to be in order: header, includes, constants, typedefs, macros, globals, inlines, code</li> <li>update driver file to be in the same order, followed by: address maps, input ports, graphics definitions, sound configs, machine driver, ROMs, driver init code, drivers</li> <li>add save state support</li> <li>move all globals to hang off of driver_data</li> <li>de-obfuscate the code where it is confusing</li> </ul>

Actually, that's quite a lot of stuff. I'm sure I've missed a thing or two in some of my recent driver updates, but some examples that are pretty up to date include: ccastles.c, cloud9.c, missile.c, turbo.c, zaxxon.c.

How MAME Works

2008-06-24T13:15:31Z

Madskunk: /* Tips & Tricks */

The following is a list of documents describing the internal workings (core) of the MAME emulator. Most are penned by Aaron Giles.

== Building MAME ==
* [[Building MAME using Microsoft Visual Studio compilers]]

== Writing for MAME ==
* [[MAME Coding Conventions]]

== For Driver Writers ==
* [[Resource Management in MAME]]
* [[DIP Switches in MAME]]
* [[MAME Interrupt Function Review]]
* [[Using MAME's tilemap system]]
* [http://aarongiles.com/?p=159 Programmable Logic Devices in MAME]
* [[CPUs and Address Spaces]]
* [[Address Maps]]

== Core Internals ==
* [http://aarongiles.com/?p=137 CPU Scheduling in MAME]
* [http://aarongiles.com/?p=74 Filters and streams in the MAME Sound System]
* [http://aarongiles.com/?p=149 Save State Fundamentals]
* [[Using the GFX/TileMap viewer (F4)]]
* [http://aarongiles.com/?p=182 How To Use the 'New' Renderer]
* [http://aarongiles.com/?p=161 Layouts and Rendering for MAME Artwork System]
* [[LAY File Basics - Part I]]

== Universal Dynamic Recompiler ==
* [[Core Concepts]]
* [[UML Architecture]]
** [[UML Control Flow Opcodes]]
** [[UML Internal Register Opcodes]]
** [[UML Integer Opcodes]]
** [[UML Floating Point Opcodes]]
* [[Dynamic Recompiler Author's Guide]]
* [[Back-End Author's Guide]]

== Tips & Tricks ==
* [[Executing Code Out of a Memory Region With a Read Handler]]
* [[Checklist for Cleaning Up Drivers]]
* [[Writing Messages to the Screen In a MAME Driver]]

Writing Messages to the Screen in a MAME Driver

2008-06-24T13:11:38Z

Madskunk: Writing Messages to the Screen In a MAME Driver moved to Writing Messages to the Screen in a MAME Driver: Wrong capitalisation

One of the side-effects of the new video system is that drivers aren't allowed to write to the UI layer directly. They can call <code>popmessage()</code> to display a popup at the bottom of the screen, but that's about it in the new system. The problem is that a few drivers were displaying important game-related information using the UI font. Specifically, Atari Football was using it to show which plays had been selected, and the Exidy Max-a-Flex system was using it to draw the status of the lamps and timer. In retrospect, it is actually good that these cases broke because the way it was being done before was a big hack. For one thing, it meant that the game screen area was artificially increased to make room for the text. And second, the state of these lamps was not being properly exposed to the outside world (or in the case of Football, it was being changed via the rendering system in addition to being displayed on screen).

Ideally, the state of these indicators should be made visible via the rendering system. This is great, except that in the absence of an external artwork file, there would be no visible indication at all. This is one of the reasons why it's good to have built-in layouts in the MAME code -- even if they are crude approximations of the original artwork, they at least can reflect important functional information. The problem is, built-in layouts can't really reference image files. All they can do is draw rectangles and disks, which is sufficient for basic overlays on top of old black & white games, but isn't really enough to provide textual information.

In order to solve this problem, I've added a couple of new primitives to the layouts. In addition to rect and disk primitives, there are two new primitives: text and led7seg.

The text primitive lets you add text anywhere within the artwork area.
You can specify color and bounds just like the other primitives. The text is drawn using the built-in fixed-width MAME font (even if you have a different UI font), and is centered within the bounds. If there is too much text to fit in the area provided, the font will be squashed horizontally to fit. Here's an example that positions the text "GAME OVER" in red centered within the given rectangle:

<code><text string="GAME OVER">
<bounds x="0" y="0" height="10" width="200" />
<color red="1.0" green="0.0" blue="0.0" />
</text></code>

The led7seg primitive lets you position a standard 7-segment LED somewhere in the artwork. The LEDs are drawn in a high resolution and oversampled down so they look nice. Typically these are used to specify a digit from 0-9, Turbo is one example. To use this, you would typically create an element with multiple states, each state reflecting the corresponding digit. Here's an example that positions a red LED with the number "2" that is only visible with the containing element is in state "2":

<code><led7seg pattern="10111010" state="2">
<color red="1.0" green="0.0" blue="0.0" />
</led7seg></code>

The pattern attribute specifies which of the segments is visible. A 1 means "on", and a 0 means "off". They are specified in the following order:

<ol>
<li>Top horizontal segment</li>
<li>Upper left vertical segment</li>
<li>Upper right vertical segment</li>
<li>Middle horizontal segment</li>
<li>Lower left vertical segment</li>
<li>Lower right vertical segment</li>
<li>Bottom horizontal segment</li>
<li>Decimal point</li>
</ol>

Using these two new primitives, I've created built-in layouts for the Atari sports games (Football and Baseball), the Sega Z80 scaling games (Turbo, Subroc 3D, Buck Rogers), Taito's Super Speed Race, and the Exidy Max-a-Flex system that display all the essential lamps and score/timing information. Of course, you can continue to use the externally-provided artwork for a better visual appearance, but now it's possible to provide vital lamps and LEDs via the new built-in layouts without affecting the core game screen or abusing the UI system.

Writing Messages to the Screen in a MAME Driver

2008-06-24T13:10:32Z

Madskunk:

One of the side-effects of the new video system is that drivers aren't allowed to write to the UI layer directly. They can call <code>popmessage()</code> to display a popup at the bottom of the screen, but that's about it in the new system. The problem is that a few drivers were displaying important game-related information using the UI font. Specifically, Atari Football was using it to show which plays had been selected, and the Exidy Max-a-Flex system was using it to draw the status of the lamps and timer. In retrospect, it is actually good that these cases broke because the way it was being done before was a big hack. For one thing, it meant that the game screen area was artificially increased to make room for the text. And second, the state of these lamps was not being properly exposed to the outside world (or in the case of Football, it was being changed via the rendering system in addition to being displayed on screen).

Ideally, the state of these indicators should be made visible via the rendering system. This is great, except that in the absence of an external artwork file, there would be no visible indication at all. This is one of the reasons why it's good to have built-in layouts in the MAME code -- even if they are crude approximations of the original artwork, they at least can reflect important functional information. The problem is, built-in layouts can't really reference image files. All they can do is draw rectangles and disks, which is sufficient for basic overlays on top of old black & white games, but isn't really enough to provide textual information.

In order to solve this problem, I've added a couple of new primitives to the layouts. In addition to rect and disk primitives, there are two new primitives: text and led7seg.

The text primitive lets you add text anywhere within the artwork area.
You can specify color and bounds just like the other primitives. The text is drawn using the built-in fixed-width MAME font (even if you have a different UI font), and is centered within the bounds. If there is too much text to fit in the area provided, the font will be squashed horizontally to fit. Here's an example that positions the text "GAME OVER" in red centered within the given rectangle:

<code><text string="GAME OVER">
<bounds x="0" y="0" height="10" width="200" />
<color red="1.0" green="0.0" blue="0.0" />
</text></code>

The led7seg primitive lets you position a standard 7-segment LED somewhere in the artwork. The LEDs are drawn in a high resolution and oversampled down so they look nice. Typically these are used to specify a digit from 0-9, Turbo is one example. To use this, you would typically create an element with multiple states, each state reflecting the corresponding digit. Here's an example that positions a red LED with the number "2" that is only visible with the containing element is in state "2":

<code><led7seg pattern="10111010" state="2">
<color red="1.0" green="0.0" blue="0.0" />
</led7seg></code>

The pattern attribute specifies which of the segments is visible. A 1 means "on", and a 0 means "off". They are specified in the following order:

<ol>
<li>Top horizontal segment</li>
<li>Upper left vertical segment</li>
<li>Upper right vertical segment</li>
<li>Middle horizontal segment</li>
<li>Lower left vertical segment</li>
<li>Lower right vertical segment</li>
<li>Bottom horizontal segment</li>
<li>Decimal point</li>
</ol>

Using these two new primitives, I've created built-in layouts for the Atari sports games (Football and Baseball), the Sega Z80 scaling games (Turbo, Subroc 3D, Buck Rogers), Taito's Super Speed Race, and the Exidy Max-a-Flex system that display all the essential lamps and score/timing information. Of course, you can continue to use the externally-provided artwork for a better visual appearance, but now it's possible to provide vital lamps and LEDs via the new built-in layouts without affecting the core game screen or abusing the UI system.

How MAME Works

2008-06-24T12:52:39Z

Madskunk: /* Tips & Tricks */

The following is a list of documents describing the internal workings (core) of the MAME emulator. Most are penned by Aaron Giles.

== Building MAME ==
* [[Building MAME using Microsoft Visual Studio compilers]]

== Writing for MAME ==
* [[MAME Coding Conventions]]

== For Driver Writers ==
* [[Resource Management in MAME]]
* [[DIP Switches in MAME]]
* [[MAME Interrupt Function Review]]
* [[Using MAME's tilemap system]]
* [http://aarongiles.com/?p=159 Programmable Logic Devices in MAME]
* [[CPUs and Address Spaces]]
* [[Address Maps]]

== Core Internals ==
* [http://aarongiles.com/?p=137 CPU Scheduling in MAME]
* [http://aarongiles.com/?p=74 Filters and streams in the MAME Sound System]
* [http://aarongiles.com/?p=149 Save State Fundamentals]
* [[Using the GFX/TileMap viewer (F4)]]
* [http://aarongiles.com/?p=182 How To Use the 'New' Renderer]
* [http://aarongiles.com/?p=161 Layouts and Rendering for MAME Artwork System]
* [[LAY File Basics - Part I]]

== Universal Dynamic Recompiler ==
* [[Core Concepts]]
* [[UML Architecture]]
** [[UML Control Flow Opcodes]]
** [[UML Internal Register Opcodes]]
** [[UML Integer Opcodes]]
** [[UML Floating Point Opcodes]]
* [[Dynamic Recompiler Author's Guide]]
* [[Back-End Author's Guide]]

== Tips & Tricks ==
* [[Executing Code Out of a Memory Region With a Read Handler]]
* [http://aarongiles.com/?p=195 Checklist for Cleaning Up Drivers]
* [[Writing Messages to the Screen In a MAME Driver]]

Writing Messages to the Screen in a MAME Driver

2008-06-24T12:51:56Z

Madskunk: New page: One of the side-effects of the new video system is that drivers aren't allowed to write to the UI layer directly. They can call popmessage() to display a popup at the bottom of the screen,...

One of the side-effects of the new video system is that drivers aren't allowed to write to the UI layer directly. They can call popmessage() to display a popup at the bottom of the screen, but that's about it in the new system. The problem is that a few drivers were displaying important game-related information using the UI font. Specifically, Atari Football was using it to show which plays had been selected, and the Exidy Max-a-Flex system was using it to draw the status of the lamps and timer. It retrospect, it is actually good that these cases broke because the way it was being done before was a big hack. For one thing, it meant that the game screen area was artificially increased to make room for the text. And second, the state of these lamps was not being properly exposed to the outside world (or in the case of Football, it was being changed via the rendering system in addition to being displayed on screen).

Ideally, the state of these indicators should be made visible via the rendering system. This is great, except that in the absence of an external artwork file, there would be no visible indication at all. This is one of the reasons why it's good to have built-in layouts in the MAME code -- even if they are crude approximations of the original artwork, they at least can reflect important functional information. The problem is, built-in layouts can't really reference image files. All they can do is draw rectangles and disks, which is sufficient for basic overlays on top of old black & white games, but isn't really enough to provide textual information.

In order to solve this problem, I've added a couple of new primitives to the layouts. In addition to rect and disk primitives, there are two new
primitives: text and led7seg.


The text primitive lets you add text anywhere within the artwork area.
You can specify color and bounds just like the other primitives. The text is drawn using the built-in fixed-width MAME font (even if you have a different UI font), and is centered within the bounds. If there is too much text to fit in the area provided, the font will be squashed horizontally to fit. Here's an example that positions the text "GAME OVER" in red centered within the given rectangle:
<code>
<text string="GAME OVER">
    <bounds x="0" y="0" height="10" width="200"
/>
    <color red="1.0" green="0.0" blue="0.0" /> </text> </code>

The led7seg primitive lets you position a standard 7-segment LED somewhere in the artwork. The LEDs are drawn a high resolution and oversampled down so they look nice. Typically these are used to specify a digit from 0-9. Turbo is one example. To use this, you would typically create an element with multiple states, each state reflecting the corresponding digit. Here's an example that positions a red LED with the number "2" that is only visible with the containing element is in state
"2":
<code>
<led7seg pattern="10111010" state="2">     <color red="1.0" green="0.0" blue="0.0" /> </text> </code>

The pattern attribute specifies which of the segments is visible. A 1 means "on", and a 0 means "off". They are specified in the following
order:

<ol>
<li>Top horizontal segment</li>
<li>Upper left vertical segment</li>
<li>Upper right vertical segment</li>
<li>Middle horizontal segment</li>
<li>Lower left vertical segment</li>
<li>Lower right vertical segment</li>
<li>Bottom horizontal segment</li>
<li>Decimal point</li>
</ol>

Using these two new primitives, I've created built-in layouts for the Atari sports games (Football and Baseball), the Sega Z80 scaling games (Turbo, Subroc 3D, Buck Rogers), Taito's Super Speed Race, and the Exidy Max-a-Flex system that display all the essential lamps and score/timing information. Of course, you can continue to use the externally-provided artwork for a better visual appearance, but now it's possible to provide vital lamps and LEDs via the new built-in layouts without affecting the core game screen or abusing the UI system.

Tomorrow I'll write about the second big change coming, which is related to the issue of lamps and other signals output from the arcade PCBs.