Re: [PATCH v2] Documentation/arch: Add kernel feature descriptions and arch support status under Documentation/features/

[Ingo Molnar <mingo@kernel.org>]

* Andrew Morton <akpm@linux-foundation.org> wrote:

> > Add arch support matrices for more than 40 generic kernel features
> > that need per architecture support.
> > 
> > Each feature has its own directory under Documentation/features/feature_name/,
> > and the arch-support.txt file shows its current arch porting status.
> > 
> > For example, lockdep support is shown the following way:
> > 
> >     triton:~/tip> cat Documentation/features/lockdep/arch-support.txt
> >     #
> >     # Feature name:          lockdep
> >     #         Kconfig:       LOCKDEP_SUPPORT
> >     #         description:   arch supports the runtime locking correctness debug facility
> >     #
> >         -----------------------
> >         |         arch |status|
> >         -----------------------
> > ...
> >         |      xtensa: |  ok  |
> >         -----------------------
> > 
> > For generic kernel features that need architecture support, the
> > arch-support.txt file in each feature directory shows the arch
> > support matrix, for all upstream Linux architectures.
> > 
> > The meaning of entries in the tables is:
> > 
> >     | ok |  # feature supported by the architecture
> >     |TODO|  # feature not yet supported by the architecture
> >     | .. |  # feature cannot be supported by the hardware
> 
> Presumably there will be instances where the maintainer decides "we 
> shall not implement that".

So I tried to limit the list of features to those that represent the 
overall progress of the generic kernel and are recommended on all 
architectures that are able to support it.

There are certainly features that are opt-in. We could still list them 
here as well, because this is a convenient central index, but would 
mark them not with 'TODO' but with a low-key '..' marking?

On the other end of the spectrum we could also define 'must have' 
features for new architectures. For example modern-timekeeping and 
clockevents.

The patch that adds a new architecture to all these files would give 
us a good overview about how complete an initial port is.

> > This directory structure can be used in the future to add other 
> > files - such as porting guides, testing description, etc.
> 
> I suppose so.  Having a great bunch of directories, each containing 
> a single file is a bit odd.

It's a starting point and nicely extensible. I was thinking about one 
more intermediate level:

   Documentation/features/locking/lockdep/
   Documentation/features/locking/rwsem-optimized/
   Documentation/features/locking/queued-rwlocks/
   Documentation/features/locking/queued-spinlocks/
   ...

   Documentation/features/vm/PG_uncached/
   Documentation/features/vm/pmdp_splitting_flush/
   Documentation/features/vm/pte_special/
   ...

The advantage of this, beyond more structure, would be that I'd 
probably move most of the Documentation/locking/*.txt files into 
Documentation/features/locking/, for example lockdep-design.txt would 
go into Documentation/features/locking/lockdep/.

I'd keep the hierarchy at a predictable depth though, i.e.:

   Documentation/features/<subsystem>/<feature_name>/

> It would be nice to provide people with commit IDs to look at, but 
> the IDs won't be known at the time the documentation file is 
> created.  We could provide patch titles.

Ok.

> But still, let's not overdo it - get something in there, see how 
> well it works, evolve it over time.

Yeah.

> I don't think we've heard from any (non-x86) arch maintainers?  Do 
> they consider this useful at all?  Poke.

I think we god some feedback from the PowerPC side, but yeah, would be 
nice to get more reactions.

Thanks,

	Ingo