1 files changed, 94 insertions, 0 deletions
diff --git a/gpxe/contrib/bochs/README b/gpxe/contrib/bochs/README
new file mode 100644
index 00000000..57c6f052
--- /dev/null
+++ b/gpxe/contrib/bochs/README
@@ -0,0 +1,94 @@
+Running Etherboot within Bochs
+==============================
+
+Michael Brown <mbrown@fensystems.co.uk>
+Based on an idea suggested by H. Peter Anvin <hpa@zytor.com>.
+
+$Id$
+
+Bochs is a program that simulates a complete Intel x86 computer,
+including hardware.  It can be used to test Etherboot.  There is a
+special pseudo NIC ("pnic") implemented in Bochs, with a corresponding
+driver in Etherboot.  (There is also an NE2000 ISA driver in Bochs,
+but it doesn't seem to quite work.)
+
+To get bochs running is fairly simple:
+
+1.  Build the utilities in this directory:
+      make
+
+2.  Get the bochs source code:
+      cvs -d:pserver:anonymous@bochs.cvs.sourceforge.net:/cvsroot/bochs \
+           login
+      cvs -d:pserver:anonymous@bochs.cvs.sourceforge.net:/cvsroot/bochs \
+           co bochs
+
+3.  Configure bochs with
+      pushd bochs
+      ./configure --enable-all-optimisations --enable-pci --enable-pnic \
+                  --enable-debugger --enable-magic-breakpoints \
+		  --enable-disasm --enable-show-ips --enable-ne2000
+      popd
+
+4.  Build bochs:
+      make -C bochs
+
+5.  As root, set up a TAP virtual network device:
+      /sbin/modprobe tun
+      chmod o+rw /dev/net/tun
+      ./tunctl -u <username> -t tap0
+      /sbin/ifconfig tap0 up 10.254.254.2 netmask 255.255.255.0
+
+6.  As root, add the following fragment to /etc/dhcpd.conf:
+      subnet 10.254.254.0 netmask 255.255.255.252 {
+        range dynamic-bootp 10.254.254.1 10.254.254.1;
+      }
+    You will also need to add in any of your usual declarations for
+    Etherboot, e.g. 'filename "vmlinuz.ltsp";'.  Note that this setup
+    assumes that your DHCP server, TFTP server etc. all live on the
+    machine you are using for running Bochs.  If not, then you're on
+    your own.
+
+7.  As root, restart dhcpd
+      /etc/init.d/dhcpd restart
+
+8.  Build Etherboot images
+      pushd ../../src
+      make bin/pnic.dsk
+      popd
+
+9.  Start Bochs
+      ./bochs/bochs -q
+    You should get to the debugger prompt "<bochs:1>".  Type "c" to
+    start running Bochs.
+
+You should see Bochs start up, load up Etherboot and attempt to boot
+from the network.
+
+
+
+Serial console
+==============
+
+You can use the program "serial-console" to obtain a virtual serial
+console for Etherboot running within Bochs.  Simply run
+"./serial-console" on a spare tty (e.g. a separate xterm window)
+before starting Bochs, and ensure that you have enabled CONSOLE_SERIAL
+in config.h.
+
+There is a manual page for "serial-console"; use
+"man ./serial-console.1" to view it.
+
+
+
+TODO
+====
+
+Packet forwarding/masquerading - document what must be set up.
+
+Mention possibility of using RFB as the display device - in
+conjunction with the serial console, gives you a test facility that
+can be accessed remotely.
+
+Mention use of BOCHSBP instruction (xchgw %bx,%bx) to avoid need to
+calculate breakpoints.