Documentation/printk-formats.txt is a candidate for conversion to
ReStructuredText format. Some effort has already been made to do this
conversion even thought the suffix is currently .txt

Changes required to complete conversion

 - Move printk-formats.txt to core-api/printk-formats.rst
 - Add entry to Documentation/core-api/index.rst
 - Remove entry from Documentation/00-INDEX
 - Fix minor grammatical errors.
 - Order heading adornments as suggested by rst docs.
 - Use 'Passed by reference' uniformly.
 - Update pointer documentation around %px specifier.
 - Fix erroneous double backticks (to commas).
 - Remove extraneous double backticks (suggested by Jonathan Corbet).
 - Simplify documentation for kobject.
Signed-off-by: NTobin C. Harding <me@tobin.cc>
[jc: downcased "kernel"]
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

This warning will happen for every normal kernel docs build and doesn't
carry any useful information.  Should anybody actually depend on this
"version" variable (which isn't clear to me), the "unknown version" value
will be clue enough.
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Add default value review to the submit checklist, referring to the
preference for "default n" from the previous patch added to
Documentation/kbuild/kconfig-language.txt.

Cc: "Yann E. MORIN" <yann.morin.1998@free.fr>
Cc: Masahiro Yamada <yamada.masahiro@socionext.com>
Cc: Michal Marek <mmarek@suse.com>
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: linux-kbuild@vger.kernel.org
Cc: linux-doc@vger.kernel.org
Signed-off-by: NDarren Hart (VMware) <dvhart@infradead.org>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Document the preference [1] for new CONFIG options to "default n" (or
not use default at all) in order to minimizes changes to the config,
especially to avoid "make oldconfig" growing unnecessarily from release
to release.

Document the exceptions where it is acceptable to use "default y/m" for
new CONFIG options.

1. https://lkml.org/lkml/2017/11/18/257

Cc: "Yann E. MORIN" <yann.morin.1998@free.fr>
Cc: Masahiro Yamada <yamada.masahiro@socionext.com>
Cc: Michal Marek <mmarek@suse.com>
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: linux-kbuild@vger.kernel.org
Cc: linux-doc@vger.kernel.org
Signed-off-by: NDarren Hart (VMware) <dvhart@infradead.org>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Update kernel-doc notation in lib/uuid.c and then add UUID/GUID
function interfaces to kernel-api.
Signed-off-by: NRandy Dunlap <rdunlap@infradead.org>
[jc: tweaked the uuid_is_valid() kerneldoc]
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Add sort() and list_sort() to the kernel API documentation in a
new "Sorting" section.
Signed-off-by: NRandy Dunlap <rdunlap@infradead.org>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Commit ac1f5912 ("kernel/watchdog.c: add sysctl knob
hardlockup_panic") added the hardlockup_panic sysctl, but did not add it
to Documentation/sysctl/kernel.txt.  Add this, and reference it from the
corresponding entry in Documentation/admin-guide/kernel-parameters.txt.
Signed-off-by: NScott Wood <swood@redhat.com>
Acked-by: NChristoph von Recklinghausen <crecklin@redhat.com>
Acked-by: NDon Zickus <dzickus@redhat.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Fix the spelling of 'enumerate' in this document.
Signed-off-by: NFabio Estevam <fabio.estevam@nxp.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

...just enough to say what the purpose is and to solicit more
contributions.
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

There is currently very little documentation in the kernel on maintainer
level tasks. In particular there are no documents on creating pull
requests to submit to Linus.

Quoting Greg Kroah-Hartman on LKML:

    Anyway, this actually came up at the kernel summit / maintainer
    meeting a few weeks ago, in that "how do I make a
    good pull request to Linus" is something we need to document.

    Here's what I do, and it seems to work well, so maybe we should turn
    it into the start of the documentation for how to do it.

(quote references: kernel summit, Europe 2017)

Create a new kernel documentation book 'how to be a maintainer'
(suggested by Jonathan Corbet). Add chapters on 'configuring git' and
'creating a pull request'.

Most of the content was written by Linus Torvalds and Greg Kroah-Hartman
in discussion on LKML. This is stated at the start of one of the
chapters and the original email thread is referenced in
'pull-requests.rst'.
Signed-off-by: NTobin C. Harding <me@tobin.cc>
Reviewed-by: NGreg Kroah-Hartman <gregkh@linuxfoundation.org>
Reviewed-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

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: NElena Reshetova <elena.reshetova@intel.com>
Signed-off-by: NKees Cook <keescook@chromium.org>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

This link is dead:

    $ curl -vI http://usb.cs.tum.edu/usbdoc
    * Could not resolve host: usb.cs.tum.edu
    * Closing connection 0
    curl: (6) Could not resolve host: usb.cs.tum.edu

I found the document somewhere else. Let's replace it.
Signed-off-by: NStefan Tatschner <stefan.tatschner@gmail.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Corrected a typo.
Signed-off-by: NMarco Donato Torsello <marcodonato.torsello@gmail.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

The URLs in mono.rst redirect to pages on www.mono-project.com, so let's
update them. I took the liberty to update the compilation instructions
to the Linux-specific version, because readers of the kernel
documentation will most likely use Linux.
Signed-off-by: NJonathan Neuschäfer <j.neuschaefer@gmx.net>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Document the recommended presence of a device-specific compatible value,
and list examples that are already in use or soon will be.
This will allow checkpatch to validate compatible values in DTS.

Update the example to match current best practices (generic node name,
specific compatible value first).
Signed-off-by: NGeert Uytterhoeven <geert+renesas@glider.be>
Signed-off-by: NRob Herring <robh@kernel.org>

Signed-off-by: NGeert Uytterhoeven <geert+renesas@glider.be>
Signed-off-by: NRob Herring <robh@kernel.org>

Improve the binding example by removing all the leading 0x to fix the
following dtc warnings:

Warning (unit_address_format): Node /XXX unit name should not have leading "0x"

Converted using the following command:

find Documentation/devicetree/bindings -name "*.txt" -exec sed -i -e 's/([^ ])\@0x([0-9a-f])/$1\@$2/g' {} +

This is a follow up to commit 48c926cdSigned-off-by: NMathieu Malaterre <malat@debian.org>
Signed-off-by: NRob Herring <robh@kernel.org>

Old kernels did not check for zero in the irq_state.flags field and old
QEMUs did not zero the flag/reserved fields when calling
KVM_S390_*_IRQ_STATE.  Let's add comments to prevent future uses of
these fields.
Signed-off-by: NChristian Borntraeger <borntraeger@de.ibm.com>
Reviewed-by: NThomas Huth <thuth@redhat.com>
Reviewed-by: NCornelia Huck <cohuck@redhat.com>
Reviewed-by: NDavid Hildenbrand <david@redhat.com>
Signed-off-by: NChristian Borntraeger <borntraeger@de.ibm.com>

The pci/htirq.c file was removed so remove it from the documentation
file also.

Error: Cannot open file ../drivers/pci/htirq.c
WARNING: kernel-doc '../scripts/kernel-doc -rst -enable-lineno -export ../drivers/pci/htirq.c' failed with return code 2

Fixes: fd2fa6c1 ("x86/PCI: Remove unused HyperTransport interrupt support")
Signed-off-by: NRandy Dunlap <rdunlap@infradead.org>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Despite commit 55020c80 ("of: Add vendor prefix for ON Semiconductor
Corp.") was made long ago, the latter commit 9f49f6dd ("gpio: pca953x:
add onsemi,pca9654 id") made use of another, undocumented vendor prefix.
Since such prefix doesn't seem to be used in any device trees, I think we
can just fix the "compatible" string in the driver and the bindings and be
done with that...

Fixes: 9f49f6dd ("gpio: pca953x: add onsemi,pca9654 id")
Signed-off-by: NSergei Shtylyov <sergei.shtylyov@cogentembedded.com>
Acked-by: NRob Herring <robh@kernel.org>
Signed-off-by: NLinus Walleij <linus.walleij@linaro.org>

In scsi_mid_low_api.txt a the scsi_device structure is mentioned
several times, but the leading 's' is uppercase (Scsi_device)
and should be lowercase (scsi_device).  Fixed by this commit.
Signed-off-by: NJohn Pittman <jpittman@redhat.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

In code blocks, :c:func:`...` annotations don't result in
cross-references. Instead, they are rendered verbatim.  Remove these
broken annotations, and mark function calls with parentheses() again.

Fixes: 76d40fae ("genericirq.rst: add cross-reference links and use monospaced fonts")
Signed-off-by: NJonathan Neuschäfer <j.neuschaefer@gmx.net>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

This patch fix following warning during 'make xmldocs'

Documentation/driver-api/dmaengine/client.rst:188:
WARNING: Title underline too short.

Further APIs:
------------
Signed-off-by: NMasanari Iida <standby24x7@gmail.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

With a nxp,se97 chip on an atmel sama5d31 board, the I2C adapter driver
is not always capable of avoiding the 25-35 ms timeout as specified by
the SMBUS protocol. This may cause silent corruption of the last bit of
any transfer, e.g. a one is read instead of a zero if the sensor chip
times out. This also affects the eeprom half of the nxp-se97 chip, where
this silent corruption was originally noticed. Other I2C adapters probably
suffer similar issues, e.g. bit-banging comes to mind as risky...

The SMBUS register in the nxp chip is not a standard Jedec register, but
it is not special to the nxp chips either, at least the atmel chips
have the same mechanism. Therefore, do not special case this on the
manufacturer, it is opt-in via the device property anyway.

Cc: stable@vger.kernel.org # 4.9+
Signed-off-by: NPeter Rosin <peda@axentia.se>
Acked-by: NRob Herring <robh@kernel.org>
Signed-off-by: NGuenter Roeck <linux@roeck-us.net>

Add to the media book the attachment kAPI for the DVB
frontend drivers that have already some kernel-doc markup.
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>

This reverts commit 0f6d24f8 ("mm/page-writeback.c: print a warning
if the vm dirtiness settings are illogical") because it causes false
positive warnings during OOM situations as noticed by Tetsuo Handa:

  Node 0 active_anon:3525940kB inactive_anon:8372kB active_file:216kB inactive_file:1872kB unevictable:0kB isolated(anon):0kB isolated(file):0kB mapped:2504kB dirty:52kB writeback:0kB shmem:8660kB shmem_thp: 0kB shmem_pmdmapped: 0kB anon_thp: 636928kB writeback_tmp:0kB unstable:0kB all_unreclaimable? yes
  Node 0 DMA free:14848kB min:284kB low:352kB high:420kB active_anon:992kB inactive_anon:0kB active_file:0kB inactive_file:0kB unevictable:0kB writepending:0kB present:15988kB managed:15904kB mlocked:0kB kernel_stack:0kB pagetables:24kB bounce:0kB free_pcp:0kB local_pcp:0kB free_cma:0kB
  lowmem_reserve[]: 0 2687 3645 3645
  Node 0 DMA32 free:53004kB min:49608kB low:62008kB high:74408kB active_anon:2712648kB inactive_anon:0kB active_file:0kB inactive_file:0kB unevictable:0kB writepending:0kB present:3129216kB managed:2773132kB mlocked:0kB kernel_stack:96kB pagetables:5096kB bounce:0kB free_pcp:0kB local_pcp:0kB free_cma:0kB
  lowmem_reserve[]: 0 0 958 958
  Node 0 Normal free:17140kB min:17684kB low:22104kB high:26524kB active_anon:812300kB inactive_anon:8372kB active_file:1228kB inactive_file:1868kB unevictable:0kB writepending:52kB present:1048576kB managed:981224kB mlocked:0kB kernel_stack:3520kB pagetables:8552kB bounce:0kB free_pcp:120kB local_pcp:120kB free_cma:0kB
  lowmem_reserve[]: 0 0 0 0
  [...]
  Out of memory: Kill process 8459 (a.out) score 999 or sacrifice child
  Killed process 8459 (a.out) total-vm:4180kB, anon-rss:88kB, file-rss:0kB, shmem-rss:0kB
  oom_reaper: reaped process 8459 (a.out), now anon-rss:0kB, file-rss:0kB, shmem-rss:0kB
  vm direct limit must be set greater than background limit.

The problem is that both thresh and bg_thresh will be 0 if
available_memory is less than 4 pages when evaluating
global_dirtyable_memory.

While this might be worked around the whole point of the warning is
dubious at best.  We do rely on admins to do sensible things when
changing tunable knobs.  Dirty memory writeback knobs are not any
special in that regards so revert the warning rather than adding more
hacks to work this around.

Debugged by Yafang Shao.

Link: http://lkml.kernel.org/r/20171127091939.tahb77nznytcxw55@dhcp22.suse.cz
Fixes: 0f6d24f8 ("mm/page-writeback.c: print a warning if the vm dirtiness settings are illogical")
Signed-off-by: NMichal Hocko <mhocko@suse.com>
Reported-by: NTetsuo Handa <penguin-kernel@I-love.SAKURA.ne.jp>
Cc: Yafang Shao <laoar.shao@gmail.com>
Cc: Jan Kara <jack@suse.cz>
Signed-off-by: NAndrew Morton <akpm@linux-foundation.org>
Signed-off-by: NLinus Torvalds <torvalds@linux-foundation.org>

printk specifier %p now hashes all addresses before printing. Sometimes
we need to see the actual unmodified address. This can be achieved using
%lx but then we face the risk that if in future we want to change the
way the Kernel handles printing of pointers we will have to grep through
the already existent 50 000 %lx call sites. Let's add specifier %px as a
clear, opt-in, way to print a pointer and maintain some level of
isolation from all the other hex integer output within the Kernel.

Add printk specifier %px to print the actual unmodified address.
Signed-off-by: NTobin C. Harding <me@tobin.cc>

Currently there exist approximately 14 000 places in the kernel where
addresses are being printed using an unadorned %p. This potentially
leaks sensitive information regarding the Kernel layout in memory. Many
of these calls are stale, instead of fixing every call lets hash the
address by default before printing. This will of course break some
users, forcing code printing needed addresses to be updated.

Code that _really_ needs the address will soon be able to use the new
printk specifier %px to print the address.

For what it's worth, usage of unadorned %p can be broken down as
follows (thanks to Joe Perches).

$ git grep -E '%p[^A-Za-z0-9]' | cut -f1 -d"/" | sort | uniq -c
   1084 arch
     20 block
     10 crypto
     32 Documentation
   8121 drivers
   1221 fs
    143 include
    101 kernel
     69 lib
    100 mm
   1510 net
     40 samples
      7 scripts
     11 security
    166 sound
    152 tools
      2 virt

Add function ptr_to_id() to map an address to a 32 bit unique
identifier. Hash any unadorned usage of specifier %p and any malformed
specifiers.
Signed-off-by: NTobin C. Harding <me@tobin.cc>

Current documentation indicates that %pK prints a leading '0x'. This is
not the case.

Correct documentation for printk specifier %pK.
Signed-off-by: NTobin C. Harding <me@tobin.cc>

All users of init_timer() have been updated. Remove the ancient interface.

Cc: Thomas Gleixner <tglx@linutronix.de>
Cc: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: NKees Cook <keescook@chromium.org>

Now that CPUs that implement Memory Protection Keys are publicly
available we can be a bit less oblique about where it is available.
Signed-off-by: NDave Hansen <dave.hansen@linux.intel.com>
Acked-by: NThomas Gleixner <tglx@linutronix.de>
Cc: Andy Lutomirski <luto@kernel.org>
Cc: Borislav Petkov <bp@alien8.de>
Cc: Brian Gerst <brgerst@gmail.com>
Cc: Denys Vlasenko <dvlasenk@redhat.com>
Cc: H. Peter Anvin <hpa@zytor.com>
Cc: Josh Poimboeuf <jpoimboe@redhat.com>
Cc: Linus Torvalds <torvalds@linux-foundation.org>
Cc: Peter Zijlstra <peterz@infradead.org>
Link: http://lkml.kernel.org/r/20171111001228.DC748A10@viggo.jf.intel.comSigned-off-by: NIngo Molnar <mingo@kernel.org>

Improve the bindings text by doing the following changes:

- Remove the i.MX53 reference, as the RTC on i.MX53 is a different hardware
- Add 'clocks' to the list of required properties
- Explain that the optional security violation irq is the second entry
- Use the real unit address and irq numbers for i.MX25
Signed-off-by: NFabio Estevam <fabio.estevam@nxp.com>
Acked-by: NJuergen Borleis <jbe@pengutronix.de>
Acked-by: NRob Herring <robh@kernel.org>
Signed-off-by: NAlexandre Belloni <alexandre.belloni@free-electrons.com>

This device's bindings are not trivial: Additional properties are
documented in in Documentation/devicetree/bindings/mfd/mc13xxx.txt.
Signed-off-by: NJonathan Neuschäfer <j.neuschaefer@gmx.net>
Reviewed-by: NFabio Estevam <fabio.estevam@nxp.com>
Signed-off-by: NRob Herring <robh@kernel.org>

Correctly the formatting of several additions to the profile= option
that have been added by using <profiletype> and listing the choices
for it.
Signed-off-by: NRandy Dunlap <rdunlap@infradead.org>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Drop CONFIG_VIDEO_400_HACK info completely.
Drop CONFIG_VIDEO_RETAIN and CONFIG_VIDEO_LOCAL completely.
Drop CONFIG_VIDEO_COMPACT and CONFIG_VIDEO_VESA info completely.
Drop CONFIG_VIDEO_SVGA info since it has been removed.
Drop chapter number & section number references since they are wrong.
Drop (bad) ftp URL for 800x600 Thinkpad XF86Config.

Rename CONFIG_VIDEO_GFX_HACK to VIDEO_GFX_HACK since it is not a
Kconfig symbol. And to match the source code.

Build options are controlled by the kernel kconfig utility.
Signed-off-by: NRandy Dunlap <rdunlap@infradead.org>
Acked-By: NMartin Mares <mj@ucw.cz>
Cc: "H. Peter Anvin" <hpa@zytor.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

This commit applies an upstream change, commit d92f842b
("memory-barriers.txt: Fix typo in pairing example") to the Korean
translation.
Signed-off-by: NSeongJae Park <sj38.park@gmail.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

This commit applies two upstream change, commit f1ab25a3
("memory-barriers: Replace uses of "transitive"") and commit 0902b1f4
("memory-barriers: Rework multicopy-atomicity section") to the Korean
translation.  Those two changes are applied with this signle commit
because the second change is improvement of the first one.
Signed-off-by: NSeongJae Park <sj38.park@gmail.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Sometimes a single patch is the result of multiple authors.  As git only
can have one "author" of a patch, it is still good to properly give
credit to the other developers of a commit.  To address this, document
the "Co-Developed-by:" tag which can be used to show other authors of
the patch.

Note, these other authors must also provide a Signed-off-by: tag as it
is their work that is being submitted here.
Reported-by: NThomas Gleixner <tglx@linutronix.de>
Signed-off-by: NGreg Kroah-Hartman <gregkh@linuxfoundation.org>
Reviewed-by: NThomas Gleixner <tglx@linutronix.de>
Acked-by: NBorislav Petkov <bp@suse.de>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

The switchtec_ntb driver has a couple requirements on the switchec's
hardware configuration so we add these notes to the documentation.
Signed-off-by: NLogan Gunthorpe <logang@deltatee.com>
Reviewed-by: NStephen Bates <sbates@raithlin.com>
Reviewed-by: NKurt Schwemmer <kurt.schwemmer@microsemi.com>
Acked-by: NAllen Hubbe <Allen.Hubbe@dell.com>
Signed-off-by: NJon Mason <jdmason@kudzu.us>

Most places use pwd and rely on $PATH lookup. Moving the remaining
absolute path /bin/pwd users over for consistency.

Also, a reason for doing /bin/pwd -> pwd instead of the other way around
is because I believe build systems should make little assumptions on
host filesystem layout. Case in point, we do this kind of patching
already in NixOS.

Ref. commit 028568d8
("kbuild: revert $(realpath ...) to $(shell cd ... && /bin/pwd)").
Signed-off-by: NBjørn Forsman <bjorn.forsman@gmail.com>
Signed-off-by: NMasahiro Yamada <yamada.masahiro@socionext.com>