The HOWTO document needed updating for the new kernel versioning.
Signed-off-by: NMario Carrillo <mario.alfredo.c.arevalo@intel.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

The kernel-doc script gets confused by __attribute__(()) strings in
structures, so just clean the out.  Also ignore the CRYPTO_MINALIGN_ATTR
macro used in the crypto subsystem.
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Functions, Structs and Parameters definitions on kernel documentation
are pure cosmetic, it only highlights the element.

To ease the navigation in the documentation we should use <links> inside
those tags so readers can easily jump between methods directly.

This was discussed in 2014[1] and is implemented by getting a list
of <refentries> from the DocBook XML to generate a database. Then it looks
for <function>,<structnames> and <paramdef> tags that matches the ones in
the database. As it only links existent references, no broken links are
added.

[1] - lists.freedesktop.org/archives/dri-devel/2014-August/065404.html
Signed-off-by: NDanilo Cesar Lemes de Paula <danilo.cesar@collabora.co.uk>
Cc: Randy Dunlap <rdunlap@infradead.org>
Cc: Daniel Vetter <daniel.vetter@ffwll.ch>
Cc: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Cc: Herbert Xu <herbert@gondor.apana.org.au>
Cc: Stephan Mueller <smueller@chronox.de>
Cc: Michal Marek <mmarek@suse.cz>
Cc: intel-gfx <intel-gfx@lists.freedesktop.org>
Cc: dri-devel <dri-devel@lists.freedesktop.org>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Some kernel-doc sections are included in multiple DocBook files.  This
means the mandocs target will generate the same manual page multiple
times with different metadata (author name/address and manual title,
taken from the including DocBook file).  If it's invoked in a parallel
build, the output is non-determinstic.

Build the manual pages in a separate subdirectory per DocBook file,
then sort and de-duplicate when installing them (which is serialised).
Signed-off-by: NBen Hutchings <ben@decadent.org.uk>
[jc: fixed conflicts with the docs tree]
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Fix minor typo so that can pass correct pointer variable for
container_of().
Signed-off-by: NLeo Yan <leo.yan@linaro.org>
[jc: tweaked formatting]
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Add a document describing the process of adding a new system call,
including the need for a flags argument for future compatibility, and
covering 32-bit/64-bit concerns (albeit in an x86-centric way).
Signed-off-by: NDavid Drysdale <drysdale@google.com>
Reviewed-by: NMichael Kerrisk <mtk.manpages@gmail.com>
Reviewed-by: NEric B Munson <emunson@akamai.com>
Reviewed-by: NKees Cook <keescook@chromium.org>
Reviewed-by: NRandy Dunlap <rdunlap@infradead.org>
Reviewed-by: NJosh Triplett <josh@joshtriplett.org>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

There are some workqueue functions declared in workqueue.h, so include
that in the workqueue section of the DocBook docs.
Signed-off-by: NTim Bird <tim.bird@sonymobile.com>
Acked-by: NRandy Dunlap <rdunlap@infradead.org>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Currently there is no general documentation on Keystone SoCs in the
Linux Documentation folder of the source tree. This patch adds some
essential documentation with links to help users of Keystone Linux and
also provide links to existing documents where necessary.
Signed-off-by: NMurali Karicheri <m-karicheri2@ti.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Describing arguments at top of a struct definition works fine
for small/medium size structs, but it definitely doesn't work well
for struct with a huge list of elements.

Keeping the arguments list inside the struct body makes it easier
to maintain the documentation.
ie:
/**
 * struct my_struct - short description
 * @a: first member
 * @b: second member
 *
 * Longer description
 */
struct my_struct {
    int a;
    int b;
    /**
     * @c: This is longer description of C
     *
     * You can use paragraphs to describe arguments
     * using this method.
     */
    int c;
};

This patch allows the use of this kind of syntax. Only one argument
per comment and user can use how many paragraphs he needs. It should
start with /**, which is already being used by kernel-doc. If those
comment doesn't follow those rules, it will be ignored.
Signed-off-by: NDanilo Cesar Lemes de Paula <danilo.cesar@collabora.co.uk>
Cc: Randy Dunlap <rdunlap@infradead.org>
Cc: Daniel Vetter <daniel.vetter@ffwll.ch>
Cc: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: Herbert Xu <herbert@gondor.apana.org.au>
Cc: Stephan Mueller <smueller@chronox.de>
Cc: Michal Marek <mmarek@suse.cz>
Cc: linux-kernel@vger.kernel.org
Cc: linux-doc@vger.kernel.org
Cc: intel-gfx <intel-gfx@lists.freedesktop.org>
Cc: dri-devel <dri-devel@lists.freedesktop.org>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Signed-off-by: NJakub Wilk <jwilk@jwilk.net>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Ben Hutchings writes:

  As part of the reproducible builds project, Jérémy Bobbio identified
  several time-dependent and non-deterministic functions in the document
  build process (htmldocs, mandocs targets).  This patch series should fix
  all of those.

I ended up reverting one patch that introduced problems.

This reverts commit b44158b1.  This commit
introduced warnings and possibly inconsistent results into the doc build
process.  The goal is good but it will need to be achieved another way.
Reported-by: NMasanari Iida <standby24x7@gmail.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Change men-chameleon-bus.txt according to the comments made by Randy Dunlap in
https://lkml.org/lkml/2015/7/17/691.

These are:
* Some minor gramatical changes
* Spelling fixes
* Write the word "Chameleon" capitalized throughout the whole document
* Explain MEN as MEN Mikro Elektronik GmbH.
Signed-off-by: NJohannes Thumshirn <jthumshirn@suse.de>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

This patch changes the tense of a verb in SubmittingPatches to ensure
grammatical validity of the containing sentence.
Signed-off-by: NBenjamin Herr <ben@0x539.de>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

The media maintainers want DocBook changes to go through their tree;
document that wish accordingly.

Install the man pages with mode 644 instead of 755
Signed-off-by: NJim Davis <jim.epost@gmail.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

I have noticed that there is no submenu in Evolution called Heading
instead there is Paragraph style
Signed-off-by: NAhmed Mohamed <ahmedsoliman0x666@gmail.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Add basic introductory documentation for the MEN Chameleon Bus.
Signed-off-by: NJohannes Thumshirn <jthumshirn@suse.de>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

This patch update the Documentation/filesystems/debugfs.txt
file. The main work is to add the description of the following
functions:
    debugfs_create_atomic_t
    debugfs_create_u32_array
    debugfs_create_devm_seqfile
    debugfs_create_file_size
Signed-off-by: NWang Long <long.wanglong@huawei.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

/proc/extfrag_index does not exist.  This file is in debugfs.  Fix the
description of extfrag_threshold to reflect this.
Signed-off-by: NRabin Vincent <rabin.vincent@axis.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

docproc.c was moved in 2011 from scripts/basic to scripts
-> updated the references accordingly
Signed-off-by: NPeter Huewe <peterhuewe@gmx.de>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

This patch fix a file name of example code.
Signed-off-by: NMasanari Iida <standby24x7@gmail.com>
Acked-by: NRodolfo Giometti <giometti@enneenne.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

"facilitate easier reviewing" says the same thing twice.
Signed-off-by: NSébastien Hinderer <Sebastien.Hinderer@ens-lyon.org>
[jc: made it "easier review"]
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Signed-off-by: NSébastien Hinderer <Sebastien.Hinderer@ens-lyon.org>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

In f35f6c8f (can: update MAINTAINERS and Documentation) chapter 3.3
was removed. This patch fixes some old references to chapter 3.4 which
no longer exists.
Signed-off-by: NStefan Tatschner <stefan@sevenbyte.org>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Signed-off-by: NDiego Viola <diego.viola@gmail.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

This patch fix some spelling typo found in Documentation/powerpc.
Signed-off-by: NMasanari Iida <standby24x7@gmail.com>
Acked-by: NIan Munsie <imunsie@au1.ibm.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Extend the kernel-bootloader interface documentation with usage of
register INFORM1 (0x0804) and different CPU resume address on Exynos542x
family (with Multi-Cluster Power Management enabled).

Additionally add glossary and reformat section titles.
Signed-off-by: NKrzysztof Kozlowski <k.kozlowski.k@gmail.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Link to the internal up to date Coding Style document inside the Kernel
sources instead of an external one.
Signed-off-by: NLuis de Bethencourt <luis@debethencourt.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Remove 2 broken links for programming reference books in Appendix I. After
a lookup on an Internet archives web site, it seems that these links have
been broken for around 3 months. We can then assume that they will not be
back up and safely remove them from the documentation.
Signed-off-by: NOlivier C. Larocque <olivier.c.larocque@gmail.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Together with the preceding changes, this allows man pages to be built
reproducibly.
Signed-off-by: NBen Hutchings <ben@decadent.org.uk>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Some kernel-doc sections are included in multiple DocBook files.  This
means the mandocs target will generate the same manual page multiple
times with different metadata (author name/address and manual title,
taken from the including DocBook file).  If it's invoked in a parallel
build, the output is nondeterminstic.

For each section that is duplicated, mark the less specific manual's
inclusion as 'extra' and exclude it during conversion to manual pages.
Use xmlif for this, as that is bundled with xmlto which we already
use.

I would have preferred to use more conventional markup for this, but
each of the following approaches failed:

1. Wrap the extra inclusions with a new element and add a template to
   the stylesheet to include/exclude them.  Unfortunately DocBook XSL
   doesn't seem to support foreign elements at an intermediate level
   in the document tree.
2. Use DocBook profiling.  This works but requires passing an absolute
   path to the profile stylesheet to xmlto, so it's not portable.
3. Use SGML marked sections.  docbook2x can handle these but xmlto
   chokes on them.
Reported-by: NJérémy Bobbio <lunar@debian.org>
Signed-off-by: NBen Hutchings <ben@decadent.org.uk>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

By default, DocBook XSL uses a non-deterministic function to generate
IDs for HTML elements where it can't take a name from the input
document.  However, it has the option to generate 'consistent'
(deterministic) IDs instead.  Enable this to make the HTML pages
reproducible.
Reported-by: NJérémy Bobbio <lunar@debian.org>
Signed-off-by: NBen Hutchings <ben@decadent.org.uk>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

The mtime on a man page is the build time.  As gzip stores the mtime
and original name in the compressed file by default, this makes
compressed man pages unreproducible.  Neither of these are important
metadata in this case, so turn this off.
Reported-by: NJérémy Bobbio <lunar@debian.org>
Signed-off-by: NBen Hutchings <ben@decadent.org.uk>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Regular expressions for highlights in kernel-doc are stored in a Perl
hash.  These hashes are ordered differently for each Perl run. This will
prevent kernel-doc to behave deterministically when parsing “@foo()” as
in some runs it will be interpreted as a parameter and in the others it
will be interpreted as a function.

We now sort the %highlights hash to get the same behavior on every run.
Signed-off-by: NJérémy Bobbio <lunar@debian.org>
Signed-off-by: NBen Hutchings <ben@decadent.org.uk>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

I am a high school student trying to become familiar with
Linux kernel development. The btrfs documentation in
Documentation/filesystems had a few typos and errors in
whitespace. This patch corrects both of these.
Signed-off-by: NDaniel Grimshaw <grimshaw@linux.vnet.ibm.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

From 7e0befc8e48a49e2ddf86bbd861027b14ea5a53d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?S=C3=A9bastien=20Hinderer?=
 <Sebastien.Hinderer@ens-lyon.org>
Date: Wed, 8 Jul 2015 21:10:18 +0200
Subject: [PATCH] SubmittingPatches: fix typo
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
Content-Type: text/plain; charset="utf-8"
Signed-off-by: NSébastien Hinderer <Sebastien.Hinderer@ens-lyon.org>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Merge tag 'platform-drivers-x86-v4.2-2' of git://git.infradead.org/users/dvhart/linux-platform-drivers-x86

Pull late x86 platform driver updates from Darren Hart:
 "The following came in a bit later and I wanted them to bake in next a
  few more days before submitting, thus the second pull.

  A new intel_pmc_ipc driver, a symmetrical allocation and free fix in
  dell-laptop, a couple minor fixes, and some updated documentation in
  the dell-laptop comments.

  intel_pmc_ipc:
   - Add Intel Apollo Lake PMC IPC driver

  tc1100-wmi:
   - Delete an unnecessary check before the function call "kfree"

  dell-laptop:
   - Fix allocating & freeing SMI buffer page
   - Show info about WiGig and UWB in debugfs
   - Update information about wireless control"

* tag 'platform-drivers-x86-v4.2-2' of git://git.infradead.org/users/dvhart/linux-platform-drivers-x86:
  intel_pmc_ipc: Add Intel Apollo Lake PMC IPC driver
  tc1100-wmi: Delete an unnecessary check before the function call "kfree"
  dell-laptop: Fix allocating & freeing SMI buffer page
  dell-laptop: Show info about WiGig and UWB in debugfs
  dell-laptop: Update information about wireless control

Pull more vfs updates from Al Viro:
 "Assorted VFS fixes and related cleanups (IMO the most interesting in
  that part are f_path-related things and Eric's descriptor-related
  stuff).  UFS regression fixes (it got broken last cycle).  9P fixes.
  fs-cache series, DAX patches, Jan's file_remove_suid() work"

[ I'd say this is much more than "fixes and related cleanups".  The
  file_table locking rule change by Eric Dumazet is a rather big and
  fundamental update even if the patch isn't huge.   - Linus ]

* 'for-linus' of git://git.kernel.org/pub/scm/linux/kernel/git/viro/vfs: (49 commits)
  9p: cope with bogus responses from server in p9_client_{read,write}
  p9_client_write(): avoid double p9_free_req()
  9p: forgetting to cancel request on interrupted zero-copy RPC
  dax: bdev_direct_access() may sleep
  block: Add support for DAX reads/writes to block devices
  dax: Use copy_from_iter_nocache
  dax: Add block size note to documentation
  fs/file.c: __fget() and dup2() atomicity rules
  fs/file.c: don't acquire files->file_lock in fd_install()
  fs:super:get_anon_bdev: fix race condition could cause dev exceed its upper limitation
  vfs: avoid creation of inode number 0 in get_next_ino
  namei: make set_root_rcu() return void
  make simple_positive() public
  ufs: use dir_pages instead of ufs_dir_pages()
  pagemap.h: move dir_pages() over there
  remove the pointless include of lglock.h
  fs: cleanup slight list_entry abuse
  xfs: Correctly lock inode when removing suid and file capabilities
  fs: Call security_ops->inode_killpriv on truncate
  fs: Provide function telling whether file_remove_privs() will do anything
  ...