Initial revision
[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.  Get the bochs source code:
18     a)  cvs -d:pserver:anonymous:@cvs.sourceforge.net:/cvsroot/bochs login
19     b)  cvs -d:pserver:anonymous:@cvs.sourceforge.net:/cvsroot/bochs co bochs
20
21 2.  Configure bochs with
22       ./configure --enable-all-optimisations --enable-pci \
23                  --enable-ne2000 --enable-pnic
24     Other potentially useful configure options:
25       --prefix=/usr
26           to force use of standard file locations
27       --enable-debugger
28           to enable the internal debugger
29
30 3.  Build bochs:
31       make
32
33 4.  Configure Etherboot with CONFIG_PCI_DIRECT: add the line
34       CFLAGS += -DCONFIG_PCI_DIRECT
35     to the end of src/arch/i386/Config.
36
37 5.  Build bin/pnic.zrom:
38       make bin/pnic.zrom
39
40 6.  Load the TUN/TAP kernel module:
41       modprobe tun
42     You should see the device /dev/net/tun is created automatically if
43     you're using devfs, otherwise you may have to create it by hand with:
44       mknod /dev/net/tun c 10 200
45
46 7.  Grant yourself write access to /dev/net/tun:
47       su -c 'chown <your user id> /dev/net/tun'
48     The alternative to this is to run Bochs as root.  Don't do that.
49
50 8.  Add the following fragment to /etc/dhcpd.conf:
51       subnet 10.254.254.0 netmask 255.255.255.252 {
52         range dynamic-bootp 10.254.254.1 10.254.254.1;
53       }
54     You will also need to add in any of your usual declarations for
55     Etherboot, e.g. 'filename "vmlinuz.ltsp";'.  Note that this setup
56     assumes that your DHCP server, TFTP server etc. all live on the
57     machine you are using for running Bochs.  If not, then you're on
58     your own.
59
60 9.  Change back to this directory and run bochs from your Bochs source tree:
61       cd /path/to/Etherboot/contrib/bochs
62       /path/to/bochs/source/tree/bochs
63
64 10. Select option 5 (Begin simulation).  You will be prompted for your
65     root password.  This is required in order to configure the tun1
66     network interface and to restart the DHCP server.
67
68 11. You should see Bochs start up and attempt to boot from the network,
69     with a screen that looks like:
70
71 VGA BIOS - Version 2.40
72 Copyright (C) 1990-2000 Elpin Systems, Inc.
73 All rights reserved.
74
75 Licensed for use with bochs, courtesy of MandrakeSoft.
76
77 For information on this or other VGA development products, contact
78 Elpin Systems at: (800) 723-9038 or www.elpin.com
79
80 Bochs BIOS, 1 cpu, $Revision$ $Date$
81
82
83 Etherboot 5.3.6 (GPL) http://etherboot.org Tagged ELF for [PNIC]
84 Relocating _text from: [00091020,0009fb50) to [01ef14d0,01f00000)
85 Boot from (N)etwork or (Q)uit?
86
87 Probing pci nic...
88 [pnic] - Detected Bochs Pseudo NIC MAC FE:FD:00:00:00:01 (API v1.0) at 0xdc00
89 Searching for server (DHCP)...
90 ..Me: 10.254.254.1, Server: 10.254.254.2
91 Loading 10.254.254.2:/tftpboot/kernel
92
93
94
95
96 Serial console
97 ==============
98
99 You can use the program "serial-console" to obtain a virtual serial
100 console for Etherboot running within Bochs.  Simply run
101 "./serial-console" on a spare tty (e.g. a separate xterm window)
102 before starting Bochs, and ensure that you have compiled Etherboot
103 with appropriate settings such as
104   CFLAGS+=      -DCONSOLE_DUAL -DCOMCONSOLE=0x3F8 -DCONSPEED=9600
105
106 There is a manual page for "serial-console"; use
107 "man ./serial-console.1" to view it.
108
109
110
111 TODO
112 ====
113
114 Packet forwarding/masquerading - document what must be set up.
115
116 Mention possibility of using RFB as the display device - in
117 conjunction with the serial console, gives you a test facility that
118 can be accessed remotely.
119
120 Mention use of BOCHSBP instruction (xchgw %bx,%bx) to avoid need to
121 calculate breakpoints.