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

[Jan Beulich <jbeulich@xxxxxxxx>]

On 17.10.2023 12:15, Andrew Cooper wrote:
> On 17/10/2023 7:34 am, Jan Beulich wrote:
>> On 16.10.2023 18:24, Andrew Cooper wrote:
>>> +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.
> 
> Triple fault, maybe.  fatal exceptions terminating the VM, no.
> 
> For both, these details are not important for the document.  This is an
> list of examples, not an exhaustive list.

Of course. But I would recommend to avoid having examples which don't
describe technical details correctly.

>>> +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.
> 
> Yes, but again, this is just a examples.  Other data pages should only
> be mapped while data is in flight.

Hmm, blkif's persistent grants are explicitly not like that. All I'm asking
for here is to insert another "e.g."

Jan