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

Ingo Molnar
2015-05-15T09:38:03Z

* Ingo Molnar <mingo@kernel.org> wrote:

> > > 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>/

So I've implemented this, the high level structure now looks like
this:

triton:~/tip/Documentation/features> ls -l
total 48
-rw-rw-r-- 1 mingo mingo 396 May 15 11:26 arch-support.txt
drwxrwxr-x 6 mingo mingo 4096 May 15 11:26 core
drwxrwxr-x 12 mingo mingo 4096 May 15 11:26 debug
drwxrwxr-x 6 mingo mingo 4096 May 15 11:26 io
drwxrwxr-x 3 mingo mingo 4096 May 15 11:26 lib
-rwxrwxr-x 1 mingo mingo 692 May 15 11:31 list-arch.sh
drwxrwxr-x 7 mingo mingo 4096 May 15 11:26 locking
drwxrwxr-x 5 mingo mingo 4096 May 15 11:26 perf
drwxrwxr-x 3 mingo mingo 4096 May 15 11:26 sched
drwxrwxr-x 3 mingo mingo 4096 May 15 11:26 seccomp
drwxrwxr-x 8 mingo mingo 4096 May 15 11:26 time
drwxrwxr-x 10 mingo mingo 4096 May 15 11:26 vm
triton:~/tip/Documentation/features>

triton:~/tip/Documentation/features> ls -l locking/
total 20
drwxrwxr-x 2 mingo mingo 4096 May 15 11:26 cmpxchg-local
drwxrwxr-x 2 mingo mingo 4096 May 15 11:26 lockdep
drwxrwxr-x 2 mingo mingo 4096 May 15 11:26 queued-rwlocks
drwxrwxr-x 2 mingo mingo 4096 May 15 11:26 queued-spinlocks
drwxrwxr-x 2 mingo mingo 4096 May 15 11:26 rwsem-optimized

triton:~/tip/Documentation/features> ls -l vm/
total 32
drwxrwxr-x 2 mingo mingo 4096 May 15 11:26 ELF-ASLR
drwxrwxr-x 2 mingo mingo 4096 May 15 11:26 huge-vmap
drwxrwxr-x 2 mingo mingo 4096 May 15 11:26 ioremap_prot
drwxrwxr-x 2 mingo mingo 4096 May 15 11:26 numa-memblock
drwxrwxr-x 2 mingo mingo 4096 May 15 11:26 PG_uncached
drwxrwxr-x 2 mingo mingo 4096 May 15 11:26 pmdp_splitting_flush
drwxrwxr-x 2 mingo mingo 4096 May 15 11:26 pte_special
drwxrwxr-x 2 mingo mingo 4096 May 15 11:26 THP

And this structure, beyond making it easier to navigate, can be
utilized to improve the visualization output as well:

triton:~/tip/Documentation/features> ./list-arch.sh
#
# Kernel feature support matrix of the 'x86' architecture:
#
core/ BPF-JIT : ok | HAVE_BPF_JIT # arch supports BPF JIT optimizations
core/ generic-idle-thread : ok | GENERIC_SMP_IDLE_THREAD # arch makes use of the generic SMP idle thread facility
core/ jump-labels : ok | HAVE_ARCH_JUMP_LABEL # arch supports live patched, high efficiency branches
core/ tracehook : ok | HAVE_ARCH_TRACEHOOK # arch supports tracehook (ptrace) register handling APIs
debug/ gcov-profile-all : ok | ARCH_HAS_GCOV_PROFILE_ALL # arch supports whole-kernel GCOV code coverage profiling
debug/ KASAN : ok | HAVE_ARCH_KASAN # arch supports the KASAN runtime memory checker
debug/ kgdb : ok | HAVE_ARCH_KGDB # arch supports the kGDB kernel debugger
debug/ kprobes : ok | HAVE_KPROBES # arch supports live patched kernel probe
debug/ kprobes-on-ftrace : ok | HAVE_KPROBES_ON_FTRACE # arch supports combined kprobes and ftrace live patching
debug/ kretprobes : ok | HAVE_KRETPROBES # arch supports kernel function-return probes
debug/ optprobes : ok | HAVE_OPTPROBES # arch supports live patched optprobes
debug/ stackprotector : ok | HAVE_CC_STACKPROTECTOR # arch supports compiler driven stack overflow protection
debug/ uprobes : ok | ARCH_SUPPORTS_UPROBES # arch supports live patched user probes
debug/ user-ret-profiler : ok | HAVE_USER_RETURN_NOTIFIER # arch supports user-space return from system call profiler
io/ dma-api-debug : ok | HAVE_DMA_API_DEBUG # arch supports DMA debug facilities
io/ dma-contiguous : ok | HAVE_DMA_CONTIGUOUS # arch supports the DMA CMA (continuous memory allocator)
io/ dma_map_attrs : ok | HAVE_DMA_ATTRS # arch provides dma_*map*_attrs() APIs
io/ sg-chain : ok | ARCH_HAS_SG_CHAIN # arch supports chained scatter-gather lists
lib/ strncasecmp : TODO | __HAVE_ARCH_STRNCASECMP # arch provides an optimized strncasecmp() function
locking/ cmpxchg-local : ok | HAVE_CMPXCHG_LOCAL # arch supports the this_cpu_cmpxchg() API
locking/ lockdep : ok | LOCKDEP_SUPPORT # arch supports the runtime locking correctness debug facility
locking/ queued-rwlocks : ok | ARCH_USE_QUEUED_RWLOCKS # arch supports queued rwlocks
locking/ queued-spinlocks : ok | ARCH_USE_QUEUED_SPINLOCKS # arch supports queued spinlocks
locking/ rwsem-optimized : ok | Optimized asm/rwsem.h # arch provides optimized rwsem APIs
perf/ kprobes-event : ok | HAVE_REGS_AND_STACK_ACCESS_API # arch supports kprobes with perf events
perf/ perf-regs : ok | HAVE_PERF_REGS # arch supports perf events register access
perf/ perf-stackdump : ok | HAVE_PERF_USER_STACK_DUMP # arch supports perf events stack dumps
sched/ numa-balancing : ok | ARCH_SUPPORTS_NUMA_BALANCING # arch supports NUMA balancing
seccomp/ seccomp-filter : ok | HAVE_ARCH_SECCOMP_FILTER # arch supports seccomp filters
time/ arch-tick-broadcast : TODO | ARCH_HAS_TICK_BROADCAST # arch provides tick_broadcast()
time/ clockevents : ok | GENERIC_CLOCKEVENTS # arch support generic clock events
time/ context-tracking : ok | HAVE_CONTEXT_TRACKING # arch supports context tracking for NO_HZ_FULL
time/ irq-time-acct : ok | HAVE_IRQ_TIME_ACCOUNTING # arch supports precise IRQ time accounting
time/ modern-timekeeping : ok | !ARCH_USES_GETTIMEOFFSET # arch does not use arch_gettimeoffset() anymore
time/ virt-cpuacct : ok | HAVE_VIRT_CPU_ACCOUNTING # arch supports precise virtual CPU time accounting
vm/ ELF-ASLR : ok | ARCH_HAS_ELF_RANDOMIZE # arch randomizes the stack, heap and binary images of ELF binaries
vm/ huge-vmap : ok | HAVE_ARCH_HUGE_VMAP # arch supports the ioremap_pud_enabled() and ioremap_pmd_enabled() VM APIs
vm/ ioremap_prot : ok | HAVE_IOREMAP_PROT # arch has ioremap_prot()
vm/ numa-memblock : ok | HAVE_MEMBLOCK_NODE_MAP # arch supports NUMA aware memblocks
vm/ PG_uncached : ok | ARCH_USES_PG_UNCACHED # arch supports the PG_uncached page flag
vm/ pmdp_splitting_flush : ok | __HAVE_ARCH_PMDP_SPLITTING_FLUSH # arch supports the pmdp_splitting_flush() VM API
vm/ pte_special : ok | __HAVE_ARCH_PTE_SPECIAL # arch supports the pte_special()/pte_mkspecial() VM APIs
vm/ THP : ok | HAVE_ARCH_TRANSPARENT_HUGEPAGE # arch supports transparent hugepages

See the first column, the subsystem prefixes - this organizes the
feature list in a natural way as well, per subsystem.

Seems to work out well.

Thanks,

Ingo