2 \documentclass[11pt]{article}
11 \usepackage{changebar}
15 \setlength{\textheight}{8.50in}
16 \setlength{\textwidth}{6.5in}
17 \setlength{\topmargin}{-0.3in}
18 %\setlength{\leftmargin}{2.9in}
19 %\setlength{\rightmargin}{-2.9in}
20 \setlength{\oddsidemargin}{0in}
21 \setlength{\parindent}{0.5in}
27 \includegraphics[height=1.5in]{v3vee.pdf}
28 \includegraphics[height=1.5in]{logo6.png} \\
30 Palacios Internal Developer Manual
37 This manual is written for Internal Palacios developers. It contains
38 information on how to obtain the palacios code base, how to go about
39 the development process, and how to commit those changes to the
40 mainline source tree. This assumes that the reader has read {\em An
41 Introduction to the Palacios Virtual Machine Monitor -- Release 1.0}
42 and also has a slight working knowledge of {\em git}.
48 Both Palacios and Kitten follow a hybrid development process that
49 uses both the centralized repository and distributed development
50 models. A central repository exists that holds the master version of
51 the code base. This central repository is cloned by multiple people
52 and in multiple places to support various development efforts. A
53 feature of git is that every developer actually has a fully copy of
54 the entire repository, and so can function independently until such
55 time as they need to resync with the master version.
57 There are typically multiple levels of access to the central
58 repository, that are granted based on the type of developer being
59 granted access. The three basic developer types and their access
63 \item Core Developers: These are the lead developers and are in
64 charge of managing the master repository. They have full read/write
65 access permissions to the central repository.
67 \item Internal Developers: Formal members of the development
68 team. These people are capable of pulling directly from the central
69 repository, but lack the ability to write directly to it.
71 \item External Developers: People who are not actual members of the
72 development team. These people can only access the public repository
73 which is only updated to contain the release versions.
76 Because internal and external developers cannot write directly to the
77 master repository, they need to first submit their changes to a core
78 developer before they can be added to the mainline. We will discuss
79 that process in Section~\ref{sec:submission}.
82 \section{Checking out Palacios}
83 The central palacios repository is located on {\em
84 newskysaw.cs.northwestern.edu} in {\em /home/palacios/palacios}. All
85 internal developers have read access to the directory. Each developer
86 must create their own local version of the repository, this is done
90 git clone /home/palacios/palacios
93 This creates a local copy of the repository at {\em ./palacios/}.
96 All development work is done in the {\em devel} branch of the
97 repository. The developer can access this branch via:
100 git checkout --track -b devel origin/devel
106 /opt/vmm-tools/bin/checkout_branch devel
110 Note that palacios is very actively developed so the contents of the
111 {\em devel} branch are frequently changing. In order to keep up to
112 date with the latest version, it is necessary to periodically pull the
113 latest changes from the master repository by running \verb.git pull..
117 \section{Checking out Kitten}
119 Kitten is available from Sandia National Labs, and is the main host OS
120 we are targetting with Palacios. Loosely speaking core Palacios
121 developers are internal Kitten developers, and internal Palacios
122 developers are external Kitten developers. Because we have limited
123 access to the Kitten repository, we are maintaining a local mirror
124 copy in {\em /home/palacios/kitten}.
126 Kitten uses Mercurial for their source management, so you will have to
127 make sure the local mercurial version is configured correctly.
128 Specifically you should add the following python path to your shell environment.
131 export PYTHONPATH=/usr/local/lib64/python2.4/site-packages/
134 You can then clone Kitten from the local mirror:
136 hg clone /home/palacios/kitten
140 {\em Important:} Like Palacios, Kitten is very actively developed so
141 source tree is frequently changing. In order to keep up to date with
142 the latest version, it is necessary to periodically pull the latest
143 changes from the mirror repository by running \verb.hg pull. followed
146 \section{Compiling Palacios}
150 This will build Palacios as a library, libv3vee.a in the palacios/palacios/build/.
153 \section{Compiling Kitten}
154 \subsection{Configuration}
155 Kitten building can be configured by either text or graph configure interface, which is similar to the Linux kernel configure, By one of the following commands:
161 Make sure turn on the network device driver, networking, and input kernel command 'console=serial net=rtl8139'
162 \subsection{Compilation}
164 Build Palacios as a module for Kitten
165 In the first time, make sure to build Kitten before you building the Palacios as the module to kitten.
166 Palacios now is built as a module of the Kitten. You can find the palacios.c and palacios.h in the kitten/palacios/. Enter the directory, build the palacios module.
170 cp built-in.o ../modules/palacios-mod.o
172 Go back to kitten root directory, and build the Kitten again.
176 \section{Running Palacios/Kitten}
177 Run the whole stuff built above in Qemu using following command:
180 /usr/local/qemu/bin/qemu-system-x86_64 -smp 1 -m 1024
181 -serial file:./serial.out
182 -cdrom ./arch/x86_64/boot/image.iso
183 -net tap, ifname=tap0
189 \section{Development Guidelines}
191 32/64 bit compatibility
196 \section{Code Submission}
197 \label{sec:submission}
198 \subsection{Palacios}
200 \includegraphics[height=3.5in]{dev_chart.pdf}
210 \section{Configuring the development host's Qemu network}
211 Set up Tap interfaces:
213 /root/util/tap\_create tapX
215 Bridging tapX with eth1 will only work (work = send packet and also make packet visible on localhost) if the IP address is set correctly (correctly = match network it is connected to e.g., network of eth1) so bring up the network inside of the VM / QEMU as 10-net, and it should route through the eth1 rule and be visible both on the host and in the physical network
218 \subsection{Configuring Kitten}
220 How to set ip address in kitten:
222 Kitten ip address setting is in file drivers/net/ne2k/rtl8139.c, in the code below which is located in function rtl8139\_init.
224 struct ip\_addr ipaddr = { htonl(0 | 10 << 24 | 0 << 16 | 2 << 8 | 16 << 0) };
225 struct ip\_addr netmask = { htonl(0xffffff00) };
226 struct ip\_addr gw = { htonl(0 | 10 << 24 | 0 << 16 | 2 << 8 | 2 << 0) };
228 This sets the ip address as 10.0.2.16, netmask 255.255.255.0 and gateway address 10.0.2.2, change it as you need.
232 \subsection{Running with networking}
234 \paragraph*{Tap Interface}
235 In which, the command line:
237 -net tap, ifname=tap2
239 specifies Qemu to use the host's tap0 as its network interface, then Qemu can access the host's physical network.
241 \paragraph*{Redirection}
243 Also you can use the following command instead to redirect host's 9555 port to Qemu's 80 port.
245 -net user -net nic,model=rtl8139 -redir tcp:9555::80
247 In this case, you can access Qemu's 80 port in the host like:
249 telnet localhost 9555
251 Qemu has many options to build up a virtual or real networking. See http://www.h7.dion.ne.jp/~qemu-win/HowToNetwork-en.html for more information.
258 For more questions, talk to Jack or Lei.