Re: Add CAVEATS to ldom.conf(5) man page
On Wed, May 20, 2020 at 09:35:39AM -0600, Theo de Raadt wrote: > Kurt Mosiejczuk wrote: > > I suppose we could look at having ldomctl throw a warning if there are not > > enough ldom and ttyV devices for the configuration file presented. > Maybe it can test access to the required resources as it starts up. Probably wise for both ldomd on startup and ldomctl when processing ldom.conf. --Kurt
Re: Add CAVEATS to ldom.conf(5) man page
On Wed, May 20, 2020 at 02:01:34PM +0200, Ingo Schwarze wrote: > Now, maybe, some manual page somewhere might say something like > "this program uses .Pa /dev/ldom* device nodes (or .Xr ldom 4 devices) > to do foobar; make sure you have enough of those". Judging from > commands like > >$ man -k any=dev/ldom >$ man -k any~'\' > > it doesn't look like such explanations exist just yet, but if someone > were to write them, they might be appropriate in a DESCRIPTION or > a FILES section of some section 8 manual page, maybe. MAKEDEV(8/sparc64) mentions the various devices, but they should be mentioned in the various driver manuals like vcctty(4/sparc64) already does. I just never came around to it.
Re: Add CAVEATS to ldom.conf(5) man page
Kurt Mosiejczuk wrote: > I suppose we could look at having ldomctl throw a warning if there are not > enough ldom and ttyV devices for the configuration file presented. Maybe it can test access to the required resources as it starts up.
Re: Add CAVEATS to ldom.conf(5) man page
On Wed, May 20, 2020 at 09:24:20AM -0600, Theo de Raadt wrote: > Kurt Mosiejczuk wrote: > > > Seems reasonable, what about adopting vmd(8) CAVEATS for ldomd(8)? > > > Running out of devices with more guests can be nasty do debug. > > Here's an attempt at doing that. There isn't a man page for the ldom > > devices nor is there one specifically for the ttyV* devices, so I left > > the ".Xr" off of those. > Let's step back. Why is it nasty to debug? > What errors are shown? What errors are not shown? Is there an error > reporting missing? Should the code *inspect* for that condition, and > report a warning or error, on stderr or via logging? > If it did, would that make the proposed manual page change redundant? Yeah. The code definitely needs improvement on that front. I've seen parts where it isn't checking return codes on operations on the devices. Part of this started because rcctl reports ldomd starting just fine but ldomd dies if it cannot access a device. I suppose we could look at having ldomctl throw a warning if there are not enough ldom and ttyV devices for the configuration file presented. --Kurt
Re: Add CAVEATS to ldom.conf(5) man page
Kurt Mosiejczuk wrote: > On Mon, May 18, 2020 at 08:12:00PM +0200, Klemens Nanni wrote: > > On Mon, May 18, 2020 at 01:20:07PM -0400, Kurt Mosiejczuk wrote: > > > Learning how LDOMs work on this T4-1 and we only create 8 devices > > > (each /dev/ldom* and /dev/ttyV*) by default. The now-commonly-available > > > T4-1 machines can do far more than that pretty easily, so bump up the > > > number created by default from 8 to 16. > > Seems reasonable, what about adopting vmd(8) CAVEATS for ldomd(8)? > > > Running out of devices with more guests can be nasty do debug. > > Here's an attempt at doing that. There isn't a man page for the ldom > devices nor is there one specifically for the ttyV* devices, so I left > the ".Xr" off of those. Let's step back. Why is it nasty to debug? What errors are shown? What errors are not shown? Is there an error reporting missing? Should the code *inspect* for that condition, and report a warning or error, on stderr or via logging? If it did, would that make the proposed manual page change redundant?
Re: Add CAVEATS to ldom.conf(5) man page
Hi Jason, Jason McIntyre wrote on Wed, May 20, 2020 at 06:38:18AM +0100: > i'm fine with the text, but does it really warrant a CAVEATS section? it > sounds like it should just be part of "this is how it works" text. I may not be the best person to judge this, but as far as i understand, this is a manual page about a configuration file, answering the question "What is the syntax and semantics of that file?" The new paragraph looks like it warns about a trap you may end up in in some unusual situations depending on what exactly you put into the file (unusual because 16 feels like a substantial number to me, presumably it was chosen because it is sufficient for the most common purposes). So CAVEATS doesn't feel wrong to me. Now, maybe, some manual page somewhere might say something like "this program uses .Pa /dev/ldom* device nodes (or .Xr ldom 4 devices) to do foobar; make sure you have enough of those". Judging from commands like $ man -k any=dev/ldom $ man -k any~'\' it doesn't look like such explanations exist just yet, but if someone were to write them, they might be appropriate in a DESCRIPTION or a FILES section of some section 8 manual page, maybe. Either way, i don't feel strongly about any of that. Yours, Ingo
Re: Add CAVEATS to ldom.conf(5) man page
On Wed, May 20, 2020 at 02:30:31AM +0200, Ingo Schwarze wrote: > Hi Kurt, > > Kurt Mosiejczuk wrote on Tue, May 19, 2020 at 07:49:56PM -0400: > > On Mon, May 18, 2020 at 08:12:00PM +0200, Klemens Nanni wrote: > >> On Mon, May 18, 2020 at 01:20:07PM -0400, Kurt Mosiejczuk wrote: > > >>> Learning how LDOMs work on this T4-1 and we only create 8 devices > >>> (each /dev/ldom* and /dev/ttyV*) by default. The now-commonly-available > >>> T4-1 machines can do far more than that pretty easily, so bump up the > >>> number created by default from 8 to 16. > > >> Seems reasonable, what about adopting vmd(8) CAVEATS for ldomd(8)? > >> Running out of devices with more guests can be nasty do debug. > > > Here's an attempt at doing that. There isn't a man page for the ldom > > devices nor is there one specifically for the ttyV* devices, so I left > > the ".Xr" off of those. > > Fair enough as long as those don't exist; if you want to stress that > those correspond to file names (below /dev/ i guess), you can use > ".Pa ldom" and/or ".Pa ttyV"; your call. > > I can't comment on the content, but: > >$ mandoc -Tlint ldom.conf.5 > mandoc: ldom.conf.5:136:10: WARNING: new sentence, new line > mandoc: ldom.conf.5:139:1: WARNING: blank line in fill mode, using .sp > mandoc: ldom.conf.5:140:1: WARNING: blank line in fill mode, using .sp > mandoc: ldom.conf.5:134:2: WARNING: > sections out of conventional order: Sh CAVEATS > > So here is a version that > > * starts the new sentence on a new input line > * avoids trailing blank lines > * puts CAVEATS before BUGS, which is the conventional ordering > i'm fine with the text, but does it really warrant a CAVEATS section? it sounds like it should just be part of "this is how it works" text. jmc > Feel free to use that, or parts of it as desired. > > Yours, > Ingo > > P.S. > Maybe somebody wants to look at writing an ldom(4) manual page, > too? If i understand correctly, then usually, if there is a device > file, having a manual page explaining its purpose is desirable, > right? Or should ldom(4) maybe be an additional .Nm in vldc(4), > with a brief explanation what the purposes of the various vldc > device nodes are? Maybe a FILES section might help there, too? > A bit like audio(4) has an additional name audioctl(4), even though > "audioctl" does not appear in the kernel config files? > > > Index: ldom.conf.5 > === > RCS file: /cvs/src/usr.sbin/ldomctl/ldom.conf.5,v > retrieving revision 1.13 > diff -u -r1.13 ldom.conf.5 > --- ldom.conf.5 21 Feb 2020 19:39:28 - 1.13 > +++ ldom.conf.5 20 May 2020 00:22:39 - > @@ -116,6 +116,12 @@ > .Xr eeprom 8 , > .Xr ldomctl 8 , > .Xr ldomd 8 > +.Sh CAVEATS > +Each guest requires one ldom device and one ttyV device per configured > +logical domain. > +Administrators may need to create additional devices using > +.Xr MAKEDEV 8 > +if more than 16 logical domains are configured. > .Sh BUGS > The hypervisor requires a machine dependent amount of physical memory that is > reserved automatically. >
Re: Add CAVEATS to ldom.conf(5) man page
Hi Kurt, Kurt Mosiejczuk wrote on Tue, May 19, 2020 at 07:49:56PM -0400: > On Mon, May 18, 2020 at 08:12:00PM +0200, Klemens Nanni wrote: >> On Mon, May 18, 2020 at 01:20:07PM -0400, Kurt Mosiejczuk wrote: >>> Learning how LDOMs work on this T4-1 and we only create 8 devices >>> (each /dev/ldom* and /dev/ttyV*) by default. The now-commonly-available >>> T4-1 machines can do far more than that pretty easily, so bump up the >>> number created by default from 8 to 16. >> Seems reasonable, what about adopting vmd(8) CAVEATS for ldomd(8)? >> Running out of devices with more guests can be nasty do debug. > Here's an attempt at doing that. There isn't a man page for the ldom > devices nor is there one specifically for the ttyV* devices, so I left > the ".Xr" off of those. Fair enough as long as those don't exist; if you want to stress that those correspond to file names (below /dev/ i guess), you can use ".Pa ldom" and/or ".Pa ttyV"; your call. I can't comment on the content, but: $ mandoc -Tlint ldom.conf.5 mandoc: ldom.conf.5:136:10: WARNING: new sentence, new line mandoc: ldom.conf.5:139:1: WARNING: blank line in fill mode, using .sp mandoc: ldom.conf.5:140:1: WARNING: blank line in fill mode, using .sp mandoc: ldom.conf.5:134:2: WARNING: sections out of conventional order: Sh CAVEATS So here is a version that * starts the new sentence on a new input line * avoids trailing blank lines * puts CAVEATS before BUGS, which is the conventional ordering Feel free to use that, or parts of it as desired. Yours, Ingo P.S. Maybe somebody wants to look at writing an ldom(4) manual page, too? If i understand correctly, then usually, if there is a device file, having a manual page explaining its purpose is desirable, right? Or should ldom(4) maybe be an additional .Nm in vldc(4), with a brief explanation what the purposes of the various vldc device nodes are? Maybe a FILES section might help there, too? A bit like audio(4) has an additional name audioctl(4), even though "audioctl" does not appear in the kernel config files? Index: ldom.conf.5 === RCS file: /cvs/src/usr.sbin/ldomctl/ldom.conf.5,v retrieving revision 1.13 diff -u -r1.13 ldom.conf.5 --- ldom.conf.5 21 Feb 2020 19:39:28 - 1.13 +++ ldom.conf.5 20 May 2020 00:22:39 - @@ -116,6 +116,12 @@ .Xr eeprom 8 , .Xr ldomctl 8 , .Xr ldomd 8 +.Sh CAVEATS +Each guest requires one ldom device and one ttyV device per configured +logical domain. +Administrators may need to create additional devices using +.Xr MAKEDEV 8 +if more than 16 logical domains are configured. .Sh BUGS The hypervisor requires a machine dependent amount of physical memory that is reserved automatically.
