MAMEDEV Wiki - User contributions [en-gb]

MAME Device Basics

2012-09-12T18:35:13Z

Aaron: /* Overview */

=Overview=

In MAME, a device is a mechanism for encapsulating behavior. While it is common to associate a device (in the MAME sense) with a physical device (in the real world), there does not necessarily need to be a 1:1 correspondance between the two.

Devices are important because they provide clean hooks into the MAME system. They are notified when key things in the system change, they encode their own configuration information, keep their own state, and can be instantiated multiple times within a given machine. They are easily located via a simple string tag, and are first-class citizens in memory maps, so they are easily read from and written to.

Devices are implemented using a collection of C++ classes. In order to provide the flexibility necessary to describe the sorts of devices in MAME, the device model relies heavily on the ''multiple inheritance'' feature of C++ to extend devices with one or more ''device interfaces''.

=Core Concepts=

Every device in the project is built up out of two classes: a device-specific ''configuration class'' (derived from the '''device_config''' class) and a device-specific ''runtime class'' (derived from the '''device_t''' class).

The configuration class is responsible for encapsulating the device's configuration. The base '''device_config''' class automatically supports several core configuration properties, such as a short string ''tag'' to identify the device instance, a ''clock'' value which represents the input clock to the device, and an ''owner'' who serves as the device's parent. All device-specific configuration classes must be derived from the '''device_config''' class at their root.

Of course, most devices require more configuration than this, and so there are mechanisms for the device-specific configuration class to accept further configuration information, both inline in the MACHINE_CONFIG description, as well as externally in a static structure. This additional configuration data is stored in the device-specific class. More details on how this works come later in this article.

In addition to holding the configuration of a device, the device-specific configuration class also serves as a "factory" class that provides a mechanism for the MAME core to instantiate both new configuration objects, via a static method, and new runtime objects, via a required virtual method. (It is worth noting that the pointer to the static method that constructs configuration objects also serves as the device "type", which is a unique single entry point into the device.)

The runtime class, as its name implies, holds the runtime state of a device. The base '''device_t''' class provides a number of basic device concepts, including device initialization, reset, hooks into the save state system, clock scaling. It also holds a reference back to the corresponding '''device_config''' that begat the device.

The device-specific runtime class, which is required to derive from '''device_t''', then contains all the runtime state of the device, along with methods to operate upon the live device. It can also override several internal methods of its parent class to gain access to hooks that are called during specific events in the machine's lifecycle.

=Lifecycle of a Device=

This section aims to describe the two core device classes and how they are used by the system.

==Configuration==

Machine configurations in MAME are represented by a tokenizing mechanism wrapped by macros. A typical machine driver looks something like this (having removed some of the irrelevant details):

static MACHINE_DRIVER_START( pacman )
MDRV_CPU_ADD("maincpu", Z80, MASTER_CLOCK/6)
MDRV_CPU_PROGRAM_MAP(pacman_map)
...
MDRV_SCREEN_ADD("screen", RASTER)
MDRV_SCREEN_FORMAT(BITMAP_FORMAT_INDEXED16)
...
MDRV_SOUND_ADD("namco", NAMCO, MASTER_CLOCK/6/32)
MDRV_SOUND_CONFIG(namco_config)
MDRV_SOUND_ROUTE(ALL_OUTPUTS, "mono", 1.0)
MACHINE_DRIVER_END

When the compiler processes this, the MDRV_* macros all map down to a set of 32-bit or 64-bit integral tokens which are stored as a stream for later processing.

It may not be immediately obvious, but the machine configuration above defines three separate devices: a CPU device called "maincpu", a video screen device called "screen", and a Namco sound device called "namco". Each device generally defines its own MDRV_*_ADD() macro which permits some flexibility in how each device is added. The MDRV_* macros that follow each device provide configuration information. More on configuration in a later chapter.

When a machine configuration is instantiated, it first takes the token stream and executes it, creating a device configuration whenever it sees an MCONFIG_TOKEN_DEVICE_ADD token (which is output by the MDRV_*_ADD() macro mentioned above), and populating the device configuration with data from subsequent macros.

One of the parameters to MCONFIG_TOKEN_DEVICE_ADD is a device type. In MAME a device type is a static function pointer which serves as the factory function for allocating a device configuration. So when we need to add a device, we simply call the factory function and ask it to allocate for us a new device configuration of the appropriate type.

Once the configuration is allocated, we continue to process tokens. Tokens within a certain well-defined range are known to be device configuration tokens, and these are handed off to the allocated device configuration for processing. Specific devices can also support their own custom-defined tokens if they need special behaviors (the MDRV_SOUND_ROUTE above does this) by overriding the '''device_process_token'''() method in the device-specific configuration class.

Upon encountering the end of the token stream, all the devices are notified that the configuration parsing is complete. This allows them to consolidate any configuration information or do any other work that needs to be done. Device-specific configuration classes can override the '''device_config_complete'''() method to hook into this event.

There are several situations in which the machine configuration and all the device configurations are created: to perform validity checks on all the drivers; to output information needed by the -listxml and other front-end functions; to check for vector screens when parsing .ini files; and finally, in preparation for starting an actual game. In all cases but the last one, the machine and device configurations are created and discarded without ever creating any runtime devices, so the device lifecycle can very well begin and end with the device configuration.

In the case where validity checks are performed, the device-specific configuration class has the option of performing its own validation by overriding the '''device_validity_check'''() method and outputting errors if any are found. For this reason, validation should happen here rather than in the '''device_config_complete'''(), so that errors can be reported in a consistent manner.

==Runtime==

When the time comes to create a running machine object and start up the devices, MAME will take the device list contained in the machine configuration and rip through it to allocate the runtime devices. The mechanism for allocating a runtime device is to call the device-specific configuration class's '''device_alloc'''() method, whose job is simply to auto_alloc an instance of the device-specific runtime class. This method is a required override.

Once the entire set of devices has been allocated, MAME will once again run through the list of devices one by one and request them to start. If a device has device-specific work to do at startup (such as allocating memory or consuming configuration information), it can override the '''device_start'''() method to do so. If a device has a dependency upon another device being started, and that other device isn't ready yet, you can throw a '''device_missing_dependencies''' exception from within the '''device_start''' function and you will be re-queued to the end of the initialization order.

An important thing to note is the explicit separation between allocation and startup. All the devices are allocated first, and then all of them are started. The intention is that most of the hard work is done at start time, leaving the class constructor mostly the job of ensuring all local variables are initialized to sane values.

After the devices are all allocated and started, MAME makes one more pass through them all to reset them. As with startup, a device-specific class can override the '''device_reset'''() method to hook into this notification. Unlike startup, which occurs exactly once, a reset may happen multiple times throughout a device's existence. In addition to the first call at startup, all devices are also implicitly reset when a soft or hard reset is performed by the user, or when a driver explicitly calls the device's '''reset'''() method.

Finally, when the emulation is complete, all the devices are destructed. Note that there is no separation between stopping and destruction, as there is between starting and allocation. This means that your device's destructor is responsible for cleaning up any allocations or other side-effects created during the device's lifetime, excepting those allocated via the '''auto_alloc''' macros, which are automatically destroyed shortly afterwards.

In addition to these basic interfaces, there are several other key times when a device is notified. Device-specific hooks are provided for each of these situations, so a simple override is all that is needed to react:

* Prior to saving the state of the system, all the devices are notified. This takes the place of registering handlers via '''state_save_register_presave'''() as was done previously. To hook this, simple override the '''device_pre_save'''() method.

* Similarly, immediately after loading a saved state, all devices are notified. Device-specific classes hook this via the '''device_post_load'''() method.

* If the emulation is started with the debugger enabled, there is a hook '''device_debug_setup'''() which is called to allow device-specific classes to register additional functions or other information with the debugger.

* Finally, if the clock of a device is changed, a notification is sent via the '''device_clock_changed'''() method. This is necessary because most clock management is handled generically in the base '''device_t''' class.

=Configuring Devices=

Device configuration comes in two flavors, static configuration and inline configuration. The decision as to which to use is fairly arbitrary -- and in fact both can be used at the same time! The example from the Lifecycle of a Device chapter demonstrates the use of both types of configuration:

static MACHINE_DRIVER_START( pacman )
MDRV_CPU_ADD("maincpu", Z80, MASTER_CLOCK/6)
MDRV_CPU_PROGRAM_MAP(pacman_map) // inline configuration
...
MDRV_SCREEN_ADD("screen", RASTER)
MDRV_SCREEN_FORMAT(BITMAP_FORMAT_INDEXED16) // inline configuration
...
MDRV_SOUND_ADD("namco", NAMCO, MASTER_CLOCK/6/32)
MDRV_SOUND_CONFIG(namco_config) // static configuration
MDRV_SOUND_ROUTE(ALL_OUTPUTS, "mono", 1.0) // AND inline configuration
MACHINE_DRIVER_END

Let's start by examining how static configuration work, as they are the simplest to understand. A static configuration is simply a single pointer to a constant structure, defined by the game driver, and expressed via the token stream as an MCONFIG_TOKEN_DEVICE_CONFIG token, followed by a pointer to the structure.

Within a machine driver configuration, a static configuration is specified by a MDRV_DEVICE_CONFIG() macro. Certain devices and device types might also provide aliases to this, like the MDRV_SOUND_CONFIG() macro above. If you look at the pacman.c driver, you'll see the configuration structure:

static const namco_interface namco_config =
{
3, /* number of voices */
0 /* stereo */
};

When a driver specifies a static configuration, the pointer is extracted from the token stream and deposited into the void pointer '''m_static_config''', stored by the '''device_config''' base class. The driver-specific configuration class can then consume this pointer when its '''device_config_complete'''() method is called, or it can leave it around for the device itself to consume when it is later instantiated (see the Best Practices section for recommendations on how to cleanly consume the static configuration).

Inline configurations, by contrast, don't require an external structure. Instead, all the information needed to configure the device is specified inline via the machine configuration macros. The way this works is that the base '''device_config''' class has a small array '''m_inline_data'''[] of 64-bit values, which can be populated via the MCONFIG_TOKEN_DEVICE_INLINE_DATA* tokens. Each token specifies an index in the array, along with a 16-bit, 32-bit, or 64-bit data value to be stored there.

The raw macros used to emit the tokens that specify inline data look like this:

MDRV_DEVICE_INLINE_DATA16(index, data)
MDRV_DEVICE_INLINE_DATA32(index, data)
MDRV_DEVICE_INLINE_DATA64(index, data)

Note that the size (16, 32, 64) reflects the number of bits needed to hold the maximum data value. Regardless of the size specified here, the '''m_inline_data'''[] array is always an array of 64-bit values. Care should be used if a signed value is truncated to 16 bits via the MDRV_DEVICE_INLINE_DATA16() macro. When extracting the result from the '''m_inline_data'''[] array, it needs to be explicitly sign-extended.

The indexes that map which data is stored in which entry in the inline data array should be defined as a public enumeration within the device-specific configuration class. This keeps the global namespace less polluted and ensures no overlapping of indices.

In all cases, it is recommended that devices using inline data define nicer, more descriptive macros for specifying that data, rather than encouraging the user to operate with raw data and indexes. These custom macros can allow for more compact specification of the data, and can even be combined with the device's custom MDRV_DEVICE_ADD() macro to further simplify things for the user. Here's an example:

#define MDRV_SPEAKER_ADD(_tag, _x, _y, _z) \
MDRV_DEVICE_ADD(_tag, SPEAKER, 0) \
MDRV_DEVICE_INLINE_DATA32(speaker_device_config::INLINE_X, (_x) * (double)(1 << 24)) \
MDRV_DEVICE_INLINE_DATA32(speaker_device_config::INLINE_Y, (_y) * (double)(1 << 24)) \
MDRV_DEVICE_INLINE_DATA32(speaker_device_config::INLINE_Z, (_z) * (double)(1 << 24))

In this case, a single line in the machine configuration:

MDRV_SPEAKER_ADD("center", 0.0, 0.0, 1.0)

not only adds the device but also specifies all of its required parameters inline. (Note that because the parameters are floating-point values, they are converted to 8.24 fixed point first, since only integral values can be stored in the inline data array.)

=Example #1: Simple Device with Static Configuration=

This example is broken into four subsections, describing the configuration structure, the configuration class, the device configuration macros, and then finally the runtime class itself.

==Static Configuration Structure==

For this example, we will define a new device that uses a static configuration. Drivers using this device will need to declare a static const instance of the '''example1_device_config_data''' struct below and specify a pointer to that struct as part of the machine configuration.

Starting with the header file, we first define what the '''example1_device_config_data''' struct looks like:

struct example1_device_config_data
{
int m_device_integer_data;
const char * m_device_string_data;
};

This structure can contain pretty much anything. However, it is very important that the struct be a "plain old data" (or POD) type. This means that there should be no constructor and no virtual methods. The reason for this is that there are thousands of drivers defined in the system, and if each of them defined a static const structure like this that needed to execute its constructor on startup, it would adversely impact the overall startup time of the emulator. So just don't do it.

==Configuration Class==

Next, we define the device configuration class:

class example1_device_config : public device_config,
public example1_device_config_data
{
friend class example1_device;

// construction/destruction
example1_device_config(const machine_config &mconfig, device_type type, const char *tag,
const device_config *owner, UINT32 clock);

public:
// allocators
static device_config *static_alloc_device_config(const machine_config &mconfig,
const char *tag, const device_config *owner, UINT32 clock);
virtual device_t *alloc_device(running_machine &machine, const device_config &config) const;

// basic information getters
virtual const char *name() const { return "Example Device 1"; }

// add accessors for any device-specific config that might be needed publically

protected:
// device-level overrides
virtual void device_config_complete();
virtual bool device_validity_check(const game_driver &driver) const;

// internal state
int m_additional_state;
};

Ok, there is a lot of good and subtle information here. Let's walk through the declaration step by step:

* First thing to note is that the class is defined as inheriting from both '''device_config''' and '''example1_device_config_data''' (our static configuration structure). While it is not strictly necessary, it is convenient to do so because the members of the '''example1_device_config_data''' struct effectively become members of the device configuration class, making them easier to access without extra indirection. Making this work also implies copying the user provided data up into your configuration class, which is done later in the '''device_config_complete''' method.

* Next you'll see we added '''example1_device''' as a friend class. In general, it is recommended to keep your configuration state private/protected, but allow the associated device to have free access to it by friending it. If external code needs to query your configuration directly, just add simple accessors to the configuration state (the need for this should be rare).

* The constructor for the configuration class is kept private. The only way to allocate a new instance of a device configuration is via the static method '''static_alloc_device_config'''(). The parameters passed to the constructor in this example are the ones that need to be passed onto the base '''device_config''' class.

Walking through the methods defined in this class one by one, most of them are fairly simple and straightforward. First, the constructor:

example1_device_config::example1_device_config(const machine_config &mconfig, const char *tag,
const device_config *owner, UINT32 clock)
: device_config(mconfig, static_alloc_device_config, tag, owner, clock),
m_additional_state(0)
{
}

As you can see, most of the parameters just pass through to the base class. But be sure to initialize all configuration member variables here to ensure they get proper values. We could initialize the members of the '''example1_device_config_data''' class here as well, but we'll wait until the configuration step is complete.

Next up is the static device configuration allocator:

device_config *example1_device_config::static_alloc_device_config(const machine_config &mconfig,
const char *tag, const device_config *owner, UINT32 clock)
{
return global_alloc(example1_device_config(mconfig, tag, owner, clock));
}

This function is required to be present, as the pointer to this function is used to identify the device type. Given just this function pointer, a configuration object can be constructed, and from there, the device can be created. Note that we need to use '''global_alloc''' here because the running_machine has not yet be created (and in fact never may be). Also note that we return a pointer to the base '''device_config''' class here, since the machine configuration only knows about the base classes.

The device allocator function follows, and it is also required:

device_t *example1_device_config::alloc_device(running_machine &machine) const
{
return auto_alloc(&machine, example1_device(machine, *this));
}

In contrast to the configuration allocator, which is static and uses '''global_alloc''', the device allocator is a virtual method that uses '''auto_alloc''' in order to allocate the device and assign its memory to the provided running machine. When we construct the actual device object, we pass the machine through along with a reference to ourself so that the newly created device can have access to our configuration information.

Once all the device configurations have been created and populated, the '''device_config_complete''' method is called. We override it here to set up our inherited copy of the static configuration structure:

void example1_device_config::device_config_complete()
{
// copy static configuration if present
if (m_static_config != NULL)
*static_cast<example1_device_config_data *>(this) =
*reinterpret_cast<const example1_device_config_data *>(m_static_config);

// otherwise, initialize it to defaults
else
{
m_device_integer_data = DEFAULT_INT_VALUE;
m_device_string_data = NULL;
}
}

In the case where the user specified a pointer to a static configuration data structure, we copy it into ourselves. We use static_cast to find the pointer to where the inherited state lives within our structure and then copy the data pointed to by '''m_static_config'''. If no configuration data was provided, we take this opportunity to initialize the inherited configuration structure to default values.

Finally, if the device wishes to provide stronger validation of data -- verified both when starting a game as well as when running MAME with the -validate option -- it can ovverride the '''device_validity_check''' method:

bool example1_device_config::device_validity_check(const game_driver &driver) const
{
bool error = false;

// sanity check configuration
if (m_device_integer_value < 0)
{
mame_printf_error("%s: %s device '%s' has invalid integer parameter\n",
driver.source_file, driver.name, tag());
error = true;
}
return error;
}

This method should examing the configuration data, output friendly errors and warnings, and return true if a fatal error was detected.

==Configuration Macros==

Now we need to declare how to reference the device from a machine configuration. This is done via special tokenizing macros:

MDRV_DEVICE_ADD("tag", DEVICE_TYPE, device_clock)
MDRV_DEVICE_REPLACE("tag", DEVICE_TYPE, device_clock)

So the first thing we need to define is our ALL_CAPS DEVICE_TYPE. As mentioned previously, the device type is simply a pointer to the static '''static_alloc_device_config'''() method, so it should be defined like so:

static const device_type EXAMPLE1 = example1_device_config::static_alloc_device_config;

Although this is all that is required at a minimum, in general it is considered a good idea to provide your own set of MDRV macros that are specific to your device. By defining our macros, we can more precisely guide the user to ensure all data is properly specified. Let's say for example that our static configuration is required (i.e., it is invalid to not specify anything). Using the raw macros, a driver writer would declare an instance of our device like this:

MDRV_DEVICE_ADD("tag", EXAMPLE1, 0)
MDRV_DEVICE_CONFIG(local_structure)

Given this, you can see that it would be easy to forget the second line and leave a device with no configuration data. Also, the user is forced to specify a dummy clock, even though our device doesn't need one. Instead, let's define our own macro for adding an EXAMPLE1 device, like so:

#define MDRV_EXAMPLE1_ADD(_tag, _config) \
MDRV_DEVICE_ADD(_tag, EXAMPLE1, 0) \
MDRV_DEVICE_CONFIG(_config)

and then the equivalent declaration becomes:

MDRV_EXAMPLE1_ADD("tag", local_structure)

By doing this, we get to provide a cleaner interface for declaration, and at the same time we ensure that a required parameter is specified.

==Runtime Class==

Next we move on to the runtime device class:

class example1_device : public device_t
{
friend class example1_device_config;

// construction/destruction
example1_device(running_machine &machine, const example1_device_config &config);

public:
// any publically acessible interfaces needed for runtime

protected:
// device-level overrides (none are required, but these are common)
virtual void device_start();
virtual void device_reset();

// internal device state goes here
const example1_device_config &m_config;
int m_device_state;
};

Going through the class definition, there are some similar patterns to the corresponding device configuration class:

* Again, we derive from a common base class, in this case the '''device_t''' class. However, unlike the configuration class, we just have simple single inheritance here, since we don't need the '''example1_device_config_data''' struct.

* We make our configuration class our friend, just as they made us their friend. Really, you should imagine these two classes as two halves of the entire device.

* As with the configuration class, our constructor is kept private. A device should only be allocated via the corresponding configuration class's '''alloc_device'''() method. Since our configuration class is our friend, it can still allocate us.

* There are no standard methods that need to be public in the runtime device. However, it is quite likely you will need some in order to interact with it (read/write handlers fall into this category, for example).

* This example overrides two device-specific notification methods, one which is called at device start time (after all devices are constructed), and one which is called at reset time. These are optional, though common, to override.

* At the bottom you'll see a reference to our configuration class. This is kept to enable easy access to the configuration data.

Looking at each of the methods above in a little detail, we first encounter the constructor:

example1_device::example1_device(running_machine &machine, const example1_device_config &config)
: device_t(machine, config),
m_config(config),
m_device_state(0)
{
}

Here we initialize our parent class by passing down the reference to the running_machine and our configuration. We also stash a reference to our configuration into the m_config variable for later use, and we reset all our internal state variables to something well-defined. Note that we don't generally do much initialization in the constructor; that work is preferred to live in the '''device_start'''() method.

Speaking of which...

example1_device::device_start()
{
// initialize state from configuration
// locate any other devices
// if other devices not ready, throw device_missing_dependencies()
// register for any save state
}

Okay, not much meat in the implementation above, but there are a number of things expected of a device during '''device_start'''() time, including consumption of the configuration, identification of related devices, and set up for save states. If a related device is located (at this point all devices are constructed) but it hasn't yet been started, you can throw a '''device_missing_dependencies'''() exception and your '''device_start'''() will be queued to the end of the list to be called again later.

Similarly,

example1_device::device_reset()
{
// reset internal state to well-defined values
}

the '''device_reset'''() method is there to enable resetting a device's state in the event of a requested reset.

=Best Practices=

MAME Coding Conventions

2012-09-12T18:31:56Z

Aaron:

This page is WIP. Please don't edit it until this notice is removed.

MAME is a project that has had many contributors from many different backgrounds. Throughout its history, there have never really been any kind of formal coding conventions defined, although thanks to imitation, there is at least a glimmer of consistency.

In general, a codebase with consistent conventions is easier to understand than one with varying conventions. However, trying to impose a strict order on a project of this magnitude is certainly taking things too far.

If you categorize the MAME codebase, you can look at it like this:
* OS-specific code (OSD)
* MAME "core" code
* CPU cores
* Sound engines
* Game drivers

The first two pieces (the core and OSD) are in general only handled by a small group of developers, while the remaining pieces (drivers and CPU/sound cores) come from a much broader audience. Furthermore, the drivers and CPU/sound cores all interact to some degree with core and OSD pieces below them, so the most benefit from code clarity and consistency comes from making the core and OSD pieces consistent.

With that in mind, below is an outline some of the key coding conventions currently in use in the core and OSD layers. If you are modifying code in these layers and wish to have it accepted upon submission, you would do well to keep to these guidelines. (In fact, if you are modifying any file in any project, you should adopt the conventions of that file/project, rather than just stuffing your own inconsistent style in the middle of something else. I can't believe how many people just ignore the existing styles and jam their own style in the middle.)

One more thing. Keep in mind that coding conventions are like religion: they are often strongly-held beliefs with little factual justification to back them up. You may disagree with them. Heck, even I disagree with a few of them. But they are the conventions that are used. Deal with it.

== Naming ==
* function, method, and variable names are named using the <code>lower_under_convention</code>
* static member functions should have a static_ prefix (e.g., <code>static_timer_callback</code>)
* member variables within a class should have a standard prefix, as follows:
** normal variables should have an m_ prefix (e.g., <code>m_device</code>, <code>m_config</code>, etc)
** static members should have an s_ prefix (e.g., <code>s_device_table</code>)
** static constant members should be treated as constants and should be in ALL_CAPS_UNDER_FORMAT (e.g., <code>MAXIMUM_ITEMS</code>)
* macros, enum items, and #defined constants should be named using the <code>ALL_CAPS_UNDER_CONVENTION</code>
* constants which are part of a group should have a common prefix; example: <code>enum { ADDRESS_SPACE_PROGRAM, ADDRESS_SPACE_DATA, ADDRESS_SPACE_IO };</code>
* prefer descriptive variable names (<code>sampnum</code>, <code>memoffset</code>) over single-letter names (<code>i</code>, <code>j</code>)
* never use the prefix "my" for anything; it's not "myobject", just use "object"

== Comments ==
* comments in the code are preferred to be <code>// C++-style comments</code>, though <code>/* standard C-style comments */</code> are still very common
* each function should have a comment preceding it that briefly describes what that function does
* each file should begin with a header that includes information about the licensing of that file; if no licensing information is given, the standard MAME license is assumed

== Spacing ==
* a space should be used between binary and trinary operators — example: <code>a + b / 2</code>
* spaces should '''not''' be used around parentheses in expressions — example: <code>(((i + j) * k) >> m)</code>
* spaces should '''not''' be used between a function and its parameters — example: <code>function(param1, param2)</code>
* a space should be used between keywords (if, while, for) and their arguments — example: <code>for (x = 0; x < 10; x++)</code>
* opening/closing braces should be on their own line, and should be indented to align with the start of the statement that introduces them
* two blank lines should separate the end of a function from the start of the next function

== Expressions ==
* do not use parentheses with '''return''', it is not a function — example: <code>return 0;</code>
* do not overuse parentheses except to clarify a statement — example: <code>if (a >= 10 && a < 20)</code>
* always use NULL (not 0) when working with pointers
* make comparisons against NULL explicit: <code>if (ptr != NULL)</code>
* make comparisons against 0 explicit: <code>if (strcmp(string1, string2) == 0)</code>
* ''don't'' make comparisons against boolean values explicit: <code>val = (a == b); if (val)...</code>

== Language conventions ==
* prefer references over pointers, using pointers primarily in situations where NULL is a valid option
* use '''static''' and '''const''' keywords aggressively where appropriate
* create typedefs for function pointers; example: <code>typedef void (*my_callback_func)(UINT32 param);</code>
* make calls through function pointers explicit — example: <code>(*funcptr)(a, b)</code>
* wherever possible, use '''enum''' instead of a macro
* wherever possible, use '''inline''' functions instead of macros
* wherever possible, use templates instead of macros
* macros that look like functions should be wrapped with <code>do { <macrobody> } while (0)</code>

== Variables ==
* avoid declaring static variables inside a function scope — these are really global variables and belong at the top of the module
* declare all global variables at the top of the file
* use the MAME-defined types: <code>INT8</code>, <code>UINT8</code>, <code>INT16</code>, <code>UINT16</code>, <code>INT32</code>, <code>UINT32</code>, <code>INT64</code>, <code>UINT64</code>

== Header Files ==
* the preferred order of definitions in a header file is:
** standard header
** reinclusion protection (see below)
** includes
** debugging flags
** constants
** type definitions
** macros
** global variables
** function prototypes
** and inline functions
* function prototypes in header files generally do not use an '''extern''' qualifier
* all header files should support reinclusion; this is done by adding the following to the top of each header
#pragma once

#ifndef __FILENAME_H__
#define __FILENAME_H__
and adding
#endif /* __FILENAME__H__ */
to the end. Note that <code>#pragma once</code> is provided because it is generally faster when supported. Since not all compilers do support it, the <code>#ifndef/#define</code> methods are retained as a fallback.

== Source Files ==
* the preferred order of code in a source file is:
** standard header
** includes
** debugging flags
** constants
** type definitions
** macros
** global variables (both static and global)
** internal function prototypes
** inline functions
** externally referenced functions
** internal functions (in same order as prototyped)

Back to [[How MAME Works]]

Submitting Source Code

2012-09-12T18:31:44Z

Aaron:

If you're handy with C and want to help out, there are several ways you can do so. Source code submissions from outside developers are welcome. In fact, many of the more unexpected improvements to MAME come from folks who are not "official" MAME devs.

== Acceptable Submissions ==

When working on modifications to MAME, keep the following guidelines in mind:

* We are not interested in adding features to MAME to make games look better or improve playability or cheat the hardware emulation in order to make things run faster. Submissions that serve only to do this will not be considered.
* Technical accuracy is our #1 goal. ROM patches or hacks to games are generally not appropriate as they do not improve our understanding of the hardware. Submissions which are merely wild guesses about something and which don't make sense based on what is known about the hardware will tend to be rejected.
* ROM set naming in MAME is arbitrary. There is no point in submitting changes to ROM set names; they are crammed into 8 characters and have many other limitations. Plus it tends to annoy the developers.
* If you think there is a problem in the naming of a game, you should [http://mamedev.org/contact.html?team send an email] rather than a source code patch. Game names changes are discussed among the developers and aren't really code changes.
* Cosmetic changes to the source are best left up to the core developers. If your change doesn't add anything worthwhile to the actual code, it is not worth your time to submit it.

== Submission Guidelines ==

Before sending in a submission, you should make sure that you follow these guidelines:

* All submissions must be compiled in both debug (make DEBUG=1) and non-debug builds using the official build tools ([http://mamedev.org/tools download them from here]), and all warnings or errors fixed.
* All submissions should be in diff format, taken against the [http://mamedev.org/updates.html most recent intermediate update]. (If you are using Windows, you can get a set of diff/patch tools [http://mamedev.org/tools/diffpatch-mingw.exe here].)
* To create a correct diff, use the following command line:
diff -Nru originaltree modifiedtree >patchname.diff
where originaltree is the 'src' directory of the original, unmodified sources; modifiedtree is the 'src' directory of your updated sources; and patchname.diff is the name of the diff you want to create.
* Once you have a .diff containing your changes, ZIP it up and submit it by sending email to [[image:Submit-email.png|frameless|122x12px|baseline]].

Submissions are most often accepted or rejected without feedback. If you submitted something and it hasn't shown up in MAME within a few intermediate releases, feel free to ask what the status of your submission is.

== Getting Started ==

MAME is a huge project, and to work on many parts of it requires extensive understanding of C, arcade game hardware, CPU architectures, audio systems, graphics systems, and reverse engineering. These are not easy to come by, and the learning curve is very steep. That said, there are still ways of contributing to MAME that don't require a full top-to-bottom understanding of everything. Here are a couple of suggestions:

# Add save state support to a driver. The save state system is very modular and pretty straightforward to use. Furthermore, very few drivers are set up to use it right now. Digging into a driver and figuring out what data needs to be preserved in order to resume execution is a great way to learn about MAME.
# Figure out what unknown DIP switches do. Some of this can be determined by twiddling the DIP switches and watching what happens, but often this is not enough. Delving into the game code to understand how the DIP switches are read and what their values are used for is a good beginning challenge in reverse engineering.
# Go to [http://www.mametesters.org/ MAMETesters] and look over the bugs. There are many tricky bugs in there, but there are also many straightforward issues that nobody has yet taken the time to look into.

If you're new to emulator programming, these are a far better places to start than trying to tackle the emulation of a game that doesn't yet work. Any games that still don't work are usually due to complicated protection or hardware emulation issues and are more than likely going to be a daunting (and discouraging) challenge for someone just getting started.

Back to [[How MAME Works]]

Contributing to MAME

2012-09-12T18:31:33Z

Aaron:

MAME is strictly a not-for-profit project that has been written with the help of hundreds of people around the world. Contributions are always welcome in the form of testing, technical information, and source code submissions.

== Testing ==
Probably the easiest way to help out is to test the games in MAME. Many developers are not particularly strong game players, and quite often have not thoroughly tested a game from beginning to end looking for issues. If you are playing a game and notice something wrong, please report bugs to [http://mametesters.org MAMETesters]. Make sure you are running the most recent intermediate update and are only using the official command-line version of MAME before submitting reports.

== Technical Information ==
If you are the owner of one or more games or game PCBs and are interested in helping out, there are several ways you can do so:

* You can run MAME side-by-side with your PCB to look for graphics, sound, or gameplay issues. If you find any issues, please report them to MAMETesters.
* You can make detailed notes of all the components on your PCB, including part numbers, locations, and labels. This information can then be added to the source code for future reference.
* If you have an EPROM programmer, you can read the ROMs from your PCB to see if they are a match for what is currently supported in MAME, or if they are an alternate revision. Use mame -romident to identify ROM images that are dumped.
* If you own a PCB for a game that doesn't currently work in MAME, let us know, especially if you have an EPROM programmer. We can potentially work with you by asking you to run tests on the game to help us get it up and running.

== Source Code Submissions ==
If you're handy with C and want to help out, there are several ways you can do so. Source code submissions from outside developers are welcome. In fact, many of the more unexpected improvements to MAME come from folks who are not "official" MAME devs.

There is a whole page dedicated to how to submit source code changes to MAME. [[Submitting Source Code|Check it out.]]

Back to [[How MAME Works]]

MAME Coding Conventions

2012-09-12T18:29:06Z

Aaron: /* Naming */

Submitting Source Code

2012-09-12T18:26:20Z

Aaron: /* Submission Guidelines */

Building MAME using Microsoft Visual Studio compilers

2012-09-12T18:23:31Z

Aaron:

By default, MAME is configured via the makefile to build using the MinGW gcc compiler. Although this is a nice cross-platform solution, debugging binaries built this way leaves a lot to be desired.

If you own a copy of Visual Studio, you can configure MAME to build using those tools instead. Once you have done that, you can debug problems in MAME using the Visual Studio debugger, which is a huge step up from gdb.

Here's how to make it work:

# You must already have an environment that can build MAME using the MinGW tools. Although you won't be using gcc to compile, you will be using several of the other tools included in the standard MAME [http://mamedev.org/tools/ MinGW Development Environment]
# From the command prompt, you need to run the batch file that was installed with Visual Studio which configures the executable, include, and library paths.
#* For example, on Visual Studio 2005, the command is: <code>"\Program Files\Microsoft Visual Studio 8\VC\vcvarsall.bat" x86</code> (To build a 64-bit version, change the <code>x86</code> to <code>amd64</code>)
# Switch to the directory where the root MAME makefile lives.
# Once you've done that, simply run: <code>make MSVC_BUILD=1 DEBUG=1 SYMBOLS=1</code> and wait for it to complete (I suggest building with DEBUG=1 as that also disables optimizations and makes debugging much easier).

At this point, you should now have a mamed.exe that was built using Visual Studio tools. To debug it is very easy.

# Open up Visual Studio.
# From the File menu choose "Open Project..."
# Select vmamed.exe (you may need to adjust the file filters to show .exe files).
# To configure command line parameters, right click on the vmamed.exe item in the Solution Explorer window and choose "Properties". In that window you can specify the "Command Arguments" which would be the command line parameters you want.
# Set some breakpoints if you want, and hit "Go" (F5), or else single step into main by hitting "Step Into" (F11).
# When you're done, Visual Studio will ask if you want to save a solution file (.sln); I usually say "yes", because then it will remember your last session parameters for the next time you want to debug MAME, and the solution will show up in the recent projects list.

Back to [[How MAME Works]]

Building MAME using Microsoft Visual Studio compilers

2012-09-12T18:22:57Z

Aaron:

By default, MAME is configured via the makefile to build using the MinGW gcc compiler. Although this is a nice cross-platform solution, debugging binaries built this way leaves a lot to be desired.

If you own a copy of Visual Studio, you can configure MAME to build using those tools instead. Once you have done that, you can debug problems in MAME using the Visual Studio debugger, which is a huge step up from gdb.

Here's how to make it work:

# You must already have an environment that can build MAME using the MinGW tools. Although you won't be using gcc to compile, you will be using several of the other tools included in the standard MAME [http://mamedev.org/tools/ MinGW Development Environment]
# From the command prompt, you need to run the batch file that was installed with Visual Studio which configures the executable, include, and library paths.
#* For example, on Visual Studio 2005, the command is: <code>"\Program Files\Microsoft Visual Studio 8\VC\vcvarsall.bat" x86</code>
#** (To build a 64-bit version, change the <code>x86</code> to <code>amd64</code>)
# Switch to the directory where the root MAME makefile lives.
# Once you've done that, simply run: <code>make MSVC_BUILD=1 DEBUG=1 SYMBOLS=1</code> and wait for it to complete (I suggest building with DEBUG=1 as that also disables optimizations and makes debugging much easier).

At this point, you should now have a mamed.exe that was built using Visual Studio tools. To debug it is very easy.

# Open up Visual Studio.
# From the File menu choose "Open Project..."
# Select vmamed.exe (you may need to adjust the file filters to show .exe files).
# To configure command line parameters, right click on the vmamed.exe item in the Solution Explorer window and choose "Properties". In that window you can specify the "Command Arguments" which would be the command line parameters you want.
# Set some breakpoints if you want, and hit "Go" (F5), or else single step into main by hitting "Step Into" (F11).
# When you're done, Visual Studio will ask if you want to save a solution file (.sln); I usually say "yes", because then it will remember your last session parameters for the next time you want to debug MAME, and the solution will show up in the recent projects list.

Back to [[How MAME Works]]

Submitting Source Code

2012-05-07T15:01:29Z

Aaron: /* Submission Guidelines */

If you're handy with C and want to help out, there are several ways you can do so. Source code submissions from outside developers are welcome. In fact, many of the more unexpected improvements to MAME come from folks who are not "official" MAME devs.

== Acceptable Submissions ==

When working on modifications to MAME, keep the following guidelines in mind:

* We are not interested in adding features to MAME to make games look better or improve playability or cheat the hardware emulation in order to make things run faster. Submissions that serve only to do this will not be considered.
* Technical accuracy is our #1 goal. ROM patches or hacks to games are generally not appropriate as they do not improve our understanding of the hardware. Submissions which are merely wild guesses about something and which don't make sense based on what is known about the hardware will tend to be rejected.
* ROM set naming in MAME is arbitrary. There is no point in submitting changes to ROM set names; they are crammed into 8 characters and have many other limitations. Plus it tends to annoy the developers.
* If you think there is a problem in the naming of a game, you should [http://mamedev.org/contact.html?team send an email] rather than a source code patch. Game names changes are discussed among the developers and aren't really code changes.
* Cosmetic changes to the source are best left up to the core developers. If your change doesn't add anything worthwhile to the actual code, it is not worth your time to submit it.

== Submission Guidelines ==

Before sending in a submission, you should make sure that you follow these guidelines:

* All submissions must be compiled in both debug (make DEBUG=1) and non-debug builds using the official build tools (download them from here), and all warnings or errors fixed.
* All submissions should be in diff format, taken against the [http://mamedev.org/release.html most recent intermediate update]. (If you are using Windows, you can get a set of diff/patch tools [http://mamedev.org/tools/diffpatch-mingw.exe here].)
* To create a correct diff, use the following command line:
diff -Nru originaltree modifiedtree >patchname.diff
where originaltree is the 'src' directory of the original, unmodified sources; modifiedtree is the 'src' directory of your updated sources; and patchname.diff is the name of the diff you want to create.
* Once you have a .diff containing your changes, ZIP it up and submit it by sending email to [[image:Submit-email.png|frameless|122x12px|baseline]].

Submissions are most often accepted or rejected without feedback. If you submitted something and it hasn't shown up in MAME within a few intermediate releases, feel free to ask what the status of your submission is.

== Getting Started ==

MAME is a huge project, and to work on many parts of it requires extensive understanding of C, arcade game hardware, CPU architectures, audio systems, graphics systems, and reverse engineering. These are not easy to come by, and the learning curve is very steep. That said, there are still ways of contributing to MAME that don't require a full top-to-bottom understanding of everything. Here are a couple of suggestions:

# Add save state support to a driver. The save state system is very modular and pretty straightforward to use. Furthermore, very few drivers are set up to use it right now. Digging into a driver and figuring out what data needs to be preserved in order to resume execution is a great way to learn about MAME.
# Figure out what unknown DIP switches do. Some of this can be determined by twiddling the DIP switches and watching what happens, but often this is not enough. Delving into the game code to understand how the DIP switches are read and what their values are used for is a good beginning challenge in reverse engineering.
# Go to [http://www.mametesters.org/ MAMETesters] and look over the bugs. There are many tricky bugs in there, but there are also many straightforward issues that nobody has yet taken the time to look into.

If you're new to emulator programming, these are a far better places to start than trying to tackle the emulation of a game that doesn't yet work. Any games that still don't work are usually due to complicated protection or hardware emulation issues and are more than likely going to be a daunting (and discouraging) challenge for someone just getting started.

File:Submit-email.png

2012-05-07T14:49:07Z

Aaron:

Device Interfaces

2010-06-10T20:23:19Z

Aaron: /* Memory */

Device interfaces are separate classes that enable devices to participate in more areas of the overall system. Each interface is a sort of contract between the device that inherits from it and related other parts of the system. For example, a device inherits from the execute interface if it wishes to be scheduled and called regularly to execute. Simiarly, a device inherits from the NVRAM interface if it wishes to participate in saving/loading data to the .nv files.

To add an interface to a device, both the device class and device's configuration class must inherit from the interface's class and the interface's configuration class, respectively. Some interfaces are more about configuration than runtime, and others are more about runtime than configuration, but in all cases both interface classes are required.

Since a device is already required to inherit from device_t, this means that you must leverage C++'s <i>multiple inheritance</i> support in order to add an interface. For example, our configuration class might look like this:

class example1_device_config : public device_config,
public device_config_memory_interface,
public device_config_nvram_interface
{
};

and our device class like this:

class example1_device : public device_t,
public device_memory_interface,
public device_nvram_interface
{
};

Notice first that the '''device_config''' and '''device_t''' classes remain the first classes listed. This is important as they are the real base classes of our device. The interface classes should always be listed afterwards. Also notice that our configuration class and our device class inherit from matching configuration and interface classes.

Each interface has its own demands on the device. Some interfaces, like the sound interface, really don't require any significant changes. Others, like the NVRAM interface, are pure virtual classes, requiring implementation of one or more methods.

Currently the MAME core defines six standard interfaces:

* The execute interface connects the device to the internal scheduler, and requires implementation of a '''device_run'''() method.

* The memory interface connects the device to the memory system, allowing it to specify one or more address spaces.

* The state interface connects the device to the debugger, enabling display and editing of state during execution from within the register view. It also provides simple indexed accessors for reading/writing state in a standard fashion.

* The NVRAM interface connects the device to the NVRAM read/write process.

* The disassembly interface connects the device to the debugger, enabling disassembly views from within the disassembly window.

* The sound interface connects the device to the sound network, enabling routing of sound from the device to/from other devices.

Details on the interfaces and their requirements are given in the sections below.

=Standard Interfaces=

This section has descriptions of each of the standard device interfaces.

==Execute==

The execute interface enables a device to participate in the standard device scheduling. The scheduler makes a list of all devices with execute interfaces, and then iterates through them, assigning each a timeslice and requesting the device to execute.

The execute interface also provides mechanisms for interrupt signalling and synchronization, allowing the device to participate properly in the execution of the aggregate system.

Finally, the configuration portion of the execute interface automatically supports the MDRV_DEVICE_DISABLE() configuration tokens, which allow an executable device to exist in a configuration but prevents it from event being scheduled.

A device configuration class that inherits from '''device_config_execute_interface''' can optionally override several methods that describe how the device executes:

class example2_device_config : public device_config,
public device_config_execute_interface
{
// normal device stuff here

protected:
// device_config_execute_interface overrides
virtual UINT32 execute_clocks_to_cycles(UINT32 clocks) const;
virtual UINT32 execute_cycles_to_clocks(UINT32 cycles) const;
virtual UINT32 execute_min_cycles() const;
virtual UINT32 execute_max_cycles() const;
virtual UINT32 execute_input_lines() const;
virtual UINT32 execute_default_irq_vector() const;
};

The first two overrides provide methods that translate from clocks to cycles and vice-versa. A '''clock''' is defined as a single cycle of the input clock to the device. A '''cycle''' is defined as an internal unit used by the device when executing. By default, it is assumed that 1 clock == 1 cycle. However, if your device has an internal clock divider or multiplier, these methods should be overridden to do the math and return the proper numbers.

The middle two overrides should simply return the minimum and maximum number of cycles that any given execution step in your device may take. For example, if you are describing a CPU whose fastest instruction takes 2 cycles and whose slowest instruction takes 10 cycles, you would override these two methods to return the values 2 and 10, respectively. Note that these numbers are in cycles, not clocks. If not provided, these values both default to 1 cycle.

The '''execute_input_lines'''() override should simply return the number of synchronized input lines attached to the device. By default, this is 0.

Finally, the '''execute_default_irq_vector'''() override should return the default integer vector that is implicitly specified when signalling an input line without explicitly providing a vector.

Moving on to the device class:

class example2_device : public device_t,
public device_execute_interface
{
// normal device stuff here

protected:
// device_execute_interface overrides
virtual INT32 execute_run(INT32 cycles);
virtual void execute_burn(INT32 cycles);
virtual void execute_set_input(int linenum, int state);
};

The most important (and only required) override here is '''execute_run'''() which is called whenever the device is scheduled for execution. It is passed the number of cycles (not clocks) to execute, and when it is finished, it should return the number of cycles that were executed.

The optional override '''execute_burn'''() is called if the device execution is suspended for any reason, but cycles are consumed. This is generally used to support internal running clocks or other things which need to keep track of how many cycles executed.

Finally, the '''execute_set_input'''() override is called whenever a synchronized input is changed. Internally, the execute interface accepts synchronized input change requests, queues them, and then calls this override at the appropriate time to ensure the state is updated in sync with all other executing devices.

==Memory==

The memory interface allows to a device to own one or more address spaces. These address spaces are detected by the memory system and automatically allocated at startup time. Memory interfaces are most commonly used for CPU cores, though any device that accesses memory out over a bus should ideally use an address space for those accesses so that bank switching or other mechanisms can be implemented to act upon reads/writes to that address space.

The configuration portion of the memory interface automatically supports the MDRV_DEVICE_ADDRESS_MAP() configuration tokens. These allow an address map to be expressed in a driver, which the memory system turns into an address space at startup.

A device configuration class that inherits from '''device_config_memory_interface''' is required to override a method that returns an '''adress_space_config''' pointer for a given address space index:

class example3_device_config : public device_config,
public device_config_memory_interface
{
// normal device stuff here

protected:
// device_config_memory_interface overrides
const address_space_config *space_config(int spacenum = 0) const;

// address space configurations
address_space_config m_program_space;
address_space_config m_io_space;
};

The ''space_config''' override accepts a space index and returns a pointer to an '''adress_space_config''' object. In general, the configuration of the address space is fixed for a device, so it is typical to just embed these objects and initialize them in the constructor. For example:

example3_device_config::example3_device_config(const machine_config &mconfig, const char *tag,
const device_config *owner, UINT32 clock)
: device_config(mconfig, static_alloc_device_config, tag, owner, clock),
device_config_memory_interface(mconfig, *this),
m_program_space("program", ENDIANNESS_LITTLE, 32, 32, 0, 32, 12),
m_io_space("data", ENDIANNESS_LITTLE, 32, 16)
{
}

This creates a "program" memory space that is 32-bit little-endian with a 32-bit address bus, a 32-bit logical address space, and 12-bit pages; and a "data" memory space that is also 32-bit little-endian with a 16-bit address bus.

Given this, then the '''space_config''' looks like:

const address_space_config *space_config(int spacenum) const
{
if (spacenum == AS_PROGRAM)
return &m_program_space;
else if (spacenum == AS_IO)
return &m_io_space;
else
return NULL;
}

Moving on to the device class:

class example2_device : public device_t,
public device_memory_interface
{
// normal device stuff here

protected:
// device_execute_interface overrides
virtual bool memory_translate(int spacenum, int intention, offs_t &address);
virtual bool memory_read(int spacenum, offs_t offset, int size, UINT64 &value);
virtual bool memory_write(int spacenum, offs_t offset, int size, UINT64 value);
virtual bool memory_readop(offs_t offset, int size, UINT64 &value);
};

All of these methods are optional. For devices that support virtual address spaces (e.g., address translation), you will want to override the '''memory_translate'''() method which allows you to transform logical addresses to physical addresses, or return false if there is no mapping for the provided address.

The remaining three overrides are primarily for debugging, and allow the device a chance to act on reads, writes, and opcode reads before they are passed to the memory system. Return true if your method handled the operation to prevent it from being passed on.

==State==

==NVRAM==

==Disassembly==

==Sound==

=Custom Interface=

Device Interfaces

2010-06-10T20:22:44Z

Aaron: /* Standard Interfaces */

Device Interfaces

2010-06-08T19:49:25Z

Aaron: /* Execute */

Device Interfaces

2010-06-08T19:43:36Z

Aaron: /* Standard Interfaces */

Device Interfaces

2010-06-08T19:27:52Z

Aaron:

MAME Device Basics

2010-05-26T20:19:52Z

Aaron: /* Example #1: Simple Device with Static Configuration */

=Overview=

In MAME, a device is a mechanism for encapsulating behavior. While it is common to associate a device (in the MAME sense) with a physical device (in the real world), there does not necessarily need to be a 1:1 correspondance between the two.

Devices are important because they provide clean hooks into the MAME system. They are notified when key things in the system change, they encode their own configuration information, keep their own state, and can be instantiated multiple times within a given machine. They are easily located via a simple string tag, and are first-class citizens in memory maps, so they are easily read from and written to.

As of MAME 0.139, devices are implemented using a collection of C++ classes. In order to provide the flexibility necessary to describe the sorts of devices in MAME, the device model relies heavily on the ''multiple inheritance'' feature of C++ to extend devices with one or more ''device interfaces''.

=Core Concepts=

Every device in the project is built up out of two classes: a device-specific ''configuration class'' (derived from the '''device_config''' class) and a device-specific ''runtime class'' (derived from the '''device_t''' class).

The configuration class is responsible for encapsulating the device's configuration. The base '''device_config''' class automatically supports several core configuration properties, such as a short string ''tag'' to identify the device instance, a ''clock'' value which represents the input clock to the device, and an ''owner'' who serves as the device's parent. All device-specific configuration classes must be derived from the '''device_config''' class at their root.

Of course, most devices require more configuration than this, and so there are mechanisms for the device-specific configuration class to accept further configuration information, both inline in the MACHINE_CONFIG description, as well as externally in a static structure. This additional configuration data is stored in the device-specific class. More details on how this works come later in this article.

In addition to holding the configuration of a device, the device-specific configuration class also serves as a "factory" class that provides a mechanism for the MAME core to instantiate both new configuration objects, via a static method, and new runtime objects, via a required virtual method. (It is worth noting that the pointer to the static method that constructs configuration objects also serves as the device "type", which is a unique single entry point into the device.)

The runtime class, as its name implies, holds the runtime state of a device. The base '''device_t''' class provides a number of basic device concepts, including device initialization, reset, hooks into the save state system, clock scaling. It also holds a reference back to the corresponding '''device_config''' that begat the device.

The device-specific runtime class, which is required to derive from '''device_t''', then contains all the runtime state of the device, along with methods to operate upon the live device. It can also override several internal methods of its parent class to gain access to hooks that are called during specific events in the machine's lifecycle.

=Lifecycle of a Device=

This section aims to describe the two core device classes and how they are used by the system.

==Configuration==

Machine configurations in MAME are represented by a tokenizing mechanism wrapped by macros. A typical machine driver looks something like this (having removed some of the irrelevant details):

static MACHINE_DRIVER_START( pacman )
MDRV_CPU_ADD("maincpu", Z80, MASTER_CLOCK/6)
MDRV_CPU_PROGRAM_MAP(pacman_map)
...
MDRV_SCREEN_ADD("screen", RASTER)
MDRV_SCREEN_FORMAT(BITMAP_FORMAT_INDEXED16)
...
MDRV_SOUND_ADD("namco", NAMCO, MASTER_CLOCK/6/32)
MDRV_SOUND_CONFIG(namco_config)
MDRV_SOUND_ROUTE(ALL_OUTPUTS, "mono", 1.0)
MACHINE_DRIVER_END

When the compiler processes this, the MDRV_* macros all map down to a set of 32-bit or 64-bit integral tokens which are stored as a stream for later processing.

It may not be immediately obvious, but the machine configuration above defines three separate devices: a CPU device called "maincpu", a video screen device called "screen", and a Namco sound device called "namco". Each device generally defines its own MDRV_*_ADD() macro which permits some flexibility in how each device is added. The MDRV_* macros that follow each device provide configuration information. More on configuration in a later chapter.

When a machine configuration is instantiated, it first takes the token stream and executes it, creating a device configuration whenever it sees an MCONFIG_TOKEN_DEVICE_ADD token (which is output by the MDRV_*_ADD() macro mentioned above), and populating the device configuration with data from subsequent macros.

One of the parameters to MCONFIG_TOKEN_DEVICE_ADD is a device type. In MAME a device type is a static function pointer which serves as the factory function for allocating a device configuration. So when we need to add a device, we simply call the factory function and ask it to allocate for us a new device configuration of the appropriate type.

Once the configuration is allocated, we continue to process tokens. Tokens within a certain well-defined range are known to be device configuration tokens, and these are handed off to the allocated device configuration for processing. Specific devices can also support their own custom-defined tokens if they need special behaviors (the MDRV_SOUND_ROUTE above does this) by overriding the '''device_process_token'''() method in the device-specific configuration class.

Upon encountering the end of the token stream, all the devices are notified that the configuration parsing is complete. This allows them to consolidate any configuration information or do any other work that needs to be done. Device-specific configuration classes can override the '''device_config_complete'''() method to hook into this event.

There are several situations in which the machine configuration and all the device configurations are created: to perform validity checks on all the drivers; to output information needed by the -listxml and other front-end functions; to check for vector screens when parsing .ini files; and finally, in preparation for starting an actual game. In all cases but the last one, the machine and device configurations are created and discarded without ever creating any runtime devices, so the device lifecycle can very well begin and end with the device configuration.

In the case where validity checks are performed, the device-specific configuration class has the option of performing its own validation by overriding the '''device_validity_check'''() method and outputting errors if any are found. For this reason, validation should happen here rather than in the '''device_config_complete'''(), so that errors can be reported in a consistent manner.

==Runtime==

When the time comes to create a running machine object and start up the devices, MAME will take the device list contained in the machine configuration and rip through it to allocate the runtime devices. The mechanism for allocating a runtime device is to call the device-specific configuration class's '''device_alloc'''() method, whose job is simply to auto_alloc an instance of the device-specific runtime class. This method is a required override.

Once the entire set of devices has been allocated, MAME will once again run through the list of devices one by one and request them to start. If a device has device-specific work to do at startup (such as allocating memory or consuming configuration information), it can override the '''device_start'''() method to do so. If a device has a dependency upon another device being started, and that other device isn't ready yet, you can throw a '''device_missing_dependencies''' exception from within the '''device_start''' function and you will be re-queued to the end of the initialization order.

An important thing to note is the explicit separation between allocation and startup. All the devices are allocated first, and then all of them are started. The intention is that most of the hard work is done at start time, leaving the class constructor mostly the job of ensuring all local variables are initialized to sane values.

After the devices are all allocated and started, MAME makes one more pass through them all to reset them. As with startup, a device-specific class can override the '''device_reset'''() method to hook into this notification. Unlike startup, which occurs exactly once, a reset may happen multiple times throughout a device's existence. In addition to the first call at startup, all devices are also implicitly reset when a soft or hard reset is performed by the user, or when a driver explicitly calls the device's '''reset'''() method.

Finally, when the emulation is complete, all the devices are destructed. Note that there is no separation between stopping and destruction, as there is between starting and allocation. This means that your device's destructor is responsible for cleaning up any allocations or other side-effects created during the device's lifetime, excepting those allocated via the '''auto_alloc''' macros, which are automatically destroyed shortly afterwards.

In addition to these basic interfaces, there are several other key times when a device is notified. Device-specific hooks are provided for each of these situations, so a simple override is all that is needed to react:

* Prior to saving the state of the system, all the devices are notified. This takes the place of registering handlers via '''state_save_register_presave'''() as was done previously. To hook this, simple override the '''device_pre_save'''() method.

* Similarly, immediately after loading a saved state, all devices are notified. Device-specific classes hook this via the '''device_post_load'''() method.

* If the emulation is started with the debugger enabled, there is a hook '''device_debug_setup'''() which is called to allow device-specific classes to register additional functions or other information with the debugger.

* Finally, if the clock of a device is changed, a notification is sent via the '''device_clock_changed'''() method. This is necessary because most clock management is handled generically in the base '''device_t''' class.

=Configuring Devices=

Device configuration comes in two flavors, static configuration and inline configuration. The decision as to which to use is fairly arbitrary -- and in fact both can be used at the same time! The example from the Lifecycle of a Device chapter demonstrates the use of both types of configuration:

static MACHINE_DRIVER_START( pacman )
MDRV_CPU_ADD("maincpu", Z80, MASTER_CLOCK/6)
MDRV_CPU_PROGRAM_MAP(pacman_map) // inline configuration
...
MDRV_SCREEN_ADD("screen", RASTER)
MDRV_SCREEN_FORMAT(BITMAP_FORMAT_INDEXED16) // inline configuration
...
MDRV_SOUND_ADD("namco", NAMCO, MASTER_CLOCK/6/32)
MDRV_SOUND_CONFIG(namco_config) // static configuration
MDRV_SOUND_ROUTE(ALL_OUTPUTS, "mono", 1.0) // AND inline configuration
MACHINE_DRIVER_END

Let's start by examining how static configuration work, as they are the simplest to understand. A static configuration is simply a single pointer to a constant structure, defined by the game driver, and expressed via the token stream as an MCONFIG_TOKEN_DEVICE_CONFIG token, followed by a pointer to the structure.

Within a machine driver configuration, a static configuration is specified by a MDRV_DEVICE_CONFIG() macro. Certain devices and device types might also provide aliases to this, like the MDRV_SOUND_CONFIG() macro above. If you look at the pacman.c driver, you'll see the configuration structure:

static const namco_interface namco_config =
{
3, /* number of voices */
0 /* stereo */
};

When a driver specifies a static configuration, the pointer is extracted from the token stream and deposited into the void pointer '''m_static_config''', stored by the '''device_config''' base class. The driver-specific configuration class can then consume this pointer when its '''device_config_complete'''() method is called, or it can leave it around for the device itself to consume when it is later instantiated (see the Best Practices section for recommendations on how to cleanly consume the static configuration).

Inline configurations, by contrast, don't require an external structure. Instead, all the information needed to configure the device is specified inline via the machine configuration macros. The way this works is that the base '''device_config''' class has a small array '''m_inline_data'''[] of 64-bit values, which can be populated via the MCONFIG_TOKEN_DEVICE_INLINE_DATA* tokens. Each token specifies an index in the array, along with a 16-bit, 32-bit, or 64-bit data value to be stored there.

The raw macros used to emit the tokens that specify inline data look like this:

MDRV_DEVICE_INLINE_DATA16(index, data)
MDRV_DEVICE_INLINE_DATA32(index, data)
MDRV_DEVICE_INLINE_DATA64(index, data)

Note that the size (16, 32, 64) reflects the number of bits needed to hold the maximum data value. Regardless of the size specified here, the '''m_inline_data'''[] array is always an array of 64-bit values. Care should be used if a signed value is truncated to 16 bits via the MDRV_DEVICE_INLINE_DATA16() macro. When extracting the result from the '''m_inline_data'''[] array, it needs to be explicitly sign-extended.

The indexes that map which data is stored in which entry in the inline data array should be defined as a public enumeration within the device-specific configuration class. This keeps the global namespace less polluted and ensures no overlapping of indices.

In all cases, it is recommended that devices using inline data define nicer, more descriptive macros for specifying that data, rather than encouraging the user to operate with raw data and indexes. These custom macros can allow for more compact specification of the data, and can even be combined with the device's custom MDRV_DEVICE_ADD() macro to further simplify things for the user. Here's an example:

#define MDRV_SPEAKER_ADD(_tag, _x, _y, _z) \
MDRV_DEVICE_ADD(_tag, SPEAKER, 0) \
MDRV_DEVICE_INLINE_DATA32(speaker_device_config::INLINE_X, (_x) * (double)(1 << 24)) \
MDRV_DEVICE_INLINE_DATA32(speaker_device_config::INLINE_Y, (_y) * (double)(1 << 24)) \
MDRV_DEVICE_INLINE_DATA32(speaker_device_config::INLINE_Z, (_z) * (double)(1 << 24))

In this case, a single line in the machine configuration:

MDRV_SPEAKER_ADD("center", 0.0, 0.0, 1.0)

not only adds the device but also specifies all of its required parameters inline. (Note that because the parameters are floating-point values, they are converted to 8.24 fixed point first, since only integral values can be stored in the inline data array.)

=Example #1: Simple Device with Static Configuration=

This example is broken into four subsections, describing the configuration structure, the configuration class, the device configuration macros, and then finally the runtime class itself.

==Static Configuration Structure==

For this example, we will define a new device that uses a static configuration. Drivers using this device will need to declare a static const instance of the '''example1_device_config_data''' struct below and specify a pointer to that struct as part of the machine configuration.

Starting with the header file, we first define what the '''example1_device_config_data''' struct looks like:

struct example1_device_config_data
{
int m_device_integer_data;
const char * m_device_string_data;
};

This structure can contain pretty much anything. However, it is very important that the struct be a "plain old data" (or POD) type. This means that there should be no constructor and no virtual methods. The reason for this is that there are thousands of drivers defined in the system, and if each of them defined a static const structure like this that needed to execute its constructor on startup, it would adversely impact the overall startup time of the emulator. So just don't do it.

==Configuration Class==

Next, we define the device configuration class:

class example1_device_config : public device_config,
public example1_device_config_data
{
friend class example1_device;

// construction/destruction
example1_device_config(const machine_config &mconfig, device_type type, const char *tag,
const device_config *owner, UINT32 clock);

public:
// allocators
static device_config *static_alloc_device_config(const machine_config &mconfig,
const char *tag, const device_config *owner, UINT32 clock);
virtual device_t *alloc_device(running_machine &machine, const device_config &config) const;

// basic information getters
virtual const char *name() const { return "Example Device 1"; }

// add accessors for any device-specific config that might be needed publically

protected:
// device-level overrides
virtual void device_config_complete();
virtual bool device_validity_check(const game_driver &driver) const;

// internal state
int m_additional_state;
};

Ok, there is a lot of good and subtle information here. Let's walk through the declaration step by step:

* First thing to note is that the class is defined as inheriting from both '''device_config''' and '''example1_device_config_data''' (our static configuration structure). While it is not strictly necessary, it is convenient to do so because the members of the '''example1_device_config_data''' struct effectively become members of the device configuration class, making them easier to access without extra indirection. Making this work also implies copying the user provided data up into your configuration class, which is done later in the '''device_config_complete''' method.

* Next you'll see we added '''example1_device''' as a friend class. In general, it is recommended to keep your configuration state private/protected, but allow the associated device to have free access to it by friending it. If external code needs to query your configuration directly, just add simple accessors to the configuration state (the need for this should be rare).

* The constructor for the configuration class is kept private. The only way to allocate a new instance of a device configuration is via the static method '''static_alloc_device_config'''(). The parameters passed to the constructor in this example are the ones that need to be passed onto the base '''device_config''' class.

Walking through the methods defined in this class one by one, most of them are fairly simple and straightforward. First, the constructor:

example1_device_config::example1_device_config(const machine_config &mconfig, const char *tag,
const device_config *owner, UINT32 clock)
: device_config(mconfig, static_alloc_device_config, tag, owner, clock),
m_additional_state(0)
{
}

As you can see, most of the parameters just pass through to the base class. But be sure to initialize all configuration member variables here to ensure they get proper values. We could initialize the members of the '''example1_device_config_data''' class here as well, but we'll wait until the configuration step is complete.

Next up is the static device configuration allocator:

device_config *example1_device_config::static_alloc_device_config(const machine_config &mconfig,
const char *tag, const device_config *owner, UINT32 clock)
{
return global_alloc(example1_device_config(mconfig, tag, owner, clock));
}

This function is required to be present, as the pointer to this function is used to identify the device type. Given just this function pointer, a configuration object can be constructed, and from there, the device can be created. Note that we need to use '''global_alloc''' here because the running_machine has not yet be created (and in fact never may be). Also note that we return a pointer to the base '''device_config''' class here, since the machine configuration only knows about the base classes.

The device allocator function follows, and it is also required:

device_t *example1_device_config::alloc_device(running_machine &machine) const
{
return auto_alloc(&machine, example1_device(machine, *this));
}

In contrast to the configuration allocator, which is static and uses '''global_alloc''', the device allocator is a virtual method that uses '''auto_alloc''' in order to allocate the device and assign its memory to the provided running machine. When we construct the actual device object, we pass the machine through along with a reference to ourself so that the newly created device can have access to our configuration information.

Once all the device configurations have been created and populated, the '''device_config_complete''' method is called. We override it here to set up our inherited copy of the static configuration structure:

void example1_device_config::device_config_complete()
{
// copy static configuration if present
if (m_static_config != NULL)
*static_cast<example1_device_config_data *>(this) =
*reinterpret_cast<const example1_device_config_data *>(m_static_config);

// otherwise, initialize it to defaults
else
{
m_device_integer_data = DEFAULT_INT_VALUE;
m_device_string_data = NULL;
}
}

In the case where the user specified a pointer to a static configuration data structure, we copy it into ourselves. We use static_cast to find the pointer to where the inherited state lives within our structure and then copy the data pointed to by '''m_static_config'''. If no configuration data was provided, we take this opportunity to initialize the inherited configuration structure to default values.

Finally, if the device wishes to provide stronger validation of data -- verified both when starting a game as well as when running MAME with the -validate option -- it can ovverride the '''device_validity_check''' method:

bool example1_device_config::device_validity_check(const game_driver &driver) const
{
bool error = false;

// sanity check configuration
if (m_device_integer_value < 0)
{
mame_printf_error("%s: %s device '%s' has invalid integer parameter\n",
driver.source_file, driver.name, tag());
error = true;
}
return error;
}

This method should examing the configuration data, output friendly errors and warnings, and return true if a fatal error was detected.

==Configuration Macros==

Now we need to declare how to reference the device from a machine configuration. This is done via special tokenizing macros:

MDRV_DEVICE_ADD("tag", DEVICE_TYPE, device_clock)
MDRV_DEVICE_REPLACE("tag", DEVICE_TYPE, device_clock)

So the first thing we need to define is our ALL_CAPS DEVICE_TYPE. As mentioned previously, the device type is simply a pointer to the static '''static_alloc_device_config'''() method, so it should be defined like so:

static const device_type EXAMPLE1 = example1_device_config::static_alloc_device_config;

Although this is all that is required at a minimum, in general it is considered a good idea to provide your own set of MDRV macros that are specific to your device. By defining our macros, we can more precisely guide the user to ensure all data is properly specified. Let's say for example that our static configuration is required (i.e., it is invalid to not specify anything). Using the raw macros, a driver writer would declare an instance of our device like this:

MDRV_DEVICE_ADD("tag", EXAMPLE1, 0)
MDRV_DEVICE_CONFIG(local_structure)

Given this, you can see that it would be easy to forget the second line and leave a device with no configuration data. Also, the user is forced to specify a dummy clock, even though our device doesn't need one. Instead, let's define our own macro for adding an EXAMPLE1 device, like so:

#define MDRV_EXAMPLE1_ADD(_tag, _config) \
MDRV_DEVICE_ADD(_tag, EXAMPLE1, 0) \
MDRV_DEVICE_CONFIG(_config)

and then the equivalent declaration becomes:

MDRV_EXAMPLE1_ADD("tag", local_structure)

By doing this, we get to provide a cleaner interface for declaration, and at the same time we ensure that a required parameter is specified.

==Runtime Class==

Next we move on to the runtime device class:

class example1_device : public device_t
{
friend class example1_device_config;

// construction/destruction
example1_device(running_machine &machine, const example1_device_config &config);

public:
// any publically acessible interfaces needed for runtime

protected:
// device-level overrides (none are required, but these are common)
virtual void device_start();
virtual void device_reset();

// internal device state goes here
const example1_device_config &m_config;
int m_device_state;
};

Going through the class definition, there are some similar patterns to the corresponding device configuration class:

* Again, we derive from a common base class, in this case the '''device_t''' class. However, unlike the configuration class, we just have simple single inheritance here, since we don't need the '''example1_device_config_data''' struct.

* We make our configuration class our friend, just as they made us their friend. Really, you should imagine these two classes as two halves of the entire device.

* As with the configuration class, our constructor is kept private. A device should only be allocated via the corresponding configuration class's '''alloc_device'''() method. Since our configuration class is our friend, it can still allocate us.

* There are no standard methods that need to be public in the runtime device. However, it is quite likely you will need some in order to interact with it (read/write handlers fall into this category, for example).

* This example overrides two device-specific notification methods, one which is called at device start time (after all devices are constructed), and one which is called at reset time. These are optional, though common, to override.

* At the bottom you'll see a reference to our configuration class. This is kept to enable easy access to the configuration data.

Looking at each of the methods above in a little detail, we first encounter the constructor:

example1_device::example1_device(running_machine &machine, const example1_device_config &config)
: device_t(machine, config),
m_config(config),
m_device_state(0)
{
}

Here we initialize our parent class by passing down the reference to the running_machine and our configuration. We also stash a reference to our configuration into the m_config variable for later use, and we reset all our internal state variables to something well-defined. Note that we don't generally do much initialization in the constructor; that work is preferred to live in the '''device_start'''() method.

Speaking of which...

example1_device::device_start()
{
// initialize state from configuration
// locate any other devices
// if other devices not ready, throw device_missing_dependencies()
// register for any save state
}

Okay, not much meat in the implementation above, but there are a number of things expected of a device during '''device_start'''() time, including consumption of the configuration, identification of related devices, and set up for save states. If a related device is located (at this point all devices are constructed) but it hasn't yet been started, you can throw a '''device_missing_dependencies'''() exception and your '''device_start'''() will be queued to the end of the list to be called again later.

Similarly,

example1_device::device_reset()
{
// reset internal state to well-defined values
}

the '''device_reset'''() method is there to enable resetting a device's state in the event of a requested reset.

=Best Practices=

MAME Device Basics

2010-05-26T20:18:08Z

Aaron: /* Configuration Macros */

=Overview=

In MAME, a device is a mechanism for encapsulating behavior. While it is common to associate a device (in the MAME sense) with a physical device (in the real world), there does not necessarily need to be a 1:1 correspondance between the two.

Devices are important because they provide clean hooks into the MAME system. They are notified when key things in the system change, they encode their own configuration information, keep their own state, and can be instantiated multiple times within a given machine. They are easily located via a simple string tag, and are first-class citizens in memory maps, so they are easily read from and written to.

As of MAME 0.139, devices are implemented using a collection of C++ classes. In order to provide the flexibility necessary to describe the sorts of devices in MAME, the device model relies heavily on the ''multiple inheritance'' feature of C++ to extend devices with one or more ''device interfaces''.

=Core Concepts=

Every device in the project is built up out of two classes: a device-specific ''configuration class'' (derived from the '''device_config''' class) and a device-specific ''runtime class'' (derived from the '''device_t''' class).

The configuration class is responsible for encapsulating the device's configuration. The base '''device_config''' class automatically supports several core configuration properties, such as a short string ''tag'' to identify the device instance, a ''clock'' value which represents the input clock to the device, and an ''owner'' who serves as the device's parent. All device-specific configuration classes must be derived from the '''device_config''' class at their root.

Of course, most devices require more configuration than this, and so there are mechanisms for the device-specific configuration class to accept further configuration information, both inline in the MACHINE_CONFIG description, as well as externally in a static structure. This additional configuration data is stored in the device-specific class. More details on how this works come later in this article.

In addition to holding the configuration of a device, the device-specific configuration class also serves as a "factory" class that provides a mechanism for the MAME core to instantiate both new configuration objects, via a static method, and new runtime objects, via a required virtual method. (It is worth noting that the pointer to the static method that constructs configuration objects also serves as the device "type", which is a unique single entry point into the device.)

The runtime class, as its name implies, holds the runtime state of a device. The base '''device_t''' class provides a number of basic device concepts, including device initialization, reset, hooks into the save state system, clock scaling. It also holds a reference back to the corresponding '''device_config''' that begat the device.

The device-specific runtime class, which is required to derive from '''device_t''', then contains all the runtime state of the device, along with methods to operate upon the live device. It can also override several internal methods of its parent class to gain access to hooks that are called during specific events in the machine's lifecycle.

=Lifecycle of a Device=

This section aims to describe the two core device classes and how they are used by the system.

==Configuration==

Machine configurations in MAME are represented by a tokenizing mechanism wrapped by macros. A typical machine driver looks something like this (having removed some of the irrelevant details):

static MACHINE_DRIVER_START( pacman )
MDRV_CPU_ADD("maincpu", Z80, MASTER_CLOCK/6)
MDRV_CPU_PROGRAM_MAP(pacman_map)
...
MDRV_SCREEN_ADD("screen", RASTER)
MDRV_SCREEN_FORMAT(BITMAP_FORMAT_INDEXED16)
...
MDRV_SOUND_ADD("namco", NAMCO, MASTER_CLOCK/6/32)
MDRV_SOUND_CONFIG(namco_config)
MDRV_SOUND_ROUTE(ALL_OUTPUTS, "mono", 1.0)
MACHINE_DRIVER_END

When the compiler processes this, the MDRV_* macros all map down to a set of 32-bit or 64-bit integral tokens which are stored as a stream for later processing.

It may not be immediately obvious, but the machine configuration above defines three separate devices: a CPU device called "maincpu", a video screen device called "screen", and a Namco sound device called "namco". Each device generally defines its own MDRV_*_ADD() macro which permits some flexibility in how each device is added. The MDRV_* macros that follow each device provide configuration information. More on configuration in a later chapter.

When a machine configuration is instantiated, it first takes the token stream and executes it, creating a device configuration whenever it sees an MCONFIG_TOKEN_DEVICE_ADD token (which is output by the MDRV_*_ADD() macro mentioned above), and populating the device configuration with data from subsequent macros.

One of the parameters to MCONFIG_TOKEN_DEVICE_ADD is a device type. In MAME a device type is a static function pointer which serves as the factory function for allocating a device configuration. So when we need to add a device, we simply call the factory function and ask it to allocate for us a new device configuration of the appropriate type.

Once the configuration is allocated, we continue to process tokens. Tokens within a certain well-defined range are known to be device configuration tokens, and these are handed off to the allocated device configuration for processing. Specific devices can also support their own custom-defined tokens if they need special behaviors (the MDRV_SOUND_ROUTE above does this) by overriding the '''device_process_token'''() method in the device-specific configuration class.

Upon encountering the end of the token stream, all the devices are notified that the configuration parsing is complete. This allows them to consolidate any configuration information or do any other work that needs to be done. Device-specific configuration classes can override the '''device_config_complete'''() method to hook into this event.

There are several situations in which the machine configuration and all the device configurations are created: to perform validity checks on all the drivers; to output information needed by the -listxml and other front-end functions; to check for vector screens when parsing .ini files; and finally, in preparation for starting an actual game. In all cases but the last one, the machine and device configurations are created and discarded without ever creating any runtime devices, so the device lifecycle can very well begin and end with the device configuration.

In the case where validity checks are performed, the device-specific configuration class has the option of performing its own validation by overriding the '''device_validity_check'''() method and outputting errors if any are found. For this reason, validation should happen here rather than in the '''device_config_complete'''(), so that errors can be reported in a consistent manner.

==Runtime==

When the time comes to create a running machine object and start up the devices, MAME will take the device list contained in the machine configuration and rip through it to allocate the runtime devices. The mechanism for allocating a runtime device is to call the device-specific configuration class's '''device_alloc'''() method, whose job is simply to auto_alloc an instance of the device-specific runtime class. This method is a required override.

Once the entire set of devices has been allocated, MAME will once again run through the list of devices one by one and request them to start. If a device has device-specific work to do at startup (such as allocating memory or consuming configuration information), it can override the '''device_start'''() method to do so. If a device has a dependency upon another device being started, and that other device isn't ready yet, you can throw a '''device_missing_dependencies''' exception from within the '''device_start''' function and you will be re-queued to the end of the initialization order.

An important thing to note is the explicit separation between allocation and startup. All the devices are allocated first, and then all of them are started. The intention is that most of the hard work is done at start time, leaving the class constructor mostly the job of ensuring all local variables are initialized to sane values.

After the devices are all allocated and started, MAME makes one more pass through them all to reset them. As with startup, a device-specific class can override the '''device_reset'''() method to hook into this notification. Unlike startup, which occurs exactly once, a reset may happen multiple times throughout a device's existence. In addition to the first call at startup, all devices are also implicitly reset when a soft or hard reset is performed by the user, or when a driver explicitly calls the device's '''reset'''() method.

Finally, when the emulation is complete, all the devices are destructed. Note that there is no separation between stopping and destruction, as there is between starting and allocation. This means that your device's destructor is responsible for cleaning up any allocations or other side-effects created during the device's lifetime, excepting those allocated via the '''auto_alloc''' macros, which are automatically destroyed shortly afterwards.

In addition to these basic interfaces, there are several other key times when a device is notified. Device-specific hooks are provided for each of these situations, so a simple override is all that is needed to react:

* Prior to saving the state of the system, all the devices are notified. This takes the place of registering handlers via '''state_save_register_presave'''() as was done previously. To hook this, simple override the '''device_pre_save'''() method.

* Similarly, immediately after loading a saved state, all devices are notified. Device-specific classes hook this via the '''device_post_load'''() method.

* If the emulation is started with the debugger enabled, there is a hook '''device_debug_setup'''() which is called to allow device-specific classes to register additional functions or other information with the debugger.

* Finally, if the clock of a device is changed, a notification is sent via the '''device_clock_changed'''() method. This is necessary because most clock management is handled generically in the base '''device_t''' class.

=Configuring Devices=

Device configuration comes in two flavors, static configuration and inline configuration. The decision as to which to use is fairly arbitrary -- and in fact both can be used at the same time! The example from the Lifecycle of a Device chapter demonstrates the use of both types of configuration:

static MACHINE_DRIVER_START( pacman )
MDRV_CPU_ADD("maincpu", Z80, MASTER_CLOCK/6)
MDRV_CPU_PROGRAM_MAP(pacman_map) // inline configuration
...
MDRV_SCREEN_ADD("screen", RASTER)
MDRV_SCREEN_FORMAT(BITMAP_FORMAT_INDEXED16) // inline configuration
...
MDRV_SOUND_ADD("namco", NAMCO, MASTER_CLOCK/6/32)
MDRV_SOUND_CONFIG(namco_config) // static configuration
MDRV_SOUND_ROUTE(ALL_OUTPUTS, "mono", 1.0) // AND inline configuration
MACHINE_DRIVER_END

Let's start by examining how static configuration work, as they are the simplest to understand. A static configuration is simply a single pointer to a constant structure, defined by the game driver, and expressed via the token stream as an MCONFIG_TOKEN_DEVICE_CONFIG token, followed by a pointer to the structure.

Within a machine driver configuration, a static configuration is specified by a MDRV_DEVICE_CONFIG() macro. Certain devices and device types might also provide aliases to this, like the MDRV_SOUND_CONFIG() macro above. If you look at the pacman.c driver, you'll see the configuration structure:

static const namco_interface namco_config =
{
3, /* number of voices */
0 /* stereo */
};

When a driver specifies a static configuration, the pointer is extracted from the token stream and deposited into the void pointer '''m_static_config''', stored by the '''device_config''' base class. The driver-specific configuration class can then consume this pointer when its '''device_config_complete'''() method is called, or it can leave it around for the device itself to consume when it is later instantiated (see the Best Practices section for recommendations on how to cleanly consume the static configuration).

Inline configurations, by contrast, don't require an external structure. Instead, all the information needed to configure the device is specified inline via the machine configuration macros. The way this works is that the base '''device_config''' class has a small array '''m_inline_data'''[] of 64-bit values, which can be populated via the MCONFIG_TOKEN_DEVICE_INLINE_DATA* tokens. Each token specifies an index in the array, along with a 16-bit, 32-bit, or 64-bit data value to be stored there.

The raw macros used to emit the tokens that specify inline data look like this:

MDRV_DEVICE_INLINE_DATA16(index, data)
MDRV_DEVICE_INLINE_DATA32(index, data)
MDRV_DEVICE_INLINE_DATA64(index, data)

Note that the size (16, 32, 64) reflects the number of bits needed to hold the maximum data value. Regardless of the size specified here, the '''m_inline_data'''[] array is always an array of 64-bit values. Care should be used if a signed value is truncated to 16 bits via the MDRV_DEVICE_INLINE_DATA16() macro. When extracting the result from the '''m_inline_data'''[] array, it needs to be explicitly sign-extended.

The indexes that map which data is stored in which entry in the inline data array should be defined as a public enumeration within the device-specific configuration class. This keeps the global namespace less polluted and ensures no overlapping of indices.

In all cases, it is recommended that devices using inline data define nicer, more descriptive macros for specifying that data, rather than encouraging the user to operate with raw data and indexes. These custom macros can allow for more compact specification of the data, and can even be combined with the device's custom MDRV_DEVICE_ADD() macro to further simplify things for the user. Here's an example:

#define MDRV_SPEAKER_ADD(_tag, _x, _y, _z) \
MDRV_DEVICE_ADD(_tag, SPEAKER, 0) \
MDRV_DEVICE_INLINE_DATA32(speaker_device_config::INLINE_X, (_x) * (double)(1 << 24)) \
MDRV_DEVICE_INLINE_DATA32(speaker_device_config::INLINE_Y, (_y) * (double)(1 << 24)) \
MDRV_DEVICE_INLINE_DATA32(speaker_device_config::INLINE_Z, (_z) * (double)(1 << 24))

In this case, a single line in the machine configuration:

MDRV_SPEAKER_ADD("center", 0.0, 0.0, 1.0)

not only adds the device but also specifies all of its required parameters inline. (Note that because the parameters are floating-point values, they are converted to 8.24 fixed point first, since only integral values can be stored in the inline data array.)

=Example #1: Simple Device with Static Configuration=

This example is broken into two subsections, describing the configuration class and then the runtime class.

==Static Configuration Structure==

For this example, we will define a new device that uses a static configuration. Drivers using this device will need to declare a static const instance of the '''example1_device_config_data''' struct below and specify a pointer to that struct as part of the machine configuration.

Starting with the header file, we first define what the '''example1_device_config_data''' struct looks like:

struct example1_device_config_data
{
int m_device_integer_data;
const char * m_device_string_data;
};

This structure can contain pretty much anything. However, it is very important that the struct be a "plain old data" (or POD) type. This means that there should be no constructor and no virtual methods. The reason for this is that there are thousands of drivers defined in the system, and if each of them defined a static const structure like this that needed to execute its constructor on startup, it would adversely impact the overall startup time of the emulator. So just don't do it.

==Configuration Class==

Next, we define the device configuration class:

class example1_device_config : public device_config,
public example1_device_config_data
{
friend class example1_device;

// construction/destruction
example1_device_config(const machine_config &mconfig, device_type type, const char *tag,
const device_config *owner, UINT32 clock);

public:
// allocators
static device_config *static_alloc_device_config(const machine_config &mconfig,
const char *tag, const device_config *owner, UINT32 clock);
virtual device_t *alloc_device(running_machine &machine, const device_config &config) const;

// basic information getters
virtual const char *name() const { return "Example Device 1"; }

// add accessors for any device-specific config that might be needed publically

protected:
// device-level overrides
virtual void device_config_complete();
virtual bool device_validity_check(const game_driver &driver) const;

// internal state
int m_additional_state;
};

Ok, there is a lot of good and subtle information here. Let's walk through the declaration step by step:

* First thing to note is that the class is defined as inheriting from both '''device_config''' and '''example1_device_config_data''' (our static configuration structure). While it is not strictly necessary, it is convenient to do so because the members of the '''example1_device_config_data''' struct effectively become members of the device configuration class, making them easier to access without extra indirection. Making this work also implies copying the user provided data up into your configuration class, which is done later in the '''device_config_complete''' method.

* Next you'll see we added '''example1_device''' as a friend class. In general, it is recommended to keep your configuration state private/protected, but allow the associated device to have free access to it by friending it. If external code needs to query your configuration directly, just add simple accessors to the configuration state (the need for this should be rare).

* The constructor for the configuration class is kept private. The only way to allocate a new instance of a device configuration is via the static method '''static_alloc_device_config'''(). The parameters passed to the constructor in this example are the ones that need to be passed onto the base '''device_config''' class.

Walking through the methods defined in this class one by one, most of them are fairly simple and straightforward. First, the constructor:

example1_device_config::example1_device_config(const machine_config &mconfig, const char *tag,
const device_config *owner, UINT32 clock)
: device_config(mconfig, static_alloc_device_config, tag, owner, clock),
m_additional_state(0)
{
}

As you can see, most of the parameters just pass through to the base class. But be sure to initialize all configuration member variables here to ensure they get proper values. We could initialize the members of the '''example1_device_config_data''' class here as well, but we'll wait until the configuration step is complete.

Next up is the static device configuration allocator:

device_config *example1_device_config::static_alloc_device_config(const machine_config &mconfig,
const char *tag, const device_config *owner, UINT32 clock)
{
return global_alloc(example1_device_config(mconfig, tag, owner, clock));
}

This function is required to be present, as the pointer to this function is used to identify the device type. Given just this function pointer, a configuration object can be constructed, and from there, the device can be created. Note that we need to use '''global_alloc''' here because the running_machine has not yet be created (and in fact never may be). Also note that we return a pointer to the base '''device_config''' class here, since the machine configuration only knows about the base classes.

The device allocator function follows, and it is also required:

device_t *example1_device_config::alloc_device(running_machine &machine) const
{
return auto_alloc(&machine, example1_device(machine, *this));
}

In contrast to the configuration allocator, which is static and uses '''global_alloc''', the device allocator is a virtual method that uses '''auto_alloc''' in order to allocate the device and assign its memory to the provided running machine. When we construct the actual device object, we pass the machine through along with a reference to ourself so that the newly created device can have access to our configuration information.

Once all the device configurations have been created and populated, the '''device_config_complete''' method is called. We override it here to set up our inherited copy of the static configuration structure:

void example1_device_config::device_config_complete()
{
// copy static configuration if present
if (m_static_config != NULL)
*static_cast<example1_device_config_data *>(this) =
*reinterpret_cast<const example1_device_config_data *>(m_static_config);

// otherwise, initialize it to defaults
else
{
m_device_integer_data = DEFAULT_INT_VALUE;
m_device_string_data = NULL;
}
}

In the case where the user specified a pointer to a static configuration data structure, we copy it into ourselves. We use static_cast to find the pointer to where the inherited state lives within our structure and then copy the data pointed to by '''m_static_config'''. If no configuration data was provided, we take this opportunity to initialize the inherited configuration structure to default values.

Finally, if the device wishes to provide stronger validation of data -- verified both when starting a game as well as when running MAME with the -validate option -- it can ovverride the '''device_validity_check''' method:

bool example1_device_config::device_validity_check(const game_driver &driver) const
{
bool error = false;

// sanity check configuration
if (m_device_integer_value < 0)
{
mame_printf_error("%s: %s device '%s' has invalid integer parameter\n",
driver.source_file, driver.name, tag());
error = true;
}
return error;
}

This method should examing the configuration data, output friendly errors and warnings, and return true if a fatal error was detected.

==Configuration Macros==

Now we need to declare how to reference the device from a machine configuration. This is done via special tokenizing macros:

MDRV_DEVICE_ADD("tag", DEVICE_TYPE, device_clock)
MDRV_DEVICE_REPLACE("tag", DEVICE_TYPE, device_clock)

So the first thing we need to define is our ALL_CAPS DEVICE_TYPE. As mentioned previously, the device type is simply a pointer to the static '''static_alloc_device_config'''() method, so it should be defined like so:

static const device_type EXAMPLE1 = example1_device_config::static_alloc_device_config;

Although this is all that is required at a minimum, in general it is considered a good idea to provide your own set of MDRV macros that are specific to your device. By defining our macros, we can more precisely guide the user to ensure all data is properly specified. Let's say for example that our static configuration is required (i.e., it is invalid to not specify anything). Using the raw macros, a driver writer would declare an instance of our device like this:

MDRV_DEVICE_ADD("tag", EXAMPLE1, 0)
MDRV_DEVICE_CONFIG(local_structure)

Given this, you can see that it would be easy to forget the second line and leave a device with no configuration data. Also, the user is forced to specify a dummy clock, even though our device doesn't need one. Instead, let's define our own macro for adding an EXAMPLE1 device, like so:

#define MDRV_EXAMPLE1_ADD(_tag, _config) \
MDRV_DEVICE_ADD(_tag, EXAMPLE1, 0) \
MDRV_DEVICE_CONFIG(_config)

and then the equivalent declaration becomes:

MDRV_EXAMPLE1_ADD("tag", local_structure)

By doing this, we get to provide a cleaner interface for declaration, and at the same time we ensure that a required parameter is specified.

==Runtime Class==

Next we move on to the runtime device class:

class example1_device : public device_t
{
friend class example1_device_config;

// construction/destruction
example1_device(running_machine &machine, const example1_device_config &config);

public:
// any publically acessible interfaces needed for runtime

protected:
// device-level overrides (none are required, but these are common)
virtual void device_start();
virtual void device_reset();

// internal device state goes here
const example1_device_config &m_config;
int m_device_state;
};

Going through the class definition, there are some similar patterns to the corresponding device configuration class:

* Again, we derive from a common base class, in this case the '''device_t''' class. However, unlike the configuration class, we just have simple single inheritance here, since we don't need the '''example1_device_config_data''' struct.

* We make our configuration class our friend, just as they made us their friend. Really, you should imagine these two classes as two halves of the entire device.

* As with the configuration class, our constructor is kept private. A device should only be allocated via the corresponding configuration class's '''alloc_device'''() method. Since our configuration class is our friend, it can still allocate us.

* There are no standard methods that need to be public in the runtime device. However, it is quite likely you will need some in order to interact with it (read/write handlers fall into this category, for example).

* This example overrides two device-specific notification methods, one which is called at device start time (after all devices are constructed), and one which is called at reset time. These are optional, though common, to override.

* At the bottom you'll see a reference to our configuration class. This is kept to enable easy access to the configuration data.

Looking at each of the methods above in a little detail, we first encounter the constructor:

example1_device::example1_device(running_machine &machine, const example1_device_config &config)
: device_t(machine, config),
m_config(config),
m_device_state(0)
{
}

Here we initialize our parent class by passing down the reference to the running_machine and our configuration. We also stash a reference to our configuration into the m_config variable for later use, and we reset all our internal state variables to something well-defined. Note that we don't generally do much initialization in the constructor; that work is preferred to live in the '''device_start'''() method.

Speaking of which...

example1_device::device_start()
{
// initialize state from configuration
// locate any other devices
// if other devices not ready, throw device_missing_dependencies()
// register for any save state
}

Okay, not much meat in the implementation above, but there are a number of things expected of a device during '''device_start'''() time, including consumption of the configuration, identification of related devices, and set up for save states. If a related device is located (at this point all devices are constructed) but it hasn't yet been started, you can throw a '''device_missing_dependencies'''() exception and your '''device_start'''() will be queued to the end of the list to be called again later.

Similarly,

example1_device::device_reset()
{
// reset internal state to well-defined values
}

the '''device_reset'''() method is there to enable resetting a device's state in the event of a requested reset.

=Best Practices=

MAME Device Basics

2010-05-26T20:17:38Z

Aaron: /* Example #1: Simple Device with Static Configuration */

=Overview=

In MAME, a device is a mechanism for encapsulating behavior. While it is common to associate a device (in the MAME sense) with a physical device (in the real world), there does not necessarily need to be a 1:1 correspondance between the two.

Devices are important because they provide clean hooks into the MAME system. They are notified when key things in the system change, they encode their own configuration information, keep their own state, and can be instantiated multiple times within a given machine. They are easily located via a simple string tag, and are first-class citizens in memory maps, so they are easily read from and written to.

As of MAME 0.139, devices are implemented using a collection of C++ classes. In order to provide the flexibility necessary to describe the sorts of devices in MAME, the device model relies heavily on the ''multiple inheritance'' feature of C++ to extend devices with one or more ''device interfaces''.

=Core Concepts=

Every device in the project is built up out of two classes: a device-specific ''configuration class'' (derived from the '''device_config''' class) and a device-specific ''runtime class'' (derived from the '''device_t''' class).

The configuration class is responsible for encapsulating the device's configuration. The base '''device_config''' class automatically supports several core configuration properties, such as a short string ''tag'' to identify the device instance, a ''clock'' value which represents the input clock to the device, and an ''owner'' who serves as the device's parent. All device-specific configuration classes must be derived from the '''device_config''' class at their root.

Of course, most devices require more configuration than this, and so there are mechanisms for the device-specific configuration class to accept further configuration information, both inline in the MACHINE_CONFIG description, as well as externally in a static structure. This additional configuration data is stored in the device-specific class. More details on how this works come later in this article.

In addition to holding the configuration of a device, the device-specific configuration class also serves as a "factory" class that provides a mechanism for the MAME core to instantiate both new configuration objects, via a static method, and new runtime objects, via a required virtual method. (It is worth noting that the pointer to the static method that constructs configuration objects also serves as the device "type", which is a unique single entry point into the device.)

The runtime class, as its name implies, holds the runtime state of a device. The base '''device_t''' class provides a number of basic device concepts, including device initialization, reset, hooks into the save state system, clock scaling. It also holds a reference back to the corresponding '''device_config''' that begat the device.

The device-specific runtime class, which is required to derive from '''device_t''', then contains all the runtime state of the device, along with methods to operate upon the live device. It can also override several internal methods of its parent class to gain access to hooks that are called during specific events in the machine's lifecycle.

=Lifecycle of a Device=

This section aims to describe the two core device classes and how they are used by the system.

==Configuration==

Machine configurations in MAME are represented by a tokenizing mechanism wrapped by macros. A typical machine driver looks something like this (having removed some of the irrelevant details):

static MACHINE_DRIVER_START( pacman )
MDRV_CPU_ADD("maincpu", Z80, MASTER_CLOCK/6)
MDRV_CPU_PROGRAM_MAP(pacman_map)
...
MDRV_SCREEN_ADD("screen", RASTER)
MDRV_SCREEN_FORMAT(BITMAP_FORMAT_INDEXED16)
...
MDRV_SOUND_ADD("namco", NAMCO, MASTER_CLOCK/6/32)
MDRV_SOUND_CONFIG(namco_config)
MDRV_SOUND_ROUTE(ALL_OUTPUTS, "mono", 1.0)
MACHINE_DRIVER_END

When the compiler processes this, the MDRV_* macros all map down to a set of 32-bit or 64-bit integral tokens which are stored as a stream for later processing.

It may not be immediately obvious, but the machine configuration above defines three separate devices: a CPU device called "maincpu", a video screen device called "screen", and a Namco sound device called "namco". Each device generally defines its own MDRV_*_ADD() macro which permits some flexibility in how each device is added. The MDRV_* macros that follow each device provide configuration information. More on configuration in a later chapter.

When a machine configuration is instantiated, it first takes the token stream and executes it, creating a device configuration whenever it sees an MCONFIG_TOKEN_DEVICE_ADD token (which is output by the MDRV_*_ADD() macro mentioned above), and populating the device configuration with data from subsequent macros.

One of the parameters to MCONFIG_TOKEN_DEVICE_ADD is a device type. In MAME a device type is a static function pointer which serves as the factory function for allocating a device configuration. So when we need to add a device, we simply call the factory function and ask it to allocate for us a new device configuration of the appropriate type.

Once the configuration is allocated, we continue to process tokens. Tokens within a certain well-defined range are known to be device configuration tokens, and these are handed off to the allocated device configuration for processing. Specific devices can also support their own custom-defined tokens if they need special behaviors (the MDRV_SOUND_ROUTE above does this) by overriding the '''device_process_token'''() method in the device-specific configuration class.

Upon encountering the end of the token stream, all the devices are notified that the configuration parsing is complete. This allows them to consolidate any configuration information or do any other work that needs to be done. Device-specific configuration classes can override the '''device_config_complete'''() method to hook into this event.

There are several situations in which the machine configuration and all the device configurations are created: to perform validity checks on all the drivers; to output information needed by the -listxml and other front-end functions; to check for vector screens when parsing .ini files; and finally, in preparation for starting an actual game. In all cases but the last one, the machine and device configurations are created and discarded without ever creating any runtime devices, so the device lifecycle can very well begin and end with the device configuration.

In the case where validity checks are performed, the device-specific configuration class has the option of performing its own validation by overriding the '''device_validity_check'''() method and outputting errors if any are found. For this reason, validation should happen here rather than in the '''device_config_complete'''(), so that errors can be reported in a consistent manner.

==Runtime==

When the time comes to create a running machine object and start up the devices, MAME will take the device list contained in the machine configuration and rip through it to allocate the runtime devices. The mechanism for allocating a runtime device is to call the device-specific configuration class's '''device_alloc'''() method, whose job is simply to auto_alloc an instance of the device-specific runtime class. This method is a required override.

Once the entire set of devices has been allocated, MAME will once again run through the list of devices one by one and request them to start. If a device has device-specific work to do at startup (such as allocating memory or consuming configuration information), it can override the '''device_start'''() method to do so. If a device has a dependency upon another device being started, and that other device isn't ready yet, you can throw a '''device_missing_dependencies''' exception from within the '''device_start''' function and you will be re-queued to the end of the initialization order.

An important thing to note is the explicit separation between allocation and startup. All the devices are allocated first, and then all of them are started. The intention is that most of the hard work is done at start time, leaving the class constructor mostly the job of ensuring all local variables are initialized to sane values.

After the devices are all allocated and started, MAME makes one more pass through them all to reset them. As with startup, a device-specific class can override the '''device_reset'''() method to hook into this notification. Unlike startup, which occurs exactly once, a reset may happen multiple times throughout a device's existence. In addition to the first call at startup, all devices are also implicitly reset when a soft or hard reset is performed by the user, or when a driver explicitly calls the device's '''reset'''() method.

Finally, when the emulation is complete, all the devices are destructed. Note that there is no separation between stopping and destruction, as there is between starting and allocation. This means that your device's destructor is responsible for cleaning up any allocations or other side-effects created during the device's lifetime, excepting those allocated via the '''auto_alloc''' macros, which are automatically destroyed shortly afterwards.

In addition to these basic interfaces, there are several other key times when a device is notified. Device-specific hooks are provided for each of these situations, so a simple override is all that is needed to react:

* Prior to saving the state of the system, all the devices are notified. This takes the place of registering handlers via '''state_save_register_presave'''() as was done previously. To hook this, simple override the '''device_pre_save'''() method.

* Similarly, immediately after loading a saved state, all devices are notified. Device-specific classes hook this via the '''device_post_load'''() method.

* If the emulation is started with the debugger enabled, there is a hook '''device_debug_setup'''() which is called to allow device-specific classes to register additional functions or other information with the debugger.

* Finally, if the clock of a device is changed, a notification is sent via the '''device_clock_changed'''() method. This is necessary because most clock management is handled generically in the base '''device_t''' class.

=Configuring Devices=

Device configuration comes in two flavors, static configuration and inline configuration. The decision as to which to use is fairly arbitrary -- and in fact both can be used at the same time! The example from the Lifecycle of a Device chapter demonstrates the use of both types of configuration:

static MACHINE_DRIVER_START( pacman )
MDRV_CPU_ADD("maincpu", Z80, MASTER_CLOCK/6)
MDRV_CPU_PROGRAM_MAP(pacman_map) // inline configuration
...
MDRV_SCREEN_ADD("screen", RASTER)
MDRV_SCREEN_FORMAT(BITMAP_FORMAT_INDEXED16) // inline configuration
...
MDRV_SOUND_ADD("namco", NAMCO, MASTER_CLOCK/6/32)
MDRV_SOUND_CONFIG(namco_config) // static configuration
MDRV_SOUND_ROUTE(ALL_OUTPUTS, "mono", 1.0) // AND inline configuration
MACHINE_DRIVER_END

Let's start by examining how static configuration work, as they are the simplest to understand. A static configuration is simply a single pointer to a constant structure, defined by the game driver, and expressed via the token stream as an MCONFIG_TOKEN_DEVICE_CONFIG token, followed by a pointer to the structure.

Within a machine driver configuration, a static configuration is specified by a MDRV_DEVICE_CONFIG() macro. Certain devices and device types might also provide aliases to this, like the MDRV_SOUND_CONFIG() macro above. If you look at the pacman.c driver, you'll see the configuration structure:

static const namco_interface namco_config =
{
3, /* number of voices */
0 /* stereo */
};

When a driver specifies a static configuration, the pointer is extracted from the token stream and deposited into the void pointer '''m_static_config''', stored by the '''device_config''' base class. The driver-specific configuration class can then consume this pointer when its '''device_config_complete'''() method is called, or it can leave it around for the device itself to consume when it is later instantiated (see the Best Practices section for recommendations on how to cleanly consume the static configuration).

Inline configurations, by contrast, don't require an external structure. Instead, all the information needed to configure the device is specified inline via the machine configuration macros. The way this works is that the base '''device_config''' class has a small array '''m_inline_data'''[] of 64-bit values, which can be populated via the MCONFIG_TOKEN_DEVICE_INLINE_DATA* tokens. Each token specifies an index in the array, along with a 16-bit, 32-bit, or 64-bit data value to be stored there.

The raw macros used to emit the tokens that specify inline data look like this:

MDRV_DEVICE_INLINE_DATA16(index, data)
MDRV_DEVICE_INLINE_DATA32(index, data)
MDRV_DEVICE_INLINE_DATA64(index, data)

Note that the size (16, 32, 64) reflects the number of bits needed to hold the maximum data value. Regardless of the size specified here, the '''m_inline_data'''[] array is always an array of 64-bit values. Care should be used if a signed value is truncated to 16 bits via the MDRV_DEVICE_INLINE_DATA16() macro. When extracting the result from the '''m_inline_data'''[] array, it needs to be explicitly sign-extended.

The indexes that map which data is stored in which entry in the inline data array should be defined as a public enumeration within the device-specific configuration class. This keeps the global namespace less polluted and ensures no overlapping of indices.

In all cases, it is recommended that devices using inline data define nicer, more descriptive macros for specifying that data, rather than encouraging the user to operate with raw data and indexes. These custom macros can allow for more compact specification of the data, and can even be combined with the device's custom MDRV_DEVICE_ADD() macro to further simplify things for the user. Here's an example:

#define MDRV_SPEAKER_ADD(_tag, _x, _y, _z) \
MDRV_DEVICE_ADD(_tag, SPEAKER, 0) \
MDRV_DEVICE_INLINE_DATA32(speaker_device_config::INLINE_X, (_x) * (double)(1 << 24)) \
MDRV_DEVICE_INLINE_DATA32(speaker_device_config::INLINE_Y, (_y) * (double)(1 << 24)) \
MDRV_DEVICE_INLINE_DATA32(speaker_device_config::INLINE_Z, (_z) * (double)(1 << 24))

In this case, a single line in the machine configuration:

MDRV_SPEAKER_ADD("center", 0.0, 0.0, 1.0)

not only adds the device but also specifies all of its required parameters inline. (Note that because the parameters are floating-point values, they are converted to 8.24 fixed point first, since only integral values can be stored in the inline data array.)

=Example #1: Simple Device with Static Configuration=

This example is broken into two subsections, describing the configuration class and then the runtime class.

==Static Configuration Structure==

For this example, we will define a new device that uses a static configuration. Drivers using this device will need to declare a static const instance of the '''example1_device_config_data''' struct below and specify a pointer to that struct as part of the machine configuration.

Starting with the header file, we first define what the '''example1_device_config_data''' struct looks like:

struct example1_device_config_data
{
int m_device_integer_data;
const char * m_device_string_data;
};

This structure can contain pretty much anything. However, it is very important that the struct be a "plain old data" (or POD) type. This means that there should be no constructor and no virtual methods. The reason for this is that there are thousands of drivers defined in the system, and if each of them defined a static const structure like this that needed to execute its constructor on startup, it would adversely impact the overall startup time of the emulator. So just don't do it.

==Configuration Class==

Next, we define the device configuration class:

class example1_device_config : public device_config,
public example1_device_config_data
{
friend class example1_device;

// construction/destruction
example1_device_config(const machine_config &mconfig, device_type type, const char *tag,
const device_config *owner, UINT32 clock);

public:
// allocators
static device_config *static_alloc_device_config(const machine_config &mconfig,
const char *tag, const device_config *owner, UINT32 clock);
virtual device_t *alloc_device(running_machine &machine, const device_config &config) const;

// basic information getters
virtual const char *name() const { return "Example Device 1"; }

// add accessors for any device-specific config that might be needed publically

protected:
// device-level overrides
virtual void device_config_complete();
virtual bool device_validity_check(const game_driver &driver) const;

// internal state
int m_additional_state;
};

Ok, there is a lot of good and subtle information here. Let's walk through the declaration step by step:

* First thing to note is that the class is defined as inheriting from both '''device_config''' and '''example1_device_config_data''' (our static configuration structure). While it is not strictly necessary, it is convenient to do so because the members of the '''example1_device_config_data''' struct effectively become members of the device configuration class, making them easier to access without extra indirection. Making this work also implies copying the user provided data up into your configuration class, which is done later in the '''device_config_complete''' method.

* Next you'll see we added '''example1_device''' as a friend class. In general, it is recommended to keep your configuration state private/protected, but allow the associated device to have free access to it by friending it. If external code needs to query your configuration directly, just add simple accessors to the configuration state (the need for this should be rare).

* The constructor for the configuration class is kept private. The only way to allocate a new instance of a device configuration is via the static method '''static_alloc_device_config'''(). The parameters passed to the constructor in this example are the ones that need to be passed onto the base '''device_config''' class.

Walking through the methods defined in this class one by one, most of them are fairly simple and straightforward. First, the constructor:

example1_device_config::example1_device_config(const machine_config &mconfig, const char *tag,
const device_config *owner, UINT32 clock)
: device_config(mconfig, static_alloc_device_config, tag, owner, clock),
m_additional_state(0)
{
}

As you can see, most of the parameters just pass through to the base class. But be sure to initialize all configuration member variables here to ensure they get proper values. We could initialize the members of the '''example1_device_config_data''' class here as well, but we'll wait until the configuration step is complete.

Next up is the static device configuration allocator:

device_config *example1_device_config::static_alloc_device_config(const machine_config &mconfig,
const char *tag, const device_config *owner, UINT32 clock)
{
return global_alloc(example1_device_config(mconfig, tag, owner, clock));
}

This function is required to be present, as the pointer to this function is used to identify the device type. Given just this function pointer, a configuration object can be constructed, and from there, the device can be created. Note that we need to use '''global_alloc''' here because the running_machine has not yet be created (and in fact never may be). Also note that we return a pointer to the base '''device_config''' class here, since the machine configuration only knows about the base classes.

The device allocator function follows, and it is also required:

device_t *example1_device_config::alloc_device(running_machine &machine) const
{
return auto_alloc(&machine, example1_device(machine, *this));
}

In contrast to the configuration allocator, which is static and uses '''global_alloc''', the device allocator is a virtual method that uses '''auto_alloc''' in order to allocate the device and assign its memory to the provided running machine. When we construct the actual device object, we pass the machine through along with a reference to ourself so that the newly created device can have access to our configuration information.

Once all the device configurations have been created and populated, the '''device_config_complete''' method is called. We override it here to set up our inherited copy of the static configuration structure:

void example1_device_config::device_config_complete()
{
// copy static configuration if present
if (m_static_config != NULL)
*static_cast<example1_device_config_data *>(this) =
*reinterpret_cast<const example1_device_config_data *>(m_static_config);

// otherwise, initialize it to defaults
else
{
m_device_integer_data = DEFAULT_INT_VALUE;
m_device_string_data = NULL;
}
}

In the case where the user specified a pointer to a static configuration data structure, we copy it into ourselves. We use static_cast to find the pointer to where the inherited state lives within our structure and then copy the data pointed to by '''m_static_config'''. If no configuration data was provided, we take this opportunity to initialize the inherited configuration structure to default values.

Finally, if the device wishes to provide stronger validation of data -- verified both when starting a game as well as when running MAME with the -validate option -- it can ovverride the '''device_validity_check''' method:

bool example1_device_config::device_validity_check(const game_driver &driver) const
{
bool error = false;

// sanity check configuration
if (m_device_integer_value < 0)
{
mame_printf_error("%s: %s device '%s' has invalid integer parameter\n",
driver.source_file, driver.name, tag());
error = true;
}
return error;
}

This method should examing the configuration data, output friendly errors and warnings, and return true if a fatal error was detected.

==Configuration Macros==

Now we need to declare how to reference the device from a machine configuration. This is done via special tokenizing macros:

MDRV_DEVICE_ADD("tag", DEVICE_TYPE, device_clock)
MDRV_DEVICE_REPLACE("tag", DEVICE_TYPE, device_clock)

So the first thing we need to define is our ALL_CAPS DEVICE_TYPE. As mentiond previously, the device type is simply a pointer to the static '''static_alloc_device_config'''() method, so it should be defined like so:

static const device_type EXAMPLE1 = example1_device_config::static_alloc_device_config;

Although this is all that is required at a minimum, in general it is considered a good idea to provide your own set of MDRV macros that are specific to your device. By defining our macros, we can more precisely guide the user to ensure all data is properly specified. Let's say for example that our static configuration is required (i.e., it is invalid to not specify anything). Using the raw macros, a driver writer would declare an instance of our device like this:

MDRV_DEVICE_ADD("tag", EXAMPLE1, 0)
MDRV_DEVICE_CONFIG(local_structure)

Given this, you can see that it would be easy to forget the second line and leave a device with no configuration data. Also, the user is forced to specify a dummy clock, even though our device doesn't need one. Instead, let's define our own macro for adding an EXAMPLE1 device, like so:

#define MDRV_EXAMPLE1_ADD(_tag, _config) \
MDRV_DEVICE_ADD(_tag, EXAMPLE1, 0) \
MDRV_DEVICE_CONFIG(_config)

and then the equivalent declaration becomes:

MDRV_EXAMPLE1_ADD("tag", local_structure)

By doing this, we get to provide a cleaner interface for declaration, and at the same time we ensure that a required parameter is specified.

==Runtime Class==

Next we move on to the runtime device class:

class example1_device : public device_t
{
friend class example1_device_config;

// construction/destruction
example1_device(running_machine &machine, const example1_device_config &config);

public:
// any publically acessible interfaces needed for runtime

protected:
// device-level overrides (none are required, but these are common)
virtual void device_start();
virtual void device_reset();

// internal device state goes here
const example1_device_config &m_config;
int m_device_state;
};

Going through the class definition, there are some similar patterns to the corresponding device configuration class:

* Again, we derive from a common base class, in this case the '''device_t''' class. However, unlike the configuration class, we just have simple single inheritance here, since we don't need the '''example1_device_config_data''' struct.

* We make our configuration class our friend, just as they made us their friend. Really, you should imagine these two classes as two halves of the entire device.

* As with the configuration class, our constructor is kept private. A device should only be allocated via the corresponding configuration class's '''alloc_device'''() method. Since our configuration class is our friend, it can still allocate us.

* There are no standard methods that need to be public in the runtime device. However, it is quite likely you will need some in order to interact with it (read/write handlers fall into this category, for example).

* This example overrides two device-specific notification methods, one which is called at device start time (after all devices are constructed), and one which is called at reset time. These are optional, though common, to override.

* At the bottom you'll see a reference to our configuration class. This is kept to enable easy access to the configuration data.

Looking at each of the methods above in a little detail, we first encounter the constructor:

example1_device::example1_device(running_machine &machine, const example1_device_config &config)
: device_t(machine, config),
m_config(config),
m_device_state(0)
{
}

Here we initialize our parent class by passing down the reference to the running_machine and our configuration. We also stash a reference to our configuration into the m_config variable for later use, and we reset all our internal state variables to something well-defined. Note that we don't generally do much initialization in the constructor; that work is preferred to live in the '''device_start'''() method.

Speaking of which...

example1_device::device_start()
{
// initialize state from configuration
// locate any other devices
// if other devices not ready, throw device_missing_dependencies()
// register for any save state
}

Okay, not much meat in the implementation above, but there are a number of things expected of a device during '''device_start'''() time, including consumption of the configuration, identification of related devices, and set up for save states. If a related device is located (at this point all devices are constructed) but it hasn't yet been started, you can throw a '''device_missing_dependencies'''() exception and your '''device_start'''() will be queued to the end of the list to be called again later.

Similarly,

example1_device::device_reset()
{
// reset internal state to well-defined values
}

the '''device_reset'''() method is there to enable resetting a device's state in the event of a requested reset.

=Best Practices=

MAME Device Basics

2010-05-25T05:07:57Z

Aaron: /* Example #1: Simple Device with Static Configuration */

=Overview=

In MAME, a device is a mechanism for encapsulating behavior. While it is common to associate a device (in the MAME sense) with a physical device (in the real world), there does not necessarily need to be a 1:1 correspondance between the two.

Devices are important because they provide clean hooks into the MAME system. They are notified when key things in the system change, they encode their own configuration information, keep their own state, and can be instantiated multiple times within a given machine. They are easily located via a simple string tag, and are first-class citizens in memory maps, so they are easily read from and written to.

As of MAME 0.139, devices are implemented using a collection of C++ classes. In order to provide the flexibility necessary to describe the sorts of devices in MAME, the device model relies heavily on the ''multiple inheritance'' feature of C++ to extend devices with one or more ''device interfaces''.

=Core Concepts=

Every device in the project is built up out of two classes: a device-specific ''configuration class'' (derived from the '''device_config''' class) and a device-specific ''runtime class'' (derived from the '''device_t''' class).

The configuration class is responsible for encapsulating the device's configuration. The base '''device_config''' class automatically supports several core configuration properties, such as a short string ''tag'' to identify the device instance, a ''clock'' value which represents the input clock to the device, and an ''owner'' who serves as the device's parent. All device-specific configuration classes must be derived from the '''device_config''' class at their root.

Of course, most devices require more configuration than this, and so there are mechanisms for the device-specific configuration class to accept further configuration information, both inline in the MACHINE_CONFIG description, as well as externally in a static structure. This additional configuration data is stored in the device-specific class. More details on how this works come later in this article.

In addition to holding the configuration of a device, the device-specific configuration class also serves as a "factory" class that provides a mechanism for the MAME core to instantiate both new configuration objects, via a static method, and new runtime objects, via a required virtual method. (It is worth noting that the pointer to the static method that constructs configuration objects also serves as the device "type", which is a unique single entry point into the device.)

The runtime class, as its name implies, holds the runtime state of a device. The base '''device_t''' class provides a number of basic device concepts, including device initialization, reset, hooks into the save state system, clock scaling. It also holds a reference back to the corresponding '''device_config''' that begat the device.

The device-specific runtime class, which is required to derive from '''device_t''', then contains all the runtime state of the device, along with methods to operate upon the live device. It can also override several internal methods of its parent class to gain access to hooks that are called during specific events in the machine's lifecycle.

=Lifecycle of a Device=

This section aims to describe the two core device classes and how they are used by the system.

==Configuration==

Machine configurations in MAME are represented by a tokenizing mechanism wrapped by macros. A typical machine driver looks something like this (having removed some of the irrelevant details):

static MACHINE_DRIVER_START( pacman )
MDRV_CPU_ADD("maincpu", Z80, MASTER_CLOCK/6)
MDRV_CPU_PROGRAM_MAP(pacman_map)
...
MDRV_SCREEN_ADD("screen", RASTER)
MDRV_SCREEN_FORMAT(BITMAP_FORMAT_INDEXED16)
...
MDRV_SOUND_ADD("namco", NAMCO, MASTER_CLOCK/6/32)
MDRV_SOUND_CONFIG(namco_config)
MDRV_SOUND_ROUTE(ALL_OUTPUTS, "mono", 1.0)
MACHINE_DRIVER_END

When the compiler processes this, the MDRV_* macros all map down to a set of 32-bit or 64-bit integral tokens which are stored as a stream for later processing.

It may not be immediately obvious, but the machine configuration above defines three separate devices: a CPU device called "maincpu", a video screen device called "screen", and a Namco sound device called "namco". Each device generally defines its own MDRV_*_ADD() macro which permits some flexibility in how each device is added. The MDRV_* macros that follow each device provide configuration information. More on configuration in a later chapter.

When a machine configuration is instantiated, it first takes the token stream and executes it, creating a device configuration whenever it sees an MCONFIG_TOKEN_DEVICE_ADD token (which is output by the MDRV_*_ADD() macro mentioned above), and populating the device configuration with data from subsequent macros.

One of the parameters to MCONFIG_TOKEN_DEVICE_ADD is a device type. In MAME a device type is a static function pointer which serves as the factory function for allocating a device configuration. So when we need to add a device, we simply call the factory function and ask it to allocate for us a new device configuration of the appropriate type.

Once the configuration is allocated, we continue to process tokens. Tokens within a certain well-defined range are known to be device configuration tokens, and these are handed off to the allocated device configuration for processing. Specific devices can also support their own custom-defined tokens if they need special behaviors (the MDRV_SOUND_ROUTE above does this) by overriding the '''device_process_token'''() method in the device-specific configuration class.

Upon encountering the end of the token stream, all the devices are notified that the configuration parsing is complete. This allows them to consolidate any configuration information or do any other work that needs to be done. Device-specific configuration classes can override the '''device_config_complete'''() method to hook into this event.

There are several situations in which the machine configuration and all the device configurations are created: to perform validity checks on all the drivers; to output information needed by the -listxml and other front-end functions; to check for vector screens when parsing .ini files; and finally, in preparation for starting an actual game. In all cases but the last one, the machine and device configurations are created and discarded without ever creating any runtime devices, so the device lifecycle can very well begin and end with the device configuration.

In the case where validity checks are performed, the device-specific configuration class has the option of performing its own validation by overriding the '''device_validity_check'''() method and outputting errors if any are found. For this reason, validation should happen here rather than in the '''device_config_complete'''(), so that errors can be reported in a consistent manner.

==Runtime==

When the time comes to create a running machine object and start up the devices, MAME will take the device list contained in the machine configuration and rip through it to allocate the runtime devices. The mechanism for allocating a runtime device is to call the device-specific configuration class's '''device_alloc'''() method, whose job is simply to auto_alloc an instance of the device-specific runtime class. This method is a required override.

Once the entire set of devices has been allocated, MAME will once again run through the list of devices one by one and request them to start. If a device has device-specific work to do at startup (such as allocating memory or consuming configuration information), it can override the '''device_start'''() method to do so. If a device has a dependency upon another device being started, and that other device isn't ready yet, you can throw a '''device_missing_dependencies''' exception from within the '''device_start''' function and you will be re-queued to the end of the initialization order.

An important thing to note is the explicit separation between allocation and startup. All the devices are allocated first, and then all of them are started. The intention is that most of the hard work is done at start time, leaving the class constructor mostly the job of ensuring all local variables are initialized to sane values.

After the devices are all allocated and started, MAME makes one more pass through them all to reset them. As with startup, a device-specific class can override the '''device_reset'''() method to hook into this notification. Unlike startup, which occurs exactly once, a reset may happen multiple times throughout a device's existence. In addition to the first call at startup, all devices are also implicitly reset when a soft or hard reset is performed by the user, or when a driver explicitly calls the device's '''reset'''() method.

Finally, when the emulation is complete, all the devices are destructed. Note that there is no separation between stopping and destruction, as there is between starting and allocation. This means that your device's destructor is responsible for cleaning up any allocations or other side-effects created during the device's lifetime, excepting those allocated via the '''auto_alloc''' macros, which are automatically destroyed shortly afterwards.

In addition to these basic interfaces, there are several other key times when a device is notified. Device-specific hooks are provided for each of these situations, so a simple override is all that is needed to react:

* Prior to saving the state of the system, all the devices are notified. This takes the place of registering handlers via '''state_save_register_presave'''() as was done previously. To hook this, simple override the '''device_pre_save'''() method.

* Similarly, immediately after loading a saved state, all devices are notified. Device-specific classes hook this via the '''device_post_load'''() method.

* If the emulation is started with the debugger enabled, there is a hook '''device_debug_setup'''() which is called to allow device-specific classes to register additional functions or other information with the debugger.

* Finally, if the clock of a device is changed, a notification is sent via the '''device_clock_changed'''() method. This is necessary because most clock management is handled generically in the base '''device_t''' class.

=Configuring Devices=

Device configuration comes in two flavors, static configuration and inline configuration. The decision as to which to use is fairly arbitrary -- and in fact both can be used at the same time! The example from the Lifecycle of a Device chapter demonstrates the use of both types of configuration:

static MACHINE_DRIVER_START( pacman )
MDRV_CPU_ADD("maincpu", Z80, MASTER_CLOCK/6)
MDRV_CPU_PROGRAM_MAP(pacman_map) // inline configuration
...
MDRV_SCREEN_ADD("screen", RASTER)
MDRV_SCREEN_FORMAT(BITMAP_FORMAT_INDEXED16) // inline configuration
...
MDRV_SOUND_ADD("namco", NAMCO, MASTER_CLOCK/6/32)
MDRV_SOUND_CONFIG(namco_config) // static configuration
MDRV_SOUND_ROUTE(ALL_OUTPUTS, "mono", 1.0) // AND inline configuration
MACHINE_DRIVER_END

Let's start by examining how static configuration work, as they are the simplest to understand. A static configuration is simply a single pointer to a constant structure, defined by the game driver, and expressed via the token stream as an MCONFIG_TOKEN_DEVICE_CONFIG token, followed by a pointer to the structure.

Within a machine driver configuration, a static configuration is specified by a MDRV_DEVICE_CONFIG() macro. Certain devices and device types might also provide aliases to this, like the MDRV_SOUND_CONFIG() macro above. If you look at the pacman.c driver, you'll see the configuration structure:

static const namco_interface namco_config =
{
3, /* number of voices */
0 /* stereo */
};

When a driver specifies a static configuration, the pointer is extracted from the token stream and deposited into the void pointer '''m_static_config''', stored by the '''device_config''' base class. The driver-specific configuration class can then consume this pointer when its '''device_config_complete'''() method is called, or it can leave it around for the device itself to consume when it is later instantiated (see the Best Practices section for recommendations on how to cleanly consume the static configuration).

Inline configurations, by contrast, don't require an external structure. Instead, all the information needed to configure the device is specified inline via the machine configuration macros. The way this works is that the base '''device_config''' class has a small array '''m_inline_data'''[] of 64-bit values, which can be populated via the MCONFIG_TOKEN_DEVICE_INLINE_DATA* tokens. Each token specifies an index in the array, along with a 16-bit, 32-bit, or 64-bit data value to be stored there.

The raw macros used to emit the tokens that specify inline data look like this:

MDRV_DEVICE_INLINE_DATA16(index, data)
MDRV_DEVICE_INLINE_DATA32(index, data)
MDRV_DEVICE_INLINE_DATA64(index, data)

Note that the size (16, 32, 64) reflects the number of bits needed to hold the maximum data value. Regardless of the size specified here, the '''m_inline_data'''[] array is always an array of 64-bit values. Care should be used if a signed value is truncated to 16 bits via the MDRV_DEVICE_INLINE_DATA16() macro. When extracting the result from the '''m_inline_data'''[] array, it needs to be explicitly sign-extended.

The indexes that map which data is stored in which entry in the inline data array should be defined as a public enumeration within the device-specific configuration class. This keeps the global namespace less polluted and ensures no overlapping of indices.

In all cases, it is recommended that devices using inline data define nicer, more descriptive macros for specifying that data, rather than encouraging the user to operate with raw data and indexes. These custom macros can allow for more compact specification of the data, and can even be combined with the device's custom MDRV_DEVICE_ADD() macro to further simplify things for the user. Here's an example:

#define MDRV_SPEAKER_ADD(_tag, _x, _y, _z) \
MDRV_DEVICE_ADD(_tag, SPEAKER, 0) \
MDRV_DEVICE_INLINE_DATA32(speaker_device_config::INLINE_X, (_x) * (double)(1 << 24)) \
MDRV_DEVICE_INLINE_DATA32(speaker_device_config::INLINE_Y, (_y) * (double)(1 << 24)) \
MDRV_DEVICE_INLINE_DATA32(speaker_device_config::INLINE_Z, (_z) * (double)(1 << 24))

In this case, a single line in the machine configuration:

MDRV_SPEAKER_ADD("center", 0.0, 0.0, 1.0)

not only adds the device but also specifies all of its required parameters inline. (Note that because the parameters are floating-point values, they are converted to 8.24 fixed point first, since only integral values can be stored in the inline data array.)

=Example #1: Simple Device with Static Configuration=

For this example, we will define a new device that uses a static configuration. Drivers using this device will need to declare a static const instance of the '''example1_device_config_data''' struct below and specify a pointer to that struct as part of the machine configuration.

Starting with the header file, we first define what the '''example1_device_config_data''' struct looks like:

struct example1_device_config_data
{
int m_device_integer_data;
const char * m_device_string_data;
};

This structure can contain pretty much anything. However, it is very important that the struct be a "plain old data" (or POD) type. This means that there should be no constructor and no virtual methods. The reason for this is that there are thousands of drivers defined in the system, and if each of them defined a static const structure like this that needed to execute its constructor on startup, it would adversely impact the overall startup time of the emulator. So just don't do it.

Next, we define the device configuration class:

class example1_device_config : public device_config,
public example1_device_config_data
{
friend class example1_device;

// construction/destruction
example1_device_config(const machine_config &mconfig, device_type type, const char *tag,
const device_config *owner, UINT32 clock);

public:
// allocators
static device_config *static_alloc_device_config(const machine_config &mconfig,
const char *tag, const device_config *owner, UINT32 clock);
virtual device_t *alloc_device(running_machine &machine, const device_config &config) const;

// basic information getters
virtual const char *name() const { return "Example Device 1"; }

// add accessors for any device-specific config that might be needed publically

protected:
// device-level overrides
virtual void device_config_complete();
virtual bool device_validity_check(const game_driver &driver) const;

// internal state
int m_additional_state;
};

Ok, there is a lot of good and subtle information here. Let's walk through the declaration step by step:

* First thing to note is that the class is defined as inheriting from both '''device_config''' and '''example1_device_config_data''' (our static configuration structure). While it is not strictly necessary, it is convenient to do so because the members of the '''example1_device_config_data''' struct effectively become members of the device configuration class, making them easier to access without extra indirection. Making this work also implies copying the user provided data up into your configuration class, which is done later in the '''device_config_complete''' method.

* Next you'll see we added '''example1_device''' as a friend class. In general, it is recommended to keep your configuration state private/protected, but allow the associated device to have free access to it by friending it. If external code needs to query your configuration directly, just add simple accessors to the configuration state (the need for this should be rare).

* If the configuration requires a destructor, then you will either need to

* The constructor for the configuration class is kept private. The only way to allocate a new instance of a device configuration is via the static method '''static_alloc_device_config'''(). The parameters passed to the constructor in this example are the ones that need to be passed onto the base '''device_config''' class.

Walking through the methods defined in this class one by one, most of them are fairly simple and straightforward. First, the constructor:

example1_device_config::example1_device_config(const machine_config &mconfig, const char *tag,
const device_config *owner, UINT32 clock)
: device_config(mconfig, static_alloc_device_config, tag, owner, clock),
m_additional_state(0)
{
}

As you can see, most of the parameters just pass through to the base class. But be sure to initialize all configuration member variables here to ensure they get proper values. We could initialize the members of the '''example1_device_config_data''' class here as well, but we'll wait until the configuration step is complete.

Next up is the static device configuration allocator:

device_config *example1_device_config::static_alloc_device_config(const machine_config &mconfig,
const char *tag, const device_config *owner, UINT32 clock)
{
return global_alloc(example1_device_config(mconfig, tag, owner, clock));
}

This function is required to be present, as the pointer to this function is used to identify the device type. Given just this function pointer, a configuration object can be constructed, and from there, the device can be created. Note that we need to use '''global_alloc''' here because the running_machine has not yet be created (and in fact never may be). Also note that we return a pointer to the base '''device_config''' class here, since the machine configuration only knows about the base classes.

The device allocator function follows, and it is also required:

device_t *example1_device_config::alloc_device(running_machine &machine) const
{
return auto_alloc(&machine, example1_device(machine, *this));
}

In contrast to the configuration allocator, which is static and uses '''global_alloc''', the device allocator is a virtual method that uses '''auto_alloc''' in order to allocate the device and assign its memory to the provided running machine. When we construct the actual device object, we pass the machine through along with a reference to ourself so that the newly created device can have access to our configuration information.

Once all the device configurations have been created and populated, the '''device_config_complete''' method is called. We override it here to set up our inherited copy of the static configuration structure:

void example1_device_config::device_config_complete()
{
// copy static configuration if present
if (m_static_config != NULL)
*static_cast<example1_device_config_data *>(this) =
*reinterpret_cast<const example1_device_config_data *>(m_static_config);

// otherwise, initialize it to defaults
else
{
m_device_integer_data = DEFAULT_INT_VALUE;
m_device_string_data = NULL;
}
}

In the case where the user specified a pointer to a static configuration data structure, we copy it into ourselves. We use static_cast to find the pointer to where the inherited state lives within our structure and then copy the data pointed to by '''m_static_config'''. If no configuration data was provided, we take this opportunity to initialize the inherited configuration structure to default values.

Finally, if the device wishes to provide stronger validation of data -- verified both when starting a game as well as when running MAME with the -validate option -- it can ovverride the '''device_validity_check''' method:

bool example1_device_config::device_validity_check(const game_driver &driver) const
{
bool error = false;

// sanity check configuration
if (m_device_integer_value < 0)
{
mame_printf_error("%s: %s device '%s' has invalid integer parameter\n",
driver.source_file, driver.name, tag());
error = true;
}
return error;
}

This method should examing the configuration data, output friendly errors and warnings, and return true if a fatal error was detected.

=Best Practices=

MAME Device Basics

2010-05-24T20:26:25Z

Aaron: /* Example #1: Simple Device with Static Configuration */

=Overview=

In MAME, a device is a mechanism for encapsulating behavior. While it is common to associate a device (in the MAME sense) with a physical device (in the real world), there does not necessarily need to be a 1:1 correspondance between the two.

Devices are important because they provide clean hooks into the MAME system. They are notified when key things in the system change, they encode their own configuration information, keep their own state, and can be instantiated multiple times within a given machine. They are easily located via a simple string tag, and are first-class citizens in memory maps, so they are easily read from and written to.

As of MAME 0.139, devices are implemented using a collection of C++ classes. In order to provide the flexibility necessary to describe the sorts of devices in MAME, the device model relies heavily on the ''multiple inheritance'' feature of C++ to extend devices with one or more ''device interfaces''.

=Core Concepts=

Every device in the project is built up out of two classes: a device-specific ''configuration class'' (derived from the '''device_config''' class) and a device-specific ''runtime class'' (derived from the '''device_t''' class).

The configuration class is responsible for encapsulating the device's configuration. The base '''device_config''' class automatically supports several core configuration properties, such as a short string ''tag'' to identify the device instance, a ''clock'' value which represents the input clock to the device, and an ''owner'' who serves as the device's parent. All device-specific configuration classes must be derived from the '''device_config''' class at their root.

Of course, most devices require more configuration than this, and so there are mechanisms for the device-specific configuration class to accept further configuration information, both inline in the MACHINE_CONFIG description, as well as externally in a static structure. This additional configuration data is stored in the device-specific class. More details on how this works come later in this article.

In addition to holding the configuration of a device, the device-specific configuration class also serves as a "factory" class that provides a mechanism for the MAME core to instantiate both new configuration objects, via a static method, and new runtime objects, via a required virtual method. (It is worth noting that the pointer to the static method that constructs configuration objects also serves as the device "type", which is a unique single entry point into the device.)

The runtime class, as its name implies, holds the runtime state of a device. The base '''device_t''' class provides a number of basic device concepts, including device initialization, reset, hooks into the save state system, clock scaling. It also holds a reference back to the corresponding '''device_config''' that begat the device.

The device-specific runtime class, which is required to derive from '''device_t''', then contains all the runtime state of the device, along with methods to operate upon the live device. It can also override several internal methods of its parent class to gain access to hooks that are called during specific events in the machine's lifecycle.

=Lifecycle of a Device=

This section aims to describe the two core device classes and how they are used by the system.

==Configuration==

Machine configurations in MAME are represented by a tokenizing mechanism wrapped by macros. A typical machine driver looks something like this (having removed some of the irrelevant details):

static MACHINE_DRIVER_START( pacman )
MDRV_CPU_ADD("maincpu", Z80, MASTER_CLOCK/6)
MDRV_CPU_PROGRAM_MAP(pacman_map)
...
MDRV_SCREEN_ADD("screen", RASTER)
MDRV_SCREEN_FORMAT(BITMAP_FORMAT_INDEXED16)
...
MDRV_SOUND_ADD("namco", NAMCO, MASTER_CLOCK/6/32)
MDRV_SOUND_CONFIG(namco_config)
MDRV_SOUND_ROUTE(ALL_OUTPUTS, "mono", 1.0)
MACHINE_DRIVER_END

When the compiler processes this, the MDRV_* macros all map down to a set of 32-bit or 64-bit integral tokens which are stored as a stream for later processing.

It may not be immediately obvious, but the machine configuration above defines three separate devices: a CPU device called "maincpu", a video screen device called "screen", and a Namco sound device called "namco". Each device generally defines its own MDRV_*_ADD() macro which permits some flexibility in how each device is added. The MDRV_* macros that follow each device provide configuration information. More on configuration in a later chapter.

When a machine configuration is instantiated, it first takes the token stream and executes it, creating a device configuration whenever it sees an MCONFIG_TOKEN_DEVICE_ADD token (which is output by the MDRV_*_ADD() macro mentioned above), and populating the device configuration with data from subsequent macros.

One of the parameters to MCONFIG_TOKEN_DEVICE_ADD is a device type. In MAME a device type is a static function pointer which serves as the factory function for allocating a device configuration. So when we need to add a device, we simply call the factory function and ask it to allocate for us a new device configuration of the appropriate type.

Once the configuration is allocated, we continue to process tokens. Tokens within a certain well-defined range are known to be device configuration tokens, and these are handed off to the allocated device configuration for processing. Specific devices can also support their own custom-defined tokens if they need special behaviors (the MDRV_SOUND_ROUTE above does this) by overriding the '''device_process_token'''() method in the device-specific configuration class.

Upon encountering the end of the token stream, all the devices are notified that the configuration parsing is complete. This allows them to consolidate any configuration information or do any other work that needs to be done. Device-specific configuration classes can override the '''device_config_complete'''() method to hook into this event.

There are several situations in which the machine configuration and all the device configurations are created: to perform validity checks on all the drivers; to output information needed by the -listxml and other front-end functions; to check for vector screens when parsing .ini files; and finally, in preparation for starting an actual game. In all cases but the last one, the machine and device configurations are created and discarded without ever creating any runtime devices, so the device lifecycle can very well begin and end with the device configuration.

In the case where validity checks are performed, the device-specific configuration class has the option of performing its own validation by overriding the '''device_validity_check'''() method and outputting errors if any are found. For this reason, validation should happen here rather than in the '''device_config_complete'''(), so that errors can be reported in a consistent manner.

==Runtime==

When the time comes to create a running machine object and start up the devices, MAME will take the device list contained in the machine configuration and rip through it to allocate the runtime devices. The mechanism for allocating a runtime device is to call the device-specific configuration class's '''device_alloc'''() method, whose job is simply to auto_alloc an instance of the device-specific runtime class. This method is a required override.

Once the entire set of devices has been allocated, MAME will once again run through the list of devices one by one and request them to start. If a device has device-specific work to do at startup (such as allocating memory or consuming configuration information), it can override the '''device_start'''() method to do so. If a device has a dependency upon another device being started, and that other device isn't ready yet, you can throw a '''device_missing_dependencies''' exception from within the '''device_start''' function and you will be re-queued to the end of the initialization order.

An important thing to note is the explicit separation between allocation and startup. All the devices are allocated first, and then all of them are started. The intention is that most of the hard work is done at start time, leaving the class constructor mostly the job of ensuring all local variables are initialized to sane values.

After the devices are all allocated and started, MAME makes one more pass through them all to reset them. As with startup, a device-specific class can override the '''device_reset'''() method to hook into this notification. Unlike startup, which occurs exactly once, a reset may happen multiple times throughout a device's existence. In addition to the first call at startup, all devices are also implicitly reset when a soft or hard reset is performed by the user, or when a driver explicitly calls the device's '''reset'''() method.

Finally, when the emulation is complete, all the devices are destructed. Note that there is no separation between stopping and destruction, as there is between starting and allocation. This means that your device's destructor is responsible for cleaning up any allocations or other side-effects created during the device's lifetime, excepting those allocated via the '''auto_alloc''' macros, which are automatically destroyed shortly afterwards.

In addition to these basic interfaces, there are several other key times when a device is notified. Device-specific hooks are provided for each of these situations, so a simple override is all that is needed to react:

* Prior to saving the state of the system, all the devices are notified. This takes the place of registering handlers via '''state_save_register_presave'''() as was done previously. To hook this, simple override the '''device_pre_save'''() method.

* Similarly, immediately after loading a saved state, all devices are notified. Device-specific classes hook this via the '''device_post_load'''() method.

* If the emulation is started with the debugger enabled, there is a hook '''device_debug_setup'''() which is called to allow device-specific classes to register additional functions or other information with the debugger.

* Finally, if the clock of a device is changed, a notification is sent via the '''device_clock_changed'''() method. This is necessary because most clock management is handled generically in the base '''device_t''' class.

=Configuring Devices=

Device configuration comes in two flavors, static configuration and inline configuration. The decision as to which to use is fairly arbitrary -- and in fact both can be used at the same time! The example from the Lifecycle of a Device chapter demonstrates the use of both types of configuration:

static MACHINE_DRIVER_START( pacman )
MDRV_CPU_ADD("maincpu", Z80, MASTER_CLOCK/6)
MDRV_CPU_PROGRAM_MAP(pacman_map) // inline configuration
...
MDRV_SCREEN_ADD("screen", RASTER)
MDRV_SCREEN_FORMAT(BITMAP_FORMAT_INDEXED16) // inline configuration
...
MDRV_SOUND_ADD("namco", NAMCO, MASTER_CLOCK/6/32)
MDRV_SOUND_CONFIG(namco_config) // static configuration
MDRV_SOUND_ROUTE(ALL_OUTPUTS, "mono", 1.0) // AND inline configuration
MACHINE_DRIVER_END

Let's start by examining how static configuration work, as they are the simplest to understand. A static configuration is simply a single pointer to a constant structure, defined by the game driver, and expressed via the token stream as an MCONFIG_TOKEN_DEVICE_CONFIG token, followed by a pointer to the structure.

Within a machine driver configuration, a static configuration is specified by a MDRV_DEVICE_CONFIG() macro. Certain devices and device types might also provide aliases to this, like the MDRV_SOUND_CONFIG() macro above. If you look at the pacman.c driver, you'll see the configuration structure:

static const namco_interface namco_config =
{
3, /* number of voices */
0 /* stereo */
};

When a driver specifies a static configuration, the pointer is extracted from the token stream and deposited into the void pointer '''m_static_config''', stored by the '''device_config''' base class. The driver-specific configuration class can then consume this pointer when its '''device_config_complete'''() method is called, or it can leave it around for the device itself to consume when it is later instantiated (see the Best Practices section for recommendations on how to cleanly consume the static configuration).

Inline configurations, by contrast, don't require an external structure. Instead, all the information needed to configure the device is specified inline via the machine configuration macros. The way this works is that the base '''device_config''' class has a small array '''m_inline_data'''[] of 64-bit values, which can be populated via the MCONFIG_TOKEN_DEVICE_INLINE_DATA* tokens. Each token specifies an index in the array, along with a 16-bit, 32-bit, or 64-bit data value to be stored there.

The raw macros used to emit the tokens that specify inline data look like this:

MDRV_DEVICE_INLINE_DATA16(index, data)
MDRV_DEVICE_INLINE_DATA32(index, data)
MDRV_DEVICE_INLINE_DATA64(index, data)

Note that the size (16, 32, 64) reflects the number of bits needed to hold the maximum data value. Regardless of the size specified here, the '''m_inline_data'''[] array is always an array of 64-bit values. Care should be used if a signed value is truncated to 16 bits via the MDRV_DEVICE_INLINE_DATA16() macro. When extracting the result from the '''m_inline_data'''[] array, it needs to be explicitly sign-extended.

The indexes that map which data is stored in which entry in the inline data array should be defined as a public enumeration within the device-specific configuration class. This keeps the global namespace less polluted and ensures no overlapping of indices.

In all cases, it is recommended that devices using inline data define nicer, more descriptive macros for specifying that data, rather than encouraging the user to operate with raw data and indexes. These custom macros can allow for more compact specification of the data, and can even be combined with the device's custom MDRV_DEVICE_ADD() macro to further simplify things for the user. Here's an example:

#define MDRV_SPEAKER_ADD(_tag, _x, _y, _z) \
MDRV_DEVICE_ADD(_tag, SPEAKER, 0) \
MDRV_DEVICE_INLINE_DATA32(speaker_device_config::INLINE_X, (_x) * (double)(1 << 24)) \
MDRV_DEVICE_INLINE_DATA32(speaker_device_config::INLINE_Y, (_y) * (double)(1 << 24)) \
MDRV_DEVICE_INLINE_DATA32(speaker_device_config::INLINE_Z, (_z) * (double)(1 << 24))

In this case, a single line in the machine configuration:

MDRV_SPEAKER_ADD("center", 0.0, 0.0, 1.0)

not only adds the device but also specifies all of its required parameters inline. (Note that because the parameters are floating-point values, they are converted to 8.24 fixed point first, since only integral values can be stored in the inline data array.)

=Example #1: Simple Device with Static Configuration=

For this example, we will define a new device that uses a static configuration. Drivers using this device will need to declare a static const instance of the '''example1_device_config_data''' struct below and specify a pointer to that struct as part of the machine configuration.

Starting with the header file, we first define what the '''example1_device_config_data''' struct looks like:

struct example1_device_config_data
{
int m_device_integer_data;
const char * m_device_string_data;
};

This structure can contain pretty much anything. However, it is very important that the struct be a "plain old data" (or POD) type. This means that there should be no constructor and no virtual methods. The reason for this is that there are thousands of drivers defined in the system, and if each of them defined a static const structure like this that needed to execute its constructor on startup, it would adversely impact the overall startup time of the emulator. So just don't do it.

Next, we define the device configuration class:

class example1_device_config : public device_config,
public example1_device_config_data
{
friend class example1_device;

// construction/destruction
example1_device_config(const machine_config &mconfig, device_type type, const char *tag,
const device_config *owner, UINT32 clock);
public:
virtual ~example1_device_config();

// allocators
static device_config *static_alloc_device_config(const machine_config &mconfig,
const char *tag, const device_config *owner, UINT32 clock);
virtual device_t *alloc_device(running_machine &machine, const device_config &config) const;

// basic information getters
virtual const char *name() const { return "Example Device 1"; }

// add accessors for any device-specific config that might be needed publically

protected:
// device-level overrides
virtual void device_config_complete();
virtual bool device_validity_check(const game_driver &driver) const;

// internal state
int m_additional_state;
};

Ok, there is a lot of good and subtle information here. Let's walk through the declaration step by step:

* First thing to note is that the class is defined as inheriting from both '''device_config''' and '''example1_device_config_data''' (our static configuration structure). While it is not strictly necessary, it is convenient to do so because the members of the '''example1_device_config_data''' struct effectively become members of the device configuration class, making them easier to access without extra indirection. Making this work also implies copying the user provided data up into your configuration class, which is done later in the '''device_config_complete''' method.

* Next you'll see we added '''example1_device''' as a friend class. In general, it is recommended to keep your configuration state private/protected, but allow the associated device to have free access to it by friending it. If external code needs to query your configuration directly, just add simple accessors to the configuration state (the need for this should be rare).

* The constructor for the configuration class is kept private. The only way to allocate a new instance of a device configuration is via the static method '''static_alloc_device_config'''(). The parameters passed to the constructor in this example are the ones that need to be passed onto the base '''device_config''' class.

* Note that the destructor is virtual. If you fail to do this you will end up partially destructing objects.

Walking through the methods defined in this class one by one, most of them are fairly simple and straightforward. First, the constructor:

example1_device_config::example1_device_config(const machine_config &mconfig, const char *tag,
const device_config *owner, UINT32 clock)
: device_config(mconfig, static_alloc_device_config, tag, owner, clock),
m_additional_state(0)
{
}

As you can see, most of the parameters just pass through to the base class. But be sure to initialize all configuration member variables here to ensure they get proper values. We could initialize the members of the '''example1_device_config_data''' class here as well, but we'll wait until the configuration step is complete.

Next, the destructor:

example1_device_config::~example1_device_config()
{
}

If we had allocated memory in the constructor or elsewhere during configuration, now would be the time to free it. This example doesn't do that, so our destructor is empty.

Next up is the static device configuration allocator:

device_config *example1_device_config::static_alloc_device_config(const machine_config &mconfig,
const char *tag, const device_config *owner, UINT32 clock)
{
return global_alloc(example1_device_config(mconfig, tag, owner, clock));
}

This function is required to be present, as the pointer to this function is used to identify the device type. Given just this function pointer, a configuration object can be constructed, and from there, the device can be created. Note that we need to use '''global_alloc''' here because the running_machine has not yet be created (and in fact never may be). Also note that we return a pointer to the base '''device_config''' class here, since the machine configuration only knows about the base classes.

The device allocator function follows, and it is also required:

device_t *example1_device_config::alloc_device(running_machine &machine) const
{
return auto_alloc(&machine, example1_device(machine, *this));
}

In contrast to the configuration allocator, which is static and uses '''global_alloc''', the device allocator is a virtual method that uses '''auto_alloc''' in order to allocate the device and assign its memory to the provided running machine. When we construct the actual device object, we pass the machine through along with a reference to ourself so that the newly created device can have access to our configuration information.

Once all the device configurations have been created and populated, the '''device_config_complete''' method is called. We override it here to set up our inherited copy of the static configuration structure:

void example1_device_config::device_config_complete()
{
// copy static configuration if present
if (m_static_config != NULL)
*static_cast<example1_device_config_data *>(this) =
*reinterpret_cast<const example1_device_config_data *>(m_static_config);

// otherwise, initialize it to defaults
else
{
m_device_integer_data = DEFAULT_INT_VALUE;
m_device_string_data = NULL;
}
}

In the case where the user specified a pointer to a static configuration data structure, we copy it into ourselves. We use static_cast to find the pointer to where the inherited state lives within our structure and then copy the data pointed to by '''m_static_config'''. If no configuration data was provided, we take this opportunity to initialize the inherited configuration structure to default values.

Finally, if the device wishes to provide stronger validation of data -- verified both when starting a game as well as when running MAME with the -validate option -- it can ovverride the '''device_validity_check''' method:

bool example1_device_config::device_validity_check(const game_driver &driver) const
{
bool error = false;

// sanity check configuration
if (m_device_integer_value < 0)
{
mame_printf_error("%s: %s device '%s' has invalid integer parameter\n",
driver.source_file, driver.name, tag());
error = true;
}
return error;
}

This method should examing the configuration data, output friendly errors and warnings, and return true if a fatal error was detected.

=Best Practices=

MAME Device Basics

2010-05-24T18:39:42Z

Aaron: /* Example #1: Simple Device with Static Configuration */

MAME Device Basics

2010-05-21T21:58:53Z

Aaron: /* Example #1: Simple Device with Static Configuration */

MAME Device Basics

2010-05-21T21:58:38Z

Aaron: /* Example #1: Simple Device with Static Configuration */

MAME Device Basics

2010-05-21T20:08:25Z

Aaron: /* Example #1: Simple Device with Static Configuration */

MAME Device Basics

2010-05-21T20:05:45Z

Aaron: /* A Basic Example */

MAME Coding Conventions

2010-05-21T19:45:01Z

Aaron: /* Language conventions */

This page is WIP. Please don't edit it until this notice is removed.

MAME is a project that has had many contributors from many different backgrounds. Throughout its history, there have never really been any kind of formal coding conventions defined, although thanks to imitation, there is at least a glimmer of consistency.

In general, a codebase with consistent conventions is easier to understand than one with varying conventions. However, trying to impose a strict order on a project of this magnitude is certainly taking things too far.

If you categorize the MAME codebase, you can look at it like this:
* OS-specific code (OSD)
* MAME "core" code
* CPU cores
* Sound engines
* Game drivers

The first two pieces (the core and OSD) are in general only handled by a small group of developers, while the remaining pieces (drivers and CPU/sound cores) come from a much broader audience. Furthermore, the drivers and CPU/sound cores all interact to some degree with core and OSD pieces below them, so the most benefit from code clarity and consistency comes from making the core and OSD pieces consistent.

With that in mind, below is an outline some of the key coding conventions currently in use in the core and OSD layers. If you are modifying code in these layers and wish to have it accepted upon submission, you would do well to keep to these guidelines. (In fact, if you are modifying any file in any project, you should adopt the conventions of that file/project, rather than just stuffing your own inconsistent style in the middle of something else. I can't believe how many people just ignore the existing styles and jam their own style in the middle.)

One more thing. Keep in mind that coding conventions are like religion: they are often strongly-held beliefs with little factual justification to back them up. You may disagree with them. Heck, even I disagree with a few of them. But they are the conventions that are used. Deal with it.

== Naming ==
* function, method, and variable names are named using the <code>lower_under_convention</code>
* static member functions should have a static_ prefix (e.g., <code>static_timer_callback</code>)
* member variables within a class should have a standard prefix, as follows:
** normal variables should have an m_ prefix (e.g., <code>m_device</code>, <code>m_config</code>, etc)
** static members should have an s_ prefix (e.g., <code>s_device_table</code>)
** static constant members should have a k_ prefix (e.g., <code>k_maximum_items</code>)
* macros, enum items, and #defined constants should be named using the <code>ALL_CAPS_UNDER_CONVENTION</code>
* constants which are part of a group should have a common prefix; example: <code>enum { ADDRESS_SPACE_PROGRAM, ADDRESS_SPACE_DATA, ADDRESS_SPACE_IO };</code>
* prefer descriptive variable names (<code>sampnum</code>, <code>memoffset</code>) over single-letter names (<code>i</code>, <code>j</code>)
* never use the prefix "my" for anything; it's not "myobject", just use "object"

== Comments ==
* comments in the code are preferred to be <code>// C++-style comments</code>, though <code>/* standard C-style comments */</code> are still very common
* each function should have a comment preceding it that briefly describes what that function does
* each file should begin with a header that includes information about the licensing of that file; if no licensing information is given, the standard MAME license is assumed

== Spacing ==
* a space should be used between binary and trinary operators — example: <code>a + b / 2</code>
* spaces should '''not''' be used around parentheses in expressions — example: <code>(((i + j) * k) >> m)</code>
* spaces should '''not''' be used between a function and its parameters — example: <code>function(param1, param2)</code>
* a space should be used between keywords (if, while, for) and their arguments — example: <code>for (x = 0; x < 10; x++)</code>
* opening/closing braces should be on their own line, and should be indented to align with the start of the statement that introduces them
* two blank lines should separate the end of a function from the start of the next function

== Expressions ==
* do not use parentheses with '''return''', it is not a function — example: <code>return 0;</code>
* do not overuse parentheses except to clarify a statement — example: <code>if (a >= 10 && a < 20)</code>
* always use NULL (not 0) when working with pointers
* make comparisons against NULL explicit: <code>if (ptr != NULL)</code>
* make comparisons against 0 explicit: <code>if (strcmp(string1, string2) == 0)</code>
* ''don't'' make comparisons against boolean values explicit: <code>val = (a == b); if (val)...</code>

== Language conventions ==
* prefer references over pointers, using pointers primarily in situations where NULL is a valid option
* use '''static''' and '''const''' keywords aggressively where appropriate
* create typedefs for function pointers; example: <code>typedef void (*my_callback_func)(UINT32 param);</code>
* make calls through function pointers explicit — example: <code>(*funcptr)(a, b)</code>
* wherever possible, use '''enum''' instead of a macro
* wherever possible, use '''inline''' functions instead of macros
* wherever possible, use templates instead of macros
* macros that look like functions should be wrapped with <code>do { <macrobody> } while (0)</code>

== Variables ==
* avoid declaring static variables inside a function scope — these are really global variables and belong at the top of the module
* declare all global variables at the top of the file
* use the MAME-defined types: <code>INT8</code>, <code>UINT8</code>, <code>INT16</code>, <code>UINT16</code>, <code>INT32</code>, <code>UINT32</code>, <code>INT64</code>, <code>UINT64</code>

== Header Files ==
* the preferred order of definitions in a header file is:
** standard header
** reinclusion protection (see below)
** includes
** debugging flags
** constants
** type definitions
** macros
** global variables
** function prototypes
** and inline functions
* function prototypes in header files generally do not use an '''extern''' qualifier
* all header files should support reinclusion; this is done by adding the following to the top of each header
#pragma once

#ifndef __FILENAME_H__
#define __FILENAME_H__
and adding
#endif /* __FILENAME__H__ */
to the end. Note that <code>#pragma once</code> is provided because it is generally faster when supported. Since not all compilers do support it, the <code>#ifndef/#define</code> methods are retained as a fallback.

== Source Files ==
* the preferred order of code in a source file is:
** standard header
** includes
** debugging flags
** constants
** type definitions
** macros
** global variables (both static and global)
** internal function prototypes
** inline functions
** externally referenced functions
** internal functions (in same order as prototyped)

MAME Coding Conventions

2010-05-21T19:41:25Z

Aaron:

This page is WIP. Please don't edit it until this notice is removed.

MAME is a project that has had many contributors from many different backgrounds. Throughout its history, there have never really been any kind of formal coding conventions defined, although thanks to imitation, there is at least a glimmer of consistency.

In general, a codebase with consistent conventions is easier to understand than one with varying conventions. However, trying to impose a strict order on a project of this magnitude is certainly taking things too far.

If you categorize the MAME codebase, you can look at it like this:
* OS-specific code (OSD)
* MAME "core" code
* CPU cores
* Sound engines
* Game drivers

The first two pieces (the core and OSD) are in general only handled by a small group of developers, while the remaining pieces (drivers and CPU/sound cores) come from a much broader audience. Furthermore, the drivers and CPU/sound cores all interact to some degree with core and OSD pieces below them, so the most benefit from code clarity and consistency comes from making the core and OSD pieces consistent.

With that in mind, below is an outline some of the key coding conventions currently in use in the core and OSD layers. If you are modifying code in these layers and wish to have it accepted upon submission, you would do well to keep to these guidelines. (In fact, if you are modifying any file in any project, you should adopt the conventions of that file/project, rather than just stuffing your own inconsistent style in the middle of something else. I can't believe how many people just ignore the existing styles and jam their own style in the middle.)

One more thing. Keep in mind that coding conventions are like religion: they are often strongly-held beliefs with little factual justification to back them up. You may disagree with them. Heck, even I disagree with a few of them. But they are the conventions that are used. Deal with it.

== Naming ==
* function, method, and variable names are named using the <code>lower_under_convention</code>
* static member functions should have a static_ prefix (e.g., <code>static_timer_callback</code>)
* member variables within a class should have a standard prefix, as follows:
** normal variables should have an m_ prefix (e.g., <code>m_device</code>, <code>m_config</code>, etc)
** static members should have an s_ prefix (e.g., <code>s_device_table</code>)
** static constant members should have a k_ prefix (e.g., <code>k_maximum_items</code>)
* macros, enum items, and #defined constants should be named using the <code>ALL_CAPS_UNDER_CONVENTION</code>
* constants which are part of a group should have a common prefix; example: <code>enum { ADDRESS_SPACE_PROGRAM, ADDRESS_SPACE_DATA, ADDRESS_SPACE_IO };</code>
* prefer descriptive variable names (<code>sampnum</code>, <code>memoffset</code>) over single-letter names (<code>i</code>, <code>j</code>)
* never use the prefix "my" for anything; it's not "myobject", just use "object"

== Comments ==
* comments in the code are preferred to be <code>// C++-style comments</code>, though <code>/* standard C-style comments */</code> are still very common
* each function should have a comment preceding it that briefly describes what that function does
* each file should begin with a header that includes information about the licensing of that file; if no licensing information is given, the standard MAME license is assumed

== Spacing ==
* a space should be used between binary and trinary operators — example: <code>a + b / 2</code>
* spaces should '''not''' be used around parentheses in expressions — example: <code>(((i + j) * k) >> m)</code>
* spaces should '''not''' be used between a function and its parameters — example: <code>function(param1, param2)</code>
* a space should be used between keywords (if, while, for) and their arguments — example: <code>for (x = 0; x < 10; x++)</code>
* opening/closing braces should be on their own line, and should be indented to align with the start of the statement that introduces them
* two blank lines should separate the end of a function from the start of the next function

== Expressions ==
* do not use parentheses with '''return''', it is not a function — example: <code>return 0;</code>
* do not overuse parentheses except to clarify a statement — example: <code>if (a >= 10 && a < 20)</code>
* always use NULL (not 0) when working with pointers
* make comparisons against NULL explicit: <code>if (ptr != NULL)</code>
* make comparisons against 0 explicit: <code>if (strcmp(string1, string2) == 0)</code>
* ''don't'' make comparisons against boolean values explicit: <code>val = (a == b); if (val)...</code>

== Language conventions ==
* use '''static''' and '''const''' keywords aggressively where appropriate
* create typedefs for function pointers; example: <code>typedef void (*my_callback_func)(UINT32 param);</code>
* make calls through function pointers explicit — example: <code>(*funcptr)(a, b)</code>
* wherever possible, use '''enum''' instead of a macro
* wherever possible, use '''inline''' functions instead of macros
* wherever possible, use templates instead of macros
* macros that look like functions should be wrapped with <code>do { <macrobody> } while (0)</code>

== Variables ==
* avoid declaring static variables inside a function scope — these are really global variables and belong at the top of the module
* declare all global variables at the top of the file
* use the MAME-defined types: <code>INT8</code>, <code>UINT8</code>, <code>INT16</code>, <code>UINT16</code>, <code>INT32</code>, <code>UINT32</code>, <code>INT64</code>, <code>UINT64</code>

== Header Files ==
* the preferred order of definitions in a header file is:
** standard header
** reinclusion protection (see below)
** includes
** debugging flags
** constants
** type definitions
** macros
** global variables
** function prototypes
** and inline functions
* function prototypes in header files generally do not use an '''extern''' qualifier
* all header files should support reinclusion; this is done by adding the following to the top of each header
#pragma once

#ifndef __FILENAME_H__
#define __FILENAME_H__
and adding
#endif /* __FILENAME__H__ */
to the end. Note that <code>#pragma once</code> is provided because it is generally faster when supported. Since not all compilers do support it, the <code>#ifndef/#define</code> methods are retained as a fallback.

== Source Files ==
* the preferred order of code in a source file is:
** standard header
** includes
** debugging flags
** constants
** type definitions
** macros
** global variables (both static and global)
** internal function prototypes
** inline functions
** externally referenced functions
** internal functions (in same order as prototyped)

MAME Coding Conventions

2010-05-21T19:40:37Z

Aaron: /* Language conventions */

This page is WIP. Please don't edit it until this notice is removed.

MAME is a project that has had many contributors from many different backgrounds. Throughout its history, there have never really been any kind of formal coding conventions defined, although thanks to imitation, there is at least a glimmer of consistency.

In general, a codebase with consistent conventions is easier to understand than one with varying conventions. However, trying to impose a strict order on a project of this magnitude is certainly taking things too far.

If you categorize the MAME codebase, you can look at it like this:
* OS-specific code (OSD)
* MAME "core" code
* CPU cores
* Sound engines
* Game drivers

The first two pieces (the core and OSD) are in general only handled by a small group of developers, while the remaining pieces (drivers and CPU/sound cores) come from a much broader audience. Furthermore, the drivers and CPU/sound cores all interact to some degree with core and OSD pieces below them, so the most benefit from code clarity and consistency comes from making the core and OSD pieces consistent.

With that in mind, below is an outline some of the key coding conventions currently in use in the core and OSD layers. If you are modifying code in theses layers and wish to have it accepted upon submission, you would do well to keep to these guidelines. (In fact, if you are modifying any file in any project, you should adopt the conventions of that file/project, rather than just stuffing your own inconsistent style in the middle of something else. I can't believe how many people just ignore the existing styles and jam their own style in the middle.)

One more thing. Keep in mind that coding conventions are like religion: they are often strongly-held beliefs with little factual justification to back them up. You may disagree with them. Heck, even I disagree with a few of them. But they are the conventions that are used. Deal with it.

== Naming ==
* function, method, and variable names are named using the <code>lower_under_convention</code>
* static member functions should have a static_ prefix (e.g., <code>static_timer_callback</code>)
* member variables within a class should have a standard prefix, as follows:
** normal variables should have an m_ prefix (e.g., <code>m_device</code>, <code>m_config</code>, etc)
** static members should have an s_ prefix (e.g., <code>s_device_table</code>)
** static constant members should have a k_ prefix (e.g., <code>k_maximum_items</code>)
* macros, enum items, and #defined constants should be named using the <code>ALL_CAPS_UNDER_CONVENTION</code>
* constants which are part of a group should have a common prefix; example: <code>enum { ADDRESS_SPACE_PROGRAM, ADDRESS_SPACE_DATA, ADDRESS_SPACE_IO };</code>
* prefer descriptive variable names (<code>sampnum</code>, <code>memoffset</code>) over single-letter names (<code>i</code>, <code>j</code>)
* never use the prefix "my" for anything; it's not "myobject", just use "object"

== Comments ==
* comments in the code are preferred to be <code>// C++-style comments</code>, though <code>/* standard C-style comments */</code> are still very common
* each function should have a comment preceding it that briefly describes what that function does
* each file should begin with a header that includes information about the licensing of that file; if no licensing information is given, the standard MAME license is assumed

== Spacing ==
* a space should be used between binary and trinary operators — example: <code>a + b / 2</code>
* spaces should '''not''' be used around parentheses in expressions — example: <code>(((i + j) * k) >> m)</code>
* spaces should '''not''' be used between a function and its parameters — example: <code>function(param1, param2)</code>
* a space should be used between keywords (if, while, for) and their arguments — example: <code>for (x = 0; x < 10; x++)</code>
* opening/closing braces should be on their own line, and should be indented to align with the start of the statement that introduces them
* two blank lines should separate the end of a function from the start of the next function

== Expressions ==
* do not use parentheses with '''return''', it is not a function — example: <code>return 0;</code>
* do not overuse parentheses except to clarify a statement — example: <code>if (a >= 10 && a < 20)</code>
* always use NULL (not 0) when working with pointers
* make comparisons against NULL explicit: <code>if (ptr != NULL)</code>
* make comparisons against 0 explicit: <code>if (strcmp(string1, string2) == 0)</code>
* ''don't'' make comparisons against boolean values explicit: <code>val = (a == b); if (val)...</code>

== Language conventions ==
* use '''static''' and '''const''' keywords aggressively where appropriate
* create typedefs for function pointers; example: <code>typedef void (*my_callback_func)(UINT32 param);</code>
* make calls through function pointers explicit — example: <code>(*funcptr)(a, b)</code>
* wherever possible, use '''enum''' instead of a macro
* wherever possible, use '''inline''' functions instead of macros
* wherever possible, use templates instead of macros
* macros that look like functions should be wrapped with <code>do { <macrobody> } while (0)</code>

== Variables ==
* avoid declaring static variables inside a function scope — these are really global variables and belong at the top of the module
* declare all global variables at the top of the file
* use the MAME-defined types: <code>INT8</code>, <code>UINT8</code>, <code>INT16</code>, <code>UINT16</code>, <code>INT32</code>, <code>UINT32</code>, <code>INT64</code>, <code>UINT64</code>

== Header Files ==
* the preferred order of definitions in a header file is:
** standard header
** reinclusion protection (see below)
** includes
** debugging flags
** constants
** type definitions
** macros
** global variables
** function prototypes
** and inline functions
* function prototypes in header files generally do not use an '''extern''' qualifier
* all header files should support reinclusion; this is done by adding the following to the top of each header
#pragma once

#ifndef __FILENAME_H__
#define __FILENAME_H__
and adding
#endif /* __FILENAME__H__ */
to the end. Note that <code>#pragma once</code> is provided because it is generally faster when supported. Since not all compilers do support it, the <code>#ifndef/#define</code> methods are retained as a fallback.

== Source Files ==
* the preferred order of code in a source file is:
** standard header
** includes
** debugging flags
** constants
** type definitions
** macros
** global variables (both static and global)
** internal function prototypes
** inline functions
** externally referenced functions
** internal functions (in same order as prototyped)

MAME Coding Conventions

2010-05-21T19:39:22Z

Aaron: /* Comments */

This page is WIP. Please don't edit it until this notice is removed.

MAME is a project that has had many contributors from many different backgrounds. Throughout its history, there have never really been any kind of formal coding conventions defined, although thanks to imitation, there is at least a glimmer of consistency.

In general, a codebase with consistent conventions is easier to understand than one with varying conventions. However, trying to impose a strict order on a project of this magnitude is certainly taking things too far.

If you categorize the MAME codebase, you can look at it like this:
* OS-specific code (OSD)
* MAME "core" code
* CPU cores
* Sound engines
* Game drivers

The first two pieces (the core and OSD) are in general only handled by a small group of developers, while the remaining pieces (drivers and CPU/sound cores) come from a much broader audience. Furthermore, the drivers and CPU/sound cores all interact to some degree with core and OSD pieces below them, so the most benefit from code clarity and consistency comes from making the core and OSD pieces consistent.

With that in mind, below is an outline some of the key coding conventions currently in use in the core and OSD layers. If you are modifying code in theses layers and wish to have it accepted upon submission, you would do well to keep to these guidelines. (In fact, if you are modifying any file in any project, you should adopt the conventions of that file/project, rather than just stuffing your own inconsistent style in the middle of something else. I can't believe how many people just ignore the existing styles and jam their own style in the middle.)

One more thing. Keep in mind that coding conventions are like religion: they are often strongly-held beliefs with little factual justification to back them up. You may disagree with them. Heck, even I disagree with a few of them. But they are the conventions that are used. Deal with it.

== Naming ==
* function, method, and variable names are named using the <code>lower_under_convention</code>
* static member functions should have a static_ prefix (e.g., <code>static_timer_callback</code>)
* member variables within a class should have a standard prefix, as follows:
** normal variables should have an m_ prefix (e.g., <code>m_device</code>, <code>m_config</code>, etc)
** static members should have an s_ prefix (e.g., <code>s_device_table</code>)
** static constant members should have a k_ prefix (e.g., <code>k_maximum_items</code>)
* macros, enum items, and #defined constants should be named using the <code>ALL_CAPS_UNDER_CONVENTION</code>
* constants which are part of a group should have a common prefix; example: <code>enum { ADDRESS_SPACE_PROGRAM, ADDRESS_SPACE_DATA, ADDRESS_SPACE_IO };</code>
* prefer descriptive variable names (<code>sampnum</code>, <code>memoffset</code>) over single-letter names (<code>i</code>, <code>j</code>)
* never use the prefix "my" for anything; it's not "myobject", just use "object"

== Comments ==
* comments in the code are preferred to be <code>// C++-style comments</code>, though <code>/* standard C-style comments */</code> are still very common
* each function should have a comment preceding it that briefly describes what that function does
* each file should begin with a header that includes information about the licensing of that file; if no licensing information is given, the standard MAME license is assumed

== Spacing ==
* a space should be used between binary and trinary operators — example: <code>a + b / 2</code>
* spaces should '''not''' be used around parentheses in expressions — example: <code>(((i + j) * k) >> m)</code>
* spaces should '''not''' be used between a function and its parameters — example: <code>function(param1, param2)</code>
* a space should be used between keywords (if, while, for) and their arguments — example: <code>for (x = 0; x < 10; x++)</code>
* opening/closing braces should be on their own line, and should be indented to align with the start of the statement that introduces them
* two blank lines should separate the end of a function from the start of the next function

== Expressions ==
* do not use parentheses with '''return''', it is not a function — example: <code>return 0;</code>
* do not overuse parentheses except to clarify a statement — example: <code>if (a >= 10 && a < 20)</code>
* always use NULL (not 0) when working with pointers
* make comparisons against NULL explicit: <code>if (ptr != NULL)</code>
* make comparisons against 0 explicit: <code>if (strcmp(string1, string2) == 0)</code>
* ''don't'' make comparisons against boolean values explicit: <code>val = (a == b); if (val)...</code>

== Language conventions ==
* use '''static''' and '''const''' keywords aggressively where appropriate
* create typedefs for function pointers; example: <code>typedef void (*my_callback_func)(UINT32 param);</code>
* make calls through function pointers explicit — example: <code>(*funcptr)(a, b)</code>
* wherever possible, use '''enum''' instead of a macro
* wherever possible, use '''INLINE''' functions instead of macros
* macros that look like functions should be wrapped with <code>do { <macrobody> } while (0)</code>

== Variables ==
* avoid declaring static variables inside a function scope — these are really global variables and belong at the top of the module
* declare all global variables at the top of the file
* use the MAME-defined types: <code>INT8</code>, <code>UINT8</code>, <code>INT16</code>, <code>UINT16</code>, <code>INT32</code>, <code>UINT32</code>, <code>INT64</code>, <code>UINT64</code>

== Header Files ==
* the preferred order of definitions in a header file is:
** standard header
** reinclusion protection (see below)
** includes
** debugging flags
** constants
** type definitions
** macros
** global variables
** function prototypes
** and inline functions
* function prototypes in header files generally do not use an '''extern''' qualifier
* all header files should support reinclusion; this is done by adding the following to the top of each header
#pragma once

#ifndef __FILENAME_H__
#define __FILENAME_H__
and adding
#endif /* __FILENAME__H__ */
to the end. Note that <code>#pragma once</code> is provided because it is generally faster when supported. Since not all compilers do support it, the <code>#ifndef/#define</code> methods are retained as a fallback.

== Source Files ==
* the preferred order of code in a source file is:
** standard header
** includes
** debugging flags
** constants
** type definitions
** macros
** global variables (both static and global)
** internal function prototypes
** inline functions
** externally referenced functions
** internal functions (in same order as prototyped)

MAME Coding Conventions

2010-05-21T19:37:50Z

Aaron: /* Naming */

This page is WIP. Please don't edit it until this notice is removed.

MAME is a project that has had many contributors from many different backgrounds. Throughout its history, there have never really been any kind of formal coding conventions defined, although thanks to imitation, there is at least a glimmer of consistency.

In general, a codebase with consistent conventions is easier to understand than one with varying conventions. However, trying to impose a strict order on a project of this magnitude is certainly taking things too far.

If you categorize the MAME codebase, you can look at it like this:
* OS-specific code (OSD)
* MAME "core" code
* CPU cores
* Sound engines
* Game drivers

The first two pieces (the core and OSD) are in general only handled by a small group of developers, while the remaining pieces (drivers and CPU/sound cores) come from a much broader audience. Furthermore, the drivers and CPU/sound cores all interact to some degree with core and OSD pieces below them, so the most benefit from code clarity and consistency comes from making the core and OSD pieces consistent.

With that in mind, below is an outline some of the key coding conventions currently in use in the core and OSD layers. If you are modifying code in theses layers and wish to have it accepted upon submission, you would do well to keep to these guidelines. (In fact, if you are modifying any file in any project, you should adopt the conventions of that file/project, rather than just stuffing your own inconsistent style in the middle of something else. I can't believe how many people just ignore the existing styles and jam their own style in the middle.)

One more thing. Keep in mind that coding conventions are like religion: they are often strongly-held beliefs with little factual justification to back them up. You may disagree with them. Heck, even I disagree with a few of them. But they are the conventions that are used. Deal with it.

== Naming ==
* function, method, and variable names are named using the <code>lower_under_convention</code>
* static member functions should have a static_ prefix (e.g., <code>static_timer_callback</code>)
* member variables within a class should have a standard prefix, as follows:
** normal variables should have an m_ prefix (e.g., <code>m_device</code>, <code>m_config</code>, etc)
** static members should have an s_ prefix (e.g., <code>s_device_table</code>)
** static constant members should have a k_ prefix (e.g., <code>k_maximum_items</code>)
* macros, enum items, and #defined constants should be named using the <code>ALL_CAPS_UNDER_CONVENTION</code>
* constants which are part of a group should have a common prefix; example: <code>enum { ADDRESS_SPACE_PROGRAM, ADDRESS_SPACE_DATA, ADDRESS_SPACE_IO };</code>
* prefer descriptive variable names (<code>sampnum</code>, <code>memoffset</code>) over single-letter names (<code>i</code>, <code>j</code>)
* never use the prefix "my" for anything; it's not "myobject", just use "object"

== Comments ==
* comments in the non-OSD parts of the code should all be <code>/* C-style comments */</code>
* comments in the OSD-specific parts of the code may be <code>// C++-style comments</code> (and are in the Windows code)
* each function should have a comment preceding it that briefly describes what that function does

== Spacing ==
* a space should be used between binary and trinary operators — example: <code>a + b / 2</code>
* spaces should '''not''' be used around parentheses in expressions — example: <code>(((i + j) * k) >> m)</code>
* spaces should '''not''' be used between a function and its parameters — example: <code>function(param1, param2)</code>
* a space should be used between keywords (if, while, for) and their arguments — example: <code>for (x = 0; x < 10; x++)</code>
* opening/closing braces should be on their own line, and should be indented to align with the start of the statement that introduces them
* two blank lines should separate the end of a function from the start of the next function

== Expressions ==
* do not use parentheses with '''return''', it is not a function — example: <code>return 0;</code>
* do not overuse parentheses except to clarify a statement — example: <code>if (a >= 10 && a < 20)</code>
* always use NULL (not 0) when working with pointers
* make comparisons against NULL explicit: <code>if (ptr != NULL)</code>
* make comparisons against 0 explicit: <code>if (strcmp(string1, string2) == 0)</code>
* ''don't'' make comparisons against boolean values explicit: <code>val = (a == b); if (val)...</code>

== Language conventions ==
* use '''static''' and '''const''' keywords aggressively where appropriate
* create typedefs for function pointers; example: <code>typedef void (*my_callback_func)(UINT32 param);</code>
* make calls through function pointers explicit — example: <code>(*funcptr)(a, b)</code>
* wherever possible, use '''enum''' instead of a macro
* wherever possible, use '''INLINE''' functions instead of macros
* macros that look like functions should be wrapped with <code>do { <macrobody> } while (0)</code>

== Variables ==
* avoid declaring static variables inside a function scope — these are really global variables and belong at the top of the module
* declare all global variables at the top of the file
* use the MAME-defined types: <code>INT8</code>, <code>UINT8</code>, <code>INT16</code>, <code>UINT16</code>, <code>INT32</code>, <code>UINT32</code>, <code>INT64</code>, <code>UINT64</code>

== Header Files ==
* the preferred order of definitions in a header file is:
** standard header
** reinclusion protection (see below)
** includes
** debugging flags
** constants
** type definitions
** macros
** global variables
** function prototypes
** and inline functions
* function prototypes in header files generally do not use an '''extern''' qualifier
* all header files should support reinclusion; this is done by adding the following to the top of each header
#pragma once

#ifndef __FILENAME_H__
#define __FILENAME_H__
and adding
#endif /* __FILENAME__H__ */
to the end. Note that <code>#pragma once</code> is provided because it is generally faster when supported. Since not all compilers do support it, the <code>#ifndef/#define</code> methods are retained as a fallback.

== Source Files ==
* the preferred order of code in a source file is:
** standard header
** includes
** debugging flags
** constants
** type definitions
** macros
** global variables (both static and global)
** internal function prototypes
** inline functions
** externally referenced functions
** internal functions (in same order as prototyped)

MAME Coding Conventions

2010-05-21T19:37:09Z

Aaron: /* Naming */

This page is WIP. Please don't edit it until this notice is removed.

MAME is a project that has had many contributors from many different backgrounds. Throughout its history, there have never really been any kind of formal coding conventions defined, although thanks to imitation, there is at least a glimmer of consistency.

In general, a codebase with consistent conventions is easier to understand than one with varying conventions. However, trying to impose a strict order on a project of this magnitude is certainly taking things too far.

If you categorize the MAME codebase, you can look at it like this:
* OS-specific code (OSD)
* MAME "core" code
* CPU cores
* Sound engines
* Game drivers

The first two pieces (the core and OSD) are in general only handled by a small group of developers, while the remaining pieces (drivers and CPU/sound cores) come from a much broader audience. Furthermore, the drivers and CPU/sound cores all interact to some degree with core and OSD pieces below them, so the most benefit from code clarity and consistency comes from making the core and OSD pieces consistent.

With that in mind, below is an outline some of the key coding conventions currently in use in the core and OSD layers. If you are modifying code in theses layers and wish to have it accepted upon submission, you would do well to keep to these guidelines. (In fact, if you are modifying any file in any project, you should adopt the conventions of that file/project, rather than just stuffing your own inconsistent style in the middle of something else. I can't believe how many people just ignore the existing styles and jam their own style in the middle.)

One more thing. Keep in mind that coding conventions are like religion: they are often strongly-held beliefs with little factual justification to back them up. You may disagree with them. Heck, even I disagree with a few of them. But they are the conventions that are used. Deal with it.

== Naming ==
* function, method, and variable names are named using the <code>lower_under_convention</code>
* static member functions should have a static_ prefix (e.g., static_timer_callback)
* member variables within a class should have a standard prefix, as follows:
** normal variables should have an m_ prefix (e.g., m_device, m_config, etc)
** static members should have an s_ prefix (e.g., s_device_table)
** static constant members should have a k_ prefix (e.g., k_maximum_items)
* macros, enum items, and #defined constants should be named using the <code>ALL_CAPS_UNDER_CONVENTION</code>
* constants which are part of a group should have a common prefix; example: <code>enum { ADDRESS_SPACE_PROGRAM, ADDRESS_SPACE_DATA, ADDRESS_SPACE_IO };</code>
* prefer descriptive variable names (<code>sampnum</code>, <code>memoffset</code>) over single-letter names (<code>i</code>, <code>j</code>)
* never use the prefix "my" for anything; it's not "myobject", just use "object"

== Comments ==
* comments in the non-OSD parts of the code should all be <code>/* C-style comments */</code>
* comments in the OSD-specific parts of the code may be <code>// C++-style comments</code> (and are in the Windows code)
* each function should have a comment preceding it that briefly describes what that function does

== Spacing ==
* a space should be used between binary and trinary operators — example: <code>a + b / 2</code>
* spaces should '''not''' be used around parentheses in expressions — example: <code>(((i + j) * k) >> m)</code>
* spaces should '''not''' be used between a function and its parameters — example: <code>function(param1, param2)</code>
* a space should be used between keywords (if, while, for) and their arguments — example: <code>for (x = 0; x < 10; x++)</code>
* opening/closing braces should be on their own line, and should be indented to align with the start of the statement that introduces them
* two blank lines should separate the end of a function from the start of the next function

== Expressions ==
* do not use parentheses with '''return''', it is not a function — example: <code>return 0;</code>
* do not overuse parentheses except to clarify a statement — example: <code>if (a >= 10 && a < 20)</code>
* always use NULL (not 0) when working with pointers
* make comparisons against NULL explicit: <code>if (ptr != NULL)</code>
* make comparisons against 0 explicit: <code>if (strcmp(string1, string2) == 0)</code>
* ''don't'' make comparisons against boolean values explicit: <code>val = (a == b); if (val)...</code>

== Language conventions ==
* use '''static''' and '''const''' keywords aggressively where appropriate
* create typedefs for function pointers; example: <code>typedef void (*my_callback_func)(UINT32 param);</code>
* make calls through function pointers explicit — example: <code>(*funcptr)(a, b)</code>
* wherever possible, use '''enum''' instead of a macro
* wherever possible, use '''INLINE''' functions instead of macros
* macros that look like functions should be wrapped with <code>do { <macrobody> } while (0)</code>

== Variables ==
* avoid declaring static variables inside a function scope — these are really global variables and belong at the top of the module
* declare all global variables at the top of the file
* use the MAME-defined types: <code>INT8</code>, <code>UINT8</code>, <code>INT16</code>, <code>UINT16</code>, <code>INT32</code>, <code>UINT32</code>, <code>INT64</code>, <code>UINT64</code>

== Header Files ==
* the preferred order of definitions in a header file is:
** standard header
** reinclusion protection (see below)
** includes
** debugging flags
** constants
** type definitions
** macros
** global variables
** function prototypes
** and inline functions
* function prototypes in header files generally do not use an '''extern''' qualifier
* all header files should support reinclusion; this is done by adding the following to the top of each header
#pragma once

#ifndef __FILENAME_H__
#define __FILENAME_H__
and adding
#endif /* __FILENAME__H__ */
to the end. Note that <code>#pragma once</code> is provided because it is generally faster when supported. Since not all compilers do support it, the <code>#ifndef/#define</code> methods are retained as a fallback.

== Source Files ==
* the preferred order of code in a source file is:
** standard header
** includes
** debugging flags
** constants
** type definitions
** macros
** global variables (both static and global)
** internal function prototypes
** inline functions
** externally referenced functions
** internal functions (in same order as prototyped)

MAME Coding Conventions

2010-05-21T19:36:24Z

Aaron: /* Naming */

This page is WIP. Please don't edit it until this notice is removed.

MAME is a project that has had many contributors from many different backgrounds. Throughout its history, there have never really been any kind of formal coding conventions defined, although thanks to imitation, there is at least a glimmer of consistency.

In general, a codebase with consistent conventions is easier to understand than one with varying conventions. However, trying to impose a strict order on a project of this magnitude is certainly taking things too far.

If you categorize the MAME codebase, you can look at it like this:
* OS-specific code (OSD)
* MAME "core" code
* CPU cores
* Sound engines
* Game drivers

The first two pieces (the core and OSD) are in general only handled by a small group of developers, while the remaining pieces (drivers and CPU/sound cores) come from a much broader audience. Furthermore, the drivers and CPU/sound cores all interact to some degree with core and OSD pieces below them, so the most benefit from code clarity and consistency comes from making the core and OSD pieces consistent.

With that in mind, below is an outline some of the key coding conventions currently in use in the core and OSD layers. If you are modifying code in theses layers and wish to have it accepted upon submission, you would do well to keep to these guidelines. (In fact, if you are modifying any file in any project, you should adopt the conventions of that file/project, rather than just stuffing your own inconsistent style in the middle of something else. I can't believe how many people just ignore the existing styles and jam their own style in the middle.)

One more thing. Keep in mind that coding conventions are like religion: they are often strongly-held beliefs with little factual justification to back them up. You may disagree with them. Heck, even I disagree with a few of them. But they are the conventions that are used. Deal with it.

== Naming ==
* function, method, and variable names are named using the <code>lower_under_convention</code>
* member variables within a class should have a standard prefix, as follows:
** normal variables should have an m_ prefix (e.g., m_device, m_config, etc)
** static members should have an s_ prefix (e.g., s_device_table)
** static constant members should have a k_ prefix (e.g., k_maximum_items)
* macros, enum items, and #defined constants should be named using the <code>ALL_CAPS_UNDER_CONVENTION</code>
* constants which are part of a group should have a common prefix; example: <code>enum { ADDRESS_SPACE_PROGRAM, ADDRESS_SPACE_DATA, ADDRESS_SPACE_IO };</code>
* prefer descriptive variable names (<code>sampnum</code>, <code>memoffset</code>) over single-letter names (<code>i</code>, <code>j</code>)
* never use the prefix "my" for anything; it's not "myobject", just use "object"

== Comments ==
* comments in the non-OSD parts of the code should all be <code>/* C-style comments */</code>
* comments in the OSD-specific parts of the code may be <code>// C++-style comments</code> (and are in the Windows code)
* each function should have a comment preceding it that briefly describes what that function does

== Spacing ==
* a space should be used between binary and trinary operators — example: <code>a + b / 2</code>
* spaces should '''not''' be used around parentheses in expressions — example: <code>(((i + j) * k) >> m)</code>
* spaces should '''not''' be used between a function and its parameters — example: <code>function(param1, param2)</code>
* a space should be used between keywords (if, while, for) and their arguments — example: <code>for (x = 0; x < 10; x++)</code>
* opening/closing braces should be on their own line, and should be indented to align with the start of the statement that introduces them
* two blank lines should separate the end of a function from the start of the next function

== Expressions ==
* do not use parentheses with '''return''', it is not a function — example: <code>return 0;</code>
* do not overuse parentheses except to clarify a statement — example: <code>if (a >= 10 && a < 20)</code>
* always use NULL (not 0) when working with pointers
* make comparisons against NULL explicit: <code>if (ptr != NULL)</code>
* make comparisons against 0 explicit: <code>if (strcmp(string1, string2) == 0)</code>
* ''don't'' make comparisons against boolean values explicit: <code>val = (a == b); if (val)...</code>

== Language conventions ==
* use '''static''' and '''const''' keywords aggressively where appropriate
* create typedefs for function pointers; example: <code>typedef void (*my_callback_func)(UINT32 param);</code>
* make calls through function pointers explicit — example: <code>(*funcptr)(a, b)</code>
* wherever possible, use '''enum''' instead of a macro
* wherever possible, use '''INLINE''' functions instead of macros
* macros that look like functions should be wrapped with <code>do { <macrobody> } while (0)</code>

== Variables ==
* avoid declaring static variables inside a function scope — these are really global variables and belong at the top of the module
* declare all global variables at the top of the file
* use the MAME-defined types: <code>INT8</code>, <code>UINT8</code>, <code>INT16</code>, <code>UINT16</code>, <code>INT32</code>, <code>UINT32</code>, <code>INT64</code>, <code>UINT64</code>

== Header Files ==
* the preferred order of definitions in a header file is:
** standard header
** reinclusion protection (see below)
** includes
** debugging flags
** constants
** type definitions
** macros
** global variables
** function prototypes
** and inline functions
* function prototypes in header files generally do not use an '''extern''' qualifier
* all header files should support reinclusion; this is done by adding the following to the top of each header
#pragma once

#ifndef __FILENAME_H__
#define __FILENAME_H__
and adding
#endif /* __FILENAME__H__ */
to the end. Note that <code>#pragma once</code> is provided because it is generally faster when supported. Since not all compilers do support it, the <code>#ifndef/#define</code> methods are retained as a fallback.

== Source Files ==
* the preferred order of code in a source file is:
** standard header
** includes
** debugging flags
** constants
** type definitions
** macros
** global variables (both static and global)
** internal function prototypes
** inline functions
** externally referenced functions
** internal functions (in same order as prototyped)

Device Interfaces

2010-05-21T19:31:40Z

Aaron: New page: =Standard Interfaces= * Execute * Memory * State * NVRAM * Disassembly * Sound =Custom Interface=

=Standard Interfaces=

* Execute
* Memory
* State
* NVRAM
* Disassembly
* Sound

=Custom Interface=

MAME Device Basics

2010-05-21T19:31:27Z

Aaron:

How MAME Works

2010-05-21T19:31:07Z

Aaron: /* 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 ==
* [[Contributing to MAME]]
* [[Submitting Source Code]]
* [[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 ==
* MAME Devices
** [[MAME Device Basics]]
** [[Device Interfaces]]
** [[Advanced Device Customization]]
** [[All About Devices]] (out of date)
* [[Timers and timing]]
* [[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]]

MAME Device Basics

2010-05-21T19:30:02Z

Aaron: /* Lifecycle of a Device */

MAME Device Basics

2010-05-21T19:29:25Z

Aaron: /* Basic Concepts */

How MAME Works

2010-05-21T19:29:02Z

Aaron: /* 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 ==
* [[Contributing to MAME]]
* [[Submitting Source Code]]
* [[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 ==
* [[MAME Device Basics]]
** [[All About Devices]] (out of date)
* [[Timers and timing]]
* [[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]]

MAME Device Basics

2010-05-21T19:28:39Z

Aaron: MAME Devices moved to MAME Device Basics: Will need several articles

MAME Device Basics

2010-05-20T22:55:32Z

Aaron: /* Configuring Devices */

MAME Device Basics

2010-05-19T20:16:24Z

Aaron:

MAME Device Basics

2010-05-19T20:03:00Z

Aaron: /* Runtime */

MAME Device Basics

2010-05-19T19:57:19Z

Aaron: /* Runtime */

MAME Device Basics

2010-05-18T21:09:03Z

Aaron: /* Runtime */

MAME Device Basics

2010-05-18T21:08:46Z

Aaron: /* Configuration */

MAME Device Basics

2010-05-18T19:40:14Z

Aaron: /* Lifecycle of a Device */

MAME Device Basics

2010-05-18T19:13:27Z

Aaron: /* Basic Concepts */

MAME Device Basics

2010-05-17T20:37:05Z

Aaron: /* Basic Concepts */

MAME Device Basics

2010-05-17T20:16:06Z

Aaron: New page: =Overview= In MAME, a device is a mechanism for encapsulating behavior. While it is common to associate a device (in the MAME sense) with a physical device (in the real world), there does...

How MAME Works

2010-05-17T19:55:40Z

Aaron: /* 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 ==
* [[Contributing to MAME]]
* [[Submitting Source Code]]
* [[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 ==
* [[MAME Devices]]
** [[All About Devices]] (out of date)
* [[Timers and timing]]
* [[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]]