--- trunk/doc/technical.html	2007/10/08 16:19:37	22
+++ trunk/doc/technical.html	2007/10/08 16:22:32	42
@@ -10,9 +10,9 @@
 
 <!--
 
-$Id: technical.html,v 1.72 2006/02/18 15:18:15 debug Exp $
+$Id: technical.html,v 1.76 2007/06/15 18:07:08 debug Exp $
 
-Copyright (C) 2004-2006  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,39 +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 recompile anything into native code, it only uses tables of
-	pointers to functions written in (sometimes machine-generated) C
-	code. Speed is lower than what can be achieved using real binary
-	translation into native code, but higher than when traditional
-	interpretation is used. With some tricks, it will hopefully still
-	give reasonable speed. The ARM and PowerPC
-	emulation modes use this kind of translation.
+  <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.
+
+
 
 
 
@@ -127,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
@@ -330,11 +309,13 @@
 <a name="devices"></a>
 <h3>Emulation of hardware devices</h3>
 
-Each file called <tt>dev_*.c</tt> in the <tt>src/device/</tt> directory is
+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
-<tt>src/machines/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.
+<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
@@ -349,21 +330,20 @@
 <pre>
 	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);
-	        }
+		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,
@@ -388,15 +368,14 @@
 	should be defined.
 <pre>
 	struct foo_data {
-		int	irq_nr;
+		struct interrupt	irq;
 		/*  ...  */
 	}
 </pre><br>
-	(There is an exception to this rule; ugly hacks which allow
-	code in <tt>src/machine.c</tt> to use some structures makes it
-	necessary to place the <tt>struct foo_data</tt> in
-	<tt>src/include/devices.h</tt> instead of in <tt>dev_foo.c</tt>
-	itself. This is useful for example for interrupt controllers.)
+	(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 
@@ -404,14 +383,14 @@
 <pre>
 	#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>
 
@@ -440,9 +419,16 @@
 		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)