Merge master to feature branch

doc/content/xen-api/basics.md

@@ -3,14 +3,16 @@ title = "XenAPI Basics"
 weight = 10
 +++
 
-This document contains a description of the Xen Management API – an interface for
+This document contains a description of the Xen Management API - an interface for
 remotely configuring and controlling virtualised guests running on a
 Xen-enabled host.
 
-The XenAPI is presented here as a set of Remote Procedure Calls, with a wire
-format based upon [XML-RPC](http://xmlrpc.scripting.com).
-No specific language bindings are prescribed,
-although examples will be given in the python programming language.
+The API is presented here as a set of Remote Procedure Calls (RPCs).
+There are two supported wire formats, one based upon
+[XML-RPC](http://xmlrpc.scripting.com/spec.html)
+and one based upon [JSON-RPC](http://www.jsonrpc.org) (v1.0 and v2.0 are both
+recognized). No specific language bindings are prescribed, although examples
+are given in the Python programming language.
 
 Although we adopt some terminology from object-oriented programming,
 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.
 Clients may obtain opaque references to these server-side objects and then
 access their fields via get/set RPCs.
 
-For each class we specify a list of fields along with their _types_ and _qualifiers_.  A
-qualifier is one of:
+For each class we specify a list of fields along with their _types_ and
+_qualifiers_. A qualifier is one of:
 
-- _RO/runtime_: the field is Read
-Only. Furthermore, its value is automatically computed at runtime.
-For example: current CPU load and disk IO throughput.
-- _RO/constructor_: the field must be manually set
-when a new object is created, but is then Read Only for
-the duration of the object's life.
-For example, the maximum memory addressable by a guest is set 
-before the guest boots.
-- _RW_: the field is Read/Write. For example, the name of a VM.
+-  _RO/runtime_: the field is Read Only. Furthermore, its value is
+  automatically computed at runtime. For example, current CPU load and disk IO
+  throughput.
 
-Types
------
+-  _RO/constructor_: the field must be manually set when a new object is
+  created, but is then Read Only for the duration of the object's life.
+  For example, the maximum memory addressable by a guest is set
+  before the guest boots.
+
+-  _RW_: the field is Read/Write. For example, the name of a VM.
+
+## Types
 
 The following types are used to specify methods and fields in the API Reference:
 
-- `string`: Text strings.
-- `int`: 64-bit integers.
-- `float`: IEEE double-precision floating-point numbers.
-- `bool`: Boolean.
-- `datetime`: Date and timestamp.
-- `c ref`: Reference to an object of class `c`.
-- `t set`: Arbitrary-length set of values of type `t`.
-- `(k → v) map`: Mapping from values of type `k` to values of type `v`.
-- `e enum`: Enumeration type with name `e`. Enums are defined in the API Reference together with classes that use them.
-
-Note that there are a number of cases where `ref`s are _doubly
-linked_ – e.g. a VM has a field called `VIFs` of type
-`VIF ref set`; this field lists
-the network interfaces attached to a particular VM. Similarly, the VIF
-class has a field called `VM` of type `VM ref` which references the VM to which the interface is connected.
+-  `string`: Text strings.
+-  `int`: 64-bit integers.
+-  `float`: IEEE double-precision floating-point numbers.
+-  `bool`: Boolean.
+-  `datetime`: Date and timestamp.
+-  `c ref`: Reference to an object of class `c`.
+-  `t set`: Arbitrary-length set of values of type `t`.
+-  `(k -> v) map`: Mapping from values of type `k` to values of type `v`.
+-  `e enum`: Enumeration type with name `e`. Enums are defined in the API
+  reference together with classes that use them.
+
+Note that there are a number of cases where `ref`s are _doubly linked_.
+For example, a `VM` has a field called `VIFs` of type `VIF ref set`;
+this field lists the network interfaces attached to a particular VM.
+Similarly, the `VIF` class has a field called `VM` of type `VM ref`
+which references the VM to which the interface is connected.
 These two fields are _bound together_, in the sense that
 creating a new VIF causes the `VIFs` field of the corresponding
 VM object to be updated automatically.
 
-The API reference explicitly lists the fields that are
+The API reference lists explicitly the fields that are
 bound together in this way. It also contains a diagram that shows
 relationships between classes. In this diagram an edge signifies the
-existance of a pair of fields that are bound together, using standard
+existence of a pair of fields that are bound together, using standard
 crows-foot notation to signify the type of relationship (e.g.
 one-many, many-many).
 
-RPCs associated with fields
----------------------------
+## RPCs associated with fields
+
+Each field, `f`, has an RPC accessor associated with it that returns `f`'s value:
+
+-  `get_f (r)`: takes a `ref`, `r` that refers to an object and returns the value
+  of `f`.
+
+Each field, `f`, with qualifier _RW_ and whose outermost type is `set` has the
+following additional RPCs associated with it:
 
-Each field, `f`, has an RPC accessor associated with it
-that returns `f`'s value:
+-  `add_f(r, v)`: adds a new element `v` to the set.
+  Note that sets cannot contain duplicate values, hence this operation has
+  no action in the case that `v` is already in the set.
 
-- `get_f (r)`: Takes a `ref`, `r`, that refers to an object and returns the value of `f`.
+-  `remove_f(r, v)`: removes element `v` from the set.
 
-Each field, `f`, with attribute `RW` and whose outermost type is `set` has the following
-additional RPCs associated with it:
+Each field, `f`, with qualifier _RW_ and whose outermost type is `map` has the
+following additional RPCs associated with it:
 
-- `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
-that `v` was already in the set.
+-  `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 key, `k`, fails with a
+  `MAP_DUPLICATE_KEY` error.
 
-- `remove_f (r, v)`: Removes element `v` from the set.
+-  `remove_from_f(r, k)`: removes the pair with key `k`
+  from the mapping stored in `f` in object `r`.
 
-Each field, `f`, with attribute RW and whose outermost type is `map` has the following
-additional RPCs associated with it:
+Each field whose outermost type is neither `set` nor `map`, but whose
+qualifier is _RW_ has an RPC accessor associated with it that sets its value:
 
-- `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
-key, `k`, fails with an `MAP_DUPLICATE_KEY` error.
-- `remove_from_f (r, k)`: Removes the pair with key `k` from the mapping stored in `f` in object `r`.
+-  `set_f(r, v)`: sets the field `f` on object `r` to value `v`.
 
-Each field whose outermost type is neither `set` nor `map`, 
-but whose attribute is RW has an RPC accessor associated with it
-that sets its value:
+## RPCs associated with classes
 
-- `set_f (r, v)`: Sets field `f` on object `r` to value `v`.
+-  Most classes have a _constructor_ RPC named `create` that
+  takes as parameters all fields marked _RW_ and _RO/constructor_. The result
+  of this RPC is that a new _persistent_ object is created on the server-side
+  with the specified field values.
 
-RPCs associated with classes
-----------------------------
+-  Each class has a `get_by_uuid(uuid)` RPC that returns the object
+  of that class that has the specified `uuid`.
 
-- Most classes have a _constructor_ RPC named `create` that
-takes as parameters all fields marked RW and
-RO/constructor. The result of this RPC is that a new _persistent_ object is
-created on the server-side with the specified field values.
-- Each class has a `get_by_uuid (uuid)` RPC that returns the object
-of that class that has the specified UUID.
-- 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
-class that have the specified `name_label`.
-- Most classes have a `destroy (r)` RPC that explicitly deletes the persistent object specified by `r` from the system.  This is a
-non-cascading delete – if the object being removed is referenced by another
-object then the `destroy` call will fail.
+-  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
+  class that have the specified `name_label`.
 
-Additional RPCs
----------------
+-  Most classes have a `destroy(r)` RPC that explicitly deletes
+  the persistent object specified by `r` from the system.  This is a
+  non-cascading delete - if the object being removed is referenced by another
+  object then the `destroy` call will fail.
 
-As well as the RPCs enumerated above, most classes have additional RPCs
-associated with them. For example, the VM class has RPCs for cloning,
+Apart from the RPCs enumerated above, most classes have additional RPCs
+associated with them. For example, the `VM` class has RPCs for cloning,
 suspending, starting etc. Such additional RPCs are described explicitly
 in the API reference.

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

@@ -2,6 +2,9 @@
 title = "VM Lifecycle"
 +++
 
+The following figure shows the states that a VM can be in and the
+API calls that can be used to move the VM between these states.
+
 ```mermaid
 graph
     halted-- start(paused) -->paused
@@ -17,7 +20,48 @@ graph
     halted-- destroy -->destroyed
 ```
 
-The figure above shows the states that a VM can be in and the
-API calls that can be used to move the VM between these states.
+## VM boot parameters
+
+The `VM` class contains a number of fields that control the way in which the VM
+is booted. With reference to the fields defined in the VM class (see later in
+this document), this section outlines the boot options available and the
+mechanisms provided for controlling them.
+
+VM booting is controlled by setting one of the two mutually exclusive groups:
+"PV" and "HVM".  If `HVM.boot_policy` is an empty string, then paravirtual
+domain building and booting will be used; otherwise the VM will be loaded as a
+HVM domain, and booted using an emulated BIOS.
+
+When paravirtual booting is in use, the `PV_bootloader` field indicates the
+bootloader to use.  It may be "pygrub", in which case the platform's default
+installation of pygrub will be used, or a full path within the control domain to
+some other bootloader.  The other fields, `PV_kernel`, `PV_ramdisk`, `PV_args`,
+and `PV_bootloader_args` will be passed to the bootloader unmodified, and
+interpretation of those fields is then specific to the bootloader itself,
+including the possibility that the bootloader will ignore some or all of
+those given values. Finally the paths of all bootable disks are added to the
+bootloader commandline (a disk is bootable if its VBD has the bootable flag set).
+There may be zero, one, or many bootable disks; the bootloader decides which
+disk (if any) to boot from.
+
+If the bootloader is pygrub, then the menu.lst is parsed, if present in the
+guest's filesystem, otherwise the specified kernel and ramdisk are used, or an
+autodetected kernel is used if nothing is specified and autodetection is
+possible. `PV_args` is appended to the kernel command line, no matter which
+mechanism is used for finding the kernel.
+
+If `PV_bootloader` is empty but `PV_kernel` is specified, then the kernel and
+ramdisk values will be treated as paths within the control domain. If both
+`PV_bootloader` and `PV_kernel` are empty, then the behaviour is as if
+`PV_bootloader` were specified as "pygrub".
+
+When using HVM booting, `HVM_boot_policy` and `HVM_boot_params` specify the boot
+handling.  Only one policy is currently defined, "BIOS order".  In this case,
+`HVM_boot_params` should contain one key-value pair "order" = "N" where N is the
+string that will be passed to QEMU.
+Optionally `HVM_boot_params` can contain another key-value pair "firmware"
+with values "bios" or "uefi" (default is "bios" if absent).
+By default Secure Boot is not enabled, it can be enabled when "uefi" is enabled
+by setting `VM.platform["secureboot"]` to true.
 
 {{% children %}}