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

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

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_{scheduler_name}_DEFAULT` when you building Xen to adjust the
default scheduler.

Roger.