Commit Graph

60 Commits

Author SHA1 Message Date
Linus Torvalds
d75ae5bdf2 Printk changes for 4.18
-----BEGIN PGP SIGNATURE-----
 Version: GnuPG v2
 
 iQIbBAABAgAGBQJbFnd0AAoJEFKgDEdIgJTyuWgP+O/+kRbXR5WTphJ8e9+CqHp4
 LF6AJXTuiA0fPJ5TcTNtZ84AVvmoNcTXnaM3Ou8HfR2qER8Gqu4WbdcfqhU2/KUq
 L4x4YlW+DZPOhy7chFx/yTgdSWc8vBwSG80DLSQhjnOJBY4SwBaVSSCYi/CSiAvr
 I18zt03mSXUe9RADrT3W0rbryIbyICvZjMbKkUlSm7ZTQv482FaU2Jezp86qDYLB
 FWc7QOLKzXRjFTg5IQ91mTtqnM2gnHwqOzGFR+jILn8BQwVe5dYp42sCSne34kBD
 pHz5GosIIYRH3Eik7pNzOhN4nsncLfPwwQQx/YH1KmKteNPTPJZO01pEwMaurc3w
 LaoTD7LNDyZCkzxJF/kKOiW4ys1cMf5jyoiV9Sou7PIVPcxuR1ToMXQvHSplZPG1
 UyDwW41XVmluYdC2O4ybRQWMu3nmrQKCjjGkCmizK3xMWNs4u/5Y4kS3mi7Zwk3y
 X1wlm2BW7RPzVl7WWlNergR2UHNq2zgToOWzFfSqXtMukYbmei+mXYIIe6nKa2GH
 ji/d/Sr/RIAgUs46sBzRBLK9ZCqybPxSvnfNZx8WodLU1dLYT3yY1vGZbGPEMB2w
 puS7ctPT9dfnBxi/MOegXlTyKTOJkCB3o/bsWkIdSvRI45qbYE1aQN8IMmDQ20sv
 X8A3LnDQZvUfKEULrU0=
 =hB2y
 -----END PGP SIGNATURE-----

Merge tag 'printk-for-4.18' of git://git.kernel.org/pub/scm/linux/kernel/git/pmladek/printk

Pull printk updates from Petr Mladek:

 - Help userspace log daemons to catch up with a flood of messages. They
   will get woken after each message even if the console is far behind
   and handled by another process.

 - Flush printk safe buffers safely even when panic() happens in the
   normal context.

 - Fix possible va_list reuse when race happened in printk_safe().

 - Remove %pCr printf format to prevent sleeping in the atomic context.

 - Misc vsprintf code cleanup.

* tag 'printk-for-4.18' of git://git.kernel.org/pub/scm/linux/kernel/git/pmladek/printk:
  printk: drop in_nmi check from printk_safe_flush_on_panic()
  lib/vsprintf: Remove atomic-unsafe support for %pCr
  serial: sh-sci: Stop using printk format %pCr
  thermal: bcm2835: Stop using printk format %pCr
  clk: renesas: cpg-mssr: Stop using printk format %pCr
  printk: fix possible reuse of va_list variable
  printk: wake up klogd in vprintk_emit
  vsprintf: Tweak pF/pf comment
  lib/vsprintf: Mark expected switch fall-through
  lib/vsprintf: Replace space with '_' before crng is ready
  lib/vsprintf: Deduplicate pointer_string()
  lib/vsprintf: Move pointer_string() upper
  lib/vsprintf: Make flag_spec global
  lib/vsprintf: Make strspec global
  lib/vsprintf: Make dec_spec global
  lib/test_printf: Mark big constant with UL
2018-06-06 16:04:55 -07:00
Geert Uytterhoeven
666902e42f lib/vsprintf: Remove atomic-unsafe support for %pCr
"%pCr" formats the current rate of a clock, and calls clk_get_rate().
The latter obtains a mutex, hence it must not be called from atomic
context.

Remove support for this rarely-used format, as vsprintf() (and e.g.
printk()) must be callable from any context.

Any remaining out-of-tree users will start seeing the clock's name
printed instead of its rate.

Reported-by: Jia-Ju Bai <baijiaju1990@gmail.com>
Fixes: 900cca2944 ("lib/vsprintf: add %pC{,n,r} format specifiers for clocks")
Link: http://lkml.kernel.org/r/1527845302-12159-5-git-send-email-geert+renesas@glider.be
To: Jia-Ju Bai <baijiaju1990@gmail.com>
To: Jonathan Corbet <corbet@lwn.net>
To: Michael Turquette <mturquette@baylibre.com>
To: Stephen Boyd <sboyd@kernel.org>
To: Zhang Rui <rui.zhang@intel.com>
To: Eduardo Valentin <edubezval@gmail.com>
To: Eric Anholt <eric@anholt.net>
To: Stefan Wahren <stefan.wahren@i2se.com>
To: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Cc: Sergey Senozhatsky <sergey.senozhatsky.work@gmail.com>
Cc: Petr Mladek <pmladek@suse.com>
Cc: Linus Torvalds <torvalds@linux-foundation.org>
Cc: Steven Rostedt <rostedt@goodmis.org>
Cc: linux-doc@vger.kernel.org
Cc: linux-clk@vger.kernel.org
Cc: linux-pm@vger.kernel.org
Cc: linux-serial@vger.kernel.org
Cc: linux-arm-kernel@lists.infradead.org
Cc: linux-renesas-soc@vger.kernel.org
Cc: linux-kernel@vger.kernel.org
Cc: Geert Uytterhoeven <geert+renesas@glider.be>
Cc: stable@vger.kernel.org # 4.1+
Signed-off-by: Geert Uytterhoeven <geert+renesas@glider.be>
Signed-off-by: Petr Mladek <pmladek@suse.com>
2018-06-05 09:43:39 +02:00
Linus Torvalds
92400b8c8b Merge branch 'locking-core-for-linus' of git://git.kernel.org/pub/scm/linux/kernel/git/tip/tip
Pull locking updates from Ingo Molnar:

 - Lots of tidying up changes all across the map for Linux's formal
   memory/locking-model tooling, by Alan Stern, Akira Yokosawa, Andrea
   Parri, Paul E. McKenney and SeongJae Park.

   Notable changes beyond an overall update in the tooling itself is the
   tidying up of spin_is_locked() semantics, which spills over into the
   kernel proper as well.

 - qspinlock improvements: the locking algorithm now guarantees forward
   progress whereas the previous implementation in mainline could starve
   threads indefinitely in cmpxchg() loops. Also other related cleanups
   to the qspinlock code (Will Deacon)

 - misc smaller improvements, cleanups and fixes all across the locking
   subsystem

* 'locking-core-for-linus' of git://git.kernel.org/pub/scm/linux/kernel/git/tip/tip: (51 commits)
  locking/rwsem: Simplify the is-owner-spinnable checks
  tools/memory-model: Add reference for 'Simplifying ARM concurrency'
  tools/memory-model: Update ASPLOS information
  MAINTAINERS, tools/memory-model: Update e-mail address for Andrea Parri
  tools/memory-model: Fix coding style in 'lock.cat'
  tools/memory-model: Remove out-of-date comments and code from lock.cat
  tools/memory-model: Improve mixed-access checking in lock.cat
  tools/memory-model: Improve comments in lock.cat
  tools/memory-model: Remove duplicated code from lock.cat
  tools/memory-model: Flag "cumulativity" and "propagation" tests
  tools/memory-model: Add model support for spin_is_locked()
  tools/memory-model: Add scripts to test memory model
  tools/memory-model: Fix coding style in 'linux-kernel.def'
  tools/memory-model: Model 'smp_store_mb()'
  tools/memory-order: Update the cheat-sheet to show that smp_mb__after_atomic() orders later RMW operations
  tools/memory-order: Improve key for SELF and SV
  tools/memory-model: Fix cheat sheet typo
  tools/memory-model: Update required version of herdtools7
  tools/memory-model: Redefine rb in terms of rcu-fence
  tools/memory-model: Rename link and rcu-path to rcu-link and rb
  ...
2018-06-04 16:40:11 -07:00
Jonathan Corbet
d43f2c98f6 docs: Use the kerneldoc comments for memalloc_no*()
Now that we have kerneldoc comments for
memalloc_no{fs,io}_{save_restore}(), go ahead and pull them into the docs.

Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2018-05-29 06:45:55 -06:00
Michal Hocko
46ca359955 doc: document scope NOFS, NOIO APIs
Although the api is documented in the source code Ted has pointed out
that there is no mention in the core-api Documentation and there are
people looking there to find answers how to use a specific API.

Requested-by: "Theodore Y. Ts'o" <tytso@mit.edu>
Reviewed-by: Dave Chinner <dchinner@redhat.com>
Signed-off-by: Michal Hocko <mhocko@suse.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2018-05-29 06:45:42 -06:00
SeongJae Park
173af2613e locking/Documentation: Use warning RST directive
Use the proper RST directive, pointed out by a build warning.

Signed-off-by: SeongJae Park <sj38.park@gmail.com>
Signed-off-by: Paul E. McKenney <paulmck@linux.vnet.ibm.com>
Cc: Andrew Morton <akpm@linux-foundation.org>
Cc: Linus Torvalds <torvalds@linux-foundation.org>
Cc: Peter Zijlstra <peterz@infradead.org>
Cc: Thomas Gleixner <tglx@linutronix.de>
Cc: Will Deacon <will.deacon@arm.com>
Cc: akiyks@gmail.com
Cc: boqun.feng@gmail.com
Cc: dhowells@redhat.com
Cc: j.alglave@ucl.ac.uk
Cc: linux-arch@vger.kernel.org
Cc: luc.maranget@inria.fr
Cc: npiggin@gmail.com
Cc: parri.andrea@gmail.com
Cc: stern@rowland.harvard.edu
Link: http://lkml.kernel.org/r/1526338533-6044-8-git-send-email-paulmck@linux.vnet.ibm.com
Signed-off-by: Ingo Molnar <mingo@kernel.org>
2018-05-15 08:11:15 +02:00
SeongJae Park
fc7bdc9024 locking/Documentation: Fix incorrect example code
- Remove a stale line of code
 - Fix the condition of the READ_ONCE() example

Signed-off-by: SeongJae Park <sj38.park@gmail.com>
Signed-off-by: Paul E. McKenney <paulmck@linux.vnet.ibm.com>
Acked-by: Alan Stern <stern@rowland.harvard.edu>
Cc: Andrew Morton <akpm@linux-foundation.org>
Cc: Linus Torvalds <torvalds@linux-foundation.org>
Cc: Peter Zijlstra <peterz@infradead.org>
Cc: Thomas Gleixner <tglx@linutronix.de>
Cc: Will Deacon <will.deacon@arm.com>
Cc: akiyks@gmail.com
Cc: boqun.feng@gmail.com
Cc: dhowells@redhat.com
Cc: j.alglave@ucl.ac.uk
Cc: linux-arch@vger.kernel.org
Cc: luc.maranget@inria.fr
Cc: npiggin@gmail.com
Cc: parri.andrea@gmail.com
Link: http://lkml.kernel.org/r/1526338533-6044-7-git-send-email-paulmck@linux.vnet.ibm.com
Signed-off-by: Ingo Molnar <mingo@kernel.org>
2018-05-15 08:11:14 +02:00
Andrea Parri
a9251553c2 Documentation: refcount-vs-atomic: Update reference to LKMM doc.
The LKMM project has moved to 'tools/memory-model/'.

Signed-off-by: Andrea Parri <andrea.parri@amarulasolutions.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2018-05-08 14:52:39 -06:00
Mauro Carvalho Chehab
d8a121e3d5 docs: core-api: add circular-buffers documentation
The circular-buffers.txt is already in ReST format. So, move it to the
core-api guide, where it belongs.

Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2018-05-08 10:07:06 -06:00
Mauro Carvalho Chehab
de0f51e4b1 docs: core-api: add cachetlb documentation
The cachetlb.txt is already in ReST format. So, move it to the
core-api guide, where it belongs.

Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2018-05-08 10:02:34 -06:00
Randy Dunlap
eacc670fa4 documentation: core-api: rearrange a few kernel-api chapters and sections
Rearrange some kernel-api chapters and sections to group them
together better.

- move Bit Operations from Basic C Library Functions to Basic
  Kernel Library Functions (now adjacent to Bitmap Operations since
  they are not typical C library functions)

- move Sorting from Math Functions to Basic Kernel Library Functions
  since sort functions are more Basic than Math Functions

- move Text Searching from Math Functions to Basic Kernel Library
  Functions (keep Sorting and Searching close to each other)

- combine CRC and Math functions together into the (newly named)
  CRC and Math Functions chapter

Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
Acked-by: Matthew Wilcox <mawilcox@microsoft.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2018-04-27 17:15:47 -06:00
Randy Dunlap
5968a70d7a textsearch: fix kernel-doc warnings and add kernel-api section
Make lib/textsearch.c usable as kernel-doc.
Add textsearch() function family to kernel-api documentation.
Fix kernel-doc warnings in <linux/textsearch.h>:
  ../include/linux/textsearch.h:65: warning: Incorrect use of kernel-doc format:
	* get_next_block - fetch next block of data
  ../include/linux/textsearch.h:82: warning: Incorrect use of kernel-doc format:
	* finish - finalize/clean a series of get_next_block() calls

Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
Signed-off-by: David S. Miller <davem@davemloft.net>
2018-04-16 18:53:13 -04:00
Joel Stanley
156383b190 Documentation: Mention why %p prints ptrval
When debugging recent kernels, people will see '(ptrval)' but there
isn't much information as to what that means. Briefly describe why it's
there.

Signed-off-by: Joel Stanley <joel@jms.id.au>
Acked-by: Tobin C. Harding <me@tobin.cc>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2018-03-23 12:42:18 -06:00
Matthew Wilcox
ac665d9423 idr: Add documentation
Move the idr kernel-doc to its own idr.rst file and add a few
paragraphs about how to use it.  Also add some more kernel-doc.

Signed-off-by: Matthew Wilcox <mawilcox@microsoft.com>
2018-02-06 16:41:29 -05:00
Linus Torvalds
ab486bc9a5 Merge branch 'for-linus' of git://git.kernel.org/pub/scm/linux/kernel/git/pmladek/printk
Pull printk updates from Petr Mladek:

 - Add a console_msg_format command line option:

     The value "default" keeps the old "[time stamp] text\n" format. The
     value "syslog" allows to see the syslog-like "<log
     level>[timestamp] text" format.

     This feature was requested by people doing regression tests, for
     example, 0day robot. They want to have both filtered and full logs
     at hands.

 - Reduce the risk of softlockup:

     Pass the console owner in a busy loop.

     This is a new approach to the old problem. It was first proposed by
     Steven Rostedt on Kernel Summit 2017. It marks a context in which
     the console_lock owner calls console drivers and could not sleep.
     On the other side, printk() callers could detect this state and use
     a busy wait instead of a simple console_trylock(). Finally, the
     console_lock owner checks if there is a busy waiter at the end of
     the special context and eventually passes the console_lock to the
     waiter.

     The hand-off works surprisingly well and helps in many situations.
     Well, there is still a possibility of the softlockup, for example,
     when the flood of messages stops and the last owner still has too
     much to flush.

     There is increasing number of people having problems with
     printk-related softlockups. We might eventually need to get better
     solution. Anyway, this looks like a good start and promising
     direction.

 - Do not allow to schedule in console_unlock() called from printk():

     This reverts an older controversial commit. The reschedule helped
     to avoid softlockups. But it also slowed down the console output.
     This patch is obsoleted by the new console waiter logic described
     above. In fact, the reschedule made the hand-off less effective.

 - Deprecate "%pf" and "%pF" format specifier:

     It was needed on ia64, ppc64 and parisc64 to dereference function
     descriptors and show the real function address. It is done
     transparently by "%ps" and "pS" format specifier now.

     Sergey Senozhatsky found that all the function descriptors were in
     a special elf section and could be easily detected.

 - Remove printk_symbol() API:

     It has been obsoleted by "%pS" format specifier, and this change
     helped to remove few continuous lines and a less intuitive old API.

 - Remove redundant memsets:

     Sergey removed unnecessary memset when processing printk.devkmsg
     command line option.

* 'for-linus' of git://git.kernel.org/pub/scm/linux/kernel/git/pmladek/printk: (27 commits)
  printk: drop redundant devkmsg_log_str memsets
  printk: Never set console_may_schedule in console_trylock()
  printk: Hide console waiter logic into helpers
  printk: Add console owner and waiter logic to load balance console writes
  kallsyms: remove print_symbol() function
  checkpatch: add pF/pf deprecation warning
  symbol lookup: introduce dereference_symbol_descriptor()
  parisc64: Add .opd based function descriptor dereference
  powerpc64: Add .opd based function descriptor dereference
  ia64: Add .opd based function descriptor dereference
  sections: split dereference_function_descriptor()
  openrisc: Fix conflicting types for _exext and _stext
  lib: do not use print_symbol()
  irq debug: do not use print_symbol()
  sysfs: do not use print_symbol()
  drivers: do not use print_symbol()
  x86: do not use print_symbol()
  unicore32: do not use print_symbol()
  sh: do not use print_symbol()
  mn10300: do not use print_symbol()
  ...
2018-02-01 13:36:15 -08:00
Matthew Wilcox
14ebc28e07 errseq: Add to documentation tree
- Move errseq.rst into core-api
 - Add errseq to the core-api index
 - Promote the header to a more prominent header type, otherwise we get three
   entries in the table of contents.
 - Reformat the table to look nicer and be a little more proportional in
   terms of horizontal width per bit (the SF bit is still disproportionately
   large, but there's no way to fix that).
 - Include errseq kernel-doc in the errseq.rst
 - Neaten some kernel-doc markup

Signed-off-by: Matthew Wilcox <mawilcox@microsoft.com>
Reviewed-by: Jeff Layton <jlayton@redhat.com>
Reviewed-by: Randy Dunlap <rdunlap@infradead.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2018-01-01 12:40:27 -07:00
Tobin C. Harding
b3ed23213e doc: convert printk-formats.txt to rst
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: Tobin C. Harding <me@tobin.cc>
[jc: downcased "kernel"]
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-12-21 13:39:07 -07:00
Randy Dunlap
d063623b6a Documentation: add UUID/GUID to kernel-api
Update kernel-doc notation in lib/uuid.c and then add UUID/GUID
function interfaces to kernel-api.

Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
[jc: tweaked the uuid_is_valid() kerneldoc]
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-12-11 15:03:08 -07:00
Randy Dunlap
3abaa5ccd9 Documentation: add Sorting section to kernel-api
Add sort() and list_sort() to the kernel API documentation in a
new "Sorting" section.

Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-12-11 14:59:31 -07:00
Elena Reshetova
b6e859f6cd docs: refcount_t documentation
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>
2017-12-11 14:37:11 -07:00
Jonathan Neuschäfer
0f83aaa3c0 genericirq.rst: Remove :c:func:... in code blocks
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: 76d40fae13 ("genericirq.rst: add cross-reference links and use monospaced fonts")
Signed-off-by: Jonathan Neuschäfer <j.neuschaefer@gmx.net>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-12-02 08:41:46 -07:00
Kees Cook
7eeb6b893b timer: Remove init_timer() interface
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: Kees Cook <keescook@chromium.org>
2017-11-21 15:57:09 -08:00
Linus Torvalds
7832681b36 A relatively calm cycle for the docs tree again.
- The old driver statement has been added to the kernel docs.
 
   - We have a couple of new helper scripts.  find-unused-docs.sh from Sayli
     Karnic will point out kerneldoc comments that are not actually used in
     the documentation.  Jani Nikula's documentation-file-ref-check finds
     references to non-existing files.
 
   - A new ftrace document from Steve Rostedt.
 
   - Vinod Koul converted the dmaengine docs to RST
 
 Beyond that, it's mostly simple fixes.
 -----BEGIN PGP SIGNATURE-----
 
 iQIcBAABAgAGBQJaCK37AAoJEI3ONVYwIuV63nwQALeqzVwGqqTwiyRyMqgEwMQM
 je/6IurEwTHtyfwtW/mztCfNid1CLTiYZg7RET3/zlHjcUI/9VlV2dbBksGFgoQo
 muHGqhwTJjXYREwjK3FkzrGckRsVZKJgdzmZYgukCCY6Ir7IffwJKYaLOCZN1S/l
 4nBHQpt2nITo0WhdmZjaNRKOQxMA8nN5yGpOIl0neGE6ywIUMgauCCCHhxnOPVWg
 ant1HliS8WR8Tizqt9wQgLCvs5lvklsBFibZPO9LBTPG2Zy3HIO9kb+npUAh2MTl
 j0Wg39zzOFvVVErqErqUIwIuQ9IrfltHrEHYYoruTvDBXBiMKIcwApF+DS+H3WSp
 TnDu3Qif4llM5SZsZGvcjawXNnbck+7SYOe9cyqpylV3SWMWrEX1tbUv6zVuVk+7
 fencYBvEZgkJmWbjDeO/Z4S50STxRTzIxFwZgLft7g/RiHo9HvlubjjwQTqBFjxA
 fVkolN7h69MGkrD8TF19eapyujqSXaNYH0pFYo87JNOjLgYmezUHyvHd8YeZJL31
 Ll0h10HqSNVzJsjFolBMgrC3CcVjsEXdBufu0yVk45sAg9ZiMYOCpwa6Rtp+tfxa
 uIBf1LKzfWSa0ocKx7+sMJt0B/CXwU3AMtsbYGyDhFhR2r3cp1NWBHf5nisz9etD
 2Md9RDFAMLELZurewB9Q
 =H6ud
 -----END PGP SIGNATURE-----

Merge tag 'docs-4.15' of git://git.lwn.net/linux

Pull documentation updates from Jonathan Corbet:
 "A relatively calm cycle for the docs tree again.

  - The old driver statement has been added to the kernel docs.

  - We have a couple of new helper scripts. find-unused-docs.sh from
    Sayli Karnic will point out kerneldoc comments that are not actually
    used in the documentation. Jani Nikula's
    documentation-file-ref-check finds references to non-existing files.

  - A new ftrace document from Steve Rostedt.

  - Vinod Koul converted the dmaengine docs to RST

  Beyond that, it's mostly simple fixes.

  This set reaches outside of Documentation/ a bit more than most. In
  all cases, the changes are to comment docs, mostly from Randy, in
  places where there didn't seem to be anybody better to take them"

* tag 'docs-4.15' of git://git.lwn.net/linux: (52 commits)
  documentation: fb: update list of available compiled-in fonts
  MAINTAINERS: update DMAengine documentation location
  dmaengine: doc: ReSTize pxa_dma doc
  dmaengine: doc: ReSTize dmatest doc
  dmaengine: doc: ReSTize client API doc
  dmaengine: doc: ReSTize provider doc
  dmaengine: doc: Add ReST style dmaengine document
  ftrace/docs: Add documentation on how to use ftrace from within the kernel
  bug-hunting.rst: Fix an example and a typo in a Sphinx tag
  scripts: Add a script to find unused documentation
  samples: Convert timers to use timer_setup()
  documentation: kernel-api: add more info on bitmap functions
  Documentation: fix selftests related file refs
  Documentation: fix ref to power basic-pm-debugging
  Documentation: fix ref to trace stm content
  Documentation: fix ref to coccinelle content
  Documentation: fix ref to workqueue content
  Documentation: fix ref to sphinx/kerneldoc.py
  Documentation: fix locking rt-mutex doc refs
  docs: dev-tools: correct Coccinelle version number
  ...
2017-11-13 08:25:06 -08:00
Paul E. McKenney
533966c8ad doc: Fix RCU's docbook options
Commit 764f80798b ("doc: Add RCU files to docbook-generation files")
added :external: options for RCU source files in the file
Documentation/core-api/kernel-api.rst.  However, this now means nothing,
so this commit removes them.

Reported-by: Randy Dunlap <rdunlap@infradead.org>
Reported-by: Akira Yokosawa <akiyks@gmail.com>
Signed-off-by: Paul E. McKenney <paulmck@linux.vnet.ibm.com>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
2017-10-19 22:26:11 -04:00
Randy Dunlap
7d7363e403 documentation: kernel-api: add more info on bitmap functions
There are some good comments about bitmap operations in lib/bitmap.c
and include/linux/bitmap.h, so format them for document generation and
pull them into core-api/kernel-api.rst.

I converted the "tables" of functions from using tabs to using spaces
so that they are more readable in the source file and in the generated
output.

Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-10-19 13:01:40 -06:00
Randy Dunlap
68e5125222 Documentation: add kernel-api section on Math functions
Add a kernel-api section on Math Functions.

Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-10-07 10:45:21 -06:00
Randy Dunlap
8a29896a6e docs: clean up and add rest of CRC functions to kernel-api.rst
Add the rest of the CRC library functions to kernel-api.

- try to clarify crc32() by adding '@' to a function parameter
- reorder kernel-api CRC functions to be less random
- add more CRC functions to kernel-api
- correct the function parameter names in several places

Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-09-26 15:01:20 -06:00
Randy Dunlap
404376af78 Documentation: kernel-api: add bitmap operations from linux/bitmap.h
Add <linux/bitmap.h> to kernel-api Bitmap Operations section.
Fix kernel-doc nitpicks in <linux/bitmap.h>.

Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
Acked-by: Yury Norov <ynorov@caviumnetworks.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-09-26 14:42:25 -06:00
Randy Dunlap
416c751735 Documentation: kernel-api: drop "Data Types" section
In the kernel-api chapter, the section for Data Types only
contains "Doubly Linked Lists" and all of the function interfaces
for list management.  There are no other data types in this section,
so collapse this section into "List Management Functions".

Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-09-26 14:32:26 -06:00
Randy Dunlap
47684e111f Documentation: core-api: minor workqueue.rst cleanups
Clean up workqueue.rst:
- fix minor typos
- put '@' after `` instead of preceding them (one place)
- use "CPU" instead of "cpu" in text consistently
- quote one function name

Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
Cc: Tejun Heo <tj@kernel.org>
Cc: Florian Mickler <florian@mickler.org>
Signed-off-by: Tejun Heo <tj@kernel.org>
2017-09-18 17:29:27 -07:00
Linus Torvalds
9954d4892a Merge branch 'for-4.14' of git://git.kernel.org/pub/scm/linux/kernel/git/tj/wq
Pull workqueue updates from Tejun Heo:
 "Nothing major. I introduced a flag collsion bug during v4.13 cycle
  which is fixed in this pull request. Fortunately, the flag is for
  debugging / verification and the bug isn't critical"

* 'for-4.14' of git://git.kernel.org/pub/scm/linux/kernel/git/tj/wq:
  workqueue: Fix flag collision
  workqueue: Use TASK_IDLE
  workqueue: fix path to documentation
  workqueue: doc change for ST behavior on NUMA systems
2017-09-06 21:59:31 -07:00
Linus Torvalds
0081a0ce80 Merge branch 'core-rcu-for-linus' of git://git.kernel.org/pub/scm/linux/kernel/git/tip/tip
Pull RCU updates from Ingo Molnad:
 "The main RCU related changes in this cycle were:

   - Removal of spin_unlock_wait()
   - SRCU updates
   - RCU torture-test updates
   - RCU Documentation updates
   - Extend the sys_membarrier() ABI with the MEMBARRIER_CMD_PRIVATE_EXPEDITED variant
   - Miscellaneous RCU fixes
   - CPU-hotplug fixes"

* 'core-rcu-for-linus' of git://git.kernel.org/pub/scm/linux/kernel/git/tip/tip: (63 commits)
  arch: Remove spin_unlock_wait() arch-specific definitions
  locking: Remove spin_unlock_wait() generic definitions
  drivers/ata: Replace spin_unlock_wait() with lock/unlock pair
  ipc: Replace spin_unlock_wait() with lock/unlock pair
  exit: Replace spin_unlock_wait() with lock/unlock pair
  completion: Replace spin_unlock_wait() with lock/unlock pair
  doc: Set down RCU's scheduling-clock-interrupt needs
  doc: No longer allowed to use rcu_dereference on non-pointers
  doc: Add RCU files to docbook-generation files
  doc: Update memory-barriers.txt for read-to-write dependencies
  doc: Update RCU documentation
  membarrier: Provide expedited private command
  rcu: Remove exports from rcu_idle_exit() and rcu_idle_enter()
  rcu: Add warning to rcu_idle_enter() for irqs enabled
  rcu: Make rcu_idle_enter() rely on callers disabling irqs
  rcu: Add assertions verifying blocked-tasks list
  rcu/tracing: Set disable_rcu_irq_enter on rcu_eqs_exit()
  rcu: Add TPS() protection for _rcu_barrier_trace strings
  rcu: Use idle versions of swait to make idle-hack clear
  swait: Add idle variants which don't contribute to load average
  ...
2017-09-04 08:13:52 -07:00
Jonathan Corbet
7ee8adcf27 doc: Add documentation for the genalloc subsystem
Genalloc/genpool has kerneldoc comments, but nothing has ever been pulled
into the docs themselves.  Here's a first attempt, repurposed from an
article I wrote at https://lwn.net/Articles/729653/.

Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-08-30 16:49:04 -06:00
Paul E. McKenney
764f80798b doc: Add RCU files to docbook-generation files
Suggested-by: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Paul E. McKenney <paulmck@linux.vnet.ibm.com>
2017-08-17 07:29:57 -07:00
Alexei Potashnik
0e0cafcda8 workqueue: doc change for ST behavior on NUMA systems
NUMA rework of workqueue made the combination of max_active of 1 and
WQ_UNBOUND insufficient to guarantee ST behavior system wide.

alloc_ordered_queue should now be used instead.

Signed-off-by: Alexei Potashnik <alexei@purestorage.com>
Signed-off-by: Tejun Heo <tj@kernel.org>
2017-07-18 14:34:53 -04:00
Linus Torvalds
954e6e03c6 A set of fixes for various warnings, including the one caused by the
removal of kernel/rcu/srcu.c.  Also correct a stray pointer in
 memory-barriers.txt.
 -----BEGIN PGP SIGNATURE-----
 
 iQIcBAABAgAGBQJZZqwLAAoJEI3ONVYwIuV6KJoP/0Ci87obaOe/zBCgPN+bNPD3
 QCe4HjihMKHmXNJbqX2kQFHwrruKKa6mS/OfKGy+UOmGVcBdNlOvMm2NjV4npw2P
 Av9HUmSiheaVIgWkbkv4Ov705DxAd3G8SqKwau34jNSajg1LmtStcEAwgM7yXQNb
 /+r2i4SWG+S5MnuJQ319qtYHyBBoXjY0PcMAaPL+n6xJ/Lt7pFjHqXuHe+rjH44U
 a7NODob3zquHELmqu3gIDNvnnaRR4yHmk66bYa4jFqRf9CIvuY3DrnM61gWq69vb
 ROv7rLKX8VEE8RShx4Gn+F6akEPYTUtTCRO8dKeT0RK4nPlhVeObF1Fq+9Ttj1xx
 SvmDhp3Kq/xI6aXXH76THOMxwoi6bykZFfZoi3zD7d6PQBmdwGPKDxPRMVOzsUqS
 E2DIo/8LSReWGoqat51DjmHAg5npoxSdcuw0BU++OVaoDTYCQ2iaPn5htIiQ/8SM
 jG4fjgMJB9I6ub/RrxVSTPPSgYC/bdRTSH0q4D7lC5/uh4jAhSM2GMtwprejQ//k
 DgUaY1UHutVnpGoceRE0jw3nj5mZZ9ILr/5iRYOztemjCJOSa/MSfyVkgRObmOKc
 P6ihr0QZq34nwOL0K/JTQml+NuszcDy53+hBIOdXhikl4wsy0BjbYysFC5gzH4V3
 DhIRdwTeTKleq0tnKNOl
 =JEoA
 -----END PGP SIGNATURE-----

Merge tag '4.13-fixes' of git://git.lwn.net/linux

Pull documentation fixes from Jonathan Corbet:
 "A set of fixes for various warnings, including the one caused by the
  removal of kernel/rcu/srcu.c. Also correct a stray pointer in
  memory-barriers.txt"

* tag '4.13-fixes' of git://git.lwn.net/linux:
  kokr/memory-barriers.txt: Fix obsolete link to atomic_ops.txt
  memory-barriers.txt: Fix broken link to atomic_ops.txt
  docs: Turn off section numbering for the input docs
  docs: Include uaccess docs from the right file
  docs: Do not include from kernel/rcu/srcu.c
2017-07-13 13:44:54 -07:00
Jonathan Corbet
7d2b39ab9b docs: Include uaccess docs from the right file
Documentation/core-api/kernel-api.rst was including kerneldoc comments from
arch/x86/include/asm/uaccess_32.h, but the relevant comments moved to
.../uaccess.h some time ago.  Correct the include to pick up the comments
and eliminate a warning.

Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-07-12 16:51:38 -06:00
Linus Torvalds
650fc870a2 There has been a fair amount of activity in the docs tree this time
around.  Highlights include:
 
  - Conversion of a bunch of security documentation into RST
 
  - The conversion of the remaining DocBook templates by The Amazing
    Mauro Machine.  We can now drop the entire DocBook build chain.
 
  - The usual collection of fixes and minor updates.
 -----BEGIN PGP SIGNATURE-----
 
 iQIcBAABAgAGBQJZWkGAAAoJEI3ONVYwIuV6rf0P/0B3JTiVPKS/WUx53+jzbAi4
 1BN7dmmuMxE1bWpgdEq+ac4aKxm07iAojuntuMj0qz/ZB1WARcmvEqqzI5i4wfq9
 5MrLduLkyuWfr4MOPseKJ2VK83p8nkMOiO7jmnBsilu7fE4nF+5YY9j4cVaArfMy
 cCQvAGjQzvej2eiWMGUSLHn4QFKh00aD7cwKyBVsJ08b27C9xL0J2LQyCDZ4yDgf
 37/MH3puEd3HX/4qAwLonIxT3xrIrrbDturqLU7OSKcWTtGZNrYyTFbwR3RQtqWd
 H8YZVg2Uyhzg9MYhkbQ2E5dEjUP4mkegcp6/JTINH++OOPpTbdTJgirTx7VTkSf1
 +kL8t7+Ayxd0FH3+77GJ5RMj8LUK6rj5cZfU5nClFQKWXP9UL3IelQ3Nl+SpdM8v
 ZAbR2KjKgH9KS6+cbIhgFYlvY+JgPkOVruwbIAc7wXVM3ibk1sWoBOFEujcbueWh
 yDpQv3l1UX0CKr3jnevJoW26LtEbGFtC7gSKZ+3btyeSBpWFGlii42KNycEGwUW0
 ezlwryDVHzyTUiKllNmkdK4v73mvPsZHEjgmme4afKAIiUilmcUF4XcqD86hISFT
 t+UJLA/zEU+0sJe26o2nK6GNJzmo4oCtVyxfhRe26Ojs1n80xlYgnZRfuIYdd31Z
 nwLBnwDCHAOyX91WXp9G
 =cVjZ
 -----END PGP SIGNATURE-----

Merge tag 'docs-4.13' of git://git.lwn.net/linux

Pull documentation updates from Jonathan Corbet:
 "There has been a fair amount of activity in the docs tree this time
  around. Highlights include:

   - Conversion of a bunch of security documentation into RST

   - The conversion of the remaining DocBook templates by The Amazing
     Mauro Machine. We can now drop the entire DocBook build chain.

   - The usual collection of fixes and minor updates"

* tag 'docs-4.13' of git://git.lwn.net/linux: (90 commits)
  scripts/kernel-doc: handle DECLARE_HASHTABLE
  Documentation: atomic_ops.txt is core-api/atomic_ops.rst
  Docs: clean up some DocBook loose ends
  Make the main documentation title less Geocities
  Docs: Use kernel-figure in vidioc-g-selection.rst
  Docs: fix table problems in ras.rst
  Docs: Fix breakage with Sphinx 1.5 and upper
  Docs: Include the Latex "ifthen" package
  doc/kokr/howto: Only send regression fixes after -rc1
  docs-rst: fix broken links to dynamic-debug-howto in kernel-parameters
  doc: Document suitability of IBM Verse for kernel development
  Doc: fix a markup error in coding-style.rst
  docs: driver-api: i2c: remove some outdated information
  Documentation: DMA API: fix a typo in a function name
  Docs: Insert missing space to separate link from text
  doc/ko_KR/memory-barriers: Update control-dependencies example
  Documentation, kbuild: fix typo "minimun" -> "minimum"
  docs: Fix some formatting issues in request-key.rst
  doc: ReSTify keys-trusted-encrypted.txt
  doc: ReSTify keys-request-key.txt
  ...
2017-07-03 21:13:25 -07:00
Paul E. McKenney
79269ee3fa doc/atomic_ops: Clarify smp_mb__{before,after}_atomic()
This commit explicitly states that surrounding a non-value-returning
atomic read-modify atomic operations provides full ordering, just as
is provided by value-returning atomic read-modify-write operations.

Signed-off-by: Paul E. McKenney <paulmck@linux.vnet.ibm.com>
2017-06-08 08:25:28 -07:00
Jonathan Corbet
6312811be2 Merge remote-tracking branch 'mauro-exp/docbook3' into death-to-docbook
Mauro says:

This patch series convert the remaining DocBooks to ReST.

The first version was originally
send as 3 patch series:

   [PATCH 00/36] Convert DocBook documents to ReST
   [PATCH 0/5] Convert more books to ReST
   [PATCH 00/13] Get rid of DocBook

The lsm book was added as if it were a text file under
Documentation. The plan is to merge it with another file
under Documentation/security, after both this series and
a security Documentation patch series gets merged.

It also adjusts some Sphinx-pedantic errors/warnings on
some kernel-doc markups.

I also added some patches here to add PDF output for all
existing ReST books.
2017-05-18 11:03:08 -06:00
Markus Heiser
e3bb40c010 core-api: remove an unexpected unident
As complained by Sphinx:
	Documentation/core-api/assoc_array.rst:13: WARNING: Enumerated list ends without a blank line; unexpected unindent.

This was already addressed, but not really fixed in 2ba90ccca7.

Signed-off-by: Markus Heiser <markus.heiser@darmarit.de>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-05-18 10:22:34 -06:00
Mauro Carvalho Chehab
8aba784832 docs-rst: convert librs book to ReST
Use pandoc to convert documentation to ReST by calling
Documentation/sphinx/tmplcvt script.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
2017-05-16 08:44:16 -03:00
Mauro Carvalho Chehab
c7e2c0643d docs-rst: core_api: move driver-specific stuff to drivers_api
There are several stuff there that are actually driver-specific.

Move those to the driver_api book.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-04-02 14:17:43 -06:00
Mauro Carvalho Chehab
61c8830bc1 kernel-api.rst: make it handle lib/crc32.c
This file has only "internal" functions:
	./lib/crc32.c:1: warning: no structured comments found

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-04-02 14:14:15 -06:00
Mauro Carvalho Chehab
baca8a0c99 kernel-api.tmpl: convert it to ReST
Brainless conversion of genericirq.tmpl book to ReST, via
	Documentation/sphinx/tmplcvt

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-04-02 14:13:27 -06:00
Mauro Carvalho Chehab
76d40fae13 genericirq.rst: add cross-reference links and use monospaced fonts
The document describes several functions that are documented
there via kernel doc macros. Add cross-references to them.

In order to be consistend with other documents, use monospaced
fonts for fields.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-04-02 14:11:27 -06:00
Mauro Carvalho Chehab
3bd3b99ab6 genericirq.tmpl: convert it to ReST
Brainless conversion of genericirq.tmpl book to ReST, via
	Documentation/sphinx/tmplcvt

Copyright information inserted manually.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-04-02 14:10:50 -06:00
sayli karnik
b2e33536c0 Documentation: Add flexible-arrays.rst to the documentation tree
Add flexible-arrays.rst to Documentation/core-api. Add kernel-doc
comments to allow referencing.

Signed-off-by: sayli karnik <karniksayli1995@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-03-29 14:50:21 -06:00
Sebastian Andrzej Siewior
ff58fa7f55 Documentation: Update CPU hotplug and move it to core-api
The current CPU hotplug is outdated. During the update to what we
currently have I rewrote it partly and moved to sphinx format.

Cc: Jonathan Corbet <corbet@lwn.net>
Cc: Mauro Carvalho Chehab <mchehab@kernel.org>
Cc: Rusty Russell <rusty@rustcorp.com.au>
Cc: Srivatsa Vaddagiri <vatsa@in.ibm.com>
Cc: Ashok Raj <ashok.raj@intel.com>
Cc: Joel Schopp <jschopp@austin.ibm.com>
Cc: linux-doc@vger.kernel.org
Signed-off-by: Sebastian Andrzej Siewior <bigeasy@linutronix.de>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-01-13 10:32:32 -07:00
Mauro Carvalho Chehab
2ba90ccca7 core-api: remove an unexpected unident
As complained by Sphinx:
	Documentation/core-api/assoc_array.rst:13: WARNING: Enumerated list ends without a blank line; unexpected unindent.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-12-01 10:46:01 -07:00