Merge master to feature/easier-pool-join

.github/workflows/release.yml

@@ -20,13 +20,11 @@ jobs:
           python-version: "3.x"
 
       - name: Install build dependencies
-        run: |
-          pip install build
-          sudo apt-get install ocaml dune libfindlib-ocaml-dev libdune-ocaml-dev libcmdliner-ocaml-dev
+        run: pip install build
 
       - name: Generate python package for XenAPI
         run: |
-          ./configure --xapi_version=${{ github.ref_name }}
+          echo "export XAPI_VERSION=${{ github.ref_name }}" > config.mk
           make python
 
       - name: Store python distribution artifacts

doc/content/design/coverage/index.md

@@ -8,7 +8,7 @@ revision: 2
 
 We would like to add optional coverage profiling to existing [OCaml]
 projects in the context of [XenServer] and [XenAPI]. This article
-presents how we do it. 
+presents how we do it.
 
 Binaries instrumented for coverage profiling in the XenServer project
 need to run in an environment where several services act together as
@@ -21,7 +21,7 @@ isolation.
 To build binaries with coverage profiling, do:
 
     ./configure --enable-coverage
-    make 
+    make
 
 Binaries will log coverage data to `/tmp/bisect*.out` from which a
 coverage report can be generated in `coverage/`:
@@ -38,7 +38,7 @@ and logs during execution data to in-memory data structures. Before an
 instrumented binary terminates, it writes the logged data to a file.
 This data can then be analysed with the `bisect-ppx-report` tool, to
 produce a summary of annotated code that highlights what part of a
-codebase was executed. 
+codebase was executed.
 
 [BisectPPX] has several desirable properties:
 
@@ -65,13 +65,13 @@ abstracted by OCamlfind (OCaml's library manager) and OCamlbuild
 
     # build it with instrumentation from bisect_ppx
     ocamlbuild -use-ocamlfind -pkg bisect_ppx -pkg unix example.native
-    
+
     # execute it - generates files ./bisect*.out
     ./example.native
-    
+
     # generate report
     bisect-ppx-report -I _build -html coverage bisect000*
-    
+
     # view coverage/index.html
 
     Summary:
@@ -86,7 +86,7 @@ will be instrumented during compilation. Behind the scenes `ocamlfind`
 makes sure that the compiler uses a preprocessing step that instruments
 the code.
 
-## Signal Handling 
+## Signal Handling
 
 During execution the code instrumentation leads to the collection of
 data. This code registers a function with `at_exit` that writes the data
@@ -98,7 +98,7 @@ terminated by receiving the `TERM` signal, a signal handler must be
 installed:
 
     let stop signal =
-      printf "caught signal %d\n" signal;
+      printf "caught signal %a\n" Debug.Pp.signal signal;
       exit 0
 
     Sys.set_signal Sys.sigterm (Sys.Signal_handle stop)
@@ -149,8 +149,8 @@ environment variable. This can happen on the command line:
 
     BISECT_FILE=/tmp/example ./example.native
 
-In the context of XenServer we could do this in startup scripts. 
-However, we added a bit of code 
+In the context of XenServer we could do this in startup scripts.
+However, we added a bit of code
 
     val Coverage.init: string -> unit
 
@@ -176,12 +176,12 @@ Goals for instrumentation are:
 
 * what files are instrumented should be obvious and easy to manage
 * instrumentation must be optional, yet easy to activate
-* avoid methods that require to keep several files in sync like multiple 
+* avoid methods that require to keep several files in sync like multiple
   `_oasis` files
 * avoid separate Git branches for instrumented and non-instrumented
   code
 
-In the ideal case, we could introduce a configuration switch 
+In the ideal case, we could introduce a configuration switch
 `./configure --enable-coverage` that would prepare compilation for
 coverage instrumentation. While [Oasis] supports the creation of such
 switches, they cannot be used to control build dependencies like
@@ -196,7 +196,7 @@ rules in file `_tags.coverage` that cause files to be instrumented:
 
 leads to the execution of this code during preparation:
 
-    coverage: _tags _tags.coverage 
+    coverage: _tags _tags.coverage
       test ! -f _tags.orig && mv _tags _tags.orig || true
       cat _tags.coverage _tags.orig > _tags
 
@@ -207,7 +207,7 @@ could be tweaked to instrument only some files:
     <**/*.native>:   pkg_bisect_ppx
 
 When `make coverage` is not called, these rules are not active and
-hence, code is not instrumented for coverage. We believe that this 
+hence, code is not instrumented for coverage. We believe that this
 solution to control instrumentation meets the goals from above. In
 particular, what files are instrumented and when is controlled by very
 few lines of declarative code that lives in the main repository of a
@@ -226,14 +226,14 @@ coverage analysis are:
 The `_oasis` file bundles the files under `profiling/` into an internal
 library which executables then depend on:
 
-		# Support files for profiling 
+		# Support files for profiling
 		Library profiling
 			CompiledObject:     best
 			Path:               profiling
 			Install:            false
 			Findlibname:        profiling
 			Modules:            Coverage
-			BuildDepends: 
+			BuildDepends:
 
 		Executable set_domain_uuid
 			CompiledObject:     best
@@ -243,16 +243,16 @@ library which executables then depend on:
 			MainIs:             set_domain_uuid.ml
 			Install:            false
 			BuildDepends:
-				xenctrl, 
-				uuidm, 
+				xenctrl,
+				uuidm,
 				cmdliner,
 				profiling			# <-- here
 
 The `Makefile` target `coverage` primes the project for a profiling build:
 
 		# make coverage - prepares for building with coverage analysis
 
-		coverage: _tags _tags.coverage 
+		coverage: _tags _tags.coverage
 			test ! -f _tags.orig && mv _tags _tags.orig || true
 			cat _tags.coverage _tags.orig > _tags
 

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.