Documentation/process/submitting-patches.rst contains a non-ascii
character.  Change it to the ascii equivalent.
Signed-off-by: Frank Rowand <frank.rowand@sony.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

A series to clean up a number of docs build warnings.  More to come.

Documentation/gpu/drm-mm.rst includes from include/drm/drm_syncobj.h with
:export:, but this is a header file without export directives.  That
results in this warning:

    ./include/drm/drm_syncobj.h:1: warning: no structured comments found

...and a failure to obtain the documentation from that file.  Switch to
:internal: instead to make both problems go away.

Cc: dri-devel@lists.freedesktop.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Mauro says:

Sphinx installation is not trivial, as not all versions are supported,
and it requires a lot of stuff for math, images and PDF/LaTeX output
to work.

So, add a script that checks if everything is fine, providing
distro-specific hints about what's needed for it to work.

Add support for detecting and installing missing packages
on Mageia. I opted to use "urpmi" at the install instructions,
as this is present on Mageia since ever. Yet, if I were using
Mageia 6, I would likely be using "dnf", as it is, IMHO,
easier to use.

Tested with Mageia 6.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Now that we have a script to check for Sphinx dependencies,
document it.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Gentoo need some USE for GraphViz and ImageMagick to have
the features required by kfigure.py.

Output that when providing instructions for Gentoo.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

ImageMagick actually uses librsvg for conversions when converiting
from SVG (actually, it uses rsvg-convert). That causes the build to
fail with:

	WARNING: Error #1 when calling: /usr/bin/convert /home/mchehab/docs/Documentation/media/uapi/v4l/selection.svg /home/mchehab/docs/Documentation/output/latex/selection.pdf
	convert: delegate failed `'rsvg-convert' -o '%o' '%i'' @ error/delegate.c/InvokeDelegate/1919.
	convert: unable to open file `/tmp/magick-8883oOQfHzrA5trM': No such file or directory @ error/constitute.c/ReadImage/544.

Add the corresponding dependencies.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

On newer versions of graphviz packaging on Fedora, it is needed to
install a separate package for PDF support.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Instead of using 3 commands to install a virtualenv, use
a single one, reading the requirements from this file:

	Documentation/sphinx/requirements.txt
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Detect if the script runs after creating the virtualenv,
printing the command line commands to enable the virtualenv.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Solving Sphinx dependencies can be painful. Add a script to
check if everything is ok.

Tested on:
	- Fedora 25 and 26;
	- Ubuntu 17.04;
	- OpenSuse Tumbleweed;
	- Arch Linux;
	- Gentoo.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

After removal of DocBook, those targets are bogus.
Reported-by: Jim Davis <jim.epost@gmail.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

commit 6807c846 ("x86: Enable KASLR by default") enables KASLR
by default on x86. While KASLR will confuse gdb which resolve kernel
symbol address from symbol table of vmlinux. We should turn off KASLR for
kernel debugging.
Signed-off-by: Zhouyi Zhou <zhouzhouyi@gmail.com>
Reviewed-by: Kieran Bingham <kbingham@kernel.org>
Acked-by: Jan Kiszka <jan.kiszka@siemens.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

commit 6807c846 ("x86: Enable KASLR by default") enables KASLR
by default on x86. While KASLR will confuse gdb which resolve kernel
symbol address from symbol table of vmlinux. We should turn off KASLR for
kernel debugging.
Signed-off-by: Zhouyi Zhou <zhouzhouyi@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

The only function of interest in that file was scsi_print_status().  That
function was removed in commit 7ac70763 (scsi: remove
scsi_print_status()) but the docs were not changed to match, yielding this
warning:

    ./drivers/scsi/constants.c:1: warning: no structured comments found

There's nothing there anymore, so just remove that section from the docs.
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Back in 2012, commit 9807f759 (UAPI: (Scripted) Disintegrate
arch/s390/include/asm) moved struct cmbdata (and its kerneldoc comments) to
another file, but did not update the docs to match.  The result is this
warning:

    ./arch/s390/include/asm/cmb.h:1: warning: no structured comments found

...and no documentation for that structure.  Update the docs to get the
information from the right place.
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

There are no kerneldoc comments in drivers/dma-buf/seqno-fence.c, and it
appears there never have been.  Stop looking for comments there to
eliminate this warning:

    ./drivers/dma-buf/seqno-fence.c:1: warning: no structured comments found
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

...because there are none there, and I cannot figure out what would ever
have been of interest there.  This eliminates this warning:

    ./kernel/sys.c:1: warning: no structured comments found

from the build.
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

The docs build complains:

    ./include/linux/init.h:1: warning: no structured comments found

The problem is that the comments in question were moved to module.h in
commit 0fd972a7 (module: relocate module_init from init.h to
module.h).  Fix basics.rst to match.
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

In a code-block with line numbers (option :lineno:) there is a
misalignment of the rendered source code lines on the right side and the
line numbers on the left side.

  https://github.com/rtfd/sphinx_rtd_theme/issues/419

Since this issue is reported to the RTD theme project, it might be fixed
in the future (take this as a interim solution).
Signed-off-by: Markus Heiser <markus.heiser@darmarit.de>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

List items with two ore more blocks are not well rendered. E.g. the gap
between last block (l1-b2) of the first list item and the following list
item (L2) is to small::

    * L1 xxxxxxxxxx
      xxxxxxxxxxxxx

      l1-b2 xxxxxxx
      xxxxxxxxxxxxx
    * L2 xxxxxxxxxx
      xxxxxxxxxxxxx

So that it can be read more liquidly, a distance was added to the last
block (l1-b2)::

    * L1 xxxxxxxxxx
      xxxxxxxxxxxxx

      l1-b2 xxxxxxx
      xxxxxxxxxxxxx

    * L2 xxxxxxxxxx
      xxxxxxxxxxxxx
Signed-off-by: Markus Heiser <markus.heiser@darmarit.de>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

All low-level PM/SMP code using virt_to_phys() should actually use
__pa_symbol() against kernel symbols.  Update the documentation to move
away from virt_to_phys().

Cfr. commit 6996cbb2372189f7 ("ARM: 8641/1: treewide: Replace uses of
virt_to_phys with __pa_symbol")
Signed-off-by: Geert Uytterhoeven <geert+renesas@glider.be>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Instead of having it on just one note, add a separate section.

This way, we could later improve it, providing a better
guide about the needed steps for PDF builds.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

As we now have a document describing the install
requirements for Sphinx, add there the need for GraphViz
and ImageMagick.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

There's no "Sphinx C Domain" reference at the Kernel
documentation. So, don't use references for it.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

As the Sphinx build seems very fragile, specially for
PDF output, add a notice about how to use it on a virtual
environment.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

The toolchain used by Sphinx is somewhat complex, and installing
it should be part of the doc-guide.

Move it out of changes.rst.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

The kfigure module doesn't work with Sphinx version 1.2. So,
update the minimal requirements accordingly.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Pull documentation format standardization from Jonathan Corbet:
 "This series converts a number of top-level documents to the RST format
  without incorporating them into the Sphinx tree. The hope is to bring
  some uniformity to kernel documentation and, perhaps more importantly,
  have our existing docs serve as an example of the desired formatting
  for those that will be added later.

  Mauro has gone through and fixed up a lot of top-level documentation
  files to make them conform to the RST format, but without moving or
  renaming them in any way. This will help when we incorporate the ones
  we want to keep into the Sphinx doctree, but the real purpose is to
  bring a bit of uniformity to our documentation and let the top-level
  docs serve as examples for those writing new ones"

* tag 'standardize-docs' of git://git.lwn.net/linux: (84 commits)
  docs: kprobes.txt: Fix whitespacing
  tee.txt: standardize document format
  cgroup-v2.txt: standardize document format
  dell_rbu.txt: standardize document format
  zorro.txt: standardize document format
  xz.txt: standardize document format
  xillybus.txt: standardize document format
  vfio.txt: standardize document format
  vfio-mediated-device.txt: standardize document format
  unaligned-memory-access.txt: standardize document format
  this_cpu_ops.txt: standardize document format
  svga.txt: standardize document format
  static-keys.txt: standardize document format
  smsc_ece1099.txt: standardize document format
  SM501.txt: standardize document format
  siphash.txt: standardize document format
  sgi-ioc4.txt: standardize document format
  SAK.txt: standardize document format
  rpmsg.txt: standardize document format
  robust-futexes.txt: standardize document format
  ...

Pull random updates from Ted Ts'o:
 "Add wait_for_random_bytes() and get_random_*_wait() functions so that
  callers can more safely get random bytes if they can block until the
  CRNG is initialized.

  Also print a warning if get_random_*() is called before the CRNG is
  initialized. By default, only one single-line warning will be printed
  per boot. If CONFIG_WARN_ALL_UNSEEDED_RANDOM is defined, then a
  warning will be printed for each function which tries to get random
  bytes before the CRNG is initialized. This can get spammy for certain
  architecture types, so it is not enabled by default"

* tag 'random_for_linus' of git://git.kernel.org/pub/scm/linux/kernel/git/tytso/random:
  random: reorder READ_ONCE() in get_random_uXX
  random: suppress spammy warnings about unseeded randomness
  random: warn when kernel uses unseeded randomness
  net/route: use get_random_int for random counter
  net/neighbor: use get_random_u32 for 32-bit hash random
  rhashtable: use get_random_u32 for hash_rnd
  ceph: ensure RNG is seeded before using
  iscsi: ensure RNG is seeded before use
  cifs: use get_random_u32 for 32-bit lock random
  random: add get_random_{bytes,u32,u64,int,long,once}_wait family
  random: add wait_for_random_bytes() API

Pull ->s_options removal from Al Viro:
 "Preparations for fsmount/fsopen stuff (coming next cycle). Everything
  gets moved to explicit ->show_options(), killing ->s_options off +
  some cosmetic bits around fs/namespace.c and friends. Basically, the
  stuff needed to work with fsmount series with minimum of conflicts
  with other work.

  It's not strictly required for this merge window, but it would reduce
  the PITA during the coming cycle, so it would be nice to have those
  bits and pieces out of the way"

* 'work.mount' of git://git.kernel.org/pub/scm/linux/kernel/git/viro/vfs:
  isofs: Fix isofs_show_options()
  VFS: Kill off s_options and helpers
  orangefs: Implement show_options
  9p: Implement show_options
  isofs: Implement show_options
  afs: Implement show_options
  affs: Implement show_options
  befs: Implement show_options
  spufs: Implement show_options
  bpf: Implement show_options
  ramfs: Implement show_options
  pstore: Implement show_options
  omfs: Implement show_options
  hugetlbfs: Implement show_options
  VFS: Don't use save/replace_mount_options if not using generic_show_options
  VFS: Provide empty name qstr
  VFS: Make get_filesystem() return the affected filesystem
  VFS: Clean up whitespace in fs/namespace.c and fs/super.c
  Provide a function to create a NUL-terminated string from unterminated data

Pull more __copy_.._user elimination from Al Viro.

* 'work.__copy_to_user' of git://git.kernel.org/pub/scm/linux/kernel/git/viro/vfs:
  drm_dp_aux_dev: switch to read_iter/write_iter

Pull uacess-unaligned removal from Al Viro:
 "That stuff had just one user, and an exotic one, at that - binfmt_flat
  on arm and m68k"

* 'work.uaccess-unaligned' of git://git.kernel.org/pub/scm/linux/kernel/git/viro/vfs:
  kill {__,}{get,put}_user_unaligned()
  binfmt_flat: flat_{get,put}_addr_from_rp() should be able to fail

Pull network field-by-field copy-in updates from Al Viro:
 "This part of the misc compat queue was held back for review from
  networking folks and since davem has jus ACKed those..."

* 'misc.compat' of git://git.kernel.org/pub/scm/linux/kernel/git/viro/vfs:
  get_compat_bpf_fprog(): don't copyin field-by-field
  get_compat_msghdr(): get rid of field-by-field copyin
  copy_msghdr_from_user(): get rid of field-by-field copyin

Pull MIPS updates from Ralf Baechle:
 "Boston platform support:
   - Document DT bindings
   - Add CLK driver for board clocks

  CM:
   - Avoid per-core locking with CM3 & higher
   - WARN on attempt to lock invalid VP, not BUG

  CPS:
   - Select CONFIG_SYS_SUPPORTS_SCHED_SMT for MIPSr6
   - Prevent multi-core with dcache aliasing
   - Handle cores not powering down more gracefully
   - Handle spurious VP starts more gracefully

  DSP:
   - Add lwx & lhx missaligned access support

  eBPF:
   - Add MIPS support along with many supporting change to add the
     required infrastructure

  Generic arch code:
   - Misc sysmips MIPS_ATOMIC_SET fixes
   - Drop duplicate HAVE_SYSCALL_TRACEPOINTS
   - Negate error syscall return in trace
   - Correct forced syscall errors
   - Traced negative syscalls should return -ENOSYS
   - Allow samples/bpf/tracex5 to access syscall arguments for sane
     traces
   - Cleanup from old Kconfig options in defconfigs
   - Fix PREF instruction usage by memcpy for MIPS R6
   - Fix various special cases in the FPU eulation
   - Fix some special cases in MIPS16e2 support
   - Fix MIPS I ISA /proc/cpuinfo reporting
   - Sort MIPS Kconfig alphabetically
   - Fix minimum alignment requirement of IRQ stack as required by
     ABI / GCC
   - Fix special cases in the module loader
   - Perform post-DMA cache flushes on systems with MAARs
   - Probe the I6500 CPU
   - Cleanup cmpxchg and add support for 1 and 2 byte operations
   - Use queued read/write locks (qrwlock)
   - Use queued spinlocks (qspinlock)
   - Add CPU shared FTLB feature detection
   - Handle tlbex-tlbp race condition
   - Allow storing pgd in C0_CONTEXT for MIPSr6
   - Use current_cpu_type() in m4kc_tlbp_war()
   - Support Boston in the generic kernel

  Generic platform:
   - yamon-dt: Pull YAMON DT shim code out of SEAD-3 board
   - yamon-dt: Support > 256MB of RAM
   - yamon-dt: Use serial* rather than uart* aliases
   - Abstract FDT fixup application
   - Set RTC_ALWAYS_BCD to 0
   - Add a MAINTAINERS entry

  core kernel:
   - qspinlock.c: include linux/prefetch.h

  Loongson 3:
   - Add support

  Perf:
   - Add I6500 support

  SEAD-3:
   - Remove GIC timer from DT
   - Set interrupt-parent per-device, not at root node
   - Fix GIC interrupt specifiers

  SMP:
   - Skip IPI setup if we only have a single CPU

  VDSO:
   - Make comment match reality
   - Improvements to time code in VDSO"

* 'upstream' of git://git.linux-mips.org/pub/scm/ralf/upstream-linus: (86 commits)
  locking/qspinlock: Include linux/prefetch.h
  MIPS: Fix MIPS I ISA /proc/cpuinfo reporting
  MIPS: Fix minimum alignment requirement of IRQ stack
  MIPS: generic: Support MIPS Boston development boards
  MIPS: DTS: img: Don't attempt to build-in all .dtb files
  clk: boston: Add a driver for MIPS Boston board clocks
  dt-bindings: Document img,boston-clock binding
  MIPS: Traced negative syscalls should return -ENOSYS
  MIPS: Correct forced syscall errors
  MIPS: Negate error syscall return in trace
  MIPS: Drop duplicate HAVE_SYSCALL_TRACEPOINTS select
  MIPS16e2: Provide feature overrides for non-MIPS16 systems
  MIPS: MIPS16e2: Report ASE presence in /proc/cpuinfo
  MIPS: MIPS16e2: Subdecode extended LWSP/SWSP instructions
  MIPS: MIPS16e2: Identify ASE presence
  MIPS: VDSO: Fix a mismatch between comment and preprocessor constant
  MIPS: VDSO: Add implementation of gettimeofday() fallback
  MIPS: VDSO: Add implementation of clock_gettime() fallback
  MIPS: VDSO: Fix conversions in do_monotonic()/do_monotonic_coarse()
  MIPS: Use current_cpu_type() in m4kc_tlbp_war()
  ...

Pull UML updates from Richard Weinberger:
 "Mostly fixes for UML:

   - First round of fixes for PTRACE_GETRESET/SETREGSET

   - A printf vs printk cleanup

   - Minor improvements"

* 'for-linus-4.13-rc1' of git://git.kernel.org/pub/scm/linux/kernel/git/rw/uml:
  um: Correctly check for PTRACE_GETRESET/SETREGSET
  um: v2: Use generic NOTES macro
  um: Add kerneldoc for userspace_tramp() and start_userspace()
  um: Add kerneldoc for segv_handler
  um: stub-data.h: remove superfluous include
  um: userspace - be more verbose in ptrace set regs error
  um: add dummy ioremap and iounmap functions
  um: Allow building and running on older hosts
  um: Avoid longjmp/setjmp symbol clashes with libpthread.a
  um: console: Ignore console= option
  um: Use os_warn to print out pre-boot warning/error messages
  um: Add os_warn() for pre-boot warning/error messages
  um: Use os_info for the messages on normal path
  um: Add os_info() for pre-boot information messages
  um: Use printk instead of printf in make_uml_dir

Pull UBIFS updates from Richard Weinberger:

 - Updates and fixes for the file encryption mode

 - Minor improvements

 - Random fixes

* tag 'upstream-4.13-rc1' of git://git.infradead.org/linux-ubifs:
  ubifs: Set double hash cookie also for RENAME_EXCHANGE
  ubifs: Massage assert in ubifs_xattr_set() wrt. init_xattrs
  ubifs: Don't leak kernel memory to the MTD
  ubifs: Change gfp flags in page allocation for bulk read
  ubifs: Fix oops when remounting with no_bulk_read.
  ubifs: Fail commit if TNC is obviously inconsistent
  ubifs: allow userspace to map mounts to volumes
  ubifs: Wire-up statx() support
  ubifs: Remove dead code from ubifs_get_link()
  ubifs: Massage debug prints wrt. fscrypt
  ubifs: Add assert to dent_key_init()
  ubifs: Fix unlink code wrt. double hash lookups
  ubifs: Fix data node size for truncating uncompressed nodes
  ubifs: Don't encrypt special files on creation
  ubifs: Fix memory leak in RENAME_WHITEOUT error path in do_rename
  ubifs: Fix inode data budget in ubifs_mknod
  ubifs: Correctly evict xattr inodes
  ubifs: Unexport ubifs_inode_slab
  ubifs: don't bother checking for encryption key in ->mmap()
  ubifs: require key for truncate(2) of encrypted file

Pull more KVM updates from Radim Krčmář:
 "Second batch of KVM updates for v4.13

  Common:
   - add uevents for VM creation/destruction
   - annotate and properly access RCU-protected objects

  s390:
   - rename IOCTL added in the first v4.13 merge

  x86:
   - emulate VMLOAD VMSAVE feature in SVM
   - support paravirtual asynchronous page fault while nested
   - add Hyper-V userspace interfaces for better migration
   - improve master clock corner cases
   - extend internal error reporting after EPT misconfig
   - correct single-stepping of emulated instructions in SVM
   - handle MCE during VM entry
   - fix nVMX VM entry checks and nVMX VMCS shadowing"

* tag 'kvm-4.13-2' of git://git.kernel.org/pub/scm/virt/kvm/kvm: (28 commits)
  kvm: x86: hyperv: make VP_INDEX managed by userspace
  KVM: async_pf: Let guest support delivery of async_pf from guest mode
  KVM: async_pf: Force a nested vmexit if the injected #PF is async_pf
  KVM: async_pf: Add L1 guest async_pf #PF vmexit handler
  KVM: x86: Simplify kvm_x86_ops->queue_exception parameter list
  kvm: x86: hyperv: add KVM_CAP_HYPERV_SYNIC2
  KVM: x86: make backwards_tsc_observed a per-VM variable
  KVM: trigger uevents when creating or destroying a VM
  KVM: SVM: Enable Virtual VMLOAD VMSAVE feature
  KVM: SVM: Add Virtual VMLOAD VMSAVE feature definition
  KVM: SVM: Rename lbr_ctl field in the vmcb control area
  KVM: SVM: Prepare for new bit definition in lbr_ctl
  KVM: SVM: handle singlestep exception when skipping emulated instructions
  KVM: x86: take slots_lock in kvm_free_pit
  KVM: s390: Fix KVM_S390_GET_CMMA_BITS ioctl definition
  kvm: vmx: Properly handle machine check during VM-entry
  KVM: x86: update master clock before computing kvmclock_offset
  kvm: nVMX: Shadow "high" parts of shadowed 64-bit VMCS fields
  kvm: nVMX: Fix nested_vmx_check_msr_bitmap_controls
  kvm: nVMX: Validate the I/O bitmaps on nested VM-entry
  ...