[PATCH 0/3] Better organize the core-api manual

[PATCH 0/3] Better organize the core-api manual

[Jonathan Corbet]

This is a brief series trying to create some order in the core-api manual.
The first patch organizes the contents into subsections, hopefully
straightening things out a bit.  The other two then move a couple of
documents to more suitable homes.

Jonathan Corbet (3):
  docs: Organize core-api/index.rst
  docs: move gcc-plugins to the kbuild manual
  docs: move core-api/ioctl.rst to driver-api/

 Documentation/core-api/index.rst              | 93 ++++++++++++++-----
 Documentation/driver-api/index.rst            |  1 +
 .../{core-api => driver-api}/ioctl.rst        |  0
 .../{core-api => kbuild}/gcc-plugins.rst      |  0
 Documentation/kbuild/index.rst                |  1 +
 MAINTAINERS                                   |  2 +-
 scripts/gcc-plugins/Kconfig                   |  2 +-
 7 files changed, 75 insertions(+), 24 deletions(-)
 rename Documentation/{core-api => driver-api}/ioctl.rst (100%)
 rename Documentation/{core-api => kbuild}/gcc-plugins.rst (100%)

-- 
2.24.1

[PATCH 1/3] docs: Organize core-api/index.rst

[Jonathan Corbet]

The core-api manual has become a big, disorganized mess.  Try to bring a
small amount of order to it by organizing the documents into
subcategories.

Signed-off-by: Jonathan Corbet <corbet@lwn.net>
---
 Documentation/core-api/index.rst | 95 ++++++++++++++++++++++++--------
 1 file changed, 73 insertions(+), 22 deletions(-)

diff --git a/Documentation/core-api/index.rst b/Documentation/core-api/index.rst
index d02b26917931..b39dae276b57 100644
--- a/Documentation/core-api/index.rst
+++ b/Documentation/core-api/index.rst
@@ -8,42 +8,81 @@ This is the beginning of a manual for core kernel APIs.  The conversion
 Core utilities
 ==============
 
+This section has general and "core core" documentation.  The first is a
+massive grab-bag of kerneldoc info left over from the docbook days; it
+should really be broken up someday when somebody finds the energy to do
+it.
+
 .. toctree::
    :maxdepth: 1
 
    kernel-api
+   workqueue
+   printk-formats
+   symbol-namespaces
+
+Data structures and low-level utilities
+=======================================
+
+Library functionality that is used throughout the kernel.
+
+.. toctree::
+   :maxdepth: 1
+
    kobject
    assoc_array
+   xarray
+   idr
+   circular-buffers
+   generic-radix-tree
+   packing
+   timekeeping
+   errseq
+
+Concurrency primitives
+======================
+
+How Linux keeps everything from happening at the same time.  See
+:doc:`/locking/index` for more related documentation.
+
+.. toctree::
+   :maxdepth: 1
+
    atomic_ops
-   cachetlb
    refcount-vs-atomic
-   cpu_hotplug
-   idr
    local_ops
-   workqueue
+   padata
+   ../RCU/index
+
+Low-level hardware management
+=============================
+
+Cache management, managing CPU hotplug, etc.
+
+.. toctree::
+   :maxdepth: 1
+
+   cachetlb
+   cpu_hotplug
+   memory-hotplug
    genericirq
-   xarray
-   librs
-   genalloc
-   errseq
-   packing
-   printk-formats
-   circular-buffers
-   generic-radix-tree
+   protection-keys
+
+Memory management
+=================
+
+How to allocate and use memory in the kernel.  Note that there is a lot
+more memory-management documentation in :doc:`/vm/index`.
+
+.. toctree::
+   :maxdepth: 1
+
    memory-allocation
    mm-api
+   genalloc
    pin_user_pages
-   gfp_mask-from-fs-io
-   timekeeping
    boot-time-mm
-   memory-hotplug
-   protection-keys
-   ../RCU/index
-   gcc-plugins
-   symbol-namespaces
-   padata
-   ioctl
-
+   gfp_mask-from-fs-io
 
 Interfaces for kernel debugging
 ===============================
@@ -54,6 +93,18 @@ Interfaces for kernel debugging
    debug-objects
    tracepoint
 
+Everything else
+===============
+
+Documents that don't fit elsewhere or which have yet to be categorized.
+
+.. toctree::
+   :maxdepth: 1
+
+   librs
+   gcc-plugins
+   ioctl
+
 .. only:: subproject and html
 
    Indices
-- 
2.24.1

[PATCH 2/3] docs: move gcc-plugins to the kbuild manual

[Jonathan Corbet]

Information about GCC plugins is relevant to kernel building, so move this
document to the kbuild manual.

Signed-off-by: Jonathan Corbet <corbet@lwn.net>
---
 Documentation/core-api/index.rst                   | 1 -
 Documentation/{core-api => kbuild}/gcc-plugins.rst | 0
 Documentation/kbuild/index.rst                     | 1 +
 MAINTAINERS                                        | 2 +-
 scripts/gcc-plugins/Kconfig                        | 2 +-
 5 files changed, 3 insertions(+), 3 deletions(-)
 rename Documentation/{core-api => kbuild}/gcc-plugins.rst (100%)

diff --git a/Documentation/core-api/index.rst b/Documentation/core-api/index.rst
index b39dae276b57..9836a0ac09a3 100644
--- a/Documentation/core-api/index.rst
+++ b/Documentation/core-api/index.rst
@@ -102,7 +102,6 @@ Documents that don't fit elsewhere or which have yet to be categorized.
    :maxdepth: 1
 
    librs
-   gcc-plugins
    ioctl
 
 .. only:: subproject and html
diff --git a/Documentation/core-api/gcc-plugins.rst b/Documentation/kbuild/gcc-plugins.rst
similarity index 100%
rename from Documentation/core-api/gcc-plugins.rst
rename to Documentation/kbuild/gcc-plugins.rst
diff --git a/Documentation/kbuild/index.rst b/Documentation/kbuild/index.rst
index 0f144fad99a6..82daf2efcb73 100644
--- a/Documentation/kbuild/index.rst
+++ b/Documentation/kbuild/index.rst
@@ -19,6 +19,7 @@ Kernel Build System
 
     issues
     reproducible-builds
+    gcc-plugins
 
 .. only::  subproject and html
 
diff --git a/MAINTAINERS b/MAINTAINERS
index 38fe2f3f7b6f..f508f6c783d6 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -6934,7 +6934,7 @@ S:	Maintained
 F:	scripts/gcc-plugins/
 F:	scripts/gcc-plugin.sh
 F:	scripts/Makefile.gcc-plugins
-F:	Documentation/core-api/gcc-plugins.rst
+F:	Documentation/kbuild/gcc-plugins.rst
 
 GASKET DRIVER FRAMEWORK
 M:	Rob Springer <rspringer@google.com>
diff --git a/scripts/gcc-plugins/Kconfig b/scripts/gcc-plugins/Kconfig
index e3569543bdac..f8ca236d6165 100644
--- a/scripts/gcc-plugins/Kconfig
+++ b/scripts/gcc-plugins/Kconfig
@@ -23,7 +23,7 @@ menuconfig GCC_PLUGINS
 	  GCC plugins are loadable modules that provide extra features to the
 	  compiler. They are useful for runtime instrumentation and static analysis.
 
-	  See Documentation/core-api/gcc-plugins.rst for details.
+	  See Documentation/kbuild/gcc-plugins.rst for details.
 
 if GCC_PLUGINS
 
-- 
2.24.1

[PATCH 3/3] docs: move core-api/ioctl.rst to driver-api/

[Jonathan Corbet]

The ioctl() documentation belongs with the rest of the driver-oriented
info, so move it there.

Signed-off-by: Jonathan Corbet <corbet@lwn.net>
---
 Documentation/core-api/index.rst                 | 1 -
 Documentation/driver-api/index.rst               | 1 +
 Documentation/{core-api => driver-api}/ioctl.rst | 0
 3 files changed, 1 insertion(+), 1 deletion(-)
 rename Documentation/{core-api => driver-api}/ioctl.rst (100%)

diff --git a/Documentation/core-api/index.rst b/Documentation/core-api/index.rst
index 9836a0ac09a3..0897ad12c119 100644
--- a/Documentation/core-api/index.rst
+++ b/Documentation/core-api/index.rst
@@ -102,7 +102,6 @@ Documents that don't fit elsewhere or which have yet to be categorized.
    :maxdepth: 1
 
    librs
-   ioctl
 
 .. only:: subproject and html
 
diff --git a/Documentation/driver-api/index.rst b/Documentation/driver-api/index.rst
index ea3003b3c5e5..1d8c5599149b 100644
--- a/Documentation/driver-api/index.rst
+++ b/Documentation/driver-api/index.rst
@@ -17,6 +17,7 @@ available subsections can be seen below.
    driver-model/index
    basics
    infrastructure
+   ioctl
    early-userspace/index
    pm/index
    clk
diff --git a/Documentation/core-api/ioctl.rst b/Documentation/driver-api/ioctl.rst
similarity index 100%
rename from Documentation/core-api/ioctl.rst
rename to Documentation/driver-api/ioctl.rst
-- 
2.24.1

Re: [PATCH 0/3] Better organize the core-api manual

[Kees Cook]

On Mon, Mar 02, 2020 at 03:39:54PM -0700, Jonathan Corbet wrote:
> This is a brief series trying to create some order in the core-api manual.
> The first patch organizes the contents into subsections, hopefully
> straightening things out a bit.  The other two then move a couple of
> documents to more suitable homes.
> 
> Jonathan Corbet (3):
>   docs: Organize core-api/index.rst
>   docs: move gcc-plugins to the kbuild manual
>   docs: move core-api/ioctl.rst to driver-api/

This looks good; thanks! Random thought while looking through it: there's
stuff in the driver-api that seems like maybe it should move into the
core (e.g. Documentation/driver-api/basics.rst) but I'm not sure what
the line between "core" and "driver" is. I would think the "driver API"
docs should be driver-specific, in which case much of basics.rst should
be moved into "core". Regardless, this series seems like a good step in
the right direction.

Reviewed-by: Kees Cook <keescook@chromium.org>

-Kees

> 
>  Documentation/core-api/index.rst              | 93 ++++++++++++++-----
>  Documentation/driver-api/index.rst            |  1 +
>  .../{core-api => driver-api}/ioctl.rst        |  0
>  .../{core-api => kbuild}/gcc-plugins.rst      |  0
>  Documentation/kbuild/index.rst                |  1 +
>  MAINTAINERS                                   |  2 +-
>  scripts/gcc-plugins/Kconfig                   |  2 +-
>  7 files changed, 75 insertions(+), 24 deletions(-)
>  rename Documentation/{core-api => driver-api}/ioctl.rst (100%)
>  rename Documentation/{core-api => kbuild}/gcc-plugins.rst (100%)
> 
> -- 
> 2.24.1
> 

-- 
Kees Cook

Re: [PATCH 0/3] Better organize the core-api manual

[Jonathan Corbet]

On Mon, 2 Mar 2020 14:59:43 -0800
Kees Cook <keescook@chromium.org> wrote:

> Random thought while looking through it: there's
> stuff in the driver-api that seems like maybe it should move into the
> core (e.g. Documentation/driver-api/basics.rst) but I'm not sure what
> the line between "core" and "driver" is. I would think the "driver API"
> docs should be driver-specific, in which case much of basics.rst should
> be moved into "core".

Sigh...driver-api is, of course, an even bigger mess than core-api.  I
mean to delve into it and create some order there as well, when I get a
chance.

The original idea was that driver-api would contain stuff you need to know
if you're writing drivers but can ignore otherwise.  We can always rethink
that, of course.

Thanks,

jon

Re: [PATCH 2/3] docs: move gcc-plugins to the kbuild manual

[Masahiro Yamada]

On Tue, Mar 3, 2020 at 7:40 AM Jonathan Corbet <corbet@lwn.net> wrote:
>
> Information about GCC plugins is relevant to kernel building, so move this
> document to the kbuild manual.
>
> Signed-off-by: Jonathan Corbet <corbet@lwn.net>


Acked-by: Masahiro Yamada <masahiroy@kernel.org>


> ---
>  Documentation/core-api/index.rst                   | 1 -
>  Documentation/{core-api => kbuild}/gcc-plugins.rst | 0
>  Documentation/kbuild/index.rst                     | 1 +
>  MAINTAINERS                                        | 2 +-
>  scripts/gcc-plugins/Kconfig                        | 2 +-
>  5 files changed, 3 insertions(+), 3 deletions(-)
>  rename Documentation/{core-api => kbuild}/gcc-plugins.rst (100%)
>
> diff --git a/Documentation/core-api/index.rst b/Documentation/core-api/index.rst
> index b39dae276b57..9836a0ac09a3 100644
> --- a/Documentation/core-api/index.rst
> +++ b/Documentation/core-api/index.rst
> @@ -102,7 +102,6 @@ Documents that don't fit elsewhere or which have yet to be categorized.
>     :maxdepth: 1
>
>     librs
> -   gcc-plugins
>     ioctl
>
>  .. only:: subproject and html
> diff --git a/Documentation/core-api/gcc-plugins.rst b/Documentation/kbuild/gcc-plugins.rst
> similarity index 100%
> rename from Documentation/core-api/gcc-plugins.rst
> rename to Documentation/kbuild/gcc-plugins.rst
> diff --git a/Documentation/kbuild/index.rst b/Documentation/kbuild/index.rst
> index 0f144fad99a6..82daf2efcb73 100644
> --- a/Documentation/kbuild/index.rst
> +++ b/Documentation/kbuild/index.rst
> @@ -19,6 +19,7 @@ Kernel Build System
>
>      issues
>      reproducible-builds
> +    gcc-plugins
>
>  .. only::  subproject and html
>
> diff --git a/MAINTAINERS b/MAINTAINERS
> index 38fe2f3f7b6f..f508f6c783d6 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -6934,7 +6934,7 @@ S:        Maintained
>  F:     scripts/gcc-plugins/
>  F:     scripts/gcc-plugin.sh
>  F:     scripts/Makefile.gcc-plugins
> -F:     Documentation/core-api/gcc-plugins.rst
> +F:     Documentation/kbuild/gcc-plugins.rst
>
>  GASKET DRIVER FRAMEWORK
>  M:     Rob Springer <rspringer@google.com>
> diff --git a/scripts/gcc-plugins/Kconfig b/scripts/gcc-plugins/Kconfig
> index e3569543bdac..f8ca236d6165 100644
> --- a/scripts/gcc-plugins/Kconfig
> +++ b/scripts/gcc-plugins/Kconfig
> @@ -23,7 +23,7 @@ menuconfig GCC_PLUGINS
>           GCC plugins are loadable modules that provide extra features to the
>           compiler. They are useful for runtime instrumentation and static analysis.
>
> -         See Documentation/core-api/gcc-plugins.rst for details.
> +         See Documentation/kbuild/gcc-plugins.rst for details.
>
>  if GCC_PLUGINS
>
> --
> 2.24.1
>


-- 
Best Regards
Masahiro Yamada