For several years, and still ongoing, the kernel.h is being split
to smaller and narrow headers to avoid "including everything" approach
which is bad in many ways. Since that, documentation missed a few
required updates to align with that work. Do it here.
Note, language translations are left untouched and if anybody willing
to help, please provide path(es) based on the updated English variant.
Signed-off-by: Andy Shevchenko <andriy.shevchenko@linux.intel.com>
Reviewed-by: Randy Dunlap <rdunlap@infradead.org>
Reviewed-by: Mathieu Poirier <mathieu.poirier@linaro.org>
Tested-by: Randy Dunlap <rdunlap@infradead.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20251126214709.2322314-1-andriy.shevchenko@linux.intel.com>
Add the generated atomic headers to driver-api/basics.rst in order to
provide documentation for the Linux kernel's atomic operations.
At the same time, dtop the x86 atomic header, which provides kerneldoc
comments for some arch_atomic*_*() operations. The arch_atomic*_*()
operations are now purely an implenentation detail of the
raw_atomic*_*() ops, and outside of implementing the atomics, code
should use the raw_atomic*_*() forms.
[Mark: add atomic-{instrumented,long}.h, update commit message]
Signed-off-by: Paul E. McKenney <paulmck@kernel.org>
Signed-off-by: Mark Rutland <mark.rutland@arm.com>
Signed-off-by: Peter Zijlstra (Intel) <peterz@infradead.org>
Reviewed-by: Kees Cook <keescook@chromium.org>
Link: https://lore.kernel.org/r/20230605070124.3741859-27-mark.rutland@arm.com
pci_device_id is already documented at pci.rst:
./Documentation/driver-api/basics.rst: WARNING: Duplicate C declaration, also defined in 'PCI/pci'.
Declaration is 'pci_device_id'.
The kstrtol and kstrtoul are already at kernel-api:
./Documentation/driver-api/basics.rst: WARNING: Duplicate C declaration, also defined in 'core-api/kernel-api'.
Declaration is 'kstrtoul'.
./Documentation/driver-api/basics.rst: WARNING: Duplicate C declaration, also defined in 'core-api/kernel-api'.
Declaration is 'kstrtol'.
And the printk is already defined at printk-basics:
./Documentation/driver-api/basics.rst: WARNING: Duplicate C declaration, also defined in 'core-api/printk-basics'.
Declaration is 'printk'.
So, exclude those identifiers from basirs.rst.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Those are already defined at kernel-api.rst, as part of the
synchronization primitives chapter.
This solves several Sphinx 3 warnings, like:
.../Documentation/driver-api/basics.rst: WARNING: Duplicate C declaration, also defined in 'core-api/kernel-api'.
Declaration is 'rcu_idle_enter'.
.../Documentation/driver-api/basics.rst: WARNING: Duplicate C declaration, also defined in 'core-api/kernel-api'.
Declaration is 'rcu_idle_exit'.
.../Documentation/driver-api/basics.rst: WARNING: Duplicate C declaration, also defined in 'core-api/kernel-api'.
Declaration is 'rcu_is_watching'.
.../Documentation/driver-api/basics.rst: WARNING: Duplicate C declaration, also defined in 'core-api/kernel-api'.
Declaration is 'call_rcu'.
.../Documentation/driver-api/basics.rst: WARNING: Duplicate C declaration, also defined in 'core-api/kernel-api'.
Declaration is 'synchronize_rcu'.
...
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
As there's already a rst file with workqueue markups, containing
part of them, move the other definitions, in order to avoid
warnings with Sphinx.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Some functions from refcount_t API provide different
memory ordering guarantees that their atomic counterparts.
This adds a document outlining these differences (
Documentation/core-api/refcount-vs-atomic.rst) as well as
some other minor improvements.
Signed-off-by: Elena Reshetova <elena.reshetova@intel.com>
Signed-off-by: Kees Cook <keescook@chromium.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
...because there are none there, and I cannot figure out what would ever
have been of interest there. This eliminates this warning:
./kernel/sys.c:1: warning: no structured comments found
from the build.
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
The docs build complains:
./include/linux/init.h:1: warning: no structured comments found
The problem is that the comments in question were moved to module.h in
commit 0fd972a7d9 (module: relocate module_init from init.h to
module.h). Fix basics.rst to match.
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
That file went away with commit bd8cc5a062 (srcu: Remove Classic SRCU)
during the 4.13 merge window, leading to errors like:
Error: Cannot open file ./kernel/rcu/srcu.c
during the docs build.
Reported-by: Linus Torvalds <torvalds@linux-foundation.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
The structs there at device table are used by other documentation
at the Kernel. So, add it to the driver API.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
We don't need to keep it as a single large file anymore; split it up so
that it is easier to manage and the individual sections can be read
directly as plain files.
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
