Make declaration type determination more robust.
When scripts/kernel-doc is deciding if some kernel-doc notation
contains an enum, a struct, a union, a typedef, or a function,
it does a pattern match on the beginning of the string, looking
for a match with one of "struct", "union", "enum", or "typedef",
and otherwise defaults to a function declaration type.
However, if a function or a function-like macro has a name that
begins with "struct" (e.g., struct_size()), then kernel-doc
incorrectly decides that this is a struct declaration.
Fix this by looking for the declaration type keywords having an
ending word boundary (\b), so that "struct_size" will not match
a struct declaration.
I compared lots of html before/after output from core-api, driver-api,
and networking. There were no differences in any of the files that
I checked.
Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
Acked-by: Jani Nikula <jani.nikula@intel.com>
Tested-by: Kees Cook <keescook@chromium.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
There was a typo in adding-syscalls.rst that could mislead developers
to add a C filename in a makefile instead of an object filename.
This error, while not keeping developers from contributing could slow
the development process down by introducing build errors.
Signed-off-by: Guillaume Dore <corwin@poussif.eu>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Remove "manual" table of contents and leave only the ReST tag so that
Sphinx will take care of TOC generation.
Signed-off-by: Mike Rapoport <rppt@linux.vnet.ibm.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
When converting from text to rst, the kobjects section and its sole
subsection about device tree nodes were coalesced into a single section,
yielding an inconsistent result.
Remove all references to kobjects, as
1. Device tree object pointers are not compatible to kobject pointers
(the former may embed the latter, though), and
2. there are no printk formats defined for kobject types.
Update the vsprintf() source code comments to match the above.
Fixes: b3ed23213e ("doc: convert printk-formats.txt to rst")
Signed-off-by: Geert Uytterhoeven <geert+renesas@glider.be>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
The existing wording implies that the use of spin_unlock whilst irqs are
disabled might trigger a reschedule. However the preemptible() test in
preempt_schedule will prevent a reschedule if irqs are disabled.
Lets improve the clarity of this wording to change the example from
spin_unlock to cond_resched() and cond_resched_lock() as these are
functions that will trigger a reschedule if the preempt count is 0 without
testing that irqs are disabled.
Also remove the 'Last Updated' line as this is not up to date and better
tracked via GIT.
Signed-off-by: Andrew Murray <andrew.murray@arm.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Commit ef548c551e ("dm flakey: introduce "error_writes" feature")
added the ability to dm flakey to error out writes in contrast to
silently dropping it with 'drop_writes'. Unfortunately this feature
is not currently documented and one has to be either familiar with the
source code of dm flakey or check out xfstests sources to know of
this parameter. So document it.
Signed-off-by: Nikolay Borisov <nborisov@suse.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
This patch fixes a couple of punctuation nits which can make the document
more correct and readable.
Also missing "()" are added to some function references for consistency.
Signed-off-by: John Garry <john.garry@huawei.com>
Acked-by: Randy Dunlap <rdunlap@infradead.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Add the full text of the ISC license to the kernel tree. It was copied
directly from:
https://spdx.org/licenses/ISC.html
With the mention of "ISC" in the warranty disclaimer replaced with
"THE AUTHOR" as done in the ISC license headers used in the ath10k and
brcmfmac wifi drivers.
Cc: Kalle Valo <kvalo@codeaurora.org>
Signed-off-by: Hans de Goede <hdegoede@redhat.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
The only reason we have the CDDL-1.0 license text around is for some
dual-licensed files from virtualbox. New code should not use this license.
Add a note about this and change the example tag to be dual-licensed.
Signed-off-by: Hans de Goede <hdegoede@redhat.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
to allow additions of new documentation about memory hotplug under the same
roof.
Signed-off-by: Mike Rapoport <rppt@linux.vnet.ibm.com>
Reviewed-by: David Hildenbrand <david@redhat.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
My eyesight is not in good shape, which means that I have difficulty
reading the online Linux documentation. Specifically, body text is
oddly small compared to list items and the contrast of various text
elements is too low for me to be able to see easily.
Therefore, alter the HTML theme overrides to make the text larger and
increase the contrast for better visibility, and trust the typeface
choices of the reader's browser.
For the PDF output, increase the text size, use a sans-serif typeface
for sans-serif text, and use a serif typeface for "roman" serif text.
Signed-off-by: Darrick J. Wong <darrick.wong@oracle.com>
Acked-by: Dave Chinner <dchinner@redhat.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Current phrasing is ambiguous since it's unclear if attaching to a
children through PTRACE_TRACEME requires CAP_SYS_PTRACE. Rephrase the
sentence to make that clear.
Signed-off-by: Yves-Alexis Perez <corsac@corsac.net>
Acked-by: Kees Cook <keescook@chromium.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
The memory hotplug notifier description is about kernel internals rather
than admin/user visible API. Place it appropriately.
Signed-off-by: Mike Rapoport <rppt@linux.vnet.ibm.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
The memory hotplug description in Documentation/memory-hotplug.txt is
already formatted as ReST and can be easily added to admin-guide/mm
section.
While on it, slightly update formatting to make it consistent with the
doc-guide.
Signed-off-by: Mike Rapoport <rppt@linux.vnet.ibm.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
"FEFEK" was incorrectly used as acronym for "File Encryption Key
Encryption Key". This replaces all occurences with "FEKEK".
Signed-off-by: Felix Eckhofer <felix@eckhofer.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Some documentation files received recent changes and are
pointing to wrong places.
Those references can easily fixed with the help of a
script:
$ ./scripts/documentation-file-ref-check --fix
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Reviewed-by: Jan Kara <jack@suse.cz>
Reviewed-by: Darrick J. Wong <darrick.wong@oracle.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Document that the default for "iommu.passthrough" is now configurable.
Fixes: 58d1131777 ("iommu: Add config option to set passthrough as default")
Signed-off-by: Robin Murphy <robin.murphy@arm.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
There were several rounds of the patches that enabled "functions" directive
with no parameters in kerneldoc.py to allow including all the kernel-doc
comments except the DOC: sections.
Yet, the boot-time-mm.rst sneaked in with the older version of that
directive and was not updated. Update it now.
Signed-off-by: Mike Rapoport <rppt@linux.vnet.ibm.com>
Tested-by: Randy Dunlap <rdunlap@infradead.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
This is a respin with a wider audience (all that get_maintainer returned)
and I know this spams a *lot* of people. Not sure what would be the correct
way, so my apologies for ruining your inbox.
The 00-INDEX files are supposed to give a summary of all files present
in a directory, but these files are horribly out of date and their
usefulness is brought into question. Often a simple "ls" would reveal
the same information as the filenames are generally quite descriptive as
a short introduction to what the file covers (it should not surprise
anyone what Documentation/sched/sched-design-CFS.txt covers)
A few years back it was mentioned that these files were no longer really
needed, and they have since then grown further out of date, so perhaps
it is time to just throw them out.
A short status yields the following _outdated_ 00-INDEX files, first
counter is files listed in 00-INDEX but missing in the directory, last
is files present but not listed in 00-INDEX.
List of outdated 00-INDEX:
Documentation: (4/10)
Documentation/sysctl: (0/1)
Documentation/timers: (1/0)
Documentation/blockdev: (3/1)
Documentation/w1/slaves: (0/1)
Documentation/locking: (0/1)
Documentation/devicetree: (0/5)
Documentation/power: (1/1)
Documentation/powerpc: (0/5)
Documentation/arm: (1/0)
Documentation/x86: (0/9)
Documentation/x86/x86_64: (1/1)
Documentation/scsi: (4/4)
Documentation/filesystems: (2/9)
Documentation/filesystems/nfs: (0/2)
Documentation/cgroup-v1: (0/2)
Documentation/kbuild: (0/4)
Documentation/spi: (1/0)
Documentation/virtual/kvm: (1/0)
Documentation/scheduler: (0/2)
Documentation/fb: (0/1)
Documentation/block: (0/1)
Documentation/networking: (6/37)
Documentation/vm: (1/3)
Then there are 364 subdirectories in Documentation/ with several files that
are missing 00-INDEX alltogether (and another 120 with a single file and no
00-INDEX).
I don't really have an opinion to whether or not we /should/ have 00-INDEX,
but the above 00-INDEX should either be removed or be kept up to date. If
we should keep the files, I can try to keep them updated, but I rather not
if we just want to delete them anyway.
As a starting point, remove all index-files and references to 00-INDEX and
see where the discussion is going.
Signed-off-by: Henrik Austad <henrik@austad.us>
Acked-by: "Paul E. McKenney" <paulmck@linux.vnet.ibm.com>
Just-do-it-by: Steven Rostedt <rostedt@goodmis.org>
Reviewed-by: Jens Axboe <axboe@kernel.dk>
Acked-by: Paul Moore <paul@paul-moore.com>
Acked-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Acked-by: Mark Brown <broonie@kernel.org>
Acked-by: Mike Rapoport <rppt@linux.vnet.ibm.com>
Cc: [Almost everybody else]
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
I'll handle these myself but thanks for providing the fallback!
Signed-off-by: Wolfram Sang <wsa@the-dreams.de>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Helps reading and hopefully avoids duplicates. Also, consistently add
the trailing '/' to make clear those are directories.
Signed-off-by: Wolfram Sang <wsa@the-dreams.de>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
The dtb= parameter is no longer the primary mechanism for providing a
devicetree to the kernel. Now either firmware or the boot selector (ex.
Grub) should provide the devicetree and dtb= should only be used for
debug or when using firmware that doesn't understand DT.
Update the EFI stub documentation to reflect the current usage.
Signed-off-by: Grant Likely <grant.likely@arm.com>
Reviewed-by: Alexander Graf <agraf@suse.de>
Acked-by: Leif Lindholm <leif.lindholm@linaro.org>
Acked-by: Olof Johansson <olof@lixom.net>
Acked-by: Ard Biesheuvel <ard.biesheuvel@linaro.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
* Fix install instruction by adding `./autogen` command
before `./configure`.
* Add link to a more detailed installation instruction.
* Add link to SmPL grammar documentation.
* Add single space after ',' to slightly improve readability.
Signed-off-by: Himanshu Jha <himanshujha199640@gmail.com>
Acked-by: Julia Lawall <julia.lawall@lip6.fr>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
The documentation and TOCs are organized in a manner of a tree. Adding a TOC to
the root, which refers to a file which is located in a subfolder forms a
grid. Those TOCs are a bit confusing and thats why we get additional error
messages while building partial documentation::
$ make SPHINXDIRS=process htmldocs
...
checking consistency... Documentation/process/license-rules.rst: \
WARNING: document isn't included in any toctree
To fix it, the *root-license-TOC* is replaced by a reference and the
'license-roles.txt' is added to the Documentation/process/index.rst TOC.
BTW: there was an old licences remark in Documentation/process/howto.rst which
is also updated, mentioning SPDX and pointing to the license-rules.rst
Signed-off-by: Markus Heiser <markus.heiser@darmarit.de>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Config fragment files should be placed in
tools/testing/selftests/<testdir>/config
Signed-off-by: Anders Roxell <anders.roxell@linaro.org>
Acked-by: Shuah Khan (Samsung OSG) <shuah@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
This space missing caused the colour scheme in vim editor messy
after that line. Add it to fix.
Signed-off-by: Baoquan He <bhe@redhat.com>
[ jc: fixed alignment after the changed line ]
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Pull timer update from Thomas Gleixner:
"New defines for the compat time* types so they can be shared between
32bit and 64bit builds. Not used yet, but merging them now allows the
actual conversions to be merged through different maintainer trees
without dependencies
We still have compat interfaces for 32bit on 64bit even with the new
2038 safe timespec/val variants because pointer size is different. And
for the old style timespec/val interfaces we need yet another 'compat'
interface for both 32bit native and 32bit on 64bit"
* 'timers-urgent-for-linus' of git://git.kernel.org/pub/scm/linux/kernel/git/tip/tip:
y2038: Provide aliases for compat helpers
Pull IDA updates from Matthew Wilcox:
"A better IDA API:
id = ida_alloc(ida, GFP_xxx);
ida_free(ida, id);
rather than the cumbersome ida_simple_get(), ida_simple_remove().
The new IDA API is similar to ida_simple_get() but better named. The
internal restructuring of the IDA code removes the bitmap
preallocation nonsense.
I hope the net -200 lines of code is convincing"
* 'ida-4.19' of git://git.infradead.org/users/willy/linux-dax: (29 commits)
ida: Change ida_get_new_above to return the id
ida: Remove old API
test_ida: check_ida_destroy and check_ida_alloc
test_ida: Convert check_ida_conv to new API
test_ida: Move ida_check_max
test_ida: Move ida_check_leaf
idr-test: Convert ida_check_nomem to new API
ida: Start new test_ida module
target/iscsi: Allocate session IDs from an IDA
iscsi target: fix session creation failure handling
drm/vmwgfx: Convert to new IDA API
dmaengine: Convert to new IDA API
ppc: Convert vas ID allocation to new IDA API
media: Convert entity ID allocation to new IDA API
ppc: Convert mmu context allocation to new IDA API
Convert net_namespace to new IDA API
cb710: Convert to new IDA API
rsxx: Convert to new IDA API
osd: Convert to new IDA API
sd: Convert to new IDA API
...
Pull gcc plugin fix from Kees Cook:
"Lift gcc test into Kconfig. This is for better behavior when the
kernel is built with Clang, reported by Stefan Agner"
* tag 'gcc-plugins-v4.19-rc1-fix' of git://git.kernel.org/pub/scm/linux/kernel/git/kees/linux:
gcc-plugins: Disable when building under Clang
Pull perf updates from Thomas Gleixner:
"Kernel:
- Improve kallsyms coverage
- Add x86 entry trampolines to kcore
- Fix ARM SPE handling
- Correct PPC event post processing
Tools:
- Make the build system more robust
- Small fixes and enhancements all over the place
- Update kernel ABI header copies
- Preparatory work for converting libtraceevnt to a shared library
- License cleanups"
* 'perf-urgent-for-linus' of git://git.kernel.org/pub/scm/linux/kernel/git/tip/tip: (100 commits)
tools arch: Update arch/x86/lib/memcpy_64.S copy used in 'perf bench mem memcpy'
tools arch x86: Update tools's copy of cpufeatures.h
perf python: Fix pyrf_evlist__read_on_cpu() interface
perf mmap: Store real cpu number in 'struct perf_mmap'
perf tools: Remove ext from struct kmod_path
perf tools: Add gzip_is_compressed function
perf tools: Add lzma_is_compressed function
perf tools: Add is_compressed callback to compressions array
perf tools: Move the temp file processing into decompress_kmodule
perf tools: Use compression id in decompress_kmodule()
perf tools: Store compression id into struct dso
perf tools: Add compression id into 'struct kmod_path'
perf tools: Make is_supported_compression() static
perf tools: Make decompress_to_file() function static
perf tools: Get rid of dso__needs_decompress() call in __open_dso()
perf tools: Get rid of dso__needs_decompress() call in symbol__disassemble()
perf tools: Get rid of dso__needs_decompress() call in read_object_code()
tools lib traceevent: Change to SPDX License format
perf llvm: Allow passing options to llc in addition to clang
perf parser: Improve error message for PMU address filters
...
Pull x86 fixes from Thomas Gleixner:
- Correct the L1TF fallout on 32bit and the off by one in the 'too much
RAM for protection' calculation.
- Add a helpful kernel message for the 'too much RAM' case
- Unbreak the VDSO in case that the compiler desides to use indirect
jumps/calls and emits retpolines which cannot be resolved because the
kernel uses its own thunks, which does not work for the VDSO. Make it
use the builtin thunks.
- Re-export start_thread() which was unexported when the 32/64bit
implementation was unified. start_thread() is required by modular
binfmt handlers.
- Trivial cleanups
* 'x86-urgent-for-linus' of git://git.kernel.org/pub/scm/linux/kernel/git/tip/tip:
x86/speculation/l1tf: Suggest what to do on systems with too much RAM
x86/speculation/l1tf: Fix off-by-one error when warning that system has too much RAM
x86/kvm/vmx: Remove duplicate l1d flush definitions
x86/speculation/l1tf: Fix overflow in l1tf_pfn_limit() on 32bit
x86/process: Re-export start_thread()
x86/mce: Add notifier_block forward declaration
x86/vdso: Fix vDSO build if a retpoline is emitted
Pull irq update from Thomas Gleixner:
"A small set of updats/fixes for the irq subsystem:
- Allow GICv3 interrupts to be configured as wake-up sources to
enable wakeup from suspend
- Make the error handling of the STM32 irqchip init function work
- A set of small cleanups and improvements"
* 'irq-urgent-for-linus' of git://git.kernel.org/pub/scm/linux/kernel/git/tip/tip:
irqchip/gic-v3: Allow interrupt to be configured as wake-up sources
irqchip/tango: Set irq handler and data in one go
dt-bindings: irqchip: renesas-irqc: Document r8a774a1 support
irqchip/s3c24xx: Remove unneeded comparison of unsigned long to 0
irqchip/stm32: Fix init error handling
irqchip/bcm7038-l1: Hide cpu offline callback when building for !SMP
Pull licking update from Thomas Gleixner:
"Mark the switch cases which fall through to the next case with the
proper comment so the fallthrough compiler checks can be enabled"
* 'locking-urgent-for-linus' of git://git.kernel.org/pub/scm/linux/kernel/git/tip/tip:
futex: Mark expected switch fall-throughs
Pull libnvdimm memory-failure update from Dave Jiang:
"As it stands, memory_failure() gets thoroughly confused by dev_pagemap
backed mappings. The recovery code has specific enabling for several
possible page states and needs new enabling to handle poison in dax
mappings.
In order to support reliable reverse mapping of user space addresses:
1/ Add new locking in the memory_failure() rmap path to prevent races
that would typically be handled by the page lock.
2/ Since dev_pagemap pages are hidden from the page allocator and the
"compound page" accounting machinery, add a mechanism to determine
the size of the mapping that encompasses a given poisoned pfn.
3/ Given pmem errors can be repaired, change the speculatively
accessed poison protection, mce_unmap_kpfn(), to be reversible and
otherwise allow ongoing access from the kernel.
A side effect of this enabling is that MADV_HWPOISON becomes usable
for dax mappings, however the primary motivation is to allow the
system to survive userspace consumption of hardware-poison via dax.
Specifically the current behavior is:
mce: Uncorrected hardware memory error in user-access at af34214200
{1}[Hardware Error]: It has been corrected by h/w and requires no further action
mce: [Hardware Error]: Machine check events logged
{1}[Hardware Error]: event severity: corrected
Memory failure: 0xaf34214: reserved kernel page still referenced by 1 users
[..]
Memory failure: 0xaf34214: recovery action for reserved kernel page: Failed
mce: Memory error not recovered
<reboot>
...and with these changes:
Injecting memory failure for pfn 0x20cb00 at process virtual address 0x7f763dd00000
Memory failure: 0x20cb00: Killing dax-pmd:5421 due to hardware memory corruption
Memory failure: 0x20cb00: recovery action for dax page: Recovered
Given all the cross dependencies I propose taking this through
nvdimm.git with acks from Naoya, x86/core, x86/RAS, and of course dax
folks"
* tag 'libnvdimm-for-4.19_dax-memory-failure' of gitolite.kernel.org:pub/scm/linux/kernel/git/nvdimm/nvdimm:
libnvdimm, pmem: Restore page attributes when clearing errors
x86/memory_failure: Introduce {set, clear}_mce_nospec()
x86/mm/pat: Prepare {reserve, free}_memtype() for "decoy" addresses
mm, memory_failure: Teach memory_failure() about dev_pagemap pages
filesystem-dax: Introduce dax_lock_mapping_entry()
mm, memory_failure: Collect mapping size in collect_procs()
mm, madvise_inject_error: Let memory_failure() optionally take a page reference
mm, dev_pagemap: Do not clear ->mapping on final put
mm, madvise_inject_error: Disable MADV_SOFT_OFFLINE for ZONE_DEVICE pages
filesystem-dax: Set page->index
device-dax: Set page->index
device-dax: Enable page_mapping()
device-dax: Convert to vmf_insert_mixed and vm_fault_t
