Palacios Public Git Repository

To checkout Palacios execute

  git clone http://v3vee.org/palacios/palacios.web/palacios.git
This will give you the master branch. You probably want the devel branch or one of the release branches. To switch to the devel branch, simply execute
  cd palacios
  git checkout --track -b devel origin/devel
The other branches are similar.


removed ne2k from release
[palacios.git] / manual / manual.tex
index d7a30d7..c13651f 100755 (executable)
 %\setlength{\rightmargin}{-2.9in}
 \setlength{\oddsidemargin}{0in}
 \setlength{\parindent}{0.5in}
+\setlength\parindent{0in}
+\setlength\parskip{0.1in} 
 
+\newcommand{\note}[1]{{$\rightarrow$ \bf Note: \emph{#1}}}
 
 \begin{document}
 
@@ -265,6 +268,8 @@ make
 make isoimage
 \end{verbatim}
 
+\note{This should probably explain how to change the iso (helloworld,etc)}
+
 This generates an ISO boot image containing Kitten, Palacios, and the
 guest that will be run as a VM. The ISO image is located at {\em
 ./arch/x86\_64/boot/image.iso}.
@@ -289,78 +294,425 @@ all output to the serial port is written directly to a file called
 
 \section{Development Guidelines}
 
-32/64 bit compatibility
-name space
-coding guidelines
+There are standard requirements we have for code entering the mainline. 
+
+First and foremost, Palacios is designed to be OS indenpendent and
+support 32 and 64 bit architectures. This means that developers should
+not include any external OS specific dependencies in any Palacios
+component. Also all changes need to be tested on both 32 and 64 bit
+architectures to make sure that they compile as well as run corrrectly.
+
+\paragraph*{Coding Style}
+
+"The use of equal negative space, as a balance to positive space, in a
+composition is considered by many as good design. This basic and often
+overlooked principle of design gives the eye a "place to rest,"
+increasing the appeal of a composition through subtle means."
+\newline\newline
+Translation: Use the spacebar, newlines, and parentheses. 
+
+Curly-brackets are not optional, even for single line conditionals. 
+
+Tabs should be 4 characters in width.
+
+{\em Special:} If you are using XEmacs add the following to your \verb.init\.el. file:
+\begin{verbatim}
+(setq c-basic-offset 4)
+(c-set-offset 'case-label 4)
+\end{verbatim}
+
+{\em Bad}
+\begin{verbatim}
+if(a&&b==5||c!=0) return;
+\end{verbatim}
+
+
+{\em Good}
+
+\begin{verbatim}
+if (((a) && (b == 5)) || 
+    (c != 0)) {
+               return;
+}
+\end{verbatim}
+
+
+
+\paragraph*{Fail Stop}
+Because booting a basic linux kernel results in over 1 million VM exits
+catching silent errors is next to impossible. For this reason
+ANY time your code has an error it should return -1, and expect the
+execution to halt. 
+
+This includes unimplemented features and unhandled cases. These cases
+should ALWAYS return -1. 
+
+
+\paragraph*{Function names}
+Externally visible function names should be used rarely and have
+unique names. Currently we have several techniques for achieving this:
+
+\begin{enumerate}
+\item \verb.#ifdefs. in the header file
+\newline
+When the V3 Hypervisor is compiled it defines the symbol
+\verb.__V3VEE__. Any function that is not needed outside the Hypervisor
+context should be inside an \verb.#ifdef __V3VEE__. block, this will make it
+invisible to the host environment.
+
+\item Static Functions
+\newline
+Any utility functions that are only needed in the .c file where they
+are defined should be declared as static and not included in the
+header file. You should make an effort to use static functions
+whenever possible. 
+
+\item \verb.v3_. prefix
+\newline
+Major interface functions should be named with the prefix \verb.v3_. This
+xallows easy understanding of how to interact with the subsystems. And
+in the case that they need to be externally visible to the host os,
+make them unlikely to collide with other functions. 
+\end{enumerate}
+
+\paragraph*{Debugging Output}
+Debugging output is sent through the host os via functions in the
+\verb.os_hooks. structure. These functions have various wrappers of the form
+\verb.Print*., with printf style semantics. 
+
+Two functions of note are \verb.PrintDebug. and \verb.PrintError..
+
+\begin{itemize}
+
+\item PrintDebug:
+\newline
+Should be used for debugging output that will often be turned off
+selectively by the VMM configuration.
+
+\item PrintError
+\newline
+Should be used when an error occurs, this will never be optimized out
+and will always print. 
+\end{itemize}
 
 
 \section{Code Submission}
 \label{sec:submission}
+
+To commit changes to the central repository they need to be exported
+as a patch set that can be applied directly to a mainline. Both Git
+and Mercurial contain functionality to allow developers to maintain
+changes as a patch set. There are also a few options that make dealing
+with patches easier.
+
 \subsection{Palacios}
 
+Git includes support for directly exporting local repository commits
+as a patch set. The basic operation is for a developer to commit a
+change to a local repository, and then export that change as a patch
+that can be applied to another git repository. While this is
+functionally possible, there are a number of issues. The main problem
+is that it is difficult to fully encapsulate a new feature in a single
+commit, and dealing with multiple patches that often overwrite each
+other is not a viable option either. Furthermore, once a patch is
+applied to the mainline, it will generate a conflicting commit that
+will become present when the developer next pulls from the central
+repository. This can result in both repositories getting out of
+sync. It is possible to deal with this by manually rebasing the local
+repository, but it is difficult and error-prone. 
+
+This approach also does not map well when patches are being revised. A
+normal patch will go through multiple revisions as it is reviewed and
+modified by others. This often leads to synchronization issues as well
+as errors with patch revisions. Ultimately it is the responsibility of
+the developer to generate a patch that will apply cleanly to the
+mainline.
+
+For this reason most internal developers should seriously consider
+{\em stacked git}. Stacked git is designed to make patch development
+easier and less of a headache. The basic mode of operation is for a
+developer to intialize a patch for a new feature and then continuously
+apply changes to the patch. Stacked Git allows a developer to layer a
+series of patches on top of a local git repository, without causing
+the repository to unsync due to local commits. Basically, the
+developer never commits changes to the repository itself but instead
+commits the changes to a specific patch. The local patches are managed
+using stack operations (push/pop) which allows a developer to apply
+and unapply patches as needed. Stacked git also manages new changes to
+the underlying git repository as a result of a pull operation and
+prevents collisions as changes are propagated upstream. For instance
+if you have a local patch that is applied to the mainline as a commit,
+when the commit is pulled down the patch becomes empty because it is
+effectively identical to the mainline. It also makes incorporating
+external revisions to a patch easier. Stacked git is installed on {\em
+newskysaw} in \verb./opt/vmm-tools/bin/. 
+
+Brief command overview:
+\begin{itemize}
+\item \verb.stg init. -- Initialize stacked git in a given branch
+\item \verb.stg new. -- create a new patch set, an editor will open
+asking for a commit message that will be used when the patch is
+ultimately committed.
+\item \verb.stg pop. -- pops a patch off of the source tree.
+\item \verb.stg push. -- pushes a patch back on to a source tree.
+\item \verb.stg export. -- exports a patch to a directory as a file
+that can then be emailed.
+\item \verb.stg refresh. -- commits local changes to the patch set at
+the top of the applied stack.
+\item \verb.stg fold. -- Apply a patch file to the current
+patch. (This is how you can manage revisions that are made by other developers).
+\end{itemize}
+
+You should definately look at the online documentation to better
+understand how stacked git works. It is not required of course, but if
+you want your changes to be applied its up to you to generate a patch
+that is acceptable to a core developer. Ultimately using Stacked git
+should be easier than going it alone.
+
+
+All patches should be emailed to Jack for inclusion in the
+mainline. An overview of the organization is given in
+Figure~\ref{fig:process}. You should assume that the first revision of
+a patch will not be accepted, and that you will have to make
+changes. Furthermore, the final form of the patch most likely will not
+be exactly what you submitted. 
+
+\begin{figure}[t]
+\begin{center}
 \includegraphics[height=3.5in]{dev_chart.pdf}
+\end{center}
+\caption{Development organization}
+\label{fig:process}
+\end{figure}
 
-stacked git
 
 \subsection{Kitten}
 
-mercurial queues
+Writing code for Kitten follows essentially the same process as
+Palacios. The difference is that the patches need to be emailed to the
+Kitten developers. To send in a patch, you can just email it to the
+V3Vee development list.
 
-\section{Networking}
 
-\section{Configuring the development host's Qemu network}
-Set up Tap interfaces:
+Also, instead of Stacked git you should use Mercurial patch
+queues. This feature is enabled in your .hgrc file.
+\begin{verbatim}
+[extensions]
+hgext.mq=
+\end{verbatim}
 
-/root/util/tap\_create tapX
+Mercurial queues use the same stack operations as stacked git, however
+it does not automatically handle the synchronization with pull
+operations. Before you update from the central version of Kitten you
+need to pop all of the patches, and then push them once the update is
+complete.
 
-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
+Basically:
+\begin{verbatim}
+hg qpop -a
+hg pull
+hg update
+hg qpush -a
+\end{verbatim}
 
 
-\subsection{Configuring Kitten}
+%Also, remember that Kitten is not a Northwestern project and is being
+%developed by professional developers at Sandia National Labs. So keep
+%in mind that you are representing Northwestern and the rest of the
+%Palacios development group. We are collaborating with them because
+%Kitten and the resources they have are very important for our research
+%efforts. They are collaborating with us because they believe that
+%Palacios might be able to help them. Therefore it is important that we
+%continue to ensure that they see value in our collaboration. In plain
+%terms, we need to make sure they think we're smart and know what we're
+%doing. So please keep that in mind when dealing with the Kitten group.
 
-To enable networking in Qemu, networking needs to be enabled in the configuration.
 
-Make sure turn on the network device driver, networking, and input
-kernel command 'console=serial net=rtl8139'
+\section{Networking}
 
-How to set ip address in kitten:
+Both the Kitten and GeekOS substrates on which Palacios can run
+currently include drivers for two simple network cards, the NE2000,
+and the RTL8139.  The Kitten substrate is acquiring an ever increasing
+set of drivers for specialized network systems.   A lightweight
+networking stack is included so that TCP/IP networking is possible
+from within the host OS kernel and in Palacios.  
+
+When debugging Palacios on QEMU, it is very convenient to add an
+RTL8139 card to your QEMU configuration, and then drive it from within
+Palacios.  QEMU can be configured to provide local connectivity to the
+QEMU emulated machine, including bridging the emulated machine with a
+physical network.  Local connectivity can be done with redirection, or
+with a TAP interface.  For global connectivity, a TAP interface must
+be used; it is bridged to a physical interface.
+
+\section{Configuring the development host's QEMU network}
+
+To get local connectivity with redirection, no networking changes on
+the host are needed.  However, people usually want to use TAP-based
+networking, which does require changes.  For one thing, TAP interfaces
+can be inspected with tools like wireshark, which makes for much
+easier debugging of network code.
+
+In order to get QEMU networking to function, it is necessary to create
+TAP interfaces, and, optionally, to bridge them to real networks.  A
+developmet machine typically will have several TAP interfaces, and
+more can be created.  Generally, each developer should have a TAP
+interface of his or her own.  In the following, we will use our
+development machine, newskysaw, as an example.
+
+To set up a TAP interface on newskysaw, the following comand is used:
+\begin{verbatim}
+/root/util/tap_create tapX
+\end{verbatim}
 
-Kitten ip address setting is in file drivers/net/ne2k/rtl8139.c, in the code below which is located in function rtl8139\_init.
+When QEMU runs with a tap interface, it will use /etc/qemu-ifup to
+bring up the interface.  On newskysaw, /etc/qemu-ifup looks like this:
 
-  struct ip\_addr ipaddr = { htonl(0 | 10 << 24 | 0 << 16 | 2 << 8 | 16 << 0) }; 
-  struct ip\_addr netmask = { htonl(0xffffff00) }; 
-  struct ip\_addr gw = { htonl(0 | 10 << 24 | 0 << 16 | 2 << 8 | 2 << 0) };
+\begin{verbatim}
+#!/bin/bash
+echo "Executing /etc/qemu-ifup - no external bridging"
+echo "Bringing up $1 for bridged mode..."
+NET=`echo $1 | cut -dp -f2` 
+sudo /sbin/ifconfig $1 172.2${NET}.0.1 up
+sleep 2
+\end{verbatim}
 
-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.
+The interface tap$N$ is brought up with the IP address 172.2$N$.0.1.
+ifconfig will also create a routing rule that sends 172.2$N$.0.1/16
+traffic to tap$N$.  The upshot is that if the code running in QEMU
+uses an IP address in this network (for example: 172.2$N$.0.2), you
+will be able to talk to it from newskysaw.  For example, from
+newskysaw, if you ping 172.21.0.2, the packet (and ARP) will go out via
+tap1.  The source address will appear to be 172.21.0.1.  The QEMU
+machine will see these packets on its interface, and the software
+controling its interface can respond to 172.21.0.1.  
+
+This form of networking is local to the machine.  You can also bridge
+a TAP interface with a physical interface.  The result of this is that
+a packet sent on it will be sent on the physical interface.  To do
+this requires more effort (and is not set up by default on newskysaw).
+As an example, consider that on newskysaw, the physical interface eth1
+is connected to a private network switch to which the lab test
+computers (v-test-amd, v-test-amd2, etc.) are connected.  To bridge,
+for example, tap10, to this interface, you would do the following
+(with root's help):
+\begin{enumerate}
+\item You need to bring up eth1 (ifconfig eth1 up {\em address}
+netmask {\em mask}).  It is important that the address and mask you
+choose are appropriate for the network eth1 is connected to.
+\item You would bring up tap10 without an address:  /sbin/ifconfig
+tap10 up
+\item You would bridge tap10 and eth1:  /usr/sbin/brctl addif br0
+tap10; /usr/sbin/brctl addif eth1.  This assumes that br0 was
+previously created. 
+\end{enumerate}
+
+Bridging tap$N$ with eth1 will only work (where ``work'' means sending
+a packet on the network and making the packet visible on localhost) if
+the IP address in the code running in QEMU is set correctly.  This
+means that it needs to be set to correspond to the network of eth1).  
+For the newskysaw configuration, this is a 10-net address.
 
 
+\subsection{Configuring Kitten}
 
-\subsection{Running with networking}
+Kitten needs to be explicitly configured to use networking. Currently
+only a subset of the networking configurations are supported. To
+enable an ethernet network you should enable the following options:
 
-\paragraph*{Tap Interface}
-In which, the command line: 
+\begin{itemize}
+\item Enable TCP Support
+\item Enable UDP Support
+\item Enable socket API
+\item Enable ARP support
+\end{itemize}
 
--net tap, ifname=tap2
+The other options are not supported, and enabling them will probably
+break the kernel compilation.
 
-specifies Qemu to use the host's tap0 as its network interface, then Qemu can access the host's physical network.
+To allow Kitten to communicate with the Qemu network card you also
+need to enable the appropriate device driver: \newline
+\verb.NE2K Device Driver (rtl8139).
 
-\paragraph*{Redirection}
+The driver then needs to be listed as a Kernel Command Line argument
+in the {\em ISOIMAGE configuration}. To do this add
+\verb.net=rtl819. to the end of the argument string.
 
-Also you can use the following command instead to redirect host's 9555 port to Qemu's 80 port.
+Kitten currently does not support the dynamic assignment or IP
+addresses at runtime. Because of this it is necessary to hardcode the
+IP address into the device driver. For the rtl8139 network driver look
+in the file {\em drivers/net/ne2k/rtl8139.c} for the function
+\verb.rtl8139_init..
 
--net user -net nic,model=rtl8139  -redir tcp:9555::80
+There shoule be a block of code that looks like the following:
+\begin{verbatim}
+  struct ip_addr ipaddr = { htonl(0 | 10 << 24 | 0 << 16 | 2 << 8 | 16 << 0) }; 
+  struct ip_addr netmask = { htonl(0xffffff00) }; 
+  struct ip_addr gw = { htonl(0 | 10 << 24 | 0 << 16 | 2 << 8 | 2 << 0) };
+\end{verbatim}
 
-In this case, you can access Qemu's 80 port in the host like:
+This sets the ip address as 10.0.2.16, netmask 255.255.255.0 and
+gateway address 10.0.2.2. Change these assignments to match your configuration.
+
+
+\paragraph*{Kitten as the Guest OS}
+
+When running Kitten as a VM, the above applies except that you will
+want to enable the {\em VMNET} device driver instead of the {\em rtl8139}.
 
-telnet localhost 9555
 
-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.
+\subsection{Running with networking}
 
+\paragraph*{TAP Interface}
+Running with a TAP interface provides either local or global
+connectivity (depending on how the TAP interface is configured and/or
+bridged).  From the perspective of the QEMU command line, both look
+the same, however.  You simply add something like this to the command
+line:
+\begin{verbatim}
+-net tap,ifname=tap2 -net nic,model=rtl8139
+\end{verbatim}
+The first \verb.-net. option indicates that you want to use a tap
+interface, specifically \verb.tap2..   The second \verb.-net. option
+specifies that this interface will appear to code in the QEMU machine
+to be a network interface card of the specific model RTL8139.  Note
+that this is a model for which we have a driver.  If tap2 were
+bridged, we'd get global connectivity.  If not, we would just get
+local connectivity.  
 
 
+\paragraph*{Redirection}
+It is also possible to achieve limited local connectivity even if you
+have no TAP support on your development machine.  In redirection, QEMU
+essentially acts as a proxy, translating TCP or other connections and
+low-level packet operations on the network interface in the QEMU
+machine.  For example, the following options will redirect the host's
+9555 port to the QEMU machine's 80 port:
+\begin{verbatim}
+-net user -net nic,model=rtl8139  -redir tcp:9555:10.10.10.33:80
+\end{verbatim}
+The first \verb.-net. option indicates that we are using user-level
+networking (proxying).  The secod \verb.-net. option indicates that
+this user-level network will appear in the QEMU machine as an RTL8139
+network card.   The \verb.-redir. option indicates that connections on
+localhost:9555 will be translated into equivalent packet exchanges on
+the RTL8139 card in the QEMU machine.  However, we have to tell QEMU
+which IP address and port to use on the QEMU machine's side.  This is
+what the 10.10.10.33 address, and port 80 are.  In the example, if you
+access port 9555 on localhost, say with:
+\begin{verbatim}
+telnet localhost 9555
+\end{verbatim}
+The packets that appear in the QEMU machine will be bound for
+10.10.10.33, port 80.  Within the QEMU machine, your RTL8139 interface
+had better then be up on that address. 
 
+Qemu has many options to build up a virtual or real networking. See
+http://www.h7.dion.ne.jp/$\sim$qemu-win/HowToNetwork-en.html for more
+information.
 
 
-For more questions, talk to Jack or Lei.
+For more questions, talk to Jack, Lei, or Peter.
 
 \end{document}