\includegraphics[height=1.5in]{v3vee.pdf}
\includegraphics[height=1.5in]{logo6.png} \\
\vspace{0.5in}
-Palacios Internal Developer Manual
+Palacios Internal and External Developer Manual
}
\maketitle
-This manual is written for internal Palacios developers. It contains
-information on how to obtain the Palacios code base, how to go about
-the development process, and how to commit those changes to the
-mainline source tree. This assumes that the reader has read {\em An
-Introduction to the Palacios Virtual Machine Monitor -- Release 1.0}
-and also has a slight working knowledge of {\em git}. You will also
-want to read the document {\em Building a bootable guest image for
-Palacios and Kitten} in order to understand how to build an extremely
-lightweight guest environment, suitable for testing.
+This manual is written for internal and external Palacios
+developers. It contains information on how to obtain the Palacios code
+base, how to go about the development process, and how to commit those
+changes to the mainline source tree. This assumes that the reader has
+read the technical report {\em An Introduction to the Palacios Virtual
+Machine Monitor -- Release 1.0}\footnote{It's important to note that
+there have been substantial changes in the build process from 1.0 to
+1.2 and beyond. Hence, the technical report is primarily useful as an
+explanation of the theory of operation of Palacios. This document is
+the one to consult for the build process.} and also has a slight
+working knowledge of {\em git}. You will also want to read the
+document {\em Building a bootable guest image for Palacios and Kitten}
+in order to understand how to build an extremely lightweight guest
+environment, suitable for testing. If you want to configure network
+booting for testing on real hardware, you'll want to read the document
+{\em Booting Palacios/Kitten Over the Network Using PXE}.
Please note that Palacios and Kitten are under rapid development,
hence this manual may very well be out of date!
models. A central repository exists that holds the master version of
the code base. This central repository is cloned by multiple people
and in multiple places to support various development efforts. A
-feature of \texttt{git} is that every developer actually has a fully copy of
+feature of \texttt{git} is that every developer actually has a full copy of
the entire repository, and so can function independently until such
time as they need to re-sync with the master version.
use the following command instead. The {\em newskysaw} home
directories are NFS-mounted on /home-remote.
-
\begin{verbatim}
git clone /home-remote/palacios/palacios
\end{verbatim}
you have a newskysaw account:
\begin{verbatim}
-git clone ssh://you@newskysaw.cs.northwestern.edu//home/palaicos/palacios
+git clone ssh://you@newskysaw.cs.northwestern.edu//home/palacios/palacios
+\end{verbatim}
+
+External developers can clone the public repository via the web. The
+public repository tracks the release and main development branch
+(e.g., devel) of the internal repository with a 30 minute delay. The
+access information is available on the web site (http://v3vee.org).
+The web site also includes a publically accessible gitweb interface to
+allow browsing of the public repository. The clone command looks like
+
+\begin{verbatim}
+git clone http://v3vee.org/palacios/palacios.web/palacios.git
\end{verbatim}
-This creates a local copy of the repository at {\em ./palacios/}.
+No matter how you clone, the clone command creates a local copy of the
+repository at {\em ./palacios/}.
Note that both {\em newskysaw} and {\em newbehemoth} have all the
tools installed that are needed to build and test Palacios and Kitten.
we are targeting with Palacios. Loosely speaking, core Palacios
developers are internal Kitten developers, and internal Palacios
developers are external Kitten developers. The public repository for
-Kitten is at {\em http://code.google.com/kitten}. To simplify things,
-we are maintaining a local mirror copy in {\em /home/palacios/kitten}
-that tracks the public repository.
+Kitten is at {\em http://code.google.com/p/kitten}. To simplify
+things, we are maintaining a local mirror copy on newskysaw in {\em
+/home/palacios/kitten} that tracks the public repository.
-Kitten uses Mercurial for their source management, so you will have to
-make sure the local mercurial version is configured correctly.
-Specifically you should add the following Python path to your shell environment.
+Kitten uses Mercurial for source management, so you will have to make
+sure the local Mercurial version is configured correctly.
+Specifically you will probably need to add something like the
+following Python path to your shell environment.
\begin{verbatim}
export PYTHONPATH=/usr/local/lib64/python2.4/site-packages/
\begin{verbatim}
hg clone ssh://you@newskysaw.cs.northwestern.edu//home/palacios/kitten
\end{verbatim}
-
+External developers, run
+\begin{verbatim}
+hg clone https://kitten.googlecode.com/hg/ kitten
+\end{verbatim}
Both the Kitten and Palacios clone commands should be run from the
same directory. This means that both repositories should be located at
{\em Important:} Like Palacios, Kitten is under active development,
and its source tree is frequently changing. In order to keep up to
date with the latest version, it is necessary to periodically pull the
-latest changes from the mirror repository by running \verb.hg.
-pull. followed by \verb.hg update..
+latest changes from the mirror repository by running \verb.hg pull.
+followed by \verb.hg update..
\section{Compiling Palacios}
overlay network under development by Lei Xia and Yuan Tang.
\item Enable built-in versions of stdlib functions --- this adds
needed stdlib functions that the host OS may not supply. For use with
-Kitten turn on and enable strncasecmp() and atoi().
+Kitten turn on and enable strcasecmp() and atoi().
\item Enable built-in versions of stdio functions (off)
\end{itemize}
\item Symbiotic Functions (these are experimental options for Jack
\item Enable Symbiotic Functionality --- This adds symbiotic features
to Palacios, specifically support for discovery and configuration by
symbiotic guests, the SymSpy passive information interface for
-asynchronous symtiotic guest $\leftrightarrow$ symbiotic VMM
+asynchronous symbiotic guest $\leftrightarrow$ symbiotic VMM
information flow, and the SymCall functional interface for synchronous
symbiotic VMM $\rightarrow$ symbiotic guest upcalls. (on)
\item Symbiotic Swap --- Enables the SwapBypass symbiotic service for
\item Passthrough PCI --- allows us to make a hardware PCI device visible and
directly accessible by the guest (on)
\end{itemize}
+\item Generic --- this is a run-time configurable device that can intercept I/O port read/writes and memory region reads/writes. Intercepted reads and writes can either be ignored or forwarded to actual hardware, and the data flow can optionally be printed. This is a useful tool with at least three purposes. First, it makes it possible to ``stub out'' hardware that isn't currently implemented and for which we don't want to allow passthrough access. Second, it makes it possible to provide low-level passthrough access to physical hardware. Third, it can be used to spy on guest/device interactions, which is very helpful when trying to understand the interface of a device.
\item NVRAM - motherboard configuration memory --- needed by BIOS bootstrap (on)
\item Keyboard - Generic PS/2 keyboard, including mostly broken mouse
implementation (on)
\end{verbatim}
This command will compile Kitten (with Palacios embedded in it) and
the init task (which will contain the guest OS blob), and then
-assemble an ISO image file which can used to boot a machine. The ISO
+assemble an ISO image file which can be used to boot a machine. The ISO
image is located at {\em ./arch/x86\_64/boot/image.iso}.
This image file can be used for booting a QEMU emulation environment,
template. It is carefully commented. In summary, a configuration
consists of
\begin{itemize}
-\item Physical memory size of the gust
+\item Physical memory size of the guest
\item Basic VMM settings, such as what form of virtual paging is to be
used, the scheduler rate, whether services like telemetry are on, etc.
\item A memory map that maps regions of the host physical address
\item A list of the devices that the guest will have, including
configuration data for each device.
\end{itemize}
-There are a few subtlies involved with devices. One is that some
-devices form attachement points for other devices. The PCI device is
+There are a few subtleties involved with devices. One is that some
+devices form attachment points for other devices. The PCI device is
an example of this. Another is that each device needs to define how
it is attached (e.g. direct (implicit), via a PCI bus, etc.)
Finally, there may be multiple instances of devices. For example, a
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
+\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.
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
-pat1ch. (This is how you can manage revisions that are made by other developers).
+\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 definitely 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
+you want your changes to be applied it's 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.
