Re: [PATCH for-4.18] docs/sphinx: Lifecycle of a domid

[Jan Beulich <jbeulich@xxxxxxxx>]

On 16.10.2023 18:24, Andrew Cooper wrote:
> +Creation
> +--------
> +
> +Within Xen, the ``domain_create()`` function is used to allocate and perform
> +bare minimum construction of a domain.  The :term:`control domain` accesses
> +this functionality via the ``DOMCTL_createdomain`` hypercall.
> +
> +The final action that ``domain_create()`` performs before returning
> +successfully is to enter the new domain into the domlist.  This makes the
> +domain "visible" within Xen, allowing the new domid to be successfully
> +referenced by other hypercalls.
> +
> +At this point, the domain exists as far as Xen is concerned, but not usefully
> +as a VM yet.  The toolstack performs further construction activities;
> +allocating vCPUs, RAM, copying in the initial executable code, etc.  Domains
> +are automatically created with one "pause" reference count held, meaning that
> +it is not eligible for scheduling.

Nit: Afaict either "A domain is ..." or "... they are ...". One might also
add "... right away, i.e. until the tool stack asks for the pause count to
be decremented".

> +Termination
> +-----------
> +
> +The VM runs for a period of time, but eventually stops.  It can stop for a
> +number of reasons, including:
> +
> + * Directly at the guest kernel's request, via the ``SCHEDOP_shutdown``
> +   hypercall.  The hypercall also includes the reason for the shutdown,
> +   e.g. ``poweroff``, ``reboot`` or ``crash``.
> +
> + * Indirectly from certain states.  E.g. executing a ``HLT`` instruction with
> +   interrupts disabled is interpreted as a shutdown request as it is a common
> +   code pattern for fatal error handling when no better options are 
> available.

HLT (note btw that this is x86 and HVM specific and hence may want mentioning
as such) is interpreted this way only if all other vCPU-s are also "down"
already.

> + * Indirectly from fatal exceptions.  In some states, execution is unable to
> +   continue, e.g. Triple Fault on x86.

Nit: This again is HVM specific.

> + * Directly from the device model, via the ``DMOP_remote_shutdown`` 
> hypercall.
> +   E.g. On x86, the 0xcf9 IO port is commonly used to perform platform
> +   poweroff, reset or sleep transitions.
> +
> + * Directly from the toolstack.  The toolstack is capable of initiating
> +   cleanup directly, e.g. ``xl destroy``.  This is typically an 
> administration
> +   action of last resort to clean up a domain which malfunctioned but not
> +   terminated properly.

Nit: You're the native speaker, but doesn't this want to be "... but did not
terminate ..."?

> +Destruction
> +-----------
> +
> +The domain object in Xen is reference counted, and survives until all
> +references are dropped.
> +
> +The ``@releaseDomain`` watch is to inform all entities that hold a reference
> +on the domain to clean up.  This may include:
> +
> + * Paravirtual driver backends having a grant map of the shared ring with the
> +   frontend.

Beyond the shared ring(s), other (data) pages may also still have mappings.

Jan