Save State Fundamentals - Revision history

Madskunk: Removed the unneeded `tags`


2008-06-28T11:39:11Z
Removed the unneeded <code> tags

				
				
				
				
				
				← Older revision
				Revision as of 13:39, 28 June 2008
				
Line 29:
Line 29:



So, how do you register this data? Well, you use one of the many different registration functions available in state.h: So, how do you register this data? Well, you use one of the many different registration functions available in state.h:
  <code>void state_save_register_UINT8   void state_save_register_UINT8
  void state_save_register_INT8   void state_save_register_INT8
  void state_save_register_UINT16   void state_save_register_UINT16
Line 38:
Line 38:
  void state_save_register_INT64   void state_save_register_INT64
  void state_save_register_double   void state_save_register_double
  void state_save_register_float</code>   void state_save_register_float
Each of these functions takes a module name, an instance number, a data name, a pointer to the variable to be saved, and a count. The first three parameters I've already explained above. The pointer is just that: the address of where the data currently lives in memory. And the count is there so that you can register a whole array of data in a single call. Each of these functions takes a module name, an instance number, a data name, a pointer to the variable to be saved, and a count. The first three parameters I've already explained above. The pointer is just that: the address of where the data currently lives in memory. And the count is there so that you can register a whole array of data in a single call.



Let's look at an example. In this example, we have several global variables that need to be saved, one of which is an array, and one of which is dynamically allocated. For this example, we register in the MACHINE_INIT callback: Let's look at an example. In this example, we have several global variables that need to be saved, one of which is an array, and one of which is dynamically allocated. For this example, we register in the MACHINE_INIT callback:



  <code>static UINT8 irq_state;   static UINT8 irq_state;
  static UINT8 irq_vector;   static UINT8 irq_vector;
  static UINT16 irq_mask[16];   static UINT16 irq_mask[16];
Line 57:
Line 57:
               
      state_save_register_UINT32("example1", 0, "allocated_data", allocated_data, 1000);       state_save_register_UINT32("example1", 0, "allocated_data", allocated_data, 1000);
  }</code>   }
A few observations here. First, you'll notice that we've set the data name equal to the name of the variable we're saving. Since these are just global variables, they don't need special instance numbers (those are mainly useful if you have a peripheral device that could have multiple instances). "example1" was arbitrarily picked as the module name, though any name would have sufficed. A few observations here. First, you'll notice that we've set the data name equal to the name of the variable we're saving. Since these are just global variables, they don't need special instance numbers (those are mainly useful if you have a peripheral device that could have multiple instances). "example1" was arbitrarily picked as the module name, though any name would have sufficed.



Line 64:
Line 64:
You'll notice that writing that is kind of tedious, and there are some obvious patterns. For example, the module name for global variables is pretty much irrelevant, the instance number is always 0 here, and the data names are consistently related to the variable names. Furthermore, the compiler knows the type of each variable, so having to specify it explicitly is just extra work. Plus, the count for single variables is always 1, and the count for arrays can be determined at compile-time. To this end, there are some macros that simplify matters: You'll notice that writing that is kind of tedious, and there are some obvious patterns. For example, the module name for global variables is pretty much irrelevant, the instance number is always 0 here, and the data names are consistently related to the variable names. Furthermore, the compiler knows the type of each variable, so having to specify it explicitly is just extra work. Plus, the count for single variables is always 1, and the count for arrays can be determined at compile-time. To this end, there are some macros that simplify matters:



  <code>static UINT8 irq_state;   static UINT8 irq_state;
  static UINT8 irq_vector;   static UINT8 irq_vector;
  static UINT16 irq_mask[16];   static UINT16 irq_mask[16];
Line 78:
Line 78:
               
      state_save_register_global_pointer(allocated_data, 1000);       state_save_register_global_pointer(allocated_data, 1000);
  }</code>   }
Ah, much simpler! All "global" items are registered with the "globals" module name and instance number 0. The '''state_save_register_global''' macro registers a single variable, while '''state_save_register_global_array''' registers an array, and '''state_save_register_global_pointer''' registers a dynamically allocated array. Ah, much simpler! All "global" items are registered with the "globals" module name and instance number 0. The '''state_save_register_global''' macro registers a single variable, while '''state_save_register_global_array''' registers an array, and '''state_save_register_global_pointer''' registers a dynamically allocated array.



Madskunk at 11:22, 28 June 2008
2008-06-28T11:22:53Z


				
				
				
				
				
				← Older revision
				Revision as of 13:22, 28 June 2008
				
Line 29:
Line 29:



So, how do you register this data? Well, you use one of the many different registration functions available in state.h: So, how do you register this data? Well, you use one of the many different registration functions available in state.h:
  <source lang=c>void state_save_register_UINT8   <code>void state_save_register_UINT8
  void state_save_register_INT8   void state_save_register_INT8
  void state_save_register_UINT16   void state_save_register_UINT16
Line 38:
Line 38:
  void state_save_register_INT64   void state_save_register_INT64
  void state_save_register_double   void state_save_register_double
  void state_save_register_float</source>   void state_save_register_float</code>
Each of these functions takes a module name, an instance number, a data name, a pointer to the variable to be saved, and a count. The first three parameters I've already explained above. The pointer is just that: the address of where the data currently lives in memory. And the count is there so that you can register a whole array of data in a single call. Each of these functions takes a module name, an instance number, a data name, a pointer to the variable to be saved, and a count. The first three parameters I've already explained above. The pointer is just that: the address of where the data currently lives in memory. And the count is there so that you can register a whole array of data in a single call.



Line 58:
Line 58:
      state_save_register_UINT32("example1", 0, "allocated_data", allocated_data, 1000);       state_save_register_UINT32("example1", 0, "allocated_data", allocated_data, 1000);
  }</code>   }</code>
A few observations here. First, you'll notice that I tend to set the data name equal to the name of the variable I'm saving. Since these are just global variables, they don't need special instance numbers (those are mainly useful if you have a peripheral device that could have multiple instances). I arbitrarily picked "example1" as my module name, though any name would have sufficed. A few observations here. First, you'll notice that we've set the data name equal to the name of the variable we're saving. Since these are just global variables, they don't need special instance numbers (those are mainly useful if you have a peripheral device that could have multiple instances). "example1" was arbitrarily picked as the module name, though any name would have sufficed.



The first two items are single variables, so we pass the address of the variable and a count of 1. The third item is an array, so we pass the address of the array and a count equal to the number of items in the array. The last item is similar, except that the data is allocated dynamically before passing the pointer and length into the registration function. The first two items are single variables, so we pass the address of the variable and a count of 1. The third item is an array, so we pass the address of the array and a count equal to the number of items in the array. The last item is similar, except that the data is allocated dynamically before passing the pointer and length into the registration function.
Line 79:
Line 79:
      state_save_register_global_pointer(allocated_data, 1000);       state_save_register_global_pointer(allocated_data, 1000);
  }</code>   }</code>
Ah, much simpler! All "global" items are registered with the "globals" module name and instance number 0. The <strong>state_save_register_global</strong> macro registers a single variable, while <strong>state_save_register_global_array</strong> registers an array, and <strong>state_save_register_global_pointer</strong> registers a dynamically allocated array. Ah, much simpler! All "global" items are registered with the "globals" module name and instance number 0. The '''state_save_register_global''' macro registers a single variable, while '''state_save_register_global_array''' registers an array, and '''state_save_register_global_pointer''' registers a dynamically allocated array.



This is the part where it is crucial to have a good, basic understanding of C. You need to understand how pointers, arrays, and variables work in C, and how they differ. You also need to understand the answers to questions like: Why don't you need to save the pointers themselves? If you can't answer that last one, you'll probably be a bit out of your depth trying to add save state support to drivers in MAME. This is the part where it is crucial to have a good, basic understanding of C. You need to understand how pointers, arrays, and variables work in C, and how they differ. You also need to understand the answers to questions like: Why don't you need to save the pointers themselves? If you can't answer that last one, you'll probably be a bit out of your depth trying to add save state support to drivers in MAME.



The final thing I will mention about registering data for save states is that there is only a small window of timeâ€”starting from early in initialization until just after the driver's MACHINE_INIT callback is calledâ€”during which registrations are allowed. This means that at init time, you need to register everything you might want to save up front. The reason for this will become clearer in a future article which explains how restore works. The final thing to mention about registering data for save states is that there is only a small window of time in which registrations are allowed, starting from early in initialization until just after the driver's MACHINE_INIT callback is called. This means that at init time, you need to register everything you might want to save up front. The reason for this will become clearer in a future article which explains how restore works.



Madskunk: New page: Before adding save state support to a driver in MAME, it's important to understand how the overall save state system works. But first, a word of warning: it's been said in the past that ad...
2008-06-28T11:12:29Z
New page: Before adding save state support to a driver in MAME, it's important to understand how the overall save state system works. But first, a word of warning: it's been said in the past that ad...
New page
Before adding save state support to a driver in MAME, it's important to understand how the overall save state system works. But first, a word of warning: it's been said in the past that adding save state support to a driver is easy. Let's clarify that by saying: adding save state support a driver is relatively easy ''if you know C well''. How do you know whether or not you know C well? Read on...



The basic concept of saving the state of any emulator involves first identifying all the information that represents the current state of the system, and then writing that data out to disk in some fashion for later retrieval. There are many ways this can be done. Let's look at the first step: what comprises the set of data that needs to be saved in order to fully represent the state of an emulated system?



Some obvious candidates are:

# the registers and internal state on each CPU

# information about what each sound chip is doing

# the contents of all RAM (including video, palette, sound RAM) in the system

# all timing information

# the state of any peripheral devices (EEPROMs, IDE controllers, etc.)

# the currently selected memory bank for banked RAM/ROM

# the state of any driver-specific devices



Fortunately, due to MAME's modular design, a lot of this is taken care of centrally. For example, many common CPU cores already have built-in support for saving their registers and internal state, as do many common sound chip emulators. Similarly, the MAME core handles saving the contents of all RAM and timers. And many peripheral devices can save their state as well, as long as they have some sort of <code>init()</code> function that is called to set them up. This leaves memory banks and driver-specific devices as the two main things that need to be managed manually for each driver.



== Saving the Data ==



In MAME, the save state system is designed as a primarily passive system. That is, MAME's save state code assumes that all the data you want to save lives in memory somewhere. It is the client's responsibility to inform the save state system where in memory that data lies, and in what format it exists. This is generally done at initialization time. The save state system manages the rest of the process from there.



Each piece of data that is registered is required to have a unique signature. This signature is actually a combination of three pieces of data: the module name, the instance number, and the data name.



The module name is a string that is intended to represent the name of the module that is saving the data; generally this is the name of the CPU (e.g., "Z80") or driver (e.g., "pacman"), but really can be any unique identifier at all.



The instance number specifies an index within the module; for example, the first Z80 in the system will use a module name "Z80" with an instance number of 0, while the second one will also use a module name "Z80" but with an instance number of 1.



The data name is a string that represents the name of the specific piece of data. For example, the AF register on a Z80 might be registered with a data name of "AF".



Keep in mind that the combination of these three pieces of data must be 100% unique within the system. Any attempt to re-register an identical set of data will abort out of MAME with an error.



So, how do you register this data? Well, you use one of the many different registration functions available in state.h:

 <source lang=c>void state_save_register_UINT8

 void state_save_register_INT8

 void state_save_register_UINT16

 void state_save_register_INT16

 void state_save_register_UINT32

 void state_save_register_INT32

 void state_save_register_UINT64

 void state_save_register_INT64

 void state_save_register_double

 void state_save_register_float</source>

Each of these functions takes a module name, an instance number, a data name, a pointer to the variable to be saved, and a count. The first three parameters I've already explained above. The pointer is just that: the address of where the data currently lives in memory. And the count is there so that you can register a whole array of data in a single call.



Let's look at an example. In this example, we have several global variables that need to be saved, one of which is an array, and one of which is dynamically allocated. For this example, we register in the MACHINE_INIT callback:



 <code>static UINT8 irq_state;

 static UINT8 irq_vector;

 static UINT16 irq_mask[16];

 static UINT32 *allocated_data;

 

 MACHINE_INIT( example1 )

 {

     state_save_register_UINT8("example1", 0, "irq_state", &irq_state, 1);

     state_save_register_UINT8("example1", 0, "irq_vector", &irq_vector, 1);

     state_save_register_UINT16("example1", 0, "irq_mask", irq_mask, 16);

     

     allocated_data = auto_malloc(1000 * sizeof(*allocated_data));

     

     state_save_register_UINT32("example1", 0, "allocated_data", allocated_data, 1000);

 }</code>

A few observations here. First, you'll notice that I tend to set the data name equal to the name of the variable I'm saving. Since these are just global variables, they don't need special instance numbers (those are mainly useful if you have a peripheral device that could have multiple instances). I arbitrarily picked "example1" as my module name, though any name would have sufficed.



The first two items are single variables, so we pass the address of the variable and a count of 1. The third item is an array, so we pass the address of the array and a count equal to the number of items in the array. The last item is similar, except that the data is allocated dynamically before passing the pointer and length into the registration function.



You'll notice that writing that is kind of tedious, and there are some obvious patterns. For example, the module name for global variables is pretty much irrelevant, the instance number is always 0 here, and the data names are consistently related to the variable names. Furthermore, the compiler knows the type of each variable, so having to specify it explicitly is just extra work. Plus, the count for single variables is always 1, and the count for arrays can be determined at compile-time. To this end, there are some macros that simplify matters:



 <code>static UINT8 irq_state;

 static UINT8 irq_vector;

 static UINT16 irq_mask[16];

 static UINT32 *allocated_data;

 

 MACHINE_INIT( example1 )

 {    

     state_save_register_global(irq_state);

     state_save_register_global(irq_vector);

     state_save_register_global_array(irq_mask);

     

     allocated_data = auto_malloc(1000 * sizeof(*allocated_data));

     

     state_save_register_global_pointer(allocated_data, 1000);

 }</code>

Ah, much simpler! All "global" items are registered with the "globals" module name and instance number 0. The <strong>state_save_register_global</strong> macro registers a single variable, while <strong>state_save_register_global_array</strong> registers an array, and <strong>state_save_register_global_pointer</strong> registers a dynamically allocated array.



This is the part where it is crucial to have a good, basic understanding of C. You need to understand how pointers, arrays, and variables work in C, and how they differ. You also need to understand the answers to questions like: Why don't you need to save the pointers themselves? If you can't answer that last one, you'll probably be a bit out of your depth trying to add save state support to drivers in MAME.



The final thing I will mention about registering data for save states is that there is only a small window of timeâ€”starting from early in initialization until just after the driver's MACHINE_INIT callback is calledâ€”during which registrations are allowed. This means that at init time, you need to register everything you might want to save up front. The reason for this will become clearer in a future article which explains how restore works.

← Older revision		Revision as of 13:39, 28 June 2008
Line 29:		Line 29:

	So, how do you register this data? Well, you use one of the many different registration functions available in state.h:		So, how do you register this data? Well, you use one of the many different registration functions available in state.h:
	~~<code>~~void state_save_register_UINT8		void state_save_register_UINT8
	void state_save_register_INT8		void state_save_register_INT8
	void state_save_register_UINT16		void state_save_register_UINT16
Line 38:		Line 38:
	void state_save_register_INT64		void state_save_register_INT64
	void state_save_register_double		void state_save_register_double
	void state_save_register_float~~</code>~~		void state_save_register_float
	Each of these functions takes a module name, an instance number, a data name, a pointer to the variable to be saved, and a count. The first three parameters I've already explained above. The pointer is just that: the address of where the data currently lives in memory. And the count is there so that you can register a whole array of data in a single call.		Each of these functions takes a module name, an instance number, a data name, a pointer to the variable to be saved, and a count. The first three parameters I've already explained above. The pointer is just that: the address of where the data currently lives in memory. And the count is there so that you can register a whole array of data in a single call.

	Let's look at an example. In this example, we have several global variables that need to be saved, one of which is an array, and one of which is dynamically allocated. For this example, we register in the MACHINE_INIT callback:		Let's look at an example. In this example, we have several global variables that need to be saved, one of which is an array, and one of which is dynamically allocated. For this example, we register in the MACHINE_INIT callback:

	~~<code>~~static UINT8 irq_state;		static UINT8 irq_state;
	static UINT8 irq_vector;		static UINT8 irq_vector;
	static UINT16 irq_mask[16];		static UINT16 irq_mask[16];
Line 57:		Line 57:

	state_save_register_UINT32("example1", 0, "allocated_data", allocated_data, 1000);		state_save_register_UINT32("example1", 0, "allocated_data", allocated_data, 1000);
	}~~</code>~~		}
	A few observations here. First, you'll notice that we've set the data name equal to the name of the variable we're saving. Since these are just global variables, they don't need special instance numbers (those are mainly useful if you have a peripheral device that could have multiple instances). "example1" was arbitrarily picked as the module name, though any name would have sufficed.		A few observations here. First, you'll notice that we've set the data name equal to the name of the variable we're saving. Since these are just global variables, they don't need special instance numbers (those are mainly useful if you have a peripheral device that could have multiple instances). "example1" was arbitrarily picked as the module name, though any name would have sufficed.

Line 64:		Line 64:
	You'll notice that writing that is kind of tedious, and there are some obvious patterns. For example, the module name for global variables is pretty much irrelevant, the instance number is always 0 here, and the data names are consistently related to the variable names. Furthermore, the compiler knows the type of each variable, so having to specify it explicitly is just extra work. Plus, the count for single variables is always 1, and the count for arrays can be determined at compile-time. To this end, there are some macros that simplify matters:		You'll notice that writing that is kind of tedious, and there are some obvious patterns. For example, the module name for global variables is pretty much irrelevant, the instance number is always 0 here, and the data names are consistently related to the variable names. Furthermore, the compiler knows the type of each variable, so having to specify it explicitly is just extra work. Plus, the count for single variables is always 1, and the count for arrays can be determined at compile-time. To this end, there are some macros that simplify matters:

	~~<code>~~static UINT8 irq_state;		static UINT8 irq_state;
	static UINT8 irq_vector;		static UINT8 irq_vector;
	static UINT16 irq_mask[16];		static UINT16 irq_mask[16];
Line 78:		Line 78:

	state_save_register_global_pointer(allocated_data, 1000);		state_save_register_global_pointer(allocated_data, 1000);
	}~~</code>~~		}
	Ah, much simpler! All "global" items are registered with the "globals" module name and instance number 0. The '''state_save_register_global''' macro registers a single variable, while '''state_save_register_global_array''' registers an array, and '''state_save_register_global_pointer''' registers a dynamically allocated array.		Ah, much simpler! All "global" items are registered with the "globals" module name and instance number 0. The '''state_save_register_global''' macro registers a single variable, while '''state_save_register_global_array''' registers an array, and '''state_save_register_global_pointer''' registers a dynamically allocated array.

← Older revision		Revision as of 13:22, 28 June 2008
Line 29:		Line 29:

	So, how do you register this data? Well, you use one of the many different registration functions available in state.h:		So, how do you register this data? Well, you use one of the many different registration functions available in state.h:
	<~~source lang=c~~>void state_save_register_UINT8		<code>void state_save_register_UINT8
	void state_save_register_INT8		void state_save_register_INT8
	void state_save_register_UINT16		void state_save_register_UINT16
Line 38:		Line 38:
	void state_save_register_INT64		void state_save_register_INT64
	void state_save_register_double		void state_save_register_double
	void state_save_register_float</~~source~~>		void state_save_register_float</code>
	Each of these functions takes a module name, an instance number, a data name, a pointer to the variable to be saved, and a count. The first three parameters I've already explained above. The pointer is just that: the address of where the data currently lives in memory. And the count is there so that you can register a whole array of data in a single call.		Each of these functions takes a module name, an instance number, a data name, a pointer to the variable to be saved, and a count. The first three parameters I've already explained above. The pointer is just that: the address of where the data currently lives in memory. And the count is there so that you can register a whole array of data in a single call.

Line 58:		Line 58:
	state_save_register_UINT32("example1", 0, "allocated_data", allocated_data, 1000);		state_save_register_UINT32("example1", 0, "allocated_data", allocated_data, 1000);
	}</code>		}</code>
	A few observations here. First, you'll notice that ~~I tend to~~ set the data name equal to the name of the variable I'm saving. Since these are just global variables, they don't need special instance numbers (those are mainly useful if you have a peripheral device that could have multiple instances). ~~I arbitrarily picked~~ "example1" as my module name, though any name would have sufficed.		A few observations here. First, you'll notice that we've set the data name equal to the name of the variable we're saving. Since these are just global variables, they don't need special instance numbers (those are mainly useful if you have a peripheral device that could have multiple instances). "example1" was arbitrarily picked as the module name, though any name would have sufficed.

	The first two items are single variables, so we pass the address of the variable and a count of 1. The third item is an array, so we pass the address of the array and a count equal to the number of items in the array. The last item is similar, except that the data is allocated dynamically before passing the pointer and length into the registration function.		The first two items are single variables, so we pass the address of the variable and a count of 1. The third item is an array, so we pass the address of the array and a count equal to the number of items in the array. The last item is similar, except that the data is allocated dynamically before passing the pointer and length into the registration function.
Line 79:		Line 79:
	state_save_register_global_pointer(allocated_data, 1000);		state_save_register_global_pointer(allocated_data, 1000);
	}</code>		}</code>
	Ah, much simpler! All "global" items are registered with the "globals" module name and instance number 0. The ~~<strong>~~state_save_register_global~~</strong>~~ macro registers a single variable, while ~~<strong>~~state_save_register_global_array~~</strong>~~ registers an array, and ~~<strong>~~state_save_register_global_pointer~~</strong>~~ registers a dynamically allocated array.		Ah, much simpler! All "global" items are registered with the "globals" module name and instance number 0. The '''state_save_register_global''' macro registers a single variable, while '''state_save_register_global_array''' registers an array, and '''state_save_register_global_pointer''' registers a dynamically allocated array.

	This is the part where it is crucial to have a good, basic understanding of C. You need to understand how pointers, arrays, and variables work in C, and how they differ. You also need to understand the answers to questions like: Why don't you need to save the pointers themselves? If you can't answer that last one, you'll probably be a bit out of your depth trying to add save state support to drivers in MAME.		This is the part where it is crucial to have a good, basic understanding of C. You need to understand how pointers, arrays, and variables work in C, and how they differ. You also need to understand the answers to questions like: Why don't you need to save the pointers themselves? If you can't answer that last one, you'll probably be a bit out of your depth trying to add save state support to drivers in MAME.

	The final thing ~~I will~~ mention about registering data for save states is that there is only a small window of ~~timeâ€”starting~~ from early in initialization until just after the driver's MACHINE_INIT callback is ~~calledâ€”during which registrations are allowed~~. This means that at init time, you need to register everything you might want to save up front. The reason for this will become clearer in a future article which explains how restore works.		The final thing to mention about registering data for save states is that there is only a small window of time in which registrations are allowed, starting from early in initialization until just after the driver's MACHINE_INIT callback is called. This means that at init time, you need to register everything you might want to save up front. The reason for this will become clearer in a future article which explains how restore works.

Save State Fundamentals - Revision history

Madskunk: Removed the unneeded tags

Madskunk at 11:22, 28 June 2008

Madskunk: New page: Before adding save state support to a driver in MAME, it's important to understand how the overall save state system works. But first, a word of warning: it's been said in the past that ad...

Madskunk: Removed the unneeded `tags`