Re: [PATCH v2] docs/man: add shutdown reasons to xl (list) man page

[Anthony PERARD <anthony.perard@xxxxxxxxx>]

On Fri, Mar 08, 2024 at 04:19:20PM +0100, zithro / Cyril Rébert wrote:
> Questions (unblocking):
>  - why a double space between all sentences ?

It's an English thing maybe?

Wikipedia has an article about it: 
https://en.wikipedia.org/wiki/Sentence_spacing
But actually, single space seems like it used to be a french thing, even
called "French spacing":
https://en.wikipedia.org/wiki/History_of_sentence_spacing#French_and_English_spacing

I guess it doesn't really matter. I don't really pay attention to it
anyway.

>  - how to get a "simple LF" ? Ie. I want to use <br>, not <p>
>    (a simple <Enter> has no effect, a double renders a <p>)

That doesn't look to be possible, unless you actually managed to write
the paragraph for all targeted formats, with things like =begin html...,
but that would probably make things more complicated that necessary.

> ---
> diff --git a/docs/man/xl.1.pod.in b/docs/man/xl.1.pod.in
> index bed8393473..d37227ba58 100644
> --- a/docs/man/xl.1.pod.in
> +++ b/docs/man/xl.1.pod.in
> @@ -370,12 +370,50 @@ scheduling by the Xen hypervisor.
>  The guest OS has shut down (SCHEDOP_shutdown has been called) but the
>  domain is not dying yet.
>  
> -=item B<c - crashed>
> +There are six shutdown reasons, which will be displayed after the "s" : 
> B<-rscwS>.
> +
> +Note that some states will only be displayed if "on_poweroff=preserve" is 
> set in
> +the config file, see L<xl.cfg(5)>).
> +
> +=over 4
> +
> +=over 4
> +
> +=item B<s- : poweroff>
> +
> +The domain exited normally, it will get destroyed.
> +
> +=item B<sr : reboot>
> +
> +The domain will reboot.

Well, that's not really true. I think to end up in this state, what
happen is that the domain shutdown and ask for a reboot. It's normally
the toolstack job to cleanup the domain then create a new domain for the
guest. I guess you might see this state if you have "on_reboot=preserve"
or you run `xl list` at the right time. Or the toolstack crashed and
fail to kill the domain before a reboot. So maybe a better to have
something like "The domain exited normally and ask for a reboot."

Same things for the other entries (poweroff and watchdog). The status is
just the current status of what is supposed to happen. But a few things
might mean that the domain stay in that state unless the admin does
something. This could be simply because there's "on_*=preserve" setting,
the toolstack crashed or we just happen to look while the toolstack is
cleaning thing up.

> +=item B<ss : suspend>
> +
> +The domain is suspended to disk or to RAM. If suspended to disk, the domain 
> will
> +get destroyed.

I think in that state, the domain is just suspended, maybe to RAM? I
don't know if suspend to disk would end up in this state, my guess is
the domain will go to "poweroff" instead. But for suspend to "RAM", I
think the toolstack is supposed to save the guest memory and guest
config somewhere, maybe even on a different host for live migration?

This is a state that seems to happen as part of a live migration (or `xl
save` I guess).

I tried to suspend a guest (runnning `systemd suspend`), but xl never
reported `ss`, because there's nothing to do I guess. So this state is
probably really about migration.


Thanks,

-- 
Anthony PERARD