--- trunk/doc/technical.html	2007/10/08 16:18:51	14
+++ trunk/doc/technical.html	2007/10/08 16:22:32	42
@@ -4,15 +4,15 @@
 <table border=0 width=100% bgcolor="#d0d0d0"><tr>
 <td width=100% align=center valign=center><table border=0 width=100%><tr>
 <td align="left" valign=center bgcolor="#d0efff"><font color="#6060e0" size="6">
-<b>Gavare's eXperimental Emulator:&nbsp;&nbsp;&nbsp;</b></font>
+<b>Gavare's eXperimental Emulator:</b></font><br>
 <font color="#000000" size="6"><b>Technical details</b>
 </font></td></tr></table></td></tr></table><p>
 
 <!--
 
-$Id: technical.html,v 1.63 2005/10/07 15:10:00 debug Exp $
+$Id: technical.html,v 1.76 2007/06/15 18:07:08 debug Exp $
 
-Copyright (C) 2004-2005  Anders Gavare.  All rights reserved.
+Copyright (C) 2004-2007  Anders Gavare.  All rights reserved.
 
 Redistribution and use in source and binary forms, with or without
 modification, are permitted provided that the following conditions are met:
@@ -70,12 +70,14 @@
 compared just like that.
 
 <p>Performance depends on several factors, including (but not limited to)  
-host architecture, host clock speed, which compiler and compiler flags
-were used to build the emulator, what the workload is, and so on. For
-example, if an emulated operating system tries to read a block from disk,
-from its point of view the read was instantaneous (no waiting). So 1 MIPS
-in an emulated OS might have taken more than one million instructions on a
-real machine.
+host architecture, target architecture, host clock speed, which compiler
+and compiler flags were used to build the emulator, what the workload is,
+what additional runtime flags are given to the emulator, and so on.
+
+<p>Devices are generally not timing-accurate: for example, if an emulated
+operating system tries to read a block from disk, from its point of view
+the read was instantaneous (no waiting). So 1 MIPS in an emulated OS might
+have taken more than one million instructions on a real machine.
 
 <p>Also, if the emulator says it has executed 1 million instructions, and 
 the CPU family in question was capable of scalar execution (i.e. one cycle 
@@ -85,37 +87,17 @@
 
 <p>Because of these issues, it is in my opinion best to measure
 performance as the actual (real-world) time it takes to perform a task
-with the emulator. Typical examples would be "How long does it take to 
-install NetBSD?", or "How long does it take to compile XYZ inside NetBSD 
-in the emulator?".
-
-<p>So, how fast is it? :-)&nbsp;&nbsp;&nbsp;Answer: it varies.
-
-<p>The emulation technique used varies depending on which processor type 
-is being emulated. (One of my main goals with GXemul is to experiment with 
-different kinds of emulation, so these might change in the future.)
+with the emulator, e.g.:
 
 <ul>
-  <li><b>MIPS:</b><br>
-	There are two emulation modes. The most important one is an
-	implementation of a <i>dynamic binary translator</i>.
-	(Compared to real binary translators, though, GXemul's bintrans
-	subsystem is very simple and does not perform very well.)
-	This mode can be used on Alpha and i386 host. The other emulation
-	mode is simple interpretation, where an instruction is read from
-	emulated memory, and interpreted one-at-a-time. (Slow, but it
-	works. It can be forcefully used by using the <tt>-B</tt> command
-	line option.)
-  <p>
-  <li><b>All other modes:</b><br>
-	These use a kind of dynamic translation system. (This system does
-	not use host-specific backends, so it is not "recompilation" or
-	anything like that.) Speed is slower than real binary translation,
-	but faster than traditional interpretation, and with some tricks
-	it will hopefully still give reasonable speed. ARM emulation uses
-	this kind of translation, for example.
+  <li>"How long does it take to install NetBSD onto a disk image?"
+  <li>"How long does it take to compile XYZ inside NetBSD
+	in the emulator?".
 </ul>
 
+<p>So, how fast is it? :-)&nbsp;&nbsp;&nbsp;Answer: it varies.
+
+
 
 
 
@@ -125,8 +107,7 @@
 <a name="net"></a>
 <h3>Networking</h3>
 
-<font color="#ff0000">NOTE/TODO: This section is very old and a bit
-out of date.</font>
+<font color="#ff0000">NOTE/TODO: This section is very old.</font>
 
 <p>Running an entire operating system under emulation is very interesting
 in itself, but for several reasons, running a modern OS without access to
@@ -318,9 +299,6 @@
 files in both directions, but then you should be aware of the 
 fragmentation issue mentioned above.
 
-<p>TODO: Write a section on how to connect multiple emulator instances.
-(Using the <tt>local_port</tt> and <tt>add_remote</tt> configuration file
-commands.)
 
 
 
@@ -331,14 +309,13 @@
 <a name="devices"></a>
 <h3>Emulation of hardware devices</h3>
 
-Each file in the <tt>src/device/</tt> directory is responsible for one
-hardware device. These are used from <tt>src/machine.c</tt>, when
-initializing which hardware a particular machine model will be using, or
-when adding devices to a machine using the <tt>device()</tt> command in
-configuration files.
-
-<p><font color="#ff0000">NOTE: The device registry subsystem is currently
-in a state of flux, as it is being redesigned.</font>
+Each file called <tt>dev_*.c</tt> in the 
+<a href="../src/devices/"><tt>src/devices/</tt></a> directory is
+responsible for one hardware device. These are used from
+<a href="../src/machines/"><tt>src/machines</tt></a><tt>/machine_*.c</tt>,
+when initializing which hardware a particular machine model will be using,
+or when adding devices to a machine using the <tt>device()</tt> command in
+<a href="configfiles.html">configuration files</a>.
 
 <p>(I'll be using the name "<tt>foo</tt>" as the name of the device in all
 these examples.  This is pseudo code, it might need some modification to
@@ -351,30 +328,26 @@
   <li>A <tt>devinit</tt> function in <tt>src/devices/dev_foo.c</tt>. It
 	would typically look something like this:
 <pre>
-	/*
-	 *  devinit_foo():
-	 */
-	int devinit_foo(struct devinit *devinit)
+	DEVINIT(foo)
 	{
-	        struct foo_data *d = malloc(sizeof(struct foo_data));
+	        struct foo_data *d;
 
-	        if (d == NULL) {
-	                fprintf(stderr, "out of memory\n");
-	                exit(1);
-	        }
-	        memset(d, 0, sizeof(struct foon_data));
+		CHECK_ALLOCATION(d = malloc(sizeof(struct foo_data)));
+	        memset(d, 0, sizeof(struct foo_data));
 
 		/*
 		 *  Set up stuff here, for example fill d with useful
-		 *  data. devinit contains settings like address, irq_nr,
+		 *  data. devinit contains settings like address, irq path,
 		 *  and other things.
 		 *
 		 *  ...
 		 */
+
+		INTERRUPT_CONNECT(devinit->interrupt_path, d->irq);
         
 	        memory_device_register(devinit->machine->memory, devinit->name,
 	            devinit->addr, DEV_FOO_LENGTH,
-	            dev_foo_access, (void *)d, MEM_DEFAULT, NULL);
+	            dev_foo_access, (void *)d, DM_DEFAULT, NULL);
         
 		/*  This should only be here if the device
 		    has a tick function:  */
@@ -386,46 +359,76 @@
 	}       
 </pre><br>
 
+	<p><tt>DEVINIT(foo)</tt> is defined as <tt>int devinit_foo(struct devinit *devinit)</tt>,
+	and the <tt>devinit</tt> argument contains everything that the device driver's
+	initialization function needs.
+
+  <p>
   <li>At the top of <tt>dev_foo.c</tt>, the <tt>foo_data</tt> struct
 	should be defined.
 <pre>
 	struct foo_data {
-		int	irq_nr;
+		struct interrupt	irq;
 		/*  ...  */
 	}
 </pre><br>
-
+	(There is an exception to this rule; some legacy code and other
+	ugly hacks have their device structs defined in
+	<tt>src/include/devices.h</tt> instead of <tt>dev_foo.c</tt>.
+	New code should not add stuff to <tt>devices.h</tt>.)
+  <p>
   <li>If <tt>foo</tt> has a tick function (that is, something that needs to be
 	run at regular intervals) then <tt>FOO_TICKSHIFT</tt> and a tick 
 	function need to be defined as well:
 <pre>
-	#define FOO_TICKSHIFT		10
+	#define FOO_TICKSHIFT		14
 
-	void dev_foo_tick(struct cpu *cpu, void *extra)
+	DEVICE_TICK(foo)
 	{
-		struct foo_data *d = (struct foo_data *) extra;
+		struct foo_data *d = extra;
 
 		if (.....)
-			cpu_interrupt(cpu, d->irq_nr);
+			INTERRUPT_ASSERT(d->irq);
 		else
-			cpu_interrupt_ack(cpu, d->irq_nr);
+			INTERRUPT_DEASSERT(d->irq);
 	}
 </pre><br>
 
+  <li>Does this device belong to a standard bus?
+	<ul>
+	  <li>If this device should be detectable as a PCI device, then
+		glue code should be added to
+		<tt>src/devices/bus_pci.c</tt>.
+	  <li>If this is a legacy ISA device which should be usable by
+		any machine which has an ISA bus, then the device should
+		be added to <tt>src/devices/bus_isa.c</tt>.
+	</ul>
+  <p>
   <li>And last but not least, the device should have an access function.
 	The access function is called whenever there is a load or store
-	to an address which is in the device' memory mapped region.
-<pre>
-	int dev_foo_access(struct cpu *cpu, struct memory *mem,
+	to an address which is in the device' memory mapped region. To
+	simplify things a little, a macro <tt>DEVICE_ACCESS(x)</tt>
+	is expanded into<pre>
+	int dev_x_access(struct cpu *cpu, struct memory *mem,
 	    uint64_t relative_addr, unsigned char *data, size_t len,
 	    int writeflag, void *extra)
+</pre>	The access function can look like this:
+<pre>
+	DEVICE_ACCESS(foo)
 	{
 		struct foo_data *d = extra;
 		uint64_t idata = 0, odata = 0;
 
-		idata = memory_readmax64(cpu, data, len);
+		if (writeflag == MEM_WRITE)
+			idata = memory_readmax64(cpu, data, len);
+
 		switch (relative_addr) {
-		/* .... */
+
+		/*  Handle accesses to individual addresses within
+		    the device here.  */
+
+		/*  ...  */
+
 		}
 
 		if (writeflag == MEM_READ)