MAME Device Basics - Revision history

Aaron: /* Overview */

2012-09-12T18:35:13Z

Overview

← Older revision		Revision as of 20:35, 12 September 2012
Line 5:		Line 5:
	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 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''.		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=		=Core Concepts=

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

2010-05-26T20:19:52Z

Example #1: Simple Device with Static Configuration

← Older revision		Revision as of 22:19, 26 May 2010
Line 135:		Line 135:
	=Example #1: Simple Device with Static Configuration=		=Example #1: Simple Device with Static Configuration=

	This example is broken into ~~two~~ subsections, describing the configuration class and then the runtime class.		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==		==Static Configuration Structure==

Aaron: /* Configuration Macros */

2010-05-26T20:18:08Z

Configuration Macros

← Older revision		Revision as of 22:18, 26 May 2010
Line 266:		Line 266:
	MDRV_DEVICE_REPLACE("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:		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;		static const device_type EXAMPLE1 = example1_device_config::static_alloc_device_config;

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

2010-05-26T20:17:38Z

Example #1: Simple Device with Static Configuration

Show changes

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

2010-05-25T05:07:57Z

Example #1: Simple Device with Static Configuration

← Older revision		Revision as of 07:07, 25 May 2010
Line 157:		Line 157:
	example1_device_config(const machine_config &mconfig, device_type type, const char *tag,		example1_device_config(const machine_config &mconfig, device_type type, const char *tag,
	const device_config *owner, UINT32 clock);		const device_config *owner, UINT32 clock);

	public:		public:
	~~virtual ~example1_device_config();~~

	// allocators		// allocators
	static device_config *static_alloc_device_config(const machine_config &mconfig,		static device_config *static_alloc_device_config(const machine_config &mconfig,
Line 184:		Line 183:

	* 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).		* 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.		* 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:		Walking through the methods defined in this class one by one, most of them are fairly simple and straightforward. First, the constructor:
Line 199:		Line 198:

	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.		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:		Next up is the static device configuration allocator:

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

2010-05-24T20:26:25Z

Example #1: Simple Device with Static Configuration

@@ Line 154: / Line 154: @@
       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);
       virtual ~example1_device_config();
@@ Line 185: / Line 185: @@
 * 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).
-(more later)
+* 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.
 =Best Practices=

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

2010-05-24T18:39:42Z

Example #1: Simple Device with Static Configuration

← Older revision		Revision as of 20:39, 24 May 2010
Line 152:		Line 152:
	public example1_device_config_data		public example1_device_config_data
	{		{
	~~DISABLE_COPYING(example1_device_config);~~

	friend class example1_device;		friend class example1_device;

Line 185:		Line 183:
	* 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.		* 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 ~~see the DISABLE_COPYING macro; this just defines a standard copy constructor and copy operator as private so that you can't accidentally assign a device and implicitly make a copy (which would be bad)~~		* 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).

	* 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).

	(more later)		(more later)

	=Best Practices=		=Best Practices=

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

2010-05-21T21:58:53Z

Example #1: Simple Device with Static Configuration

← Older revision		Revision as of 23:58, 21 May 2010
Line 176:		Line 176:
	virtual void device_config_complete();		virtual void device_config_complete();
	virtual bool device_validity_check(const game_driver &driver) const;		virtual bool device_validity_check(const game_driver &driver) const;

	// internal state		// internal state
	int m_additional_state;		int m_additional_state;

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

2010-05-21T21:58:38Z

Example #1: Simple Device with Static Configuration

← Older revision		Revision as of 23:58, 21 May 2010
Line 152:		Line 152:
	public example1_device_config_data		public example1_device_config_data
	{		{
	DISABLE_COPYING(example1_device_config );		DISABLE_COPYING(example1_device_config);

	friend class example1_device;		friend class example1_device;
Line 170:		Line 170:
	virtual const char *name() const { return "Example Device 1"; }		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		// device-level overrides
	virtual void device_config_complete();		virtual void device_config_complete();
	virtual bool device_validity_check(const game_driver &driver) const;		virtual bool device_validity_check(const game_driver &driver) const;

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

	~~protected:~~
	// internal state		// internal state
			int m_additional_state;
	};		};

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

2010-05-21T20:08:25Z

Example #1: Simple Device with Static Configuration

← Older revision		Revision as of 22:08, 21 May 2010
Line 153:		Line 153:
	{		{
	DISABLE_COPYING(example1_device_config );		DISABLE_COPYING(example1_device_config );

	friend class example1_device;		friend class example1_device;

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

	// allocators		// allocators
	static device_config static_alloc_device_config(const machine_config &mconfig, const char tag, const device_config *owner, UINT32 clock);		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;		virtual device_t *alloc_device(running_machine &machine, const device_config &config) const;

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

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

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

	protected:		protected:
	// internal state		// internal state