contrib/bochs/README

   1 Running Etherboot within Bochs
   2 ==============================
   3
   4 Michael Brown <mbrown@fensystems.co.uk>
   5 Based on an idea suggested by H. Peter Anvin <hpa@zytor.com>.
   6
   7 $Id$
   8
   9 Bochs is a program that simulates a complete Intel x86 computer,
  10 including hardware.  It can be used to test Etherboot.  There is a
  11 special pseudo NIC ("pnic") implemented in Bochs, with a corresponding
  12 driver in Etherboot.  (There is also an NE2000 ISA driver in Bochs,
  13 but it doesn't seem to quite work.)
  14
  15 To get bochs running is fairly simple:
  16
  17 1.  Get the bochs source code:
  18       cvs -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/bochs login
  19       cvs -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/bochs co bochs
  20
  21 2.  Configure bochs with
  22       pushd bochs
  23       ./configure --enable-all-optimisations --enable-pci --enable-pnic
  24                   --enable-debugger --enable-magic-breakpoints --enable-disasm
  25       popd
  26
  27 3.  Build bochs:
  28       make -C bochs
  29
  30 4.  Set up a TAP virtual network device:
  31       modprobe tun
  32       tunctl -u <username> -t tap0
  33       ifconfig tap0 up 10.254.254.2 netmask 255.255.255.0
  34
  35 5.  Add the following fragment to /etc/dhcpd.conf:
  36       subnet 10.254.254.0 netmask 255.255.255.252 {
  37         range dynamic-bootp 10.254.254.1 10.254.254.1;
  38       }
  39     You will also need to add in any of your usual declarations for
  40     Etherboot, e.g. 'filename "vmlinuz.ltsp";'.  Note that this setup
  41     assumes that your DHCP server, TFTP server etc. all live on the
  42     machine you are using for running Bochs.  If not, then you're on
  43     your own.
  44
  45 6.  Restart dhcpd
  46       /etc/init.d/dhcpd restart
  47
  48 7.  Build Etherboot images
  49       pushd ../../src
  50       make bin/pnic.dsk
  51       popd
  52
  53 8.  Start Bochs
  54       ./bochs/bochs -q
  55     You should get to the debugger prompt "<bochs:1>".  Type "c" to
  56     start running Bochs.
  57
  58 You should see Bochs start up, load up Etherboot and attempt to boot
  59 from the network.
  60
  61
  62
  63 Serial console
  64 ==============
  65
  66 You can use the program "serial-console" to obtain a virtual serial
  67 console for Etherboot running within Bochs.  Simply run
  68 "./serial-console" on a spare tty (e.g. a separate xterm window)
  69 before starting Bochs, and ensure that you have compiled Etherboot
  70 with appropriate settings such as
  71   CFLAGS+= -DCONSOLE_DUAL -DCOMCONSOLE=0x3F8 -DCONSPEED=9600
  72
  73 There is a manual page for "serial-console"; use
  74 "man ./serial-console.1" to view it.
  75
  76
  77
  78 TODO
  79 ====
  80
  81 Packet forwarding/masquerading - document what must be set up.
  82
  83 Mention possibility of using RFB as the display device - in
  84 conjunction with the serial console, gives you a test facility that
  85 can be accessed remotely.
  86
  87 Mention use of BOCHSBP instruction (xchgw %bx,%bx) to avoid need to
  88 calculate breakpoints.