Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]
Groups > linux.kernel > #1488805 > unrolled thread
| Started by | Mauro Carvalho Chehab <mchehab@s-opensource.com> |
|---|---|
| First post | 2016-09-22 13:50 +0200 |
| Last post | 2016-09-22 14:00 +0200 |
| Articles | 16 — 1 participant |
Back to article view | Back to linux.kernel
[PATCH 00/17] More files converted to ReST format Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-22 13:50 +0200
[PATCH 01/17] Documentation/applying-patches.txt: fix a bad external link Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-22 13:50 +0200
[PATCH 13/17] Documentation/serial-console.txt: convert it to ReST markup Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-22 13:50 +0200
[PATCH 09/17] Documentation/adding-syscalls.txt: convert it to ReST markup Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-22 13:50 +0200
[PATCH 02/17] Documentation/email-clients.txt: convert it to ReST markup Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-22 14:00 +0200
[PATCH 08/17] docs-rst: create an user's manual book Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-22 14:00 +0200
[PATCH 07/17] docs-rst: add documents to development-process Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-22 14:00 +0200
[PATCH 15/17] Documentation/BUG-HUNTING: convert to ReST markup Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-22 14:00 +0200
[PATCH 11/17] Documentation/basic_profiling.rst: convert to ReST markup Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-22 14:00 +0200
[PATCH 03/17] docs-rst: add inter-document cross references Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-22 14:00 +0200
[PATCH 06/17] Documentation/kernel-parameters.txt: convert to ReST markup Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-22 14:00 +0200
[PATCH 14/17] Documentation/braille-console: convert it to ReST markup Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-22 14:00 +0200
[PATCH 04/17] REPORTING-BUGS: convert to ReST markup Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-22 14:00 +0200
[PATCH 12/17] Documentation/binfmt_misc.txt: convert it to ReST markup Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-22 14:00 +0200
[PATCH 10/17] Documentation/bad_memory.txt: convert it to ReST markup Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-22 14:00 +0200
[PATCH 05/17] README: convert it to ReST markup Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-22 14:00 +0200
| From | Mauro Carvalho Chehab <mchehab@s-opensource.com> |
|---|---|
| Date | 2016-09-22 13:50 +0200 |
| Subject | [PATCH 00/17] More files converted to ReST format |
| Message-ID | <skaFP-5LW-1@gated-at.bofh.it> |
This series contain conversion of other files that, IMHO, belong to the development-process book or to an user manual book. Patch 1 is actually just a fixup; Patch 2 is actually patch 28/29 from my past series that weren' t applied because it was merging file renames on it; Patch 3 add ReST cross references for the already converted patches; patches 4, 5 and 6 convert README, REPORTING-BUGS and kernel-parameter.txt to be the basis of a Linux Kernel User' s manual; patch 7 add the already converted text files that are meant to be read by Linux developers at the development-process book; patch 8 creates the Linux Kernel User' s manual. The remaining patches convert generic documentation that, IMHO, belongs to either the "user" or "develoment" book. I'll keep working on converting those files, but we have already enough patches to be flushed to linux-doc and LKML :) Mauro Carvalho Chehab (17): Documentation/applying-patches.txt: fix a bad external link Documentation/email-clients.txt: convert it to ReST markup docs-rst: add inter-document cross references REPORTING-BUGS: convert to ReST markup README: convert it to ReST markup Documentation/kernel-parameters.txt: convert to ReST markup docs-rst: add documents to development-process docs-rst: create an user's manual book Documentation/adding-syscalls.txt: convert it to ReST markup Documentation/bad_memory.txt: convert it to ReST markup Documentation/basic_profiling.rst: convert to ReST markup Documentation/binfmt_misc.txt: convert it to ReST markup Documentation/serial-console.txt: convert it to ReST markup Documentation/braille-console: convert it to ReST markup Documentation/BUG-HUNTING: convert to ReST markup CodeOfConflict: add it to the development-process book Documentation/devices.rst: convert it to ReST markup Documentation/BUG-HUNTING | 162 +-- Documentation/CodeOfConflict | 1 + Documentation/SecurityBugs | 12 +- Documentation/SubmitChecklist | 10 +- Documentation/SubmittingDrivers | 7 +- Documentation/SubmittingPatches | 24 +- Documentation/adding-syscalls.txt | 263 ++--- Documentation/applying-patches.txt | 2 +- Documentation/bad_memory.txt | 26 +- Documentation/basic_profiling.txt | 59 +- Documentation/binfmt_misc.txt | 134 ++- Documentation/braille-console.txt | 30 +- Documentation/development-process/Changes.rst | 1 + .../development-process/CodeOfConflict.rst | 1 + Documentation/development-process/CodingStyle.rst | 1 + Documentation/development-process/HOWTO.rst | 1 + .../development-process/ManagementStyle.rst | 1 + .../development-process/SubmitChecklist.rst | 1 + .../development-process/SubmittingDrivers.rst | 1 + .../development-process/SubmittingPatches.rst | 1 + .../development-process/adding-syscalls.rst | 1 + .../development-process/applying-patches.rst | 1 + .../development-process/development-process.rst | 2 + .../development-process/email-clients.rst | 1 + Documentation/development-process/index.rst | 21 + Documentation/development-process/kernel-docs.rst | 1 + .../development-process/stable_api_nonsense.rst | 1 + .../development-process/stable_kernel_rules.rst | 1 + Documentation/devices.txt | 1090 ++++++++++---------- Documentation/email-clients.txt | 208 ++-- Documentation/index.rst | 1 + Documentation/kernel-parameters.txt | 33 +- Documentation/serial-console.txt | 68 +- Documentation/stable_kernel_rules.txt | 7 +- Documentation/user/BUG-HUNTING.rst | 1 + Documentation/user/README.rst | 1 + Documentation/user/REPORTING-BUGS.rst | 1 + Documentation/user/SecurityBugs.rst | 1 + Documentation/user/bad_memory.rst | 1 + Documentation/user/basic_profiling.rst | 1 + Documentation/user/binfmt_misc.rst | 1 + Documentation/user/braile-console.rst | 1 + Documentation/user/devices.rst | 1 + Documentation/user/index.rst | 20 + Documentation/user/kernel-parameters.rst | 1 + Documentation/user/serial-console.rst | 1 + README | 105 +- REPORTING-BUGS | 66 +- 48 files changed, 1297 insertions(+), 1079 deletions(-) create mode 120000 Documentation/development-process/Changes.rst create mode 120000 Documentation/development-process/CodeOfConflict.rst create mode 120000 Documentation/development-process/CodingStyle.rst create mode 120000 Documentation/development-process/HOWTO.rst create mode 120000 Documentation/development-process/ManagementStyle.rst create mode 120000 Documentation/development-process/SubmitChecklist.rst create mode 120000 Documentation/development-process/SubmittingDrivers.rst create mode 120000 Documentation/development-process/SubmittingPatches.rst create mode 120000 Documentation/development-process/adding-syscalls.rst create mode 120000 Documentation/development-process/applying-patches.rst create mode 120000 Documentation/development-process/email-clients.rst create mode 120000 Documentation/development-process/kernel-docs.rst create mode 120000 Documentation/development-process/stable_api_nonsense.rst create mode 120000 Documentation/development-process/stable_kernel_rules.rst create mode 120000 Documentation/user/BUG-HUNTING.rst create mode 120000 Documentation/user/README.rst create mode 120000 Documentation/user/REPORTING-BUGS.rst create mode 120000 Documentation/user/SecurityBugs.rst create mode 120000 Documentation/user/bad_memory.rst create mode 120000 Documentation/user/basic_profiling.rst create mode 120000 Documentation/user/binfmt_misc.rst create mode 120000 Documentation/user/braile-console.rst create mode 120000 Documentation/user/devices.rst create mode 100644 Documentation/user/index.rst create mode 120000 Documentation/user/kernel-parameters.rst create mode 120000 Documentation/user/serial-console.rst -- 2.7.4
[toc] | [next] | [standalone]
| From | Mauro Carvalho Chehab <mchehab@s-opensource.com> |
|---|---|
| Date | 2016-09-22 13:50 +0200 |
| Subject | [PATCH 01/17] Documentation/applying-patches.txt: fix a bad external link |
| Message-ID | <skaFQ-5LW-5@gated-at.bofh.it> |
| In reply to | #1488805 |
We can't use :ref: for external links. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> --- Documentation/applying-patches.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/applying-patches.txt b/Documentation/applying-patches.txt index 02ce4924468e..3395da13d415 100644 --- a/Documentation/applying-patches.txt +++ b/Documentation/applying-patches.txt @@ -427,7 +427,7 @@ The -mm patches are experimental patches released by Andrew Morton. In the past, -mm tree were used to also test subsystem patches, but this function is now done via the -:ref:`linux-next <https://www.kernel.org/doc/man-pages/linux-next.html>` +`linux-next <https://www.kernel.org/doc/man-pages/linux-next.html>` tree. The Subsystem maintainers push their patches first to linux-next, and, during the merge window, sends them directly to Linus. -- 2.7.4
[toc] | [prev] | [next] | [standalone]
| From | Mauro Carvalho Chehab <mchehab@s-opensource.com> |
|---|---|
| Date | 2016-09-22 13:50 +0200 |
| Subject | [PATCH 13/17] Documentation/serial-console.txt: convert it to ReST markup |
| Message-ID | <skaFQ-5LW-7@gated-at.bofh.it> |
| In reply to | #1488805 |
- Fix identation for the document title;
- use monotonic fonts for paths;
- use quote blocks where needed;
- adjust spaces to properly format paragraphs;
- use :menuselection: for the menu item;
- add it to the user book.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
Documentation/serial-console.txt | 66 +++++++++++++++++++----------------
Documentation/user/index.rst | 1 +
Documentation/user/serial-console.rst | 1 +
3 files changed, 37 insertions(+), 31 deletions(-)
create mode 120000 Documentation/user/serial-console.rst
diff --git a/Documentation/serial-console.txt b/Documentation/serial-console.txt
index 9a7bc8b3f479..1d9a3e48e929 100644
--- a/Documentation/serial-console.txt
+++ b/Documentation/serial-console.txt
@@ -1,15 +1,19 @@
- Linux Serial Console
+Linux Serial Console
+====================
To use a serial port as console you need to compile the support into your
kernel - by default it is not compiled in. For PC style serial ports
-it's the config option next to "Standard/generic (dumb) serial support".
+it's the config option next to menu option:
+
+:menuselection:`Character devices --> Serial drivers --> 8250/16550 and compatible serial support --> Console on 8250/16550 and compatible serial port`
+
You must compile serial support into the kernel and not as a module.
It is possible to specify multiple devices for console output. You can
define a new kernel command line option to select which device(s) to
use for console output.
-The format of this option is:
+The format of this option is::
console=device,options
@@ -28,11 +32,11 @@ The format of this option is:
You can specify multiple console= options on the kernel command line.
Output will appear on all of them. The last device will be used when
-you open /dev/console. So, for example:
+you open ``/dev/console``. So, for example::
console=ttyS1,9600 console=tty0
-defines that opening /dev/console will get you the current foreground
+defines that opening ``/dev/console`` will get you the current foreground
virtual console, and kernel messages will appear on both the VGA
console and the 2nd serial port (ttyS1 or COM2) at 9600 baud.
@@ -44,61 +48,61 @@ first looks for a VGA card and then for a serial port. So if you don't
have a VGA card in your system the first serial port will automatically
become the console.
-You will need to create a new device to use /dev/console. The official
-/dev/console is now character device 5,1.
+You will need to create a new device to use ``/dev/console``. The official
+``/dev/console`` is now character device 5,1.
(You can also use a network device as a console. See
-Documentation/networking/netconsole.txt for information on that.)
+``Documentation/networking/netconsole.txt`` for information on that.)
-Here's an example that will use /dev/ttyS1 (COM2) as the console.
+Here's an example that will use ``/dev/ttyS1`` (COM2) as the console.
Replace the sample values as needed.
-1. Create /dev/console (real console) and /dev/tty0 (master virtual
- console):
+1. Create ``/dev/console`` (real console) and ``/dev/tty0`` (master virtual
+ console)::
- cd /dev
- rm -f console tty0
- mknod -m 622 console c 5 1
- mknod -m 622 tty0 c 4 0
+ cd /dev
+ rm -f console tty0
+ mknod -m 622 console c 5 1
+ mknod -m 622 tty0 c 4 0
2. LILO can also take input from a serial device. This is a very
useful option. To tell LILO to use the serial port:
- In lilo.conf (global section):
+ In lilo.conf (global section)::
- serial = 1,9600n8 (ttyS1, 9600 bd, no parity, 8 bits)
+ serial = 1,9600n8 (ttyS1, 9600 bd, no parity, 8 bits)
3. Adjust to kernel flags for the new kernel,
- again in lilo.conf (kernel section)
+ again in lilo.conf (kernel section)::
- append = "console=ttyS1,9600"
+ append = "console=ttyS1,9600"
4. Make sure a getty runs on the serial port so that you can login to
it once the system is done booting. This is done by adding a line
- like this to /etc/inittab (exact syntax depends on your getty):
+ like this to ``/etc/inittab`` (exact syntax depends on your getty)::
- S1:23:respawn:/sbin/getty -L ttyS1 9600 vt100
+ S1:23:respawn:/sbin/getty -L ttyS1 9600 vt100
-5. Init and /etc/ioctl.save
+5. Init and ``/etc/ioctl.save``
- Sysvinit remembers its stty settings in a file in /etc, called
- `/etc/ioctl.save'. REMOVE THIS FILE before using the serial
+ Sysvinit remembers its stty settings in a file in ``/etc``, called
+ ``/etc/ioctl.save``. REMOVE THIS FILE before using the serial
console for the first time, because otherwise init will probably
set the baudrate to 38400 (baudrate of the virtual console).
-6. /dev/console and X
+6. ``/dev/console`` and X
Programs that want to do something with the virtual console usually
- open /dev/console. If you have created the new /dev/console device,
+ open ``/dev/console``. If you have created the new ``/dev/console`` device,
and your console is NOT the virtual console some programs will fail.
Those are programs that want to access the VT interface, and use
- /dev/console instead of /dev/tty0. Some of those programs are:
+ ``/dev/console instead of /dev/tty0``. Some of those programs are::
- Xfree86, svgalib, gpm, SVGATextMode
+ Xfree86, svgalib, gpm, SVGATextMode
It should be fixed in modern versions of these programs though.
- Note that if you boot without a console= option (or with
- console=/dev/tty0), /dev/console is the same as /dev/tty0. In that
- case everything will still work.
+ Note that if you boot without a ``console=`` option (or with
+ ``console=/dev/tty0``), ``/dev/console`` is the same as ``/dev/tty0``.
+ In that case everything will still work.
7. Thanks
diff --git a/Documentation/user/index.rst b/Documentation/user/index.rst
index 22f2ccac102b..8b0afcac2a72 100644
--- a/Documentation/user/index.rst
+++ b/Documentation/user/index.rst
@@ -11,6 +11,7 @@ Contents:
REPORTING-BUGS
SecurityBugs
kernel-parameters
+ serial-console
binfmt_misc
bad_memory
basic_profiling
diff --git a/Documentation/user/serial-console.rst b/Documentation/user/serial-console.rst
new file mode 120000
index 000000000000..fa315ca3b8e6
--- /dev/null
+++ b/Documentation/user/serial-console.rst
@@ -0,0 +1 @@
+../serial-console.txt
\ No newline at end of file
--
2.7.4
[toc] | [prev] | [next] | [standalone]
| From | Mauro Carvalho Chehab <mchehab@s-opensource.com> |
|---|---|
| Date | 2016-09-22 13:50 +0200 |
| Subject | [PATCH 09/17] Documentation/adding-syscalls.txt: convert it to ReST markup |
| Message-ID | <skaFQ-5LW-11@gated-at.bofh.it> |
| In reply to | #1488805 |
Convert adding-syscalls.txt to ReST markup and add it to the
development-process book:
- add extra lines to make Sphinx to correctly parse paragraphs;
- use quote blocks for examples;
- use monotonic font for dirs, function calls, etc;
- mark manpage pages using the right markup;
- add cross-reference to SubmittingPatches.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
Documentation/adding-syscalls.txt | 263 +++++++++++----------
.../development-process/adding-syscalls.rst | 1 +
Documentation/development-process/index.rst | 1 +
3 files changed, 141 insertions(+), 124 deletions(-)
create mode 120000 Documentation/development-process/adding-syscalls.rst
diff --git a/Documentation/adding-syscalls.txt b/Documentation/adding-syscalls.txt
index bbb31e091b28..f5b5b1aa51b3 100644
--- a/Documentation/adding-syscalls.txt
+++ b/Documentation/adding-syscalls.txt
@@ -3,7 +3,7 @@ Adding a New System Call
This document describes what's involved in adding a new system call to the
Linux kernel, over and above the normal submission advice in
-Documentation/SubmittingPatches.
+:ref:`Documentation/SubmittingPatches <submittingpatches>`.
System Call Alternatives
@@ -19,30 +19,33 @@ interface.
object, it may make more sense to create a new filesystem or device. This
also makes it easier to encapsulate the new functionality in a kernel module
rather than requiring it to be built into the main kernel.
+
- If the new functionality involves operations where the kernel notifies
userspace that something has happened, then returning a new file
descriptor for the relevant object allows userspace to use
- poll/select/epoll to receive that notification.
- - However, operations that don't map to read(2)/write(2)-like operations
- have to be implemented as ioctl(2) requests, which can lead to a
- somewhat opaque API.
+ ``poll``/``select``/``epoll`` to receive that notification.
+ - However, operations that don't map to
+ :manpage:`read(2)`/:manpage:`write(2)`-like operations
+ have to be implemented as :manpage:`ioctl(2)` requests, which can lead
+ to a somewhat opaque API.
+
- If you're just exposing runtime system information, a new node in sysfs
- (see Documentation/filesystems/sysfs.txt) or the /proc filesystem may be
- more appropriate. However, access to these mechanisms requires that the
+ (see ``Documentation/filesystems/sysfs.txt``) or the ``/proc`` filesystem may
+ be more appropriate. However, access to these mechanisms requires that the
relevant filesystem is mounted, which might not always be the case (e.g.
in a namespaced/sandboxed/chrooted environment). Avoid adding any API to
debugfs, as this is not considered a 'production' interface to userspace.
- If the operation is specific to a particular file or file descriptor, then
- an additional fcntl(2) command option may be more appropriate. However,
- fcntl(2) is a multiplexing system call that hides a lot of complexity, so
+ an additional :manpage:`fcntl(2)` command option may be more appropriate. However,
+ :manpage:`fcntl(2)` is a multiplexing system call that hides a lot of complexity, so
this option is best for when the new function is closely analogous to
- existing fcntl(2) functionality, or the new functionality is very simple
+ existing :manpage:`fcntl(2)` functionality, or the new functionality is very simple
(for example, getting/setting a simple flag related to a file descriptor).
- If the operation is specific to a particular task or process, then an
- additional prctl(2) command option may be more appropriate. As with
- fcntl(2), this system call is a complicated multiplexor so is best reserved
- for near-analogs of existing prctl() commands or getting/setting a simple
- flag related to a process.
+ additional :manpage:`prctl(2)` command option may be more appropriate. As
+ with :manpage:`fcntl(2)`, this system call is a complicated multiplexor so
+ is best reserved for near-analogs of existing ``prctl()`` commands or
+ getting/setting a simple flag related to a process.
Designing the API: Planning for Extension
@@ -54,15 +57,16 @@ interface on the kernel mailing list, and it's important to plan for future
extensions of the interface.
(The syscall table is littered with historical examples where this wasn't done,
-together with the corresponding follow-up system calls -- eventfd/eventfd2,
-dup2/dup3, inotify_init/inotify_init1, pipe/pipe2, renameat/renameat2 -- so
+together with the corresponding follow-up system calls --
+``eventfd``/``eventfd2``, ``dup2``/``dup3``, ``inotify_init``/``inotify_init1``,
+``pipe``/``pipe2``, ``renameat``/``renameat2`` -- so
learn from the history of the kernel and plan for extensions from the start.)
For simpler system calls that only take a couple of arguments, the preferred
way to allow for future extensibility is to include a flags argument to the
system call. To make sure that userspace programs can safely use flags
between kernel versions, check whether the flags value holds any unknown
-flags, and reject the system call (with EINVAL) if it does:
+flags, and reject the system call (with ``EINVAL``) if it does::
if (flags & ~(THING_FLAG1 | THING_FLAG2 | THING_FLAG3))
return -EINVAL;
@@ -72,7 +76,7 @@ flags, and reject the system call (with EINVAL) if it does:
For more sophisticated system calls that involve a larger number of arguments,
it's preferred to encapsulate the majority of the arguments into a structure
that is passed in by pointer. Such a structure can cope with future extension
-by including a size argument in the structure:
+by including a size argument in the structure::
struct xyzzy_params {
u32 size; /* userspace sets p->size = sizeof(struct xyzzy_params) */
@@ -81,19 +85,19 @@ by including a size argument in the structure:
u64 param_3;
};
-As long as any subsequently added field, say param_4, is designed so that a
+As long as any subsequently added field, say ``param_4``, is designed so that a
zero value gives the previous behaviour, then this allows both directions of
version mismatch:
- To cope with a later userspace program calling an older kernel, the kernel
code should check that any memory beyond the size of the structure that it
- expects is zero (effectively checking that param_4 == 0).
+ expects is zero (effectively checking that ``param_4 == 0``).
- To cope with an older userspace program calling a newer kernel, the kernel
code can zero-extend a smaller instance of the structure (effectively
- setting param_4 = 0).
+ setting ``param_4 = 0``).
-See perf_event_open(2) and the perf_copy_attr() function (in
-kernel/events/core.c) for an example of this approach.
+See :manpage:`perf_event_open(2)` and the ``perf_copy_attr()`` function (in
+``kernel/events/core.c``) for an example of this approach.
Designing the API: Other Considerations
@@ -104,57 +108,60 @@ should use a file descriptor as the handle for that object -- don't invent a
new type of userspace object handle when the kernel already has mechanisms and
well-defined semantics for using file descriptors.
-If your new xyzzy(2) system call does return a new file descriptor, then the
-flags argument should include a value that is equivalent to setting O_CLOEXEC
-on the new FD. This makes it possible for userspace to close the timing
-window between xyzzy() and calling fcntl(fd, F_SETFD, FD_CLOEXEC), where an
-unexpected fork() and execve() in another thread could leak a descriptor to
+If your new :manpage:`xyzzy(2)` system call does return a new file descriptor,
+then the flags argument should include a value that is equivalent to setting
+``O_CLOEXEC`` on the new FD. This makes it possible for userspace to close
+the timing window between ``xyzzy()`` and calling
+``fcntl(fd, F_SETFD, FD_CLOEXEC)``, where an unexpected ``fork()`` and
+``execve()`` in another thread could leak a descriptor to
the exec'ed program. (However, resist the temptation to re-use the actual value
-of the O_CLOEXEC constant, as it is architecture-specific and is part of a
-numbering space of O_* flags that is fairly full.)
+of the ``O_CLOEXEC`` constant, as it is architecture-specific and is part of a
+numbering space of ``O_*`` flags that is fairly full.)
If your system call returns a new file descriptor, you should also consider
-what it means to use the poll(2) family of system calls on that file
+what it means to use the :manpage:`poll(2)` family of system calls on that file
descriptor. Making a file descriptor ready for reading or writing is the
normal way for the kernel to indicate to userspace that an event has
occurred on the corresponding kernel object.
-If your new xyzzy(2) system call involves a filename argument:
+If your new :manpage:`xyzzy(2)` system call involves a filename argument::
int sys_xyzzy(const char __user *path, ..., unsigned int flags);
-you should also consider whether an xyzzyat(2) version is more appropriate:
+you should also consider whether an :manpage:`xyzzyat(2)` version is more appropriate::
int sys_xyzzyat(int dfd, const char __user *path, ..., unsigned int flags);
This allows more flexibility for how userspace specifies the file in question;
in particular it allows userspace to request the functionality for an
-already-opened file descriptor using the AT_EMPTY_PATH flag, effectively giving
-an fxyzzy(3) operation for free:
+already-opened file descriptor using the ``AT_EMPTY_PATH`` flag, effectively
+giving an :manpage:`fxyzzy(3)` operation for free::
- xyzzyat(AT_FDCWD, path, ..., 0) is equivalent to xyzzy(path,...)
- xyzzyat(fd, "", ..., AT_EMPTY_PATH) is equivalent to fxyzzy(fd, ...)
-(For more details on the rationale of the *at() calls, see the openat(2) man
-page; for an example of AT_EMPTY_PATH, see the fstatat(2) man page.)
+(For more details on the rationale of the \*at() calls, see the
+:manpage:`openat(2)` man page; for an example of AT_EMPTY_PATH, see the
+:manpage:`fstatat(2)` man page.)
-If your new xyzzy(2) system call involves a parameter describing an offset
-within a file, make its type loff_t so that 64-bit offsets can be supported
-even on 32-bit architectures.
+If your new :manpage:`xyzzy(2)` system call involves a parameter describing an
+offset within a file, make its type ``loff_t`` so that 64-bit offsets can be
+supported even on 32-bit architectures.
-If your new xyzzy(2) system call involves privileged functionality, it needs
-to be governed by the appropriate Linux capability bit (checked with a call to
-capable()), as described in the capabilities(7) man page. Choose an existing
-capability bit that governs related functionality, but try to avoid combining
-lots of only vaguely related functions together under the same bit, as this
-goes against capabilities' purpose of splitting the power of root. In
-particular, avoid adding new uses of the already overly-general CAP_SYS_ADMIN
-capability.
+If your new :manpage:`xyzzy(2)` system call involves privileged functionality,
+it needs to be governed by the appropriate Linux capability bit (checked with
+a call to ``capable()``), as described in the :manpage:`capabilities(7)` man
+page. Choose an existing capability bit that governs related functionality,
+but try to avoid combining lots of only vaguely related functions together
+under the same bit, as this goes against capabilities' purpose of splitting
+the power of root. In particular, avoid adding new uses of the already
+overly-general ``CAP_SYS_ADMIN`` capability.
-If your new xyzzy(2) system call manipulates a process other than the calling
-process, it should be restricted (using a call to ptrace_may_access()) so that
-only a calling process with the same permissions as the target process, or
-with the necessary capabilities, can manipulate the target process.
+If your new :manpage:`xyzzy(2)` system call manipulates a process other than
+the calling process, it should be restricted (using a call to
+``ptrace_may_access()``) so that only a calling process with the same
+permissions as the target process, or with the necessary capabilities, can
+manipulate the target process.
Finally, be aware that some non-x86 architectures have an easier time if
system call parameters that are explicitly 64-bit fall on odd-numbered
@@ -175,7 +182,7 @@ distinct commits (each of which is described further below):
- Wiring up of the new system call for one particular architecture, usually
x86 (including all of x86_64, x86_32 and x32).
- A demonstration of the use of the new system call in userspace via a
- selftest in tools/testing/selftests/.
+ selftest in ``tools/testing/selftests/``.
- A draft man-page for the new system call, either as plain text in the
cover letter, or as a patch to the (separate) man-pages repository.
@@ -186,24 +193,24 @@ be cc'ed to linux-api@vger.kernel.org.
Generic System Call Implementation
----------------------------------
-The main entry point for your new xyzzy(2) system call will be called
-sys_xyzzy(), but you add this entry point with the appropriate
-SYSCALL_DEFINEn() macro rather than explicitly. The 'n' indicates the number
-of arguments to the system call, and the macro takes the system call name
+The main entry point for your new :manpage:`xyzzy(2)` system call will be called
+``sys_xyzzy()``, but you add this entry point with the appropriate
+``SYSCALL_DEFINEn()`` macro rather than explicitly. The 'n' indicates the
+number of arguments to the system call, and the macro takes the system call name
followed by the (type, name) pairs for the parameters as arguments. Using
this macro allows metadata about the new system call to be made available for
other tools.
The new entry point also needs a corresponding function prototype, in
-include/linux/syscalls.h, marked as asmlinkage to match the way that system
-calls are invoked:
+``include/linux/syscalls.h``, marked as asmlinkage to match the way that system
+calls are invoked::
asmlinkage long sys_xyzzy(...);
Some architectures (e.g. x86) have their own architecture-specific syscall
tables, but several other architectures share a generic syscall table. Add your
new system call to the generic list by adding an entry to the list in
-include/uapi/asm-generic/unistd.h:
+``include/uapi/asm-generic/unistd.h``::
#define __NR_xyzzy 292
__SYSCALL(__NR_xyzzy, sys_xyzzy)
@@ -212,30 +219,30 @@ Also update the __NR_syscalls count to reflect the additional system call, and
note that if multiple new system calls are added in the same merge window,
your new syscall number may get adjusted to resolve conflicts.
-The file kernel/sys_ni.c provides a fallback stub implementation of each system
-call, returning -ENOSYS. Add your new system call here too:
+The file ``kernel/sys_ni.c`` provides a fallback stub implementation of each
+system call, returning ``-ENOSYS``. Add your new system call here too::
cond_syscall(sys_xyzzy);
Your new kernel functionality, and the system call that controls it, should
-normally be optional, so add a CONFIG option (typically to init/Kconfig) for
-it. As usual for new CONFIG options:
+normally be optional, so add a ``CONFIG`` option (typically to
+``init/Kconfig``) for it. As usual for new ``CONFIG`` options:
- Include a description of the new functionality and system call controlled
by the option.
- Make the option depend on EXPERT if it should be hidden from normal users.
- Make any new source files implementing the function dependent on the CONFIG
- option in the Makefile (e.g. "obj-$(CONFIG_XYZZY_SYSCALL) += xyzzy.c").
+ option in the Makefile (e.g. ``obj-$(CONFIG_XYZZY_SYSCALL) += xyzzy.c``).
- Double check that the kernel still builds with the new CONFIG option turned
off.
To summarize, you need a commit that includes:
- - CONFIG option for the new function, normally in init/Kconfig
- - SYSCALL_DEFINEn(xyzzy, ...) for the entry point
- - corresponding prototype in include/linux/syscalls.h
- - generic table entry in include/uapi/asm-generic/unistd.h
- - fallback stub in kernel/sys_ni.c
+ - ``CONFIG`` option for the new function, normally in ``init/Kconfig``
+ - ``SYSCALL_DEFINEn(xyzzy, ...)`` for the entry point
+ - corresponding prototype in ``include/linux/syscalls.h``
+ - generic table entry in ``include/uapi/asm-generic/unistd.h``
+ - fallback stub in ``kernel/sys_ni.c``
x86 System Call Implementation
@@ -244,11 +251,11 @@ x86 System Call Implementation
To wire up your new system call for x86 platforms, you need to update the
master syscall tables. Assuming your new system call isn't special in some
way (see below), this involves a "common" entry (for x86_64 and x32) in
-arch/x86/entry/syscalls/syscall_64.tbl:
+arch/x86/entry/syscalls/syscall_64.tbl::
333 common xyzzy sys_xyzzy
-and an "i386" entry in arch/x86/entry/syscalls/syscall_32.tbl:
+and an "i386" entry in ``arch/x86/entry/syscalls/syscall_32.tbl``::
380 i386 xyzzy sys_xyzzy
@@ -267,48 +274,49 @@ However, there are a couple of situations where a compatibility layer is
needed to cope with size differences between 32-bit and 64-bit.
The first is if the 64-bit kernel also supports 32-bit userspace programs, and
-so needs to parse areas of (__user) memory that could hold either 32-bit or
+so needs to parse areas of (``__user``) memory that could hold either 32-bit or
64-bit values. In particular, this is needed whenever a system call argument
is:
- a pointer to a pointer
- - a pointer to a struct containing a pointer (e.g. struct iovec __user *)
- - a pointer to a varying sized integral type (time_t, off_t, long, ...)
+ - a pointer to a struct containing a pointer (e.g. ``struct iovec __user *``)
+ - a pointer to a varying sized integral type (``time_t``, ``off_t``,
+ ``long``, ...)
- a pointer to a struct containing a varying sized integral type.
The second situation that requires a compatibility layer is if one of the
system call's arguments has a type that is explicitly 64-bit even on a 32-bit
-architecture, for example loff_t or __u64. In this case, a value that arrives
-at a 64-bit kernel from a 32-bit application will be split into two 32-bit
-values, which then need to be re-assembled in the compatibility layer.
+architecture, for example ``loff_t`` or ``__u64``. In this case, a value that
+arrives at a 64-bit kernel from a 32-bit application will be split into two
+32-bit values, which then need to be re-assembled in the compatibility layer.
(Note that a system call argument that's a pointer to an explicit 64-bit type
-does *not* need a compatibility layer; for example, splice(2)'s arguments of
-type loff_t __user * do not trigger the need for a compat_ system call.)
+does **not** need a compatibility layer; for example, :manpage:`splice(2)`'s arguments of
+type ``loff_t __user *`` do not trigger the need for a ``compat_`` system call.)
-The compatibility version of the system call is called compat_sys_xyzzy(), and
-is added with the COMPAT_SYSCALL_DEFINEn() macro, analogously to
+The compatibility version of the system call is called ``compat_sys_xyzzy()``,
+and is added with the ``COMPAT_SYSCALL_DEFINEn()`` macro, analogously to
SYSCALL_DEFINEn. This version of the implementation runs as part of a 64-bit
kernel, but expects to receive 32-bit parameter values and does whatever is
-needed to deal with them. (Typically, the compat_sys_ version converts the
-values to 64-bit versions and either calls on to the sys_ version, or both of
+needed to deal with them. (Typically, the ``compat_sys_`` version converts the
+values to 64-bit versions and either calls on to the ``sys_`` version, or both of
them call a common inner implementation function.)
The compat entry point also needs a corresponding function prototype, in
-include/linux/compat.h, marked as asmlinkage to match the way that system
-calls are invoked:
+``include/linux/compat.h``, marked as asmlinkage to match the way that system
+calls are invoked::
asmlinkage long compat_sys_xyzzy(...);
If the system call involves a structure that is laid out differently on 32-bit
-and 64-bit systems, say struct xyzzy_args, then the include/linux/compat.h
-header file should also include a compat version of the structure (struct
-compat_xyzzy_args) where each variable-size field has the appropriate compat_
-type that corresponds to the type in struct xyzzy_args. The
-compat_sys_xyzzy() routine can then use this compat_ structure to parse the
-arguments from a 32-bit invocation.
+and 64-bit systems, say ``struct xyzzy_args``, then the include/linux/compat.h
+header file should also include a compat version of the structure (``struct
+compat_xyzzy_args``) where each variable-size field has the appropriate
+``compat_`` type that corresponds to the type in ``struct xyzzy_args``. The
+``compat_sys_xyzzy()`` routine can then use this ``compat_`` structure to
+parse the arguments from a 32-bit invocation.
-For example, if there are fields:
+For example, if there are fields::
struct xyzzy_args {
const char __user *ptr;
@@ -317,7 +325,7 @@ For example, if there are fields:
/* ... */
};
-in struct xyzzy_args, then struct compat_xyzzy_args would have:
+in struct xyzzy_args, then struct compat_xyzzy_args would have::
struct compat_xyzzy_args {
compat_uptr_t ptr;
@@ -327,18 +335,19 @@ in struct xyzzy_args, then struct compat_xyzzy_args would have:
};
The generic system call list also needs adjusting to allow for the compat
-version; the entry in include/uapi/asm-generic/unistd.h should use
-__SC_COMP rather than __SYSCALL:
+version; the entry in ``include/uapi/asm-generic/unistd.h`` should use
+``__SC_COMP`` rather than ``__SYSCALL``::
#define __NR_xyzzy 292
__SC_COMP(__NR_xyzzy, sys_xyzzy, compat_sys_xyzzy)
To summarize, you need:
- - a COMPAT_SYSCALL_DEFINEn(xyzzy, ...) for the compat entry point
- - corresponding prototype in include/linux/compat.h
- - (if needed) 32-bit mapping struct in include/linux/compat.h
- - instance of __SC_COMP not __SYSCALL in include/uapi/asm-generic/unistd.h
+ - a ``COMPAT_SYSCALL_DEFINEn(xyzzy, ...)`` for the compat entry point
+ - corresponding prototype in ``include/linux/compat.h``
+ - (if needed) 32-bit mapping struct in ``include/linux/compat.h``
+ - instance of ``__SC_COMP`` not ``__SYSCALL`` in
+ ``include/uapi/asm-generic/unistd.h``
Compatibility System Calls (x86)
@@ -347,9 +356,9 @@ Compatibility System Calls (x86)
To wire up the x86 architecture of a system call with a compatibility version,
the entries in the syscall tables need to be adjusted.
-First, the entry in arch/x86/entry/syscalls/syscall_32.tbl gets an extra
+First, the entry in ``arch/x86/entry/syscalls/syscall_32.tbl`` gets an extra
column to indicate that a 32-bit userspace program running on a 64-bit kernel
-should hit the compat entry point:
+should hit the compat entry point::
380 i386 xyzzy sys_xyzzy compat_sys_xyzzy
@@ -359,8 +368,8 @@ should either match the 64-bit version or the 32-bit version.
If there's a pointer-to-a-pointer involved, the decision is easy: x32 is
ILP32, so the layout should match the 32-bit version, and the entry in
-arch/x86/entry/syscalls/syscall_64.tbl is split so that x32 programs hit the
-compatibility wrapper:
+``arch/x86/entry/syscalls/syscall_64.tbl`` is split so that x32 programs hit
+the compatibility wrapper::
333 64 xyzzy sys_xyzzy
...
@@ -384,8 +393,9 @@ stack the same and most of the registers the same as before the system call,
and with the same virtual memory space.
However, a few system calls do things differently. They might return to a
-different location (rt_sigreturn) or change the memory space (fork/vfork/clone)
-or even architecture (execve/execveat) of the program.
+different location (``rt_sigreturn``) or change the memory space
+(``fork``/``vfork``/``clone``) or even architecture (``execve``/``execveat``)
+of the program.
To allow for this, the kernel implementation of the system call may need to
save and restore additional registers to the kernel stack, allowing complete
@@ -395,31 +405,31 @@ This is arch-specific, but typically involves defining assembly entry points
that save/restore additional registers and invoke the real system call entry
point.
-For x86_64, this is implemented as a stub_xyzzy entry point in
-arch/x86/entry/entry_64.S, and the entry in the syscall table
-(arch/x86/entry/syscalls/syscall_64.tbl) is adjusted to match:
+For x86_64, this is implemented as a ``stub_xyzzy`` entry point in
+``arch/x86/entry/entry_64.S``, and the entry in the syscall table
+(``arch/x86/entry/syscalls/syscall_64.tbl``) is adjusted to match::
333 common xyzzy stub_xyzzy
The equivalent for 32-bit programs running on a 64-bit kernel is normally
-called stub32_xyzzy and implemented in arch/x86/entry/entry_64_compat.S,
+called ``stub32_xyzzy`` and implemented in ``arch/x86/entry/entry_64_compat.S``,
with the corresponding syscall table adjustment in
-arch/x86/entry/syscalls/syscall_32.tbl:
+``arch/x86/entry/syscalls/syscall_32.tbl``::
380 i386 xyzzy sys_xyzzy stub32_xyzzy
If the system call needs a compatibility layer (as in the previous section)
-then the stub32_ version needs to call on to the compat_sys_ version of the
-system call rather than the native 64-bit version. Also, if the x32 ABI
+then the ``stub32_`` version needs to call on to the ``compat_sys_`` version
+of the system call rather than the native 64-bit version. Also, if the x32 ABI
implementation is not common with the x86_64 version, then its syscall
-table will also need to invoke a stub that calls on to the compat_sys_
+table will also need to invoke a stub that calls on to the ``compat_sys_``
version.
For completeness, it's also nice to set up a mapping so that user-mode Linux
still works -- its syscall table will reference stub_xyzzy, but the UML build
-doesn't include arch/x86/entry/entry_64.S implementation (because UML
+doesn't include ``arch/x86/entry/entry_64.S`` implementation (because UML
simulates registers etc). Fixing this is as simple as adding a #define to
-arch/x86/um/sys_call_table_64.c:
+``arch/x86/um/sys_call_table_64.c``::
#define stub_xyzzy sys_xyzzy
@@ -432,9 +442,9 @@ occasional exception that may need updating for your particular system call.
The audit subsystem is one such special case; it includes (arch-specific)
functions that classify some special types of system call -- specifically
-file open (open/openat), program execution (execve/exeveat) or socket
-multiplexor (socketcall) operations. If your new system call is analogous to
-one of these, then the audit system should be updated.
+file open (``open``/``openat``), program execution (``execve``/``exeveat``) or
+socket multiplexor (``socketcall``) operations. If your new system call is
+analogous to one of these, then the audit system should be updated.
More generally, if there is an existing system call that is analogous to your
new system call, it's worth doing a kernel-wide grep for the existing system
@@ -447,10 +457,10 @@ Testing
A new system call should obviously be tested; it is also useful to provide
reviewers with a demonstration of how user space programs will use the system
call. A good way to combine these aims is to include a simple self-test
-program in a new directory under tools/testing/selftests/.
+program in a new directory under ``tools/testing/selftests/``.
For a new system call, there will obviously be no libc wrapper function and so
-the test will need to invoke it using syscall(); also, if the system call
+the test will need to invoke it using ``syscall()``; also, if the system call
involves a new userspace-visible structure, the corresponding header will need
to be installed to compile the test.
@@ -461,6 +471,7 @@ and x32 (-mx32) ABI program.
For more extensive and thorough testing of new functionality, you should also
consider adding tests to the Linux Test Project, or to the xfstests project
for filesystem-related changes.
+
- https://linux-test-project.github.io/
- git://git.kernel.org/pub/scm/fs/xfs/xfstests-dev.git
@@ -487,12 +498,14 @@ References and Sources
arguments: https://lwn.net/Articles/311630/
- Pair of LWN articles from David Drysdale that describe the system call
implementation paths in detail for v3.14:
+
- https://lwn.net/Articles/604287/
- https://lwn.net/Articles/604515/
+
- Architecture-specific requirements for system calls are discussed in the
- syscall(2) man-page:
+ :manpage:`syscall(2)` man-page:
http://man7.org/linux/man-pages/man2/syscall.2.html#NOTES
- - Collated emails from Linus Torvalds discussing the problems with ioctl():
+ - Collated emails from Linus Torvalds discussing the problems with ``ioctl()``:
http://yarchive.net/comp/linux/ioctl.html
- "How to not invent kernel interfaces", Arnd Bergmann,
http://www.ukuug.org/events/linux2007/2007/papers/Bergmann.pdf
@@ -507,17 +520,19 @@ References and Sources
commit: https://lkml.org/lkml/2014/11/19/254
- Suggestion from Greg Kroah-Hartman that it's good for new system calls to
come with a man-page & selftest: https://lkml.org/lkml/2014/3/19/710
- - Discussion from Michael Kerrisk of new system call vs. prctl(2) extension:
+ - Discussion from Michael Kerrisk of new system call vs. :manpage:`prctl(2)` extension:
https://lkml.org/lkml/2014/6/3/411
- Suggestion from Ingo Molnar that system calls that involve multiple
arguments should encapsulate those arguments in a struct, which includes a
size field for future extensibility: https://lkml.org/lkml/2015/7/30/117
- Numbering oddities arising from (re-)use of O_* numbering space flags:
+
- commit 75069f2b5bfb ("vfs: renumber FMODE_NONOTIFY and add to uniqueness
check")
- commit 12ed2e36c98a ("fanotify: FMODE_NONOTIFY and __O_SYNC in sparc
conflict")
- commit bb458c644a59 ("Safer ABI for O_TMPFILE")
+
- Discussion from Matthew Wilcox about restrictions on 64-bit arguments:
https://lkml.org/lkml/2008/12/12/187
- Recommendation from Greg Kroah-Hartman that unknown flags should be
diff --git a/Documentation/development-process/adding-syscalls.rst b/Documentation/development-process/adding-syscalls.rst
new file mode 120000
index 000000000000..67c4beaac713
--- /dev/null
+++ b/Documentation/development-process/adding-syscalls.rst
@@ -0,0 +1 @@
+../adding-syscalls.txt
\ No newline at end of file
diff --git a/Documentation/development-process/index.rst b/Documentation/development-process/index.rst
index e6faabd34ab8..acb2c00fa5c1 100644
--- a/Documentation/development-process/index.rst
+++ b/Documentation/development-process/index.rst
@@ -24,5 +24,6 @@ Contents:
applying-patches
email-clients
SubmitChecklist
+ adding-syscalls
development-process
--
2.7.4
[toc] | [prev] | [next] | [standalone]
| From | Mauro Carvalho Chehab <mchehab@s-opensource.com> |
|---|---|
| Date | 2016-09-22 14:00 +0200 |
| Subject | [PATCH 02/17] Documentation/email-clients.txt: convert it to ReST markup |
| Message-ID | <skaPv-5PF-1@gated-at.bofh.it> |
| In reply to | #1488805 |
As this file is mentioned at the development-process/ book,
let's convert it to ReST markup.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
Documentation/email-clients.txt | 208 ++++++++++++++++++++++------------------
1 file changed, 114 insertions(+), 94 deletions(-)
diff --git a/Documentation/email-clients.txt b/Documentation/email-clients.txt
index 2d485dea8cec..ac892b30815e 100644
--- a/Documentation/email-clients.txt
+++ b/Documentation/email-clients.txt
@@ -1,23 +1,27 @@
+.. _email_clients:
+
Email clients info for Linux
-======================================================================
+============================
Git
-----------------------------------------------------------------------
-These days most developers use `git send-email` instead of regular
+---
+
+These days most developers use ``git send-email`` instead of regular
email clients. The man page for this is quite good. On the receiving
-end, maintainers use `git am` to apply the patches.
+end, maintainers use ``git am`` to apply the patches.
-If you are new to git then send your first patch to yourself. Save it
-as raw text including all the headers. Run `git am raw_email.txt` and
-then review the changelog with `git log`. When that works then send
+If you are new to ``git`` then send your first patch to yourself. Save it
+as raw text including all the headers. Run ``git am raw_email.txt`` and
+then review the changelog with ``git log``. When that works then send
the patch to the appropriate mailing list(s).
General Preferences
-----------------------------------------------------------------------
+-------------------
+
Patches for the Linux kernel are submitted via email, preferably as
inline text in the body of the email. Some maintainers accept
attachments, but then the attachments should have content-type
-"text/plain". However, attachments are generally frowned upon because
+``text/plain``. However, attachments are generally frowned upon because
it makes quoting portions of the patch more difficult in the patch
review process.
@@ -25,7 +29,7 @@ Email clients that are used for Linux kernel patches should send the
patch text untouched. For example, they should not modify or delete tabs
or spaces, even at the beginning or end of lines.
-Don't send patches with "format=flowed". This can cause unexpected
+Don't send patches with ``format=flowed``. This can cause unexpected
and unwanted line breaks.
Don't let your email client do automatic word wrapping for you.
@@ -54,57 +58,63 @@ mailing lists.
Some email client (MUA) hints
-----------------------------------------------------------------------
+-----------------------------
+
Here are some specific MUA configuration hints for editing and sending
patches for the Linux kernel. These are not meant to be complete
software package configuration summaries.
+
Legend:
-TUI = text-based user interface
-GUI = graphical user interface
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+- TUI = text-based user interface
+- GUI = graphical user interface
+
Alpine (TUI)
+************
Config options:
-In the "Sending Preferences" section:
-- "Do Not Send Flowed Text" must be enabled
-- "Strip Whitespace Before Sending" must be disabled
+In the :menuselection:`Sending Preferences` section:
+
+- :menuselection:`Do Not Send Flowed Text` must be ``enabled``
+- :menuselection:`Strip Whitespace Before Sending` must be ``disabled``
When composing the message, the cursor should be placed where the patch
-should appear, and then pressing CTRL-R let you specify the patch file
+should appear, and then pressing :kbd:`CTRL-R` let you specify the patch file
to insert into the message.
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Claws Mail (GUI)
+****************
Works. Some people use this successfully for patches.
-To insert a patch use Message->Insert File (CTRL+i) or an external editor.
+To insert a patch use :menuselection:`Message-->Insert` File (:kbd:`CTRL-I`)
+or an external editor.
If the inserted patch has to be edited in the Claws composition window
-"Auto wrapping" in Configuration->Preferences->Compose->Wrapping should be
+"Auto wrapping" in
+:menuselection:`Configuration-->Preferences-->Compose-->Wrapping` should be
disabled.
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Evolution (GUI)
+***************
Some people use this successfully for patches.
When composing mail select: Preformat
- from Format->Paragraph Style->Preformatted (Ctrl-7)
+ from :menuselection:`Format-->Paragraph Style-->Preformatted` (:kbd:`CTRL-7`)
or the toolbar
Then use:
- Insert->Text File... (Alt-n x)
+:menuselection:`Insert-->Text File...` (:kbd:`ALT-N x`)
to insert the patch.
-You can also "diff -Nru old.c new.c | xclip", select Preformat, then
-paste with the middle button.
+You can also ``diff -Nru old.c new.c | xclip``, select
+:menuselection:`Preformat`, then paste with the middle button.
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Kmail (GUI)
+***********
Some people use Kmail successfully for patches.
@@ -120,11 +130,12 @@ word-wrapped and you can uncheck "word wrap" without losing the existing
wrapping.
At the bottom of your email, put the commonly-used patch delimiter before
-inserting your patch: three hyphens (---).
+inserting your patch: three hyphens (``---``).
-Then from the "Message" menu item, select insert file and choose your patch.
+Then from the :menuselection:`Message` menu item, select insert file and
+choose your patch.
As an added bonus you can customise the message creation toolbar menu
-and put the "insert file" icon there.
+and put the :menuselection:`insert file` icon there.
Make the composer window wide enough so that no lines wrap. As of
KMail 1.13.5 (KDE 4.5.4), KMail will apply word wrapping when sending
@@ -139,86 +150,96 @@ as inlined text will make them tricky to extract from their 7-bit encoding.
If you absolutely must send patches as attachments instead of inlining
them as text, right click on the attachment and select properties, and
-highlight "Suggest automatic display" to make the attachment inlined to
-make it more viewable.
+highlight :menuselection:`Suggest automatic display` to make the attachment
+inlined to make it more viewable.
When saving patches that are sent as inlined text, select the email that
contains the patch from the message list pane, right click and select
-"save as". You can use the whole email unmodified as a patch if it was
-properly composed. There is no option currently to save the email when you
-are actually viewing it in its own window -- there has been a request filed
-at kmail's bugzilla and hopefully this will be addressed. Emails are saved
-as read-write for user only so you will have to chmod them to make them
+:menuselection:`save as`. You can use the whole email unmodified as a patch
+if it was properly composed. There is no option currently to save the email
+when you are actually viewing it in its own window -- there has been a request
+filed at kmail's bugzilla and hopefully this will be addressed. Emails are
+saved as read-write for user only so you will have to chmod them to make them
group and world readable if you copy them elsewhere.
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Lotus Notes (GUI)
+*****************
Run away from it.
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Mutt (TUI)
+**********
-Plenty of Linux developers use mutt, so it must work pretty well.
+Plenty of Linux developers use ``mutt``, so it must work pretty well.
Mutt doesn't come with an editor, so whatever editor you use should be
used in a way that there are no automatic linebreaks. Most editors have
-an "insert file" option that inserts the contents of a file unaltered.
+an :menuselection:`insert file` option that inserts the contents of a file
+unaltered.
+
+To use ``vim`` with mutt::
-To use 'vim' with mutt:
set editor="vi"
- If using xclip, type the command
+If using xclip, type the command::
+
:set paste
- before middle button or shift-insert or use
+
+before middle button or shift-insert or use::
+
:r filename
if you want to include the patch inline.
-(a)ttach works fine without "set paste".
+(a)ttach works fine without ``set paste``.
+
+You can also generate patches with ``git format-patch`` and then use Mutt
+to send them::
-You can also generate patches with 'git format-patch' and then use Mutt
-to send them:
$ mutt -H 0001-some-bug-fix.patch
Config options:
+
It should work with default settings.
-However, it's a good idea to set the "send_charset" to:
+However, it's a good idea to set the ``send_charset`` to::
+
set send_charset="us-ascii:utf-8"
Mutt is highly customizable. Here is a minimum configuration to start
-using Mutt to send patches through Gmail:
+using Mutt to send patches through Gmail::
-# .muttrc
-# ================ IMAP ====================
-set imap_user = 'yourusername@gmail.com'
-set imap_pass = 'yourpassword'
-set spoolfile = imaps://imap.gmail.com/INBOX
-set folder = imaps://imap.gmail.com/
-set record="imaps://imap.gmail.com/[Gmail]/Sent Mail"
-set postponed="imaps://imap.gmail.com/[Gmail]/Drafts"
-set mbox="imaps://imap.gmail.com/[Gmail]/All Mail"
+ # .muttrc
+ # ================ IMAP ====================
+ set imap_user = 'yourusername@gmail.com'
+ set imap_pass = 'yourpassword'
+ set spoolfile = imaps://imap.gmail.com/INBOX
+ set folder = imaps://imap.gmail.com/
+ set record="imaps://imap.gmail.com/[Gmail]/Sent Mail"
+ set postponed="imaps://imap.gmail.com/[Gmail]/Drafts"
+ set mbox="imaps://imap.gmail.com/[Gmail]/All Mail"
-# ================ SMTP ====================
-set smtp_url = "smtp://username@smtp.gmail.com:587/"
-set smtp_pass = $imap_pass
-set ssl_force_tls = yes # Require encrypted connection
+ # ================ SMTP ====================
+ set smtp_url = "smtp://username@smtp.gmail.com:587/"
+ set smtp_pass = $imap_pass
+ set ssl_force_tls = yes # Require encrypted connection
-# ================ Composition ====================
-set editor = `echo \$EDITOR`
-set edit_headers = yes # See the headers when editing
-set charset = UTF-8 # value of $LANG; also fallback for send_charset
-# Sender, email address, and sign-off line must match
-unset use_domain # because joe@localhost is just embarrassing
-set realname = "YOUR NAME"
-set from = "username@gmail.com"
-set use_from = yes
+ # ================ Composition ====================
+ set editor = `echo \$EDITOR`
+ set edit_headers = yes # See the headers when editing
+ set charset = UTF-8 # value of $LANG; also fallback for send_charset
+ # Sender, email address, and sign-off line must match
+ unset use_domain # because joe@localhost is just embarrassing
+ set realname = "YOUR NAME"
+ set from = "username@gmail.com"
+ set use_from = yes
The Mutt docs have lots more information:
+
http://dev.mutt.org/trac/wiki/UseCases/Gmail
+
http://dev.mutt.org/doc/manual.html
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Pine (TUI)
+**********
Pine has had some whitespace truncation issues in the past, but these
should all be fixed now.
@@ -226,12 +247,13 @@ should all be fixed now.
Use alpine (pine's successor) if you can.
Config options:
-- quell-flowed-text is needed for recent versions
-- the "no-strip-whitespace-before-send" option is needed
+
+- ``quell-flowed-text`` is needed for recent versions
+- the ``no-strip-whitespace-before-send`` option is needed
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Sylpheed (GUI)
+**************
- Works well for inlining text (or using attachments).
- Allows use of an external editor.
@@ -241,50 +263,50 @@ Sylpheed (GUI)
- Adding addresses to address book doesn't understand the display name
properly.
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Thunderbird (GUI)
+*****************
Thunderbird is an Outlook clone that likes to mangle text, but there are ways
to coerce it into behaving.
- Allow use of an external editor:
The easiest thing to do with Thunderbird and patches is to use an
- "external editor" extension and then just use your favorite $EDITOR
+ "external editor" extension and then just use your favorite ``$EDITOR``
for reading/merging patches into the body text. To do this, download
and install the extension, then add a button for it using
- View->Toolbars->Customize... and finally just click on it when in the
- Compose dialog.
+ :menuselection:`View-->Toolbars-->Customize...` and finally just click on it
+ when in the :menuselection:`Compose` dialog.
Please note that "external editor" requires that your editor must not
fork, or in other words, the editor must not return before closing.
You may have to pass additional flags or change the settings of your
editor. Most notably if you are using gvim then you must pass the -f
- option to gvim by putting "/usr/bin/gvim -f" (if the binary is in
- /usr/bin) to the text editor field in "external editor" settings. If you
- are using some other editor then please read its manual to find out how
- to do this.
+ option to gvim by putting ``/usr/bin/gvim -f`` (if the binary is in
+ ``/usr/bin``) to the text editor field in :menuselection:`external editor`
+ settings. If you are using some other editor then please read its manual
+ to find out how to do this.
To beat some sense out of the internal editor, do this:
-- Edit your Thunderbird config settings so that it won't use format=flowed.
- Go to "edit->preferences->advanced->config editor" to bring up the
- thunderbird's registry editor.
+- Edit your Thunderbird config settings so that it won't use ``format=flowed``.
+ Go to :menuselection:`edit-->preferences-->advanced-->config editor` to bring up
+ the thunderbird's registry editor.
-- Set "mailnews.send_plaintext_flowed" to "false"
+- Set ``mailnews.send_plaintext_flowed`` to ``false``
-- Set "mailnews.wraplength" from "72" to "0"
+- Set ``mailnews.wraplength`` from ``72`` to ``0``
-- "View" > "Message Body As" > "Plain Text"
+- :menuselection:`View-->Message Body As-->Plain Text`
-- "View" > "Character Encoding" > "Unicode (UTF-8)"
+- :menuselection:`View-->Character Encoding-->Unicode (UTF-8)`
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
TkRat (GUI)
+***********
Works. Use "Insert file..." or external editor.
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Gmail (Web GUI)
+***************
Does not work for sending patches.
@@ -295,5 +317,3 @@ although tab2space problem can be solved with external editor.
Another problem is that Gmail will base64-encode any message that has a
non-ASCII character. That includes things like European names.
-
- ###
--
2.7.4
[toc] | [prev] | [next] | [standalone]
| From | Mauro Carvalho Chehab <mchehab@s-opensource.com> |
|---|---|
| Date | 2016-09-22 14:00 +0200 |
| Subject | [PATCH 08/17] docs-rst: create an user's manual book |
| Message-ID | <skaPv-5PF-3@gated-at.bofh.it> |
| In reply to | #1488805 |
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>
---
Documentation/SecurityBugs | 12 ++++++------
Documentation/index.rst | 1 +
Documentation/user/README.rst | 1 +
Documentation/user/REPORTING-BUGS.rst | 1 +
Documentation/user/SecurityBugs.rst | 1 +
Documentation/user/index.rst | 13 +++++++++++++
Documentation/user/kernel-parameters.rst | 1 +
7 files changed, 24 insertions(+), 6 deletions(-)
create mode 120000 Documentation/user/README.rst
create mode 120000 Documentation/user/REPORTING-BUGS.rst
create mode 120000 Documentation/user/SecurityBugs.rst
create mode 100644 Documentation/user/index.rst
create mode 120000 Documentation/user/kernel-parameters.rst
diff --git a/Documentation/SecurityBugs b/Documentation/SecurityBugs
index 342d769834f6..df795e22d08b 100644
--- a/Documentation/SecurityBugs
+++ b/Documentation/SecurityBugs
@@ -8,8 +8,8 @@ like to know when a security bug is found so that it can be fixed and
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 @@ REPORTING-BUGS if you are unclear about what information is helpful.
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 @@ disclosure is from immediate (esp. if it's already publicly known)
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/index.rst b/Documentation/index.rst
index d9ccb94fca95..235b6bc3a304 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -11,6 +11,7 @@ Contents:
.. toctree::
:maxdepth: 2
+ user/index
kernel-documentation
development-process/index
dev-tools/tools
diff --git a/Documentation/user/README.rst b/Documentation/user/README.rst
new file mode 120000
index 000000000000..3830a41184be
--- /dev/null
+++ b/Documentation/user/README.rst
@@ -0,0 +1 @@
+../../README
\ No newline at end of file
diff --git a/Documentation/user/REPORTING-BUGS.rst b/Documentation/user/REPORTING-BUGS.rst
new file mode 120000
index 000000000000..8074a63d7596
--- /dev/null
+++ b/Documentation/user/REPORTING-BUGS.rst
@@ -0,0 +1 @@
+../../REPORTING-BUGS
\ No newline at end of file
diff --git a/Documentation/user/SecurityBugs.rst b/Documentation/user/SecurityBugs.rst
new file mode 120000
index 000000000000..fa5504256c04
--- /dev/null
+++ b/Documentation/user/SecurityBugs.rst
@@ -0,0 +1 @@
+../SecurityBugs
\ No newline at end of file
diff --git a/Documentation/user/index.rst b/Documentation/user/index.rst
new file mode 100644
index 000000000000..280e62f21efa
--- /dev/null
+++ b/Documentation/user/index.rst
@@ -0,0 +1,13 @@
+Linux Kernel User's Documentation
+=================================
+
+Contents:
+
+.. toctree::
+ :maxdepth: 2
+ :numbered:
+
+ README
+ REPORTING-BUGS
+ SecurityBugs
+ kernel-parameters
diff --git a/Documentation/user/kernel-parameters.rst b/Documentation/user/kernel-parameters.rst
new file mode 120000
index 000000000000..eea97c5ac948
--- /dev/null
+++ b/Documentation/user/kernel-parameters.rst
@@ -0,0 +1 @@
+../kernel-parameters.txt
\ No newline at end of file
--
2.7.4
[toc] | [prev] | [next] | [standalone]
| From | Mauro Carvalho Chehab <mchehab@s-opensource.com> |
|---|---|
| Date | 2016-09-22 14:00 +0200 |
| Subject | [PATCH 07/17] docs-rst: add documents to development-process |
| Message-ID | <skaPv-5PF-5@gated-at.bofh.it> |
| In reply to | #1488805 |
Add several documents to the development-process ReST book.
As we don't want renames, use symlinks instead, keeping those
documents on their original place.
Acked-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
Documentation/development-process/Changes.rst | 1 +
Documentation/development-process/CodingStyle.rst | 1 +
Documentation/development-process/HOWTO.rst | 1 +
Documentation/development-process/ManagementStyle.rst | 1 +
Documentation/development-process/SubmitChecklist.rst | 1 +
.../development-process/SubmittingDrivers.rst | 1 +
.../development-process/SubmittingPatches.rst | 1 +
.../development-process/applying-patches.rst | 1 +
Documentation/development-process/email-clients.rst | 1 +
Documentation/development-process/index.rst | 19 +++++++++++++++++++
Documentation/development-process/kernel-docs.rst | 1 +
.../development-process/stable_api_nonsense.rst | 1 +
.../development-process/stable_kernel_rules.rst | 1 +
13 files changed, 31 insertions(+)
create mode 120000 Documentation/development-process/Changes.rst
create mode 120000 Documentation/development-process/CodingStyle.rst
create mode 120000 Documentation/development-process/HOWTO.rst
create mode 120000 Documentation/development-process/ManagementStyle.rst
create mode 120000 Documentation/development-process/SubmitChecklist.rst
create mode 120000 Documentation/development-process/SubmittingDrivers.rst
create mode 120000 Documentation/development-process/SubmittingPatches.rst
create mode 120000 Documentation/development-process/applying-patches.rst
create mode 120000 Documentation/development-process/email-clients.rst
create mode 120000 Documentation/development-process/kernel-docs.rst
create mode 120000 Documentation/development-process/stable_api_nonsense.rst
create mode 120000 Documentation/development-process/stable_kernel_rules.rst
diff --git a/Documentation/development-process/Changes.rst b/Documentation/development-process/Changes.rst
new file mode 120000
index 000000000000..91698e7753f1
--- /dev/null
+++ b/Documentation/development-process/Changes.rst
@@ -0,0 +1 @@
+../Changes
\ No newline at end of file
diff --git a/Documentation/development-process/CodingStyle.rst b/Documentation/development-process/CodingStyle.rst
new file mode 120000
index 000000000000..0377b2fe8778
--- /dev/null
+++ b/Documentation/development-process/CodingStyle.rst
@@ -0,0 +1 @@
+../CodingStyle
\ No newline at end of file
diff --git a/Documentation/development-process/HOWTO.rst b/Documentation/development-process/HOWTO.rst
new file mode 120000
index 000000000000..10734efe8eab
--- /dev/null
+++ b/Documentation/development-process/HOWTO.rst
@@ -0,0 +1 @@
+../HOWTO
\ No newline at end of file
diff --git a/Documentation/development-process/ManagementStyle.rst b/Documentation/development-process/ManagementStyle.rst
new file mode 120000
index 000000000000..a7d15159c108
--- /dev/null
+++ b/Documentation/development-process/ManagementStyle.rst
@@ -0,0 +1 @@
+../ManagementStyle
\ No newline at end of file
diff --git a/Documentation/development-process/SubmitChecklist.rst b/Documentation/development-process/SubmitChecklist.rst
new file mode 120000
index 000000000000..7b75ef138e89
--- /dev/null
+++ b/Documentation/development-process/SubmitChecklist.rst
@@ -0,0 +1 @@
+../SubmitChecklist
\ No newline at end of file
diff --git a/Documentation/development-process/SubmittingDrivers.rst b/Documentation/development-process/SubmittingDrivers.rst
new file mode 120000
index 000000000000..955fc75e6759
--- /dev/null
+++ b/Documentation/development-process/SubmittingDrivers.rst
@@ -0,0 +1 @@
+../SubmittingDrivers
\ No newline at end of file
diff --git a/Documentation/development-process/SubmittingPatches.rst b/Documentation/development-process/SubmittingPatches.rst
new file mode 120000
index 000000000000..bd9bb84255d4
--- /dev/null
+++ b/Documentation/development-process/SubmittingPatches.rst
@@ -0,0 +1 @@
+../SubmittingPatches
\ No newline at end of file
diff --git a/Documentation/development-process/applying-patches.rst b/Documentation/development-process/applying-patches.rst
new file mode 120000
index 000000000000..c124a067a16b
--- /dev/null
+++ b/Documentation/development-process/applying-patches.rst
@@ -0,0 +1 @@
+../applying-patches.txt
\ No newline at end of file
diff --git a/Documentation/development-process/email-clients.rst b/Documentation/development-process/email-clients.rst
new file mode 120000
index 000000000000..b4bbad729cca
--- /dev/null
+++ b/Documentation/development-process/email-clients.rst
@@ -0,0 +1 @@
+../email-clients.txt
\ No newline at end of file
diff --git a/Documentation/development-process/index.rst b/Documentation/development-process/index.rst
index c37475d91090..e6faabd34ab8 100644
--- a/Documentation/development-process/index.rst
+++ b/Documentation/development-process/index.rst
@@ -1,3 +1,9 @@
+.. raw:: latex
+
+ \renewcommand\thesection*
+ \renewcommand\thesubsection*
+
+
Linux Kernel Development Documentation
======================================
@@ -6,4 +12,17 @@ Contents:
.. toctree::
:maxdepth: 2
+ HOWTO
+ Changes
+ CodingStyle
+ SubmittingPatches
+ SubmittingDrivers
+ stable_api_nonsense
+ ManagementStyle
+ stable_kernel_rules
+ kernel-docs
+ applying-patches
+ email-clients
+ SubmitChecklist
+
development-process
diff --git a/Documentation/development-process/kernel-docs.rst b/Documentation/development-process/kernel-docs.rst
new file mode 120000
index 000000000000..1075b84514ff
--- /dev/null
+++ b/Documentation/development-process/kernel-docs.rst
@@ -0,0 +1 @@
+../kernel-docs.txt
\ No newline at end of file
diff --git a/Documentation/development-process/stable_api_nonsense.rst b/Documentation/development-process/stable_api_nonsense.rst
new file mode 120000
index 000000000000..2c44a79fdeef
--- /dev/null
+++ b/Documentation/development-process/stable_api_nonsense.rst
@@ -0,0 +1 @@
+../stable_api_nonsense.txt
\ No newline at end of file
diff --git a/Documentation/development-process/stable_kernel_rules.rst b/Documentation/development-process/stable_kernel_rules.rst
new file mode 120000
index 000000000000..320a01411304
--- /dev/null
+++ b/Documentation/development-process/stable_kernel_rules.rst
@@ -0,0 +1 @@
+../stable_kernel_rules.txt
\ No newline at end of file
--
2.7.4
[toc] | [prev] | [next] | [standalone]
| From | Mauro Carvalho Chehab <mchehab@s-opensource.com> |
|---|---|
| Date | 2016-09-22 14:00 +0200 |
| Subject | [PATCH 15/17] Documentation/BUG-HUNTING: convert to ReST markup |
| Message-ID | <skaPv-5PF-15@gated-at.bofh.it> |
| In reply to | #1488805 |
- Add a document title and remove its own index;
- use monotonic fonts for paths;
- use quote blocks where needed;
- adjust/use spaces to properly format paragraphs;
- add it to the user book.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
Documentation/BUG-HUNTING | 162 +++++++++++++++++++------------------
Documentation/user/BUG-HUNTING.rst | 1 +
Documentation/user/index.rst | 1 +
3 files changed, 84 insertions(+), 80 deletions(-)
create mode 120000 Documentation/user/BUG-HUNTING.rst
diff --git a/Documentation/BUG-HUNTING b/Documentation/BUG-HUNTING
index 65022a87bf17..a8ef794aadae 100644
--- a/Documentation/BUG-HUNTING
+++ b/Documentation/BUG-HUNTING
@@ -1,18 +1,8 @@
-Table of contents
-=================
+Bug hunting
++++++++++++
Last updated: 20 December 2005
-Contents
-========
-
-- Introduction
-- Devices not appearing
-- Finding patch that caused a bug
--- Finding using git-bisect
--- Finding it the old way
-- Fixing the bug
-
Introduction
============
@@ -24,7 +14,8 @@ Finding bugs is not always easy. Have a go though. If you can't find it don't
give up. Report as much as you have found to the relevant maintainer. See
MAINTAINERS for who that is for the subsystem you have worked on.
-Before you submit a bug report read REPORTING-BUGS.
+Before you submit a bug report read
+:ref:`Documentation/REPORTING-BUGS <reportingbugs>`.
Devices not appearing
=====================
@@ -37,15 +28,16 @@ Finding patch that caused a bug
-Finding using git-bisect
-------------------------
+Finding using ``git-bisect``
+----------------------------
-Using the provided tools with git makes finding bugs easy provided the bug is
-reproducible.
+Using the provided tools with ``git`` makes finding bugs easy provided the bug
+is reproducible.
Steps to do it:
+
- start using git for the kernel source
-- read the man page for git-bisect
+- read the man page for ``git-bisect``
- have fun
Finding it the old way
@@ -58,22 +50,22 @@ It's a brute force approach but it works pretty well.
You need:
- . A reproducible bug - it has to happen predictably (sorry)
- . All the kernel tar files from a revision that worked to the
+ - A reproducible bug - it has to happen predictably (sorry)
+ - All the kernel tar files from a revision that worked to the
revision that doesn't
You will then do:
- . Rebuild a revision that you believe works, install, and verify that.
- . Do a binary search over the kernels to figure out which one
+ - Rebuild a revision that you believe works, install, and verify that.
+ - Do a binary search over the kernels to figure out which one
introduced the bug. I.e., suppose 1.3.28 didn't have the bug, but
you know that 1.3.69 does. Pick a kernel in the middle and build
that, like 1.3.50. Build & test; if it works, pick the mid point
between .50 and .69, else the mid point between .28 and .50.
- . You'll narrow it down to the kernel that introduced the bug. You
+ - You'll narrow it down to the kernel that introduced the bug. You
can probably do better than this but it gets tricky.
- . Narrow it down to a subdirectory
+ - Narrow it down to a subdirectory
- Copy kernel that works into "test". Let's say that 3.62 works,
but 3.63 doesn't. So you diff -r those two kernels and come
@@ -83,7 +75,7 @@ You will then do:
Copy the non-working directory next to the working directory
as "dir.63".
One directory at time, try moving the working directory to
- "dir.62" and mv dir.63 dir"time, try
+ "dir.62" and mv dir.63 dir"time, try::
mv dir dir.62
mv dir.63 dir
@@ -97,15 +89,15 @@ You will then do:
found in my case that they were self explanatory - you may
or may not want to give up when that happens.
- . Narrow it down to a file
+ - Narrow it down to a file
- You can apply the same technique to each file in the directory,
hoping that the changes in that file are self contained.
- . Narrow it down to a routine
+ - Narrow it down to a routine
- You can take the old file and the new file and manually create
- a merged file that has
+ a merged file that has::
#ifdef VER62
routine()
@@ -120,7 +112,7 @@ You will then do:
#endif
And then walk through that file, one routine at a time and
- prefix it with
+ prefix it with::
#define VER62
/* both routines here */
@@ -153,94 +145,104 @@ To debug a kernel, use objdump and look for the hex offset from the crash
output to find the valid line of code/assembler. Without debug symbols, you
will see the assembler code for the routine shown, but if your kernel has
debug symbols the C code will also be available. (Debug symbols can be enabled
-in the kernel hacking menu of the menu configuration.) For example:
+in the kernel hacking menu of the menu configuration.) For example::
objdump -r -S -l --disassemble net/dccp/ipv4.o
-NB.: you need to be at the top level of the kernel tree for this to pick up
-your C files.
+.. note::
+
+ You need to be at the top level of the kernel tree for this to pick up
+ your C files.
If you don't have access to the code you can also debug on some crash dumps
-e.g. crash dump output as shown by Dave Miller.
+e.g. crash dump output as shown by Dave Miller::
-> EIP is at ip_queue_xmit+0x14/0x4c0
-> ...
-> Code: 44 24 04 e8 6f 05 00 00 e9 e8 fe ff ff 8d 76 00 8d bc 27 00 00
-> 00 00 55 57 56 53 81 ec bc 00 00 00 8b ac 24 d0 00 00 00 8b 5d 08
-> <8b> 83 3c 01 00 00 89 44 24 14 8b 45 28 85 c0 89 44 24 18 0f 85
->
-> Put the bytes into a "foo.s" file like this:
->
-> .text
-> .globl foo
-> foo:
-> .byte .... /* bytes from Code: part of OOPS dump */
->
-> Compile it with "gcc -c -o foo.o foo.s" then look at the output of
-> "objdump --disassemble foo.o".
->
-> Output:
->
-> ip_queue_xmit:
-> push %ebp
-> push %edi
-> push %esi
-> push %ebx
-> sub $0xbc, %esp
-> mov 0xd0(%esp), %ebp ! %ebp = arg0 (skb)
-> mov 0x8(%ebp), %ebx ! %ebx = skb->sk
-> mov 0x13c(%ebx), %eax ! %eax = inet_sk(sk)->opt
+ EIP is at ip_queue_xmit+0x14/0x4c0
+ ...
+ Code: 44 24 04 e8 6f 05 00 00 e9 e8 fe ff ff 8d 76 00 8d bc 27 00 00
+ 00 00 55 57 56 53 81 ec bc 00 00 00 8b ac 24 d0 00 00 00 8b 5d 08
+ <8b> 83 3c 01 00 00 89 44 24 14 8b 45 28 85 c0 89 44 24 18 0f 85
+
+ Put the bytes into a "foo.s" file like this:
+
+ .text
+ .globl foo
+ foo:
+ .byte .... /* bytes from Code: part of OOPS dump */
+
+ Compile it with "gcc -c -o foo.o foo.s" then look at the output of
+ "objdump --disassemble foo.o".
+
+ Output:
+
+ ip_queue_xmit:
+ push %ebp
+ push %edi
+ push %esi
+ push %ebx
+ sub $0xbc, %esp
+ mov 0xd0(%esp), %ebp ! %ebp = arg0 (skb)
+ mov 0x8(%ebp), %ebx ! %ebx = skb->sk
+ mov 0x13c(%ebx), %eax ! %eax = inet_sk(sk)->opt
In addition, you can use GDB to figure out the exact file and line
-number of the OOPS from the vmlinux file. If you have
-CONFIG_DEBUG_INFO enabled, you can simply copy the EIP value from the
-OOPS:
+number of the OOPS from the ``vmlinux`` file. If you have
+``CONFIG_DEBUG_INFO`` enabled, you can simply copy the EIP value from the
+OOPS::
EIP: 0060:[<c021e50e>] Not tainted VLI
-And use GDB to translate that to human-readable form:
+And use GDB to translate that to human-readable form::
gdb vmlinux
(gdb) l *0xc021e50e
-If you don't have CONFIG_DEBUG_INFO enabled, you use the function
-offset from the OOPS:
+If you don't have ``CONFIG_DEBUG_INFO`` enabled, you use the function
+offset from the OOPS::
EIP is at vt_ioctl+0xda8/0x1482
-And recompile the kernel with CONFIG_DEBUG_INFO enabled:
+And recompile the kernel with ``CONFIG_DEBUG_INFO`` enabled::
make vmlinux
gdb vmlinux
(gdb) p vt_ioctl
(gdb) l *(0x<address of vt_ioctl> + 0xda8)
-or, as one command
+
+or, as one command::
+
(gdb) l *(vt_ioctl + 0xda8)
-If you have a call trace, such as :-
->Call Trace:
-> [<ffffffff8802c8e9>] :jbd:log_wait_commit+0xa3/0xf5
-> [<ffffffff810482d9>] autoremove_wake_function+0x0/0x2e
-> [<ffffffff8802770b>] :jbd:journal_stop+0x1be/0x1ee
-> ...
+If you have a call trace, such as::
+
+ Call Trace:
+ [<ffffffff8802c8e9>] :jbd:log_wait_commit+0xa3/0xf5
+ [<ffffffff810482d9>] autoremove_wake_function+0x0/0x2e
+ [<ffffffff8802770b>] :jbd:journal_stop+0x1be/0x1ee
+ ...
+
this shows the problem in the :jbd: module. You can load that module in gdb
-and list the relevant code.
+and list the relevant code::
+
gdb fs/jbd/jbd.ko
(gdb) p log_wait_commit
(gdb) l *(0x<address> + 0xa3)
-or
+
+or::
+
(gdb) l *(log_wait_commit + 0xa3)
Another very useful option of the Kernel Hacking section in menuconfig is
Debug memory allocations. This will help you see whether data has been
initialised and not set before use etc. To see the values that get assigned
-with this look at mm/slab.c and search for POISON_INUSE. When using this an
-Oops will often show the poisoned data instead of zero which is the default.
+with this look at ``mm/slab.c`` and search for ``POISON_INUSE``. When using
+this an Oops will often show the poisoned data instead of zero which is the
+default.
Once you have worked out a fix please submit it upstream. After all open
source is about sharing what you do and don't you want to be recognised for
your genius?
-Please do read Documentation/SubmittingPatches though to help your code get
-accepted.
+Please do read :ref:`Documentation/SubmittingPatches <submittingpatches>`
+though to help your code get accepted.
diff --git a/Documentation/user/BUG-HUNTING.rst b/Documentation/user/BUG-HUNTING.rst
new file mode 120000
index 000000000000..fb5f11ad246d
--- /dev/null
+++ b/Documentation/user/BUG-HUNTING.rst
@@ -0,0 +1 @@
+../BUG-HUNTING
\ No newline at end of file
diff --git a/Documentation/user/index.rst b/Documentation/user/index.rst
index fe4c5b587e6f..d9d8840000b8 100644
--- a/Documentation/user/index.rst
+++ b/Documentation/user/index.rst
@@ -9,6 +9,7 @@ Contents:
README
REPORTING-BUGS
+ BUG-HUNTING
SecurityBugs
kernel-parameters
serial-console
--
2.7.4
[toc] | [prev] | [next] | [standalone]
| From | Mauro Carvalho Chehab <mchehab@s-opensource.com> |
|---|---|
| Date | 2016-09-22 14:00 +0200 |
| Subject | [PATCH 11/17] Documentation/basic_profiling.rst: convert to ReST markup |
| Message-ID | <skaPw-5PF-23@gated-at.bofh.it> |
| In reply to | #1488805 |
Convert it to ReST markup and add it to the user book:
- Add a title to the document;
- touch spaces/new lines to fix Sphinx format;
- use ``foo`` for commands;
- use quote blocks where needed;
- add it to the user book;
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
Documentation/basic_profiling.txt | 59 +++++++++++++++++++++-------------
Documentation/user/basic_profiling.rst | 1 +
Documentation/user/index.rst | 1 +
3 files changed, 38 insertions(+), 23 deletions(-)
create mode 120000 Documentation/user/basic_profiling.rst
diff --git a/Documentation/basic_profiling.txt b/Documentation/basic_profiling.txt
index 8764e9f70821..15a49dbd0189 100644
--- a/Documentation/basic_profiling.txt
+++ b/Documentation/basic_profiling.txt
@@ -1,56 +1,69 @@
+Basic kernel profiling
+======================
+
+
These instructions are deliberately very basic. If you want something clever,
-go read the real docs ;-) Please don't add more stuff, but feel free to
+go read the real docs ;-)
+
+Please don't add more stuff, but feel free to
correct my mistakes ;-) (mbligh@aracnet.com)
+
Thanks to John Levon, Dave Hansen, et al. for help writing this.
-<test> is the thing you're trying to measure.
-Make sure you have the correct System.map / vmlinux referenced!
+``<test>`` is the thing you're trying to measure.
+Make sure you have the correct ``System.map`` / ``vmlinux`` referenced!
-It is probably easiest to use "make install" for linux and hack
-/sbin/installkernel to copy vmlinux to /boot, in addition to vmlinuz,
-config, System.map, which are usually installed by default.
+It is probably easiest to use ``make install`` for linux and hack
+``/sbin/installkernel`` to copy ``vmlinux`` to ``/boot``, in addition to
+``vmlinuz``, ``config``, ``System.map``, which are usually installed by default.
Readprofile
-----------
-A recent readprofile command is needed for 2.6, such as found in util-linux
+
+A recent ``readprofile`` command is needed for 2.6, such as found in util-linux
2.12a, which can be downloaded from:
-http://www.kernel.org/pub/linux/utils/util-linux/
+ http://www.kernel.org/pub/linux/utils/util-linux/
Most distributions will ship it already.
-Add "profile=2" to the kernel command line.
+Add ``profile=2`` to the kernel command line.
-clear readprofile -r
- <test>
-dump output readprofile -m /boot/System.map > captured_profile
+Some ``readprofile`` commands::
+
+ clear readprofile -r
+ <test>
+ dump output readprofile -m /boot/System.map > captured_profile
Oprofile
--------
Get the source (see Changes for required version) from
-http://oprofile.sourceforge.net/ and add "idle=poll" to the kernel command
+http://oprofile.sourceforge.net/ and add ``idle=poll`` to the kernel command
line.
-Configure with CONFIG_PROFILING=y and CONFIG_OPROFILE=y & reboot on new kernel
+Configure with ``CONFIG_PROFILING=y`` and ``CONFIG_OPROFILE=y`` & reboot on new kernel::
-./configure --with-kernel-support
-make install
+ ./configure --with-kernel-support
+ make install
For superior results, be sure to enable the local APIC. If opreport sees
a 0Hz CPU, APIC was not on. Be aware that idle=poll may mean a performance
penalty.
-One time setup:
- opcontrol --setup --vmlinux=/boot/vmlinux
+One time setup::
-clear opcontrol --reset
-start opcontrol --start
+ opcontrol --setup --vmlinux=/boot/vmlinux
+
+Some ``opcontrol`` commands::
+
+ clear opcontrol --reset
+ start opcontrol --start
<test>
-stop opcontrol --stop
-dump output opreport > output_file
+ stop opcontrol --stop
+ dump output opreport > output_file
-To only report on the kernel, run opreport -l /boot/vmlinux > output_file
+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/user/basic_profiling.rst b/Documentation/user/basic_profiling.rst
new file mode 120000
index 000000000000..5b1481ea0736
--- /dev/null
+++ b/Documentation/user/basic_profiling.rst
@@ -0,0 +1 @@
+../basic_profiling.txt
\ No newline at end of file
diff --git a/Documentation/user/index.rst b/Documentation/user/index.rst
index d4886e366b5a..6ac599ba0886 100644
--- a/Documentation/user/index.rst
+++ b/Documentation/user/index.rst
@@ -12,3 +12,4 @@ Contents:
SecurityBugs
kernel-parameters
bad_memory
+ basic_profiling
--
2.7.4
[toc] | [prev] | [next] | [standalone]
| From | Mauro Carvalho Chehab <mchehab@s-opensource.com> |
|---|---|
| Date | 2016-09-22 14:00 +0200 |
| Subject | [PATCH 03/17] docs-rst: add inter-document cross references |
| Message-ID | <skaPw-5PF-21@gated-at.bofh.it> |
| In reply to | #1488805 |
Add cross references for the development process documents
that were converted to ReST:
Documentation/SubmitChecklist
Documentation/SubmittingDrivers
Documentation/SubmittingPatches
Documentation/development-process/development-process.rst
Documentation/stable_kernel_rules.txt
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
Documentation/SubmitChecklist | 10 +++++----
Documentation/SubmittingDrivers | 7 ++++---
Documentation/SubmittingPatches | 24 ++++++++++++++--------
.../development-process/development-process.rst | 2 ++
Documentation/stable_kernel_rules.txt | 7 +++++--
5 files changed, 32 insertions(+), 18 deletions(-)
diff --git a/Documentation/SubmitChecklist b/Documentation/SubmitChecklist
index 22a370ff34e5..894289b22b15 100644
--- a/Documentation/SubmitChecklist
+++ b/Documentation/SubmitChecklist
@@ -1,3 +1,5 @@
+.. _submitchecklist:
+
Linux Kernel patch submission checklist
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -5,7 +7,7 @@ Here are some basic things that developers should do if they want to see their
kernel patch submissions accepted more quickly.
These are all above and beyond the documentation that is provided in
-Documentation/SubmittingPatches
+:ref:`Documentation/SubmittingPatches <submittingpatches>`
and elsewhere regarding submitting Linux kernel patches.
@@ -28,8 +30,8 @@ and elsewhere regarding submitting Linux kernel patches.
4) ppc64 is a good architecture for cross-compilation checking because it
tends to use ``unsigned long`` for 64-bit quantities.
-5: Check your patch for general style as detailed in
- Documentation/CodingStyle.
+5) Check your patch for general style as detailed in
+ :ref:`Documentation/CodingStyle <codingstyle>`.
Check for trivial violations with the patch style checker prior to
submission (``scripts/checkpatch.pl``).
You should be able to justify all violations that remain in
@@ -54,7 +56,7 @@ and elsewhere regarding submitting Linux kernel patches.
but any one function that uses more than 512 bytes on the stack is a
candidate for change.
-11: Include :ref:`kernel-doc <kernel_doc>` to document global kernel APIs.
+11) Include :ref:`kernel-doc <kernel_doc>` to document global kernel APIs.
(Not required for static functions, but OK there also.) Use
``make htmldocs`` or ``make pdfdocs`` to check the
:ref:`kernel-doc <kernel_doc>` and fix any issues.
diff --git a/Documentation/SubmittingDrivers b/Documentation/SubmittingDrivers
index 2ac931645e53..252b77a23fad 100644
--- a/Documentation/SubmittingDrivers
+++ b/Documentation/SubmittingDrivers
@@ -40,9 +40,9 @@ Linux 2.4:
maintainer does not respond or you cannot find the appropriate
maintainer then please contact Willy Tarreau <w@1wt.eu>.
-Linux 2.6:
+Linux 2.6 and upper:
The same rules apply as 2.4 except that you should follow linux-kernel
- to track changes in API's. The final contact point for Linux 2.6
+ to track changes in API's. The final contact point for Linux 2.6+
submissions is Andrew Morton.
What Criteria Determine Acceptance
@@ -73,7 +73,8 @@ Interfaces:
Code:
Please use the Linux style of code formatting as documented
- in Documentation/CodingStyle. If you have sections of code
+ in :ref:`Documentation/CodingStyle <codingStyle>`.
+ If you have sections of code
that need to be in other formats, for example because they
are shared with a windows driver kit and you want to
maintain them just once separate them out nicely and note
diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index 9c3dfa7babf3..36f1dedc944c 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -10,10 +10,12 @@ can greatly increase the chances of your change being accepted.
This document contains a large number of suggestions in a relatively terse
format. For detailed information on how the kernel development process
-works, see Documentation/development-process. Also, read
-Documentation/SubmitChecklist for a list of items to check before
+works, see :ref:`Documentation/development-process <development_process_main>`.
+Also, read :ref:`Documentation/SubmitChecklist <submitchecklist>`
+for a list of items to check before
submitting code. If you are submitting a driver, also read
-Documentation/SubmittingDrivers; for device tree binding patches, read
+:ref:`Documentation/SubmittingDrivers <submittingdrivers>`;
+for device tree binding patches, read
Documentation/devicetree/bindings/submitting-patches.txt.
Many of these steps describe the default behavior of the ``git`` version
@@ -235,7 +237,9 @@ then only post say 15 or so at a time and wait for review and integration.
---------------------------
Check your patch for basic style violations, details of which can be
-found in Documentation/CodingStyle. Failure to do so simply wastes
+found in
+:ref:`Documentation/CodingStyle <codingstyle>`.
+Failure to do so simply wastes
the reviewers time and will get your patch rejected, probably
without even being read.
@@ -300,8 +304,9 @@ toward the stable maintainers by putting a line like this::
Cc: stable@vger.kernel.org
into the sign-off area of your patch (note, NOT an email recipient). You
-should also read Documentation/stable_kernel_rules.txt in addition to this
-file.
+should also read
+:ref:`Documentation/stable_kernel_rules.txt <stable_kernel_rules>`
+in addition to this file.
Note, however, that some subsystem maintainers want to come to their own
conclusions on which patches should go to the stable trees. The networking
@@ -358,8 +363,9 @@ decreasing the likelihood of your MIME-attached change being accepted.
Exception: If your mailer is mangling patches then someone may ask
you to re-send them using MIME.
-See Documentation/email-clients.txt for hints about configuring
-your e-mail client so that it sends your patches untouched.
+See :ref:`Documentation/email-clients.txt <email_clients>`
+for hints about configuring your e-mail client so that it sends your patches
+untouched.
7) E-mail size
--------------
@@ -823,7 +829,7 @@ NO!!!! No more huge patch bombs to linux-kernel@vger.kernel.org people!
<https://lkml.org/lkml/2005/7/11/336>
Kernel Documentation/CodingStyle:
- <Documentation/CodingStyle>
+ :ref:`Documentation/CodingStyle <codingstyle>`
Linus Torvalds's mail on the canonical patch format:
<http://lkml.org/lkml/2005/4/7/183>
diff --git a/Documentation/development-process/development-process.rst b/Documentation/development-process/development-process.rst
index d431a1098875..bd1399f7202a 100644
--- a/Documentation/development-process/development-process.rst
+++ b/Documentation/development-process/development-process.rst
@@ -1,3 +1,5 @@
+.. _development_process_main:
+
A guide to the Kernel Development Process
=========================================
diff --git a/Documentation/stable_kernel_rules.txt b/Documentation/stable_kernel_rules.txt
index 1eba72708c7f..4d82e31b7958 100644
--- a/Documentation/stable_kernel_rules.txt
+++ b/Documentation/stable_kernel_rules.txt
@@ -26,7 +26,9 @@ Rules on what kind of patches are accepted, and which ones are not, into the
race can be exploited is also provided.
- It cannot contain any "trivial" fixes in it (spelling changes,
whitespace cleanups, etc).
- - It must follow the Documentation/SubmittingPatches rules.
+ - It must follow the
+ :ref:`Documentation/SubmittingPatches <submittingpatches>`
+ rules.
- It or an equivalent fix must already exist in Linus' tree (upstream).
@@ -37,7 +39,8 @@ Procedure for submitting patches to the -stable tree
submission guidelines as described in
Documentation/networking/netdev-FAQ.txt
- Security patches should not be handled (solely) by the -stable review
- process but should follow the procedures in Documentation/SecurityBugs.
+ process but should follow the procedures in
+ :ref:`Documentation/SecurityBugs <securitybugs>`.
For all other submissions, choose one of the following procedures
-----------------------------------------------------------------
--
2.7.4
[toc] | [prev] | [next] | [standalone]
| From | Mauro Carvalho Chehab <mchehab@s-opensource.com> |
|---|---|
| Date | 2016-09-22 14:00 +0200 |
| Subject | [PATCH 06/17] Documentation/kernel-parameters.txt: convert to ReST markup |
| Message-ID | <skaPw-5PF-33@gated-at.bofh.it> |
| In reply to | #1488805 |
Adjust the file for it to be parsed by Sphinx:
- adjust the document title to be parsed;
- use :: for quote blocks;
- fix the horizontal bar markup;
- lower case the TODO title.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
Documentation/kernel-parameters.txt | 33 +++++++++++++++++++--------------
1 file changed, 19 insertions(+), 14 deletions(-)
diff --git a/Documentation/kernel-parameters.txt b/Documentation/kernel-parameters.txt
index 861f57514fbd..96cb618decf1 100644
--- a/Documentation/kernel-parameters.txt
+++ b/Documentation/kernel-parameters.txt
@@ -1,5 +1,5 @@
- Kernel Parameters
- ~~~~~~~~~~~~~~~~~
+Kernel Parameters
+~~~~~~~~~~~~~~~~~
The following is a consolidated list of the kernel parameters as
implemented by the __setup(), core_param() and module_param() macros
@@ -14,7 +14,7 @@ environment, others are passed as command line arguments to init.
Everything after "--" is passed as an argument to init.
Module parameters can be specified in two ways: via the kernel command
-line with a module name prefix, or via modprobe, e.g.:
+line with a module name prefix, or via modprobe, e.g.::
(kernel command line) usbcore.blinkenlights=1
(modprobe command line) modprobe usbcore blinkenlights=1
@@ -25,12 +25,16 @@ kernel command line (/proc/cmdline) and collects module parameters
when it loads a module, so the kernel command line can be used for
loadable modules too.
-Hyphens (dashes) and underscores are equivalent in parameter names, so
+Hyphens (dashes) and underscores are equivalent in parameter names, so::
+
log_buf_len=1M print-fatal-signals=1
-can also be entered as
+
+can also be entered as::
+
log-buf-len=1M print_fatal_signals=1
-Double-quotes can be used to protect spaces in values, e.g.:
+Double-quotes can be used to protect spaces in values, e.g.::
+
param="spaces in here"
This document may not be entirely up to date and comprehensive. The command
@@ -38,12 +42,12 @@ This document may not be entirely up to date and comprehensive. The command
module. Loadable modules, after being loaded into the running kernel, also
reveal their parameters in /sys/module/${modulename}/parameters/. Some of these
parameters may be changed at runtime by the command
-"echo -n ${value} > /sys/module/${modulename}/parameters/${parm}".
+``echo -n ${value} > /sys/module/${modulename}/parameters/${parm}``.
The parameters listed below are only valid if certain kernel build options were
enabled and if respective hardware is present. The text in square brackets at
the beginning of each description states the restrictions within which a
-parameter is applicable:
+parameter is applicable::
ACPI ACPI support is enabled.
AGP AGP (Accelerated Graphics Port) is enabled.
@@ -134,7 +138,7 @@ parameter is applicable:
X86_UV SGI UV support is enabled.
XEN Xen support is enabled
-In addition, the following text indicates that the option:
+In addition, the following text indicates that the option::
BUGS= Relates to possible processor bugs on the said processor.
KNL Is a kernel start-up parameter.
@@ -163,7 +167,7 @@ and is between 256 and 4096 characters. It is defined in the file
Finally, the [KMG] suffix is commonly described after a number of kernel
parameter values. These 'K', 'M', and 'G' letters represent the _binary_
multipliers 'Kilo', 'Mega', and 'Giga', equalling 2^10, 2^20, and 2^30
-bytes respectively. Such letter suffixes can also be entirely omitted.
+bytes respectively. Such letter suffixes can also be entirely omitted::
acpi= [HW,ACPI,X86,ARM64]
@@ -2479,7 +2483,7 @@ bytes respectively. Such letter suffixes can also be entirely omitted.
will be sent.
The default is to send the implementation identification
information.
-
+
nfs.recover_lost_locks =
[NFSv4] Attempt to recover locks that were lost due
to a lease timeout on the server. Please note that
@@ -4124,7 +4128,7 @@ bytes respectively. Such letter suffixes can also be entirely omitted.
See also Documentation/input/joystick-parport.txt
udbg-immortal [PPC] When debugging early kernel crashes that
- happen after console_init() and before a proper
+ happen after console_init() and before a proper
console driver takes over, this boot options might
help "seeing" what's going on.
@@ -4490,8 +4494,9 @@ bytes respectively. Such letter suffixes can also be entirely omitted.
Format:
<irq>,<irq_mask>,<io>,<full_duplex>,<do_sound>,<lockup_hack>[,<irq2>[,<irq3>[,<irq4>]]]
-______________________________________________________________________
+------------------------
-TODO:
+Todo
+----
Add more DRM drivers.
--
2.7.4
[toc] | [prev] | [next] | [standalone]
| From | Mauro Carvalho Chehab <mchehab@s-opensource.com> |
|---|---|
| Date | 2016-09-22 14:00 +0200 |
| Subject | [PATCH 14/17] Documentation/braille-console: convert it to ReST markup |
| Message-ID | <skaPw-5PF-43@gated-at.bofh.it> |
| In reply to | #1488805 |
- Fix identation for the document title;
- use monotonic fonts for paths;
- use quote blocks where needed;
- adjust spaces to properly format paragraphs;
- use :menuselection: and :kbd: for the menu item and keys;
- point too the right item at the menu;
- add it to the user book.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
Documentation/braille-console.txt | 30 +++++++++++++++++-------------
Documentation/serial-console.txt | 2 ++
Documentation/user/braile-console.rst | 1 +
Documentation/user/index.rst | 1 +
4 files changed, 21 insertions(+), 13 deletions(-)
create mode 120000 Documentation/user/braile-console.rst
diff --git a/Documentation/braille-console.txt b/Documentation/braille-console.txt
index d0d042c2fd5e..fa3702dc04ab 100644
--- a/Documentation/braille-console.txt
+++ b/Documentation/braille-console.txt
@@ -1,33 +1,37 @@
- Linux Braille Console
+Linux Braille Console
+=====================
To get early boot messages on a braille device (before userspace screen
readers can start), you first need to compile the support for the usual serial
-console (see serial-console.txt), and for braille device (in Device Drivers -
-Accessibility).
+console (see :ref:`Documentation/serial-console.txt <serial_console>`), and
+for braille device
+(in :menuselection:`Device Drivers --> Accessibility support --> Console on braille device`).
-Then you need to specify a console=brl, option on the kernel command line, the
-format is:
+Then you need to specify a ``console=brl``, option on the kernel command line, the
+format is::
console=brl,serial_options...
-where serial_options... are the same as described in serial-console.txt
+where ``serial_options...`` are the same as described in
+:ref:`Documentation/serial-console.txt <serial_console>`.
-So for instance you can use console=brl,ttyS0 if the braille device is connected
-to the first serial port, and console=brl,ttyS0,115200 to override the baud rate
-to 115200, etc.
+So for instance you can use ``console=brl,ttyS0`` if the braille device is connected to the first serial port, and ``console=brl,ttyS0,115200`` to
+override the baud rate to 115200, etc.
By default, the braille device will just show the last kernel message (console
mode). To review previous messages, press the Insert key to switch to the VT
review mode. In review mode, the arrow keys permit to browse in the VT content,
-page up/down keys go at the top/bottom of the screen, and the home key goes back
+:kbd:`PAGE-UP`/:kbd:`PAGE-DOWN` keys go at the top/bottom of the screen, and
+the :kbd:`HOME` key goes back
to the cursor, hence providing very basic screen reviewing facility.
-Sound feedback can be obtained by adding the braille_console.sound=1 kernel
+Sound feedback can be obtained by adding the ``braille_console.sound=1`` kernel
parameter.
For simplicity, only one braille console can be enabled, other uses of
-console=brl,... will be discarded. Also note that it does not interfere with
-the console selection mechanism described in serial-console.txt
+``console=brl,...`` will be discarded. Also note that it does not interfere with
+the console selection mechanism described in
+:ref:`Documentation/serial-console.txt <serial_console>`.
For now, only the VisioBraille device is supported.
diff --git a/Documentation/serial-console.txt b/Documentation/serial-console.txt
index 1d9a3e48e929..a8d1e36b627a 100644
--- a/Documentation/serial-console.txt
+++ b/Documentation/serial-console.txt
@@ -1,3 +1,5 @@
+.. _serial_console:
+
Linux Serial Console
====================
diff --git a/Documentation/user/braile-console.rst b/Documentation/user/braile-console.rst
new file mode 120000
index 000000000000..3a4e6444407a
--- /dev/null
+++ b/Documentation/user/braile-console.rst
@@ -0,0 +1 @@
+../braille-console.txt
\ No newline at end of file
diff --git a/Documentation/user/index.rst b/Documentation/user/index.rst
index 8b0afcac2a72..fe4c5b587e6f 100644
--- a/Documentation/user/index.rst
+++ b/Documentation/user/index.rst
@@ -12,6 +12,7 @@ Contents:
SecurityBugs
kernel-parameters
serial-console
+ braile-console
binfmt_misc
bad_memory
basic_profiling
--
2.7.4
[toc] | [prev] | [next] | [standalone]
| From | Mauro Carvalho Chehab <mchehab@s-opensource.com> |
|---|---|
| Date | 2016-09-22 14:00 +0200 |
| Subject | [PATCH 04/17] REPORTING-BUGS: convert to ReST markup |
| Message-ID | <skaPw-5PF-47@gated-at.bofh.it> |
| In reply to | #1488805 |
- add a title to the document;
- use :: before verbatim blocks;
- add blank lines where required;
- use protocol for URL references;
- use a verbatim block for the bugs template;
- add cross references to SecurityBugs.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
REPORTING-BUGS | 66 ++++++++++++++++++++++++++++++++--------------------------
1 file changed, 37 insertions(+), 29 deletions(-)
diff --git a/REPORTING-BUGS b/REPORTING-BUGS
index 914baf9cf5fa..05c53ac7fa76 100644
--- a/REPORTING-BUGS
+++ b/REPORTING-BUGS
@@ -1,3 +1,8 @@
+.. _reportingbugs:
+
+Reporting bugs
+++++++++++++++
+
Background
==========
@@ -50,12 +55,13 @@ 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:
+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
-Documentation/SecurityBugs for more information.
+: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
@@ -69,8 +75,9 @@ 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
+ 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
@@ -99,34 +106,34 @@ 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".
+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.
+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:
+ [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
@@ -153,7 +160,8 @@ 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 LWN.net for more info:
+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
--
2.7.4
[toc] | [prev] | [next] | [standalone]
| From | Mauro Carvalho Chehab <mchehab@s-opensource.com> |
|---|---|
| Date | 2016-09-22 14:00 +0200 |
| Subject | [PATCH 12/17] Documentation/binfmt_misc.txt: convert it to ReST markup |
| Message-ID | <skaPw-5PF-45@gated-at.bofh.it> |
| In reply to | #1488805 |
- Fix identation for the document title;
- use monotonic fonts for commands, paths, etc;
- use quote blocks where needed;
- adjust spaces to properly format paragraphs;
- add it to the user book.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
Documentation/binfmt_misc.txt | 134 +++++++++++++++++++++----------------
Documentation/user/binfmt_misc.rst | 1 +
Documentation/user/index.rst | 1 +
3 files changed, 79 insertions(+), 57 deletions(-)
create mode 120000 Documentation/user/binfmt_misc.rst
diff --git a/Documentation/binfmt_misc.txt b/Documentation/binfmt_misc.txt
index ec83bbce547a..9c5ff8f260bf 100644
--- a/Documentation/binfmt_misc.txt
+++ b/Documentation/binfmt_misc.txt
@@ -1,5 +1,5 @@
- Kernel Support for miscellaneous (your favourite) Binary Formats v1.1
- =====================================================================
+Kernel Support for miscellaneous (your favourite) Binary Formats v1.1
+=====================================================================
This Kernel feature allows you to invoke almost (for restrictions see below)
every program by simply typing its name in the shell.
@@ -9,122 +9,142 @@ To achieve this you must tell binfmt_misc which interpreter has to be invoked
with which binary. Binfmt_misc recognises the binary-type by matching some bytes
at the beginning of the file with a magic byte sequence (masking out specified
bits) you have supplied. Binfmt_misc can also recognise a filename extension
-aka '.com' or '.exe'.
+aka ``.com`` or ``.exe``.
-First you must mount binfmt_misc:
- mount binfmt_misc -t binfmt_misc /proc/sys/fs/binfmt_misc
+First you must mount binfmt_misc::
+
+ mount binfmt_misc -t binfmt_misc /proc/sys/fs/binfmt_misc
To actually register a new binary type, you have to set up a string looking like
-:name:type:offset:magic:mask:interpreter:flags (where you can choose the ':'
-upon your needs) and echo it to /proc/sys/fs/binfmt_misc/register.
+``:name:type:offset:magic:mask:interpreter:flags`` (where you can choose the
+``:`` upon your needs) and echo it to ``/proc/sys/fs/binfmt_misc/register``.
Here is what the fields mean:
- - 'name' is an identifier string. A new /proc file will be created with this
- name below /proc/sys/fs/binfmt_misc; cannot contain slashes '/' for obvious
- reasons.
- - 'type' is the type of recognition. Give 'M' for magic and 'E' for extension.
- - 'offset' is the offset of the magic/mask in the file, counted in bytes. This
- defaults to 0 if you omit it (i.e. you write ':name:type::magic...'). Ignored
- when using filename extension matching.
- - 'magic' is the byte sequence binfmt_misc is matching for. The magic string
- may contain hex-encoded characters like \x0a or \xA4. Note that you must
- escape any NUL bytes; parsing halts at the first one. In a shell environment
- you might have to write \\x0a to prevent the shell from eating your \.
+
+- ``name``
+ is an identifier string. A new /proc file will be created with this
+ ``name below /proc/sys/fs/binfmt_misc``; cannot contain slashes ``/`` for
+ obvious reasons.
+- ``type``
+ is the type of recognition. Give ``M`` for magic and ``E`` for extension.
+- ``offset``
+ is the offset of the magic/mask in the file, counted in bytes. This
+ defaults to 0 if you omit it (i.e. you write ``:name:type::magic...``).
+ Ignored when using filename extension matching.
+- ``magic``
+ is the byte sequence binfmt_misc is matching for. The magic string
+ may contain hex-encoded characters like ``\x0a`` or ``\xA4``. Note that you
+ must escape any NUL bytes; parsing halts at the first one. In a shell
+ environment you might have to write ``\\x0a`` to prevent the shell from
+ eating your ``\``.
If you chose filename extension matching, this is the extension to be
- recognised (without the '.', the \x0a specials are not allowed). Extension
- matching is case sensitive, and slashes '/' are not allowed!
- - 'mask' is an (optional, defaults to all 0xff) mask. You can mask out some
+ recognised (without the ``.``, the ``\x0a`` specials are not allowed).
+ Extension matching is case sensitive, and slashes ``/`` are not allowed!
+- ``mask``
+ is an (optional, defaults to all 0xff) mask. You can mask out some
bits from matching by supplying a string like magic and as long as magic.
The mask is anded with the byte sequence of the file. Note that you must
escape any NUL bytes; parsing halts at the first one. Ignored when using
filename extension matching.
- - 'interpreter' is the program that should be invoked with the binary as first
+- ``interpreter``
+ is the program that should be invoked with the binary as first
argument (specify the full path)
- - 'flags' is an optional field that controls several aspects of the invocation
+- ``flags``
+ is an optional field that controls several aspects of the invocation
of the interpreter. It is a string of capital letters, each controls a
- certain aspect. The following flags are supported -
- 'P' - preserve-argv[0]. Legacy behavior of binfmt_misc is to overwrite
+ certain aspect. The following flags are supported:
+
+ ``P`` - preserve-argv[0]
+ Legacy behavior of binfmt_misc is to overwrite
the original argv[0] with the full path to the binary. When this
flag is included, binfmt_misc will add an argument to the argument
- vector for this purpose, thus preserving the original argv[0].
- e.g. If your interp is set to /bin/foo and you run `blah` (which is
- in /usr/local/bin), then the kernel will execute /bin/foo with
- argv[] set to ["/bin/foo", "/usr/local/bin/blah", "blah"]. The
- interp has to be aware of this so it can execute /usr/local/bin/blah
- with argv[] set to ["blah"].
- 'O' - open-binary. Legacy behavior of binfmt_misc is to pass the full path
+ vector for this purpose, thus preserving the original ``argv[0]``.
+ e.g. If your interp is set to ``/bin/foo`` and you run ``blah``
+ (which is in ``/usr/local/bin``), then the kernel will execute
+ ``/bin/foo`` with ``argv[]`` set to ``["/bin/foo", "/usr/local/bin/blah", "blah"]``. The interp has to be aware of this so it can
+ execute ``/usr/local/bin/blah``
+ with ``argv[]`` set to ``["blah"]``.
+ ``O`` - open-binary
+ Legacy behavior of binfmt_misc is to pass the full path
of the binary to the interpreter as an argument. When this flag is
included, binfmt_misc will open the file for reading and pass its
descriptor as an argument, instead of the full path, thus allowing
the interpreter to execute non-readable binaries. This feature
should be used with care - the interpreter has to be trusted not to
emit the contents of the non-readable binary.
- 'C' - credentials. Currently, the behavior of binfmt_misc is to calculate
+ ``C`` - credentials
+ Currently, the behavior of binfmt_misc is to calculate
the credentials and security token of the new process according to
the interpreter. When this flag is included, these attributes are
- calculated according to the binary. It also implies the 'O' flag.
+ calculated according to the binary. It also implies the ``O`` flag.
This feature should be used with care as the interpreter
will run with root permissions when a setuid binary owned by root
is run with binfmt_misc.
- 'F' - fix binary. The usual behaviour of binfmt_misc is to spawn the
- binary lazily when the misc format file is invoked. However,
- this doesn't work very well in the face of mount namespaces and
- changeroots, so the F mode opens the binary as soon as the
+ ``F`` - fix binary
+ The usual behaviour of binfmt_misc is to spawn the
+ binary lazily when the misc format file is invoked. However,
+ this doesn``t work very well in the face of mount namespaces and
+ changeroots, so the ``F`` mode opens the binary as soon as the
emulation is installed and uses the opened image to spawn the
emulator, meaning it is always available once installed,
regardless of how the environment changes.
There are some restrictions:
+
- the whole register string may not exceed 1920 characters
- the magic must reside in the first 128 bytes of the file, i.e.
offset+size(magic) has to be less than 128
- the interpreter string may not exceed 127 characters
To use binfmt_misc you have to mount it first. You can mount it with
-"mount -t binfmt_misc none /proc/sys/fs/binfmt_misc" command, or you can add
-a line "none /proc/sys/fs/binfmt_misc binfmt_misc defaults 0 0" to your
-/etc/fstab so it auto mounts on boot.
+``mount -t binfmt_misc none /proc/sys/fs/binfmt_misc`` command, or you can add
+a line ``none /proc/sys/fs/binfmt_misc binfmt_misc defaults 0 0`` to your
+``/etc/fstab`` so it auto mounts on boot.
-You may want to add the binary formats in one of your /etc/rc scripts during
+You may want to add the binary formats in one of your ``/etc/rc`` scripts during
boot-up. Read the manual of your init program to figure out how to do this
right.
Think about the order of adding entries! Later added entries are matched first!
-A few examples (assumed you are in /proc/sys/fs/binfmt_misc):
+A few examples (assumed you are in ``/proc/sys/fs/binfmt_misc``):
-- enable support for em86 (like binfmt_em86, for Alpha AXP only):
- echo ':i386:M::\x7fELF\x01\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x02\x00\x03:\xff\xff\xff\xff\xff\xfe\xfe\xff\xff\xff\xff\xff\xff\xff\xff\xff\xfb\xff\xff:/bin/em86:' > register
- echo ':i486:M::\x7fELF\x01\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x02\x00\x06:\xff\xff\xff\xff\xff\xfe\xfe\xff\xff\xff\xff\xff\xff\xff\xff\xff\xfb\xff\xff:/bin/em86:' > register
+- enable support for em86 (like binfmt_em86, for Alpha AXP only)::
-- enable support for packed DOS applications (pre-configured dosemu hdimages):
- echo ':DEXE:M::\x0eDEX::/usr/bin/dosexec:' > register
+ echo ':i386:M::\x7fELF\x01\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x02\x00\x03:\xff\xff\xff\xff\xff\xfe\xfe\xff\xff\xff\xff\xff\xff\xff\xff\xff\xfb\xff\xff:/bin/em86:' > register
+ echo ':i486:M::\x7fELF\x01\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x02\x00\x06:\xff\xff\xff\xff\xff\xfe\xfe\xff\xff\xff\xff\xff\xff\xff\xff\xff\xfb\xff\xff:/bin/em86:' > register
-- enable support for Windows executables using wine:
- echo ':DOSWin:M::MZ::/usr/local/bin/wine:' > register
+- enable support for packed DOS applications (pre-configured dosemu hdimages)::
+
+ echo ':DEXE:M::\x0eDEX::/usr/bin/dosexec:' > register
+
+- enable support for Windows executables using wine::
+
+ echo ':DOSWin:M::MZ::/usr/local/bin/wine:' > register
For java support see Documentation/java.txt
You can enable/disable binfmt_misc or one binary type by echoing 0 (to disable)
-or 1 (to enable) to /proc/sys/fs/binfmt_misc/status or /proc/.../the_name.
-Catting the file tells you the current status of binfmt_misc/the entry.
+or 1 (to enable) to ``/proc/sys/fs/binfmt_misc/status`` or
+``/proc/.../the_name``.
+Catting the file tells you the current status of ``binfmt_misc/the_entry``.
-You can remove one entry or all entries by echoing -1 to /proc/.../the_name
-or /proc/sys/fs/binfmt_misc/status.
+You can remove one entry or all entries by echoing -1 to ``/proc/.../the_name``
+or ``/proc/sys/fs/binfmt_misc/status``.
-HINTS:
-======
+Hints
+-----
If you want to pass special arguments to your interpreter, you can
write a wrapper script for it. See Documentation/java.txt for an
example.
Your interpreter should NOT look in the PATH for the filename; the kernel
-passes it the full filename (or the file descriptor) to use. Using $PATH can
+passes it the full filename (or the file descriptor) to use. Using ``$PATH`` can
cause unexpected behaviour and can be a security hazard.
diff --git a/Documentation/user/binfmt_misc.rst b/Documentation/user/binfmt_misc.rst
new file mode 120000
index 000000000000..9eac529ea9a1
--- /dev/null
+++ b/Documentation/user/binfmt_misc.rst
@@ -0,0 +1 @@
+../binfmt_misc.txt
\ No newline at end of file
diff --git a/Documentation/user/index.rst b/Documentation/user/index.rst
index 6ac599ba0886..22f2ccac102b 100644
--- a/Documentation/user/index.rst
+++ b/Documentation/user/index.rst
@@ -11,5 +11,6 @@ Contents:
REPORTING-BUGS
SecurityBugs
kernel-parameters
+ binfmt_misc
bad_memory
basic_profiling
--
2.7.4
[toc] | [prev] | [next] | [standalone]
| From | Mauro Carvalho Chehab <mchehab@s-opensource.com> |
|---|---|
| Date | 2016-09-22 14:00 +0200 |
| Subject | [PATCH 10/17] Documentation/bad_memory.txt: convert it to ReST markup |
| Message-ID | <skaPw-5PF-51@gated-at.bofh.it> |
| In reply to | #1488805 |
- promote the section level of the document name;
- add/remove spaces/new lines where needed to format the output;
- use quote blocks.
- add it to the user book.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
Documentation/bad_memory.txt | 26 ++++++++++++++++----------
Documentation/user/bad_memory.rst | 1 +
Documentation/user/index.rst | 1 +
3 files changed, 18 insertions(+), 10 deletions(-)
create mode 120000 Documentation/user/bad_memory.rst
diff --git a/Documentation/bad_memory.txt b/Documentation/bad_memory.txt
index df8416213202..5cac93e27a97 100644
--- a/Documentation/bad_memory.txt
+++ b/Documentation/bad_memory.txt
@@ -1,9 +1,10 @@
+How to deal with bad memory e.g. reported by memtest86+ ?
+=========================================================
+
March 2008
Jan-Simon Moeller, dl9pf@gmx.de
-How to deal with bad memory e.g. reported by memtest86+ ?
-#########################################################
There are three possibilities I know of:
@@ -19,6 +20,7 @@ This Howto is about number 3) .
BadRAM
######
+
BadRAM is the actively developed and available as kernel-patch
here: http://rick.vanrein.org/linux/badram/
@@ -31,15 +33,19 @@ memmap is already in the kernel and usable as kernel-parameter at
boot-time. Its syntax is slightly strange and you may need to
calculate the values by yourself!
-Syntax to exclude a memory area (see kernel-parameters.txt for details):
-memmap=<size>$<address>
+Syntax to exclude a memory area (see kernel-parameters.txt for details)::
+
+ memmap=<size>$<address>
Example: memtest86+ reported here errors at address 0x18691458, 0x18698424 and
- some others. All had 0x1869xxxx in common, so I chose a pattern of
- 0x18690000,0xffff0000.
+some others. All had 0x1869xxxx in common, so I chose a pattern of
+0x18690000,0xffff0000.
-With the numbers of the example above:
-memmap=64K$0x18690000
- or
-memmap=0x10000$0x18690000
+With the numbers of the example above::
+
+ memmap=64K$0x18690000
+
+or::
+
+ memmap=0x10000$0x18690000
diff --git a/Documentation/user/bad_memory.rst b/Documentation/user/bad_memory.rst
new file mode 120000
index 000000000000..c5ffc33348f2
--- /dev/null
+++ b/Documentation/user/bad_memory.rst
@@ -0,0 +1 @@
+../bad_memory.txt
\ No newline at end of file
diff --git a/Documentation/user/index.rst b/Documentation/user/index.rst
index 280e62f21efa..d4886e366b5a 100644
--- a/Documentation/user/index.rst
+++ b/Documentation/user/index.rst
@@ -11,3 +11,4 @@ Contents:
REPORTING-BUGS
SecurityBugs
kernel-parameters
+ bad_memory
--
2.7.4
[toc] | [prev] | [next] | [standalone]
| From | Mauro Carvalho Chehab <mchehab@s-opensource.com> |
|---|---|
| Date | 2016-09-22 14:00 +0200 |
| Subject | [PATCH 05/17] README: convert it to ReST markup |
| Message-ID | <skaPw-5PF-53@gated-at.bofh.it> |
| In reply to | #1488805 |
Adjust the readme file for it to use the ReST markup:
- add chapter/section markups;
- use ``foo`` for commands;
- use :: for verbatim and script blocks;
- replace unsupported markup _foo_ by **foo**;
- add cross-references to other ReST files;
- use lower case on the section titles, to match other ReST files.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
README | 105 ++++++++++++++++++++++++++++++++++++-----------------------------
1 file changed, 58 insertions(+), 47 deletions(-)
diff --git a/README b/README
index 09f34f78f2bb..3335b3b2973a 100644
--- a/README
+++ b/README
@@ -1,10 +1,12 @@
- Linux kernel release 4.x <http://kernel.org/>
+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?
+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
@@ -18,7 +20,8 @@ WHAT IS LINUX?
It is distributed under the GNU General Public License - see the
accompanying COPYING file for more details.
-ON WHAT HARDWARE DOES IT RUN?
+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
@@ -34,7 +37,8 @@ ON WHAT HARDWARE DOES IT RUN?
Linux has also been ported to itself. You can now run the kernel as a
userspace application - this is called UserMode Linux (UML).
-DOCUMENTATION:
+Documentation
+-------------
- There is a lot of documentation available both in electronic form on
the Internet and in books, both Linux-specific and pertaining to
@@ -53,14 +57,15 @@ DOCUMENTATION:
- 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.
+ After installation, ``make psdocs``, ``make pdfdocs``, ``make htmldocs``,
+ or ``make mandocs`` will render the documentation in the requested format.
-INSTALLING the kernel source:
+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:
+ unpack it::
xz -cd linux-4.X.tar.xz | tar xvf -
@@ -74,12 +79,12 @@ INSTALLING the kernel source:
- 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:
+ (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
+ 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.
@@ -90,12 +95,12 @@ INSTALLING the kernel source:
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
- Documentation/applying-patches.txt
+ 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.
+ patches found::
linux/scripts/patch-kernel linux
@@ -103,55 +108,58 @@ INSTALLING the kernel source:
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:
+ - 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
+Software requirements
+---------------------
Compiling and running the 4.x kernels requires up-to-date
versions of various software packages. Consult
- Documentation/Changes for the minimum version numbers required
- and how to get updates for these packages. Beware that using
+ :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:
+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
+ Using the option ``make O=output/dir`` allows you to specify an alternate
place for the output files (including .config).
- Example:
+ Example::
kernel source code: /usr/src/linux-4.X
build directory: /home/name/build/kernel
- To configure and build the kernel, use:
+ 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
+ Please note: If the ``O=output/dir`` option is used, then it must be
used for all invocations of make.
-CONFIGURING the kernel:
+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
+ new version with minimal work, use ``make oldconfig``, which will
only ask you for the answers to new questions.
- - Alternative configuration commands are:
+ - Alternative configuration commands are::
"make config" Plain text interface.
@@ -223,7 +231,7 @@ CONFIGURING the kernel:
You can find more information on using the Linux kernel config tools
in Documentation/kbuild/kconfig.txt.
- - NOTES on "make config":
+ - NOTES on ``make config``:
- Having unnecessary drivers will make the kernel bigger, and can
under some circumstances lead to problems: probing for a
@@ -242,22 +250,23 @@ CONFIGURING the kernel:
should probably answer 'n' to the questions for "development",
"experimental", or "debugging" features.
-COMPILING the kernel:
+Compiling the kernel
+--------------------
- Make sure you have at least gcc 3.2 available.
- For more information, refer to Documentation/Changes.
+ 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
+ - 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".
+ - 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:
@@ -265,12 +274,12 @@ COMPILING the kernel:
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.
+ ``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".
+ 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
@@ -278,7 +287,7 @@ COMPILING the kernel:
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".
+ do a ``make modules_install``.
Alternatively, before compiling, use the kernel config option
"LOCALVERSION" to append a unique suffix to the regular kernel version.
@@ -308,13 +317,14 @@ COMPILING the kernel:
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
+ 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 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
@@ -328,7 +338,7 @@ IF SOMETHING GOES WRONG:
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
+ - If the bug results in a message like::
unable to handle kernel paging request at address C0000010
Oops: 0002
@@ -348,7 +358,7 @@ IF SOMETHING GOES WRONG:
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
+ 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/ .
@@ -358,13 +368,13 @@ IF SOMETHING GOES WRONG:
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
+ 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:
+ the EIP from the kernel crash, do::
nm vmlinux | sort | less
@@ -383,18 +393,19 @@ IF SOMETHING GOES WRONG:
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 REPORTING-BUGS document for details.
+ 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").
+ 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".
+ 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
+ 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)
+ gdb'ing a non-running kernel currently fails because ``gdb`` (wrongly)
disregards the starting offset for which the kernel is compiled.
--
2.7.4
[toc] | [prev] | [standalone]
Back to top | Article view | linux.kernel
csiph-web