Re: [PATCH] docs: fix documentation about default scheduler

[Roger Pau Monné <roger.pau@xxxxxxxxxx>]

On Wed, Nov 11, 2020 at 12:45:38PM +0100, Jürgen Groß wrote:
> On 11.11.20 12:37, Roger Pau Monné wrote:
> > On Wed, Nov 11, 2020 at 12:24:50PM +0100, George Dunlap wrote:
> > > 
> > > 
> > > > On Nov 11, 2020, at 11:10 AM, Andrew Cooper <Andrew.Cooper3@xxxxxxxxxx> 
> > > > wrote:
> > > > 
> > > > On 11/11/2020 10:12, George Dunlap wrote:
> > > > > 
> > > > > > On Nov 10, 2020, at 6:51 PM, Roger Pau Monne <roger.pau@xxxxxxxxxx> 
> > > > > > wrote:
> > > > > > 
> > > > > > Fix the command line document to account for the default scheduler 
> > > > > > not
> > > > > > being credit anymore likely, and the fact that it's selectable from
> > > > > > Kconfig and thus different builds could end up with different 
> > > > > > default
> > > > > > schedulers.
> > > > > > 
> > > > > > Fixes: dafd936dddbd ('Make credit2 the default scheduler')
> > > > > > Signed-off-by: Roger Pau Monné <roger.pau@xxxxxxxxxx>
> > > > > > ---
> > > > > > Changes since v1:
> > > > > > - Point that the default scheduler is being selected by Kconfig,
> > > > > >   don't mention the default Kconfig selection.
> > > > > > ---
> > > > > > docs/misc/xen-command-line.pandoc | 2 +-
> > > > > > 1 file changed, 1 insertion(+), 1 deletion(-)
> > > > > > 
> > > > > > diff --git a/docs/misc/xen-command-line.pandoc 
> > > > > > b/docs/misc/xen-command-line.pandoc
> > > > > > index 4ae9391fcd..eb1db25f92 100644
> > > > > > --- a/docs/misc/xen-command-line.pandoc
> > > > > > +++ b/docs/misc/xen-command-line.pandoc
> > > > > > @@ -1876,7 +1876,7 @@ with read and write permissions.
> > > > > > ### sched
> > > > > > > `= credit | credit2 | arinc653 | rtds | null`
> > > > > > -> Default: `sched=credit`
> > > > > > +> Default: selectable via Kconfig.  Depends on enabled schedulers.
> > > > > Sorry for not weighing in earlier; but this basically makes this 
> > > > > documentation useless.
> > > > 
> > > > No.  It is the only half useable version, by being the only version
> > > > which isn't misleading.
> > > 
> > > The version in this patch essentially says “This has some options, it 
> > > also has a default, but we’re not going to tell you any of them, nor what 
> > > your default most likely is.  Go read KConfig to find out.”  This is is 
> > > completely useless to the person trying to figure out what the default is 
> > > and what potential alternate values they can put here.
> > > 
> > > The vast majority of people who search for this on the internet will have 
> > > that list of options, and have credit2=default.  As long as we tell them 
> > > that a local configuration can override the available options and the 
> > > default, people are smart enough to figure out what their system is doing.
> > > 
> > > > It would however be far better to name the CONFIG_ variable (we do
> > > > elsewhere in this doc) in question so people can actually figure out
> > > > what they've got in front of them.
> > > 
> > > Something like that would be even better, if Roger (or someone) wants to 
> > > write it up.
> > 
> > I'm happy to send an updated version, but would like to have some
> > agreement before doing so. Is the text below acceptable to everyone?
> > 
> > ### sched
> > > `= credit | credit2 | arinc653 | rtds | null`
> > 
> > > Default: `sched=credit2`
> > 
> > Choose the default scheduler. Note the default scheduler is selectable via
> > Kconfig and depends on enabled schedulers. Check
> 
> ... CONFIG_SCHED_DEFAULT to see which scheduler is the default.
> 
> CONFIG_SCHED_{scheduler_name} specify which schedulers are available.

Hm, that's weird. When I hit help in menuconfig for the default
scheduler selection it reports the option is named
SCHED_{name}_DEFAULT. Will change it.

Roger.