This document attempts to codify the intent around kernel self-protection
along with discussion of both existing and desired technologies, with
attention given to the rationale behind them, and the expectations of
their usage.

Signed-off-by: Kees Cook <keescook@chromium.org>
Reviewed-by: Randy Dunlap <rdunlap@infradead.org>
[jc: applied fixes suggested by Randy]
Reviewed-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Patch series from Jani Nikula:

> Jon, I was hoping we could consider nudging things forward a bit in the
> kernel-doc and docproc reStructuredText front already in 4.7. I know
> it's a bit close to the merge window, but this should not interfere with
> anything else, and some of it are just trivial cleanups that I've been
> carrying around locally.
>
> Obviously this doesn't actually add anything that uses them yet, but I
> think it would be helpful to have some common base in to ease
> collaboration.

As of commit ebd2c8f6 ("serial: kill off uart_info"), the
circular transmission buffer is part of struct uart_state instead of
struct uart_info. Make it clear this structure is pointed to from struct
uart_port.

Change 'circ' to 'circ_buf' to match the structure name while we're at
it.

Signed-off-by: Geert Uytterhoeven <geert+renesas@glider.be>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Stop referring to the mutex member of the tty_port struct as
'port->mutex', as 'port' is ambiguous, and usually refers to the
uart_port struct in this document.  Use 'tty_port->mutex' instead,
following the single existing use.

Signed-off-by: Geert Uytterhoeven <geert+renesas@glider.be>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Signed-off-by: Geert Uytterhoeven <geert+renesas@glider.be>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

The restriction of kmem setting is not there anymore because the
accounting is enabled by default even in the cgroup v1 - see
b313aeee ("mm: memcontrol: enable kmem accounting for all
cgroups in the legacy hierarchy").

Update docs accordingly.

Signed-off-by: Qiang Huang <h.huangqiang@huawei.com>
Acked-by: Michal Hocko <mhocko@suse.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Leave a hint to folks which file to edit instead.

Signed-off-by: Jani Nikula <jani.nikula@intel.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Expect reStructuredText input and have kernel-doc produce
reStructuredText output with the new --rst option. Also add --docbook
option for completeness. If no option is given, default to
reStructuredText if the input file has ".rst" extension, DocBook
otherwise.

Directives for reStructuredText use .. ! instead of just !, to make them
reStructuredText comments.

Signed-off-by: Jani Nikula <jani.nikula@intel.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Cleaner code. Also fixes a bug when F or P directives didn't in fact
have space.

Signed-off-by: Jani Nikula <jani.nikula@intel.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Helps follow-up work. No functional changes.

Signed-off-by: Jani Nikula <jani.nikula@intel.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Improves clarity. No functional changes.

Signed-off-by: Jani Nikula <jani.nikula@intel.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Improves clarity. No functional changes.

Signed-off-by: Jani Nikula <jani.nikula@intel.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

First, the headings for structs, enums and typedefs will be similar to
functions. Second, this provides a kind of namespace for cross
references. Third, and most importantly, the return and parameter types
from .. c:function:: definitions will automagically become cross
references to the documented types.

Signed-off-by: Jani Nikula <jani.nikula@intel.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

If given the -rst flag, output will now be in RestructuredText.  Various
glitches to be worked out yet.

In the end I decided not to use RST section headings within the kerneldoc
comments.  gpu.tmpl already has headings five levels deep; adding more is
not going to bring clarity.

This is really just Jani Nikula's asciidoc change with the serial numbers
filed off.  It's a hack job that doubtless needs a lot of cleaning up.

Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Jani Nikula <jani.nikula@intel.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Instead of having the kernel-doc usage in both comments and in output to
the user, merge them all to one here document. While at it, imrove the
text and make it pretty. Give shoemaker's children some shoes.

Signed-off-by: Jani Nikula <jani.nikula@intel.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

sysrq.c moved to drivers/tty in 2010; update the documentation to match.

Signed-off-by: René Nyffenegger <mail@renenyffenegger.ch>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

This fixes several spelling mistakes in the Documentation/ tree, which
are caught by checkpatch.pl's spell checking.

Signed-off-by: Kees Cook <keescook@chromium.org>
Reviewed-by: Paul E. McKenney <paulmck@linux.vnet.ibm.com>
Acked-by: Randy Dunlap <rdunlap@infradead.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

A small bug with the new autoksyms support showed that there are
two kernel modules in the Documentation directory that qualify
as samples, while all other samples are in the samples/ directory.

This patch was originally meant as a workaround for that bug, but
it has now been solved in a different way. However, I still think
it makes sense as a cleanup to consolidate all sample code in
one place.

Signed-off-by: Arnd Bergmann <arnd@arndb.de>
Acked-by: Hans Verkuil <hans.verkuil@cisco.com>
Acked-by: Mauro Carvalho Chehab <mchehab@osg.samsung.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

A small bug with the new autoksyms support showed that there are
two kernel modules in the Documentation directory that qualify
as samples, while all other samples are in the samples/ directory.

This patch was originally meant as a workaround for that bug, but
it has now been solved in a different way. However, I still think
it makes sense as a cleanup to consolidate all sample code in
one place.

Signed-off-by: Arnd Bergmann <arnd@arndb.de>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Signed-off-by: Eric Engestrom <eric@engestrom.ch>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Signed-off-by: Eric Engestrom <eric@engestrom.ch>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Signed-off-by: Eric Engestrom <eric@engestrom.ch>
[jc: fixed trailing whitespace errors]
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Signed-off-by: Eric Engestrom <eric@engestrom.ch>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Signed-off-by: Eric Engestrom <eric@engestrom.ch>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Signed-off-by: Eric Engestrom <eric@engestrom.ch>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Signed-off-by: Eric Engestrom <eric@engestrom.ch>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

devm_input_allocate_device() got introduced with commit 2be975c6
("Input: introduce managed input devices (add devres support)").
Add this function to the list of managed interfaces within the
devres documentation.

Signed-off-by: Alexander Kurz <akurz@blala.de>
Acked-by: Tejun Heo <tj@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

This is a update of Chinese documentation: Documentation/zh_CN/arm64/booting.txt

It is based on the modifications of Documentation/arm64/booting.txt in submission:
"a7f8de16".

Signed-off-by: Fu Wei <wefu@redhat.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

It has:
a tense correction(led->leads);
a typo(unevitably->inevitably);

Signed-off-by: Cao jin <caoj.fnst@cn.fujitsu.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Signed-off-by: Askar Safin <safinaskar@mail.ru>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Homepage url of git in HOWTO document was updated by commit
e234ebf7 ("Documentation/HOWTO: update
git home URL") but not applied to several translations.  This commit
updates them.

Signed-off-by: SeongJae Park <sj38.park@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Obsolete info about regression postings were removed by commit
5645a717 ("Documentation: HOWTO: remove
obsolete info about regression postings") but not applied to
translations.  This commit applies the change to translations.

Signed-off-by: SeongJae Park <sj38.park@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

break_ctl() is not called from any sort of atomic context, so there is no
problem with it sleeping.

Reported-by: Peter Hurley <peter@hurleysoftware.com>
Signed-off-by: Geert Uytterhoeven <geert+renesas@glider.be>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Document that .(un)throttle() are serialized with each other, and with
termios modification by the tty layer.

Reported-by: Peter Hurley <peter@hurleysoftware.com>
Signed-off-by: Geert Uytterhoeven <geert+renesas@glider.be>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Document that .throttle() and .unthrottle() are relevant only if
hardware assisted flow control is enabled.

Signed-off-by: Geert Uytterhoeven <geert+renesas@glider.be>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Commit 834392a7 ("serial: doc: Un-document non-existing
uart_write_console()") removed a paragraph about a helper function that
seemed to never exist.

Peter Hurley pointed out that the function does exist, but is called
differently. Re-add the paragraph, with the function name corrected.

Fixes: 834392a7 ("serial: doc: Un-document non-existing uart_write_console()")
Signed-off-by: Geert Uytterhoeven <geert+renesas@glider.be>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

The correct value 17 can be found later in this document
and in the kernel-page-flags.h header (KPF_HUGE). I noticed
this while implementing vmprobe's kpageflags support.

Signed-off-by: Jonathan Corbet <corbet@lwn.net>

It tries to "match" drivers for each interface (not "much").

Signed-off-by: Diego Herranz <diegoherranz@diegoherranz.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Signed-off-by: Diego Viola <diego.viola@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

The URL for "Writing Linux Device Drivers" hasn't been available in some
time. Updating the entry to Michael K. Johnson's "Linux Kernel Hackers'
Guide"

Signed-off-by: Luis de Bethencourt <luisbg@osg.samsung.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>