* [PATCH 1/3] docs: Organize core-api/index.rst
2020-03-02 22:39 [PATCH 0/3] Better organize the core-api manual Jonathan Corbet
@ 2020-03-02 22:39 ` Jonathan Corbet
2020-03-02 22:39 ` [PATCH 2/3] docs: move gcc-plugins to the kbuild manual Jonathan Corbet
` (2 subsequent siblings)
3 siblings, 0 replies; 7+ messages in thread
From: Jonathan Corbet @ 2020-03-02 22:39 UTC (permalink / raw)
To: linux-kernel
Cc: Kees Cook, Masahiro Yamada, Michal Marek, linux-doc, 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
^ permalink raw reply related [flat|nested] 7+ messages in thread* [PATCH 2/3] docs: move gcc-plugins to the kbuild manual
2020-03-02 22:39 [PATCH 0/3] Better organize the core-api manual Jonathan Corbet
2020-03-02 22:39 ` [PATCH 1/3] docs: Organize core-api/index.rst Jonathan Corbet
@ 2020-03-02 22:39 ` Jonathan Corbet
2020-03-05 2:12 ` Masahiro Yamada
2020-03-02 22:39 ` [PATCH 3/3] docs: move core-api/ioctl.rst to driver-api/ Jonathan Corbet
2020-03-02 22:59 ` [PATCH 0/3] Better organize the core-api manual Kees Cook
3 siblings, 1 reply; 7+ messages in thread
From: Jonathan Corbet @ 2020-03-02 22:39 UTC (permalink / raw)
To: linux-kernel
Cc: Kees Cook, Masahiro Yamada, Michal Marek, linux-doc, 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
^ permalink raw reply related [flat|nested] 7+ messages in thread* Re: [PATCH 2/3] docs: move gcc-plugins to the kbuild manual
2020-03-02 22:39 ` [PATCH 2/3] docs: move gcc-plugins to the kbuild manual Jonathan Corbet
@ 2020-03-05 2:12 ` Masahiro Yamada
0 siblings, 0 replies; 7+ messages in thread
From: Masahiro Yamada @ 2020-03-05 2:12 UTC (permalink / raw)
To: Jonathan Corbet
Cc: Linux Kernel Mailing List, Kees Cook, Michal Marek,
open list:DOCUMENTATION
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
^ permalink raw reply [flat|nested] 7+ messages in thread
* [PATCH 3/3] docs: move core-api/ioctl.rst to driver-api/
2020-03-02 22:39 [PATCH 0/3] Better organize the core-api manual Jonathan Corbet
2020-03-02 22:39 ` [PATCH 1/3] docs: Organize core-api/index.rst Jonathan Corbet
2020-03-02 22:39 ` [PATCH 2/3] docs: move gcc-plugins to the kbuild manual Jonathan Corbet
@ 2020-03-02 22:39 ` Jonathan Corbet
2020-03-02 22:59 ` [PATCH 0/3] Better organize the core-api manual Kees Cook
3 siblings, 0 replies; 7+ messages in thread
From: Jonathan Corbet @ 2020-03-02 22:39 UTC (permalink / raw)
To: linux-kernel
Cc: Kees Cook, Masahiro Yamada, Michal Marek, linux-doc, 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
^ permalink raw reply related [flat|nested] 7+ messages in thread* Re: [PATCH 0/3] Better organize the core-api manual
2020-03-02 22:39 [PATCH 0/3] Better organize the core-api manual Jonathan Corbet
` (2 preceding siblings ...)
2020-03-02 22:39 ` [PATCH 3/3] docs: move core-api/ioctl.rst to driver-api/ Jonathan Corbet
@ 2020-03-02 22:59 ` Kees Cook
2020-03-02 23:23 ` Jonathan Corbet
3 siblings, 1 reply; 7+ messages in thread
From: Kees Cook @ 2020-03-02 22:59 UTC (permalink / raw)
To: Jonathan Corbet; +Cc: linux-kernel, Masahiro Yamada, Michal Marek, linux-doc
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
^ permalink raw reply [flat|nested] 7+ messages in thread* Re: [PATCH 0/3] Better organize the core-api manual
2020-03-02 22:59 ` [PATCH 0/3] Better organize the core-api manual Kees Cook
@ 2020-03-02 23:23 ` Jonathan Corbet
0 siblings, 0 replies; 7+ messages in thread
From: Jonathan Corbet @ 2020-03-02 23:23 UTC (permalink / raw)
To: Kees Cook; +Cc: linux-kernel, Masahiro Yamada, Michal Marek, linux-doc
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
^ permalink raw reply [flat|nested] 7+ messages in thread