All About Devices - Revision history

Stiletto at 03:25, 25 November 2014

2014-11-25T03:25:02Z

← Older revision		Revision as of 05:25, 25 November 2014
Line 3:		Line 3:
	The first thing to be aware of when thinking about devices is that you shouldn't get too hung up on the term "device". A device in MAME doesn't have to correspond to a physical chip or device or anything that concrete (although they can and often do). Instead, just think of a device as a means of grouping a set of functions and behaviors together and calling it something. They are a preferred means of wrapping together functions that are used across multiple machines.		The first thing to be aware of when thinking about devices is that you shouldn't get too hung up on the term "device". A device in MAME doesn't have to correspond to a physical chip or device or anything that concrete (although they can and often do). Instead, just think of a device as a means of grouping a set of functions and behaviors together and calling it something. They are a preferred means of wrapping together functions that are used across multiple machines.

	Devices in MAME might seem like a relatively recent concept, but in reality they are simply the culmination of previous efforts to define a consistent "plug-in" style interface for assembling a machine. CPU cores were the first device-like objects which exposed a consistent interface (see [~~https~~://github.com/mamedev/mame/blob/master/src/emu/cpuintrf.h cpuintrf.h] (broken link) for definitions). Later on, the sound cores got their own similar interface (see [~~https~~://github.com/mamedev/mame/blob/master/src/emu/sndintrf.h sndintrf.h] (broken link)). It has only been recently that a more abstract device interface (see [~~https~~://github.com/mamedev/mame/blob/master/src/emu/devintrf.h devintrf.h] (broken link)) has been introduced. Eventually, the CPU and sound interfaces will be retooled to be based fully on the abstract device interface, and then everything will be able to be treated equally as a generic device.		Devices in MAME might seem like a relatively recent concept, but in reality they are simply the culmination of previous efforts to define a consistent "plug-in" style interface for assembling a machine. CPU cores were the first device-like objects which exposed a consistent interface (see [http://github.com/mamedev/mame/blob/master/src/emu/cpuintrf.h cpuintrf.h] (broken link) for definitions). Later on, the sound cores got their own similar interface (see [http://github.com/mamedev/mame/blob/master/src/emu/sndintrf.h sndintrf.h] (broken link)). It has only been recently that a more abstract device interface (see [http://github.com/mamedev/mame/blob/master/src/emu/devintrf.h devintrf.h] (broken link)) has been introduced. Eventually, the CPU and sound interfaces will be retooled to be based fully on the abstract device interface, and then everything will be able to be treated equally as a generic device.

	Devices have many nice features beyond their consistent interface that makes them useful in MAME:		Devices have many nice features beyond their consistent interface that makes them useful in MAME:
Line 85:		Line 85:
	device = devtag_get_device(machine, "tag");		device = devtag_get_device(machine, "tag");

	There are several similar devtag_ functions declared in [~~https~~://github.com/mamedev/mame/blob/master/src/emu/devintrf.h devintrf.h (broken link)], which replace the list head parameter with a running_machine object for easier use when the system is running.		There are several similar devtag_ functions declared in [http://github.com/mamedev/mame/blob/master/src/emu/devintrf.h devintrf.h (broken link)], which replace the list head parameter with a running_machine object for easier use when the system is running.

	=== Device Configuration ===		=== Device Configuration ===

Stiletto at 03:09, 25 November 2014

2014-11-25T03:09:30Z

← Older revision		Revision as of 05:09, 25 November 2014
Line 85:		Line 85:
	device = devtag_get_device(machine, "tag");		device = devtag_get_device(machine, "tag");

	There are several similar devtag_ functions declared in [~~http~~://mamedev~~.org~~/~~source~~/src/emu/devintrf.h~~.html~~ devintrf.h], which replace the list head parameter with a running_machine object for easier use when the system is running.		There are several similar devtag_ functions declared in [https://github.com/mamedev/mame/blob/master/src/emu/devintrf.h devintrf.h (broken link)], which replace the list head parameter with a running_machine object for easier use when the system is running.

	=== Device Configuration ===		=== Device Configuration ===

Stiletto: cpuintrf/sndintrf/devintrf is outdated

2014-11-25T03:08:11Z

cpuintrf/sndintrf/devintrf is outdated

← Older revision		Revision as of 05:08, 25 November 2014
Line 3:		Line 3:
	The first thing to be aware of when thinking about devices is that you shouldn't get too hung up on the term "device". A device in MAME doesn't have to correspond to a physical chip or device or anything that concrete (although they can and often do). Instead, just think of a device as a means of grouping a set of functions and behaviors together and calling it something. They are a preferred means of wrapping together functions that are used across multiple machines.		The first thing to be aware of when thinking about devices is that you shouldn't get too hung up on the term "device". A device in MAME doesn't have to correspond to a physical chip or device or anything that concrete (although they can and often do). Instead, just think of a device as a means of grouping a set of functions and behaviors together and calling it something. They are a preferred means of wrapping together functions that are used across multiple machines.

	Devices in MAME might seem like a relatively recent concept, but in reality they are simply the culmination of previous efforts to define a consistent "plug-in" style interface for assembling a machine. CPU cores were the first device-like objects which exposed a consistent interface (see [https://github.com/mamedev/mame/blob/master/src/emu/cpuintrf.h cpuintrf.h] for definitions). Later on, the sound cores got their own similar interface (see [https://github.com/mamedev/mame/blob/master/src/emu/sndintrf.h sndintrf.h]). It has only been recently that a more abstract device interface (see [https://github.com/mamedev/mame/blob/master/src/emu/devintrf.h devintrf.h]) has been introduced. Eventually, the CPU and sound interfaces will be retooled to be based fully on the abstract device interface, and then everything will be able to be treated equally as a generic device.		Devices in MAME might seem like a relatively recent concept, but in reality they are simply the culmination of previous efforts to define a consistent "plug-in" style interface for assembling a machine. CPU cores were the first device-like objects which exposed a consistent interface (see [https://github.com/mamedev/mame/blob/master/src/emu/cpuintrf.h cpuintrf.h] (broken link) for definitions). Later on, the sound cores got their own similar interface (see [https://github.com/mamedev/mame/blob/master/src/emu/sndintrf.h sndintrf.h] (broken link)). It has only been recently that a more abstract device interface (see [https://github.com/mamedev/mame/blob/master/src/emu/devintrf.h devintrf.h] (broken link)) has been introduced. Eventually, the CPU and sound interfaces will be retooled to be based fully on the abstract device interface, and then everything will be able to be treated equally as a generic device.

	Devices have many nice features beyond their consistent interface that makes them useful in MAME:		Devices have many nice features beyond their consistent interface that makes them useful in MAME:

Stiletto at 03:02, 25 November 2014

2014-11-25T03:02:16Z

← Older revision		Revision as of 05:02, 25 November 2014
Line 3:		Line 3:
	The first thing to be aware of when thinking about devices is that you shouldn't get too hung up on the term "device". A device in MAME doesn't have to correspond to a physical chip or device or anything that concrete (although they can and often do). Instead, just think of a device as a means of grouping a set of functions and behaviors together and calling it something. They are a preferred means of wrapping together functions that are used across multiple machines.		The first thing to be aware of when thinking about devices is that you shouldn't get too hung up on the term "device". A device in MAME doesn't have to correspond to a physical chip or device or anything that concrete (although they can and often do). Instead, just think of a device as a means of grouping a set of functions and behaviors together and calling it something. They are a preferred means of wrapping together functions that are used across multiple machines.

	Devices in MAME might seem like a relatively recent concept, but in reality they are simply the culmination of previous efforts to define a consistent "plug-in" style interface for assembling a machine. CPU cores were the first device-like objects which exposed a consistent interface (see [~~http~~://mamedev~~.org~~/~~source~~/src/emu/cpuintrf.h~~.html~~ cpuintrf.h] for definitions). Later on, the sound cores got their own similar interface (see [~~http~~://mamedev~~.org~~/~~source~~/src/emu/sndintrf.h~~.html~~ sndintrf.h]). It has only been recently that a more abstract device interface (see [~~http~~://mamedev~~.org~~/~~source~~/src/emu/devintrf.h~~.html~~ devintrf.h]) has been introduced. Eventually, the CPU and sound interfaces will be retooled to be based fully on the abstract device interface, and then everything will be able to be treated equally as a generic device.		Devices in MAME might seem like a relatively recent concept, but in reality they are simply the culmination of previous efforts to define a consistent "plug-in" style interface for assembling a machine. CPU cores were the first device-like objects which exposed a consistent interface (see [https://github.com/mamedev/mame/blob/master/src/emu/cpuintrf.h cpuintrf.h] for definitions). Later on, the sound cores got their own similar interface (see [https://github.com/mamedev/mame/blob/master/src/emu/sndintrf.h sndintrf.h]). It has only been recently that a more abstract device interface (see [https://github.com/mamedev/mame/blob/master/src/emu/devintrf.h devintrf.h]) has been introduced. Eventually, the CPU and sound interfaces will be retooled to be based fully on the abstract device interface, and then everything will be able to be treated equally as a generic device.

	Devices have many nice features beyond their consistent interface that makes them useful in MAME:		Devices have many nice features beyond their consistent interface that makes them useful in MAME:

Aaron at 19:20, 3 June 2009

2009-06-03T19:20:30Z

← Older revision		Revision as of 21:20, 3 June 2009
Line 66:		Line 66:

	const device_config *device;		const device_config *device;
	device = device_list_find_by_tag(config->devicelist~~, DEVICETYPE~~, "tag");		device = device_list_find_by_tag(config->devicelist, "tag");

	You can also enumerate through all the devices of a given type:		You can also enumerate through all the devices of a given type:
Line 83:		Line 83:

	const device_config *device;		const device_config *device;
	device = devtag_get_device(machine~~, DEVICETYPE~~, "tag");		device = devtag_get_device(machine, "tag");

	There are several similar devtag_ functions declared in [http://mamedev.org/source/src/emu/devintrf.h.html devintrf.h], which replace the list head parameter with a running_machine object for easier use when the system is running.		There are several similar devtag_ functions declared in [http://mamedev.org/source/src/emu/devintrf.h.html devintrf.h], which replace the list head parameter with a running_machine object for easier use when the system is running.
Line 91:		Line 91:
	struct _device_config		struct _device_config
	{		{
	device_config * next; /* next device */		/* device relationships (always valid) */
	~~device_type type~~; /* device type */		device_config * next; /* next device (of any type/class) */
	~~device_class~~ ~~class~~; /* device class */		device_config * owner; /* device that owns us, or NULL if nobody */
	~~device_set_info_func set_info;~~ /* ~~quick pointer to set_info callback~~ */		device_config * typenext; /* next device of the same type */
	~~device_start_func start~~; /* ~~quick pointer to start callback~~ */		device_config * classnext; /* next device of the same class */
	~~device_stop_func stop~~; /* ~~quick pointer to stop callback~~ */
	~~device_reset_func reset;~~ /* ~~quick pointer to reset callback~~ */		/* device properties (always valid) */
	~~device_nvram_func nvram~~; /* ~~quick pointer to nvram callback~~ */		device_type type; /* device type */
	const void * static_config; /* static device configuration */		device_class devclass; /* device class */
	void * inline_config; /* inline device configuration */
			/* device configuration (always valid) */
			UINT32 clock; /* device clock */
			const void * static_config; /* static device configuration */
			void * inline_config; /* inline device configuration */

			/* these fields are only valid once the device is attached to a machine */
			running_machine * machine; /* machine if device is live */

	/* these fields are only valid if the device is live */		/* these fields are only valid if the device is live */
	UINT8 started; /* TRUE if the start function has succeeded */		UINT8 started; /* TRUE if the start function has succeeded */
	void * token; /* token if device is live */		void * token; /* token if device is live */
	~~void * classtoken~~; /* ~~class~~ token ~~if device is live */~~		UINT32 tokenbytes; /* size of the token data allocated */
	~~running_machine * machine; /* machine if device is live~~ */		UINT8 * region; /* pointer to region with the device's tag, or NULL */
	UINT8 * region; /* pointer to region with the device's tag */		UINT32 regionbytes; /* size of the region, in bytes */
	UINT32 regionbytes; /* size of the region, in bytes */		device_execute_func execute; /* quick pointer to execute callback */

	char tag[1]; /* tag for this instance */		/* tag (always valid; at end because it is variable-length) */
			char tag[1]; /* tag for this instance */
	};		};

Aaron: /* Using Devices */

2008-12-10T21:05:35Z

Using Devices

← Older revision		Revision as of 23:05, 10 December 2008
Line 22:		Line 22:

	== Using Devices ==		== Using Devices ==

			=== Declaring Devices ===

	The first step to using a device is declaring its existence. This is done in the machine configuration, like so:		The first step to using a device is declaring its existence. This is done in the machine configuration, like so:

			MDRV_DEVICE_ADD( "tag", DEVICETYPE )

			Here "tag" is a short, unique string that idenitifies the device, and DEVICETYPE is the name of the device in question (by convention, device names are in ALL CAPS). There can be multiple devices declared in a single machine configuration, and multiple instances of the same device (though each instance must have a unique tag).

			Once you define a device this way, it is considered the "current" device for the MDRV_ macros that follow. It is often the case that there are configuration macros following the declaration of a device:

			MDRV_DEVICE_ADD( "tag", DEVICETYPE ) // declare device
			MDRV_DEVICE_CONFIG( my_config_struct ) // provide configuration data

			In practice, however, you will rarely see MDRV_DEVICE_ADD macros in the wild. This is because it is convention for each device to define its own MDRV_ macro for declaring itself, along with any required configuration. Here is an example for the IDE controller:

			MDRV_IDE_CONTROLLER_ADD("ide", ide_interrupt)
			MDRV_IDE_BUS_MASTER_SPACE("main", PROGRAM)

			The first macro expands to an MDRV_DEVICE_ADD of an IDE_CONTROLLER, followed by configuration macros to specify the ide_interrupt function. The second macro provides two additional optional pieces of configuration data for the device.

			If you need to modify the configuration of an existing device, you can use:

			MDRV_DEVICE_MODIFY( "tag", DEVICETYPE )

			which makes a previously-declare device "current" again so that subsequent configuration macros apply to it. You can also remove a device:

			MDRV_DEVICE_REMOVE( "tag", DEVICETYPE )

			All this manipulation of devices (add/configure/remove) is done when the machine configuration is first created, and before the emulation begins. This means you can examine the list of devices and identify them very early on.

			=== Locating Devices ===

			Once a device has been declared, you will likely need to find it, in order to operate upon it. Since devices are created as part of the machine configuration, it makes sense that the list of devices is stored within the machine configuration structure itself:

			struct _machine_config
			{
			...
			const device_config * devicelist; /* list head for devices */
			};

			Once you have the head of the list, you can either walk through the list directly to find your device, or take advantage of several functions that help you locate devices. For example, to find a particular device in a machine configuration (config), use:

			const device_config *device;
			device = device_list_find_by_tag(config->devicelist, DEVICETYPE, "tag");

			You can also enumerate through all the devices of a given type:

			const device_config *device;
			for (device = device_list_first(config->devicelist, DEVICETYPE);
			device != NULL;
			device = device_list_next(device, DEVICETYPE)
			{
			...
			}

			One thing to notice is that none of these basic location functions depends on the existing of a running emulation (i.e., no running_machine object). This is primarily to allow easy enumeration and identification of devices during early startup and for informational purposes.

			However, since it is very common that a driver needs to find one or more of its devices during driver startup, there is a preferred shortcut:

			const device_config *device;
			device = devtag_get_device(machine, DEVICETYPE, "tag");

			There are several similar devtag_ functions declared in [http://mamedev.org/source/src/emu/devintrf.h.html devintrf.h], which replace the list head parameter with a running_machine object for easier use when the system is running.

			=== Device Configuration ===

			struct _device_config
			{
			device_config * next; /* next device */
			device_type type; /* device type */
			device_class class; /* device class */
			device_set_info_func set_info; /* quick pointer to set_info callback */
			device_start_func start; /* quick pointer to start callback */
			device_stop_func stop; /* quick pointer to stop callback */
			device_reset_func reset; /* quick pointer to reset callback */
			device_nvram_func nvram; /* quick pointer to nvram callback */
			const void * static_config; /* static device configuration */
			void * inline_config; /* inline device configuration */

			/* these fields are only valid if the device is live */
			UINT8 started; /* TRUE if the start function has succeeded */
			void * token; /* token if device is live */
			void * classtoken; /* class token if device is live */
			running_machine * machine; /* machine if device is live */
			UINT8 * region; /* pointer to region with the device's tag */
			UINT32 regionbytes; /* size of the region, in bytes */

			char tag[1]; /* tag for this instance */
			};

Aaron: /* All About Devices */

2008-12-09T21:00:27Z

All About Devices

← Older revision		Revision as of 23:00, 9 December 2008
Line 1:		Line 1:
	~~== All About Devices ==~~

	'''Devices''' in MAME are a mechanism for encapsulating a particular bit of functionality in a standard way. All devices have a set of common characteristics (how they start, reset, interact with the rest of the system) which makes it possible for the MAME core to treat them equally, and allows for a driver to plug any number of them together to create a working system.		'''Devices''' in MAME are a mechanism for encapsulating a particular bit of functionality in a standard way. All devices have a set of common characteristics (how they start, reset, interact with the rest of the system) which makes it possible for the MAME core to treat them equally, and allows for a driver to plug any number of them together to create a working system.

Aaron: To be continued....

2008-12-09T21:00:12Z

To be continued....

New page

== All About Devices ==

'''Devices''' in MAME are a mechanism for encapsulating a particular bit of functionality in a standard way. All devices have a set of common characteristics (how they start, reset, interact with the rest of the system) which makes it possible for the MAME core to treat them equally, and allows for a driver to plug any number of them together to create a working system.

The first thing to be aware of when thinking about devices is that you shouldn't get too hung up on the term "device". A device in MAME doesn't have to correspond to a physical chip or device or anything that concrete (although they can and often do). Instead, just think of a device as a means of grouping a set of functions and behaviors together and calling it something. They are a preferred means of wrapping together functions that are used across multiple machines.

Devices in MAME might seem like a relatively recent concept, but in reality they are simply the culmination of previous efforts to define a consistent "plug-in" style interface for assembling a machine. CPU cores were the first device-like objects which exposed a consistent interface (see [http://mamedev.org/source/src/emu/cpuintrf.h.html cpuintrf.h] for definitions). Later on, the sound cores got their own similar interface (see [http://mamedev.org/source/src/emu/sndintrf.h.html sndintrf.h]). It has only been recently that a more abstract device interface (see [http://mamedev.org/source/src/emu/devintrf.h.html devintrf.h]) has been introduced. Eventually, the CPU and sound interfaces will be retooled to be based fully on the abstract device interface, and then everything will be able to be treated equally as a generic device.

Devices have many nice features beyond their consistent interface that makes them useful in MAME:

* They demand dynamic allocation of state (instead of relying on static global variables)
* They demand support for an arbitrary number of instances (no more hard-coded limits)
* They are uniquely identifiable via their required tag
* The preferred way to locate devices is by tag, not by index, removing dependencies on ordering and the possibility of conflicts
* They are described directly in the machine configuration structure
* They can be configured entirely within the machine configuration structure (as opposed to requiring an external struct)
* They can be directly mapped in the address map, referenced by tag
* They can add to or modify the machine configuration they are part of
* They can reference their own device-specific ROMs

How this all works is explained in more detail below, in the section on writing a new device.

However, the first and most important thing to know is: as a user, how do you add, remove, configure, and interact with devices?

== Using Devices ==

The first step to using a device is declaring its existence. This is done in the machine configuration, like so: