X-Git-Url: http://v3vee.org/palacios/gitweb/gitweb.cgi?a=blobdiff_plain;f=manual%2Fmanual.tex;h=c13651fdf2f24b6a9a12c77bda7dc09fe8bd8bc6;hb=7a761f270328ceeb84c53b118cfa76ef7656b4a7;hp=27706eecf90a86a0b6534ed42aa9c40a11001e3c;hpb=18513ebcb5ec756381225382a63146460eb13d6c;p=palacios.git diff --git a/manual/manual.tex b/manual/manual.tex index 27706ee..c13651f 100755 --- a/manual/manual.tex +++ b/manual/manual.tex @@ -22,6 +22,8 @@ \setlength\parindent{0in} \setlength\parskip{0.1in} +\newcommand{\note}[1]{{$\rightarrow$ \bf Note: \emph{#1}}} + \begin{document} \title{ @@ -266,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}. @@ -307,7 +311,15 @@ 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. +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} @@ -320,13 +332,12 @@ if(a&&b==5||c!=0) return; \begin{verbatim} if (((a) && (b == 5)) || (c != 0)) { - return; + 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 @@ -520,64 +531,188 @@ hg qpush -a \section{Networking} -\section{Configuring the development host's Qemu network} -Set up Tap interfaces: - -/root/util/tap\_create tapX - -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 - +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} -\subsection{Configuring Kitten} +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: -To enable networking in Qemu, networking needs to be enabled in the configuration. +\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} -Make sure turn on the network device driver, networking, and input -kernel command 'console=serial net=rtl8139' +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} -How to set ip address in kitten: +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. -Kitten ip address setting is in file drivers/net/ne2k/rtl8139.c, in the code below which is located in function rtl8139\_init. - 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) }; +\subsection{Configuring Kitten} -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. +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: +\begin{itemize} +\item Enable TCP Support +\item Enable UDP Support +\item Enable socket API +\item Enable ARP support +\end{itemize} +The other options are not supported, and enabling them will probably +break the kernel compilation. -\subsection{Running with networking} +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*{Tap Interface} -In which, the command line: +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. --net tap, ifname=tap2 +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.. -specifies Qemu to use the host's tap0 as its network interface, then Qemu can access the host's physical network. +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} -\paragraph*{Redirection} +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. -Also you can use the following command instead to redirect host's 9555 port to Qemu's 80 port. --net user -net nic,model=rtl8139 -redir tcp:9555::80 +\paragraph*{Kitten as the Guest OS} -In this case, you can access Qemu's 80 port in the host like: +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}