Dan Carpenter [Mon, 28 Nov 2016 14:43:15 +0000 (17:43 +0300)]
Documentation/process/howto: Only send regression fixes after -rc1
The original text was not clear if white space or other harmless patches
should be merged in -rc kernels. The discussion at Kernel Summit said
that we should be more strict about sending regression fixes only.
Signed-off-by: Dan Carpenter <dan.carpenter@oracle.com> Acked-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
docs-rst: doc-guide: split the kernel-documentation.rst contents
Having the kernel-documentation at the topmost level doesn't
allow generating a separate PDF file for it. Also, makes harder
to add extra contents. So, place it on a sub-dir.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Daniel Vetter [Thu, 17 Nov 2016 10:19:43 +0000 (11:19 +0100)]
doc: Document the new inline struct member kernel-doc style
We don't just need better doc toolchains, we also need better docs for
our doc toolchain!
v2: Make sure we don't have foo twice (Jani).
Cc: Daniel Vetter <daniel@ffwll.ch> Cc: Jani Nikula <jani.nikula@intel.com> Cc: Jonathan Corbet <corbet@lwn.net> Cc: linux-doc@vger.kernel.org Signed-off-by: Daniel Vetter <daniel.vetter@intel.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Jani Nikula [Wed, 16 Nov 2016 15:26:16 +0000 (17:26 +0200)]
kernel-doc: add support for one line inline struct member doc comments
kernel-doc supports documenting struct members "inline" since a4c6ebede2f9 ("scripts/kernel-doc Allow struct arguments documentation
in struct body"). This requires the inline kernel-doc comments to have
the opening and closing comment markers (/** and */ respectively) on
lines of their own, even for short comments. For example:
/**
* struct foo - struct documentation
*/
struct foo {
/**
* @bar: member documentation
*/
int bar;
};
Add support for one line inline comments:
/**
* struct foo - struct documentation
*/
struct foo {
/** @bar: member documentation */
int bar;
};
Note that mixing of the two in one doc comment is not allowed; either
both comment markers must be on lines of their own, or both must be on
the one line. This limitation keeps both the comments more uniform, and
kernel-doc less complicated.
Cc: Daniel Vetter <daniel@ffwll.ch> Signed-off-by: Jani Nikula <jani.nikula@intel.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Brian Norris [Tue, 15 Nov 2016 22:42:14 +0000 (14:42 -0800)]
docs/completion.txt: drop dangling reference to completions-design.txt
Per the original author, the proposed document was never deemed
necessary, and the important bits got merged into completion.txt. Let's
just stop confusing readers by pointing at a nonexistent doc.
Signed-off-by: Brian Norris <briannorris@chromium.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Mark Rutland [Wed, 16 Nov 2016 11:12:49 +0000 (11:12 +0000)]
Documentation: circular-buffers: use READ_ONCE()
While the {READ,WRITE}_ONCE() macros should be used in preference to
ACCESS_ONCE(), the circular buffer documentation uses the latter
exclusively.
To point people in the right direction, and as a step towards the
eventual removal of ACCESS_ONCE(), update the documentation to use
READ_ONCE(), as ACCESS_ONCE() is only used in a reader context in the
circular buffer documentation.
Signed-off-by: Mark Rutland <mark.rutland@arm.com> Acked-by: David Howells <dhowells@redhat.com> Acked-by: Paul E. McKenney <paulmck@linux.vnet.ibm.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Mark Rutland [Wed, 16 Nov 2016 11:13:59 +0000 (11:13 +0000)]
Documentation: atomic_ops: use {READ,WRITE}_ONCE()
While the {READ,WRITE}_ONCE() macros should be used in preference to
ACCESS_ONCE(), the atomic documentation uses the latter exclusively.
To point people in the right direction, and as a step towards the
eventual removal of ACCESS_ONCE(), update the documentation to use the
{READ,WRITE}_ONCE() macros as appropriate.
Signed-off-by: Mark Rutland <mark.rutland@arm.com> Cc: Boqun Feng <boqun.feng@gmail.com> Cc: Peter Zijlstra <peterz@infradead.org> Cc: Will Deacon <will.deacon@arm.com> Acked-by: Paul E. McKenney <paulmck@linux.vnet.ibm.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Jonathan Corbet [Wed, 16 Nov 2016 22:39:56 +0000 (15:39 -0700)]
Merge branch 'mauro-pdf' into docs-next
Mauro says:
This series address a series of errors during PDF generation from
media documentation.
The first patch fixes the late redefinition of a LaTeX command at the
Sphinx LaTeX style that causes build to break when some cross-references
are used.
The next two patches fix PDF output issues with subdev-formats.rst.
The next 3 patches fix image includes and their output for PDF.
It is aligned with Linus request of not having binary-generated images
from their SVG source codes.
I still intend to move the remaing PNG images to vectorial ones (SVG),
as image scale works better, but this will require some additional work.
When done, I'll submit as a separate patch series.
It should also be noticed that the last patch violates the output dir,
when make is used with "O=some_dir", as Sphinx doesn't accept
image files outside the source directory. We'll likely need some Sphinx
extension in order to fix it, but at least with this series (plus Jani Nikola's
PDF fix series), the PDF output should work fine again.
[jc: added a commit fixing up a "make cleandocs" warning]
The PDF files that contain media images were actually generated
offline from their SVG or PNG source files.
Sphinx can handle PNG sources automatially. So, let's just
drop their PDF counterparts.
For SVG, however, Sphinx doesn't produce the right tags to
use the TexLive SVG support. Also, the SVG support is done via
shell execution, with is not nice.
So, while we don't have any support for SVG inside Sphinx
core or as an extension, move the logic to build them to Makefile,
producing the PDF images on runtime.
NOTE: due to the way Sphinx works, the PDF images should be
generated inside the Kernel source tree, as otherwise Sphinx
won't find it, not obeying what's specified by "O=" makefile
parameter.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
docs-rst: fix LaTeX \DURole renewcommand with Sphinx 1.3+
PDF build on Kernel 4.9-rc? returns an error with Sphinx 1.3.x
and Sphinx 1.4.x, when trying to solve some cross-references.
The solution is to redefine the \DURole macro.
However, this is redefined too late. Move such redefinition to
LaTeX preamble and bind it to just the Sphinx versions where the
error is known to be present.
Tested by building the documentation on interactive mode:
make PDFLATEX=xelatex -C Documentation/output/./latex
Fixes: e61a39baf74d ("[media] index.rst: Fix LaTeX error in interactive mode on Sphinx 1.4.x") Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
SeongJae Park [Tue, 8 Nov 2016 12:26:07 +0000 (21:26 +0900)]
docs/driver-api: Apply changed source file names
Few files under dma-buf/ changed their names but the changes didn't
applied to a document that referencing them. It is causing few
documentation build warnings. This commit fixes the problems by
applying changed file names on the document.
Signed-off-by: SeongJae Park <sj38.park@gmail.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Takashi Iwai [Thu, 10 Nov 2016 21:19:33 +0000 (22:19 +0100)]
ASoC: doc: ReSTize dapm.txt
A simple conversion from a plain text file.
The section numbers and the item numbers are dropped to align with the
ReST format. Some lists are converted to description lists to be
clearer.
Acked-by: Mark Brown <broonie@kernel.org> Signed-off-by: Takashi Iwai <tiwai@suse.de>
Takashi Iwai [Wed, 9 Nov 2016 14:52:06 +0000 (15:52 +0100)]
ALSA: doc: ReSTize Procfile document
A simple conversion from a text file.
A new subidrectory, Documentation/sound/designs, was created to put
this document. The other API design and implementation docuemnts
will be put to that directory in later commits.
Takashi Iwai [Wed, 9 Nov 2016 12:01:05 +0000 (13:01 +0100)]
ALSA: doc: ReSTize HD-Audio document
The original HD-Audio.txt was already in asciidoc format, so it's a
simple conversion in the end.
A new subdirectory, Documentation/sound/hd-audio, is created and the
document is moved there with another file name to match better with
the recent Documentation tree structure.
A typo sneaked in the latest change on the USB documentation. Fixing it
and also a trailing whitespace since it is also in the "USB Host-Side API
Model" chapter.
Signed-off-by: Luis de Bethencourt <luisbg@osg.samsung.com>
Masahiro Yamada [Wed, 2 Nov 2016 16:57:34 +0000 (01:57 +0900)]
coding-style: fix mismatch of jump label name
Commit 865a1caa4b6b ("CodingStyle: Clarify and complete chapter 7")
renamed the label "out_buffer" to "out_free_buffer", but missed to
change this line.
Signed-off-by: Masahiro Yamada <yamada.masahiro@socionext.com> Reviewed-by: Jean Delvare <jdelvare@suse.de> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Changes since v1:
- Reduce the patch to DocBook cleandocs
References: http://lkml.kernel.org/r/CA+r1Zhjr5SCVAroREBv84t9bxDVu5jVJ_Fu=BbVDGNNABdQOuQ@mail.gmail.com Reported-by: Jim Davis <jim.epost@gmail.com> Signed-off-by: Markus Heiser <markus.heiser@darmarit.de> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Jarkko Sakkinen [Thu, 3 Nov 2016 23:57:51 +0000 (17:57 -0600)]
tpm: transition tpm_vtpm_proxy documentation to the Sphinx
Transitioned the tpm_vtpm_proxy documentation to the Sphinx
infrastructure and removed parts from the documentation that are easier
to pull from the sources. Restructured vtpm_proxy.h and tpm_vtpm_proxy.c
to be compatible with this approach and wrote associated documentation
comments.
Signed-off-by: Jarkko Sakkinen <jarkko.sakkinen@linux.intel.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
SeongJae Park [Mon, 31 Oct 2016 20:27:21 +0000 (05:27 +0900)]
ko_KR/HOWTO: Mark subsection in suggested format
`Specific guidelines for the kernel documentation` section of
`kernel-documentation.rst` suggests to use ``~`` for subsection but
subsections in HOWTO is not marked in the format. This commit marks
them in the format.
Signed-off-by: SeongJae Park <sj38.park@gmail.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
SeongJae Park [Mon, 31 Oct 2016 20:27:20 +0000 (05:27 +0900)]
ko_KR/HOWTO: Add whitespace between URL and text
Because few sentences has no whitespace between URL and text, few
document viewers fail to properly parse the URL from it. This commit
adds whitespace between them to fix the problem.
Signed-off-by: SeongJae Park <sj38.park@gmail.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
SeongJae Park [Mon, 31 Oct 2016 20:27:14 +0000 (05:27 +0900)]
ko_KR/HOWTO: Convert to ReST notation
This commit applies commit 022e04d6f555 ("Documentation/HOWTO: convert
to ReST notation") to Korean translation and fix a trivial ReST build
failure problem.
Signed-off-by: SeongJae Park <sj38.park@gmail.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
SeongJae Park [Mon, 31 Oct 2016 20:27:10 +0000 (05:27 +0900)]
Documentation/process/howto: Mark subsection in suggested format
`Specific guidelines for the kernel documentation` section of
`kernel-documentation.rst` suggests to use ``~`` for subsection but
subsections in HOWTO is not marked in the format. This commit marks
them in the format.
Signed-off-by: SeongJae Park <sj38.park@gmail.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Now that oops-tracing.rst has only information about
stack dumps found on OOPS, and bug-hunting.rst has only
information about how to identify the source code line
associated with a stack dump, let's merge them and
improve the information inside it.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
The document shows a really old procedure for bug hunting that
nobody uses anymore. Remove such section, and update the
remaining documentation to reflect the procedures used
currently.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Linus Torvalds [Sat, 5 Nov 2016 18:46:02 +0000 (11:46 -0700)]
Merge branches 'sched-urgent-for-linus' and 'core-urgent-for-linus' of git://git.kernel.org/pub/scm/linux/kernel/git/tip/tip
Pull stack vmap fixups from Thomas Gleixner:
"Two small patches related to sched_show_task():
- make sure to hold a reference on the task stack while accessing it
- remove the thread_saved_pc printout
.. and add a sanity check into release_task_stack() to catch problems
with task stack references"
* 'sched-urgent-for-linus' of git://git.kernel.org/pub/scm/linux/kernel/git/tip/tip:
sched/core: Remove pointless printout in sched_show_task()
sched/core: Fix oops in sched_show_task()
* 'core-urgent-for-linus' of git://git.kernel.org/pub/scm/linux/kernel/git/tip/tip:
fork: Add task stack refcounting sanity check and prevent premature task stack freeing
Linus Torvalds [Sat, 5 Nov 2016 18:34:07 +0000 (11:34 -0700)]
Merge tag 'md/4.9-rc3' of git://git.kernel.org/pub/scm/linux/kernel/git/shli/md
Pull MD fixes from Shaohua Li:
"There are several bug fixes queued:
- fix raid5-cache recovery bugs
- fix discard IO error handling for raid1/10
- fix array sync writes bogus position to superblock
- fix IO error handling for raid array with external metadata"
* tag 'md/4.9-rc3' of git://git.kernel.org/pub/scm/linux/kernel/git/shli/md:
md: be careful not lot leak internal curr_resync value into metadata. -- (all)
raid1: handle read error also in readonly mode
raid5-cache: correct condition for empty metadata write
md: report 'write_pending' state when array in sync
md/raid5: write an empty meta-block when creating log super-block
md/raid5: initialize next_checkpoint field before use
RAID10: ignore discard error
RAID1: ignore discard error
Linus Torvalds [Sat, 5 Nov 2016 18:28:21 +0000 (11:28 -0700)]
Merge tag 'scsi-fixes' of git://git.kernel.org/pub/scm/linux/kernel/git/jejb/scsi
Pull SCSI fixes from James Bottomley:
"Two more important data integrity fixes related to RAID device drivers
which wrongly throw away the SYNCHRONIZE CACHE command in the non-RAID
path and a memory leak in the scsi_debug driver"
* tag 'scsi-fixes' of git://git.kernel.org/pub/scm/linux/kernel/git/jejb/scsi:
scsi: arcmsr: Send SYNCHRONIZE_CACHE command to firmware
scsi: scsi_debug: Fix memory leak if LBP enabled and module is unloaded
scsi: megaraid_sas: Fix data integrity failure for JBOD (passthrough) devices
projects / linux-beck.git / log