Address Maps - Revision history

Galibert: Obsolete, redirect to up-to-date doc.

2020-12-10T09:43:36Z

Obsolete, redirect to up-to-date doc.

Stiletto at 03:26, 25 November 2014

2014-11-25T03:26:20Z

← Older revision		Revision as of 05:26, 25 November 2014
Line 3:		Line 3:
	== Address Map Structure ==		== Address Map Structure ==

	A typical address map looks like this (this example is taken from the [~~https~~://github.com/mamedev/mame/blob/master/src/mame/drivers/qix.c qix.c driver]):		A typical address map looks like this (this example is taken from the [http://github.com/mamedev/mame/blob/master/src/mame/drivers/qix.c qix.c driver]):

	static ADDRESS_MAP_START( main_map, ADDRESS_SPACE_PROGRAM, 8 )		static ADDRESS_MAP_START( main_map, ADDRESS_SPACE_PROGRAM, 8 )

Stiletto at 03:06, 25 November 2014

2014-11-25T03:06:15Z

← Older revision		Revision as of 05:06, 25 November 2014
Line 3:		Line 3:
	== Address Map Structure ==		== Address Map Structure ==

	A typical address map looks like this (this example is taken from the [~~http~~://mamedev~~.org~~/~~source~~/src/mame/drivers/qix.c~~.html~~ qix.c driver]):		A typical address map looks like this (this example is taken from the [https://github.com/mamedev/mame/blob/master/src/mame/drivers/qix.c qix.c driver]):

	static ADDRESS_MAP_START( main_map, ADDRESS_SPACE_PROGRAM, 8 )		static ADDRESS_MAP_START( main_map, ADDRESS_SPACE_PROGRAM, 8 )

Aaron: /* Debugging Helpers */

2008-04-21T19:51:49Z

Debugging Helpers

← Older revision		Revision as of 21:51, 21 April 2008
Line 200:		Line 200:

	== Debugging Helpers ==		== Debugging Helpers ==
			When using the debugger, there are a few useful commands that can help you figure out what is going on with the address mapping.

			The first command is the map command:
			map <address>

			This command has two purposes. First, if you are running on a CPU that supports address translation, the debugger will look up the translation and tell you which physical address the ''address'' parameter is referring to. And second, the debugger will look up the read and write handlers associated with that address and print them out.

Aaron: /* Runtime Modifications */

2008-04-21T19:48:08Z

Runtime Modifications

← Older revision		Revision as of 21:48, 21 April 2008
Line 183:		Line 183:

	== Runtime Modifications ==		== Runtime Modifications ==
			Address maps as described above are hooked up to a CPU by specifying them in a machine configuration. It is common for several game drivers to reference the same machine configuration because many games run on common hardware platforms. However, if even one change needs to be made to the address map for a game, you would need to replicate the machine configuration and the address map just to specify that one alteration.

			To address this and other more complex addressing schemes at runtime, it is possible to dynamically alter an address map after it has been constructed. Generally, game-specific tweaks to an address map are handled in the DRIVER_INIT callback. However, changes can actually be made at any time during execution, so if you have a system that can radically alter its memory map or dynamically configure where peripherals are mapped, you can accomplish this by rewriting portions of the address map "live".

			The key functions for performing these changes are:
			memory_install_read8_handler(machine, cpu, space, start, end, mask, mirror, rhandler)
			memory_install_write8_handler(machine, cpu, space, start, end, mask, mirror, rhandler)
			memory_install_readwrite8_handler(machine, cpu, space, start, end, mask, mirror, rhandler, whandler)
			(Note the '8' in the function names — that specifies the data bus width of the handler you are installing. To install a 16-bit handler, replace the '8' with '16'; repeat for 32-bit and 64-bit handlers.)

			As you can see, the parameters to these functions replicate most of the parameters you can control via the address map. ''machine'' is a pointer to the current running_machine. ''cpu'' gives the CPU index (CPU 0 is the first CPU). ''space'' specifies which address space you wish to modify. ''start'', ''end'', ''mirror'', and ''mask'' correspond directly to the values specified in the address map, described above. And ''rhandler'' and ''whandler'' represent pointers to the read and write callback functions, respectively.

			Note that there is no corresponding function to "uninstall" a memory handler — you can't do that, as the memory system does not keep track of the ordering of handlers or their original parameters. If you want to unmap something, you can install read/write handlers of '''SMH_UNMAP'''. In fact, you can wipe the entire address space clean by installing '''SMH_UNMAP''' handlers across the entire space, and then rebuilding the address map from there.

			Also note that you cannot install '''SMH_RAM''' or '''SMH_ROM''' dynamically. This is because RAM and ROM are treated specially at initialization time and are dynamically converted into memory banks. If you need to dynamically install RAM or ROM space, you can use '''SMH_BANK(n)''' instead and explicitly set the bank base via a call to <code>memory_set_bankptr</code>.

	== Debugging Helpers ==		== Debugging Helpers ==

Aaron at 19:48, 16 April 2008

2008-04-16T19:48:04Z

← Older revision		Revision as of 21:48, 16 April 2008
Line 55:		Line 55:

	=== AM_READn, AM_WRITEn, AM_READWRITEn ===		=== AM_READn, AM_WRITEn, AM_READWRITEn ===
	AM_READ8(readhandler, ~~shift~~)		AM_READ8(readhandler, mask)
	AM_WRITE8(writehandler, ~~shift~~)		AM_WRITE8(writehandler, mask)
	AM_READWRITE8(readhandler, writehandler, ~~shift~~)		AM_READWRITE8(readhandler, writehandler, mask)
	AM_READ16(readhandler, ~~shift~~)		AM_READ16(readhandler, mask)
	AM_WRITE16(writehandler, ~~shift~~)		AM_WRITE16(writehandler, mask)
	AM_READWRITE16(readhandler, writehandler, ~~shift~~)		AM_READWRITE16(readhandler, writehandler, mask)
	AM_READ32(readhandler, ~~shift~~)		AM_READ32(readhandler, mask)
	AM_WRITE32(writehandler, ~~shift~~)		AM_WRITE32(writehandler, mask)
	AM_READWRITE32(readhandler, writehandler, ~~shift~~)		AM_READWRITE32(readhandler, writehandler, mask)

	These variants of the standard '''AM_READ''' and '''AM_WRITE''' macros allow you to specify a read or write handler for a data bus width smaller than the data bus width of the current address space. By default, read and write handlers must be sized equal to the data bus width; for example, on a 32-bit wide data bus, you must specify a READ32_HANDLER function. However, it is common to use peripheral devices with smaller data bus widths on systems that have a wide data bus. In general, when this is done, one of two approaches is used.		These variants of the standard '''AM_READ''' and '''AM_WRITE''' macros allow you to specify a read or write handler for a data bus width smaller than the data bus width of the current address space. By default, read and write handlers must be sized equal to the data bus width; for example, on a 32-bit wide data bus, you must specify a READ32_HANDLER function. However, it is common to use peripheral devices with smaller data bus widths on systems that have a wide data bus. In general, when this is done, one of two approaches is used.

	The simpler approach is simply to map only a subset of the bits to that peripheral. This is most commonly done on arcade hardware where backwards compatibility is not important. So if you had, for example, an 8-bit device on a 32-bit data bus, the hardware designer could choose any of four possible byte lanes to position those 8 bits on, shifted either 0, 8, 16, or 24 bits. Whenever a read or write to that address occurs, only 8 of the 32 bits are provided by the device and all other bits are effectively unmapped. In this case, you would use the '''AM_READ8''' macro and provide a ''~~shift~~'' value, ~~indiciating how much~~ to ~~shift the~~ 8-~~bit value to locate it in the right bits~~.		The simpler approach is simply to map only a subset of the bits to that peripheral. This is most commonly done on arcade hardware where backwards compatibility is not important. So if you had, for example, an 8-bit device on a 32-bit data bus, the hardware designer could choose any of four possible byte lanes to position those 8 bits on, shifted either 0, 8, 16, or 24 bits. Whenever a read or write to that address occurs, only 8 of the 32 bits are provided by the device and all other bits are effectively unmapped. In this case, you would use the '''AM_READ8''' macro and provide a ''mask'' value indicating which of the 8 bits were controlled by the device (for example, if the device is connected to bits 8-15, you would use a mask of 0xff00).

	The second approach is more complicated, and involves "packing" the address space of the device into the data bus width. This is far more common on computers where backwards compatbility is important. In the example above, instead of each 32-bit access only generating a single 8-bit access to the device, it could be packed such that a single 32-bit read actually generates 4 separate 8-bit accesses and packs the results into a single 32-bit result. To describe this situation, you could use the '''AM_READ8''' macro with a ~~special~~ ''~~shift~~'' value of ~~SHIFT_PACKED~~.		The second approach is more complicated, and involves "packing" the address space of the device into the data bus width. This is far more common on computers where backwards compatbility is important. In the example above, instead of each 32-bit access only generating a single 8-bit access to the device, it could be packed such that a single 32-bit read actually generates 4 separate 8-bit accesses and packs the results into a single 32-bit result. To describe this situation, you could use the '''AM_READ8''' macro with a ''mask'' value indicating that all bits are mapped to the device (for a 32-bit bus, that would be a mask of 0xffffffff).

	=== AM_READ_PORT ===		=== AM_READ_PORT ===
Line 84:		Line 84:

	=== AM_DEVREADn, AM_DEVWRITEn, AM_DEVREADWRITEn ===		=== AM_DEVREADn, AM_DEVWRITEn, AM_DEVREADWRITEn ===
	AM_DEVREAD8(type, tag, readhandler, ~~shift~~)		AM_DEVREAD8(type, tag, readhandler, mask)
	AM_DEVWRITE8(type, tag, writehandler, ~~shift~~)		AM_DEVWRITE8(type, tag, writehandler, mask)
	AM_DEVREADWRITE8(type, tag, readhandler, writehandler, ~~shift~~)		AM_DEVREADWRITE8(type, tag, readhandler, writehandler, mask)
	AM_DEVREAD16(type, tag, readhandler, ~~shift~~)		AM_DEVREAD16(type, tag, readhandler, mask)
	AM_DEVWRITE16(type, tag, writehandler, ~~shift~~)		AM_DEVWRITE16(type, tag, writehandler, mask)
	AM_DEVREADWRITE16(type, tag, readhandler, writehandler, ~~shift~~)		AM_DEVREADWRITE16(type, tag, readhandler, writehandler, mask)
	AM_DEVREAD32(type, tag, readhandler, ~~shift~~)		AM_DEVREAD32(type, tag, readhandler, mask)
	AM_DEVWRITE32(type, tag, writehandler, ~~shift~~)		AM_DEVWRITE32(type, tag, writehandler, mask)
	AM_DEVREADWRITE32(type, tag, readhandler, writehandler, ~~shift~~)		AM_DEVREADWRITE32(type, tag, readhandler, writehandler, mask)

	These macros are perfectly analagous to the '''AM_READn''', '''AM_WRITEn''' and '''AM_READWRITEn''' macros, except that they allow you to specify a device.		These macros are perfectly analagous to the '''AM_READn''', '''AM_WRITEn''' and '''AM_READWRITEn''' macros, except that they allow you to specify a device.
Line 147:		Line 147:

	AM_RAM is short for AM_READWRITE(SMH_RAM, SMH_RAM), specifying that the given range should be treated as RAM. It is vital to understand that SMH_RAM and SMH_ROM are special static memory handlers which only have meaning when specified in an address map structure. They cannot be used to dynamically install RAM or ROM; see the section on [[#Runtime Modifications\|Runtime Modifications]] below for more details.		AM_RAM is short for AM_READWRITE(SMH_RAM, SMH_RAM), specifying that the given range should be treated as RAM. It is vital to understand that SMH_RAM and SMH_ROM are special static memory handlers which only have meaning when specified in an address map structure. They cannot be used to dynamically install RAM or ROM; see the section on [[#Runtime Modifications\|Runtime Modifications]] below for more details.

			=== AM_RAM_WRITE ===

			AM_RAM_WRITE(handler) is short for AM_READWRITE(SMH_RAM, handler), specifying that the given range should be treated as RAM for reads but should call the provided ''handler'' for writes. This is commonly used for memory ranges that are backed by RAM but which require some processing whenever a write occurs. A typical example is the memory backing a tilemap; reads need no special processing but a write needs to mark the tilemap dirty at the appropriate location.

	=== AM_ROM ===		=== AM_ROM ===

Aaron: /* AM_READn, AM_WRITEn, AM_READWRITEn */

2008-04-14T19:49:16Z

AM_READn, AM_WRITEn, AM_READWRITEn

← Older revision		Revision as of 21:49, 14 April 2008
Line 67:		Line 67:
	These variants of the standard '''AM_READ''' and '''AM_WRITE''' macros allow you to specify a read or write handler for a data bus width smaller than the data bus width of the current address space. By default, read and write handlers must be sized equal to the data bus width; for example, on a 32-bit wide data bus, you must specify a READ32_HANDLER function. However, it is common to use peripheral devices with smaller data bus widths on systems that have a wide data bus. In general, when this is done, one of two approaches is used.		These variants of the standard '''AM_READ''' and '''AM_WRITE''' macros allow you to specify a read or write handler for a data bus width smaller than the data bus width of the current address space. By default, read and write handlers must be sized equal to the data bus width; for example, on a 32-bit wide data bus, you must specify a READ32_HANDLER function. However, it is common to use peripheral devices with smaller data bus widths on systems that have a wide data bus. In general, when this is done, one of two approaches is used.

	The simpler approach is simply to map only a subset of the bits to that peripheral. This is most commonly done on arcade hardware where backwards compatibility is not important. So if you had, for example, an 8-bit device on a 32-bit data bus, the hardware designer could choose any of four possible byte lanes to position those 8 bits on, shifted either 0, 8, 16, or 24 bits. Whenever a read or write to that address occurs, only 8 of the 32 bits are provided by the device and all other bits are effectively unmapped. In this case, you would use the '''AM_READ8''' macro and provide an ''shift'' value, indiciating how much to shift the 8-bit value to locate it in the right bits.		The simpler approach is simply to map only a subset of the bits to that peripheral. This is most commonly done on arcade hardware where backwards compatibility is not important. So if you had, for example, an 8-bit device on a 32-bit data bus, the hardware designer could choose any of four possible byte lanes to position those 8 bits on, shifted either 0, 8, 16, or 24 bits. Whenever a read or write to that address occurs, only 8 of the 32 bits are provided by the device and all other bits are effectively unmapped. In this case, you would use the '''AM_READ8''' macro and provide a ''shift'' value, indiciating how much to shift the 8-bit value to locate it in the right bits.

	The second approach is more complicated, and involves "packing" the address space of the device into the data bus width. This is far more common on computers where backwards compatbility is important. In the example above, instead of each 32-bit access only generating a single 8-bit access to the device, it could be packed such that a single 32-bit read actually generates 4 separate 8-bit accesses and packs the results into a single 32-bit result. To describe this situation, you could use the '''AM_READ8''' macro with a special ''shift'' value of SHIFT_PACKED.		The second approach is more complicated, and involves "packing" the address space of the device into the data bus width. This is far more common on computers where backwards compatbility is important. In the example above, instead of each 32-bit access only generating a single 8-bit access to the device, it could be packed such that a single 32-bit read actually generates 4 separate 8-bit accesses and packs the results into a single 32-bit result. To describe this situation, you could use the '''AM_READ8''' macro with a special ''shift'' value of SHIFT_PACKED.

Aaron at 19:48, 14 April 2008

2008-04-14T19:48:24Z

@@ Line 1: / Line 1: @@
 Address maps define how the address space of a CPU is layed out. This article aims to explain how address maps are declared and modified. Before reading this article, you might also want to check out [[CPUs and Address Spaces]].
 == Address Map Structure ==
@@ Line 52: / Line 50: @@
 Instead of passing the raw address to the read/write handlers, the memory system actually passes an offset relative to the ''start'' address provided in the '''AM_RANGE''' macro. This allows for common handlers regardless of where the component is actually mapped in the address space.
-In addition to regular function pointers, a small number of static identifiers are also permitted. For example, in an 8-bit address map, you can specify a ''readhandler'' of MRA8_RAM to specify a dynamically allocated region of RAM, or a ''writehandler'' of MWA8_UNMAP to specify that the current address range is unmapped for writes. More information on the supported static handler types is provided later.
+In addition to regular function pointers, a small number of static identifiers are also permitted. For example, in an 8-bit address map, you can specify a ''readhandler'' of SMH_RAM to specify a dynamically allocated region of RAM, or a ''writehandler'' of SMH_UNMAP to specify that the current address range is unmapped for writes. More information on the supported static handler types is provided later.
 The '''AM_READWRITE''' macro is really just a shortcut for '''AM_READ''' followed by '''AM_WRITE'''.
 === AM_READ_PORT ===
@@ Line 67: / Line 82: @@
 To specify which device you wish to pass to the read/write handler, you provide the device's ''type'' and ''tag'', which is used to look up the device.
 === AM_MASK ===

Aaron: /* AM_RAM */

2008-03-20T20:02:32Z

AM_RAM

← Older revision		Revision as of 22:02, 20 March 2008
Line 118:		Line 118:
	=== AM_RAM ===		=== AM_RAM ===

	AM_RAM is short for AM_READWRITE(SMH_RAM, SMH_RAM), specifying that the given range should be treated as RAM. It is vital to understand that SMH_RAM and SMH_ROM are special static memory handlers which only have meaning when specified in an address map structure. They cannot be used to dynamically install RAM or ROM; see the section on Runtime Modifications below for more details.		AM_RAM is short for AM_READWRITE(SMH_RAM, SMH_RAM), specifying that the given range should be treated as RAM. It is vital to understand that SMH_RAM and SMH_ROM are special static memory handlers which only have meaning when specified in an address map structure. They cannot be used to dynamically install RAM or ROM; see the section on [[#Runtime Modifications\|Runtime Modifications]] below for more details.

	=== AM_ROM ===		=== AM_ROM ===

Aaron: /* Address Map Flags */

2008-03-20T19:59:54Z

Address Map Flags

← Older revision		Revision as of 21:59, 20 March 2008
Line 136:		Line 136:
	AM_NOP is short for AM_READWRITE(SMH_NOP, SMH_NOP). AM_READNOP is short for AM_READ(SMH_NOP), and AM_WRITENOP is short for AM_WRITE(SMH_NOP). The static "nop" memory handler operates exactly like the unmapped memory handler, except that it does not log to the error.log file. This is handy if you have a particular address range you wish to explicitly ignore and don't want each access to that range to clog up the log file.		AM_NOP is short for AM_READWRITE(SMH_NOP, SMH_NOP). AM_READNOP is short for AM_READ(SMH_NOP), and AM_WRITENOP is short for AM_WRITE(SMH_NOP). The static "nop" memory handler operates exactly like the unmapped memory handler, except that it does not log to the error.log file. This is handy if you have a particular address range you wish to explicitly ignore and don't want each access to that range to clog up the log file.

	== Address Map ~~Flags~~ ==		== Address Map Global Controls ==

	=== ~~AMEF_ABITS~~ ===		There are two global control values that can be specified in an address map. Generally, these controls are placed at the top of the address map. Regardless of where they are located, however, their effects apply to the entire address space.
	=== ~~AMEF_UNMAP~~ ===
			=== ADDRESS_MAP_GLOBAL_MASK ===

			Specifying ADDRESS_MAP_GLOBAL_MASK(''maskval'') applies the given ''maskval'' as a bitmask to all addresses in the range. CPUs generally have many address lines and for some systems, it isn't worth the effort to decode each and every address line in order to determine whether or not a given memory access corresponds to a particular device. In this case, the address line from the CPU is completely ignored, and ADDRESS_MAP_GLOBAL_MASK allows you to specify a bitmask of only those bits which are actually decoded.

			A famous example of this is the Z80 I/O address space. In reality, this is a 16-bit address bus, but most systems that used it only decoded the lower 8 bits. So in many cases in MAME you will see ADDRESS_MAP_GLOBAL_MASK(0xff) in the I/O address map.

			=== ADDRESS_MAP_UNMAP_LOW, ADDRESS_MAP_UNMAP_HIGH ===

			These two macros specify explicitly how unmapped (and "nop") reads from the address space are handled. By default, an unmapped read returns 0 (this is actually usually not the case, though the default is left this way for historical reasons). However, on many systems, an unmapped read should return all 1 bits (for example, $FF on an 8-bit data bus). To enable this, simply include an ADDRESS_MAP_UNMAP_HIGH in your address map and the static unmapped memory handler will return all 1's instead of all 0's (which is what you get by default, or if you specify ADDRESS_MAP_UNMAP_LOW).

	== Runtime Modifications ==		== Runtime Modifications ==

	== Debugging Helpers ==		== Debugging Helpers ==