Skip to content

Commit 0472024

Browse files
robhoesrobhoes
authored
Docs changes; minor C# SDK enhancement. (#6174)
Regarding the docs changes, I moved the copies of `basics.md`, `wire-protocol.md`, and `vm-lifecycle.md` from `ocaml/doc` to `doc/content/xen-api`. The latter folder had these files already, so the resulting changes on them are the following: - `basics.md` has formatting changes only. - `vm-lifecycle.md` has now the additional section on VM boot parameters. - `wire-protocol.md` has formatting changes, the sections for JSON-RPC, and a section on the error format which previously was in the API errors markdown (and was absent from the github.io docs since we don't list the errors anywhere; we could add this list in a future PR).
2 parents 88534a0 + 039f61f commit 0472024

File tree

10 files changed

+865
-1259
lines changed

10 files changed

+865
-1259
lines changed

‎doc/content/xen-api/basics.md‎

Lines changed: 77 additions & 71 deletions
Original file line numberDiff line numberDiff line change
@@ -3,14 +3,16 @@ title = "XenAPI Basics"
33
weight = 10
44
+++
55

6-
This document contains a description of the Xen Management API – an interface for
6+
This document contains a description of the Xen Management API - an interface for
77
remotely configuring and controlling virtualised guests running on a
88
Xen-enabled host.
99

10-
The XenAPI is presented here as a set of Remote Procedure Calls, with a wire
11-
format based upon [XML-RPC](http://xmlrpc.scripting.com).
12-
No specific language bindings are prescribed,
13-
although examples will be given in the python programming language.
10+
The API is presented here as a set of Remote Procedure Calls (RPCs).
11+
There are two supported wire formats, one based upon
12+
[XML-RPC](http://xmlrpc.scripting.com/spec.html)
13+
and one based upon [JSON-RPC](http://www.jsonrpc.org) (v1.0 and v2.0 are both
14+
recognized). No specific language bindings are prescribed, although examples
15+
are given in the Python programming language.
1416

1517
Although we adopt some terminology from object-oriented programming,
1618
future client language bindings may or may not be object oriented.
@@ -21,98 +23,102 @@ specific values. Objects are persistent and exist on the server-side.
2123
Clients may obtain opaque references to these server-side objects and then
2224
access their fields via get/set RPCs.
2325

24-
For each class we specify a list of fields along with their _types_ and _qualifiers_. A
25-
qualifier is one of:
26+
For each class we specify a list of fields along with their _types_ and
27+
_qualifiers_. A qualifier is one of:
2628

27-
- _RO/runtime_: the field is Read
28-
Only. Furthermore, its value is automatically computed at runtime.
29-
For example: current CPU load and disk IO throughput.
30-
- _RO/constructor_: the field must be manually set
31-
when a new object is created, but is then Read Only for
32-
the duration of the object's life.
33-
For example, the maximum memory addressable by a guest is set
34-
before the guest boots.
35-
- _RW_: the field is Read/Write. For example, the name of a VM.
29+
- _RO/runtime_: the field is Read Only. Furthermore, its value is
30+
automatically computed at runtime. For example, current CPU load and disk IO
31+
throughput.
3632

37-
Types
38-
-----
33+
- _RO/constructor_: the field must be manually set when a new object is
34+
created, but is then Read Only for the duration of the object's life.
35+
For example, the maximum memory addressable by a guest is set
36+
before the guest boots.
37+
38+
- _RW_: the field is Read/Write. For example, the name of a VM.
39+
40+
## Types
3941

4042
The following types are used to specify methods and fields in the API Reference:
4143

42-
- `string`: Text strings.
43-
- `int`: 64-bit integers.
44-
- `float`: IEEE double-precision floating-point numbers.
45-
- `bool`: Boolean.
46-
- `datetime`: Date and timestamp.
47-
- `c ref`: Reference to an object of class `c`.
48-
- `t set`: Arbitrary-length set of values of type `t`.
49-
- `(k → v) map`: Mapping from values of type `k` to values of type `v`.
50-
- `e enum`: Enumeration type with name `e`. Enums are defined in the API Reference together with classes that use them.
51-
52-
Note that there are a number of cases where `ref`s are _doubly
53-
linked_ – e.g. a VM has a field called `VIFs` of type
54-
`VIF ref set`; this field lists
55-
the network interfaces attached to a particular VM. Similarly, the VIF
56-
class has a field called `VM` of type `VM ref` which references the VM to which the interface is connected.
44+
- `string`: Text strings.
45+
- `int`: 64-bit integers.
46+
- `float`: IEEE double-precision floating-point numbers.
47+
- `bool`: Boolean.
48+
- `datetime`: Date and timestamp.
49+
- `c ref`: Reference to an object of class `c`.
50+
- `t set`: Arbitrary-length set of values of type `t`.
51+
- `(k -> v) map`: Mapping from values of type `k` to values of type `v`.
52+
- `e enum`: Enumeration type with name `e`. Enums are defined in the API
53+
reference together with classes that use them.
54+
55+
Note that there are a number of cases where `ref`s are _doubly linked_.
56+
For example, a `VM` has a field called `VIFs` of type `VIF ref set`;
57+
this field lists the network interfaces attached to a particular VM.
58+
Similarly, the `VIF` class has a field called `VM` of type `VM ref`
59+
which references the VM to which the interface is connected.
5760
These two fields are _bound together_, in the sense that
5861
creating a new VIF causes the `VIFs` field of the corresponding
5962
VM object to be updated automatically.
6063

61-
The API reference explicitly lists the fields that are
64+
The API reference lists explicitly the fields that are
6265
bound together in this way. It also contains a diagram that shows
6366
relationships between classes. In this diagram an edge signifies the
64-
existance of a pair of fields that are bound together, using standard
67+
existence of a pair of fields that are bound together, using standard
6568
crows-foot notation to signify the type of relationship (e.g.
6669
one-many, many-many).
6770

68-
RPCs associated with fields
69-
---------------------------
71+
## RPCs associated with fields
72+
73+
Each field, `f`, has an RPC accessor associated with it that returns `f`'s value:
74+
75+
- `get_f (r)`: takes a `ref`, `r` that refers to an object and returns the value
76+
of `f`.
77+
78+
Each field, `f`, with qualifier _RW_ and whose outermost type is `set` has the
79+
following additional RPCs associated with it:
7080

71-
Each field, `f`, has an RPC accessor associated with it
72-
that returns `f`'s value:
81+
- `add_f(r, v)`: adds a new element `v` to the set.
82+
Note that sets cannot contain duplicate values, hence this operation has
83+
no action in the case that `v` is already in the set.
7384

74-
- `get_f (r)`: Takes a `ref`, `r`, that refers to an object and returns the value of `f`.
85+
- `remove_f(r, v)`: removes element `v` from the set.
7586

76-
Each field, `f`, with attribute `RW` and whose outermost type is `set` has the following
77-
additional RPCs associated with it:
87+
Each field, `f`, with qualifier _RW_ and whose outermost type is `map` has the
88+
following additional RPCs associated with it:
7889

79-
- `add_f (r, v)`: Adds a new element `v` to the set. Since sets cannot contain duplicate values this operation has no action in the case
80-
that `v` was already in the set.
90+
- `add_to_f(r, k, v)`: adds new pair `k -> v` to the mapping stored in `f` in
91+
object `r`. Attempting to add a new pair for duplicate key, `k`, fails with a
92+
`MAP_DUPLICATE_KEY` error.
8193

82-
- `remove_f (r, v)`: Removes element `v` from the set.
94+
- `remove_from_f(r, k)`: removes the pair with key `k`
95+
from the mapping stored in `f` in object `r`.
8396

84-
Each field, `f`, with attribute RW and whose outermost type is `map` has the following
85-
additional RPCs associated with it:
97+
Each field whose outermost type is neither `set` nor `map`, but whose
98+
qualifier is _RW_ has an RPC accessor associated with it that sets its value:
8699

87-
- `add_to_f (r, k, v)`: Adds new pair `(k → v)` to the mapping stored in `f` in object `r`. Attempting to add a new pair for duplicate
88-
key, `k`, fails with an `MAP_DUPLICATE_KEY` error.
89-
- `remove_from_f (r, k)`: Removes the pair with key `k` from the mapping stored in `f` in object `r`.
100+
- `set_f(r, v)`: sets the field `f` on object `r` to value `v`.
90101

91-
Each field whose outermost type is neither `set` nor `map`,
92-
but whose attribute is RW has an RPC accessor associated with it
93-
that sets its value:
102+
## RPCs associated with classes
94103

95-
- `set_f (r, v)`: Sets field `f` on object `r` to value `v`.
104+
- Most classes have a _constructor_ RPC named `create` that
105+
takes as parameters all fields marked _RW_ and _RO/constructor_. The result
106+
of this RPC is that a new _persistent_ object is created on the server-side
107+
with the specified field values.
96108

97-
RPCs associated with classes
98-
----------------------------
109+
- Each class has a `get_by_uuid(uuid)` RPC that returns the object
110+
of that class that has the specified `uuid`.
99111

100-
- Most classes have a _constructor_ RPC named `create` that
101-
takes as parameters all fields marked RW and
102-
RO/constructor. The result of this RPC is that a new _persistent_ object is
103-
created on the server-side with the specified field values.
104-
- Each class has a `get_by_uuid (uuid)` RPC that returns the object
105-
of that class that has the specified UUID.
106-
- Each class that has a `name_label` field has a `get_by_name_label (name_label)` RPC that returns a set of objects of that
107-
class that have the specified `name_label`.
108-
- Most classes have a `destroy (r)` RPC that explicitly deletes the persistent object specified by `r` from the system. This is a
109-
non-cascading delete – if the object being removed is referenced by another
110-
object then the `destroy` call will fail.
112+
- Each class that has a `name_label` field has a
113+
`get_by_name_label(name_label)` RPC that returns a set of objects of that
114+
class that have the specified `name_label`.
111115

112-
Additional RPCs
113-
---------------
116+
- Most classes have a `destroy(r)` RPC that explicitly deletes
117+
the persistent object specified by `r` from the system. This is a
118+
non-cascading delete - if the object being removed is referenced by another
119+
object then the `destroy` call will fail.
114120

115-
As well as the RPCs enumerated above, most classes have additional RPCs
116-
associated with them. For example, the VM class has RPCs for cloning,
121+
Apart from the RPCs enumerated above, most classes have additional RPCs
122+
associated with them. For example, the `VM` class has RPCs for cloning,
117123
suspending, starting etc. Such additional RPCs are described explicitly
118124
in the API reference.

‎doc/content/xen-api/topics/vm-lifecycle.md‎

Lines changed: 46 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,9 @@
22
title = "VM Lifecycle"
33
+++
44

5+
The following figure shows the states that a VM can be in and the
6+
API calls that can be used to move the VM between these states.
7+
58
```mermaid
69
graph
710
halted-- start(paused) -->paused
@@ -17,7 +20,48 @@ graph
1720
halted-- destroy -->destroyed
1821
```
1922

20-
The figure above shows the states that a VM can be in and the
21-
API calls that can be used to move the VM between these states.
23+
## VM boot parameters
24+
25+
The `VM` class contains a number of fields that control the way in which the VM
26+
is booted. With reference to the fields defined in the VM class (see later in
27+
this document), this section outlines the boot options available and the
28+
mechanisms provided for controlling them.
29+
30+
VM booting is controlled by setting one of the two mutually exclusive groups:
31+
"PV" and "HVM". If `HVM.boot_policy` is an empty string, then paravirtual
32+
domain building and booting will be used; otherwise the VM will be loaded as a
33+
HVM domain, and booted using an emulated BIOS.
34+
35+
When paravirtual booting is in use, the `PV_bootloader` field indicates the
36+
bootloader to use. It may be "pygrub", in which case the platform's default
37+
installation of pygrub will be used, or a full path within the control domain to
38+
some other bootloader. The other fields, `PV_kernel`, `PV_ramdisk`, `PV_args`,
39+
and `PV_bootloader_args` will be passed to the bootloader unmodified, and
40+
interpretation of those fields is then specific to the bootloader itself,
41+
including the possibility that the bootloader will ignore some or all of
42+
those given values. Finally the paths of all bootable disks are added to the
43+
bootloader commandline (a disk is bootable if its VBD has the bootable flag set).
44+
There may be zero, one, or many bootable disks; the bootloader decides which
45+
disk (if any) to boot from.
46+
47+
If the bootloader is pygrub, then the menu.lst is parsed, if present in the
48+
guest's filesystem, otherwise the specified kernel and ramdisk are used, or an
49+
autodetected kernel is used if nothing is specified and autodetection is
50+
possible. `PV_args` is appended to the kernel command line, no matter which
51+
mechanism is used for finding the kernel.
52+
53+
If `PV_bootloader` is empty but `PV_kernel` is specified, then the kernel and
54+
ramdisk values will be treated as paths within the control domain. If both
55+
`PV_bootloader` and `PV_kernel` are empty, then the behaviour is as if
56+
`PV_bootloader` were specified as "pygrub".
57+
58+
When using HVM booting, `HVM_boot_policy` and `HVM_boot_params` specify the boot
59+
handling. Only one policy is currently defined, "BIOS order". In this case,
60+
`HVM_boot_params` should contain one key-value pair "order" = "N" where N is the
61+
string that will be passed to QEMU.
62+
Optionally `HVM_boot_params` can contain another key-value pair "firmware"
63+
with values "bios" or "uefi" (default is "bios" if absent).
64+
By default Secure Boot is not enabled, it can be enabled when "uefi" is enabled
65+
by setting `VM.platform["secureboot"]` to true.
2266

2367
{{% children %}}

0 commit comments

Comments
 (0)