Guided tour through MESS - Revision history

Stefan Haubenthal: Category

2015-06-20T22:36:00Z

Mizapf: /* Main part */

2013-06-21T18:47:29Z

Main part

← Older revision		Revision as of 18:47, 21 June 2013
Line 127:		Line 127:

	=== Main part ===		=== Main part ===
			static MACHINE_CONFIG_START( ti99_4a_50hz, ti99_4x_state )
	static MACHINE_CONFIG_START( ti99_4a_50hz, ~~ti99_4x~~ )		/* CPU */
	~~MCFG_CPU_ADD~~("maincpu", TMS9900, 3000000)		MCFG_TMS99xx_ADD("maincpu", TMS9900, 3000000, memmap, cru_map, ti99_cpuconf)
	~~MCFG_CPU_PROGRAM_MAP(~~memmap)
	~~MCFG_CPU_IO_MAP(cru_map)~~		MCFG_MACHINE_START_OVERRIDE(ti99_4x_state, ti99_4a )
	~~MCFG_MACHINE_START~~( ti99_4a )		MCFG_MACHINE_RESET_OVERRIDE(ti99_4x_state, ti99_4a )
	~~MCFG_MACHINE_RESET~~( ti99_4a )

	/* Video hardware */		/* Video hardware */
Line 140:		Line 139:
	/* Main board */		/* Main board */
	MCFG_TMS9901_ADD(TMS9901_TAG, tms9901_wiring_ti99_4a, 3000000)		MCFG_TMS9901_ADD(TMS9901_TAG, tms9901_wiring_ti99_4a, 3000000)
	MCFG_DMUX_ADD( DATAMUX_TAG, ~~dmux_devices~~ )		MCFG_DMUX_ADD( DATAMUX_TAG, datamux_conf )
	MCFG_TI99_GROMPORT_ADD( GROMPORT_TAG, console_cartslot )		MCFG_TI99_GROMPORT_ADD( GROMPORT_TAG, console_cartslot )

Line 150:		Line 149:

	/* sound hardware */		/* sound hardware */
	~~MCFG_SPEAKER_STANDARD_MONO~~(~~"mono")~~		MCFG_TI_SOUND_94624_ADD( TISOUND_TAG, sound_conf )
	~~MCFG_SOUND_ADD(TISOUNDCHIP_TAG, SN94624, 3579545/8) /* 3.579545 MHz */~~
	~~MCFG_SOUND_ROUTE(ALL_OUTPUTS, "mono"~~, ~~0.75)~~
	~~MCFG_TI_SOUND_ADD( TISOUND_TAG~~ )

	/* Cassette drives */		/* Cassette drives */
	MCFG_CASSETTE_ADD( ~~CASSETTE_TAG~~, default_cassette_interface )		MCFG_SPEAKER_STANDARD_MONO("cass_out")
	MCFG_CASSETTE_ADD( ~~CASSETTE2_TAG~~, default_cassette_interface )		MCFG_CASSETTE_ADD( "cassette", default_cassette_interface )
			MCFG_CASSETTE_ADD( "cassette2", default_cassette_interface )

			MCFG_SOUND_WAVE_ADD(WAVE_TAG, "cassette")
			MCFG_SOUND_ROUTE(ALL_OUTPUTS, "cass_out", 0.25)

	~~MCFG_SOUND_WAVE_ADD(WAVE_TAG, CASSETTE_TAG)~~
	~~MCFG_SOUND_ROUTE(ALL_OUTPUTS, "mono", 0.25)~~

	/* GROM devices */		/* GROM devices */
	MCFG_GROM_ADD( GROM0_TAG, grom0_config )		MCFG_GROM_ADD( GROM0_TAG, grom0_config )
Line 167:		Line 164:
	MCFG_GROM_ADD( GROM2_TAG, grom2_config )		MCFG_GROM_ADD( GROM2_TAG, grom2_config )

	/* ~~User controller~~ */		/* Joystick port */
	~~MCFG_MECMOUSE_ADD~~( ~~MECMOUSE_TAG~~, 50 )		MCFG_TI_JOYPORT4A_ADD( JOYPORT_TAG, joyport4a_50 )

	MACHINE_CONFIG_END		MACHINE_CONFIG_END

	This is a complete system description. The lines are not executed one after the other, although the order does matter for some lines. Actually, each line is a macro that is translated to a operation to put a value into the system description object which you won't see anywhere; it is part of the core.		This is a complete system description. The lines are not executed one after the other, although the order does matter for some lines. Actually, each line is a macro that is translated to a operation to put a value into the system description object which you won't see anywhere; it is part of the core.

	~~MCFG_CPU_ADD~~ is a ~~macro to~~ add a device, in particular, a device that can be ''scheduled''. It defines a clock frequency as 3000000 Hz, creates an instance of the device (class) TMS9900 which is defined in tms9900.h. Note that MESS has an own model of component management - the devices like TMS9900 should not be understood as ''objects'' but as ''components''. Instances of these components are automatically created at runtime, and they are referenced by a name given as a string. In this case it is "maincpu". Whenever the string "maincpu" appears, the system will follow a reference to the concrete instance of the component.		MCFG_TMS99xx_ADD is a specialized version of MCFG_DEVICE_ADD which add a device; here, in particular, a device that can be ''scheduled''. It defines a clock frequency as 3000000 Hz, creates an instance of the device (class) TMS9900 which is defined in tms9900.h.

	~~Thus~~, in order to get a running system, you have to instantiate a set of schedulable objects, and these objects are then run by the MAME core at their defined frequencies. What follows now is to connect the signal lines of these components to other components in the system.		Note that MESS has an own model of '''component''' management - the devices like TMS9900 should not be understood as ''objects'' but as ''components''. Instances of these components are automatically created at runtime, and they are referenced by a name given as a string. In this case it is "maincpu". Whenever the string "maincpu" appears, the system will follow a reference to the concrete instance of the component. Accordingly you do not instantiate a component in the same way as an object (by new), but by registering the component class with the core. Components are usually not created on demand but all at startup time.

			Hence, in order to get a running system, you have to instantiate a set of schedulable objects, and these objects are then run by the MAME core at their defined frequencies. What follows now is to connect the signal lines of these components to other components in the system.

	Any schedulable components may have up to three address spaces: a PROGRAM space, a DATA space, and an IO space. For the TI-99/4A we define a PROGRAM space to encompass the whole 64 KiB address space, while the IO space corresponds to the CRU lines. We do not define a DATA space as the TI console is a standard Von-Neumann architecture. (Note that you could maybe create a Harvard architecture with separate program and data space by making use of the IAQ output line of the processor. This line is asserted when the processor attempts to get a command word over the bus.)		Any schedulable components may have up to three address spaces: a PROGRAM space, a DATA space, and an IO space. For the TI-99/4A we define a PROGRAM space to encompass the whole 64 KiB address space, while the IO space corresponds to the CRU lines. We do not define a DATA space as the TI console is a standard Von-Neumann architecture. (Note that you could maybe create a Harvard architecture with separate program and data space by making use of the IAQ output line of the processor. This line is asserted when the processor attempts to get a command word over the bus.)

	The idea is now that a map be declared for each address space. This is contained within the ti99_4x.c file.		The idea is now that a map be declared for each address space. This is contained within the ti99_4x.c file.

			static ADDRESS_MAP_START(memmap, AS_PROGRAM, 16, ti99_4x_state)
			ADDRESS_MAP_GLOBAL_MASK(0xffff)
			AM_RANGE(0x0000, 0x1fff) AM_ROM
			AM_RANGE(0x8000, 0x80ff) AM_MIRROR(0x0300) AM_RAM
			AM_RANGE(0x0000, 0xffff) AM_DEVREADWRITE(DATAMUX_TAG, ti99_datamux_device, read, write)
			ADDRESS_MAP_END

			While the processor runs, it performs accesses into the address space. The map as given here declares what happens in specific sections of the address space.

			* In the area from 0000 - 1fff (hex), the ROM is accessed. This means that write accesses are ignored, and that the contents can be found in the appropriate ROM section.
			* In the area of 8000 to 80ff, we have a 256 byte of RAM memory (Scratch pad) which is mirrored at addresses that are defined by the mirror mask 0x0300. The mirror mask tells us which bits may be set to define a mirror. In this case, the main address area is 8000-80ff, and the three other options are 8100-81ff, 8200-82ff, and 8300-83ff. Indeed, if you check the schematics, you will see that these lines are not decoded, so the scratch pad RAM is mirrored at these addresses.
			* The last line covers the whole address space. It will only be reached when no other option before applies. What it does is that it calls the READ and WRITE handlers of a component identified by DATAMUX_TAG, instantiated from ti99_datamux_device, with a method called ''read'' for reading and a method ''write'' for writing.

			The databus multiplexer is a collection of circuits which converts the 16-bit data bus of the TMS9900 to an 8-bit time-multiplexed bus. This means that each word access is split into two byte accesses. We do not see this here, but in the implementation of the datamux; see datamux.c.

			class ti99_datamux_device : public device_t
			{
			public:
			ti99_datamux_device(const machine_config &mconfig, const char tag, device_t owner, UINT32 clock);
			DECLARE_READ16_MEMBER( read );
			DECLARE_WRITE16_MEMBER( write );
			...

			This is the start of the declaration of the component in datamux.h. Besides the constructor which is called form the MAME core, the two access methods read and write are declared. They carry a set of parameters which are required for the component handling, and by using the macro DECLARE_READ16_MEMBER we can hide the details. Correspondingly, in the file datamux.c we have

			READ16_MEMBER( ti99_datamux_device::read )

			which is the implementation of this method.

			Summarizing: When the CPU reads, for example, from address at location >6000, the core will consult the address map, searches through the map, finds the entry for the datamux, and invokes the read method on the instance identified by DATAMUX_TAG.

	'''To be continued'''		'''To be continued'''

Mizapf at 18:12, 21 June 2013

2013-06-21T18:12:40Z

← Older revision		Revision as of 18:12, 21 June 2013
Line 171:		Line 171:
	MACHINE_CONFIG_END		MACHINE_CONFIG_END

			This is a complete system description. The lines are not executed one after the other, although the order does matter for some lines. Actually, each line is a macro that is translated to a operation to put a value into the system description object which you won't see anywhere; it is part of the core.

			MCFG_CPU_ADD is a macro to add a device, in particular, a device that can be ''scheduled''. It defines a clock frequency as 3000000 Hz, creates an instance of the device (class) TMS9900 which is defined in tms9900.h. Note that MESS has an own model of component management - the devices like TMS9900 should not be understood as ''objects'' but as ''components''. Instances of these components are automatically created at runtime, and they are referenced by a name given as a string. In this case it is "maincpu". Whenever the string "maincpu" appears, the system will follow a reference to the concrete instance of the component.

			Thus, in order to get a running system, you have to instantiate a set of schedulable objects, and these objects are then run by the MAME core at their defined frequencies. What follows now is to connect the signal lines of these components to other components in the system.

			Any schedulable components may have up to three address spaces: a PROGRAM space, a DATA space, and an IO space. For the TI-99/4A we define a PROGRAM space to encompass the whole 64 KiB address space, while the IO space corresponds to the CRU lines. We do not define a DATA space as the TI console is a standard Von-Neumann architecture. (Note that you could maybe create a Harvard architecture with separate program and data space by making use of the IAQ output line of the processor. This line is asserted when the processor attempts to get a command word over the bus.)

			The idea is now that a map be declared for each address space. This is contained within the ti99_4x.c file.

	'''To be continued'''		'''To be continued'''

Mizapf at 10:45, 14 November 2012

2012-11-14T10:45:22Z

← Older revision		Revision as of 10:45, 14 November 2012
Line 1:		Line 1:
	MESS is lacking what many software projects, in particular open-source projects, also fail to give: a good introduction to find into the concepts of what you can see there as program code. This is rarely a malevolence of the implemententors; it is usually caused by one or more of these reasons:		MESS is lacking what many software projects, in particular open-source projects, also fail to give: a good introduction to find into the concepts of what you can see there as program code. This is rarely a malevolence of the implemententors; it is usually caused by one or more of these reasons:

	* ''lack of time'': We have to fix bug#18274 and have to more time to write the docs		* ''lack of time'': We have to fix bug#18274 and have no more time to write the docs
	* ''outdated'': Docs have been written with quite some efforts, but since version x.y most of them do not apply any longer, and no one really has the energy to make them catch up ([http://en.wikipedia.org/wiki/Sisyphus Sisyphus])		* ''outdated'': Docs have been written with quite some efforts, but since version x.y most of them do not apply any longer, and no one really has the energy to make them catch up ([http://en.wikipedia.org/wiki/Sisyphus Sisyphus])
	* ''different level of understanding'': What may be plain to see for the developer is often cryptic to the beginner.		* ''different level of understanding'': What may be plain to see for the developer is often cryptic to the beginner.
	* ''hidden knowledge'': Similar to the last point, the developer does not even know that he ~~adds some missing links for understanding~~.		* ''hidden knowledge'': Similar to the last point, the developer does not even know that he assumes knowledge which the reader need not have.

	I'll try to fight the last two points with this guided tour through MESS. We will discuss on the example of the TI-99/4A emulation how MESS works and how to implement new parts.		I'll try to fight the last two points with this guided tour through MESS. We will discuss on the example of the TI-99/4A emulation how MESS works and how to implement new parts.

Mizapf at 13:42, 4 March 2012

2012-03-04T13:42:37Z

@@ Line 43: / Line 43: @@
 | ...
 |}
 == Starting point ==
@@ Line 107: / Line 125: @@
 We could also clip the GROM region, since we put cartridge GROMs in their own regions. (Maybe I'll do that in a later release.) For now it does not hurt to waste 40960 bytes.

Mizapf at 13:20, 4 March 2012

2012-03-04T13:20:15Z

← Older revision		Revision as of 13:20, 4 March 2012
Line 5:		Line 5:
	* ''different level of understanding'': What may be plain to see for the developer is often cryptic to the beginner.		* ''different level of understanding'': What may be plain to see for the developer is often cryptic to the beginner.
	* ''hidden knowledge'': Similar to the last point, the developer does not even know that he adds some missing links for understanding.		* ''hidden knowledge'': Similar to the last point, the developer does not even know that he adds some missing links for understanding.

			I'll try to fight the last two points with this guided tour through MESS. We will discuss on the example of the TI-99/4A emulation how MESS works and how to implement new parts.

			== Terminology ==

			MESS is a sister project of MAME, the ''Multi Arcade Machine Emulator''. It uses the same software core but adds new structures and support for typical devices used with computers. MAME introduced some terms which are also used inside MESS (which is reasonable, or we would need a dictionary all the time) but which can be confusing or misleading sometimes. Accordingly, I will present some of the more important terms here.

			{\| class="plain" style="width:90%; margin-top:3em"
			! MAME/MESS term
			! Meaning
			\|-
			\| Game
			\| Refers to the emulated system (consider the viewpoint of MAME); GAME_NOT_WORKING is a flag to mark a system as non-functional
			\|-
			\| Driver
			\| The complete system; ti99_4a is a driver, as is geneve.
			\|-
			\| Device
			\| An instance of the device_t class. Managed by the core.
			\|-
			\| Image
			\| Representation of memory contents stored in a file, usually referring to media like disks, cartridges
			\|-
			\| Dump
			\| File of ROM contents. Good dump = verified to be correct; overdump = dump that is longer than the original contents
			\|-
			\| Cartridges
			\| Representation of pluggable software components, like the TI-99/4A command modules.
			\|-
			\| CHD
			\| Compressed Hunk of Data, storage format for mass storage devices, allows for uncompressed or compressed and checksummed content.
			\|-
			\| Input ports
			\| Any kind of system component that changes state on external action, like a dip switch or a key on the keyboard.
			\|-
			\| ...
			\| ...
			\|}

			== Starting point ==

			MESS can be started from the command line or from a frontend like QMC2. The frontend supplies the same parameters to the emulator as would be required on a command line. A simple command line could look like this:

			mess ti99_4ae

			The executable program file is '''mess''' (in Windows: mess.exe), sometimes also '''mess64''' (for 64 bit systems) or '''messd''' (special version containing symbols for debugging) or '''mess64d'''. If you want to find bugs in the emulator (not in your TI programs running on the emulator!) you should use a debug build. For normal usage the standard build is recommended which is also much smaller.

			Within the whole TI emulation part you will not find any '''int main(...)'''. The main function belongs to the core, and this is a area where I would recommended to go not before you finished our tour and completely understood the concepts. For now, just keep in mind that the program starts somewhere in the core and will later reach the TI emulation.

			=== The system ===

			The first thing to do for the system is to process the argument ti99_4ae. This is a name of a driver which it must look up in its tables. These tables were created during build time, so this is not of interest for you. The file where we should look at next is '''ti99_4x.c'''. (It could have been named in any way - the important point are the data which it registers in the core.)

			At the end of ti99_4x we can find the following lines:

			COMP( 1979, ti99_4, 0, 0, ti99_4_60hz, ti99_4, 0, "Texas Instruments", "TI99/4 Home Computer (US)" , 0)
			COMP( 1980, ti99_4e, ti99_4, 0, ti99_4_50hz, ti99_4, 0, "Texas Instruments", "TI99/4 Home Computer (Europe)" , 0)
			COMP( 1981, ti99_4a, 0, 0, ti99_4a_60hz, ti99_4a, 0, "Texas Instruments", "TI99/4A Home Computer (US)" , 0)
			COMP( 1981, ti99_4ae, ti99_4a, 0, ti99_4a_50hz, ti99_4a, 0, "Texas Instruments", "TI99/4A Home Computer (Europe)" , 0)
			COMP( 1994, ti99_4ev, ti99_4a, 0, ti99_4ev_60hz,ti99_4a, 0, "Texas Instruments", "TI99/4A Home Computer with EVPC" , 0)

			'''COMP''' is not a command, but it is a macro which is transformed to a structure that is loaded into the core at startup time. In the fourth line you can find the character string that we provided on the command line.

			The components of the lines have the following meaning:

			* Year of the release of the system; just an information item
			* The driver name
			* The parent driver name.
			* Compatibility information (not used here)
			* Machine name - this one points to configuration data
			* A pointer to the configuration of input ports
			* Initialization information (not used here)
			* Company; just information
			* System name; used in frontends

			There is already one important thing to note. Drivers (see above for the meaning - it is the complete system) may have ''children''. Sometimes you have systems that closely resemble each other, except for some small differences. If they share the same ROM dumps you can avoid to provide the dumps for each system again. In our case, the ti99_4ae driver is a child of ti99_4a; it only differs in the video refresh rate. Therefore we do not need to provide the emulator with the dumps for ti99_4a and ti99_4ae. If the emulator cannot find a ROM dump for a driver, it checks whether there is a parent which can deliver the missing dumps. As all dumps are the same, it suffices to provide the ROMs for ti99_4a only.

			=== ROMs ===

			The next thing the core has to find out is whether it must load any ROM dumps, and how they are named. For a TI-99/4A we need dumps for the console ROMs and GROMs. This is also declared inside ti99_4x.c:

			ROM_START(ti99_4a)
			ROM_REGION16_BE(0x2000, "maincpu", 0)
			ROM_LOAD16_WORD("994arom.bin", 0x0000, 0x2000, CRC(db8f33e5) SHA1(6541705116598ab462ea9403c00656d6353ceb85))
			ROM_REGION(0x10000, region_grom, 0)
			ROM_LOAD("994agrom.bin", 0x0000, 0x6000, CRC(af5c2449) SHA1(0c5eaad0093ed89e9562a2c0ee6a370bdc9df439))
			ROM_END

			As just explained, we do not have separate ROMs for ti99_4ae, so the core looks up the parent name and finds this structure. Again, ROM_START is a macro, like all the other capitalized terms. It does not execute anything but transforms the data as shown here into a structure that is registered in the core. The CRC and SHA1 declarations are used to verify that the ROMs are unchanged.

			What if I want to use a modified ROM? - Well, this is not directly possible. You would need to calculate the new CRC and SHA1 values (MESS prints them on startup when they differ) and recompile the emulator. If it were allowed to modify the ROMs, debugging would become a nightmare. Imagine your TI emulation locks up - we could not be sure whether the bug is in the emulation or whether the dump has been modified. Sorry ... you're on your own here.

			Both ROM files must be stored in a ZIP file named after the driver name, in this case ti99_4a.zip. The lines should be read in this way:

			* This is ROM content for the memory region "maincpu" (see later).
			* It is 16 bit (our ROMs are connected to the 16 bit bus), and the byte order is big-endian (in the TI, the most significant byte has a lower address than the least significant byte; if you store >1234 at >A000, then >12 is at >A000 and >34 is at >A001). PCs use little-endian, in contrast.
			* Load the contents of the file "994arom.bin" into the region, >2000 bytes (8192).
			* Another region we use is region_grom (somewhere else declared as a string "console_groms").
			* Its size is 64 KiB (yes, each GROMs only has 6 KiB contents, but they nevertheless occupy the whole address space) and it is 8-bit memory.
			* We load the contents of "994agrom.bin" into the region, size is >6000 bytes (24576; the first three GROMs). The remainder of the region is filled with zeros.

			We could also clip the GROM region, since we put cartridge GROMs in their own regions. (Maybe I'll do that in a later release.) For now it does not hurt to waste 40960 bytes.

Mizapf: Created page with "MESS is lacking what many software projects, in particular open-source projects, also fail to give: a good introduction to find into the concepts of what you can see there as pro..."

2012-03-04T11:31:07Z

Created page with "MESS is lacking what many software projects, in particular open-source projects, also fail to give: a good introduction to find into the concepts of what you can see there as pro..."

New page

MESS is lacking what many software projects, in particular open-source projects, also fail to give: a good introduction to find into the concepts of what you can see there as program code. This is rarely a malevolence of the implemententors; it is usually caused by one or more of these reasons:

* ''lack of time'': We have to fix bug#18274 and have to more time to write the docs
* ''outdated'': Docs have been written with quite some efforts, but since version x.y most of them do not apply any longer, and no one really has the energy to make them catch up ([http://en.wikipedia.org/wiki/Sisyphus Sisyphus])
* ''different level of understanding'': What may be plain to see for the developer is often cryptic to the beginner.
* ''hidden knowledge'': Similar to the last point, the developer does not even know that he adds some missing links for understanding.

← Older revision		Revision as of 22:36, 20 June 2015
Line 213:		Line 213:

	'''To be continued'''		'''To be continued'''

			[[Category:MESS]]