docs: add documentation for domain scheduling

Signed-off-by: James Archer <[email protected]>

docs/manual.md

@@ -102,6 +102,7 @@ This document attempts to clearly describe all of these terms, however as the co
 * [notification](#notification)
 * [interrupt](#irq)
 * [fault](#fault)
+* [domain scheduling](#domain)
 
 ## System {#system}
 
@@ -173,6 +174,10 @@ Runnable PDs of the same priority are scheduled in a round-robin manner.
 
 The **passive** determines whether the PD is passive. A passive PD will have its scheduling context revoked after initialisation and then bound instead to the PD's notification object. This means the PD will be scheduled on receiving a notification, whereby it will run on the notification's scheduling context. When the PD receives a *protected procedure* by another PD or a *fault* caused by a child PD, the passive PD will run on the scheduling context of the callee.
 
+#### Domain scheduling (experimental)
+
+If the SDK is built with experimental domain support, the PD can be assigned to a scheduling **domain** in the system description. If a PD is assigned to a domain, then the PD will only be allowed to execute when that domain is active. Which domain is active at any given point in time is determined by the [domain schedule](#domain).
+
 ## Virtual Machine {#vm}
 
 A *virtual machine* (VM) is a runtime abstraction for running guest operating systems in Microkit. It is similar
@@ -311,6 +316,10 @@ protection domain. The same applies for a virtual machine.
 This means that whenever a fault is caused by a child, it will be delivered to the parent PD instead of the system fault
 handler via the `fault` entry point. It is then up to the parent to decide how the fault is handled.
 
+## Domain scheduling (experimental) {#domain}
+
+Microkit can be built with experimental support for a method of temporally isolating different groups of PDs called domain scheduling. On a Microkit system, only one domain is active at a time, and the kernel alternates between domains according to a round-robin schedule. A domain schedule consists of an ordered list of domains, each with an associated length of time to run. The kernel will then activate a domain for the specified length of time; after that time has passed, it will deactivate that domain and activate the next domain for its length of time, and so on, proceeding through the list until it wraps back to the first domain. PDs are assigned to domains, such that when a certain domain is active, only PDs belonging to that domain will be scheduled to run.
+
 # SDK {#sdk}
 
 Microkit is distributed as a software development kit (SDK).
@@ -630,6 +639,7 @@ Within the `system` root element the following child elements are supported:
 * `protection_domain`
 * `memory_region`
 * `channel`
+* `domain_schedule` (if SDK is built with domain scheduling support)
 
 ## `protection_domain`
 
@@ -646,6 +656,7 @@ It supports the following attributes:
 * `stack_size`: (optional) Number of bytes that will be used for the PD's stack.
   Must be be between 4KiB and 16MiB and be 4K page-aligned. Defaults to 4KiB.
 * `smc`: (optional, only on ARM) Allow the PD to give an SMC call for the kernel to perform. Only available when the kernel has been configured with `KernelAllowSMCCalls`. Defaults to false.
+* `domain`: (optional, experimental) Specifies the name of the scheduling domain the PD belongs to.
 
 Additionally, it supports the following child elements:
 
@@ -736,6 +747,19 @@ The `end` element has the following attributes:
 The `id` is passed to the PD in the `notified` and `protected` entry points.
 The `id` should be passed to the `microkit_notify` and `microkit_ppcall` functions.
 
+## `domain_schedule` (experimental)
+
+The `domain_schedule` element has has a list of up to 256 `domain` child elements. Each child specifies information about a particular domain, and the order of the child elements specifies the order in which the domains will be scheduled.
+
+The `domain` element has the following attributes:
+
+* `name`: Name of the domain.
+* `length`: Length of time the domain will run each time it is active, in microseconds.
+
+The `name` attribute of each `domain` element can be referenced in the `domain` attribute of a `protection_domain` element.
+
+The `domain_schedule` element is only valid if the SDK is built with the `--experimental-domain-support` flag.
+
 # Board Support Packages {#bsps}
 
 This chapter describes the board support packages that are available in the SDK.