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