Update the Cross-referencing section to explain how to create a
cross-reference to a document using relative paths and with no
additional syntax, by relying on automarkup.py.
Signed-off-by: Nícolas F. R. A. Prado <nfraprado@protonmail.com>
Link: https://lore.kernel.org/r/20210128010028.58541-3-nfraprado@protonmail.comSigned-off-by: Jonathan Corbet <corbet@lwn.net>

Previously, a cross-reference to another document could only be created
by writing the full path to the document starting from the
Documentation/ directory.

Extend this to also allow relative paths to be used. A relative path
would be just the path, like ../filename.rst, while the absolute path
still needs to start from Documentation, like Documentation/filename.rst.

As part of this change, the .rst extension is now required for both
types of paths, since not requiring it would cause the regex to be too
generic.
Suggested-by: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Nícolas F. R. A. Prado <nfraprado@protonmail.com>
Link: https://lore.kernel.org/r/20210128010028.58541-2-nfraprado@protonmail.com
[jc: Tweaked the regex to recognize .txt too]
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Signed-off-by: Flavio Suligoi <f.suligoi@asem.it>
Reviewed-by: Viresh Kumar <viresh.kumar@linaro.org>
Link: https://lore.kernel.org/r/20210129132035.16967-1-f.suligoi@asem.itSigned-off-by: Jonathan Corbet <corbet@lwn.net>

Since commit 9bba03d4 ("kconfig: remove 'kvmconfig' and 'xenconfig'
shorthands") kvm/xen config shortcuts are not available anymore. Update
the file to reflect how they should be used, with the full filename.
Signed-off-by: André Almeida <andrealmeid@collabora.com>
Link: https://lore.kernel.org/r/20210130014547.123006-2-andrealmeid@collabora.comSigned-off-by: Jonathan Corbet <corbet@lwn.net>

The documentation explains the need to create internal syscalls' helpers,
and that they should be called `kern_xyzzy()`. However, the comment at
include/linux/syscalls.h says that they should be named as
`ksys_xyzzy()`, and so are all the helpers declared bellow it. Change the
documentation to reflect this.

Fixes: 819671ff ("syscalls: define and explain goal to not call syscalls in the kernel")
Signed-off-by: André Almeida <andrealmeid@collabora.com>
Reviewed-by: Dominik Brodowski <linux@dominikbrodowski.net>
Link: https://lore.kernel.org/r/20210130014547.123006-1-andrealmeid@collabora.comSigned-off-by: Jonathan Corbet <corbet@lwn.net>

Commas are not how statements are terminated.
Always use semicolons and braces if necessary.
Signed-off-by: Joe Perches <joe@perches.com>
Link: https://lore.kernel.org/r/2a97b738bba335434461a5a918053a49c1fb6af4.1598331148.git.joe@perches.comSigned-off-by: Jonathan Corbet <corbet@lwn.net>

Update contents of /proc/loadavg: add 3 more fields.
Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
Cc: linux-doc@vger.kernel.org
Link: https://lore.kernel.org/r/fe55b139-bd03-4762-199b-83be873cf7dd@infradead.orgSigned-off-by: Jonathan Corbet <corbet@lwn.net>

Document that backtraces in commit messages should be trimmed down to
the useful information only.

This has been carved out from a tip subsystem handbook patchset by
Thomas Gleixner:

  https://lkml.kernel.org/r/20181107171010.421878737@linutronix.de

and incorporates follow-on comments.
Signed-off-by: Borislav Petkov <bp@suse.de>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

The kernel build system as a whole is dropping support for Python 2, so we
should do the same.  The effects are rather small, especially considering
that much of the deleted code was not doing anything under any version of
Python anyway.
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

As promised, drop support for some ancient sphinx releases, along with a
lot of the cruft that was required to make that support work.
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

ABS_PRESSURE and ABS_MT_PRESSURE on touch devices usually represent
contact size (as a finger flattens with higher pressure the contact size
increases) and userspace translates the kernel pressure value back into
contact size. For example, libinput has pressure thresholds when a touch is
considered a palm (palm == large contact area -> high pressure). The values
themselves are on an arbitrary scale and device-specific.

On pressurepads however, the pressure axis may represent the real physical
pressure. Pressurepads are touchpads without a hinge but an actual pressure
sensor underneath the device instead, for example the Lenovo Yoga 9i.

A high-enough pressure is converted to a button click by the firmware.
Microsoft does not require a pressure axis to be present, see [1], so as seen
from userspace most pressurepads are identical to clickpads - one button and
INPUT_PROP_BUTTONPAD set.

However, pressurepads that export the pressure axis break userspace because
that axis no longer represents contact size, resulting in inconsistent touch
tracking, e.g. [2]. Userspace needs to know when a pressure axis represents
real pressure and the best way to do so is to define what the resolution
field means. Userspace can then treat data with a pressure resolution as
true pressure.

This patch documents that the pressure resolution is in units/gram. This
allows for fine-grained detail and tops out at roughly ~2000t, enough for the
devices we're dealing with. Grams is not a scientific pressure unit but the
alternative is:
- Pascal: defined as force per area and area is unreliable on many devices and
  seems like the wrong option here anyway, especially for devices with a
  single pressure sensor only.
- Newton: defined as mass * distance/acceleration and for the purposes of a
  pressure axis, the distance is tricky to interpret and we get the data to
  calculate acceleration from event timestamps anyway.

For the purposes of touch devices and digitizers, grams seems the best choice
and the easiest to interpret.

Bonus side effect: we can use the existing hwdb infrastructure in userspace to
fix devices that advertise false pressure.

[1] https://docs.microsoft.com/en-us/windows-hardware/design/component-guidelines/windows-precision-touchpad-required-hid-top-level-collections#windows-precision-touchpad-input-reports
[2] https://gitlab.freedesktop.org/libinput/libinput/-/issues/562Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>
Acked-by: Benjamin Tissoires <benjamin.tissoires@redhat.com>
Link: https://lore.kernel.org/r/20210112230310.GA149342@jellySigned-off-by: Jonathan Corbet <corbet@lwn.net>

While DOC: section titles are not converted into RST headings
sections and are only decorated with strong emphasis markup,
nothing stops us from generating internal hyperlinks for them,
to mimic implicit hyperlinks to RST headings.
Signed-off-by: Michal Wajdeczko <michal.wajdeczko@intel.com>
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: Jani Nikula <jani.nikula@intel.com>
Cc: Chris Wilson <chris@chris-wilson.co.uk>
Link: https://lore.kernel.org/r/20210118110813.1490-1-michal.wajdeczko@intel.comSigned-off-by: Jonathan Corbet <corbet@lwn.net>

max_user_watches for epoll should say 1/25, rather than 1/32
Signed-off-by: Eric Curtin <ericcurtin17@gmail.com>
Link: https://lore.kernel.org/r/20210120132648.19046-1-ericcurtin17@gmail.comSigned-off-by: Jonathan Corbet <corbet@lwn.net>

There were two references to devicetree/booting-without-of.rst (which has
been removed) for DTB format information, and
devicetree/usage-model.rst pointed to
https://elinux.org/Device_Tree_Usage. Change all three of these references to
https://www.devicetree.org/specifications/.
Signed-off-by: Milan Lakhani <milan.lakhani@codethink.co.uk>
Link: https://lore.kernel.org/r/1611149511-4990-1-git-send-email-milan.lakhani@codethink.co.ukSigned-off-by: Jonathan Corbet <corbet@lwn.net>

This patch translates Documentation/iio/index.rst into Chinese.
Signed-off-by: Yanteng Si <siyanteng@loongson.cn>
Reviewed-by: Alex Shi <alex.shi@linux.alibaba.com>
Reviewed-by: Huacai Chen <chenhuacai@kernel.org>
Link: https://lore.kernel.org/r/20210121033302.558935-3-siyanteng@loongson.cnSigned-off-by: Jonathan Corbet <corbet@lwn.net>

This patch translates Documentation/iio/ep93xx_adc.rst into Chinese.
Signed-off-by: Yanteng Si <siyanteng@loongson.cn>
Reviewed-by: Alex Shi <alex.shi@linux.alibaba.com>
Reviewed-by: Huacai Chen <chenhuacai@kernel.org>
Link: https://lore.kernel.org/r/20210121033302.558935-2-siyanteng@loongson.cnSigned-off-by: Jonathan Corbet <corbet@lwn.net>

This patch translates Documentation/iio/iio_configfs.rst into Chinese.
Signed-off-by: Yanteng Si <siyanteng@loongson.cn>
Reviewed-by: Alex Shi <alex.shi@linux.alibaba.com>
Reviewed-by: Huacai Chen <chenhuacai@kernel.org>
Link: https://lore.kernel.org/r/20210121033302.558935-1-siyanteng@loongson.cnSigned-off-by: Jonathan Corbet <corbet@lwn.net>

The booting-without-of.rst file is no longer there. Link to
devicetree.org instead.

Fixes: 44184828 ("dt: Remove booting-without-of.rst")
Signed-off-by: Baruch Siach <baruch@tkos.co.il>
Cc: Rob Herring <robh@kernel.org>
Link: https://lore.kernel.org/r/7f07e544d9fc584242d496c2f54f9303d8de0724.1611558630.git.baruch@tkos.co.ilSigned-off-by: Jonathan Corbet <corbet@lwn.net>

Add qualifying build option legend [CMA] to kernel boot options
that requirce CMA support to be enabled for them to be usable.

Also capitalize 'CMA' when it is used as an acronym.
Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
Acked-by: Mike Kravetz <mike.kravetz@oracle.com>
Link: https://lore.kernel.org/r/20210125043202.22399-1-rdunlap@infradead.orgSigned-off-by: Jonathan Corbet <corbet@lwn.net>

On Marvell website is documentation accessible without need to register or
fill any other forms.
Signed-off-by: Pali Rohár <pali@kernel.org>
Link: https://lore.kernel.org/r/20210125141529.32357-1-pali@kernel.orgSigned-off-by: Jonathan Corbet <corbet@lwn.net>

Signed-off-by: Pali Rohár <pali@kernel.org>
Link: https://lore.kernel.org/r/20210125141341.32200-1-pali@kernel.orgSigned-off-by: Jonathan Corbet <corbet@lwn.net>

Signed-off-by: Pali Rohár <pali@kernel.org>
Reviewed-by: Andrew Lunn <andrew@lunn.ch>
Link: https://lore.kernel.org/r/20210121193418.22678-2-pali@kernel.orgSigned-off-by: Jonathan Corbet <corbet@lwn.net>

Fixes: dc7a12bd ("docs: arm: convert docs to ReST and rename to *.rst")
Signed-off-by: Pali Rohár <pali@kernel.org>
Reviewed-by: Andrew Lunn <andrew@lunn.ch>
Link: https://lore.kernel.org/r/20210121193418.22678-1-pali@kernel.orgSigned-off-by: Jonathan Corbet <corbet@lwn.net>

struct setup_data.len is the length of data field. In case of
SETUP_INDIRECT, it should be sizeof(setup_indirect).
Signed-off-by: Cao jin <jojing64@gmail.com>
Reviewed-by: Daniel Kiper <daniel.kiper@oracle.com>
Link: https://lore.kernel.org/r/20210127084911.63438-1-jojing64@gmail.comSigned-off-by: Jonathan Corbet <corbet@lwn.net>

Acked-by: Randy Dunlap <rdunlap@infradead.org>
Signed-off-by: Wolfram Sang <wsa+renesas@sang-engineering.com>
Link: https://lore.kernel.org/r/20210127104343.5647-1-wsa+renesas@sang-engineering.comSigned-off-by: Jonathan Corbet <corbet@lwn.net>

The kernel-doc markups on this file are weird: they don't
follow what's specified at:

	Documentation/doc-guide/kernel-doc.rst

In particular, markups should use this format:
        identifier - description

and not this:
	identifier(args)

The way the definitions are inside this file cause the
parser to completely miss the identifier name of each
function.

This prevents improving the script to do some needed validation
tests.

Address this part. Yet, furter changes are needed in order
for it to fully follow the specs.
Acked-by: Kees Cook <keescook@chromium.org>
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/8383758160fdb4fcbb2ac56beeb874ca6dffc6b9.1610610937.git.mchehab+huawei@kernel.orgSigned-off-by: Jonathan Corbet <corbet@lwn.net>

A function has a different name between their prototype
and its kernel-doc markup.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/2dc136ff6290d7c8919599d21bee244f31647c8c.1610610937.git.mchehab+huawei@kernel.orgSigned-off-by: Jonathan Corbet <corbet@lwn.net>

Some identifiers have different names between their prototypes
and the kernel-doc markup.
Acked-by: Mike Rapoport <rppt@linux.ibm.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/f3c65f61367993a607f9daf9dc1a3bdab1f0a040.1610610937.git.mchehab+huawei@kernel.orgSigned-off-by: Jonathan Corbet <corbet@lwn.net>

A function has a different name between their prototype
and its kernel-doc markup.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/1963266e84c6fb0154602f276b04887c85f80bd3.1610610937.git.mchehab+huawei@kernel.orgSigned-off-by: Jonathan Corbet <corbet@lwn.net>

A function has a different name between their prototype
and its kernel-doc markup.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/889cfb141a98ae06d5bc79b744786ec2e8f92d93.1610610937.git.mchehab+huawei@kernel.orgSigned-off-by: Jonathan Corbet <corbet@lwn.net>

There are some common comments marked, instead, with kernel-doc
notation, which won't work.

While here, rename an identifier, in order to match the
function prototype below kernel-doc markup.
Acked-by: Richard Gong <richard.gong@linux.intel.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/02a1eb47767e01e875d8840805b8b2d4f3c6bdee.1610610937.git.mchehab+huawei@kernel.orgSigned-off-by: Jonathan Corbet <corbet@lwn.net>

The documented struct is psz_head and not psz_buffer.
Reviewed-by: Kees Cook <keescook@chromium.org>
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/a67ca4d12c3ef277dadb9e0d0df8450158e637cc.1610610937.git.mchehab+huawei@kernel.orgSigned-off-by: Jonathan Corbet <corbet@lwn.net>

Two markups are at the wrong place. Kernel-doc only
support having the comment just before the identifier.

Also, some identifiers have different names between their
prototypes and the kernel-doc markup.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/96b1e1b388600ab092331f6c4e88ff8e8779ce6c.1610610937.git.mchehab+huawei@kernel.orgSigned-off-by: Jonathan Corbet <corbet@lwn.net>

Probaly this was due to a cut and paste issue.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/e23e64983788a51dd9099e2b0d881e1f64ecbc5b.1610610937.git.mchehab+huawei@kernel.orgSigned-off-by: Jonathan Corbet <corbet@lwn.net>

The kernel-doc markup inside share.c is actually for
__parport_register_driver. The actual goal seems to be
to document parport_register_driver().

So, fix the existing markup and add a new one.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/dc0778af8c466cc667409ead05876a5cfd3cbece.1610610937.git.mchehab+huawei@kernel.orgSigned-off-by: Jonathan Corbet <corbet@lwn.net>

Fix typos (punctuation, grammar, spelling) in afs.rst.
Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
Cc: David Howells <dhowells@redhat.com>
Cc: linux-afs@lists.infradead.org
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: linux-doc@vger.kernel.org
Link: https://lore.kernel.org/r/20210117213351.1075-1-rdunlap@infradead.orgSigned-off-by: Jonathan Corbet <corbet@lwn.net>

It's a unused tag with a incorrect big name but just for mips arch.
So remove it.
Signed-off-by: Alex Shi <alex.shi@linux.alibaba.com>
Cc: Yanteng Si <siyanteng@loongson.cn>
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: linux-doc@vger.kernel.org
Link: https://lore.kernel.org/r/20210121024113.16344-1-alex.shi@linux.alibaba.comSigned-off-by: Jonathan Corbet <corbet@lwn.net>

There are two EP9312, one of them should be 9315
Signed-off-by: Yanteng Si <siyanteng@loongson.cn>
Link: https://lore.kernel.org/r/20210119030320.2860870-1-siyanteng@loongson.cnSigned-off-by: Jonathan Corbet <corbet@lwn.net>

Commit adab66b7 ("Revert: "ring-buffer: Remove HAVE_64BIT_ALIGNED_ACCESS"")
added the config HAVE_64BIT_ALIGNED_ACCESS back into arch/Kconfig with this
revert. In the meantime, commit c9b54d6f ("docs: move other kAPI
documents to core-api") changed ./Documentation/unaligned-memory-access.txt
to ./Documentation/core-api/unaligned-memory-access.rst.

Fortunately, ./scripts/documentation-file-ref-check detects this and warns
about this broken reference.

Update the file reference in arch/Kconfig.

Fixes: adab66b7 ("Revert: "ring-buffer: Remove HAVE_64BIT_ALIGNED_ACCESS"")
Signed-off-by: Lukas Bulwahn <lukas.bulwahn@gmail.com>
Link: https://lore.kernel.org/r/20210119095326.13896-1-lukas.bulwahn@gmail.comSigned-off-by: Jonathan Corbet <corbet@lwn.net>

Due to an extra empty line between the option and its description
it is rendered not like in other places.

Remove the empty lines to fix.
Signed-off-by: Kir Kolyshkin <kolyshkin@gmail.com>
Acked-by: Tejun Heo <tj@kernel.org>
Link: https://lore.kernel.org/r/20210120001824.385168-11-kolyshkin@gmail.comSigned-off-by: Jonathan Corbet <corbet@lwn.net>