Commit Graph

49 Commits

Author SHA1 Message Date
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
Jonathan Corbet 2fc9254d0c Merge branch 'silvio' into docs-next 2016-11-30 17:46:23 -07:00
Silvio Fricke 326bc876fe Documentation/atomic_ops.txt: convert to ReST markup
... and move to core-api folder.

Signed-off-by: Silvio Fricke <silvio.fricke@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-11-30 17:40:52 -07:00
Silvio Fricke c232694ec1 Documentation/local_ops.txt: convert to ReST markup
... and move to core-api folder.

Signed-off-by: Silvio Fricke <silvio.fricke@gmail.com>
Reviewed-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-11-30 17:40:48 -07:00
Silvio Fricke c3cbf1a704 Documentation/assoc_array.txt: convert to ReST markup
... and move to Documentation/core-api folder.

Signed-off-by: Silvio Fricke <silvio.fricke@gmail.com>
Reviewed-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-11-30 17:40:43 -07:00
Jonathan Corbet d6ba7a9c8b doc: Sphinxify the tracepoint docbook
Convert the tracepoint docbook template to RST and add it to the core-api
manual.  No changes to the actual text beyond the mechanical formatting
conversion.

Cc: Jason Baron <jbaron@redhat.com>
Cc: William Cohen <wcohen@redhat.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-11-29 14:44:23 -07:00
Jonathan Corbet 8da3dc5334 doc: debugobjects: actually pull in the kerneldoc comments
Add the appropriate markup to get the kerneldoc comments out of
lib/debugobjects.c that have never seen the light of day until now.

A logical next step, left for the reader at the moment, is to move the
function descriptions *out* of debug-objects.rst and into the kerneldoc
comments themselves.

Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-11-29 14:44:14 -07:00
Jonathan Corbet 93dc3a112b doc: Convert the debugobjects DocBook template to sphinx
A couple of the most minor heading tweaks, otherwise no changes to the text
itself beyond the mechanical conversion.

Note that the inclusion of the kerneldoc comments from the source has never
worked, since exported symbols were asked for and none of those functions
are exported to modules.  It doesn't work here either :)

Cc: Thomas Gleixner <tglx@linutronix.de>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-11-29 14:44:04 -07:00
Jonathan Corbet 22917b992d docs: Add more manuals to the PDF build
There were a few manuals that weren't being built in PDF format, but
there's no reason not to...

Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-11-16 16:07:02 -07:00
Silvio Fricke e7f08ffb18 Documentation/workqueue.txt: convert to ReST markup
... and move to Documentation/core-api folder.

Signed-off-by: Silvio Fricke <silvio.fricke@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-10-28 10:55:01 -06:00
Silvio Fricke 24755a55b0 Documentation/00-index: update for new core-api folder
Signed-off-by: Silvio Fricke <silvio.fricke@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-10-28 10:54:51 -06:00