| Message ID | 0a2fcad111622431b8cd54c69adc3dedd24fb572.1709910923.git.slack@rabbit.lu (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | [v2] docs/man: add shutdown reasons to xl (list) man page | expand |
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,
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, >
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. + +=item B<ss : suspend> + +The domain is suspended to disk or to RAM. If suspended to disk, the domain will +get destroyed. + +=item B<sc : crash> The domain has crashed, which is always a violent ending. Usually this state only occurs if the domain has been configured not to restart on a crash. See L<xl.cfg(5)> for more info. +=item B<sw : watchdog> + +Restart because watchdog time expired. + +=item B<sS : soft_reset> + +The domain asked to perform 'soft reset' for it. The expected behavior +is to reset internal Xen state for the domain returning it to the point +where it was created but leaving the domain's memory contents and vCPU +contexts intact. This will allow the domain to start over and set up +all Xen specific interfaces again. + +=back + +=back + =item B<d - dying> The domain is in the process of dying, but hasn't completely shut down or
Add the shutdown reasons to the paragraph of "xl list" concerning the shutdown status. I have adapted the explanations from the source code : - tools/xl/xl_info.c : function "list_domains()", variable "shutdown_reason_letters" - xen/include/public/sched.h : variable "shed_shutdown_reason" Suggested-by: Roger Pau Monné <roger.pau@citrix.com> Signed-off-by: Cyril Rébert / zithro <slack@rabbit.lu> --- v2: - apply changes from Anthony and Roger Questions (unblocking): - why a double space between all sentences ? - 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>) --- docs/man/xl.1.pod.in | 40 +++++++++++++++++++++++++++++++++++++++- 1 file changed, 39 insertions(+), 1 deletion(-)