Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]
Groups > linux.kernel > #1502210 > unrolled thread
| Started by | Mauro Carvalho Chehab <mchehab@s-opensource.com> |
|---|---|
| First post | 2016-10-17 19:00 +0200 |
| Last post | 2016-10-19 17:00 +0200 |
| Articles | 20 on this page of 42 — 5 participants |
Back to article view | Back to linux.kernel
[PATCH 00/32] Create an User's manual and improve development-process book Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-10-17 19:00 +0200
[PATCH 16/32] Documentation/dynamic-debug-howto.txt: convert it to ReST markup Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-10-17 19:00 +0200
[PATCH 19/32] Documentation/magic-number.txt: convert it to ReST markup Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-10-17 19:00 +0200
[PATCH 31/32] Documentation/volatile-considered-harmful.txt: convert to ReST markup Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-10-17 19:00 +0200
[PATCH 25/32] Documentation/parport.txt: convert to ReST markup Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-10-17 19:00 +0200
[PATCH 32/32] Documentation/parport.txt: fix table to show on LaTeX Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-10-17 19:00 +0200
[PATCH 27/32] Documentation/sysfs-rules.txt: convert it to ReST markup Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-10-17 19:00 +0200
[PATCH 21/32] Documentation/module-signing.txt: convert to ReST markup Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-10-17 19:00 +0200
[PATCH 05/32] docs-rst: add documents to development-process Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-10-17 19:00 +0200
[PATCH 17/32] Documentation/initrd.txt: convert to ReST markup Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-10-17 19:00 +0200
[PATCH 13/32] Documentation/BUG-HUNTING: convert to ReST markup Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-10-17 19:10 +0200
[PATCH 04/32] Documentation/kernel-parameters.txt: convert to ReST markup Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-10-17 19:10 +0200
[PATCH 20/32] Documentation/md.txt: Convert to ReST markup Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-10-17 19:10 +0200
[PATCH 14/32] Documentation/CodeOfConflict: add it to the development-process book Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-10-17 19:10 +0200
[PATCH 10/32] Documentation/binfmt_misc.txt: convert it to ReST markup Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-10-17 19:10 +0200
[PATCH 09/32] Documentation/basic_profiling.rst: convert to ReST markup Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-10-17 19:10 +0200
[PATCH 02/32] REPORTING-BUGS: convert to ReST markup Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-10-17 19:10 +0200
[PATCH 06/32] docs-rst: create an user's manual book Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-10-17 19:10 +0200
[PATCH 11/32] Documentation/serial-console.txt: convert it to ReST markup Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-10-17 19:10 +0200
[PATCH 03/32] README: convert it to ReST markup Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-10-17 19:10 +0200
[PATCH 12/32] Documentation/braille-console: convert it to ReST markup Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-10-17 19:10 +0200
[PATCH 22/32] Documentation/mono.txt: convert to ReST markup Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-10-17 19:10 +0200
[PATCH 07/32] Documentation/adding-syscalls.txt: convert it to ReST markup Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-10-17 19:10 +0200
[PATCH 28/32] Documentation/sysrq.txt: convert to ReST markup Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-10-17 19:10 +0200
[PATCH 24/32] Documentation/oops-tracing.txt: convert to ReST markup Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-10-17 19:10 +0200
[PATCH 29/32] Documentation/unicode.txt: convert it to ReST markup Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-10-17 19:10 +0200
[PATCH 30/32] Documentation/VGA-softcursor.txt: convert to ReST markup Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-10-17 19:10 +0200
[PATCH 26/32] Documentation/ramoops.txt: convert it to ReST format Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-10-17 19:10 +0200
[PATCH 23/32] Documentation/java.txt: convert to ReST markup Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-10-17 19:10 +0200
[PATCH 08/32] Documentation/bad_memory.txt: convert it to ReST markup Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-10-17 19:20 +0200
Re: [PATCH 00/32] Create an User's manual and improve development-process book Jonathan Corbet <corbet@lwn.net> - 2016-10-18 00:50 +0200
Re: [PATCH 00/32] Create an User's manual and improve development-process book Markus Heiser <markus.heiser@darmarit.de> - 2016-10-18 06:40 +0200
Renaming Documentation/ [was [PATCH 00/32] Create an User's manual and improve development-process book] Jonathan Corbet <corbet@lwn.net> - 2016-10-18 15:40 +0200
Re: Renaming Documentation/ [was [PATCH 00/32] Create an User's manual and improve development-process book] Theodore Ts'o <tytso@mit.edu> - 2016-10-18 16:20 +0200
Re: [PATCH 00/32] Create an User's manual and improve development-process book Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-10-18 10:40 +0200
Re: [PATCH 00/32] Create an User's manual and improve development-process book Jani Nikula <jani.nikula@linux.intel.com> - 2016-10-18 12:10 +0200
Re: [PATCH 00/32] Create an User's manual and improve development-process book Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-10-18 12:30 +0200
Re: [PATCH 00/32] Create an User's manual and improve development-process book Jani Nikula <jani.nikula@linux.intel.com> - 2016-10-18 12:40 +0200
Re: [PATCH 00/32] Create an User's manual and improve development-process book Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-10-18 12:50 +0200
Re: [PATCH 00/32] Create an User's manual and improve development-process book Jonathan Corbet <corbet@lwn.net> - 2016-10-19 01:30 +0200
Re: [PATCH 00/32] Create an User's manual and improve development-process book Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-10-19 16:20 +0200
Re: [PATCH 00/32] Create an User's manual and improve development-process book Markus Heiser <markus.heiser@darmarit.de> - 2016-10-19 17:00 +0200
Page 2 of 3 — ← Prev page 1 [2] 3 Next page →
| From | Mauro Carvalho Chehab <mchehab@s-opensource.com> |
|---|---|
| Date | 2016-10-17 19:10 +0200 |
| Subject | [PATCH 12/32] Documentation/braille-console: convert it to ReST markup |
| Message-ID | <stjAf-6l5-55@gated-at.bofh.it> |
| In reply to | #1502210 |
- 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-10-17 19:10 +0200 |
| Subject | [PATCH 22/32] Documentation/mono.txt: convert to ReST markup |
| Message-ID | <stjAf-6l5-59@gated-at.bofh.it> |
| In reply to | #1502210 |
- Fix document title;
- use quote blocks where needed;
- use .. note:: for notes;
- use monotonic fonts for config options and file names;
- adjust whitespaces and blank lines;
- add it to the user's book.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
Documentation/mono.txt | 44 +++++++++++++++++++++++---------------------
Documentation/user/index.rst | 1 +
Documentation/user/mono.rst | 1 +
3 files changed, 25 insertions(+), 21 deletions(-)
create mode 120000 Documentation/user/mono.rst
diff --git a/Documentation/mono.txt b/Documentation/mono.txt
index d01ac6052194..9a9744ca0cf3 100644
--- a/Documentation/mono.txt
+++ b/Documentation/mono.txt
@@ -1,5 +1,5 @@
- Mono(tm) Binary Kernel Support for Linux
- -----------------------------------------
+Mono(tm) Binary Kernel Support for Linux
+-----------------------------------------
To configure Linux to automatically execute Mono-based .NET binaries
(in the form of .exe files) without the need to use the mono CLR
@@ -19,22 +19,22 @@ other program after you have done the following:
http://www.go-mono.com/compiling.html
Once the Mono CLR support has been installed, just check that
- /usr/bin/mono (which could be located elsewhere, for example
- /usr/local/bin/mono) is working.
+ ``/usr/bin/mono`` (which could be located elsewhere, for example
+ ``/usr/local/bin/mono``) is working.
2) You have to compile BINFMT_MISC either as a module or into
- the kernel (CONFIG_BINFMT_MISC) and set it up properly.
+ the kernel (``CONFIG_BINFMT_MISC``) and set it up properly.
If you choose to compile it as a module, you will have
to insert it manually with modprobe/insmod, as kmod
- cannot be easily supported with binfmt_misc.
- Read the file 'binfmt_misc.txt' in this directory to know
+ cannot be easily supported with binfmt_misc.
+ Read the file ``binfmt_misc.txt`` in this directory to know
more about the configuration process.
-3) Add the following entries to /etc/rc.local or similar script
- to be run at system startup:
+3) Add the following entries to ``/etc/rc.local`` or similar script
+ to be run at system startup::
-# Insert BINFMT_MISC module into the kernel
-if [ ! -e /proc/sys/fs/binfmt_misc/register ]; then
+ # Insert BINFMT_MISC module into the kernel
+ if [ ! -e /proc/sys/fs/binfmt_misc/register ]; then
/sbin/modprobe binfmt_misc
# Some distributions, like Fedora Core, perform
# the following command automatically when the
@@ -43,24 +43,26 @@ if [ ! -e /proc/sys/fs/binfmt_misc/register ]; then
# Thus, it is possible that the following line
# is not needed at all.
mount -t binfmt_misc none /proc/sys/fs/binfmt_misc
-fi
+ fi
-# Register support for .NET CLR binaries
-if [ -e /proc/sys/fs/binfmt_misc/register ]; then
+ # Register support for .NET CLR binaries
+ if [ -e /proc/sys/fs/binfmt_misc/register ]; then
# Replace /usr/bin/mono with the correct pathname to
# the Mono CLR runtime (usually /usr/local/bin/mono
# when compiling from sources or CVS).
echo ':CLR:M::MZ::/usr/bin/mono:' > /proc/sys/fs/binfmt_misc/register
-else
+ else
echo "No binfmt_misc support"
exit 1
-fi
+ fi
-4) Check that .exe binaries can be ran without the need of a
- wrapper script, simply by launching the .exe file directly
- from a command prompt, for example:
+4) Check that ``.exe`` binaries can be ran without the need of a
+ wrapper script, simply by launching the ``.exe`` file directly
+ from a command prompt, for example::
/usr/bin/xsd.exe
- NOTE: If this fails with a permission denied error, check
- that the .exe file has execute permissions.
+ .. note::
+
+ If this fails with a permission denied error, check
+ that the ``.exe`` file has execute permissions.
diff --git a/Documentation/user/index.rst b/Documentation/user/index.rst
index dee63ce0662a..1858fc94c630 100644
--- a/Documentation/user/index.rst
+++ b/Documentation/user/index.rst
@@ -21,5 +21,6 @@ Contents:
devices
module-signing
binfmt_misc
+ mono
bad_memory
basic_profiling
diff --git a/Documentation/user/mono.rst b/Documentation/user/mono.rst
new file mode 120000
index 000000000000..067f9498c0e3
--- /dev/null
+++ b/Documentation/user/mono.rst
@@ -0,0 +1 @@
+../mono.txt
\ No newline at end of file
--
2.7.4
[toc] | [prev] | [next] | [standalone]
| From | Mauro Carvalho Chehab <mchehab@s-opensource.com> |
|---|---|
| Date | 2016-10-17 19:10 +0200 |
| Subject | [PATCH 07/32] Documentation/adding-syscalls.txt: convert it to ReST markup |
| Message-ID | <stjAf-6l5-57@gated-at.bofh.it> |
| In reply to | #1502210 |
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-10-17 19:10 +0200 |
| Subject | [PATCH 28/32] Documentation/sysrq.txt: convert to ReST markup |
| Message-ID | <stjAf-6l5-69@gated-at.bofh.it> |
| In reply to | #1502210 |
- Fix document title;
- use a table for the valid commands;
- use quote blocks where needed;
- use monotonic fonts for config options and file names;
- adjust whitespaces and blank lines;
- add it to the user's book.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
Documentation/sysrq.txt | 266 ++++++++++++++++++++++++-------------------
Documentation/user/index.rst | 1 +
Documentation/user/sysrq.rst | 1 +
3 files changed, 151 insertions(+), 117 deletions(-)
create mode 120000 Documentation/user/sysrq.rst
diff --git a/Documentation/sysrq.txt b/Documentation/sysrq.txt
index 3a3b30ac2a75..d1712ea2d314 100644
--- a/Documentation/sysrq.txt
+++ b/Documentation/sysrq.txt
@@ -1,23 +1,29 @@
Linux Magic System Request Key Hacks
+====================================
+
Documentation for sysrq.c
-* What is the magic SysRq key?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+What is the magic SysRq key?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
It is a 'magical' key combo you can hit which the kernel will respond to
regardless of whatever else it is doing, unless it is completely locked up.
-* How do I enable the magic SysRq key?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+How do I enable the magic SysRq key?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
You need to say "yes" to 'Magic SysRq key (CONFIG_MAGIC_SYSRQ)' when
configuring the kernel. When running a kernel with SysRq compiled in,
/proc/sys/kernel/sysrq controls the functions allowed to be invoked via
the SysRq key. The default value in this file is set by the
CONFIG_MAGIC_SYSRQ_DEFAULT_ENABLE config symbol, which itself defaults
to 1. Here is the list of possible values in /proc/sys/kernel/sysrq:
- 0 - disable sysrq completely
- 1 - enable all functions of sysrq
- >1 - bitmask of allowed sysrq functions (see below for detailed function
- description):
+
+ - 0 - disable sysrq completely
+ - 1 - enable all functions of sysrq
+ - >1 - bitmask of allowed sysrq functions (see below for detailed function
+ description)::
+
2 = 0x2 - enable control of console logging level
4 = 0x4 - enable control of keyboard (SAK, unraw)
8 = 0x8 - enable debugging dumps of processes etc.
@@ -27,112 +33,126 @@ to 1. Here is the list of possible values in /proc/sys/kernel/sysrq:
128 = 0x80 - allow reboot/poweroff
256 = 0x100 - allow nicing of all RT tasks
-You can set the value in the file by the following command:
+You can set the value in the file by the following command::
+
echo "number" >/proc/sys/kernel/sysrq
The number may be written here either as decimal or as hexadecimal
with the 0x prefix. CONFIG_MAGIC_SYSRQ_DEFAULT_ENABLE must always be
written in hexadecimal.
-Note that the value of /proc/sys/kernel/sysrq influences only the invocation
-via a keyboard. Invocation of any operation via /proc/sysrq-trigger is always
-allowed (by a user with admin privileges).
+Note that the value of ``/proc/sys/kernel/sysrq`` influences only the invocation
+via a keyboard. Invocation of any operation via ``/proc/sysrq-trigger`` is
+always allowed (by a user with admin privileges).
-* How do I use the magic SysRq key?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-On x86 - You press the key combo 'ALT-SysRq-<command key>'. Note - Some
+How do I use the magic SysRq key?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+On x86 - You press the key combo :kbd:`ALT-SysRq-<command key>`.
+
+.. note::
+ Some
keyboards may not have a key labeled 'SysRq'. The 'SysRq' key is
also known as the 'Print Screen' key. Also some keyboards cannot
handle so many keys being pressed at the same time, so you might
- have better luck with "press Alt", "press SysRq", "release SysRq",
- "press <command key>", release everything.
+ have better luck with press :kbd:`Alt`, press :kbd:`SysRq`,
+ release :kbd:`SysRq`, press :kbd:`<command key>`, release everything.
-On SPARC - You press 'ALT-STOP-<command key>', I believe.
+On SPARC - You press :kbd:`ALT-STOP-<command key>`, I believe.
-On the serial console (PC style standard serial ports only) -
- You send a BREAK, then within 5 seconds a command key. Sending
- BREAK twice is interpreted as a normal BREAK.
+On the serial console (PC style standard serial ports only)
+ You send a ``BREAK``, then within 5 seconds a command key. Sending
+ ``BREAK`` twice is interpreted as a normal BREAK.
-On PowerPC - Press 'ALT - Print Screen (or F13) - <command key>,
- Print Screen (or F13) - <command key> may suffice.
+On PowerPC
+ Press :kbd:`ALT - Print Screen` (or :kbd:`F13`) - :kbd:`<command key>`,
+ :kbd:`Print Screen` (or :kbd:`F13`) - :kbd:`<command key>` may suffice.
-On other - If you know of the key combos for other architectures, please
- let me know so I can add them to this section.
+On other
+ If you know of the key combos for other architectures, please
+ let me know so I can add them to this section.
-On all - write a character to /proc/sysrq-trigger. e.g.:
+On all
+ write a character to /proc/sysrq-trigger. e.g.::
echo t > /proc/sysrq-trigger
-* What are the 'command' keys?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-'b' - Will immediately reboot the system without syncing or unmounting
- your disks.
+What are the 'command' keys?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-'c' - Will perform a system crash by a NULL pointer dereference.
- A crashdump will be taken if configured.
+=========== ===================================================================
+Command Function
+=========== ===================================================================
+``b`` Will immediately reboot the system without syncing or unmounting
+ your disks.
-'d' - Shows all locks that are held.
+``c`` Will perform a system crash by a NULL pointer dereference.
+ A crashdump will be taken if configured.
-'e' - Send a SIGTERM to all processes, except for init.
+``d`` Shows all locks that are held.
-'f' - Will call the oom killer to kill a memory hog process, but do not
- panic if nothing can be killed.
+``e`` Send a SIGTERM to all processes, except for init.
-'g' - Used by kgdb (kernel debugger)
+``f`` Will call the oom killer to kill a memory hog process, but do not
+ panic if nothing can be killed.
-'h' - Will display help (actually any other key than those listed
- here will display help. but 'h' is easy to remember :-)
+``g`` Used by kgdb (kernel debugger)
-'i' - Send a SIGKILL to all processes, except for init.
+``h`` Will display help (actually any other key than those listed
+ here will display help. but ``h`` is easy to remember :-)
-'j' - Forcibly "Just thaw it" - filesystems frozen by the FIFREEZE ioctl.
+``i`` Send a SIGKILL to all processes, except for init.
-'k' - Secure Access Key (SAK) Kills all programs on the current virtual
- console. NOTE: See important comments below in SAK section.
+``j`` Forcibly "Just thaw it" - filesystems frozen by the FIFREEZE ioctl.
-'l' - Shows a stack backtrace for all active CPUs.
+``k`` Secure Access Key (SAK) Kills all programs on the current virtual
+ console. NOTE: See important comments below in SAK section.
-'m' - Will dump current memory info to your console.
+``l`` Shows a stack backtrace for all active CPUs.
-'n' - Used to make RT tasks nice-able
+``m`` Will dump current memory info to your console.
-'o' - Will shut your system off (if configured and supported).
+``n`` Used to make RT tasks nice-able
-'p' - Will dump the current registers and flags to your console.
+``o`` Will shut your system off (if configured and supported).
-'q' - Will dump per CPU lists of all armed hrtimers (but NOT regular
- timer_list timers) and detailed information about all
- clockevent devices.
+``p`` Will dump the current registers and flags to your console.
-'r' - Turns off keyboard raw mode and sets it to XLATE.
+``q`` Will dump per CPU lists of all armed hrtimers (but NOT regular
+ timer_list timers) and detailed information about all
+ clockevent devices.
-'s' - Will attempt to sync all mounted filesystems.
+``r`` Turns off keyboard raw mode and sets it to XLATE.
-'t' - Will dump a list of current tasks and their information to your
- console.
+``s`` Will attempt to sync all mounted filesystems.
-'u' - Will attempt to remount all mounted filesystems read-only.
+``t`` Will dump a list of current tasks and their information to your
+ console.
-'v' - Forcefully restores framebuffer console
-'v' - Causes ETM buffer dump [ARM-specific]
+``u`` Will attempt to remount all mounted filesystems read-only.
-'w' - Dumps tasks that are in uninterruptable (blocked) state.
+``v`` Forcefully restores framebuffer console
+``v`` Causes ETM buffer dump [ARM-specific]
-'x' - Used by xmon interface on ppc/powerpc platforms.
- Show global PMU Registers on sparc64.
- Dump all TLB entries on MIPS.
+``w`` Dumps tasks that are in uninterruptable (blocked) state.
-'y' - Show global CPU Registers [SPARC-64 specific]
+``x`` Used by xmon interface on ppc/powerpc platforms.
+ Show global PMU Registers on sparc64.
+ Dump all TLB entries on MIPS.
-'z' - Dump the ftrace buffer
+``y`` Show global CPU Registers [SPARC-64 specific]
-'0'-'9' - Sets the console log level, controlling which kernel messages
- will be printed to your console. ('0', for example would make
- it so that only emergency messages like PANICs or OOPSes would
- make it to your console.)
+``z`` Dump the ftrace buffer
+
+``0``-``9`` Sets the console log level, controlling which kernel messages
+ will be printed to your console. (``0``, for example would make
+ it so that only emergency messages like PANICs or OOPSes would
+ make it to your console.)
+=========== ===================================================================
+
+Okay, so what can I use them for?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-* Okay, so what can I use them for?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Well, unraw(r) is very handy when your X server or a svgalib program crashes.
sak(k) (Secure Access Key) is useful when you want to be sure there is no
@@ -140,73 +160,80 @@ trojan program running at console which could grab your password
when you would try to login. It will kill all programs on given console,
thus letting you make sure that the login prompt you see is actually
the one from init, not some trojan program.
-IMPORTANT: In its true form it is not a true SAK like the one in a :IMPORTANT
-IMPORTANT: c2 compliant system, and it should not be mistaken as :IMPORTANT
-IMPORTANT: such. :IMPORTANT
- It seems others find it useful as (System Attention Key) which is
+
+.. important::
+
+ In its true form it is not a true SAK like the one in a
+ c2 compliant system, and it should not be mistaken as
+ such.
+
+It seems others find it useful as (System Attention Key) which is
useful when you want to exit a program that will not let you switch consoles.
(For example, X or a svgalib program.)
-reboot(b) is good when you're unable to shut down. But you should also
-sync(s) and umount(u) first.
+``reboot(b)`` is good when you're unable to shut down. But you should also
+``sync(s)`` and ``umount(u)`` first.
-crash(c) can be used to manually trigger a crashdump when the system is hung.
+``crash(c)`` can be used to manually trigger a crashdump when the system is hung.
Note that this just triggers a crash if there is no dump mechanism available.
-sync(s) is great when your system is locked up, it allows you to sync your
+``sync(s)`` is great when your system is locked up, it allows you to sync your
disks and will certainly lessen the chance of data loss and fscking. Note
that the sync hasn't taken place until you see the "OK" and "Done" appear
on the screen. (If the kernel is really in strife, you may not ever get the
OK or Done message...)
-umount(u) is basically useful in the same ways as sync(s). I generally sync(s),
-umount(u), then reboot(b) when my system locks. It's saved me many a fsck.
-Again, the unmount (remount read-only) hasn't taken place until you see the
-"OK" and "Done" message appear on the screen.
+``umount(u)`` is basically useful in the same ways as ``sync(s)``. I generally
+``sync(s)``, ``umount(u)``, then ``reboot(b)`` when my system locks. It's saved
+me many a fsck. Again, the unmount (remount read-only) hasn't taken place until
+you see the "OK" and "Done" message appear on the screen.
-The loglevels '0'-'9' are useful when your console is being flooded with
-kernel messages you do not want to see. Selecting '0' will prevent all but
+The loglevels ``0``-``9`` are useful when your console is being flooded with
+kernel messages you do not want to see. Selecting ``0`` will prevent all but
the most urgent kernel messages from reaching your console. (They will
still be logged if syslogd/klogd are alive, though.)
-term(e) and kill(i) are useful if you have some sort of runaway process you
-are unable to kill any other way, especially if it's spawning other
+``term(e)`` and ``kill(i)`` are useful if you have some sort of runaway process
+you are unable to kill any other way, especially if it's spawning other
processes.
-"just thaw it(j)" is useful if your system becomes unresponsive due to a frozen
-(probably root) filesystem via the FIFREEZE ioctl.
+"just thaw ``it(j)``" is useful if your system becomes unresponsive due to a
+frozen (probably root) filesystem via the FIFREEZE ioctl.
+
+Sometimes SysRq seems to get 'stuck' after using it, what can I do?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-* Sometimes SysRq seems to get 'stuck' after using it, what can I do?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
That happens to me, also. I've found that tapping shift, alt, and control
on both sides of the keyboard, and hitting an invalid sysrq sequence again
-will fix the problem. (i.e., something like alt-sysrq-z). Switching to another
-virtual console (ALT+Fn) and then back again should also help.
+will fix the problem. (i.e., something like :kbd:`alt-sysrq-z`). Switching to
+another virtual console (:kbd:`ALT+Fn`) and then back again should also help.
+
+I hit SysRq, but nothing seems to happen, what's wrong?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-* I hit SysRq, but nothing seems to happen, what's wrong?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
There are some keyboards that produce a different keycode for SysRq than the
-pre-defined value of 99 (see KEY_SYSRQ in include/linux/input.h), or which
-don't have a SysRq key at all. In these cases, run 'showkey -s' to find an
-appropriate scancode sequence, and use 'setkeycodes <sequence> 99' to map
-this sequence to the usual SysRq code (e.g., 'setkeycodes e05b 99'). It's
+pre-defined value of 99 (see ``KEY_SYSRQ`` in ``include/linux/input.h``), or
+which don't have a SysRq key at all. In these cases, run ``showkey -s`` to find
+an appropriate scancode sequence, and use ``setkeycodes <sequence> 99`` to map
+this sequence to the usual SysRq code (e.g., ``setkeycodes e05b 99``). It's
probably best to put this command in a boot script. Oh, and by the way, you
-exit 'showkey' by not typing anything for ten seconds.
+exit ``showkey`` by not typing anything for ten seconds.
+
+I want to add SysRQ key events to a module, how does it work?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-* I want to add SysRQ key events to a module, how does it work?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
In order to register a basic function with the table, you must first include
-the header 'include/linux/sysrq.h', this will define everything else you need.
-Next, you must create a sysrq_key_op struct, and populate it with A) the key
+the header ``include/linux/sysrq.h``, this will define everything else you need.
+Next, you must create a ``sysrq_key_op`` struct, and populate it with A) the key
handler function you will use, B) a help_msg string, that will print when SysRQ
prints help, and C) an action_msg string, that will print right before your
handler is called. Your handler must conform to the prototype in 'sysrq.h'.
-After the sysrq_key_op is created, you can call the kernel function
-register_sysrq_key(int key, struct sysrq_key_op *op_p); this will
-register the operation pointed to by 'op_p' at table key 'key',
+After the ``sysrq_key_op`` is created, you can call the kernel function
+``register_sysrq_key(int key, struct sysrq_key_op *op_p);`` this will
+register the operation pointed to by ``op_p`` at table key 'key',
if that slot in the table is blank. At module unload time, you must call
-the function unregister_sysrq_key(int key, struct sysrq_key_op *op_p), which
+the function ``unregister_sysrq_key(int key, struct sysrq_key_op *op_p)``, which
will remove the key op pointed to by 'op_p' from the key 'key', if and only if
it is currently registered in that slot. This is in case the slot has been
overwritten since you registered it.
@@ -214,8 +241,10 @@ overwritten since you registered it.
The Magic SysRQ system works by registering key operations against a key op
lookup table, which is defined in 'drivers/tty/sysrq.c'. This key table has
a number of operations registered into it at compile time, but is mutable,
-and 2 functions are exported for interface to it:
+and 2 functions are exported for interface to it::
+
register_sysrq_key and unregister_sysrq_key.
+
Of course, never ever leave an invalid pointer in the table. I.e., when
your module that called register_sysrq_key() exits, it must call
unregister_sysrq_key() to clean up the sysrq key table entry that it used.
@@ -224,33 +253,36 @@ Null pointers in the table are always safe. :)
If for some reason you feel the need to call the handle_sysrq function from
within a function called by handle_sysrq, you must be aware that you are in
a lock (you are also in an interrupt handler, which means don't sleep!), so
-you must call __handle_sysrq_nolock instead.
+you must call ``__handle_sysrq_nolock`` instead.
+
+When I hit a SysRq key combination only the header appears on the console?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-* When I hit a SysRq key combination only the header appears on the console?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Sysrq output is subject to the same console loglevel control as all
other console output. This means that if the kernel was booted 'quiet'
as is common on distro kernels the output may not appear on the actual
console, even though it will appear in the dmesg buffer, and be accessible
-via the dmesg command and to the consumers of /proc/kmsg. As a specific
+via the dmesg command and to the consumers of ``/proc/kmsg``. As a specific
exception the header line from the sysrq command is passed to all console
consumers as if the current loglevel was maximum. If only the header
is emitted it is almost certain that the kernel loglevel is too low.
Should you require the output on the console channel then you will need
-to temporarily up the console loglevel using alt-sysrq-8 or:
+to temporarily up the console loglevel using :kbd:`alt-sysrq-8` or::
echo 8 > /proc/sysrq-trigger
Remember to return the loglevel to normal after triggering the sysrq
command you are interested in.
-* I have more questions, who can I ask?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+I have more questions, who can I ask?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
Just ask them on the linux-kernel mailing list:
linux-kernel@vger.kernel.org
-* Credits
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Credits
+~~~~~~~
+
Written by Mydraal <vulpyne@vulpyne.net>
Updated by Adam Sulmicki <adam@cfar.umd.edu>
Updated by Jeremy M. Dolan <jmd@turbogeek.org> 2001/01/28 10:15:59
diff --git a/Documentation/user/index.rst b/Documentation/user/index.rst
index d59a6d0b581f..16c73d947744 100644
--- a/Documentation/user/index.rst
+++ b/Documentation/user/index.rst
@@ -21,6 +21,7 @@ Contents:
braile-console
parport
md
+ sysrq
sysfs-rules
devices
module-signing
diff --git a/Documentation/user/sysrq.rst b/Documentation/user/sysrq.rst
new file mode 120000
index 000000000000..532d4e8806b0
--- /dev/null
+++ b/Documentation/user/sysrq.rst
@@ -0,0 +1 @@
+../sysrq.txt
\ No newline at end of file
--
2.7.4
[toc] | [prev] | [next] | [standalone]
| From | Mauro Carvalho Chehab <mchehab@s-opensource.com> |
|---|---|
| Date | 2016-10-17 19:10 +0200 |
| Subject | [PATCH 24/32] Documentation/oops-tracing.txt: convert to ReST markup |
| Message-ID | <stjAf-6l5-65@gated-at.bofh.it> |
| In reply to | #1502210 |
- Add a document title;
- use .. note:: markup;
- use quote blocks where needed;
- use monotonic fonts for config options and file names;
- adjust whitespaces and blank lines;
- replace _foo_ by **foo**;
- while here, remove whitespaces at the end of paragraph;
- add it to the user's book.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
Documentation/oops-tracing.txt | 255 +++++++++++++++++++-----------------
Documentation/user/index.rst | 1 +
Documentation/user/oops-tracing.rst | 1 +
3 files changed, 140 insertions(+), 117 deletions(-)
create mode 120000 Documentation/user/oops-tracing.rst
diff --git a/Documentation/oops-tracing.txt b/Documentation/oops-tracing.txt
index f3ac05cc23e4..3e25ea7349ee 100644
--- a/Documentation/oops-tracing.txt
+++ b/Documentation/oops-tracing.txt
@@ -1,7 +1,13 @@
-NOTE: ksymoops is useless on 2.6. Please use the Oops in its original format
-(from dmesg, etc). Ignore any references in this or other docs to "decoding
-the Oops" or "running it through ksymoops". If you post an Oops from 2.6 that
-has been run through ksymoops, people will just tell you to repost it.
+OOPS tracing
+============
+
+.. note::
+
+ ``ksymoops`` is useless on 2.6 or upper. Please use the Oops in its original
+ format (from ``dmesg``, etc). Ignore any references in this or other docs to
+ "decoding the Oops" or "running it through ksymoops".
+ If you post an Oops from 2.6+ that has been run through ``ksymoops``,
+ people will just tell you to repost it.
Quick Summary
-------------
@@ -12,7 +18,7 @@ If you are unsure send it to the person responsible for the code relevant to
what you were doing. If it occurs repeatably try and describe how to recreate
it. That's worth even more than the oops.
-If you are totally stumped as to whom to send the report, send it to
+If you are totally stumped as to whom to send the report, send it to
linux-kernel@vger.kernel.org. Thanks for your help in making Linux as
stable as humanly possible.
@@ -20,24 +26,25 @@ Where is the Oops?
----------------------
Normally the Oops text is read from the kernel buffers by klogd and
-handed to syslogd which writes it to a syslog file, typically
-/var/log/messages (depends on /etc/syslog.conf). Sometimes klogd dies,
-in which case you can run dmesg > file to read the data from the kernel
-buffers and save it. Or you can cat /proc/kmsg > file, however you
-have to break in to stop the transfer, kmsg is a "never ending file".
+handed to ``syslogd`` which writes it to a syslog file, typically
+``/var/log/messages`` (depends on ``/etc/syslog.conf``). Sometimes ``klogd``
+dies, in which case you can run ``dmesg > file`` to read the data from the
+kernel buffers and save it. Or you can ``cat /proc/kmsg > file``, however you
+have to break in to stop the transfer, ``kmsg`` is a "never ending file".
If the machine has crashed so badly that you cannot enter commands or
-the disk is not available then you have three options :-
+the disk is not available then you have three options :
(1) Hand copy the text from the screen and type it in after the machine
has restarted. Messy but it is the only option if you have not
planned for a crash. Alternatively, you can take a picture of
the screen with a digital camera - not nice, but better than
nothing. If the messages scroll off the top of the console, you
- may find that booting with a higher resolution (eg, vga=791)
- will allow you to read more of the text. (Caveat: This needs vesafb,
+ may find that booting with a higher resolution (eg, ``vga=791``)
+ will allow you to read more of the text. (Caveat: This needs ``vesafb``,
so won't help for 'early' oopses)
-(2) Boot with a serial console (see Documentation/serial-console.txt),
+(2) Boot with a serial console (see
+ :ref:`Documentation/serial-console.txt <serial_console>`),
run a null modem to a second machine and capture the output there
using your favourite communication program. Minicom works well.
@@ -49,117 +56,126 @@ the disk is not available then you have three options :-
Full Information
----------------
-NOTE: the message from Linus below applies to 2.4 kernel. I have preserved it
-for historical reasons, and because some of the information in it still
-applies. Especially, please ignore any references to ksymoops.
+.. note::
-From: Linus Torvalds <torvalds@osdl.org>
+ the message from Linus below applies to 2.4 kernel. I have preserved it
+ for historical reasons, and because some of the information in it still
+ applies. Especially, please ignore any references to ksymoops.
-How to track down an Oops.. [originally a mail to linux-kernel]
+ ::
-The main trick is having 5 years of experience with those pesky oops
-messages ;-)
+ From: Linus Torvalds <torvalds@osdl.org>
-Actually, there are things you can do that make this easier. I have two
-separate approaches:
+ How to track down an Oops.. [originally a mail to linux-kernel]
+
+ The main trick is having 5 years of experience with those pesky oops
+ messages ;-)
+
+Actually, there are things you can do that make this easier. I have two
+separate approaches::
gdb /usr/src/linux/vmlinux
gdb> disassemble <offending_function>
-That's the easy way to find the problem, at least if the bug-report is
-well made (like this one was - run through ksymoops to get the
-information of which function and the offset in the function that it
+That's the easy way to find the problem, at least if the bug-report is
+well made (like this one was - run through ``ksymoops`` to get the
+information of which function and the offset in the function that it
happened in).
-Oh, it helps if the report happens on a kernel that is compiled with the
+Oh, it helps if the report happens on a kernel that is compiled with the
same compiler and similar setups.
-The other thing to do is disassemble the "Code:" part of the bug report:
+The other thing to do is disassemble the "Code:" part of the bug report:
ksymoops will do this too with the correct tools, but if you don't have
-the tools you can just do a silly program:
+the tools you can just do a silly program::
char str[] = "\xXX\xXX\xXX...";
main(){}
-and compile it with gcc -g and then do "disassemble str" (where the "XX"
-stuff are the values reported by the Oops - you can just cut-and-paste
-and do a replace of spaces to "\x" - that's what I do, as I'm too lazy
+and compile it with ``gcc -g`` and then do ``disassemble str`` (where the ``XX``
+stuff are the values reported by the Oops - you can just cut-and-paste
+and do a replace of spaces to ``\x`` - that's what I do, as I'm too lazy
to write a program to automate this all).
-Alternatively, you can use the shell script in scripts/decodecode.
-Its usage is: decodecode < oops.txt
+Alternatively, you can use the shell script in ``scripts/decodecode``.
+Its usage is::
+
+ decodecode < oops.txt
The hex bytes that follow "Code:" may (in some architectures) have a series
of bytes that precede the current instruction pointer as well as bytes at and
following the current instruction pointer. In some cases, one instruction
-byte or word is surrounded by <> or (), as in "<86>" or "(f00d)". These
-<> or () markings indicate the current instruction pointer. Example from
-i386, split into multiple lines for readability:
+byte or word is surrounded by ``<>`` or ``()``, as in ``<86>`` or ``(f00d)``.
+These ``<>`` or ``()`` markings indicate the current instruction pointer.
-Code: f9 0f 8d f9 00 00 00 8d 42 0c e8 dd 26 11 c7 a1 60 ea 2b f9 8b 50 08 a1
-64 ea 2b f9 8d 34 82 8b 1e 85 db 74 6d 8b 15 60 ea 2b f9 <8b> 43 04 39 42 54
-7e 04 40 89 42 54 8b 43 04 3b 05 00 f6 52 c0
+Example from i386, split into multiple lines for readability::
-Finally, if you want to see where the code comes from, you can do
+ Code: f9 0f 8d f9 00 00 00 8d 42 0c e8 dd 26 11 c7 a1 60 ea 2b f9 8b 50 08 a1
+ 64 ea 2b f9 8d 34 82 8b 1e 85 db 74 6d 8b 15 60 ea 2b f9 <8b> 43 04 39 42 54
+ 7e 04 40 89 42 54 8b 43 04 3b 05 00 f6 52 c0
+
+Finally, if you want to see where the code comes from, you can do::
cd /usr/src/linux
make fs/buffer.s # or whatever file the bug happened in
-and then you get a better idea of what happens than with the gdb
+and then you get a better idea of what happens than with the gdb
disassembly.
-Now, the trick is just then to combine all the data you have: the C
-sources (and general knowledge of what it _should_ do), the assembly
-listing and the code disassembly (and additionally the register dump you
-also get from the "oops" message - that can be useful to see _what_ the
-corrupted pointers were, and when you have the assembler listing you can
-also match the other registers to whatever C expressions they were used
+Now, the trick is just then to combine all the data you have: the C
+sources (and general knowledge of what it **should** do), the assembly
+listing and the code disassembly (and additionally the register dump you
+also get from the "oops" message - that can be useful to see **what** the
+corrupted pointers were, and when you have the assembler listing you can
+also match the other registers to whatever C expressions they were used
for).
-Essentially, you just look at what doesn't match (in this case it was the
-"Code" disassembly that didn't match with what the compiler generated).
-Then you need to find out _why_ they don't match. Often it's simple - you
-see that the code uses a NULL pointer and then you look at the code and
-wonder how the NULL pointer got there, and if it's a valid thing to do
+Essentially, you just look at what doesn't match (in this case it was the
+"Code" disassembly that didn't match with what the compiler generated).
+Then you need to find out **why** they don't match. Often it's simple - you
+see that the code uses a NULL pointer and then you look at the code and
+wonder how the NULL pointer got there, and if it's a valid thing to do
you just check against it..
-Now, if somebody gets the idea that this is time-consuming and requires
-some small amount of concentration, you're right. Which is why I will
-mostly just ignore any panic reports that don't have the symbol table
-info etc looked up: it simply gets too hard to look it up (I have some
-programs to search for specific patterns in the kernel code segment, and
-sometimes I have been able to look up those kinds of panics too, but
-that really requires pretty good knowledge of the kernel just to be able
+Now, if somebody gets the idea that this is time-consuming and requires
+some small amount of concentration, you're right. Which is why I will
+mostly just ignore any panic reports that don't have the symbol table
+info etc looked up: it simply gets too hard to look it up (I have some
+programs to search for specific patterns in the kernel code segment, and
+sometimes I have been able to look up those kinds of panics too, but
+that really requires pretty good knowledge of the kernel just to be able
to pick out the right sequences etc..)
-_Sometimes_ it happens that I just see the disassembled code sequence
-from the panic, and I know immediately where it's coming from. That's when
+**Sometimes** it happens that I just see the disassembled code sequence
+from the panic, and I know immediately where it's coming from. That's when
I get worried that I've been doing this for too long ;-)
Linus
---------------------------------------------------------------------------
-Notes on Oops tracing with klogd:
+
+Notes on Oops tracing with ``klogd``
+------------------------------------
In order to help Linus and the other kernel developers there has been
-substantial support incorporated into klogd for processing protection
+substantial support incorporated into ``klogd`` for processing protection
faults. In order to have full support for address resolution at least
-version 1.3-pl3 of the sysklogd package should be used.
+version 1.3-pl3 of the ``sysklogd`` package should be used.
-When a protection fault occurs the klogd daemon automatically
+When a protection fault occurs the ``klogd`` daemon automatically
translates important addresses in the kernel log messages to their
symbolic equivalents. This translated kernel message is then
-forwarded through whatever reporting mechanism klogd is using. The
+forwarded through whatever reporting mechanism ``klogd`` is using. The
protection fault message can be simply cut out of the message files
and forwarded to the kernel developers.
-Two types of address resolution are performed by klogd. The first is
+Two types of address resolution are performed by ``klogd``. The first is
static translation and the second is dynamic translation. Static
translation uses the System.map file in much the same manner that
-ksymoops does. In order to do static translation the klogd daemon
+ksymoops does. In order to do static translation the ``klogd`` daemon
must be able to find a system map file at daemon initialization time.
-See the klogd man page for information on how klogd searches for map
+See the klogd man page for information on how ``klogd`` searches for map
files.
Dynamic address translation is important when kernel loadable modules
@@ -178,101 +194,106 @@ information available if the developer of the loadable module chose to
export symbol information from the module.
Since the kernel module environment can be dynamic there must be a
-mechanism for notifying the klogd daemon when a change in module
+mechanism for notifying the ``klogd`` daemon when a change in module
environment occurs. There are command line options available which
allow klogd to signal the currently executing daemon that symbol
-information should be refreshed. See the klogd manual page for more
+information should be refreshed. See the ``klogd`` manual page for more
information.
A patch is included with the sysklogd distribution which modifies the
-modules-2.0.0 package to automatically signal klogd whenever a module
+``modules-2.0.0`` package to automatically signal klogd whenever a module
is loaded or unloaded. Applying this patch provides essentially
seamless support for debugging protection faults which occur with
kernel loadable modules.
The following is an example of a protection fault in a loadable module
-processed by klogd:
----------------------------------------------------------------------------
-Aug 29 09:51:01 blizard kernel: Unable to handle kernel paging request at virtual address f15e97cc
-Aug 29 09:51:01 blizard kernel: current->tss.cr3 = 0062d000, %cr3 = 0062d000
-Aug 29 09:51:01 blizard kernel: *pde = 00000000
-Aug 29 09:51:01 blizard kernel: Oops: 0002
-Aug 29 09:51:01 blizard kernel: CPU: 0
-Aug 29 09:51:01 blizard kernel: EIP: 0010:[oops:_oops+16/3868]
-Aug 29 09:51:01 blizard kernel: EFLAGS: 00010212
-Aug 29 09:51:01 blizard kernel: eax: 315e97cc ebx: 003a6f80 ecx: 001be77b edx: 00237c0c
-Aug 29 09:51:01 blizard kernel: esi: 00000000 edi: bffffdb3 ebp: 00589f90 esp: 00589f8c
-Aug 29 09:51:01 blizard kernel: ds: 0018 es: 0018 fs: 002b gs: 002b ss: 0018
-Aug 29 09:51:01 blizard kernel: Process oops_test (pid: 3374, process nr: 21, stackpage=00589000)
-Aug 29 09:51:01 blizard kernel: Stack: 315e97cc 00589f98 0100b0b4 bffffed4 0012e38e 00240c64 003a6f80 00000001
-Aug 29 09:51:01 blizard kernel: 00000000 00237810 bfffff00 0010a7fa 00000003 00000001 00000000 bfffff00
-Aug 29 09:51:01 blizard kernel: bffffdb3 bffffed4 ffffffda 0000002b 0007002b 0000002b 0000002b 00000036
-Aug 29 09:51:01 blizard kernel: Call Trace: [oops:_oops_ioctl+48/80] [_sys_ioctl+254/272] [_system_call+82/128]
-Aug 29 09:51:01 blizard kernel: Code: c7 00 05 00 00 00 eb 08 90 90 90 90 90 90 90 90 89 ec 5d c3
+processed by ``klogd``::
+
+ Aug 29 09:51:01 blizard kernel: Unable to handle kernel paging request at virtual address f15e97cc
+ Aug 29 09:51:01 blizard kernel: current->tss.cr3 = 0062d000, %cr3 = 0062d000
+ Aug 29 09:51:01 blizard kernel: *pde = 00000000
+ Aug 29 09:51:01 blizard kernel: Oops: 0002
+ Aug 29 09:51:01 blizard kernel: CPU: 0
+ Aug 29 09:51:01 blizard kernel: EIP: 0010:[oops:_oops+16/3868]
+ Aug 29 09:51:01 blizard kernel: EFLAGS: 00010212
+ Aug 29 09:51:01 blizard kernel: eax: 315e97cc ebx: 003a6f80 ecx: 001be77b edx: 00237c0c
+ Aug 29 09:51:01 blizard kernel: esi: 00000000 edi: bffffdb3 ebp: 00589f90 esp: 00589f8c
+ Aug 29 09:51:01 blizard kernel: ds: 0018 es: 0018 fs: 002b gs: 002b ss: 0018
+ Aug 29 09:51:01 blizard kernel: Process oops_test (pid: 3374, process nr: 21, stackpage=00589000)
+ Aug 29 09:51:01 blizard kernel: Stack: 315e97cc 00589f98 0100b0b4 bffffed4 0012e38e 00240c64 003a6f80 00000001
+ Aug 29 09:51:01 blizard kernel: 00000000 00237810 bfffff00 0010a7fa 00000003 00000001 00000000 bfffff00
+ Aug 29 09:51:01 blizard kernel: bffffdb3 bffffed4 ffffffda 0000002b 0007002b 0000002b 0000002b 00000036
+ Aug 29 09:51:01 blizard kernel: Call Trace: [oops:_oops_ioctl+48/80] [_sys_ioctl+254/272] [_system_call+82/128]
+ Aug 29 09:51:01 blizard kernel: Code: c7 00 05 00 00 00 eb 08 90 90 90 90 90 90 90 90 89 ec 5d c3
+
---------------------------------------------------------------------------
-Dr. G.W. Wettstein Oncology Research Div. Computing Facility
-Roger Maris Cancer Center INTERNET: greg@wind.rmcc.com
-820 4th St. N.
-Fargo, ND 58122
-Phone: 701-234-7556
+::
+
+ Dr. G.W. Wettstein Oncology Research Div. Computing Facility
+ Roger Maris Cancer Center INTERNET: greg@wind.rmcc.com
+ 820 4th St. N.
+ Fargo, ND 58122
+ Phone: 701-234-7556
---------------------------------------------------------------------------
-Tainted kernels:
-Some oops reports contain the string 'Tainted: ' after the program
+Tainted kernels
+---------------
+
+Some oops reports contain the string **'Tainted: '** after the program
counter. This indicates that the kernel has been tainted by some
mechanism. The string is followed by a series of position-sensitive
characters, each representing a particular tainted value.
- 1: 'G' if all modules loaded have a GPL or compatible license, 'P' if
+ 1) 'G' if all modules loaded have a GPL or compatible license, 'P' if
any proprietary module has been loaded. Modules without a
MODULE_LICENSE or with a MODULE_LICENSE that is not recognised by
insmod as GPL compatible are assumed to be proprietary.
- 2: 'F' if any module was force loaded by "insmod -f", ' ' if all
+ 2) ``F`` if any module was force loaded by ``insmod -f``, ``' '`` if all
modules were loaded normally.
- 3: 'S' if the oops occurred on an SMP kernel running on hardware that
+ 3) ``S`` if the oops occurred on an SMP kernel running on hardware that
hasn't been certified as safe to run multiprocessor.
Currently this occurs only on various Athlons that are not
SMP capable.
- 4: 'R' if a module was force unloaded by "rmmod -f", ' ' if all
+ 4) ``R`` if a module was force unloaded by ``rmmod -f``, ``' '`` if all
modules were unloaded normally.
- 5: 'M' if any processor has reported a Machine Check Exception,
- ' ' if no Machine Check Exceptions have occurred.
+ 5) ``M`` if any processor has reported a Machine Check Exception,
+ ``' '`` if no Machine Check Exceptions have occurred.
- 6: 'B' if a page-release function has found a bad page reference or
+ 6) ``B`` if a page-release function has found a bad page reference or
some unexpected page flags.
- 7: 'U' if a user or user application specifically requested that the
- Tainted flag be set, ' ' otherwise.
+ 7) ``U`` if a user or user application specifically requested that the
+ Tainted flag be set, ``' '`` otherwise.
- 8: 'D' if the kernel has died recently, i.e. there was an OOPS or BUG.
+ 8) ``D`` if the kernel has died recently, i.e. there was an OOPS or BUG.
- 9: 'A' if the ACPI table has been overridden.
+ 9) ``A`` if the ACPI table has been overridden.
- 10: 'W' if a warning has previously been issued by the kernel.
+ 10) ``W`` if a warning has previously been issued by the kernel.
(Though some warnings may set more specific taint flags.)
- 11: 'C' if a staging driver has been loaded.
+ 11) ``C`` if a staging driver has been loaded.
- 12: 'I' if the kernel is working around a severe bug in the platform
+ 12) ``I`` if the kernel is working around a severe bug in the platform
firmware (BIOS or similar).
- 13: 'O' if an externally-built ("out-of-tree") module has been loaded.
+ 13) ``O`` if an externally-built ("out-of-tree") module has been loaded.
- 14: 'E' if an unsigned module has been loaded in a kernel supporting
+ 14) ``E`` if an unsigned module has been loaded in a kernel supporting
module signature.
- 15: 'L' if a soft lockup has previously occurred on the system.
+ 15) ``L`` if a soft lockup has previously occurred on the system.
- 16: 'K' if the kernel has been live patched.
+ 16) ``K`` if the kernel has been live patched.
-The primary reason for the 'Tainted: ' string is to tell kernel
+The primary reason for the **'Tainted: '** string is to tell kernel
debuggers if this is a clean kernel or if anything unusual has
occurred. Tainting is permanent: even if an offending module is
unloaded, the tainted value remains to indicate that the kernel is not
diff --git a/Documentation/user/index.rst b/Documentation/user/index.rst
index 654b17c72818..28b32633d3e2 100644
--- a/Documentation/user/index.rst
+++ b/Documentation/user/index.rst
@@ -10,6 +10,7 @@ Contents:
README
REPORTING-BUGS
BUG-HUNTING
+ oops-tracing
initrd
init
dynamic-debug-howto
diff --git a/Documentation/user/oops-tracing.rst b/Documentation/user/oops-tracing.rst
new file mode 120000
index 000000000000..0f44d382d248
--- /dev/null
+++ b/Documentation/user/oops-tracing.rst
@@ -0,0 +1 @@
+../oops-tracing.txt
\ No newline at end of file
--
2.7.4
[toc] | [prev] | [next] | [standalone]
| From | Mauro Carvalho Chehab <mchehab@s-opensource.com> |
|---|---|
| Date | 2016-10-17 19:10 +0200 |
| Subject | [PATCH 29/32] Documentation/unicode.txt: convert it to ReST markup |
| Message-ID | <stjAf-6l5-81@gated-at.bofh.it> |
| In reply to | #1502210 |
Probably, unicode is something that we might remove from the
docs, as all modern systems support it. Yet, this chapter
is fun, as it mentions support for the Klington fictional
charset ;)
On the other hand, I bet all other OS user manuals
explicit mention unicode support.
So, convert it to ReST and include it at the user's book.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
Documentation/unicode.txt | 22 ++++++++++++++++++----
Documentation/user/index.rst | 1 +
Documentation/user/unicode.rst | 1 +
3 files changed, 20 insertions(+), 4 deletions(-)
create mode 120000 Documentation/user/unicode.rst
diff --git a/Documentation/unicode.txt b/Documentation/unicode.txt
index 4a33f81cadb1..012e8e895842 100644
--- a/Documentation/unicode.txt
+++ b/Documentation/unicode.txt
@@ -1,3 +1,6 @@
+Unicode support
+===============
+
Last update: 2005-01-17, version 1.4
This file is maintained by H. Peter Anvin <unicode@lanana.org> as part
@@ -6,7 +9,8 @@ The current version can be found at:
http://www.lanana.org/docs/unicode/unicode.txt
- ------------------------
+Introdution
+-----------
The Linux kernel code has been rewritten to use Unicode to map
characters to fonts. By downloading a single Unicode-to-font table,
@@ -16,12 +20,14 @@ the font as indicated.
This changes the semantics of the eight-bit character tables subtly.
The four character tables are now:
+=============== =============================== ================
Map symbol Map name Escape code (G0)
-
+=============== =============================== ================
LAT1_MAP Latin-1 (ISO 8859-1) ESC ( B
GRAF_MAP DEC VT100 pseudographics ESC ( 0
IBMPC_MAP IBM code page 437 ESC ( U
USER_MAP User defined ESC ( K
+=============== =============================== ================
In particular, ESC ( U is no longer "straight to font", since the font
might be completely different than the IBM character set. This
@@ -55,10 +61,12 @@ In addition, the following characters not present in Unicode 1.1.4
have been defined; these are used by the DEC VT graphics map. [v1.2]
THIS USE IS OBSOLETE AND SHOULD NO LONGER BE USED; PLEASE SEE BELOW.
+====== ======================================
U+F800 DEC VT GRAPHICS HORIZONTAL LINE SCAN 1
U+F801 DEC VT GRAPHICS HORIZONTAL LINE SCAN 3
U+F803 DEC VT GRAPHICS HORIZONTAL LINE SCAN 7
U+F804 DEC VT GRAPHICS HORIZONTAL LINE SCAN 9
+====== ======================================
The DEC VT220 uses a 6x10 character matrix, and these characters form
a smooth progression in the DEC VT graphics character set. I have
@@ -74,10 +82,12 @@ keyboard symbols that are unlikely to ever be added to Unicode proper
since they are horribly vendor-specific. This, of course, is an
excellent example of horrible design.
+====== ======================================
U+F810 KEYBOARD SYMBOL FLYING FLAG
U+F811 KEYBOARD SYMBOL PULLDOWN MENU
U+F812 KEYBOARD SYMBOL OPEN APPLE
U+F813 KEYBOARD SYMBOL SOLID APPLE
+====== ======================================
Klingon language support
------------------------
@@ -99,8 +109,10 @@ of the dingbats/symbols/forms type and this is a language, I have
located it at the end, on a 16-cell boundary in keeping with standard
Unicode practice.
-NOTE: This range is now officially managed by the ConScript Unicode
-Registry. The normative reference is at:
+.. note::
+
+ This range is now officially managed by the ConScript Unicode
+ Registry. The normative reference is at:
http://www.evertype.com/standards/csur/klingon.html
@@ -112,6 +124,7 @@ However, since the set of symbols appear to be consistent throughout,
with only the actual shapes being different, in keeping with standard
Unicode practice these differences are considered font variants.
+====== =======================================================
U+F8D0 KLINGON LETTER A
U+F8D1 KLINGON LETTER B
U+F8D2 KLINGON LETTER CH
@@ -155,6 +168,7 @@ U+F8F9 KLINGON DIGIT NINE
U+F8FD KLINGON COMMA
U+F8FE KLINGON FULL STOP
U+F8FF KLINGON SYMBOL FOR EMPIRE
+====== =======================================================
Other Fictional and Artificial Scripts
--------------------------------------
diff --git a/Documentation/user/index.rst b/Documentation/user/index.rst
index 16c73d947744..6814e1813448 100644
--- a/Documentation/user/index.rst
+++ b/Documentation/user/index.rst
@@ -22,6 +22,7 @@ Contents:
parport
md
sysrq
+ unicode
sysfs-rules
devices
module-signing
diff --git a/Documentation/user/unicode.rst b/Documentation/user/unicode.rst
new file mode 120000
index 000000000000..66f661283310
--- /dev/null
+++ b/Documentation/user/unicode.rst
@@ -0,0 +1 @@
+../unicode.txt
\ No newline at end of file
--
2.7.4
[toc] | [prev] | [next] | [standalone]
| From | Mauro Carvalho Chehab <mchehab@s-opensource.com> |
|---|---|
| Date | 2016-10-17 19:10 +0200 |
| Subject | [PATCH 30/32] Documentation/VGA-softcursor.txt: convert to ReST markup |
| Message-ID | <stjAf-6l5-83@gated-at.bofh.it> |
| In reply to | #1502210 |
- Fix document title;
- use quote blocks where needed;
- use monotonic fonts for config options and file names;
- adjust whitespaces and blank lines;
- add it to the user's book.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
Documentation/VGA-softcursor.txt | 73 ++++++++++++++++++++++++-----------
Documentation/user/VGA-softcursor.rst | 1 +
Documentation/user/index.rst | 1 +
3 files changed, 52 insertions(+), 23 deletions(-)
create mode 120000 Documentation/user/VGA-softcursor.rst
diff --git a/Documentation/VGA-softcursor.txt b/Documentation/VGA-softcursor.txt
index 70acfbf399eb..9eac6744b3a1 100644
--- a/Documentation/VGA-softcursor.txt
+++ b/Documentation/VGA-softcursor.txt
@@ -1,39 +1,66 @@
-Software cursor for VGA by Pavel Machek <pavel@atrey.karlin.mff.cuni.cz>
-======================= and Martin Mares <mj@atrey.karlin.mff.cuni.cz>
+Software cursor for VGA
+=======================
- Linux now has some ability to manipulate cursor appearance. Normally, you
+by Pavel Machek <pavel@atrey.karlin.mff.cuni.cz>
+and Martin Mares <mj@atrey.karlin.mff.cuni.cz>
+
+Linux now has some ability to manipulate cursor appearance. Normally, you
can set the size of hardware cursor (and also work around some ugly bugs in
-those miserable Trident cards--see #define TRIDENT_GLITCH in drivers/video/
-vgacon.c). You can now play a few new tricks: you can make your cursor look
+those miserable Trident cards [#f1]_. You can now play a few new tricks:
+you can make your cursor look
+
like a non-blinking red block, make it inverse background of the character it's
over or to highlight that character and still choose whether the original
hardware cursor should remain visible or not. There may be other things I have
never thought of.
- The cursor appearance is controlled by a "<ESC>[?1;2;3c" escape sequence
+The cursor appearance is controlled by a ``<ESC>[?1;2;3c`` escape sequence
where 1, 2 and 3 are parameters described below. If you omit any of them,
they will default to zeroes.
- Parameter 1 specifies cursor size (0=default, 1=invisible, 2=underline, ...,
-8=full block) + 16 if you want the software cursor to be applied + 32 if you
-want to always change the background color + 64 if you dislike having the
-background the same as the foreground. Highlights are ignored for the last two
-flags.
+first Parameter
+ specifies cursor size::
- The second parameter selects character attribute bits you want to change
-(by simply XORing them with the value of this parameter). On standard VGA,
-the high four bits specify background and the low four the foreground. In both
-groups, low three bits set color (as in normal color codes used by the console)
-and the most significant one turns on highlight (or sometimes blinking--it
-depends on the configuration of your VGA).
+ 0=default
+ 1=invisible
+ 2=underline,
+ ...
+ 8=full block
+ + 16 if you want the software cursor to be applied
+ + 32 if you want to always change the background color
+ + 64 if you dislike having the background the same as the
+ foreground.
- The third parameter consists of character attribute bits you want to set.
-Bit setting takes place before bit toggling, so you can simply clear a bit by
-including it in both the set mask and the toggle mask.
+ Highlights are ignored for the last two flags.
+
+second parameter
+ selects character attribute bits you want to change
+ (by simply XORing them with the value of this parameter). On standard
+ VGA, the high four bits specify background and the low four the
+ foreground. In both groups, low three bits set color (as in normal
+ color codes used by the console) and the most significant one turns
+ on highlight (or sometimes blinking -- it depends on the configuration
+ of your VGA).
+
+third parameter
+ consists of character attribute bits you want to set.
+
+ Bit setting takes place before bit toggling, so you can simply clear a
+ bit by including it in both the set mask and the toggle mask.
+
+.. [#f1] see ``#define TRIDENT_GLITCH`` in ``drivers/video/vgacon.c``.
Examples:
=========
-To get normal blinking underline, use: echo -e '\033[?2c'
-To get blinking block, use: echo -e '\033[?6c'
-To get red non-blinking block, use: echo -e '\033[?17;0;64c'
+To get normal blinking underline, use::
+
+ echo -e '\033[?2c'
+
+To get blinking block, use::
+
+ echo -e '\033[?6c'
+
+To get red non-blinking block, use::
+
+ echo -e '\033[?17;0;64c'
diff --git a/Documentation/user/VGA-softcursor.rst b/Documentation/user/VGA-softcursor.rst
new file mode 120000
index 000000000000..500dbb35a76f
--- /dev/null
+++ b/Documentation/user/VGA-softcursor.rst
@@ -0,0 +1 @@
+../VGA-softcursor.txt
\ No newline at end of file
diff --git a/Documentation/user/index.rst b/Documentation/user/index.rst
index 6814e1813448..6fbb2dc4b3b7 100644
--- a/Documentation/user/index.rst
+++ b/Documentation/user/index.rst
@@ -23,6 +23,7 @@ Contents:
md
sysrq
unicode
+ VGA-softcursor
sysfs-rules
devices
module-signing
--
2.7.4
[toc] | [prev] | [next] | [standalone]
| From | Mauro Carvalho Chehab <mchehab@s-opensource.com> |
|---|---|
| Date | 2016-10-17 19:10 +0200 |
| Subject | [PATCH 26/32] Documentation/ramoops.txt: convert it to ReST format |
| Message-ID | <stjAf-6l5-67@gated-at.bofh.it> |
| In reply to | #1502210 |
- Fix document title;
- use quote blocks where needed;
- use monotonic fonts for config options and file names;
- adjust whitespaces and blank lines;
- add it to the user's book.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
Documentation/ramoops.txt | 86 +++++++++++++++++++++++-------------------
Documentation/user/index.rst | 1 +
Documentation/user/ramoops.rst | 1 +
3 files changed, 49 insertions(+), 39 deletions(-)
create mode 120000 Documentation/user/ramoops.rst
diff --git a/Documentation/ramoops.txt b/Documentation/ramoops.txt
index 26b9f31cf65a..7eaf1e71c083 100644
--- a/Documentation/ramoops.txt
+++ b/Documentation/ramoops.txt
@@ -5,34 +5,37 @@ Sergiu Iordache <sergiu@chromium.org>
Updated: 17 November 2011
-0. Introduction
+Introduction
+------------
Ramoops is an oops/panic logger that writes its logs to RAM before the system
crashes. It works by logging oopses and panics in a circular buffer. Ramoops
needs a system with persistent RAM so that the content of that area can
survive after a restart.
-1. Ramoops concepts
+Ramoops concepts
+----------------
Ramoops uses a predefined memory area to store the dump. The start and size
and type of the memory area are set using three variables:
- * "mem_address" for the start
- * "mem_size" for the size. The memory size will be rounded down to a
- power of two.
- * "mem_type" to specifiy if the memory type (default is pgprot_writecombine).
-Typically the default value of mem_type=0 should be used as that sets the pstore
-mapping to pgprot_writecombine. Setting mem_type=1 attempts to use
-pgprot_noncached, which only works on some platforms. This is because pstore
+ * ``mem_address`` for the start
+ * ``mem_size`` for the size. The memory size will be rounded down to a
+ power of two.
+ * ``mem_type`` to specifiy if the memory type (default is pgprot_writecombine).
+
+Typically the default value of ``mem_type=0`` should be used as that sets the pstore
+mapping to pgprot_writecombine. Setting ``mem_type=1`` attempts to use
+``pgprot_noncached``, which only works on some platforms. This is because pstore
depends on atomic operations. At least on ARM, pgprot_noncached causes the
memory to be mapped strongly ordered, and atomic operations on strongly ordered
memory are implementation defined, and won't work on many ARMs such as omaps.
-The memory area is divided into "record_size" chunks (also rounded down to
-power of two) and each oops/panic writes a "record_size" chunk of
+The memory area is divided into ``record_size`` chunks (also rounded down to
+power of two) and each oops/panic writes a ``record_size`` chunk of
information.
-Dumping both oopses and panics can be done by setting 1 in the "dump_oops"
+Dumping both oopses and panics can be done by setting 1 in the ``dump_oops``
variable while setting 0 in that variable dumps only the panics.
The module uses a counter to record multiple dumps but the counter gets reset
@@ -43,7 +46,8 @@ This might be useful when a hardware reset was used to bring the machine back
to life (i.e. a watchdog triggered). In such cases, RAM may be somewhat
corrupt, but usually it is restorable.
-2. Setting the parameters
+Setting the parameters
+----------------------
Setting the ramoops parameters can be done in several different manners:
@@ -52,12 +56,13 @@ Setting the ramoops parameters can be done in several different manners:
boot and then use the reserved memory for ramoops. For example, assuming a
machine with > 128 MB of memory, the following kernel command line will tell
the kernel to use only the first 128 MB of memory, and place ECC-protected
- ramoops region at 128 MB boundary:
- "mem=128M ramoops.mem_address=0x8000000 ramoops.ecc=1"
+ ramoops region at 128 MB boundary::
+
+ mem=128M ramoops.mem_address=0x8000000 ramoops.ecc=1
B. Use Device Tree bindings, as described in
- Documentation/device-tree/bindings/reserved-memory/ramoops.txt.
- For example:
+ ``Documentation/device-tree/bindings/reserved-memory/ramoops.txt``.
+ For example::
reserved-memory {
#address-cells = <2>;
@@ -73,60 +78,63 @@ Setting the ramoops parameters can be done in several different manners:
};
C. Use a platform device and set the platform data. The parameters can then
- be set through that platform data. An example of doing that is:
+ be set through that platform data. An example of doing that is::
-#include <linux/pstore_ram.h>
-[...]
+ #include <linux/pstore_ram.h>
+ [...]
-static struct ramoops_platform_data ramoops_data = {
+ static struct ramoops_platform_data ramoops_data = {
.mem_size = <...>,
.mem_address = <...>,
.mem_type = <...>,
.record_size = <...>,
.dump_oops = <...>,
.ecc = <...>,
-};
+ };
-static struct platform_device ramoops_dev = {
+ static struct platform_device ramoops_dev = {
.name = "ramoops",
.dev = {
.platform_data = &ramoops_data,
},
-};
+ };
-[... inside a function ...]
-int ret;
+ [... inside a function ...]
+ int ret;
-ret = platform_device_register(&ramoops_dev);
-if (ret) {
+ ret = platform_device_register(&ramoops_dev);
+ if (ret) {
printk(KERN_ERR "unable to register platform device\n");
return ret;
-}
+ }
You can specify either RAM memory or peripheral devices' memory. However, when
specifying RAM, be sure to reserve the memory by issuing memblock_reserve()
-very early in the architecture code, e.g.:
+very early in the architecture code, e.g.::
-#include <linux/memblock.h>
+ #include <linux/memblock.h>
-memblock_reserve(ramoops_data.mem_address, ramoops_data.mem_size);
+ memblock_reserve(ramoops_data.mem_address, ramoops_data.mem_size);
-3. Dump format
+Dump format
+-----------
-The data dump begins with a header, currently defined as "====" followed by a
+The data dump begins with a header, currently defined as ``====`` followed by a
timestamp and a new line. The dump then continues with the actual data.
-4. Reading the data
+Reading the data
+----------------
The dump data can be read from the pstore filesystem. The format for these
-files is "dmesg-ramoops-N", where N is the record number in memory. To delete
+files is ``dmesg-ramoops-N``, where N is the record number in memory. To delete
a stored record from RAM, simply unlink the respective pstore file.
-5. Persistent function tracing
+Persistent function tracing
+---------------------------
Persistent function tracing might be useful for debugging software or hardware
-related hangs. The functions call chain log is stored in a "ftrace-ramoops"
-file. Here is an example of usage:
+related hangs. The functions call chain log is stored in a ``ftrace-ramoops``
+file. Here is an example of usage::
# mount -t debugfs debugfs /sys/kernel/debug/
# echo 1 > /sys/kernel/debug/pstore/record_ftrace
diff --git a/Documentation/user/index.rst b/Documentation/user/index.rst
index c2304e135b40..f5dec1436263 100644
--- a/Documentation/user/index.rst
+++ b/Documentation/user/index.rst
@@ -11,6 +11,7 @@ Contents:
REPORTING-BUGS
BUG-HUNTING
oops-tracing
+ ramoops
initrd
init
dynamic-debug-howto
diff --git a/Documentation/user/ramoops.rst b/Documentation/user/ramoops.rst
new file mode 120000
index 000000000000..0750fa1ce290
--- /dev/null
+++ b/Documentation/user/ramoops.rst
@@ -0,0 +1 @@
+../ramoops.txt
\ No newline at end of file
--
2.7.4
[toc] | [prev] | [next] | [standalone]
| From | Mauro Carvalho Chehab <mchehab@s-opensource.com> |
|---|---|
| Date | 2016-10-17 19:10 +0200 |
| Subject | [PATCH 23/32] Documentation/java.txt: convert to ReST markup |
| Message-ID | <stjAg-6l5-85@gated-at.bofh.it> |
| In reply to | #1502210 |
- Fix document title;
- use quote blocks where needed;
- use monotonic fonts for config options and file names;
- adjust whitespaces and blank lines;
- add it to the user's book.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
Documentation/java.txt | 244 +++++++++++++++++++++++--------------------
Documentation/user/index.rst | 1 +
Documentation/user/java.rst | 1 +
3 files changed, 131 insertions(+), 115 deletions(-)
create mode 120000 Documentation/user/java.rst
diff --git a/Documentation/java.txt b/Documentation/java.txt
index 418020584ccc..ae33d959638c 100644
--- a/Documentation/java.txt
+++ b/Documentation/java.txt
@@ -1,5 +1,5 @@
- Java(tm) Binary Kernel Support for Linux v1.03
- ----------------------------------------------
+Java(tm) Binary Kernel Support for Linux v1.03
+----------------------------------------------
Linux beats them ALL! While all other OS's are TALKING about direct
support of Java Binaries in the OS, Linux is doing it!
@@ -19,70 +19,80 @@ other program after you have done the following:
as the application itself).
2) You have to compile BINFMT_MISC either as a module or into
- the kernel (CONFIG_BINFMT_MISC) and set it up properly.
+ the kernel (``CONFIG_BINFMT_MISC``) and set it up properly.
If you choose to compile it as a module, you will have
to insert it manually with modprobe/insmod, as kmod
- cannot easily be supported with binfmt_misc.
+ cannot easily be supported with binfmt_misc.
Read the file 'binfmt_misc.txt' in this directory to know
more about the configuration process.
3) Add the following configuration items to binfmt_misc
- (you should really have read binfmt_misc.txt now):
- support for Java applications:
+ (you should really have read ``binfmt_misc.txt`` now):
+ support for Java applications::
+
':Java:M::\xca\xfe\xba\xbe::/usr/local/bin/javawrapper:'
- support for executable Jar files:
+
+ support for executable Jar files::
+
':ExecutableJAR:E::jar::/usr/local/bin/jarwrapper:'
- support for Java Applets:
+
+ support for Java Applets::
+
':Applet:E::html::/usr/bin/appletviewer:'
- or the following, if you want to be more selective:
+
+ or the following, if you want to be more selective::
+
':Applet:M::<!--applet::/usr/bin/appletviewer:'
Of course you have to fix the path names. The path/file names given in this
- document match the Debian 2.1 system. (i.e. jdk installed in /usr,
- custom wrappers from this document in /usr/local)
+ document match the Debian 2.1 system. (i.e. jdk installed in ``/usr``,
+ custom wrappers from this document in ``/usr/local``)
Note, that for the more selective applet support you have to modify
- existing html-files to contain <!--applet--> in the first line
- ('<' has to be the first character!) to let this work!
+ existing html-files to contain ``<!--applet-->`` in the first line
+ (``<`` has to be the first character!) to let this work!
For the compiled Java programs you need a wrapper script like the
following (this is because Java is broken in case of the filename
handling), again fix the path names, both in the script and in the
above given configuration string.
- You, too, need the little program after the script. Compile like
- gcc -O2 -o javaclassname javaclassname.c
- and stick it to /usr/local/bin.
+ You, too, need the little program after the script. Compile like::
+
+ gcc -O2 -o javaclassname javaclassname.c
+
+ and stick it to ``/usr/local/bin``.
Both the javawrapper shellscript and the javaclassname program
were supplied by Colin J. Watson <cjw44@cam.ac.uk>.
-====================== Cut here ===================
-#!/bin/bash
-# /usr/local/bin/javawrapper - the wrapper for binfmt_misc/java
+Javawrapper shell script::
-if [ -z "$1" ]; then
+ #!/bin/bash
+ # /usr/local/bin/javawrapper - the wrapper for binfmt_misc/java
+
+ if [ -z "$1" ]; then
exec 1>&2
echo Usage: $0 class-file
exit 1
-fi
+ fi
-CLASS=$1
-FQCLASS=`/usr/local/bin/javaclassname $1`
-FQCLASSN=`echo $FQCLASS | sed -e 's/^.*\.\([^.]*\)$/\1/'`
-FQCLASSP=`echo $FQCLASS | sed -e 's-\.-/-g' -e 's-^[^/]*$--' -e 's-/[^/]*$--'`
+ CLASS=$1
+ FQCLASS=`/usr/local/bin/javaclassname $1`
+ FQCLASSN=`echo $FQCLASS | sed -e 's/^.*\.\([^.]*\)$/\1/'`
+ FQCLASSP=`echo $FQCLASS | sed -e 's-\.-/-g' -e 's-^[^/]*$--' -e 's-/[^/]*$--'`
-# for example:
-# CLASS=Test.class
-# FQCLASS=foo.bar.Test
-# FQCLASSN=Test
-# FQCLASSP=foo/bar
+ # for example:
+ # CLASS=Test.class
+ # FQCLASS=foo.bar.Test
+ # FQCLASSN=Test
+ # FQCLASSP=foo/bar
-unset CLASSBASE
+ unset CLASSBASE
-declare -i LINKLEVEL=0
+ declare -i LINKLEVEL=0
-while :; do
+ while :; do
if [ "`basename $CLASS .class`" == "$FQCLASSN" ]; then
# See if this directory works straight off
cd -L `dirname $CLASS`
@@ -119,9 +129,9 @@ while :; do
exit 1
fi
CLASS=`ls --color=no -l $CLASS | sed -e 's/^.* \([^ ]*\)$/\1/'`
-done
+ done
-if [ -z "$CLASSBASE" ]; then
+ if [ -z "$CLASSBASE" ]; then
if [ -z "$FQCLASSP" ]; then
GOODNAME=$FQCLASSN.class
else
@@ -131,24 +141,23 @@ if [ -z "$CLASSBASE" ]; then
echo $0:
echo " $FQCLASS should be in a file called $GOODNAME"
exit 1
-fi
+ fi
-if ! echo $CLASSPATH | grep -q "^\(.*:\)*$CLASSBASE\(:.*\)*"; then
+ if ! echo $CLASSPATH | grep -q "^\(.*:\)*$CLASSBASE\(:.*\)*"; then
# class is not in CLASSPATH, so prepend dir of class to CLASSPATH
if [ -z "${CLASSPATH}" ] ; then
export CLASSPATH=$CLASSBASE
else
export CLASSPATH=$CLASSBASE:$CLASSPATH
fi
-fi
+ fi
-shift
-/usr/bin/java $FQCLASS "$@"
-====================== Cut here ===================
+ shift
+ /usr/bin/java $FQCLASS "$@"
+javaclassname.c::
-====================== Cut here ===================
-/* javaclassname.c
+ /* javaclassname.c
*
* Extracts the class name from a Java class file; intended for use in a Java
* wrapper of the type supported by the binfmt_misc option in the Linux kernel.
@@ -170,57 +179,57 @@ shift
* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
*/
-#include <stdlib.h>
-#include <stdio.h>
-#include <stdarg.h>
-#include <sys/types.h>
-
-/* From Sun's Java VM Specification, as tag entries in the constant pool. */
-
-#define CP_UTF8 1
-#define CP_INTEGER 3
-#define CP_FLOAT 4
-#define CP_LONG 5
-#define CP_DOUBLE 6
-#define CP_CLASS 7
-#define CP_STRING 8
-#define CP_FIELDREF 9
-#define CP_METHODREF 10
-#define CP_INTERFACEMETHODREF 11
-#define CP_NAMEANDTYPE 12
-#define CP_METHODHANDLE 15
-#define CP_METHODTYPE 16
-#define CP_INVOKEDYNAMIC 18
-
-/* Define some commonly used error messages */
-
-#define seek_error() error("%s: Cannot seek\n", program)
-#define corrupt_error() error("%s: Class file corrupt\n", program)
-#define eof_error() error("%s: Unexpected end of file\n", program)
-#define utf8_error() error("%s: Only ASCII 1-255 supported\n", program);
-
-char *program;
-
-long *pool;
-
-u_int8_t read_8(FILE *classfile);
-u_int16_t read_16(FILE *classfile);
-void skip_constant(FILE *classfile, u_int16_t *cur);
-void error(const char *format, ...);
-int main(int argc, char **argv);
-
-/* Reads in an unsigned 8-bit integer. */
-u_int8_t read_8(FILE *classfile)
-{
+ #include <stdlib.h>
+ #include <stdio.h>
+ #include <stdarg.h>
+ #include <sys/types.h>
+
+ /* From Sun's Java VM Specification, as tag entries in the constant pool. */
+
+ #define CP_UTF8 1
+ #define CP_INTEGER 3
+ #define CP_FLOAT 4
+ #define CP_LONG 5
+ #define CP_DOUBLE 6
+ #define CP_CLASS 7
+ #define CP_STRING 8
+ #define CP_FIELDREF 9
+ #define CP_METHODREF 10
+ #define CP_INTERFACEMETHODREF 11
+ #define CP_NAMEANDTYPE 12
+ #define CP_METHODHANDLE 15
+ #define CP_METHODTYPE 16
+ #define CP_INVOKEDYNAMIC 18
+
+ /* Define some commonly used error messages */
+
+ #define seek_error() error("%s: Cannot seek\n", program)
+ #define corrupt_error() error("%s: Class file corrupt\n", program)
+ #define eof_error() error("%s: Unexpected end of file\n", program)
+ #define utf8_error() error("%s: Only ASCII 1-255 supported\n", program);
+
+ char *program;
+
+ long *pool;
+
+ u_int8_t read_8(FILE *classfile);
+ u_int16_t read_16(FILE *classfile);
+ void skip_constant(FILE *classfile, u_int16_t *cur);
+ void error(const char *format, ...);
+ int main(int argc, char **argv);
+
+ /* Reads in an unsigned 8-bit integer. */
+ u_int8_t read_8(FILE *classfile)
+ {
int b = fgetc(classfile);
if(b == EOF)
eof_error();
return (u_int8_t)b;
-}
+ }
-/* Reads in an unsigned 16-bit integer. */
-u_int16_t read_16(FILE *classfile)
-{
+ /* Reads in an unsigned 16-bit integer. */
+ u_int16_t read_16(FILE *classfile)
+ {
int b1, b2;
b1 = fgetc(classfile);
if(b1 == EOF)
@@ -229,11 +238,11 @@ u_int16_t read_16(FILE *classfile)
if(b2 == EOF)
eof_error();
return (u_int16_t)((b1 << 8) | b2);
-}
+ }
-/* Reads in a value from the constant pool. */
-void skip_constant(FILE *classfile, u_int16_t *cur)
-{
+ /* Reads in a value from the constant pool. */
+ void skip_constant(FILE *classfile, u_int16_t *cur)
+ {
u_int16_t len;
int seekerr = 1;
pool[*cur] = ftell(classfile);
@@ -270,19 +279,19 @@ void skip_constant(FILE *classfile, u_int16_t *cur)
}
if(seekerr)
seek_error();
-}
+ }
-void error(const char *format, ...)
-{
+ void error(const char *format, ...)
+ {
va_list ap;
va_start(ap, format);
vfprintf(stderr, format, ap);
va_end(ap);
exit(1);
-}
+ }
-int main(int argc, char **argv)
-{
+ int main(int argc, char **argv)
+ {
FILE *classfile;
u_int16_t cp_count, i, this_class, classinfo_ptr;
u_int8_t length;
@@ -349,19 +358,19 @@ int main(int argc, char **argv)
free(pool);
fclose(classfile);
return 0;
-}
-====================== Cut here ===================
+ }
+jarwrapper::
-====================== Cut here ===================
-#!/bin/bash
-# /usr/local/java/bin/jarwrapper - the wrapper for binfmt_misc/jar
+ #!/bin/bash
+ # /usr/local/java/bin/jarwrapper - the wrapper for binfmt_misc/jar
-java -jar $1
-====================== Cut here ===================
+ java -jar $1
-Now simply chmod +x the .class, .jar and/or .html files you want to execute.
+Now simply ``chmod +x`` the ``.class``, ``.jar`` and/or ``.html`` files you
+want to execute.
+
To add a Java program to your path best put a symbolic link to the main
.class file into /usr/bin (or another place you like) omitting the .class
extension. The directory containing the original .class file will be
@@ -369,7 +378,7 @@ added to your CLASSPATH during execution.
To test your new setup, enter in the following simple Java app, and name
-it "HelloWorld.java":
+it "HelloWorld.java"::
class HelloWorld {
public static void main(String args[]) {
@@ -377,23 +386,28 @@ it "HelloWorld.java":
}
}
-Now compile the application with:
+Now compile the application with::
+
javac HelloWorld.java
-Set the executable permissions of the binary file, with:
+Set the executable permissions of the binary file, with::
+
chmod 755 HelloWorld.class
-And then execute it:
+And then execute it::
+
./HelloWorld.class
-To execute Java Jar files, simple chmod the *.jar files to include
-the execution bit, then just do
+To execute Java Jar files, simple chmod the ``*.jar`` files to include
+the execution bit, then just do::
+
./Application.jar
-To execute Java Applets, simple chmod the *.html files to include
-the execution bit, then just do
+To execute Java Applets, simple chmod the ``*.html`` files to include
+the execution bit, then just do::
+
./Applet.html
diff --git a/Documentation/user/index.rst b/Documentation/user/index.rst
index 1858fc94c630..654b17c72818 100644
--- a/Documentation/user/index.rst
+++ b/Documentation/user/index.rst
@@ -22,5 +22,6 @@ Contents:
module-signing
binfmt_misc
mono
+ java
bad_memory
basic_profiling
diff --git a/Documentation/user/java.rst b/Documentation/user/java.rst
new file mode 120000
index 000000000000..da9be21b4e5e
--- /dev/null
+++ b/Documentation/user/java.rst
@@ -0,0 +1 @@
+../java.txt
\ No newline at end of file
--
2.7.4
[toc] | [prev] | [next] | [standalone]
| From | Mauro Carvalho Chehab <mchehab@s-opensource.com> |
|---|---|
| Date | 2016-10-17 19:20 +0200 |
| Subject | [PATCH 08/32] Documentation/bad_memory.txt: convert it to ReST markup |
| Message-ID | <stjJX-6pe-121@gated-at.bofh.it> |
| In reply to | #1502210 |
- 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 | Jonathan Corbet <corbet@lwn.net> |
|---|---|
| Date | 2016-10-18 00:50 +0200 |
| Subject | Re: [PATCH 00/32] Create an User's manual and improve development-process book |
| Message-ID | <stoTf-1G1-11@gated-at.bofh.it> |
| In reply to | #1502210 |
I've only been able to take a quick look at these - I'm buried fairly deep at the moment. A few superficial thoughts. On Mon, 17 Oct 2016 14:55:37 -0200 Mauro Carvalho Chehab <mchehab@s-opensource.com> wrote: > In my opinion, it would be better to move the converted files to be inside > a Sphinx build directory, but Jon seems reluctant to that, so, this series > use symlinks, as it is easy to move the files in the future with a very simple > patch, if we decide to do so. So I raised this topic in talks at both Kernel Recipes and LinuxCon Europe, and nobody threw things at me. I have come to suspect that I'm worrying a little too much about it; maybe we should go ahead and move the documents and see who screams. The work could go into docs-next soon, and there would be an opportunity to fix things up if all hell breaks loose at the kernel summit. Can I make some silly requests? - Can we move development-process to something shorter, like just "process"? We'll be typing it a lot, and tab completion doesn't work in most email clients :) - I think we should leave pointers behind in the form of one-line "this file has moved" messages. Probably only SubmittingPatches and CodingStyle need that treatment, I think. - The "user manual" is certainly something that has been on my mind as well. We have documentation for completely separate audiences all mixed together now, and definitely need to fix that. But rather than "user", can we paint that shed "admin-guide" or something like that? Thanks for doing all of this, jon
[toc] | [prev] | [next] | [standalone]
| From | Markus Heiser <markus.heiser@darmarit.de> |
|---|---|
| Date | 2016-10-18 06:40 +0200 |
| Message-ID | <stulY-5kR-13@gated-at.bofh.it> |
| In reply to | #1502566 |
Hi Jon, Am 18.10.2016 um 00:43 schrieb Jonathan Corbet <corbet@lwn.net>: > I've only been able to take a quick look at these - I'm buried fairly deep > at the moment. A few superficial thoughts. > > On Mon, 17 Oct 2016 14:55:37 -0200 > Mauro Carvalho Chehab <mchehab@s-opensource.com> wrote: > >> In my opinion, it would be better to move the converted files to be inside >> a Sphinx build directory, but Jon seems reluctant to that, so, this series >> use symlinks, as it is easy to move the files in the future with a very simple >> patch, if we decide to do so. > > So I raised this topic in talks at both Kernel Recipes and LinuxCon > Europe, and nobody threw things at me. sounds good ;-) > I have come to suspect that I'm > worrying a little too much about it; maybe we should go ahead and move > the documents and see who screams. The work could go into docs-next soon, > and there would be an opportunity to fix things up if all hell breaks > loose at the kernel summit. > > Can I make some silly requests? > > - Can we move development-process to something shorter, like just > "process"? We'll be typing it a lot, and tab completion doesn't work in > most email clients :) > > - I think we should leave pointers behind in the form of one-line "this > file has moved" messages. Probably only SubmittingPatches and > CodingStyle need that treatment, I think. > > - The "user manual" is certainly something that has been on my mind as > well. We have documentation for completely separate audiences all mixed > together now, and definitely need to fix that. But rather than "user", > can we paint that shed "admin-guide" or something like that? > One Silly request of mine: Is there a chance moving "./Documentation" to something shorter like "./doc"? Even with "Text completion" (in Emacs [1]), IMO "Documentation" is to long. --Markus-- [1] https://www.emacswiki.org/emacs/CategoryCompletion > Thanks for doing all of this, > > jon > -- > To unsubscribe from this list: send the line "unsubscribe linux-doc" in > the body of a message to majordomo@vger.kernel.org > More majordomo info at http://vger.kernel.org/majordomo-info.html
[toc] | [prev] | [next] | [standalone]
| From | Jonathan Corbet <corbet@lwn.net> |
|---|---|
| Date | 2016-10-18 15:40 +0200 |
| Subject | Renaming Documentation/ [was [PATCH 00/32] Create an User's manual and improve development-process book] |
| Message-ID | <stCMz-2hJ-69@gated-at.bofh.it> |
| In reply to | #1502681 |
On Tue, 18 Oct 2016 06:30:48 +0200 Markus Heiser <markus.heiser@darmarit.de> wrote: > One Silly request of mine: > > Is there a chance moving "./Documentation" to something shorter > like "./doc"? Even with "Text completion" (in Emacs [1]), IMO > "Documentation" is to long. I'd be entirely in favor of that. It would require some pretty widespread and high-level buy-in, though, including from the device-tree folks. That truly is something to raise at the kernel summit; if Linus incinerates me, we'll know it's not going to happen...:) jon
[toc] | [prev] | [next] | [standalone]
| From | Theodore Ts'o <tytso@mit.edu> |
|---|---|
| Date | 2016-10-18 16:20 +0200 |
| Subject | Re: Renaming Documentation/ [was [PATCH 00/32] Create an User's manual and improve development-process book] |
| Message-ID | <stDpf-2Og-5@gated-at.bofh.it> |
| In reply to | #1502997 |
On Tue, Oct 18, 2016 at 07:37:34AM -0600, Jonathan Corbet wrote: > On Tue, 18 Oct 2016 06:30:48 +0200 > Markus Heiser <markus.heiser@darmarit.de> wrote: > > > One Silly request of mine: > > > > Is there a chance moving "./Documentation" to something shorter > > like "./doc"? Even with "Text completion" (in Emacs [1]), IMO > > "Documentation" is to long. > > I'd be entirely in favor of that. It would require some pretty > widespread and high-level buy-in, though, including from the device-tree > folks. That truly is something to raise at the kernel summit; if Linus > incinerates me, we'll know it's not going to happen...:) In the meantime, simply dropping in a symlink is a convenient shortcut for individual developers (for example, I have a symlink at the top-level from patches to .git/patches/origin to make accessing my guilt patch stack more convenient). - Ted
[toc] | [prev] | [next] | [standalone]
| From | Mauro Carvalho Chehab <mchehab@s-opensource.com> |
|---|---|
| Date | 2016-10-18 10:40 +0200 |
| Subject | Re: [PATCH 00/32] Create an User's manual and improve development-process book |
| Message-ID | <sty6d-7Dr-11@gated-at.bofh.it> |
| In reply to | #1502566 |
Em Mon, 17 Oct 2016 16:43:42 -0600 Jonathan Corbet <corbet@lwn.net> escreveu: > I've only been able to take a quick look at these - I'm buried fairly deep > at the moment. A few superficial thoughts. > > On Mon, 17 Oct 2016 14:55:37 -0200 > Mauro Carvalho Chehab <mchehab@s-opensource.com> wrote: > > > In my opinion, it would be better to move the converted files to be inside > > a Sphinx build directory, but Jon seems reluctant to that, so, this series > > use symlinks, as it is easy to move the files in the future with a very simple > > patch, if we decide to do so. > > So I raised this topic in talks at both Kernel Recipes and LinuxCon > Europe, and nobody threw things at me. I have come to suspect that I'm > worrying a little too much about it; maybe we should go ahead and move > the documents and see who screams. The work could go into docs-next soon, > and there would be an opportunity to fix things up if all hell breaks > loose at the kernel summit. > > Can I make some silly requests? > > - Can we move development-process to something shorter, like just > "process"? We'll be typing it a lot, and tab completion doesn't work in > most email clients :) OK! > - I think we should leave pointers behind in the form of one-line "this > file has moved" messages. Probably only SubmittingPatches and > CodingStyle need that treatment, I think. Ok. Following such logic, I guess we should also add a similar notice to the main README file too, that will be at the "user/admin-guide". I would actually be a little more verbose there, providing pointers to the main documentation books (e. g. the non-subsystem specific ones) there, like: The content of this file was moved to Documentation/admin-guide/README.rst For Kernel's build and admin documentation, please see Documentation/admin-guide; For guides about the Kernel development process, please see Documentation/process; ... > - The "user manual" is certainly something that has been on my mind as > well. We have documentation for completely separate audiences all mixed > together now, and definitely need to fix that. But rather than "user", > can we paint that shed "admin-guide" or something like that? Ok! "admin-guide" sounds a good name. > Thanks for doing all of this, Anytime! Thanks, Mauro
[toc] | [prev] | [next] | [standalone]
| From | Jani Nikula <jani.nikula@linux.intel.com> |
|---|---|
| Date | 2016-10-18 12:10 +0200 |
| Message-ID | <stzvj-ck-11@gated-at.bofh.it> |
| In reply to | #1502566 |
On Tue, 18 Oct 2016, Jonathan Corbet <corbet@lwn.net> wrote: > So I raised this topic in talks at both Kernel Recipes and LinuxCon > Europe, and nobody threw things at me. I have come to suspect that I'm > worrying a little too much about it; maybe we should go ahead and move > the documents and see who screams. While at it, how about unifying some of the FilenamesInCamelCase, filenames-with-hyphens, and filenames_with_underscores too...? To at least move things towards just one of them within one directory. > Thanks for doing all of this, Yes! Despite all my nitpicking and disagreements about the Sphinx build stuff, I very much appreciate your efforts here, Mauro! BR, Jani. -- Jani Nikula, Intel Open Source Technology Center
[toc] | [prev] | [next] | [standalone]
| From | Mauro Carvalho Chehab <mchehab@s-opensource.com> |
|---|---|
| Date | 2016-10-18 12:30 +0200 |
| Subject | Re: [PATCH 00/32] Create an User's manual and improve development-process book |
| Message-ID | <stzOG-lH-15@gated-at.bofh.it> |
| In reply to | #1502856 |
Em Tue, 18 Oct 2016 13:01:01 +0300 Jani Nikula <jani.nikula@linux.intel.com> escreveu: > On Tue, 18 Oct 2016, Jonathan Corbet <corbet@lwn.net> wrote: > > So I raised this topic in talks at both Kernel Recipes and LinuxCon > > Europe, and nobody threw things at me. I have come to suspect that I'm > > worrying a little too much about it; maybe we should go ahead and move > > the documents and see who screams. > > While at it, how about unifying some of the FilenamesInCamelCase, > filenames-with-hyphens, and filenames_with_underscores too...? To at > least move things towards just one of them within one directory. Sure, let's do it. I would just keep README as README.rst , as people are more used to see readme files on upercases. For the rest, what's your preference? - FooBar.rst - foo_bar.rst - foo-bar.rst My personal preference is for "foo-bar". > > > Thanks for doing all of this, > > Yes! Despite all my nitpicking and disagreements about the Sphinx build > stuff, I very much appreciate your efforts here, Mauro! Thanks! Life would be very boring if everybody would have the same opinion :) So, feel free to disagree with me. Your views are very welcome, even when differs from my own :) Regards, Mauro
[toc] | [prev] | [next] | [standalone]
| From | Jani Nikula <jani.nikula@linux.intel.com> |
|---|---|
| Date | 2016-10-18 12:40 +0200 |
| Message-ID | <stzYl-p4-15@gated-at.bofh.it> |
| In reply to | #1502880 |
On Tue, 18 Oct 2016, Mauro Carvalho Chehab <mchehab@s-opensource.com> wrote: > Em Tue, 18 Oct 2016 13:01:01 +0300 > Jani Nikula <jani.nikula@linux.intel.com> escreveu: > >> On Tue, 18 Oct 2016, Jonathan Corbet <corbet@lwn.net> wrote: >> > So I raised this topic in talks at both Kernel Recipes and LinuxCon >> > Europe, and nobody threw things at me. I have come to suspect that I'm >> > worrying a little too much about it; maybe we should go ahead and move >> > the documents and see who screams. >> >> While at it, how about unifying some of the FilenamesInCamelCase, >> filenames-with-hyphens, and filenames_with_underscores too...? To at >> least move things towards just one of them within one directory. > > Sure, let's do it. I would just keep README as README.rst , as people > are more used to see readme files on upercases. Right, I guess I'd keep the top level files as-is, and just do this within Documentation. > For the rest, what's your preference? > > - FooBar.rst > - foo_bar.rst > - foo-bar.rst > > My personal preference is for "foo-bar". Same here, but I don't mind so much *which* one it is as long as at least each directory has consistent naming. > Thanks! Life would be very boring if everybody would have the same > opinion :) So, feel free to disagree with me. Your views are very > welcome, even when differs from my own :) Thanks, good to check we're on the same page here and not antagonizing. :) BR, Jani. -- Jani Nikula, Intel Open Source Technology Center
[toc] | [prev] | [next] | [standalone]
| From | Mauro Carvalho Chehab <mchehab@s-opensource.com> |
|---|---|
| Date | 2016-10-18 12:50 +0200 |
| Subject | Re: [PATCH 00/32] Create an User's manual and improve development-process book |
| Message-ID | <stA81-sA-11@gated-at.bofh.it> |
| In reply to | #1502883 |
Em Tue, 18 Oct 2016 13:35:39 +0300 Jani Nikula <jani.nikula@linux.intel.com> escreveu: > On Tue, 18 Oct 2016, Mauro Carvalho Chehab <mchehab@s-opensource.com> wrote: > > Em Tue, 18 Oct 2016 13:01:01 +0300 > > Jani Nikula <jani.nikula@linux.intel.com> escreveu: > > > >> On Tue, 18 Oct 2016, Jonathan Corbet <corbet@lwn.net> wrote: > >> > So I raised this topic in talks at both Kernel Recipes and LinuxCon > >> > Europe, and nobody threw things at me. I have come to suspect that I'm > >> > worrying a little too much about it; maybe we should go ahead and move > >> > the documents and see who screams. > >> > >> While at it, how about unifying some of the FilenamesInCamelCase, > >> filenames-with-hyphens, and filenames_with_underscores too...? To at > >> least move things towards just one of them within one directory. > > > > Sure, let's do it. I would just keep README as README.rst , as people > > are more used to see readme files on upercases. > > Right, I guess I'd keep the top level files as-is, and just do this > within Documentation. Well IMHO, the most important documentation for an user/admin's guide is at /README. So, most of its contents (if not all) should be moved to Documentation/admin-guide. > > > For the rest, what's your preference? > > > > - FooBar.rst > > - foo_bar.rst > > - foo-bar.rst > > > > My personal preference is for "foo-bar". > > Same here, but I don't mind so much *which* one it is as long as at > least each directory has consistent naming. Yeah, my preference here is also not strong... whatever works best for the others fit to me. > > > Thanks! Life would be very boring if everybody would have the same > > opinion :) So, feel free to disagree with me. Your views are very > > welcome, even when differs from my own :) > > Thanks, good to check we're on the same page here and not > antagonizing. :) :) > > > BR, > Jani. > > > Thanks, Mauro
[toc] | [prev] | [next] | [standalone]
| From | Jonathan Corbet <corbet@lwn.net> |
|---|---|
| Date | 2016-10-19 01:30 +0200 |
| Subject | Re: [PATCH 00/32] Create an User's manual and improve development-process book |
| Message-ID | <stLZw-Db-29@gated-at.bofh.it> |
| In reply to | #1502880 |
On Tue, 18 Oct 2016 08:20:18 -0200 Mauro Carvalho Chehab <mchehab@s-opensource.com> wrote: > > While at it, how about unifying some of the FilenamesInCamelCase, > > filenames-with-hyphens, and filenames_with_underscores too...? To at > > least move things towards just one of them within one directory. > > Sure, let's do it. I would just keep README as README.rst , as people > are more used to see readme files on upercases. > > For the rest, what's your preference? > > - FooBar.rst > - foo_bar.rst > - foo-bar.rst > > My personal preference is for "foo-bar". I guess that would be mine too. CamelCase is not generally all that popular in kernel space. On one hand, I worry about further renaming files that we're already moving; on the other, if we're going to do it, I guess this would be the time, when people will have to look for them anyway... jon
[toc] | [prev] | [next] | [standalone]
Page 2 of 3 — ← Prev page 1 [2] 3 Next page →
Back to top | Article view | linux.kernel
csiph-web