Skip to content

Commit

Permalink
Update feature/perf from master (xapi-project#6218)
Browse files Browse the repository at this point in the history 
Continuing from xapi-project#6208

The conflict resolution can be reviewed with:
`git log --remerge-diff -1 8b8af63`

```diff
diff --git a/ocaml/libs/xapi-stdext/lib/xapi-stdext-threads/scheduler.ml b/ocaml/libs/xapi-stdext/lib/xapi-stdext-threads/scheduler.ml
remerge CONFLICT (content): Merge conflict in ocaml/libs/xapi-stdext/lib/xapi-stdext-threads/scheduler.ml
index 7bace30dae..27cf306995 100644
--- a/ocaml/libs/xapi-stdext/lib/xapi-stdext-threads/scheduler.ml
+++ b/ocaml/libs/xapi-stdext/lib/xapi-stdext-threads/scheduler.ml
@@ -33,49 +33,8 @@ let (queue : t Ipq.t) = Ipq.create 50 queue_default

 let lock = Mutex.create ()

-<<<<<<< 6589d9a (Xapi thread classification - part 2 (xapi-project#6154))
 let add_to_queue_span name ty start_span newfunc =
   let ( ++ ) = Mtime.Span.add in
-||||||| 4f3f08f
-module Clock = struct
-  let span s = Mtime.Span.of_uint64_ns (Int64.of_float (s *. 1e9))
-
-  let span_to_s span =
-    Mtime.Span.to_uint64_ns span |> Int64.to_float |> fun ns -> ns /. 1e9
-
-  let add_span clock secs =
-    (* return mix or max available value if the add overflows *)
-    match Mtime.add_span clock (span secs) with
-    | Some t ->
-        t
-    | None when secs > 0. ->
-        Mtime.max_stamp
-    | None ->
-        Mtime.min_stamp
-end
-
-let add_to_queue name ty start newfunc =
-  let ( ++ ) = Clock.add_span in
-=======
-module Clock = struct
-  let span s = Mtime.Span.of_uint64_ns (Int64.of_float (s *. 1e9))
-
-  let span_to_s span = Mtime.Span.to_float_ns span |> fun ns -> ns /. 1e9
-
-  let add_span clock secs =
-    (* return mix or max available value if the add overflows *)
-    match Mtime.add_span clock (span secs) with
-    | Some t ->
-        t
-    | None when secs > 0. ->
-        Mtime.max_stamp
-    | None ->
-        Mtime.min_stamp
-end
-
-let add_to_queue name ty start newfunc =
-  let ( ++ ) = Clock.add_span in
->>>>>>> 8c9b754 (SDK fixes including CP-53003 (xapi-project#6210))
   let item =
     {
       Ipq.ev= {func= newfunc; ty; name}
```

This code got deleted in `feature/perf`
6b02474, where `span_to_s` got replaced
with `Clock.Timer.span_to_s`, and changed in master by
e68cda7.
Both achieve the same result: `span_to_s` uses `Mtime.Span.to_float_ns`,
except the commit on feature/perf also removes code duplication by
reusing the other clock module.
  • Loading branch information
@edwintorok
edwintorok authored Jan 13, 2025
2 parents 6589d9a + 8b8af63 commit b418d69
Show file tree
Hide file tree
Showing 71 changed files with 2,509 additions and 2,337 deletions.
148 changes: 77 additions & 71 deletions doc/content/xen-api/basics.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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.
48 changes: 46 additions & 2 deletions doc/content/xen-api/topics/vm-lifecycle.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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 %}}
Loading

0 comments on commit b418d69

Please sign in to comment.