docs-rst: create an user's manual book
Place README, REPORTING-BUGS, SecurityBugs and kernel-parameters
on an user's manual book.
As we'll be numbering the user's manual, remove the manual
numbering from SecurityBugs.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
diff --git a/Documentation/admin-guide/README.rst b/Documentation/admin-guide/README.rst
new file mode 100644
index 0000000..05aad85
--- /dev/null
+++ b/Documentation/admin-guide/README.rst
@@ -0,0 +1,410 @@
+Linux kernel release 4.x <http://kernel.org/>
+=============================================
+
+These are the release notes for Linux version 4. Read them carefully,
+as they tell you what this is all about, explain how to install the
+kernel, and what to do if something goes wrong.
+
+What is Linux?
+--------------
+
+ Linux is a clone of the operating system Unix, written from scratch by
+ Linus Torvalds with assistance from a loosely-knit team of hackers across
+ the Net. It aims towards POSIX and Single UNIX Specification compliance.
+
+ It has all the features you would expect in a modern fully-fledged Unix,
+ including true multitasking, virtual memory, shared libraries, demand
+ loading, shared copy-on-write executables, proper memory management,
+ and multistack networking including IPv4 and IPv6.
+
+ It is distributed under the GNU General Public License - see the
+ accompanying COPYING file for more details.
+
+On what hardware does it run?
+-----------------------------
+
+ Although originally developed first for 32-bit x86-based PCs (386 or higher),
+ today Linux also runs on (at least) the Compaq Alpha AXP, Sun SPARC and
+ UltraSPARC, Motorola 68000, PowerPC, PowerPC64, ARM, Hitachi SuperH, Cell,
+ IBM S/390, MIPS, HP PA-RISC, Intel IA-64, DEC VAX, AMD x86-64, AXIS CRIS,
+ Xtensa, Tilera TILE, AVR32, ARC and Renesas M32R architectures.
+
+ Linux is easily portable to most general-purpose 32- or 64-bit architectures
+ as long as they have a paged memory management unit (PMMU) and a port of the
+ GNU C compiler (gcc) (part of The GNU Compiler Collection, GCC). Linux has
+ also been ported to a number of architectures without a PMMU, although
+ functionality is then obviously somewhat limited.
+ Linux has also been ported to itself. You can now run the kernel as a
+ userspace application - this is called UserMode Linux (UML).
+
+Documentation
+-------------
+
+ - There is a lot of documentation available both in electronic form on
+ the Internet and in books, both Linux-specific and pertaining to
+ general UNIX questions. I'd recommend looking into the documentation
+ subdirectories on any Linux FTP site for the LDP (Linux Documentation
+ Project) books. This README is not meant to be documentation on the
+ system: there are much better sources available.
+
+ - There are various README files in the Documentation/ subdirectory:
+ these typically contain kernel-specific installation notes for some
+ drivers for example. See Documentation/00-INDEX for a list of what
+ is contained in each file. Please read the Changes file, as it
+ contains information about the problems, which may result by upgrading
+ your kernel.
+
+ - The Documentation/DocBook/ subdirectory contains several guides for
+ kernel developers and users. These guides can be rendered in a
+ number of formats: PostScript (.ps), PDF, HTML, & man-pages, among others.
+ After installation, ``make psdocs``, ``make pdfdocs``, ``make htmldocs``,
+ or ``make mandocs`` will render the documentation in the requested format.
+
+Installing the kernel source
+----------------------------
+
+ - If you install the full sources, put the kernel tarball in a
+ directory where you have permissions (e.g. your home directory) and
+ unpack it::
+
+ xz -cd linux-4.X.tar.xz | tar xvf -
+
+ Replace "X" with the version number of the latest kernel.
+
+ Do NOT use the /usr/src/linux area! This area has a (usually
+ incomplete) set of kernel headers that are used by the library header
+ files. They should match the library, and not get messed up by
+ whatever the kernel-du-jour happens to be.
+
+ - You can also upgrade between 4.x releases by patching. Patches are
+ distributed in the xz format. To install by patching, get all the
+ newer patch files, enter the top level directory of the kernel source
+ (linux-4.X) and execute::
+
+ xz -cd ../patch-4.x.xz | patch -p1
+
+ Replace "x" for all versions bigger than the version "X" of your current
+ source tree, **in_order**, and you should be ok. You may want to remove
+ the backup files (some-file-name~ or some-file-name.orig), and make sure
+ that there are no failed patches (some-file-name# or some-file-name.rej).
+ If there are, either you or I have made a mistake.
+
+ Unlike patches for the 4.x kernels, patches for the 4.x.y kernels
+ (also known as the -stable kernels) are not incremental but instead apply
+ directly to the base 4.x kernel. For example, if your base kernel is 4.0
+ and you want to apply the 4.0.3 patch, you must not first apply the 4.0.1
+ and 4.0.2 patches. Similarly, if you are running kernel version 4.0.2 and
+ want to jump to 4.0.3, you must first reverse the 4.0.2 patch (that is,
+ patch -R) **before** applying the 4.0.3 patch. You can read more on this in
+ :ref:`Documentation/applying-patches.txt <applying_patches>`.
+
+ Alternatively, the script patch-kernel can be used to automate this
+ process. It determines the current kernel version and applies any
+ patches found::
+
+ linux/scripts/patch-kernel linux
+
+ The first argument in the command above is the location of the
+ kernel source. Patches are applied from the current directory, but
+ an alternative directory can be specified as the second argument.
+
+ - Make sure you have no stale .o files and dependencies lying around::
+
+ cd linux
+ make mrproper
+
+ You should now have the sources correctly installed.
+
+Software requirements
+---------------------
+
+ Compiling and running the 4.x kernels requires up-to-date
+ versions of various software packages. Consult
+ :ref:`Documentation/Changes <changes>` for the minimum version numbers
+ required and how to get updates for these packages. Beware that using
+ excessively old versions of these packages can cause indirect
+ errors that are very difficult to track down, so don't assume that
+ you can just update packages when obvious problems arise during
+ build or operation.
+
+Build directory for the kernel
+------------------------------
+
+ When compiling the kernel, all output files will per default be
+ stored together with the kernel source code.
+ Using the option ``make O=output/dir`` allows you to specify an alternate
+ place for the output files (including .config).
+ Example::
+
+ kernel source code: /usr/src/linux-4.X
+ build directory: /home/name/build/kernel
+
+ To configure and build the kernel, use::
+
+ cd /usr/src/linux-4.X
+ make O=/home/name/build/kernel menuconfig
+ make O=/home/name/build/kernel
+ sudo make O=/home/name/build/kernel modules_install install
+
+ Please note: If the ``O=output/dir`` option is used, then it must be
+ used for all invocations of make.
+
+Configuring the kernel
+----------------------
+
+ Do not skip this step even if you are only upgrading one minor
+ version. New configuration options are added in each release, and
+ odd problems will turn up if the configuration files are not set up
+ as expected. If you want to carry your existing configuration to a
+ new version with minimal work, use ``make oldconfig``, which will
+ only ask you for the answers to new questions.
+
+ - Alternative configuration commands are::
+
+ "make config" Plain text interface.
+
+ "make menuconfig" Text based color menus, radiolists & dialogs.
+
+ "make nconfig" Enhanced text based color menus.
+
+ "make xconfig" Qt based configuration tool.
+
+ "make gconfig" GTK+ based configuration tool.
+
+ "make oldconfig" Default all questions based on the contents of
+ your existing ./.config file and asking about
+ new config symbols.
+
+ "make silentoldconfig"
+ Like above, but avoids cluttering the screen
+ with questions already answered.
+ Additionally updates the dependencies.
+
+ "make olddefconfig"
+ Like above, but sets new symbols to their default
+ values without prompting.
+
+ "make defconfig" Create a ./.config file by using the default
+ symbol values from either arch/$ARCH/defconfig
+ or arch/$ARCH/configs/${PLATFORM}_defconfig,
+ depending on the architecture.
+
+ "make ${PLATFORM}_defconfig"
+ Create a ./.config file by using the default
+ symbol values from
+ arch/$ARCH/configs/${PLATFORM}_defconfig.
+ Use "make help" to get a list of all available
+ platforms of your architecture.
+
+ "make allyesconfig"
+ Create a ./.config file by setting symbol
+ values to 'y' as much as possible.
+
+ "make allmodconfig"
+ Create a ./.config file by setting symbol
+ values to 'm' as much as possible.
+
+ "make allnoconfig" Create a ./.config file by setting symbol
+ values to 'n' as much as possible.
+
+ "make randconfig" Create a ./.config file by setting symbol
+ values to random values.
+
+ "make localmodconfig" Create a config based on current config and
+ loaded modules (lsmod). Disables any module
+ option that is not needed for the loaded modules.
+
+ To create a localmodconfig for another machine,
+ store the lsmod of that machine into a file
+ and pass it in as a LSMOD parameter.
+
+ target$ lsmod > /tmp/mylsmod
+ target$ scp /tmp/mylsmod host:/tmp
+
+ host$ make LSMOD=/tmp/mylsmod localmodconfig
+
+ The above also works when cross compiling.
+
+ "make localyesconfig" Similar to localmodconfig, except it will convert
+ all module options to built in (=y) options.
+
+ You can find more information on using the Linux kernel config tools
+ in Documentation/kbuild/kconfig.txt.
+
+ - NOTES on ``make config``:
+
+ - Having unnecessary drivers will make the kernel bigger, and can
+ under some circumstances lead to problems: probing for a
+ nonexistent controller card may confuse your other controllers
+
+ - A kernel with math-emulation compiled in will still use the
+ coprocessor if one is present: the math emulation will just
+ never get used in that case. The kernel will be slightly larger,
+ but will work on different machines regardless of whether they
+ have a math coprocessor or not.
+
+ - The "kernel hacking" configuration details usually result in a
+ bigger or slower kernel (or both), and can even make the kernel
+ less stable by configuring some routines to actively try to
+ break bad code to find kernel problems (kmalloc()). Thus you
+ should probably answer 'n' to the questions for "development",
+ "experimental", or "debugging" features.
+
+Compiling the kernel
+--------------------
+
+ - Make sure you have at least gcc 3.2 available.
+ For more information, refer to :ref:`Documentation/Changes <changes>`.
+
+ Please note that you can still run a.out user programs with this kernel.
+
+ - Do a ``make`` to create a compressed kernel image. It is also
+ possible to do ``make install`` if you have lilo installed to suit the
+ kernel makefiles, but you may want to check your particular lilo setup first.
+
+ To do the actual install, you have to be root, but none of the normal
+ build should require that. Don't take the name of root in vain.
+
+ - If you configured any of the parts of the kernel as ``modules``, you
+ will also have to do ``make modules_install``.
+
+ - Verbose kernel compile/build output:
+
+ Normally, the kernel build system runs in a fairly quiet mode (but not
+ totally silent). However, sometimes you or other kernel developers need
+ to see compile, link, or other commands exactly as they are executed.
+ For this, use "verbose" build mode. This is done by passing
+ ``V=1`` to the ``make`` command, e.g.::
+
+ make V=1 all
+
+ To have the build system also tell the reason for the rebuild of each
+ target, use ``V=2``. The default is ``V=0``.
+
+ - Keep a backup kernel handy in case something goes wrong. This is
+ especially true for the development releases, since each new release
+ contains new code which has not been debugged. Make sure you keep a
+ backup of the modules corresponding to that kernel, as well. If you
+ are installing a new kernel with the same version number as your
+ working kernel, make a backup of your modules directory before you
+ do a ``make modules_install``.
+
+ Alternatively, before compiling, use the kernel config option
+ "LOCALVERSION" to append a unique suffix to the regular kernel version.
+ LOCALVERSION can be set in the "General Setup" menu.
+
+ - In order to boot your new kernel, you'll need to copy the kernel
+ image (e.g. .../linux/arch/x86/boot/bzImage after compilation)
+ to the place where your regular bootable kernel is found.
+
+ - Booting a kernel directly from a floppy without the assistance of a
+ bootloader such as LILO, is no longer supported.
+
+ If you boot Linux from the hard drive, chances are you use LILO, which
+ uses the kernel image as specified in the file /etc/lilo.conf. The
+ kernel image file is usually /vmlinuz, /boot/vmlinuz, /bzImage or
+ /boot/bzImage. To use the new kernel, save a copy of the old image
+ and copy the new image over the old one. Then, you MUST RERUN LILO
+ to update the loading map! If you don't, you won't be able to boot
+ the new kernel image.
+
+ Reinstalling LILO is usually a matter of running /sbin/lilo.
+ You may wish to edit /etc/lilo.conf to specify an entry for your
+ old kernel image (say, /vmlinux.old) in case the new one does not
+ work. See the LILO docs for more information.
+
+ After reinstalling LILO, you should be all set. Shutdown the system,
+ reboot, and enjoy!
+
+ If you ever need to change the default root device, video mode,
+ ramdisk size, etc. in the kernel image, use the ``rdev`` program (or
+ alternatively the LILO boot options when appropriate). No need to
+ recompile the kernel to change these parameters.
+
+ - Reboot with the new kernel and enjoy.
+
+If something goes wrong
+-----------------------
+
+ - If you have problems that seem to be due to kernel bugs, please check
+ the file MAINTAINERS to see if there is a particular person associated
+ with the part of the kernel that you are having trouble with. If there
+ isn't anyone listed there, then the second best thing is to mail
+ them to me (torvalds@linux-foundation.org), and possibly to any other
+ relevant mailing-list or to the newsgroup.
+
+ - In all bug-reports, *please* tell what kernel you are talking about,
+ how to duplicate the problem, and what your setup is (use your common
+ sense). If the problem is new, tell me so, and if the problem is
+ old, please try to tell me when you first noticed it.
+
+ - If the bug results in a message like::
+
+ unable to handle kernel paging request at address C0000010
+ Oops: 0002
+ EIP: 0010:XXXXXXXX
+ eax: xxxxxxxx ebx: xxxxxxxx ecx: xxxxxxxx edx: xxxxxxxx
+ esi: xxxxxxxx edi: xxxxxxxx ebp: xxxxxxxx
+ ds: xxxx es: xxxx fs: xxxx gs: xxxx
+ Pid: xx, process nr: xx
+ xx xx xx xx xx xx xx xx xx xx
+
+ or similar kernel debugging information on your screen or in your
+ system log, please duplicate it *exactly*. The dump may look
+ incomprehensible to you, but it does contain information that may
+ help debugging the problem. The text above the dump is also
+ important: it tells something about why the kernel dumped code (in
+ the above example, it's due to a bad kernel pointer). More information
+ on making sense of the dump is in Documentation/oops-tracing.txt
+
+ - If you compiled the kernel with CONFIG_KALLSYMS you can send the dump
+ as is, otherwise you will have to use the ``ksymoops`` program to make
+ sense of the dump (but compiling with CONFIG_KALLSYMS is usually preferred).
+ This utility can be downloaded from
+ ftp://ftp.<country>.kernel.org/pub/linux/utils/kernel/ksymoops/ .
+ Alternatively, you can do the dump lookup by hand:
+
+ - In debugging dumps like the above, it helps enormously if you can
+ look up what the EIP value means. The hex value as such doesn't help
+ me or anybody else very much: it will depend on your particular
+ kernel setup. What you should do is take the hex value from the EIP
+ line (ignore the ``0010:``), and look it up in the kernel namelist to
+ see which kernel function contains the offending address.
+
+ To find out the kernel function name, you'll need to find the system
+ binary associated with the kernel that exhibited the symptom. This is
+ the file 'linux/vmlinux'. To extract the namelist and match it against
+ the EIP from the kernel crash, do::
+
+ nm vmlinux | sort | less
+
+ This will give you a list of kernel addresses sorted in ascending
+ order, from which it is simple to find the function that contains the
+ offending address. Note that the address given by the kernel
+ debugging messages will not necessarily match exactly with the
+ function addresses (in fact, that is very unlikely), so you can't
+ just 'grep' the list: the list will, however, give you the starting
+ point of each kernel function, so by looking for the function that
+ has a starting address lower than the one you are searching for but
+ is followed by a function with a higher address you will find the one
+ you want. In fact, it may be a good idea to include a bit of
+ "context" in your problem report, giving a few lines around the
+ interesting one.
+
+ If you for some reason cannot do the above (you have a pre-compiled
+ kernel image or similar), telling me as much about your setup as
+ possible will help. Please read the :ref:`REPORTING-BUGS <reportingbugs>`
+ document for details.
+
+ - Alternatively, you can use gdb on a running kernel. (read-only; i.e. you
+ cannot change values or set break points.) To do this, first compile the
+ kernel with -g; edit arch/x86/Makefile appropriately, then do a ``make
+ clean``. You'll also need to enable CONFIG_PROC_FS (via ``make config``).
+
+ After you've rebooted with the new kernel, do ``gdb vmlinux /proc/kcore``.
+ You can now use all the usual gdb commands. The command to look up the
+ point where your system crashed is ``l *0xXXXXXXXX``. (Replace the XXXes
+ with the EIP value.)
+
+ gdb'ing a non-running kernel currently fails because ``gdb`` (wrongly)
+ disregards the starting offset for which the kernel is compiled.
diff --git a/Documentation/bad_memory.txt b/Documentation/admin-guide/bad-memory.rst
similarity index 99%
rename from Documentation/bad_memory.txt
rename to Documentation/admin-guide/bad-memory.rst
index 5cac93e..017fc86 100644
--- a/Documentation/bad_memory.txt
+++ b/Documentation/admin-guide/bad-memory.rst
@@ -48,4 +48,3 @@
or::
memmap=0x10000$0x18690000
-
diff --git a/Documentation/basic_profiling.txt b/Documentation/admin-guide/basic-profiling.rst
similarity index 99%
rename from Documentation/basic_profiling.txt
rename to Documentation/admin-guide/basic-profiling.rst
index 15a49db..72babc7 100644
--- a/Documentation/basic_profiling.txt
+++ b/Documentation/admin-guide/basic-profiling.rst
@@ -66,4 +66,3 @@
To only report on the kernel, run ``opreport -l /boot/vmlinux > output_file``
A reset is needed to clear old statistics, which survive a reboot.
-
diff --git a/Documentation/binfmt_misc.txt b/Documentation/admin-guide/binfmt-misc.rst
similarity index 100%
rename from Documentation/binfmt_misc.txt
rename to Documentation/admin-guide/binfmt-misc.rst
diff --git a/Documentation/braille-console.txt b/Documentation/admin-guide/braille-console.rst
similarity index 100%
rename from Documentation/braille-console.txt
rename to Documentation/admin-guide/braille-console.rst
diff --git a/Documentation/BUG-HUNTING b/Documentation/admin-guide/bug-hunting.rst
similarity index 100%
rename from Documentation/BUG-HUNTING
rename to Documentation/admin-guide/bug-hunting.rst
diff --git a/Documentation/admin-guide/conf.py b/Documentation/admin-guide/conf.py
new file mode 100644
index 0000000..86f7389
--- /dev/null
+++ b/Documentation/admin-guide/conf.py
@@ -0,0 +1,10 @@
+# -*- coding: utf-8; mode: python -*-
+
+project = 'Linux Kernel User Documentation'
+
+tags.add("subproject")
+
+latex_documents = [
+ ('index', 'linux-user.tex', 'Linux Kernel User Documentation',
+ 'The kernel development community', 'manual'),
+]
diff --git a/Documentation/devices.txt b/Documentation/admin-guide/devices.rst
similarity index 99%
rename from Documentation/devices.txt
rename to Documentation/admin-guide/devices.rst
index 17b3653..b295550 100644
--- a/Documentation/devices.txt
+++ b/Documentation/admin-guide/devices.rst
@@ -3348,4 +3348,3 @@
in our notation). This removes the problem of exhausting the
namespace and enables the kernel to automatically create the device
nodes for the slaves on demand using the "devpts" filesystem.
-
diff --git a/Documentation/dynamic-debug-howto.txt b/Documentation/admin-guide/dynamic-debug-howto.rst
similarity index 100%
rename from Documentation/dynamic-debug-howto.txt
rename to Documentation/admin-guide/dynamic-debug-howto.rst
diff --git a/Documentation/admin-guide/index.rst b/Documentation/admin-guide/index.rst
new file mode 100644
index 0000000..4e5abbb
--- /dev/null
+++ b/Documentation/admin-guide/index.rst
@@ -0,0 +1,34 @@
+Linux Kernel User's Documentation
+=================================
+
+Contents:
+
+.. toctree::
+ :maxdepth: 2
+ :numbered:
+
+ README
+ reporting-bugs
+ bug-hunting
+ oops-tracing
+ ramoops
+ initrd
+ init
+ dynamic-debug-howto
+ security-bugs
+ kernel-parameters
+ serial-console
+ braille-console
+ parport
+ md
+ module-signing
+ sysrq
+ unicode
+ vga-softcursor
+ sysfs-rules
+ devices
+ binfmt-misc
+ mono
+ java
+ bad-memory
+ basic-profiling
diff --git a/Documentation/init.txt b/Documentation/admin-guide/init.rst
similarity index 100%
rename from Documentation/init.txt
rename to Documentation/admin-guide/init.rst
diff --git a/Documentation/initrd.txt b/Documentation/admin-guide/initrd.rst
similarity index 100%
rename from Documentation/initrd.txt
rename to Documentation/admin-guide/initrd.rst
diff --git a/Documentation/java.txt b/Documentation/admin-guide/java.rst
similarity index 99%
rename from Documentation/java.txt
rename to Documentation/admin-guide/java.rst
index ae33d95..a0de7c1 100644
--- a/Documentation/java.txt
+++ b/Documentation/admin-guide/java.rst
@@ -415,4 +415,3 @@
heavily edited for binfmt_misc by Richard Günther
new scripts by Colin J. Watson <cjw44@cam.ac.uk>
added executable Jar file support by Kurt Huwig <kurt@iku-netz.de>
-
diff --git a/Documentation/kernel-parameters.txt b/Documentation/admin-guide/kernel-parameters.rst
similarity index 100%
rename from Documentation/kernel-parameters.txt
rename to Documentation/admin-guide/kernel-parameters.rst
diff --git a/Documentation/md.txt b/Documentation/admin-guide/md.rst
similarity index 100%
rename from Documentation/md.txt
rename to Documentation/admin-guide/md.rst
diff --git a/Documentation/mono.txt b/Documentation/admin-guide/mono.rst
similarity index 100%
rename from Documentation/mono.txt
rename to Documentation/admin-guide/mono.rst
diff --git a/Documentation/oops-tracing.txt b/Documentation/admin-guide/oops-tracing.rst
similarity index 100%
rename from Documentation/oops-tracing.txt
rename to Documentation/admin-guide/oops-tracing.rst
diff --git a/Documentation/parport.txt b/Documentation/admin-guide/parport.rst
similarity index 100%
rename from Documentation/parport.txt
rename to Documentation/admin-guide/parport.rst
diff --git a/Documentation/ramoops.txt b/Documentation/admin-guide/ramoops.rst
similarity index 100%
rename from Documentation/ramoops.txt
rename to Documentation/admin-guide/ramoops.rst
diff --git a/Documentation/admin-guide/reporting-bugs.rst b/Documentation/admin-guide/reporting-bugs.rst
new file mode 100644
index 0000000..05c53ac
--- /dev/null
+++ b/Documentation/admin-guide/reporting-bugs.rst
@@ -0,0 +1,182 @@
+.. _reportingbugs:
+
+Reporting bugs
+++++++++++++++
+
+Background
+==========
+
+The upstream Linux kernel maintainers only fix bugs for specific kernel
+versions. Those versions include the current "release candidate" (or -rc)
+kernel, any "stable" kernel versions, and any "long term" kernels.
+
+Please see https://www.kernel.org/ for a list of supported kernels. Any
+kernel marked with [EOL] is "end of life" and will not have any fixes
+backported to it.
+
+If you've found a bug on a kernel version that isn't listed on kernel.org,
+contact your Linux distribution or embedded vendor for support.
+Alternatively, you can attempt to run one of the supported stable or -rc
+kernels, and see if you can reproduce the bug on that. It's preferable
+to reproduce the bug on the latest -rc kernel.
+
+
+How to report Linux kernel bugs
+===============================
+
+
+Identify the problematic subsystem
+----------------------------------
+
+Identifying which part of the Linux kernel might be causing your issue
+increases your chances of getting your bug fixed. Simply posting to the
+generic linux-kernel mailing list (LKML) may cause your bug report to be
+lost in the noise of a mailing list that gets 1000+ emails a day.
+
+Instead, try to figure out which kernel subsystem is causing the issue,
+and email that subsystem's maintainer and mailing list. If the subsystem
+maintainer doesn't answer, then expand your scope to mailing lists like
+LKML.
+
+
+Identify who to notify
+----------------------
+
+Once you know the subsystem that is causing the issue, you should send a
+bug report. Some maintainers prefer bugs to be reported via bugzilla
+(https://bugzilla.kernel.org), while others prefer that bugs be reported
+via the subsystem mailing list.
+
+To find out where to send an emailed bug report, find your subsystem or
+device driver in the MAINTAINERS file. Search in the file for relevant
+entries, and send your bug report to the person(s) listed in the "M:"
+lines, making sure to Cc the mailing list(s) in the "L:" lines. When the
+maintainer replies to you, make sure to 'Reply-all' in order to keep the
+public mailing list(s) in the email thread.
+
+If you know which driver is causing issues, you can pass one of the driver
+files to the get_maintainer.pl script::
+
+ perl scripts/get_maintainer.pl -f <filename>
+
+If it is a security bug, please copy the Security Contact listed in the
+MAINTAINERS file. They can help coordinate bugfix and disclosure. See
+:ref:`Documentation/SecurityBugs <securitybugs>` for more information.
+
+If you can't figure out which subsystem caused the issue, you should file
+a bug in kernel.org bugzilla and send email to
+linux-kernel@vger.kernel.org, referencing the bugzilla URL. (For more
+information on the linux-kernel mailing list see
+http://www.tux.org/lkml/).
+
+
+Tips for reporting bugs
+-----------------------
+
+If you haven't reported a bug before, please read:
+
+ http://www.chiark.greenend.org.uk/~sgtatham/bugs.html
+
+ http://www.catb.org/esr/faqs/smart-questions.html
+
+It's REALLY important to report bugs that seem unrelated as separate email
+threads or separate bugzilla entries. If you report several unrelated
+bugs at once, it's difficult for maintainers to tease apart the relevant
+data.
+
+
+Gather information
+------------------
+
+The most important information in a bug report is how to reproduce the
+bug. This includes system information, and (most importantly)
+step-by-step instructions for how a user can trigger the bug.
+
+If the failure includes an "OOPS:", take a picture of the screen, capture
+a netconsole trace, or type the message from your screen into the bug
+report. Please read "Documentation/oops-tracing.txt" before posting your
+bug report. This explains what you should do with the "Oops" information
+to make it useful to the recipient.
+
+This is a suggested format for a bug report sent via email or bugzilla.
+Having a standardized bug report form makes it easier for you not to
+overlook things, and easier for the developers to find the pieces of
+information they're really interested in. If some information is not
+relevant to your bug, feel free to exclude it.
+
+First run the ver_linux script included as scripts/ver_linux, which
+reports the version of some important subsystems. Run this script with
+the command ``sh scripts/ver_linux``.
+
+Use that information to fill in all fields of the bug report form, and
+post it to the mailing list with a subject of "PROBLEM: <one line
+summary from [1.]>" for easy identification by the developers::
+
+ [1.] One line summary of the problem:
+ [2.] Full description of the problem/report:
+ [3.] Keywords (i.e., modules, networking, kernel):
+ [4.] Kernel information
+ [4.1.] Kernel version (from /proc/version):
+ [4.2.] Kernel .config file:
+ [5.] Most recent kernel version which did not have the bug:
+ [6.] Output of Oops.. message (if applicable) with symbolic information
+ resolved (see Documentation/oops-tracing.txt)
+ [7.] A small shell script or example program which triggers the
+ problem (if possible)
+ [8.] Environment
+ [8.1.] Software (add the output of the ver_linux script here)
+ [8.2.] Processor information (from /proc/cpuinfo):
+ [8.3.] Module information (from /proc/modules):
+ [8.4.] Loaded driver and hardware information (/proc/ioports, /proc/iomem)
+ [8.5.] PCI information ('lspci -vvv' as root)
+ [8.6.] SCSI information (from /proc/scsi/scsi)
+ [8.7.] Other information that might be relevant to the problem
+ (please look in /proc and include all information that you
+ think to be relevant):
+ [X.] Other notes, patches, fixes, workarounds:
+
+
+Follow up
+=========
+
+Expectations for bug reporters
+------------------------------
+
+Linux kernel maintainers expect bug reporters to be able to follow up on
+bug reports. That may include running new tests, applying patches,
+recompiling your kernel, and/or re-triggering your bug. The most
+frustrating thing for maintainers is for someone to report a bug, and then
+never follow up on a request to try out a fix.
+
+That said, it's still useful for a kernel maintainer to know a bug exists
+on a supported kernel, even if you can't follow up with retests. Follow
+up reports, such as replying to the email thread with "I tried the latest
+kernel and I can't reproduce my bug anymore" are also helpful, because
+maintainers have to assume silence means things are still broken.
+
+Expectations for kernel maintainers
+-----------------------------------
+
+Linux kernel maintainers are busy, overworked human beings. Some times
+they may not be able to address your bug in a day, a week, or two weeks.
+If they don't answer your email, they may be on vacation, or at a Linux
+conference. Check the conference schedule at https://LWN.net for more info:
+
+ https://lwn.net/Calendar/
+
+In general, kernel maintainers take 1 to 5 business days to respond to
+bugs. The majority of kernel maintainers are employed to work on the
+kernel, and they may not work on the weekends. Maintainers are scattered
+around the world, and they may not work in your time zone. Unless you
+have a high priority bug, please wait at least a week after the first bug
+report before sending the maintainer a reminder email.
+
+The exceptions to this rule are regressions, kernel crashes, security holes,
+or userspace breakage caused by new kernel behavior. Those bugs should be
+addressed by the maintainers ASAP. If you suspect a maintainer is not
+responding to these types of bugs in a timely manner (especially during a
+merge window), escalate the bug to LKML and Linus Torvalds.
+
+Thank you!
+
+[Some of this is taken from Frohwalt Egerer's original linux-kernel FAQ]
diff --git a/Documentation/SecurityBugs b/Documentation/admin-guide/security-bugs.rst
similarity index 94%
rename from Documentation/SecurityBugs
rename to Documentation/admin-guide/security-bugs.rst
index 342d769..df795e2 100644
--- a/Documentation/SecurityBugs
+++ b/Documentation/admin-guide/security-bugs.rst
@@ -8,8 +8,8 @@
disclosed as quickly as possible. Please report security bugs to the
Linux kernel security team.
-1) Contact
-----------
+Contact
+-------
The Linux kernel security team can be contacted by email at
<security@kernel.org>. This is a private list of security officers
@@ -23,8 +23,8 @@
Any exploit code is very helpful and will not be released without
consent from the reporter unless it has already been made public.
-2) Disclosure
--------------
+Disclosure
+----------
The goal of the Linux kernel security team is to work with the
bug submitter to bug resolution as well as disclosure. We prefer
@@ -39,8 +39,8 @@
to a few weeks. As a basic default policy, we expect report date to
disclosure date to be on the order of 7 days.
-3) Non-disclosure agreements
-----------------------------
+Non-disclosure agreements
+-------------------------
The Linux kernel security team is not a formal body and therefore unable
to enter any non-disclosure agreements.
diff --git a/Documentation/serial-console.txt b/Documentation/admin-guide/serial-console.rst
similarity index 100%
rename from Documentation/serial-console.txt
rename to Documentation/admin-guide/serial-console.rst
diff --git a/Documentation/sysfs-rules.txt b/Documentation/admin-guide/sysfs-rules.rst
similarity index 100%
rename from Documentation/sysfs-rules.txt
rename to Documentation/admin-guide/sysfs-rules.rst
diff --git a/Documentation/sysrq.txt b/Documentation/admin-guide/sysrq.rst
similarity index 100%
rename from Documentation/sysrq.txt
rename to Documentation/admin-guide/sysrq.rst
diff --git a/Documentation/unicode.txt b/Documentation/admin-guide/unicode.rst
similarity index 100%
rename from Documentation/unicode.txt
rename to Documentation/admin-guide/unicode.rst
diff --git a/Documentation/VGA-softcursor.txt b/Documentation/admin-guide/vga-softcursor.rst
similarity index 100%
rename from Documentation/VGA-softcursor.txt
rename to Documentation/admin-guide/vga-softcursor.rst
diff --git a/Documentation/conf.py b/Documentation/conf.py
index b08e0c9..d9bad21 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -336,6 +336,8 @@
# (source start file, target name, title,
# author, documentclass [howto, manual, or own class]).
latex_documents = [
+ ('user/index', 'linux-user.tex', 'Linux Kernel User Documentation',
+ 'The kernel development community', 'manual'),
('kernel-documentation', 'kernel-documentation.tex', 'The Linux Kernel Documentation',
'The kernel development community', 'manual'),
('process/index', 'development-process.tex', 'Linux Kernel Development Documentation',
diff --git a/Documentation/index.rst b/Documentation/index.rst
index e1f18b3..f6a3d47 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -11,6 +11,7 @@
.. toctree::
:maxdepth: 2
+ admin-guide/index
kernel-documentation
process/index
dev-tools/tools
