From 7358bb2f3293461737a61850c56523695f5b2219 Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Wed, 26 Oct 2016 16:14:52 -0600 Subject: docs: Clean up and organize the admin guide a bit The admin guide is a good start, but it's time to turn it into something better than an unordered blob of files. This is a first step in that direction. The TOC has been split up and annotated, the guides have been reordered, and minor tweaks have been applied to a few of them. One consequence of splitting up the TOC is that we don't really want to use :numbered: anymore, since the count resets every time and there doesn't seem to be a way to change that. Eventually we probably want to group the documents into sub-books, at which point we can go back to a single TOC, but it's probably early to do that. Reviewed-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- Documentation/admin-guide/index.rst | 50 +++++++++++++++++++------ Documentation/admin-guide/kernel-parameters.rst | 4 +- Documentation/admin-guide/sysfs-rules.rst | 4 +- Documentation/admin-guide/vga-softcursor.rst | 4 +- 4 files changed, 45 insertions(+), 17 deletions(-) (limited to 'Documentation/admin-guide') diff --git a/Documentation/admin-guide/index.rst b/Documentation/admin-guide/index.rst index 4e5abbb..2ce2bf0 100644 --- a/Documentation/admin-guide/index.rst +++ b/Documentation/admin-guide/index.rst @@ -1,22 +1,52 @@ -Linux Kernel User's Documentation -================================= +The Linux kernel user's and administrator's guide +================================================= -Contents: +The following is a collection of user-oriented documents that have been +added to the kernel over time. There is, as yet, little overall order or +organization here — this material was not written to be a single, coherent +document! With luck things will improve quickly over time. + +This initial section contains overall information, including the README +file describing the kernel as a whole, documentation on kernel parameters, +etc. .. toctree:: - :maxdepth: 2 - :numbered: + :maxdepth: 1 README + kernel-parameters + devices + +Here is a set of documents aimed at users who are trying to track down +problems and bugs in particular. + +.. toctree:: + :maxdepth: 1 + reporting-bugs + security-bugs bug-hunting oops-tracing ramoops - initrd - init dynamic-debug-howto - security-bugs - kernel-parameters + init + +This is the beginning of a section with information of interest to +application developers. Documents covering various aspects of the kernel +ABI will be found here. + +.. toctree:: + :maxdepth: 1 + + sysfs-rules + +The rest of this manual consists of various unordered guides on how to +configure specific aspects of kernel behavior to your liking. + +.. toctree:: + :maxdepth: 1 + + initrd serial-console braille-console parport @@ -25,8 +55,6 @@ Contents: sysrq unicode vga-softcursor - sysfs-rules - devices binfmt-misc mono java diff --git a/Documentation/admin-guide/kernel-parameters.rst b/Documentation/admin-guide/kernel-parameters.rst index d2f2725..37105ae 100644 --- a/Documentation/admin-guide/kernel-parameters.rst +++ b/Documentation/admin-guide/kernel-parameters.rst @@ -1,5 +1,5 @@ -Kernel Parameters -~~~~~~~~~~~~~~~~~ +The kernel's command-line parameters +==================================== The following is a consolidated list of the kernel parameters as implemented by the __setup(), core_param() and module_param() macros diff --git a/Documentation/admin-guide/sysfs-rules.rst b/Documentation/admin-guide/sysfs-rules.rst index 04bdd52..abad335 100644 --- a/Documentation/admin-guide/sysfs-rules.rst +++ b/Documentation/admin-guide/sysfs-rules.rst @@ -1,5 +1,5 @@ -Rules on how to access information in the Linux kernel sysfs -============================================================ +Rules on how to access information in sysfs +=========================================== The kernel-exported sysfs exports internal kernel implementation details and depends on internal kernel structures and layout. It is agreed upon diff --git a/Documentation/admin-guide/vga-softcursor.rst b/Documentation/admin-guide/vga-softcursor.rst index 9eac674..a663a74 100644 --- a/Documentation/admin-guide/vga-softcursor.rst +++ b/Documentation/admin-guide/vga-softcursor.rst @@ -50,8 +50,8 @@ third parameter .. [#f1] see ``#define TRIDENT_GLITCH`` in ``drivers/video/vgacon.c``. -Examples: -========= +Examples +-------- To get normal blinking underline, use:: -- cgit v1.1 From 2c79dcafd8ecdfd44ee4c509a9c55785b022eba9 Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Wed, 26 Oct 2016 16:20:27 -0600 Subject: docs: Get rid of the badRAM guide The last release of this tool was for 2.6.28; it's hard to see how it has any relevance to current kernels. Signed-off-by: Jonathan Corbet --- Documentation/admin-guide/bad-memory.rst | 50 -------------------------------- Documentation/admin-guide/index.rst | 1 - 2 files changed, 51 deletions(-) delete mode 100644 Documentation/admin-guide/bad-memory.rst (limited to 'Documentation/admin-guide') diff --git a/Documentation/admin-guide/bad-memory.rst b/Documentation/admin-guide/bad-memory.rst deleted file mode 100644 index a5c0e25..0000000 --- a/Documentation/admin-guide/bad-memory.rst +++ /dev/null @@ -1,50 +0,0 @@ -How to deal with bad memory e.g. reported by memtest86+ ? -========================================================= - -March 2008 -Jan-Simon Moeller, dl9pf@gmx.de - - - -There are three possibilities I know of: - -1) Reinsert/swap the memory modules - -2) Buy new modules (best!) or try to exchange the memory - if you have spare-parts - -3) Use BadRAM or memmap - -This Howto is about number 3) . - - -BadRAM -###### - -BadRAM is the actively developed and available as kernel-patch -here: http://rick.vanrein.org/linux/badram/ - -For more details see the BadRAM documentation. - -memmap -###### - -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 admin-guide/kernel-parameters.rst for details):: - - memmap=$
- -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. - -With the numbers of the example above:: - - memmap=64K$0x18690000 - -or:: - - memmap=0x10000$0x18690000 diff --git a/Documentation/admin-guide/index.rst b/Documentation/admin-guide/index.rst index 2ce2bf0..d737ae7 100644 --- a/Documentation/admin-guide/index.rst +++ b/Documentation/admin-guide/index.rst @@ -58,5 +58,4 @@ configure specific aspects of kernel behavior to your liking. binfmt-misc mono java - bad-memory basic-profiling -- cgit v1.1 From 5700d1974818a98983e018efa01da9bc81b84e1a Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Wed, 26 Oct 2016 16:22:01 -0600 Subject: docs: Get rid of the "basic profiling" guide The document has not been touched in over 11 years and doesn't reflect how profiling is done in the perf era. Signed-off-by: Jonathan Corbet --- Documentation/admin-guide/basic-profiling.rst | 68 --------------------------- Documentation/admin-guide/index.rst | 1 - 2 files changed, 69 deletions(-) delete mode 100644 Documentation/admin-guide/basic-profiling.rst (limited to 'Documentation/admin-guide') diff --git a/Documentation/admin-guide/basic-profiling.rst b/Documentation/admin-guide/basic-profiling.rst deleted file mode 100644 index 72babc7..0000000 --- a/Documentation/admin-guide/basic-profiling.rst +++ /dev/null @@ -1,68 +0,0 @@ -Basic kernel profiling -====================== - - -These instructions are deliberately very basic. If you want something clever, -go read the real docs ;-) - -Please don't add more stuff, but feel free to -correct my mistakes ;-) (mbligh@aracnet.com) - -Thanks to John Levon, Dave Hansen, et al. for help writing this. - -```` is the thing you're trying to measure. -Make sure you have the correct ``System.map`` / ``vmlinux`` referenced! - -It is probably easiest to use ``make install`` for linux and hack -``/sbin/installkernel`` to copy ``vmlinux`` to ``/boot``, in addition to -``vmlinuz``, ``config``, ``System.map``, which are usually installed by default. - -Readprofile ------------ - -A recent ``readprofile`` command is needed for 2.6, such as found in util-linux -2.12a, which can be downloaded from: - - http://www.kernel.org/pub/linux/utils/util-linux/ - -Most distributions will ship it already. - -Add ``profile=2`` to the kernel command line. - -Some ``readprofile`` commands:: - - clear readprofile -r - - dump output readprofile -m /boot/System.map > captured_profile - -Oprofile --------- - -Get the source (see Changes for required version) from -http://oprofile.sourceforge.net/ and add ``idle=poll`` to the kernel command -line. - -Configure with ``CONFIG_PROFILING=y`` and ``CONFIG_OPROFILE=y`` & reboot on new kernel:: - - ./configure --with-kernel-support - make install - -For superior results, be sure to enable the local APIC. If opreport sees -a 0Hz CPU, APIC was not on. Be aware that idle=poll may mean a performance -penalty. - -One time setup:: - - opcontrol --setup --vmlinux=/boot/vmlinux - -Some ``opcontrol`` commands:: - - clear opcontrol --reset - start opcontrol --start - - stop opcontrol --stop - dump output opreport > output_file - -To only report on the kernel, run ``opreport -l /boot/vmlinux > output_file`` - -A reset is needed to clear old statistics, which survive a reboot. diff --git a/Documentation/admin-guide/index.rst b/Documentation/admin-guide/index.rst index d737ae7..2872c0c 100644 --- a/Documentation/admin-guide/index.rst +++ b/Documentation/admin-guide/index.rst @@ -58,4 +58,3 @@ configure specific aspects of kernel behavior to your liking. binfmt-misc mono java - basic-profiling -- cgit v1.1