[contrib] Bring bochs/qemu READMEs up to date with latest upstream code
[people/oremanj/gpxe.git] / 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.  Build the utilities in this directory:
18       make
19
20 2.  Get the bochs source code:
21       cvs -d:pserver:anonymous@bochs.cvs.sourceforge.net:/cvsroot/bochs \
22            login
23       cvs -d:pserver:anonymous@bochs.cvs.sourceforge.net:/cvsroot/bochs \
24            co bochs
25
26 3.  Configure bochs with
27       pushd bochs
28       ./configure --enable-all-optimisations --enable-show-ips \
29                   --enable-cpu-level=6 \
30                   --enable-pci --enable-pnic --enable-ne2000 \
31                   --enable-debugger --enable-disasm
32       popd
33
34 4.  Build bochs:
35       make -C bochs
36
37 5.  As root, set up a TAP virtual network device:
38       /sbin/modprobe tun
39       chmod o+rw /dev/net/tun
40       ./tunctl -u <username> -t tap0
41       /sbin/ifconfig tap0 up 10.254.254.2 netmask 255.255.255.0
42
43 6.  As root, add the following fragment to /etc/dhcpd.conf:
44       subnet 10.254.254.0 netmask 255.255.255.252 {
45         range dynamic-bootp 10.254.254.1 10.254.254.1;
46       }
47     You will also need to add in any of your usual declarations for
48     Etherboot, e.g. 'filename "vmlinuz.ltsp";'.  Note that this setup
49     assumes that your DHCP server, TFTP server etc. all live on the
50     machine you are using for running Bochs.  If not, then you're on
51     your own.
52
53 7.  As root, restart dhcpd
54       /etc/init.d/dhcpd restart
55
56 8.  Build Etherboot images
57       pushd ../../src
58       make bin/pnic.dsk
59       popd
60
61 9.  Start Bochs
62       ./bochs/bochs -q
63     You should get to the debugger prompt "<bochs:1>".  Type "c" to
64     start running Bochs.
65
66 You should see Bochs start up, load up Etherboot and attempt to boot
67 from the network.
68
69
70
71 Serial console
72 ==============
73
74 You can use the program "serial-console" to obtain a virtual serial
75 console for Etherboot running within Bochs.  Simply run
76 "./serial-console" on a spare tty (e.g. a separate xterm window)
77 before starting Bochs, and ensure that you have enabled CONSOLE_SERIAL
78 in config.h.
79
80 There is a manual page for "serial-console"; use
81 "man ./serial-console.1" to view it.
82
83
84
85 TODO
86 ====
87
88 Packet forwarding/masquerading - document what must be set up.
89
90 Mention possibility of using RFB as the display device - in
91 conjunction with the serial console, gives you a test facility that
92 can be accessed remotely.
93
94 Mention use of BOCHSBP instruction (xchgw %bx,%bx) to avoid need to
95 calculate breakpoints.