ia64/xen-unstable

view docs/misc/xen_config.html @ 15783:c93e2a822d6f

[xen, xencomm] xencomm multiple page support
Current implementation doesn't allow struct xencomm_desc::address
array to be more than single page. On IA64 it causes 64GB+ domain
creation failure. This patch generalizes xencomm to allow multipage

Signed-off-by: Isaku Yamahata <yamahata@valinux.co.jp>
author kfraser@localhost.localdomain
date Tue Aug 28 15:32:27 2007 +0100 (2007-08-28)
parents f1abe953e401
children
line source
1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
2 <html>
3 <head>
4 <meta http-equiv="content-type" content="text/html; charset=ISO-8859-1">
5 <title>Xen Configuration Syntax</title>
6 </head>
7 <body>
8 <center>
9 <h1>Xen Configuration Syntax</h1>
10 <br>
11 <!-- Version 0.1<br>2004 June 21<br> -->
12 Version 0.2<br>2004 July 19<br>
13 </center>
15 <h1>Xen Configuration</h1>
16 The Xen virtual machine creation tools provide command-line interfaces and
17 HTTP interfaces to creating virtual machines. Underneath all these interfaces
18 virtual machine configuration data is represented in a common configuration syntax
19 called SXP.
21 The SXP syntax is s-expressions (sxprs), a simple bracketed abstract syntax.
22 Python lists are used to represent its parsed form, with a support
23 api providing access to fields and values (class xen.xend.sxp).
25 <h1>SXP syntax</h1>
26 <p>A general s-expression has the syntax:
27 <code><pre>
28 s-exp = '(' s-exp* ')' | atom | string
29 </pre></code>
30 Where an <code>atom</code> is an unquoted string, such as fred or /domain/0.
31 A <code>string</code> is a quoted string, supporting the usual escape sequences.
32 Strings support single or double quotes: 'fred 1' or "fred 2" are both accepted.
33 The characters ()[]&lt;&gt{} are separators.
35 <p>An <code>element</code> is an s-expression representing data similar to XML.
36 It has the form:
37 <code><pre>
38 element = '(' name attributes? value* ')'
39 name = atom
40 attributes = '(' '@' attribute* ')'
41 attribute = '(' attrname attrval ')'
42 attrname = atom
43 attrval = atom | string
44 value = element | atom | string
45 </pre></code>
46 The <code>name</code> is the element name (roughly indentifying its type).
47 The <code>attributes</code> is a list of attribute-values.
48 We usually prefer to avoid using attributes, and use sub-elements instead.
49 As in XML, any element may have the attribute <code>id</code> to give it an identifier
50 for later reference.
52 <h1>VM configuration</h1>
53 A vm configuration is a single SXP vm element, with subelements for
54 vm parameters and devices. The supported elements and their fields
55 are listed below.
57 <h2>(vm) element</h2>
58 The top-level element, a virtual machine configuration.
59 <ul>
60 <li>name: string, required. Domain name.
61 <li>id: int, optional, default generated. Domain unique id.
62 <li>memory: int, required. Domain memory in MB.
63 <li>maxmem: int, optional. Maximum domain memory in MB.
64 <li>cpu: int, optional. Cpu to run on.
65 <li>cpu_weight, float, optional, default 1. Cpu weight - controls share of CPU.
66 <li>image: linux | netbsd | ..., required. Domain image (OS-specific element).
67 <li>backend: any backend device type, optional, default none.
68 <li>device: any device type, optional, repeats. Device.
69 <li>restart: string, optional, default onreboot. Restart mode, one of
70 <ul><li>onreboot: restart the domain when it exits with code reboot.
71 <li>always: always restart the domain when it exits.
72 <li>never: never restart the domain.
73 </ul>
74 <li>console: int, optional, default 9600 + domain id. Console port.
75 </ul>
77 <h2>(image (linux)) element</h2>
78 Defines a linux kernel image and its command-line parameters.
79 <ul>
80 <li>kernel: string, required. Kernel image file (absolute path).
81 <li>root: string, optional. Root device.
82 <li>ip: string, optional. IP address specifier.
83 <li>ramdisk: string, optional, default none. Ramdisk file (absolute path).
84 <li>args: string, optional. Extra kernel args.
85 </ul>
87 <h2>(image (netbsd)) element</h2>
88 Defines a netbsd kernel image and its command-line parameters.
89 <ul>
90 <li>kernel: string, required. Kernel image file.
91 <li>root: string, optional. Root device.
92 <li>ip: string, optional. IP address specifier.
93 <li>ramdisk: string, optional, default none. Ramdisk file.
94 <li>args: string, optional. Extra kernel args.
95 </ul>
97 <h2>(backend (blkif)) element</h2>
98 The vm is a block device backend.
99 The vm can have pci devices configured.
101 <h2>(backend (netif)) element</h2>
102 The vm is a net device backend.
104 <h2>(device (vif)) element</h2>
105 Defines a virtual network interface.
106 <ul>
107 <li>mac: string, required. Interface MAC address.
108 <li>bridge: string, optional, default system-dependent. Bridge to connect to.
109 <li>script: string, optional, default system-dependent. Vif script to use
110 when bringing the interface up or down.
111 <li>ip: IP address, optional, no default. May be repeated. An IP address
112 or CIDR-format subnet the vif may use.
113 <li>backend: domain name or id, optional, default 0.
114 Defines the domain to use as the backend for the interface.
115 </ul>
117 <h2>(device (vbd)) element</h2>
118 Defines a virtual block device.
119 <ul>
120 <li>uname: string, required. Virtual block device id, e.g phys:hda1.
121 <li>dev: string, required. Device file name in domain, e.g. xda1.
122 <li>mode: string, optional, default r. Read-write mode: r | rw | w.
123 <li>backend: domain name or id, optional, default 0.
124 Defines the domain to use as the backend for the device.
125 </ul>
126 The uname field defines the device being exported from the block device
127 controller. The dev field defines the device name the vm will see.
128 The device is read-only unless the mode contains w.
130 <h2>(device (pci)) element</h2>
131 Defines a pci device.
132 <ul>
133 <li>bus: int, required. PCI bus id.
134 <li>dev: int, required. PCI dev id.
135 <li>func: int, required. PCI func id.
136 </ul>
137 The bus, dev or func may be given in hex,
138 e.g. 0xff. With no leading 0x they are interpreted as decimal.
140 <h2>(vnet) element</h2>
141 Defines the virtual networks associated with vifs (may go away soon).
142 Contains a list of vif elements:
143 <ul>
144 <li>id: id of the vif being configured.
145 <li>vnet: id of vnet the vif is assigned to.
146 </ul>
148 <h1>Examples</h1>
149 <p> A vm with 64 MB memory, root on /dev/xda1 (mapped from /dev/hda1),
150 one vif with default MAC.
151 <code><pre>
152 (vm
153 (name xendom1)
154 (memory 64)
155 (image
156 (linux
157 (kernel /boot/vmlinuz-2.6.12-xen)
158 (ip ::::xendom1:eth0:dhcp)
159 (root /dev/xda1)
160 (args 'rw fastboot 4')
161 )
162 )
163 (device (vif))
164 (device (vbd (uname phy:hda1) (dev xda1) (mode w)))
165 )
166 </pre></code>
168 <p>A vm with 64 MB memory, NFS root, and 2 vifs on separate vnets.
169 <code><pre>
170 (vm
171 (name xendom2)
172 (memory 64)
173 # Define a linux image.
174 (image
175 (linux
176 (kernel "/boot/vmlinuz-2.4.26-xen")
177 (ip "::::xendom2:eth0:dhcp")
178 (root "/dev/nfs")
179 (args "rw fastboot nfsroot=15.144.25.79:/opt/xen/xendom2 4")
180 )
181 )
182 # Define some vifs, with ids for use later.
183 (device (vif (@ (id vif1)) (mac aa:00:00:00:00:12)))
184 (device (vif (@ (id vif2)) (mac aa:00:00:00:10:12)))
186 # Configure vnets. Refer to vifs by id.
187 (vnet (vif (id vif1) (vnet 1))
188 (vif (id vif2) (vnet 2)))
190 )
191 </pre></code>
193 </body>
194 </html>