From: Jack Lange <jarusl@cs.northwestern.edu>
Date: Tue, 1 Dec 2009 05:07:58 +0000 (-0600)
Subject: documentation changes
X-Git-Url: http://v3vee.org/palacios/gitweb/gitweb.cgi?p=palacios.git;a=commitdiff_plain;h=e94e38127240269fb1566eb4a5698ed7716a1656

documentation changes
---

diff --git a/utils/guest_creator/default.xml b/utils/guest_creator/default.xml
index ac1e355..9d8414a 100644
--- a/utils/guest_creator/default.xml
+++ b/utils/guest_creator/default.xml
@@ -1,107 +1,131 @@
 
-<vm class="PC">
-       <memory>1024</memory>
-       <telemetry>enable</telemetry>
-       <paging>nested</paging>
-       <schedule_hz>100</schedule_hz>
+<!-- This defines a PC VM. The class defines the initial cpu/memory state of the VM. This drives the initialization of CPU registers, as well as BIOS memory mappings.-->
+<vm class="PC"> 
 
+	<!-- Memory in MB -->
+	<memory>1024</memory> 
+
+	<!-- Basic VMM system flags -->
+	<telemetry>enable</telemetry>
+	<paging>nested</paging>
+	<schedule_hz>100</schedule_hz>
+
+
+	<!-- Memory redirections -->
+	<!-- Redirects a guest's memory region to a host physical address -->
        <memmap>
-               <region>
+		<!-- This region maps the VGA framebuffer to the host's framebuffer -->
+		<region>
                        <start>0xa0000</start>
                        <end>0xc0000</end>
                        <host_addr>0xa0000</host_addr>
                </region>
        </memmap>
 
-       <files>
-               <file id="boot-cd" filename="/home/jarusl/image.iso" />
-               <!--<file id="harddisk" filename="firefox.img" />-->
-       </files>
-
-       <devices>
-               <device id="8259A" name="PIC"/>
-               <device id="KEYBOARD" name="keyboard"/>
-               <device id="8254_PIT" name="PIC" />
-               <device id="BOCHS_DEBUG" name="bochs debug"/>
-               <device id="OS_DEBUG" name="os debug" />
-               <device id="LAPIC" name="apic"/>
-               <device id="IOAPIC" name="ioapic">
+
+	<!-- List of binary files to include with configuration -->
+	<!-- This is where you add disk images -->
+	<files>
+		<!-- The file 'id' is used as a reference for other configuration components -->
+		<file id="boot-cd" filename="/home/jarusl/image.iso" />
+		<!--<file id="harddisk" filename="firefox.img" />-->
+	</files>
+
+
+	<!-- List of devices attached to guest -->
+	<!-- The device 'ID' is the device name in the global device registry -->
+	<!-- The device 'name' is the reference to the device instance associated with a VM -->
+	<!--	The name can be used as a reference by other devices -->
+	<devices>
+		<device id="8259A" name="PIC"/>
+		<device id="KEYBOARD" name="keyboard"/>
+		<device id="8254_PIT" name="PIC" />
+		<device id="BOCHS_DEBUG" name="bochs debug"/>
+		<device id="OS_DEBUG" name="os debug" />
+		<device id="LAPIC" name="apic"/>
+		<device id="IOAPIC" name="ioapic">
                        <irq_bus>apic</irq_bus>
-               </device>
+		</device>
 
 <!--
-               <device id="CGA_VIDEO" name="cga" passthrough="enable" />
-               <device id="TELNET_CONSOLE" name="telnet console">
+		<device id="CGA_VIDEO" name="cga" passthrough="enable" />
+		<device id="TELNET_CONSOLE" name="telnet console">
                        <frontend tag="CGA_VIDEO" />
                        <port>19997</port>
-               </device>
+		</device>
 -->
-               <device id="PCI" name="pci0" />
-
-               <device id="i440FX" name="northbridge">
-                       <bus>pci0</bus>
-               </device>
-
-               <device id="PIIX3" name="southbridge">
-                       <bus>pci0</bus>
-               </device>
-
-               <device id="LNX_VIRTIO_SYM" name="sym_pci">
-                       <bus>pci0</bus>
-               </device>
-
-               <device id="LNX_VIRTIO_BLK" name="blk_virtio">
-                       <bus>pci0</bus>
-               </device>
-
-               <device id="LNX_VIRTIO_BALLOON" name="balloon">
-                       <bus>pci0</bus>
-               </device>
+		<device id="PCI" name="pci0" />
+
+		<device id="i440FX" name="northbridge">
+			<bus>pci0</bus>
+		</device>
+
+		<device id="PIIX3" name="southbridge">
+			<bus>pci0</bus>
+		</device>
+
+		<device id="LNX_VIRTIO_SYM" name="sym_pci">
+			<bus>pci0</bus>
+		</device>
+
+		<device id="LNX_VIRTIO_BLK" name="blk_virtio">
+			<bus>pci0</bus>
+		</device>
+
+		<device id="LNX_VIRTIO_BALLOON" name="balloon">
+			<bus>pci0</bus>
+		</device>
+
+		<device id="IDE" name="ide">
+			<bus>pci0</bus>
+			<controller>southbridge</controller>
+		</device>
+
+		<device id="PCI_PASSTHROUGH" name="e1000">
+			<bus>pci0</bus>
+			<vendor_id>0x8086</vendor_id>
+			<device_id>0x100e</device_id>
+		</device>
+
+		<device id="PCI_PASSTHROUGH" name="e1000-hw">
+			<bus>pci0</bus>
+			<vendor_id>0x8086</vendor_id>
+			<device_id>0x107c</device_id>
+			<irq>59</irq>
+		</device>
+
+
+		<!-- This is a Storage Backend that connects to a frontend -->
+		<!-- The frontend section is passed to the frontend when the backend connects -->
+		<!-- The file tag refers to an 'id' already listed in the file list section above -->
+		<device id="RAMDISK" name="CD0">
+			<file>boot-cd</file>
+			<frontend tag="ide">
+				<model>V3Vee CDROM</model>
+				<type>CDROM</type>
+				<bus_num>0</bus_num>
+				<drive_num>0</drive_num>
+			</frontend>
+		</device>
+
+		<device id="SYM_SWAP" name="sym swap">
+			<frontend tag="blk_virtio" />
+			<size>150</size>
+		</device>
 
-               <device id="SYM_SWAP" name="sym swap">
-                       <frontend tag="blk_virtio" />
-                       <size>150</size>
-               </device>
 
-               <device id="IDE" name="ide">
-                       <bus>pci0</bus>
-                       <controller>southbridge</controller>
-               </device>
-
-               <device id="PCI_PASSTHROUGH" name="e1000">
-                       <bus>pci0</bus>
-                       <vendor_id>0x8086</vendor_id>
-                       <device_id>0x100e</device_id>
-               </device>
-
-               <device id="PCI_PASSTHROUGH" name="e1000-hw">
-                       <bus>pci0</bus>
-                       <vendor_id>0x8086</vendor_id>
-                       <device_id>0x107c</device_id>
-                       <irq>59</irq>
-               </device>
 <!--
-               <device id="RAMDISK" name="HD0">
-                       <file>harddisk</file>
-                       <frontend tag="blk_virtio" />
-               </device>
+		<device id="RAMDISK" name="HD0">
+			<file>harddisk</file>
+			<frontend tag="blk_virtio" />
+		</device>
 -->
 
-               <device id="RAMDISK" name="CD0">
-                       <file>boot-cd</file>
-                       <frontend tag="ide">
-			  <model>V3Vee CDROM</model>
-			  <type>CDROM</type>
-                          <bus_num>0</bus_num>
-                          <drive_num>0</drive_num>
-                       </frontend>
-               </device>
-
-               <device id="NVRAM" name="nvram">
-                       <storage>ide</storage>
-               </device>
+		<device id="NVRAM" name="nvram">
+			<storage>ide</storage>
+		</device>
 
-               <device id="GENERIC" name="generic">
+		<device id="GENERIC" name="generic">
 			<ports>
                                <start>0x00</start>
                                <end>0x07</end>
diff --git a/utils/guest_creator/main.c b/utils/guest_creator/main.c
index 782e63d..2255adf 100644
--- a/utils/guest_creator/main.c
+++ b/utils/guest_creator/main.c
@@ -24,7 +24,7 @@ int parse_config_input(ezxml_t cfg_input);
 int write_output(char * filename, ezxml_t cfg_output);
 
 void usage() {
-    printf("Usage: builder <infile> [-o outfile]\n");
+    printf("Usage: build_vm <infile> [-o outfile]\n");
 }
 
 int main(int argc, char ** argv) {
diff --git a/utils/guest_creator/out_format b/utils/guest_creator/out_format
index d8f82fc..f9a5fe7 100644
--- a/utils/guest_creator/out_format
+++ b/utils/guest_creator/out_format
@@ -1,12 +1,17 @@
 v3vee\0\0\0        : 8 bytes
 <length of xml>    : 4 bytes
-<xml>
-<zeroes>           : 8 bytes of zeroes
+<xml>              : xml configuration string
+<zero's>           : 8 bytes of zeroes
 
 <num files>        : 8 bytes
 
 <index>            : 4 bytes
 <size>             : 4 bytes
 <offset>           : 8 bytes
-...
-<padding>          : zeroes to 8 byte boundary
+... other files ...
+
+<zero's>           : 8 bytes of zeroes
+
+<file>             : raw file data
+
+... other raw file data ...