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

[zithro <slack@xxxxxxxxx>]

On 20 Mar 2024 17:08, Anthony PERARD wrote:
> 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.
Thanks for the links !
From "https://en.wikipedia.org/wiki/Sentence_spacing#Computer_era"; :
- "text-editing [...] in Emacs by default uses a double space following 
a period"
- "Troff uses two spaces to mark the end of a sentence"

I guess we at least know why ? :) Many man pages (not only Xen's) use 
double spaces. I just copied the format, good to know it's not 
mandatory. Let's save disk space, one space at a time.
(For fun, another quote from wiki : "Varying the spacing between 
sentences, and using the changing spacing to encode information, are a 
standard method of steganography, hiding secret information in public 
documents", so ... what are you doing guys ? ^^).

> >   - 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.
Ok, nevermind then.
By the way, are "raw text" files (*.txt) still accepted as docs ?

> > ---
> > 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
(one may also use 'watch -n 1 xl list' to "follow states" during tests)

> 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."
Ok, will rephrase ! Although I'd have agreed you'd do such changes while 
committing, you better know the terminology than me ! ;)
> 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.
I also wanted to "normalize" the shutdown statuses between 'xl list' and 
'xl top'. I mainly use (and dev a bit in) xentop, and realized the 
shutdown statuses are not shown (only "s", not "sX").
> > +=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.
I'm not sure if you have seen my other patch "Add suspend-to-ram to xl" 
(posted 29 february, no answers yet).
It allows for a domain to be suspended from dom0, without systemd, using 
libxl. Libvirt can do this, and Qubes is using it to suspend domUs 
before suspending dom0.
It works, and better than pause/unpause for the domU, but there's a bug 
later, the domains don't get "destroy"ed after a correct shutdown, need 
to 'xl destroy' manually. I talked a bit about that on XenDevel, but 
didn't get a correct answer, so the patch is stalled ...
Anyways, "ss" would be seen in both cases, if I correctly read the code 
Roger showed me (I cannot use live migration) there is only one 
"suspend" reason.
Meanwhile, will provide v3 !

> Thanks,
--
++
zithro / Cyril